Functions
double	speciesUnitFactor (const std::string &units, const SimulationOptions &opts)
	Map a species unit prefix to its concentration-mass to user-mass factor.

bool	active (const SimulationContext &ctx) noexcept
	Read whether the resolved surface species store is active.

void	resolveLidRemovals (SimulationContext &ctx, std::vector< std::string > &warnings)
	Bind by-name LID removals to pollutant or native species identities.

void	activateForRain (SimulationContext &ctx) noexcept
	Enable native surface storage needed by rainfall or scoped reaction/LID laws.

std::vector< std::string >	resolve (SimulationContext &ctx)
	Resolve named surface rows then activate rainfall/reaction-only species storage.

void	refreshDerived (SimulationContext &ctx) noexcept
	Recalculate analytic buildup saturation times after a parameter edit.

void	initState (SimulationContext &ctx)
	Reset native surface state and seed initial dry buildup from loadings or dry days.

void	step (SimulationContext &ctx, double dt_runoff, double old_runoff_time)
	Advance native dry/wet species reactions and shared surface buildup/washoff once.

void	bookPostLid (SimulationContext &ctx, double dt_runoff, const std::vector< double > &lid_infil_vol)
	Book native species deposition/infiltration and runoff after conventional LID routing.

void	addLidDrain (SimulationContext &ctx, int control, int sc, int node, double drain_cfs, bool to_perv, bool runoff_load, double dt_runoff, const double *source) noexcept
	Queue one conventional LID underdrain species export and optional runoff/BMP mass bookings.

void	addLidDrainRunon (SimulationContext &ctx, int control, int sc, int receiver, double drain_cfs, bool to_perv, bool runoff_load, double dt_runoff, const double *source) noexcept
	Queue one conventional LID underdrain species export and optional runoff/BMP mass bookings.

void	consumeLidDrainRunon (SimulationContext &ctx, int receiver) noexcept
	Move queued LID underdrain species run-on into one receiver and clear that queue.

void	rollLidDrain (SimulationContext &ctx) noexcept
	Retain current node underdrain species rates as previous step then clear current rates.

double	remainingBuildup (const SimulationContext &ctx, int m) noexcept
	Sum retained surface and conventional-LID species inventory for final user-mass reporting.

void	clearRunon (SimulationContext &ctx) noexcept
	Clear every native surface species run-on mass-rate entry before assembly.

void	addRunon (SimulationContext &ctx, int donor, int receiver, double q) noexcept
	Add donor previous-runoff species concentration to one receiver's run-on mass rate.

void	deliver (SimulationContext &ctx, double dt_routing)
	Deliver this routing step's washoff into `msx_ext_mass_in` (+= interpolated old/new runoff mass rate per outlet node, the `addWetWeatherLoads` trapezoid on old/new runoff). Call after the external-inflow assembly has (re)zeroed the array for the step.

Function Documentation

◆ activateForRain()

void openswmm::msxsurf::activateForRain ( SimulationContext & ctx )

noexcept

Enable native surface storage needed by rainfall or scoped reaction/LID laws.

Parameters

[in,out] ctx Configured native species and final land-use/subcatchment counts; may resize parameters and initial loading, set conversion factors/derived limits and mark resolved.

Note: Returns when already resolved or reactions unconfigured. Positive rain concentration, subcatchment/buildup reaction laws or any LID control can activate otherwise empty rows. Dimension mismatch resets parameter/loading arrays; existing evolved state should not be passed through reconfiguration. No water/clock update; exclusive lifecycle. Allocations in this noexcept routine terminate on allocation failure rather than returning an error.

Set the store up for a species that only rains in (called by resolve and initState).

Here is the call graph for this function:

Here is the caller graph for this function:

◆ active()

bool openswmm::msxsurf::active ( const SimulationContext & ctx )

noexcept

Read whether the resolved surface species store is active.

True once rows resolved to at least one MSX species with a land use.

Parameters

[in] ctx Stable reaction surface dimensions/resolution flag.

Returns: surface.active(), without resolving rows, rebuilding state or allocating.

◆ addLidDrain()

void openswmm::msxsurf::addLidDrain	(	SimulationContext &	ctx,
		int	control,
		int	sc,
		int	node,
		double	drain_cfs,
		bool	to_perv,
		bool	runoff_load,
		double	dt_runoff,
		const double *	source )

noexcept

Queue one conventional LID underdrain species export and optional runoff/BMP mass bookings.

Parameters

[in,out]	ctx	Active surface concentrations, removal fractions, conversion factors and ledgers.
[in]	control	LID control ID; missing/invalid removal tuple uses fraction0, without clamping.
[in]	sc	Valid source subcatchment ID, required when source is null or source-ledger booking occurs.
[in]	node	Native destination node ID; invalid returns before state access.
[in]	drain_cfs	Accepted underdrain flow ft3/s, caller validates sign/finite value.
[in]	to_perv	True suppresses runoff/BMP/user-load bookings; destination queue still receives rate.
[in]	runoff_load	True books positive post-removal load as runoff when not routed to pervious land.
[in]	dt_runoff	Matching accepted runoff duration s used only for mass bookings.
[in]	source	Optional borrowed n_species underdrain concentrations; null uses source washoff. When supplied, books source total load as well. Must remain stable and not alias writable ledgers.

Note: User-mass bookings use drain*c*dt*28.317*mcf. Does not transfer water or change clock; exactly-once accepted export and exclusive queue/context ownership required. No generic extent/physical validation. Node queue is resized/reset when shape differs, then adds concentration*ft3/s without litre factor. Allocation inside noexcept terminates on failure; reset can discard previous mismatched queue.

LID underdrain species load from one unit (the A6b drain loop's species half), and the per-runoff-step roll of those loads.

◆ addLidDrainRunon()

void openswmm::msxsurf::addLidDrainRunon	(	SimulationContext &	ctx,
		int	control,
		int	sc,
		int	receiver,
		double	drain_cfs,
		bool	to_perv,
		bool	runoff_load,
		double	dt_runoff,
		const double *	source )

noexcept

Queue one conventional LID underdrain species export and optional runoff/BMP mass bookings.

Parameters

[in,out]	ctx	Active surface concentrations, removal fractions, conversion factors and ledgers.
[in]	control	LID control ID; missing/invalid removal tuple uses fraction0, without clamping.
[in]	sc	Valid source subcatchment ID, required when source is null or source-ledger booking occurs.
[in]	receiver	Destination subcatchment ID; invalid returns. Covered run-on tuples accumulate concentration-mass/s using28.317L/ft3; queue is not resized here.
[in]	drain_cfs	Accepted underdrain flow ft3/s, caller validates sign/finite value.
[in]	to_perv	True suppresses runoff/BMP/user-load bookings; destination queue still receives rate.
[in]	runoff_load	True books positive post-removal load as runoff when not routed to pervious land.
[in]	dt_runoff	Matching accepted runoff duration s used only for mass bookings.
[in]	source	Optional borrowed n_species underdrain concentrations; null uses source washoff. When supplied, books source total load as well. Must remain stable and not alias writable ledgers.

Note: User-mass bookings use drain*c*dt*28.317*mcf. Does not transfer water or change clock; exactly-once accepted export and exclusive queue/context ownership required. No generic extent/physical validation. Allocation-free; uncovered destination tuples are skipped while mass bookings may still proceed.

A LID underdrain routed to another subcatchment: the species join that subcatchment's run-on (next runoff step), as the water does.

◆ addRunon()

void openswmm::msxsurf::addRunon	(	SimulationContext &	ctx,
		int	donor,
		int	receiver,
		double	q )

noexcept

Add donor previous-runoff species concentration to one receiver's run-on mass rate.

Parameters

[in,out]	ctx	Active surface old washoff concentration and writable runon arrays, matching dimensions.
[in]	donor	Valid nonnegative subcatchment index; source tuple must be covered.
[in]	receiver	Valid nonnegative destination subcatchment index; destination tuple must be covered.
[in]	q	Routed runoff ft3/s; sign/finite value is not validated or clamped.

Note: Adds q*old_concentration*28.317L/ft3 for covered tuples; inactive returns. Does not clear queues, move hydraulic water, book global mass or advance clock. No allocation; exclusive assembly access.

◆ bookPostLid()

void openswmm::msxsurf::bookPostLid	(	SimulationContext &	ctx,
		double	dt_runoff,
		const std::vector< double > &	lid_infil_vol )

Book native species deposition/infiltration and runoff after conventional LID routing.

Parameters

[in,out]	ctx	Active resolved native surface stores and matching accepted LID/runoff hydraulics; receives shared-kernel user-mass ledgers.
[in]	dt_runoff	Matching positive finite runoff interval s, caller qualified.
[in]	lid_infil_vol	Per-subcatchment accepted LID infiltration volumes ft3, covered for all sources.

Note: Inactive/no-subcatchment returns. Builds temporary parameter vectors and borrows synchronous views; shared kernel controls ignored-quality handling. No water/clock advance; exactly-once post-LID phase and exclusive state required. Allocations/partial ledger changes may throw.

Post-LID bookings for the species, after the LID units have run (SWMMEngine::bookWashoffLoads' species half).

Here is the call graph for this function:

◆ clearRunon()

void openswmm::msxsurf::clearRunon ( SimulationContext & ctx )

noexcept

Clear every native surface species run-on mass-rate entry before assembly.

Run-on, beside the pollutant lines in SWMMEngine::assembleRunon.

Parameters

[in,out] ctx Writable surface runon_qual_rate, regardless of active flag.

Note: No allocation, other queues/ledgers, water or clock changes. Caller owns exclusive assembly phase; clearing after addRunon/consumeLidDrainRunon discards those pending rates.

◆ consumeLidDrainRunon()

void openswmm::msxsurf::consumeLidDrainRunon	(	SimulationContext &	ctx,
		int	receiver )

noexcept

Move queued LID underdrain species run-on into one receiver and clear that queue.

Parameters

[in,out]	ctx	Active surface store with matching runon and underdrain queue extents.
[in]	receiver	Valid nonnegative subcatchment ID, with products fitting indexing types.

Note: For covered tuples adds concentration-mass/s then zeros queue; inactive returns. No allocation, water/clock change or mass conversion. Caller serializes queue production/consumption and consumes once before the receiver's runoff interval; uncovered tuple remains queued.

◆ deliver()

void openswmm::msxsurf::deliver	(	SimulationContext &	ctx,
		double	dt_routing )

Deliver this routing step's washoff into msx_ext_mass_in (+= interpolated old/new runoff mass rate per outlet node, the addWetWeatherLoads trapezoid on old/new runoff). Call after the external-inflow assembly has (re)zeroed the array for the step.

Parameters

[in,out]	ctx	Native node inflow destination and matching accepted surface/LID histories.
[in]	dt_routing	Unused routing duration s, retained for routing-dispatch interface consistency.

Here is the call graph for this function:

◆ initState()

void openswmm::msxsurf::initState ( SimulationContext & ctx )

Reset native surface state and seed initial dry buildup from loadings or dry days.

Size the state and seed initial buildup: [LOADINGS] row when given, else the land use's function at [OPTIONS] DRY_DAYS (legacy landuse_getInitBuildup).

Parameters

[in,out] ctx Resolved species/land-use parameters, final coverage percentages, user-unit areas/curb lengths and DRY_DAYS. May activate rain-only storage, then resize/reset state/ledgers.

Note: Positive loading takes precedence for every covered land use: per-area loading is direct; per-curb loading is scaled area/curb,0 for absent curb. Otherwise positive dry days use analytic power/exponential/saturation, never external series. Books mass*coverage-normalizer to initial user mass ledger. Requires prepared positive dimensions and covered parallel arrays. No water/clock advance. Exclusive initial lifecycle; repeating resets evolved stores. Allocations may partially reset.

Here is the call graph for this function:

◆ refreshDerived()

void openswmm::msxsurf::refreshDerived ( SimulationContext & ctx )

noexcept

Recalculate analytic buildup saturation times after a parameter edit.

Re-derive bu_max_days after a parameter edit (C API).

Parameters

[in,out] ctx Parallel surface bu_type/c1/c2/c3/max_days arrays with equal covered extents. Writes max_days for each configured row: exponential .1-percent remainder time, power cap time, saturation999*c3, otherwise0.

Note: No resize, finite/domain validation beyond positive coefficient guards, clock or inventory change. Caller serializes parameter edits and subsequent surface steps.

Here is the caller graph for this function:

◆ remainingBuildup()

double openswmm::msxsurf::remainingBuildup	(	const SimulationContext &	ctx,
		int	m )

noexcept

Sum retained surface and conventional-LID species inventory for final user-mass reporting.

Parameters

[in]	ctx	Stable matching coverage, user-unit geometry, normalizers, conversion factors and surface/conventional-LID storage; all parallel configured extents prepared.
[in]	m	Zero-based native species; inactive/invalid yields0.

Returns: User mass from covered normalized dry buildup, ponded mass*mcf, conventional LID layer/carry native mass*28.317*mcf and retained ponded-loss ledger. Does not include native LID-node stores or undelivered node/run-on queues. Read-only, no allocation or receipt consumption; consistent phase required.

Species m left on the land at the end (user mass), the qual_final_buildup row of the pollutants.

◆ resolve()

std::vector< std::string > openswmm::msxsurf::resolve ( SimulationContext & ctx )

Resolve named surface rows then activate rainfall/reaction-only species storage.

Bind the by-name rows to (land use, species) — call after the reactions component has been applied and the name tables are final.

Parameters

[in,out] ctx Stable final species, pollutant, land-use, subcatchment and control names; receives resolved parameters/removal tables and activation state.

Returns: Nonfatal row/removal warnings from resolveRows. Allocation/configuration exceptions can leave partial changes; no rollback, physical water advance or engine clock change. Exclusive setup.; Warnings (unresolvable species / land use / subcatchment names, WALL species). Never fatal: a typo in a row is a warning here, exactly as the pollutant handlers silently skip theirs.

Here is the call graph for this function:

◆ resolveLidRemovals()

void openswmm::msxsurf::resolveLidRemovals	(	SimulationContext &	ctx,
		std::vector< std::string > &	warnings )

Bind by-name LID removals to pollutant or native species identities.

Bind LID REMOVALS entries kept by name (called by resolve).

Parameters

[in,out]	ctx	Final pollutant/species/LID control names; resets dense control*n_species MSX removals and migrates recognized pollutant rows into each control's indexed pollutant removal list.
[in,out]	warnings	Appends unknown-species warnings; preserves previous entries.

Note: MSX rows remain by-name for repeat resolution, pollutant rows are removed after migration. Fractions are copied without range/finite validation. Requires stable matching counts; allocations can leave partial tables/migrations. Exclusive configuration phase; no hydraulic/clock change.

Here is the call graph for this function:

◆ rollLidDrain()

void openswmm::msxsurf::rollLidDrain ( SimulationContext & ctx )

noexcept

Retain current node underdrain species rates as previous step then clear current rates.

Parameters

[in,out] ctx Surface current/old node*species underdrain rate arrays, even when inactive.

Note: Copies concentration*ft3/s and clears only current node rates, not subcatchment run-on queue. No physical water/clock/ledger change. Exclusive once-per-runoff chronology; vector copy may allocate inside noexcept, terminating on allocation failure.

◆ speciesUnitFactor()

double openswmm::msxsurf::speciesUnitFactor	(	const std::string &	units,
		const SimulationOptions &	opts )

Map a species unit prefix to its concentration-mass to user-mass factor.

Parameters

[in]	units	Case-insensitive text: prefixes UG and MG select micrograms and milligrams; all other strings, including count units, select factor1. Prefixes need not occupy the full string.
[in]	opts	Unit system used by UCF(MASS).

Returns: UCF(MASS)/1000 for UG, UCF(MASS) for MG, otherwise1. No model mutation; text copy can allocate.

D-A27: concentration-mass → user-mass factor from a species' declared units (MG → UCF(MASS), UG → UCF(MASS)/1000, anything else → 1). Shared with the 2D cell store (S7).

Here is the call graph for this function:

Here is the caller graph for this function:

◆ step()

void openswmm::msxsurf::step	(	SimulationContext &	ctx,
		double	dt_runoff,
		double	old_runoff_time )

Advance native dry/wet species reactions and shared surface buildup/washoff once.

One runoff step: buildup accrual then washoff for every (subcatchment, land use, species); stores the washoff concentration per (subcatchment, species) for delivery. Runs the pollutant kernel (SurfaceSpeciesKernel) over the species store (Multispecies Phase 2).

Parameters

[in,out]	ctx	Active resolved surface species, final parameters and completed runoff hydraulics; receives inventories/concentrations, user-mass ledgers and possible reaction warnings.
[in]	dt_runoff	Positive finite accepted runoff duration s; inactive/nonpositive/NaN returns.
[in]	old_runoff_time	Runoff step start in elapsed simulation seconds for external buildup/sweeps.

Note: Materializes parameters, reacts dry buildup, optionally reacts complete ponded pools then passes borrowed synchronous views to SurfaceSpeciesKernel. Caller enforces quality enable/phase, matching extents and exactly-once chronology; no water or clock advance. Allocation or reaction errors may leave earlier inventory/ledger changes; no global rollback or thread-safe shared access.

Argument dt_runoff: runoff step (s)
Argument old_runoff_time: seconds since the start at the step's start

Here is the call graph for this function:

Functions

Function Documentation

◆ activateForRain()

◆ active()

◆ addLidDrain()

◆ addLidDrainRunon()

◆ addRunon()

◆ bookPostLid()

◆ clearRunon()

◆ consumeLidDrainRunon()

◆ deliver()

◆ initState()

◆ refreshDerived()

◆ remainingBuildup()

◆ resolve()

◆ resolveLidRemovals()

◆ rollLidDrain()

◆ speciesUnitFactor()

◆ step()