All SWMM simulation options parsed from [OPTIONS] section. More...

#include <SimulationOptions.hpp>

Collaboration diagram for openswmm::SimulationOptions:

Public Member Functions
double	totalDurationMs () const
	Total simulation duration in milliseconds (legacy TotalDuration).

Public Attributes
double	start_date = 2453006.0
	Simulation start date/time (decimal days, OADate (days since 12/30/1899)).

double	end_date = 0.0
	Simulation end date/time (decimal days, OADate (days since 12/30/1899)).

double	total_duration_ms = -1.0
	Total simulation duration in milliseconds, or -1 if not set.

double	report_start = 0.0
	Report start date/time.

double	routing_step = 20.0
	Hydraulic routing timestep in seconds. Legacy default: 20.

double	min_routing_step = 0.5
	Minimum routing timestep in seconds (CFL floor).

double	dry_step = 3600.0
	Dry-weather runoff timestep in seconds.

double	wet_step = 300.0
	Wet-weather runoff timestep in seconds.

double	report_step = 900.0
	Reporting output interval in seconds.

double	dry_days = 0.0
	Antecedent dry days.

double	variable_step = 0.75
	Courant factor for variable time stepping (0 = fixed step).

double	lengthening_step = 0.0
	Conduit lengthening timestep (seconds, 0 = use routing_step).

int	sweep_start = 1
	Street sweeping start day-of-year (1-365). 0 = not set.

int	sweep_end = 365
	Street sweeping end day-of-year (1-365). 0 = not set.

FlowUnits	flow_units = FlowUnits::CFS
	Flow units system.

RoutingModel	routing_model = RoutingModel::DYNWAVE
	Routing method. Legacy default: DYNWAVE.

QualitySolverKind	quality_solver = QualitySolverKind::LEGACY
	Water-quality engine selection (`[OPTIONS] QUALITY_SOLVER`).

double	quality_step = 0.0
	`[OPTIONS] QUALITY_STEP` — transport substep, seconds (HH:MM:SS or seconds; 0 = follow ROUTING_STEP).

int	max_segments_per_link = 100
	`[OPTIONS] MAX_SEGMENTS_PER_LINK` — LARD slab capacity per link (strategy §4.1; default 100, the EPANET MAXSEGS shape).

bool	lard_rwpt = false
	`[OPTIONS] DISPERSION RWPT\|OFF` — LARD RWPT dispersion (X3b; strategy §5; the GUI plan's Lagrangian-group key).

int	rwpt_seed = 0
	`[OPTIONS] RWPT_SEED` — deterministic counter-RNG seed (D-L6). Same seed ⇒ bit-identical runs at any thread count.

bool	water_age = false
	`[OPTIONS] WATER_AGE ON\|OFF` — transported water-age tracking (water age plan §1, reserved species WATER_AGE).

bool	outfall_backflow_zero = false
	`[OPTIONS] OUTFALL_BACKFLOW_QUALITY LAST\|ZERO` — quality carried by reverse flow at outfalls (false = LAST, the default).

bool	heat_transport = false
	`[OPTIONS] HEAT_TRANSPORT ON\|OFF` — transported temperature (heat plan §1, reserved species TEMPERATURE).

double	humidity [12] = {50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50}
	Monthly relative humidity, % (`[TEMPERATURE] HUMIDITY`).

int	humidity_type = 0
	Humidity source: 0=CONSTANT, 1=MONTHLY, 2=TIMESERIES.

int	humidity_var = 0
	Humidity quantity: 0=RELATIVE (%), 1=DEWPOINT (deg F US / deg C SI).

std::string	humidity_ts_name
	Timeseries name for humidity (humidity_type == 2).

double	water_density = 1000.0
	Water density, kg/m³ (`[OPTIONS] WATER_DENSITY`; CSH Table 4.1).

double	water_specific_heat = 4184.0
	Water specific heat capacity, J/kg/°C (`WATER_SPECIFIC_HEAT_CAPACITY`).

double	wind_func_coeff_a = 1.505e-8
	Wind-function coefficients (`WIND_FUNC_COEFF_A` / `_B`), CSH Table 4.1 — `f(w) = a + b·w`, Dunne & Leopold (1978) defaults.

double	wind_func_coeff_b = 1.6e-8

double	pressure_ratio = 1.0
	Pa/P elevation correction in the Bowen ratio (`PRESSURE_RATIO`).

fv::FvOptions	fv
	Knobs for FLOW_ROUTING FV, grouped rather than spread across this struct (plan §4.2 — first-class [OPTIONS] keys, no new section).

InfiltrationModel	infiltration = InfiltrationModel::HORTON
	Infiltration method for subcatchments.

RunoffModel	runoff_model = RunoffModel::NL_POND
	Runoff routing method.

int	max_trials = 8
	Maximum number of flow routing iterations (dynamic wave).

int	surcharge_method = 0
	Surcharge method: 0=EXTRAN, 1=SLOT, 2=DYNAMIC_SLOT (DPS).

double	tpa_celerity = 100.0
	TPA acoustic celerity a for SURCHARGE_METHOD TPA (PROJECT length units per second, converted like FV_SLOT_CELERITY). Sets the constant slot width w = g·A_full/a² (issue #156).

double	dps_target_celerity = 25.0
	DPS target pressure celerity (m/s, converted to ft/s at init).

double	dps_alpha = 3.0
	DPS surcharge shock parameter (dimensionless, >= 2).

double	dps_decay_time = 0.5
	DPS decay time scale (seconds).

int	unsteady_friction = 0
	Unsteady friction model: 0=NONE (default, inert), 1=VITKOVSKY.

int	report_signed_heads = 0
	Report signed piezometric heads: 0 = NO (default, legacy bit-parity — NODE_HEAD is rebuilt as f32(floored depth) + f32(invert)), 1 = YES — the .out HEAD field carries the TRUE signed head (point-in-time), so sub-atmospheric TPA columns are observable (issue #156 O-6). DEPTH stays floored either way.

double	uf_k3 = 0.015
	Unsteady friction coefficient k3 (dimensionless).

NodeContinuity	node_continuity = NodeContinuity::EXPLICIT
	Node continuity formulation for depth update. Default: EXPLICIT (legacy).

int	virtual_junction_momentum = 0
	Virtual-junction momentum treatment. Always 0 (BASIC).

bool	anderson_accel = false
	Enable Anderson acceleration for Picard iteration convergence.

int	normal_flow_ltd = 2
	Normal flow limitation: 0=SLOPE, 1=FROUDE, 2=BOTH, 3=NEITHER.

int	force_main_eqn = 0
	Force main equation: 0=Hazen-Williams, 1=Darcy-Weisbach.

int	inertial_damping = 1
	Inertial damping: 0=NONE, 1=PARTIAL, 2=FULL.

int	link_offsets = 0
	Link offset mode: 0=DEPTH_OFFSET, 1=ELEV_OFFSET.

double	min_slope = 0.0
	Minimum conduit slope (ft/ft).

double	min_surf_area = 0.0
	Minimum node surface area (ft²).

double	head_tol = 0.005
	Convergence head tolerance in project length units.

double	sys_flow_tol = 0.05
	System flow tolerance (fraction, e.g., 0.05 = 5%).

double	lat_flow_tol = 0.05
	Lateral inflow tolerance (fraction, e.g., 0.05 = 5%).

bool	skip_steady_state = false
	Skip routing when system is in steady state.

bool	write_absolute_paths = false
	Slice IO-4 opt-out: emit external-file paths verbatim absolute.

bool	quality_routing = false
	True if quality routing is enabled.

bool	allow_ponding = false
	True if evaporation is included.

bool	ignore_rainfall = false
	Ignore rainfall (for hot start runs).

bool	ignore_snow_melt = false
	Ignore snowmelt.

bool	ignore_groundwater = false
	Ignore groundwater.

bool	ignore_rdii = false
	Ignore RDII.

bool	ignore_routing = false
	Ignore routing.

bool	ignore_quality = false
	Ignore water quality.

bool	ignore_2d = false
	Ignore the 2D surface-routing module.

double	rule_step = 0.0
	Control rule evaluation interval (seconds).

int	num_threads = 1
	Number of OpenMP threads for parallel solver loops.

std::string	crs
	Coordinate reference system string.

std::unordered_map< std::string, std::string >	ext_options
	Key-value map for unknown [OPTIONS] keys.

int	evap_type = 0
	Evaporation type: 0=CONSTANT, 1=MONTHLY, 2=TIMESERIES, 3=TEMPERATURE, 4=FILE.

double	evap_values [12] = {0,0,0,0,0,0,0,0,0,0,0,0}
	Monthly evaporation values (used when evap_type == 0 or 1).

std::string	evap_ts_name
	Timeseries name for evaporation (evap_type == 2).

std::string	evap_recovery_pat
	Recovery pattern name for evaporation.

bool	evap_dry_only = false
	If true, evaporation only occurs on dry days.

double	pan_coeff [12] = {1,1,1,1,1,1,1,1,1,1,1,1}
	Monthly pan coefficients (used when evap_type == 4/FILE).

int	temp_source = 0
	Temperature source: 0=NONE, 1=TIMESERIES, 2=FILE.

std::string	temp_ts_name
	Timeseries name for temperature data.

FilePathPair	temp_file
	File path for temperature data. Carries {absolute, original}.

double	temp_file_start = 0.0
	Temperature file start date (OADate).

int	temp_units = -1
	Climate-file temperature units: 0=tenths-degC (C10), 1=degC (C), 2=degF (F); -1 = unspecified (reader keeps its per-format default).

int	wind_type = 0
	Wind speed type: 0=MONTHLY, 1=FILE.

double	wind_speed [12] = {0,0,0,0,0,0,0,0,0,0,0,0}
	Monthly wind speed values (12 months).

double	snow_divt = 34.0
	Snowmelt: dividing temperature.

double	snow_ati_wt = 0.5
	Snowmelt: ATI weight (0–1).

double	snow_nrg_ratio = 0.6
	Snowmelt: negative melt ratio.

double	snow_lat = 0.0
	Snowmelt: latitude (degrees).

double	snow_dtlong = 0.0
	Snowmelt: longitude/solar-time correction (minutes).

double	snow_elev = 0.0
	Snowmelt: site elevation above sea level (ft, internal units).

double	snow_min_melt = 0.0
	Snowmelt: minimum melt coefficient.

double	snow_max_melt = 0.0
	Snowmelt: maximum melt coefficient.

double	adc_imperv [10] = {1,1,1,1,1,1,1,1,1,1}
	Areal depletion curve for impervious surfaces (10 fractions).

double	adc_perv [10] = {1,1,1,1,1,1,1,1,1,1}
	Areal depletion curve for pervious surfaces (10 fractions).

bool	rpt_disabled = false
	TRUE if all reporting is disabled.

int	rpt_subcatchments = 1
	Subcatchment reporting: 0=NONE, 1=ALL, 2=SOME. Default ALL.

int	rpt_nodes = 1
	Node reporting: 0=NONE, 1=ALL, 2=SOME. Default ALL.

int	rpt_links = 1
	Link reporting: 0=NONE, 1=ALL, 2=SOME. Default ALL.

bool	rpt_input = false
	Report input summary.

bool	rpt_continuity = true
	Report continuity errors (default true).

bool	rpt_flowstats = true
	Report flow statistics (default true).

bool	rpt_controls = false
	Report control actions (default false).

bool	rpt_averages = false
	Report time-averaged results (default false).

std::vector< std::string >	rpt_subcatch_names
	Named subcatchments to report (used when rpt_subcatchments == 2).

std::vector< std::string >	rpt_node_names
	Named nodes to report (used when rpt_nodes == 2).

std::vector< std::string >	rpt_link_names
	Named links to report (used when rpt_links == 2).

Detailed Description

All SWMM simulation options parsed from [OPTIONS] section.

This struct consolidates all options that were previously global variables in src/solver/globals.h (e.g., FlowUnits, RouteModel, RouteStep, etc.) into a single value type that lives inside SimulationContext.

The ext_options map stores any key in [OPTIONS] that is not recognized as a standard SWMM option. A SWMM_WARN_UNKNOWN_OPTION warning is issued. Extension options are available to plugins via the C API.

Member Function Documentation

◆ totalDurationMs()

double openswmm::SimulationOptions::totalDurationMs ( ) const

inline

Total simulation duration in milliseconds (legacy TotalDuration).

Returns the legacy-exact value stored by the INP options handler when available; otherwise falls back to flooring the combined serial difference to whole seconds (mirroring legacy swmm5.c:3198-3200 as closely as the combined representation allows).

Here is the caller graph for this function:

Member Data Documentation

◆ adc_imperv

double openswmm::SimulationOptions::adc_imperv[10] = {1,1,1,1,1,1,1,1,1,1}

Areal depletion curve for impervious surfaces (10 fractions).

◆ adc_perv

double openswmm::SimulationOptions::adc_perv[10] = {1,1,1,1,1,1,1,1,1,1}

Areal depletion curve for pervious surfaces (10 fractions).

◆ allow_ponding

bool openswmm::SimulationOptions::allow_ponding = false

True if evaporation is included.

◆ anderson_accel

bool openswmm::SimulationOptions::anderson_accel = false

Enable Anderson acceleration for Picard iteration convergence.

When true, uses depth-2 Anderson mixing to accelerate node depth convergence, typically reducing iteration count by 25-50%. Falls back to standard Picard for nodes that violate physical bounds.

ANDERSON_ACCEL YES ;; enable Anderson acceleration

ANDERSON_ACCEL NO ;; standard Picard iteration (default)

NO

@ NO

No option.

Definition enums.h:1222

YES

@ YES

Yes option.

Definition enums.h:1224

◆ crs

std::string openswmm::SimulationOptions::crs

Coordinate reference system string.

Set via the CRS key in [OPTIONS]:

[OPTIONS]

CRS EPSG:4326

or using a PROJ string:

[OPTIONS]

CRS "+proj=utm +zone=33 +datum=WGS84"

Empty string if not specified. Also stored in SpatialFrame::crs.

◆ dps_alpha

double openswmm::SimulationOptions::dps_alpha = 3.0

DPS surcharge shock parameter (dimensionless, >= 2).

Controls the celerity shock at the mixed-flow transition. Larger values → initial P closer to 1 → bigger shock. Recommended: alpha = 3.

See also: Sharior et al. (2023) Eq. 23

◆ dps_decay_time

double openswmm::SimulationOptions::dps_decay_time = 0.5

DPS decay time scale (seconds).

Time for Preissmann Number to decay from P_hat_0 to ~1. Shorter r → faster transition to target celerity but potential oscillations. Should be meaningful physical/numerical time scale.

See also: Sharior et al. (2023) Eq. 22

◆ dps_target_celerity

double openswmm::SimulationOptions::dps_target_celerity = 25.0

DPS target pressure celerity (m/s, converted to ft/s at init).

Controls the maximum modeled pressure wave speed. Lower values allow larger timesteps but reduce transient fidelity.

See also: Sharior et al. (2023) Eq. 7

◆ dry_days

double openswmm::SimulationOptions::dry_days = 0.0

Antecedent dry days.

◆ dry_step

double openswmm::SimulationOptions::dry_step = 3600.0

Dry-weather runoff timestep in seconds.

◆ end_date

double openswmm::SimulationOptions::end_date = 0.0

Simulation end date/time (decimal days, OADate (days since 12/30/1899)).

◆ evap_dry_only

bool openswmm::SimulationOptions::evap_dry_only = false

If true, evaporation only occurs on dry days.

◆ evap_recovery_pat

std::string openswmm::SimulationOptions::evap_recovery_pat

Recovery pattern name for evaporation.

◆ evap_ts_name

std::string openswmm::SimulationOptions::evap_ts_name

Timeseries name for evaporation (evap_type == 2).

◆ evap_type

int openswmm::SimulationOptions::evap_type = 0

Evaporation type: 0=CONSTANT, 1=MONTHLY, 2=TIMESERIES, 3=TEMPERATURE, 4=FILE.

◆ evap_values

double openswmm::SimulationOptions::evap_values[12] = {0,0,0,0,0,0,0,0,0,0,0,0}

Monthly evaporation values (used when evap_type == 0 or 1).

◆ ext_options

std::unordered_map<std::string, std::string> openswmm::SimulationOptions::ext_options

Key-value map for unknown [OPTIONS] keys.

Any key in [OPTIONS] that is not a recognized SWMM keyword is stored here as a string pair. A SWMM_WARN_UNKNOWN_OPTION warning is issued for each unknown key.

Plugins can retrieve values via swmm_options_get_ext(). Keys are stored uppercase-normalized.

Example:

[OPTIONS]
TURBULENCE_DAMP  0.85    ;; stored as ext_options["TURBULENCE_DAMP"] = "0.85"
PLUGIN_TIMEOUT   30      ;; stored as ext_options["PLUGIN_TIMEOUT"] = "30"

◆ flow_units

FlowUnits openswmm::SimulationOptions::flow_units = FlowUnits::CFS

Flow units system.

◆ force_main_eqn

int openswmm::SimulationOptions::force_main_eqn = 0

Force main equation: 0=Hazen-Williams, 1=Darcy-Weisbach.

See also: Legacy: ForceMainEqn

◆ fv

fv::FvOptions openswmm::SimulationOptions::fv

Knobs for FLOW_ROUTING FV, grouped rather than spread across this struct (plan §4.2 — first-class [OPTIONS] keys, no new section).

Length-dimensioned members are stored here in the PROJECT's display units exactly as parsed; Router::init converts them to internal feet, the same treatment HEAD_TOLERANCE gets. FV_* keys are accepted and inert under any other routing model, so switching FLOW_ROUTING never invalidates a file.

◆ head_tol

double openswmm::SimulationOptions::head_tol = 0.005

Convergence head tolerance in project length units.

Legacy default: 0.0 (sentinel → runtime default 0.005 ft).

◆ heat_transport

bool openswmm::SimulationOptions::heat_transport = false

[OPTIONS] HEAT_TRANSPORT ON|OFF — transported temperature (heat plan §1, reserved species TEMPERATURE).

H1 scope: TRANSPORT ONLY. Temperature is advected and mixed as a conservative tracer under the LEGACY CSTR engine and reported as a trailing species column; per-source inlet temperatures come from the heat component's [HEAT_SOURCES]. The surface/radiative/sediment flux modules of plan §2 — the terms that make temperature change rather than merely move — arrive with H2–H4.

◆ humidity

double openswmm::SimulationOptions::humidity[12] = {50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50}

Monthly relative humidity, % ([TEMPERATURE] HUMIDITY).

H2. ClimateState::humidity has existed with a 50 % default since before this program and nothing ever wrote to it — the GeoPackage climate format reads a humidity column that never reached the running state. Surface heat exchange is the first consumer, so the deck key arrives with it. Monthly like WINDSPEED; a single value fills all twelve months.

Holds RH (%) when humidity_var == 0, dew point (project temperature units) when humidity_var == 1. Used when humidity_type is CONSTANT (0) or MONTHLY (1).

◆ humidity_ts_name

std::string openswmm::SimulationOptions::humidity_ts_name

Timeseries name for humidity (humidity_type == 2).

◆ humidity_type

int openswmm::SimulationOptions::humidity_type = 0

Humidity source: 0=CONSTANT, 1=MONTHLY, 2=TIMESERIES.

◆ humidity_var

int openswmm::SimulationOptions::humidity_var = 0

Humidity quantity: 0=RELATIVE (%), 1=DEWPOINT (deg F US / deg C SI).

Dew point is converted to RH each step from the effective air temperature: RH = 100·e_s(Td)/e_s(Ta), clamped to [0, 100].

◆ ignore_2d

bool openswmm::SimulationOptions::ignore_2d = false

Ignore the 2D surface-routing module.

Parsed from IGNORE_2D in [OPTIONS] (OpenSWMM extension — not a legacy key, so the InpWriter emits it only when YES). When set, the 2D solver never activates even if the model carries a mesh: the GUI's "2D Surface Routing" module checkbox writes this so unchecking it genuinely runs the model 1D-only without stripping the mesh sections.

◆ ignore_groundwater

bool openswmm::SimulationOptions::ignore_groundwater = false

Ignore groundwater.

◆ ignore_quality

bool openswmm::SimulationOptions::ignore_quality = false

Ignore water quality.

◆ ignore_rainfall

bool openswmm::SimulationOptions::ignore_rainfall = false

Ignore rainfall (for hot start runs).

◆ ignore_rdii

bool openswmm::SimulationOptions::ignore_rdii = false

Ignore RDII.

◆ ignore_routing

bool openswmm::SimulationOptions::ignore_routing = false

Ignore routing.

◆ ignore_snow_melt

bool openswmm::SimulationOptions::ignore_snow_melt = false

Ignore snowmelt.

◆ inertial_damping

int openswmm::SimulationOptions::inertial_damping = 1

Inertial damping: 0=NONE, 1=PARTIAL, 2=FULL.

See also: Legacy: InertDamping

◆ infiltration

InfiltrationModel openswmm::SimulationOptions::infiltration = InfiltrationModel::HORTON

Infiltration method for subcatchments.

◆ lard_rwpt

bool openswmm::SimulationOptions::lard_rwpt = false

[OPTIONS] DISPERSION RWPT|OFF — LARD RWPT dispersion (X3b; strategy §5; the GUI plan's Lagrangian-group key).

Resolved vertical-shear dispersion on the segments (RwptDispersion.hpp). LARD-only; warns under other solvers (the ARD engine's dispersion is E3's transport.ard machinery, deliberately separate).

◆ lat_flow_tol

double openswmm::SimulationOptions::lat_flow_tol = 0.05

Lateral inflow tolerance (fraction, e.g., 0.05 = 5%).

Legacy default: 0.05. Input is in percent, divided by 100.

◆ lengthening_step

double openswmm::SimulationOptions::lengthening_step = 0.0

Conduit lengthening timestep (seconds, 0 = use routing_step).

Used to compute modified conduit lengths for CFL stability.

See also: Legacy: LengtheningStep

◆ link_offsets

int openswmm::SimulationOptions::link_offsets = 0

Link offset mode: 0=DEPTH_OFFSET, 1=ELEV_OFFSET.

See also: Legacy: LinkOffsets

◆ max_segments_per_link

int openswmm::SimulationOptions::max_segments_per_link = 100

[OPTIONS] MAX_SEGMENTS_PER_LINK — LARD slab capacity per link (strategy §4.1; default 100, the EPANET MAXSEGS shape).

Values below 2 are clamped to 2 at solver init. Consumed by the LARD engine only; warns at open under other solvers.

◆ max_trials

int openswmm::SimulationOptions::max_trials = 8

Maximum number of flow routing iterations (dynamic wave).

◆ min_routing_step

double openswmm::SimulationOptions::min_routing_step = 0.5

Minimum routing timestep in seconds (CFL floor).

◆ min_slope

double openswmm::SimulationOptions::min_slope = 0.0

Minimum conduit slope (ft/ft).

See also: Legacy: MinSlope

◆ min_surf_area

double openswmm::SimulationOptions::min_surf_area = 0.0

Minimum node surface area (ft²).

See also: Legacy: MinSurfArea

◆ node_continuity

NodeContinuity openswmm::SimulationOptions::node_continuity = NodeContinuity::EXPLICIT

Node continuity formulation for depth update. Default: EXPLICIT (legacy).

◆ normal_flow_ltd

int openswmm::SimulationOptions::normal_flow_ltd = 2

Normal flow limitation: 0=SLOPE, 1=FROUDE, 2=BOTH, 3=NEITHER.

See also: Legacy: NormalFlowLtd

◆ num_threads

int openswmm::SimulationOptions::num_threads = 1

Number of OpenMP threads for parallel solver loops.

Parsed from the THREADS keyword in [OPTIONS]. Resolution (core/ThreadInfo.hpp, THREAD_LIMITS_AND_OVERSUBSCRIPTION_PLAN):

0 → auto: omp_get_max_threads() — the logical processors the OpenMP runtime allows (lowered by OMP_NUM_THREADS / OMP_THREAD_LIMIT / CPU affinity) — then the model-size gates and, on Apple Silicon, the dynamic-wave performance-core clamp.
1 → single-threaded (default, no OpenMP overhead).
N → exactly N threads. Values above the logical processors or the runtime limit are honoured (oversubscription) with a warning; the active spin-wait policy is disabled for an oversubscribed run.

Model-size gates still apply to explicit values (warned): dynamic wave keeps >= 100 conduits per thread; the 2D marcher needs >= 4 triangles per thread. The 2D Kokkos OpenMP backend receives the raw value via the plugin ABI (v4) and initialises once per process.

Environment overrides (each warned when active): SWMM_DW_THREADS forces the dynamic-wave count; OPENSWMM_2D_THREADS forces the Kokkos backend.

See also: Legacy reference: globals.h NumThreads, project.c

◆ outfall_backflow_zero

bool openswmm::SimulationOptions::outfall_backflow_zero = false

[OPTIONS] OUTFALL_BACKFLOW_QUALITY LAST|ZERO — quality carried by reverse flow at outfalls (false = LAST, the default).

LAST is the legacy convention (src/legacy/engine/qualrout.c findNodeQual): an outfall that takes no inflow keeps its last mixed concentration while wet, and backflow re-injects that held value — under WATER_AGE the held boundary water also keeps aging 1:1, so a permanently supplying outfall becomes an unbounded age source. ZERO makes a supplying outfall a fresh boundary: whenever it takes no volume inflow its held state reads zero for every pollutant AND WATER_AGE, so re-entering water carries no mass and no age (the EPANET-reservoir picture). ZERO deliberately does NOT return the mass that left through the outfall — the receiving water is an infinite fresh reservoir; tidal-flushing studies where returned mass matters keep LAST.

◆ pan_coeff

double openswmm::SimulationOptions::pan_coeff[12] = {1,1,1,1,1,1,1,1,1,1,1,1}

Monthly pan coefficients (used when evap_type == 4/FILE).

◆ pressure_ratio

double openswmm::SimulationOptions::pressure_ratio = 1.0

Pa/P elevation correction in the Bowen ratio (PRESSURE_RATIO).

◆ quality_routing

bool openswmm::SimulationOptions::quality_routing = false

True if quality routing is enabled.

◆ quality_solver

QualitySolverKind openswmm::SimulationOptions::quality_solver = QualitySolverKind::LEGACY

Water-quality engine selection ([OPTIONS] QUALITY_SOLVER).

LEGACY = the legacy-parity CSTR QualitySolver (default, bit-identical behavior). EULERIAN_ARD = the solver-agnostic Eulerian ARD engine on the FV cell mesh (plans/transport/EULERIAN_ARD_TRANSPORT_PLAN.md rev. 2; master plan D-UT6). LAGRANGIAN = the LARD segment engine — X1 wiring only: the dispatch exists, transport does not, so quality state reads zero and the open() warning says so (plans/transport/LARD_AGE_EXPEDITE_SUBPLAN_2026-08-23.md).

◆ quality_step

double openswmm::SimulationOptions::quality_step = 0.0

[OPTIONS] QUALITY_STEP — transport substep, seconds (HH:MM:SS or seconds; 0 = follow ROUTING_STEP).

X3a: consumed by the LARD engine only, which splits each routing step into ceil(dt_routing / quality_step) equal substeps (strategy §4.2). Setting it under LEGACY or EULERIAN_ARD warns at open — those engines do not substep on this key.

◆ report_signed_heads

int openswmm::SimulationOptions::report_signed_heads = 0

Report signed piezometric heads: 0 = NO (default, legacy bit-parity — NODE_HEAD is rebuilt as f32(floored depth) + f32(invert)), 1 = YES — the .out HEAD field carries the TRUE signed head (point-in-time), so sub-atmospheric TPA columns are observable (issue #156 O-6). DEPTH stays floored either way.

◆ report_start

double openswmm::SimulationOptions::report_start = 0.0

Report start date/time.

◆ report_step

double openswmm::SimulationOptions::report_step = 900.0

Reporting output interval in seconds.

◆ routing_model

RoutingModel openswmm::SimulationOptions::routing_model = RoutingModel::DYNWAVE

Routing method. Legacy default: DYNWAVE.

◆ routing_step

double openswmm::SimulationOptions::routing_step = 20.0

Hydraulic routing timestep in seconds. Legacy default: 20.

◆ rpt_averages

bool openswmm::SimulationOptions::rpt_averages = false

Report time-averaged results (default false).

◆ rpt_continuity

bool openswmm::SimulationOptions::rpt_continuity = true

Report continuity errors (default true).

◆ rpt_controls

bool openswmm::SimulationOptions::rpt_controls = false

Report control actions (default false).

◆ rpt_disabled

bool openswmm::SimulationOptions::rpt_disabled = false

TRUE if all reporting is disabled.

◆ rpt_flowstats

bool openswmm::SimulationOptions::rpt_flowstats = true

Report flow statistics (default true).

◆ rpt_input

bool openswmm::SimulationOptions::rpt_input = false

Report input summary.

◆ rpt_link_names

std::vector<std::string> openswmm::SimulationOptions::rpt_link_names

Named links to report (used when rpt_links == 2).

◆ rpt_links

int openswmm::SimulationOptions::rpt_links = 1

Link reporting: 0=NONE, 1=ALL, 2=SOME. Default ALL.

◆ rpt_node_names

std::vector<std::string> openswmm::SimulationOptions::rpt_node_names

Named nodes to report (used when rpt_nodes == 2).

◆ rpt_nodes

int openswmm::SimulationOptions::rpt_nodes = 1

Node reporting: 0=NONE, 1=ALL, 2=SOME. Default ALL.

◆ rpt_subcatch_names

std::vector<std::string> openswmm::SimulationOptions::rpt_subcatch_names

Named subcatchments to report (used when rpt_subcatchments == 2).

◆ rpt_subcatchments

int openswmm::SimulationOptions::rpt_subcatchments = 1

Subcatchment reporting: 0=NONE, 1=ALL, 2=SOME. Default ALL.

◆ rule_step

double openswmm::SimulationOptions::rule_step = 0.0

Control rule evaluation interval (seconds).

Parsed from RULE_STEP in [OPTIONS]. 0.0 means evaluate control rules every routing step (legacy default behaviour).

See also: Legacy: globals.h RuleStep

◆ runoff_model

RunoffModel openswmm::SimulationOptions::runoff_model = RunoffModel::NL_POND

Runoff routing method.

◆ rwpt_seed

int openswmm::SimulationOptions::rwpt_seed = 0

[OPTIONS] RWPT_SEED — deterministic counter-RNG seed (D-L6). Same seed ⇒ bit-identical runs at any thread count.

◆ skip_steady_state

bool openswmm::SimulationOptions::skip_steady_state = false

Skip routing when system is in steady state.

When true, routing is skipped if no control actions were taken, flow error is below sys_flow_tol, and no inflows changed.

See also: Legacy: SkipSteadyState

◆ snow_ati_wt

double openswmm::SimulationOptions::snow_ati_wt = 0.5

Snowmelt: ATI weight (0–1).

◆ snow_divt

double openswmm::SimulationOptions::snow_divt = 34.0

Snowmelt: dividing temperature.

◆ snow_dtlong

double openswmm::SimulationOptions::snow_dtlong = 0.0

Snowmelt: longitude/solar-time correction (minutes).

Legacy [TEMPERATURE] SNOWMELT longitude field. Stored verbatim in minutes; converted to hours (÷60) into ClimateState::dtlong at init, matching legacy climate.c (Temp.dtlong = x[5]/60.0). 0 = use true solar time.

◆ snow_elev

double openswmm::SimulationOptions::snow_elev = 0.0

Snowmelt: site elevation above sea level (ft, internal units).

Used to compute atmospheric pressure for psychrometric constant. Legacy field: Temp.elev (from [TEMPERATURE] SNOWMELT section). Default 0.0 = sea level → pa = 29.9 in-Hg → gamma ≈ 0.01073.

◆ snow_lat

double openswmm::SimulationOptions::snow_lat = 0.0

Snowmelt: latitude (degrees).

◆ snow_max_melt

double openswmm::SimulationOptions::snow_max_melt = 0.0

Snowmelt: maximum melt coefficient.

◆ snow_min_melt

double openswmm::SimulationOptions::snow_min_melt = 0.0

Snowmelt: minimum melt coefficient.

◆ snow_nrg_ratio

double openswmm::SimulationOptions::snow_nrg_ratio = 0.6

Snowmelt: negative melt ratio.

◆ start_date

double openswmm::SimulationOptions::start_date = 2453006.0

Simulation start date/time (decimal days, OADate (days since 12/30/1899)).

Legacy default: Jan 1, 2004 = datetime_encodeDate(2004,1,1).

◆ surcharge_method

int openswmm::SimulationOptions::surcharge_method = 0

Surcharge method: 0=EXTRAN, 1=SLOT, 2=DYNAMIC_SLOT (DPS).

See also: Legacy: SurchargeMethod; Sharior et al. (2023) for DYNAMIC_SLOT

◆ sweep_end

int openswmm::SimulationOptions::sweep_end = 365

Street sweeping end day-of-year (1-365). 0 = not set.

◆ sweep_start

int openswmm::SimulationOptions::sweep_start = 1

Street sweeping start day-of-year (1-365). 0 = not set.

◆ sys_flow_tol

double openswmm::SimulationOptions::sys_flow_tol = 0.05

System flow tolerance (fraction, e.g., 0.05 = 5%).

Legacy default: 0.05. Input is in percent, divided by 100.

◆ temp_file

FilePathPair openswmm::SimulationOptions::temp_file

File path for temperature data. Carries {absolute, original}.

◆ temp_file_start

double openswmm::SimulationOptions::temp_file_start = 0.0

Temperature file start date (OADate).

◆ temp_source

int openswmm::SimulationOptions::temp_source = 0

Temperature source: 0=NONE, 1=TIMESERIES, 2=FILE.

◆ temp_ts_name

std::string openswmm::SimulationOptions::temp_ts_name

Timeseries name for temperature data.

◆ temp_units

int openswmm::SimulationOptions::temp_units = -1

Climate-file temperature units: 0=tenths-degC (C10), 1=degC (C), 2=degF (F); -1 = unspecified (reader keeps its per-format default).

Maps the legacy [TEMPERATURE] FILE units keyword (TempUnitsWords {"C10","C","F"} in climate.c) and ClimateFile TempUnits enum.

◆ total_duration_ms

double openswmm::SimulationOptions::total_duration_ms = -1.0

Total simulation duration in milliseconds, or -1 if not set.

PARITY legacy swmm5.c:3198-3200 / project.c:173: legacy forms TotalDuration from the SEPARATE date and time parts — floor((EndDate-StartDate)*86400 + (EndTime-StartTime)*86400) * 1000 — which yields EXACT whole-second ms (e.g. 172680000.0), whereas (end_date - start_date)*86400000 from the combined serials rounds (e.g. 172679999.99999997). The INP options handler stores the legacy-exact value here; writers that only set the combined serials must reset it to -1 so total_duration_ms() falls back.

◆ tpa_celerity

double openswmm::SimulationOptions::tpa_celerity = 100.0

TPA acoustic celerity a for SURCHARGE_METHOD TPA (PROJECT length units per second, converted like FV_SLOT_CELERITY). Sets the constant slot width w = g·A_full/a² (issue #156).

See also: Vasconcelos, Wright & Roe (2006)

◆ uf_k3

double openswmm::SimulationOptions::uf_k3 = 0.015

Unsteady friction coefficient k3 (dimensionless).

Brunone-type coefficient; used only when unsteady_friction != 0. Paper-calibrated range 0.005–0.020 (tested to 0.045).

See also: Pinto et al. (2025) Table 1 (issue #156)

◆ unsteady_friction

int openswmm::SimulationOptions::unsteady_friction = 0

Unsteady friction model: 0=NONE (default, inert), 1=VITKOVSKY.

Adds the Pinto/Vasconcelos/Soares (2025) unsteady-friction source term S_fu = (k3/g)(dV/dt + c·sgn(V)|dV/dx|) with regime-dependent celerity c to the momentum equation. CONSUMED BY THE FV SOLVER as of issue #156 Phase 2 (copied into FvOptions by Router::initFv; applied by kernels::ufUpdate after the steady-friction stage, with the convective term precomputed per substep). Under DYNWAVE the key is still parsed, round-tripped and echoed but inert — the dynamic wave source term is Phase 3.

See also: Pinto, Vasconcelos & Soares (2025), J. Hydraul. Eng. 152(1); Vitkovsky et al. (2000). Plan: plans/MIXED_FLOW_CLOSURES_TPA_UF_PLAN_2026-08-29.md §3

◆ variable_step

double openswmm::SimulationOptions::variable_step = 0.75

Courant factor for variable time stepping (0 = fixed step).

Legacy default: 0.75 (enabled).

◆ virtual_junction_momentum

int openswmm::SimulationOptions::virtual_junction_momentum = 0

Virtual-junction momentum treatment. Always 0 (BASIC).

BASIC applies zero storage, the shared junction sigma and cross-junction upwinding of area/hydraulic radius; it transmits no cross-junction convective momentum. FULL, which added the dq4_j correction, is RETIRED (2026-08-14): the term was sign-inverted relative to the per-link convective term and applied to both adjacent links, destroying 224-325 % of the routed volume on SWASHES macdonald-periodic. The keyword is still parsed, warns, and is treated as BASIC; the field is kept only so existing writers/readers keep their layout.

VIRTUAL_JUNCTION_MOMENTUM BASIC ;; default; FULL warns and maps here

openswmm::ReactionCoupling::FULL

@ FULL

Definition ReactionData.hpp:51

◆ water_age

bool openswmm::SimulationOptions::water_age = false

[OPTIONS] WATER_AGE ON|OFF — transported water-age tracking (water age plan §1, reserved species WATER_AGE).

A1a scope: the age species rides the EULERIAN_ARD mesh (unit zero-order aging + volume-weighted mixing); per-source initial ages come from the waterage component's [WATER_AGE_SOURCES]. LEGACY-engine age arrives with A1b and warns until then.

◆ water_density

double openswmm::SimulationOptions::water_density = 1000.0

Water density, kg/m³ ([OPTIONS] WATER_DENSITY; CSH Table 4.1).

H2. Load-bearing from this phase on: it sets the weight of a surface flux against advected heat. H1 deliberately shipped without it because with no fluxes it cancelled identically and no gate could observe its value.

◆ water_specific_heat

double openswmm::SimulationOptions::water_specific_heat = 4184.0

Water specific heat capacity, J/kg/°C (WATER_SPECIFIC_HEAT_CAPACITY).

◆ wet_step

double openswmm::SimulationOptions::wet_step = 300.0

Wet-weather runoff timestep in seconds.

◆ wind_func_coeff_a

double openswmm::SimulationOptions::wind_func_coeff_a = 1.505e-8

Wind-function coefficients (WIND_FUNC_COEFF_A / _B), CSH Table 4.1 — f(w) = a + b·w, Dunne & Leopold (1978) defaults.

◆ wind_func_coeff_b

double openswmm::SimulationOptions::wind_func_coeff_b = 1.6e-8

◆ wind_speed

double openswmm::SimulationOptions::wind_speed[12] = {0,0,0,0,0,0,0,0,0,0,0,0}

Monthly wind speed values (12 months).

◆ wind_type

int openswmm::SimulationOptions::wind_type = 0

Wind speed type: 0=MONTHLY, 1=FILE.

◆ write_absolute_paths

bool openswmm::SimulationOptions::write_absolute_paths = false

Slice IO-4 opt-out: emit external-file paths verbatim absolute.

Default (false) makes InpWriter rebase every external-file reference relative to the destination .inp directory for portability. Set true to disable rebasing — paths are emitted in their resolved absolute form. Used by power users locked to legacy tools that don't accept relative paths in .inp. See IO_PORTABILITY_PLAN.md §1A & §5.4.

See also: Legacy: no equivalent — relative paths always work in EPA SWMM.

The documentation for this struct was generated from the following file:

/home/runner/work/openswmm.engine/openswmm.engine/src/engine/core/SimulationOptions.hpp

Public Member Functions

Public Attributes