Skip to content

Constants

Centralized constants and magic numbers used throughout HMS Commander.

This module provides unit conversions, HMS method enumerations, time intervals, and other constants.

Available Constants

HMS-specific constants and method definitions.

This module is the single source of truth for all magic numbers, enumerations, and configuration constants used throughout hms-commander. It eliminates scattered magic numbers and provides clear, documented values.

Categories
  • Unit conversion factors (INCHES_TO_MM, CFS_TO_CMS, etc.)
  • Time constants (MINUTES_PER_HOUR, TIME_INTERVALS)
  • HMS method enumerations (LOSS_METHODS, TRANSFORM_METHODS, etc.)
  • Version support thresholds (MIN_HMS_3X_VERSION, etc.)
  • File formats (HMS_DATE_FORMAT, FILE_EXTENSIONS)
  • Acceptance criteria defaults (DEFAULT_PEAK_THRESHOLD_PCT, etc.)
Usage

from hms_commander._constants import ( INCHES_TO_MM, LOSS_METHODS, TIME_INTERVALS )

Convert units

precip_mm = precip_inches * INCHES_TO_MM

Validate method

if method in LOSS_METHODS: pass # Valid loss method

INCHES_TO_MM = 25.4 module-attribute

Convert inches to millimeters: mm = inches * 25.4

MM_TO_INCHES = 1.0 / 25.4 module-attribute

Convert millimeters to inches: inches = mm / 25.4

FEET_TO_METERS = 0.3048 module-attribute

Convert feet to meters: m = ft * 0.3048

METERS_TO_FEET = 1.0 / 0.3048 module-attribute

Convert meters to feet: ft = m / 0.3048

SQMI_TO_SQKM = 2.58999 module-attribute

Convert square miles to square kilometers

SQKM_TO_SQMI = 1.0 / 2.58999 module-attribute

Convert square kilometers to square miles

ACRE_TO_SQKM = 0.00404686 module-attribute

Convert acres to square kilometers

SQKM_TO_ACRE = 1.0 / 0.00404686 module-attribute

Convert square kilometers to acres

CFS_TO_CMS = 0.028316847 module-attribute

Convert cubic feet per second to cubic meters per second

CMS_TO_CFS = 1.0 / 0.028316847 module-attribute

Convert cubic meters per second to cubic feet per second

ACFT_TO_M3 = 1233.48 module-attribute

Convert acre-feet to cubic meters

M3_TO_ACFT = 1.0 / 1233.48 module-attribute

Convert cubic meters to acre-feet

CFS_HOURS_TO_ACFT = 0.0413 module-attribute

Convert CFS*hours to acre-feet: V(acft) = Q(cfs) * t(hr) * 0.0413

MINUTES_PER_HOUR = 60 module-attribute

Minutes in one hour

MINUTES_PER_DAY = 1440 module-attribute

Minutes in one day (60 * 24)

SECONDS_PER_HOUR = 3600 module-attribute

Seconds in one hour (60 * 60)

HOURS_PER_DAY = 24 module-attribute

Hours in one day

DEFAULT_EXECUTION_TIMEOUT = 3600 module-attribute

Default HMS execution timeout in seconds (1 hour)

TIME_INTERVALS = {'1 Minute': 1, '2 Minutes': 2, '3 Minutes': 3, '4 Minutes': 4, '5 Minutes': 5, '6 Minutes': 6, '10 Minutes': 10, '12 Minutes': 12, '15 Minutes': 15, '20 Minutes': 20, '30 Minutes': 30, '1 Hour': 60, '2 Hours': 120, '3 Hours': 180, '4 Hours': 240, '6 Hours': 360, '8 Hours': 480, '12 Hours': 720, '1 Day': 1440} module-attribute

HMS time interval strings mapped to minutes. Used for control file parsing.

MIN_HMS_3X_VERSION = (3, 3) module-attribute

Minimum HMS 3.x version with Jython scripting support

MIN_HMS_4X_VERSION = (4, 4, 1) module-attribute

Minimum HMS 4.x version with reliable Jython scripting

UNSUPPORTED_HMS_VERSIONS = [(4, 0), (4, 1), (4, 2), (4, 3)] module-attribute

HMS versions with legacy classpath issues (not supported)

DEFAULT_MAX_MEMORY = '4G' module-attribute

Default maximum JVM heap size for 64-bit HMS

DEFAULT_INITIAL_MEMORY = '128M' module-attribute

Default initial JVM heap size

MAX_MEMORY_32BIT = '1280M' module-attribute

Maximum JVM heap size for 32-bit HMS (physical limit ~1.5GB)

MAX_MEMORY_32BIT_MB = 1280 module-attribute

Maximum 32-bit memory in megabytes for numeric comparisons

INITIAL_MEMORY_32BIT = '64M' module-attribute

Initial JVM heap size for 32-bit HMS

IA_RATIO = 0.2 module-attribute

Initial abstraction ratio (Ia = 0.2 * S for standard method)

CN_FORMULA_BASE = 10 module-attribute

Base value in CN formula: S = (1000/CN) - 10

CN_FORMULA_NUMERATOR = 1000 module-attribute

Numerator in CN formula: S = (1000/CN) - 10

CN_MIN = 0 module-attribute

Minimum valid curve number

CN_MAX = 100 module-attribute

Maximum valid curve number

DEFAULT_PEAK_POSITION_PCT = 67.0 module-attribute

Default peak position (% of duration before peak). HCFCD standard is 67%.

DEFAULT_STORM_DURATION_MIN = 1440 module-attribute

Default storm duration in minutes (24 hours)

DEFAULT_STORM_INTERVAL_MIN = 5 module-attribute

Default time interval in minutes for frequency storms

ATLAS14_DEFAULT_INTERVAL_MIN = 30 module-attribute

Default time interval for Atlas 14 hyetographs (30 minutes)

ATLAS14_DEFAULT_DURATION_HR = 24 module-attribute

Default storm duration for Atlas 14 (24 hours)

ATLAS14_QUARTILES = ['First Quartile', 'Second Quartile', 'Third Quartile', 'Fourth Quartile', 'All Cases'] module-attribute

Available Atlas 14 temporal distribution quartiles

DEFAULT_PEAK_THRESHOLD_PCT = 1.0 module-attribute

Default peak flow comparison threshold (percent difference)

DEFAULT_VOLUME_THRESHOLD_PCT = 0.5 module-attribute

Default volume comparison threshold (percent difference)

DEFAULT_TIMING_THRESHOLD_HOURS = 1 module-attribute

Default time-to-peak comparison threshold (hours)

DEPTH_TOLERANCE_INCHES = 0.001 module-attribute

Tolerance for precipitation depth comparisons (inches)

LOG_MAX_BYTES = 10 * 1024 * 1024 module-attribute

Maximum log file size in bytes before rotation

LOG_MAX_MB = 10 module-attribute

Maximum log file size in megabytes

LOG_BACKUP_COUNT = 5 module-attribute

Number of backup log files to retain

LOSS_METHODS = ['Deficit and Constant', 'Green and Ampt', 'Gridded Deficit Constant', 'Gridded Green Ampt', 'Gridded SCS Curve Number', 'Gridded Soil Moisture Accounting', 'Initial and Constant', 'SCS Curve Number', 'Smith Parlange', 'Soil Moisture Accounting', 'None'] module-attribute

Valid loss/infiltration methods for subbasins in HEC-HMS

TRANSFORM_METHODS = ['Clark Unit Hydrograph', 'Kinematic Wave', 'ModClark', 'SCS Unit Hydrograph', 'Snyder Unit Hydrograph', 'User-Specified S-Graph', 'User-Specified Unit Hydrograph', 'None'] module-attribute

Valid transform/unit hydrograph methods for subbasins

BASEFLOW_METHODS = ['Bounded Recession', 'Constant Monthly', 'Linear Reservoir', 'Nonlinear Boussinesq', 'Recession', 'None'] module-attribute

Valid baseflow methods for subbasins

ROUTING_METHODS = ['Kinematic Wave', 'Lag', 'Modified Puls', 'Muskingum', 'Muskingum-Cunge', 'Straddle Stagger', 'None'] module-attribute

Valid channel routing methods for reaches

PRECIP_METHODS = ['Frequency Storm', 'Gage Weights', 'Gridded Precipitation', 'Inverse Distance', 'SCS Storm', 'Specified Hyetograph', 'Standard Project Storm', 'None'] module-attribute

Valid precipitation methods for meteorologic models

ET_METHODS = ['Gridded Priestley Taylor', 'Hamon', 'Monthly Average', 'Priestley Taylor', 'Specified Evapotranspiration', 'None'] module-attribute

Valid evapotranspiration methods for meteorologic models

SNOWMELT_METHODS = ['Gridded Temperature Index', 'Temperature Index', 'None'] module-attribute

Valid snowmelt methods for meteorologic models

GAGE_DATA_TYPES = ['Precipitation', 'Discharge', 'Stage', 'Temperature', 'Solar Radiation', 'Wind Speed', 'Relative Humidity', 'Crop Coefficient'] module-attribute

Valid gage data types for .gage files

PRECIP_UNITS = ['IN', 'MM'] module-attribute

Valid precipitation units (inches or millimeters)

DISCHARGE_UNITS = ['CFS', 'CMS'] module-attribute

Valid discharge units (cubic feet or meters per second)

STAGE_UNITS = ['FT', 'M'] module-attribute

Valid stage units (feet or meters)

TEMP_UNITS = ['DEG F', 'DEG C'] module-attribute

Valid temperature units (Fahrenheit or Celsius)

FILE_EXTENSIONS = {'hms': '*.hms', 'basin': '*.basin', 'met': '*.met', 'control': '*.control', 'gage': '*.gage', 'run': '*.run', 'dss': '*.dss', 'log': '*.log', 'geo': '*.geo', 'map': '*.map', 'grid': '*.grid', 'sqlite': '*.sqlite'} module-attribute

HMS file extension patterns by component type

DSS_EXTENSION = '.dss' module-attribute

DSS file extension

HMS_DATE_FORMAT = '%d %B %Y' module-attribute

HMS date format string, e.g., '1 January 2020' (full month name with spaces)

HMS_TIME_FORMAT = '%H:%M' module-attribute

HMS time format string, e.g., '00:00' or '14:30'

PRIMARY_ENCODING = 'utf-8' module-attribute

Primary file encoding for HMS files

FALLBACK_ENCODING = 'latin-1' module-attribute

Fallback encoding for older HMS files with extended characters

SUPPORTED_ENCODINGS = ['utf-8', 'latin-1', 'cp1252'] module-attribute

Ordered list of encodings to try when reading HMS files

LOSS_PARAM_MAP = {'LossRate': 'loss_method', 'Percent Impervious Area': 'percent_impervious', 'Initial Loss': 'initial_loss', 'Moisture Deficit': 'moisture_deficit', 'Wetting Front Suction': 'wetting_front_suction', 'Hydraulic Conductivity': 'hydraulic_conductivity', 'Initial Variable': 'initial_variable', 'Initial Deficit': 'initial_deficit', 'Maximum Deficit': 'maximum_deficit', 'Constant Rate': 'constant_rate', 'Percolation Rate': 'percolation_rate', 'Curve Number': 'curve_number', 'Initial Abstraction': 'initial_abstraction', 'Initial Rate': 'initial_rate', 'Saturated Conductivity': 'saturated_conductivity', 'Wetting Front Capillary': 'wetting_front_capillary', 'Soil': 'soil', 'Groundwater 1': 'groundwater_1', 'Groundwater 2': 'groundwater_2', 'Max Infiltration': 'max_infiltration'} module-attribute

Maps HMS loss parameter file keys to snake_case column names.

LOSS_PARAM_REVERSE_MAP = {v: k for k, v in (LOSS_PARAM_MAP.items())} module-attribute

Reverse map: snake_case column names to HMS file keys.

TRANSFORM_PARAM_MAP = {'Transform': 'transform_method', 'Time of Concentration': 'time_of_concentration', 'Storage Coefficient': 'storage_coefficient', 'Clark Method': 'clark_method', 'Lag': 'lag', 'Graph Type': 'graph_type', 'Snyder Tp': 'snyder_tp', 'Snyder Cp': 'snyder_cp', 'Number of Subreaches': 'number_of_subreaches'} module-attribute

Maps HMS transform parameter file keys to snake_case column names.

TRANSFORM_PARAM_REVERSE_MAP = {v: k for k, v in (TRANSFORM_PARAM_MAP.items())} module-attribute

Reverse map: snake_case column names to HMS file keys.

BASEFLOW_PARAM_MAP = {'Baseflow': 'baseflow_method', 'Recession Factor': 'recession_factor', 'Initial Discharge': 'initial_discharge', 'Threshold Type': 'threshold_type', 'Threshold Flow': 'threshold_flow', 'Threshold Ratio': 'threshold_ratio', 'GW 1 Initial': 'gw1_initial', 'GW 1 Coefficient': 'gw1_coefficient', 'GW 1 Reservoirs': 'gw1_reservoirs', 'GW 2 Initial': 'gw2_initial', 'GW 2 Coefficient': 'gw2_coefficient', 'GW 2 Reservoirs': 'gw2_reservoirs', 'Max Baseflow': 'max_baseflow', 'January Baseflow': 'january_baseflow', 'February Baseflow': 'february_baseflow', 'March Baseflow': 'march_baseflow', 'April Baseflow': 'april_baseflow', 'May Baseflow': 'may_baseflow', 'June Baseflow': 'june_baseflow', 'July Baseflow': 'july_baseflow', 'August Baseflow': 'august_baseflow', 'September Baseflow': 'september_baseflow', 'October Baseflow': 'october_baseflow', 'November Baseflow': 'november_baseflow', 'December Baseflow': 'december_baseflow'} module-attribute

Maps HMS baseflow parameter file keys to snake_case column names.

BASEFLOW_PARAM_REVERSE_MAP = {v: k for k, v in (BASEFLOW_PARAM_MAP.items())} module-attribute

Reverse map: snake_case column names to HMS file keys.

ROUTING_PARAM_MAP = {'Route': 'route_method', 'Muskingum K': 'muskingum_k', 'Muskingum x': 'muskingum_x', 'Muskingum Steps': 'muskingum_steps', 'Lag': 'lag', 'Number of Reaches': 'number_of_reaches', 'Initial Outflow Equals Inflow': 'initial_outflow_equals_inflow', 'Storage Outflow Table Name': 'storage_outflow_table_name', 'Channel': 'channel', 'Length': 'length', 'Energy Slope': 'energy_slope', 'Mannings n': 'mannings_n', 'Left Mannings n': 'left_mannings_n', 'Right Mannings n': 'right_mannings_n', 'Cross Section Name': 'cross_section_name', 'Initial Variable': 'initial_variable', 'Space-Time Method': 'space_time_method', 'Index Parameter Type': 'index_parameter_type', 'Index Celerity': 'index_celerity', 'Index Flow': 'index_flow', 'Maximum Depth Iterations': 'maximum_depth_iterations', 'Maximum Route Step Iterations': 'maximum_route_step_iterations', 'Channel Loss': 'channel_loss'} module-attribute

Maps HMS routing parameter file keys to snake_case column names.

ROUTING_PARAM_REVERSE_MAP = {v: k for k, v in (ROUTING_PARAM_MAP.items())} module-attribute

Reverse map: snake_case column names to HMS file keys.

HMS_RESULT_PATTERNS = {'flow': '/FLOW[^/]*/|/FLOW/', 'flow-total': '/FLOW/', 'flow-observed': '/FLOW-OBSERVED/', 'flow-direct': '/FLOW-DIRECT/', 'flow-base': '/FLOW-BASE/', 'flow-combine': '/FLOW-COMBINE/', 'precipitation': '/PRECIP[^/]*/|/PRECIP/', 'precip-inc': '/PRECIP-INC/', 'precip-cum': '/PRECIP-CUM/', 'precip-excess': '/PRECIP-EXCESS/', 'precip-loss': '/PRECIP-LOSS/', 'stage': '/STAGE/', 'storage': '/STORAGE[^/]*/|/STORAGE/', 'storage-gw': '/STORAGE-GW/', 'storage-soil': '/STORAGE-SOIL/', 'elevation': '/ELEV/', 'outflow': '/OUTFLOW[^/]*/|/OUTFLOW/', 'inflow': '/INFLOW[^/]*/|/INFLOW/', 'excess': '/EXCESS[^/]*/|/EXCESS/', 'baseflow': '/BASEFLOW/', 'infiltration': '/INFILTRATION/', 'et': '/ET[^/]*/|/ET/'} module-attribute

Regex patterns for matching HMS result types in DSS C-part

CLB Engineering Corporation  ·  LLM Forward Engineering
HMS Commander is a free and open-source project maintained by CLB Engineering Corporation. For agencies and firms seeking to modernize H&H workflows with LLM Forward approaches, contact CLB to partner with the engineers who wrote the automation.