The S7 store: authored rows, resolved per-cell coverages and state, and the per-species ledgers. More...

#include <SurfaceQuality2D.hpp>

Collaboration diagram for openswmm::twoD::SurfaceQuality2D:

Public Member Functions
bool	authored () const noexcept
	Test whether any coverage, loading or curb authoring row exists.

void	clearRows ()
	Clear all authored coverage, loading and curb-length rows.

std::vector< std::string >	resolve (const SimulationContext &ctx, const MeshData &mesh, const SurfaceTransportState &tr, const SolverOptions2D &opts)
	Bind the rows to the mesh, the land uses and the transport rows.

bool	active () const noexcept
	Read whether the last resolution activated mesh surface quality.

void	initState (const SimulationContext &ctx, const MeshData &mesh)
	Seed initial buildup: `[2D_LOADINGS]` row, else the buildup function at `[OPTIONS] DRY_DAYS` (legacy landuse_getInitBuildup).

void	step (const SimulationContext &ctx, const MeshData &mesh, SurfaceStateData &state, double dt_runoff, double abs_time, bool is_raining)
	One runoff step: buildup accrual, washoff into the cell rows, street sweeping.

int	nLandUses () const noexcept
	Read the resolved land-use count.

int	nSpecies () const noexcept
	Read the resolved pollutant plus MSX buildup row count, excluding age/temperature.

int	nCells () const noexcept
	< surface species (rows that build up)

int	rowOf (int s) const noexcept
	Transport row index of surface species `s` (pollutants first, then MSX).

const std::string &	speciesName (int s) const noexcept
	Read resolved per-species metadata.

double	coverage (int c, int lu) const noexcept
	Read one resolved cell/land-use coverage fraction.

double	curbLength (int c) const noexcept
	Read resolved curb normalization length.

double	buildup (int c, int lu, int s) const noexcept
	Buildup of species s on land use lu of cell c, user mass per normalizer unit.

double	buildupPerArea (int c, int s) const noexcept
	Total buildup of species s on cell c per unit land area (user mass / acre or ha) — what the results file reports.

const std::vector< double > &	ledInitBuildup () const noexcept
	Per-species ledgers, user mass, cumulative.

const std::vector< double > &	ledBuildup () const noexcept
	Borrow cumulative accrued buildup, including generated storeless-washoff supply per surface species.

const std::vector< double > &	ledWashoff () const noexcept
	Borrow cumulative net washoff delivered to surface transport after BMP per surface species.

const std::vector< double > &	ledSweeping () const noexcept
	Borrow cumulative buildup removed by sweeping per surface species.

const std::vector< double > &	ledBmp () const noexcept
	Borrow cumulative washoff removed by BMP treatment per surface species.

double	mcf (int s) const noexcept
	Per-species conversion: concentration-mass units → user mass (lbs / kg).

double	runoffVolume (int c) const noexcept
	Cumulative runoff volume (m³) the cell produced (the positive part of its net outflow per step, D-A22) — the `q·A·dt` the washoff laws saw.

double	wetRunoffVolume (int c) const noexcept
	…of which on steps fast enough to wash off (legacy MIN_RUNOFF): the volume an EMC washes off at its concentration.

Public Attributes
std::vector< CoverageRow2D >	coverage_rows

std::vector< LoadingRow2D >	loading_rows

std::vector< CurbRow2D >	curb_rows

Detailed Description

The S7 store: authored rows, resolved per-cell coverages and state, and the per-species ledgers.

Member Function Documentation

◆ active()

bool openswmm::twoD::SurfaceQuality2D::active ( ) const

inlinenoexcept

Read whether the last resolution activated mesh surface quality.

Returns: Stored flag, false after unresolved/failed/inert resolution. Does not validate current external row identity or inspect whether any cell currently has runoff/buildup. No mutation.

◆ authored()

bool openswmm::twoD::SurfaceQuality2D::authored ( ) const

inlinenoexcept

Test whether any coverage, loading or curb authoring row exists.

Returns: True for any nonempty authored vector, independent of resolved activation/validity. No resolution, allocation or state change occurs.

Here is the caller graph for this function:

◆ buildup()

double openswmm::twoD::SurfaceQuality2D::buildup	(	int	c,
		int	lu,
		int	s ) const

inlinenoexcept

Buildup of species s on land use lu of cell c, user mass per normalizer unit.

Parameters

[in]	c	Valid resolved cell, unchecked.
[in]	lu	Valid resolved land-use row, unchecked.
[in]	s	Valid resolved buildup species, unchecked.

Returns: Stored user mass per land-area or curb normalizer unit. To obtain actual user mass, multiply by coverage times cell land area or coverage times curb length according to the law. Read-only and allocation-free; no normalization, sweeping or washoff is performed.

◆ buildupPerArea()

double openswmm::twoD::SurfaceQuality2D::buildupPerArea	(	int	c,
		int	s ) const

noexcept

Total buildup of species s on cell c per unit land area (user mass / acre or ha) — what the results file reports.

Parameters

[in]	c	Valid resolved cell when active, unchecked.
[in]	s	Valid resolved species when active, unchecked.

Returns: Total stored buildup user mass per acre (US) or ha (SI), summed across covered land uses. Inactive/nonpositive resolved land area returns zero. Uses each law's actual area/curb normalizer; no mutation or allocation occurs.

◆ clearRows()

void openswmm::twoD::SurfaceQuality2D::clearRows ( )

inline

Clear all authored coverage, loading and curb-length rows.

Note: Does not clear resolved runtime arrays, activation, buildup or cumulative ledgers. Caller re-resolves before reusing changed authoring. Invalidates row views and requires exclusive access.

◆ coverage()

double openswmm::twoD::SurfaceQuality2D::coverage	(	int	c,
		int	lu ) const

inlinenoexcept

Read one resolved cell/land-use coverage fraction.

Parameters

[in]	c	Valid cell [0,nCells()), unchecked.
[in]	lu	Valid land use [0,nLandUses()), unchecked.

Returns: Fraction 0..1 from resolved scope precedence, not percentage. Read-only and allocation-free; does not infer active quality or current buildup.

◆ curbLength()

double openswmm::twoD::SurfaceQuality2D::curbLength ( int c ) const

inlinenoexcept

Read resolved curb normalization length.

Parameters

[in] c Valid cell [0,nCells()), unchecked.

Returns: Stored project length units, zero where unauthored. Not SI-converted automatically. Requires stable resolved arrays; no mutation, allocation or current geometry lookup occurs.

◆ initState()

void openswmm::twoD::SurfaceQuality2D::initState	(	const SimulationContext &	ctx,
		const MeshData &	mesh )

Seed initial buildup: [2D_LOADINGS] row, else the buildup function at [OPTIONS] DRY_DAYS (legacy landuse_getInitBuildup).

Parameters

[in]	ctx	Context with initial dry_days; must match resolved land-use/species identity.
[in]	mesh	Matching SI cell areas; all configured cells must be present.

Note: Inactive returns. Positive authored initial loading overrides function seeding; otherwise positive dry days seeds nonexternal buildup laws. Writes normalized buildup and adds user mass to led_init_ for covered cells. Zero seeding does not clear previous buildup, and ledgers accumulate: call once after resolve() initializes arrays, not repeatedly as a reset. No water/species is added to surface transport until later washoff. Requires exclusive runtime access.

◆ ledBmp()

const std::vector< double > & openswmm::twoD::SurfaceQuality2D::ledBmp ( ) const

inlinenoexcept

Borrow cumulative washoff removed by BMP treatment per surface species.

Returns: Solver-owned const vector in user mass units (lb/kg or configured counts convention), ordered by rowOf()/speciesName(). resolve() resets/replaces it; step/initState mutate it as applicable. Read access requires stable owner; no copy, reset or ownership transfer occurs.

◆ ledBuildup()

const std::vector< double > & openswmm::twoD::SurfaceQuality2D::ledBuildup ( ) const

inlinenoexcept

Borrow cumulative accrued buildup, including generated storeless-washoff supply per surface species.

Returns: Solver-owned const vector in user mass units (lb/kg or configured counts convention), ordered by rowOf()/speciesName(). resolve() resets/replaces it; step/initState mutate it as applicable. Read access requires stable owner; no copy, reset or ownership transfer occurs.

◆ ledInitBuildup()

const std::vector< double > & openswmm::twoD::SurfaceQuality2D::ledInitBuildup ( ) const

inlinenoexcept

Per-species ledgers, user mass, cumulative.

Borrow cumulative seeded initial buildup per surface species.

Returns: Solver-owned const vector in user mass units (lb/kg or configured counts convention), ordered by rowOf()/speciesName(). resolve() resets/replaces it; step/initState mutate it as applicable. Read access requires stable owner; no copy, reset or ownership transfer occurs.

◆ ledSweeping()

const std::vector< double > & openswmm::twoD::SurfaceQuality2D::ledSweeping ( ) const

inlinenoexcept

Borrow cumulative buildup removed by sweeping per surface species.

Returns: Solver-owned const vector in user mass units (lb/kg or configured counts convention), ordered by rowOf()/speciesName(). resolve() resets/replaces it; step/initState mutate it as applicable. Read access requires stable owner; no copy, reset or ownership transfer occurs.

◆ ledWashoff()

const std::vector< double > & openswmm::twoD::SurfaceQuality2D::ledWashoff ( ) const

inlinenoexcept

Borrow cumulative net washoff delivered to surface transport after BMP per surface species.

Returns: Solver-owned const vector in user mass units (lb/kg or configured counts convention), ordered by rowOf()/speciesName(). resolve() resets/replaces it; step/initState mutate it as applicable. Read access requires stable owner; no copy, reset or ownership transfer occurs.

◆ mcf()

double openswmm::twoD::SurfaceQuality2D::mcf ( int s ) const

inlinenoexcept

Per-species conversion: concentration-mass units → user mass (lbs / kg).

Read resolved per-species metadata.

Parameters

[in] s Valid surface species index [0,nSpecies()); unchecked.

Returns: Conversion from concentration-mass units to user mass (lb/kg, or counts convention).

Note: Requires stable resolved arrays. The separate row-volume factor 1000 converts concentration*m3 to concentration-mass. No mutation or validation occurs.

Here is the caller graph for this function:

◆ nCells()

int openswmm::twoD::SurfaceQuality2D::nCells ( ) const

inlinenoexcept

< surface species (rows that build up)

Read the resolved mesh-cell count.

Returns: Stored nonnegative count after valid resolution; not a live query of context authoring. An inactive object can retain counts from partial/previous resolution. No allocation or mutation.

◆ nLandUses()

int openswmm::twoD::SurfaceQuality2D::nLandUses ( ) const

inlinenoexcept

Read the resolved land-use count.

Returns: Stored nonnegative count after valid resolution; not a live query of context authoring. An inactive object can retain counts from partial/previous resolution. No allocation or mutation.

◆ nSpecies()

int openswmm::twoD::SurfaceQuality2D::nSpecies ( ) const

inlinenoexcept

Read the resolved pollutant plus MSX buildup row count, excluding age/temperature.

Returns: Stored nonnegative count after valid resolution; not a live query of context authoring. An inactive object can retain counts from partial/previous resolution. No allocation or mutation.

◆ resolve()

std::vector< std::string > openswmm::twoD::SurfaceQuality2D::resolve	(	const SimulationContext &	ctx,
		const MeshData &	mesh,
		const SurfaceTransportState &	tr,
		const SolverOptions2D &	opts )

Bind the rows to the mesh, the land uses and the transport rows.

Returns: Diagnostics; an entry starting with "ERROR" is fatal (unknown land use / species / tag / cell, percent > 100, PER_CURB land use without a curb length), the rest are warnings (inert under RAINFALL_MODE NONE; double-counting with a covered subcatchment).

Parameters

[in]	ctx	Prepared land-use, pollutant/MSX, unit-system and subcatchment identity. Parameters are copied; source context must remain compatible for subsequent initialization/steps.
[in]	mesh	Prepared SI cell areas/centroids/tags and stable cell identity.
[in]	tr	Prepared native transport layout, with pollutant/MSX rows first and matching names. Age/temperature are excluded from buildup rows.
[in]	opts	Resolved rainfall ownership and mesh coordinate conversion. RAINFALL_MODE NONE leaves runtime inert after authoring validation; possible subcatchment double-loading emits warning.

Note: Resets active first and progressively rebuilds copied parameters, scope-resolved fractions, curb/loadings and zeroed runtime arrays/ledgers. GLOBAL < TAG < CELL overrides replace each coverage set; same-pass row ordering is retained. Calls initState() separately after successful activation. Failure can leave partial/inactive arrays; allocations can throw. Does not modify context/mesh/tr. Requires exclusive access; authored numeric rows must satisfy parser constraints.

Here is the call graph for this function:

◆ rowOf()

int openswmm::twoD::SurfaceQuality2D::rowOf ( int s ) const

inlinenoexcept

Transport row index of surface species s (pollutants first, then MSX).

Read resolved per-species metadata.

Parameters

[in] s Valid surface species index [0,nSpecies()); unchecked.

Returns: Native transport row index for the resolved surface species.

Note: Requires stable resolved arrays. No mutation or validation occurs.

◆ runoffVolume()

double openswmm::twoD::SurfaceQuality2D::runoffVolume ( int c ) const

inlinenoexcept

Cumulative runoff volume (m³) the cell produced (the positive part of its net outflow per step, D-A22) — the q·A·dt the washoff laws saw.

Parameters

[in] c Valid resolved cell index, unchecked.

Returns: Cumulative nonnegative produced runoff, m3, since resolution. Wet eligibility uses q >= MIN_RUNOFF, while actual washoff requires q > MIN_RUNOFF. This read does not consume the per-step transport runoff accumulator or recompute volume. Requires stable arrays; no allocation/mutation.

◆ speciesName()

const std::string & openswmm::twoD::SurfaceQuality2D::speciesName ( int s ) const

inlinenoexcept

Read resolved per-species metadata.

Parameters

[in] s Valid surface species index [0,nSpecies()); unchecked.

Returns: Borrowed solver-owned exact species name; valid until resolve/replacement.

Note: Requires stable resolved arrays. No copy or ownership transfer occurs. No mutation or validation occurs.

◆ step()

void openswmm::twoD::SurfaceQuality2D::step	(	const SimulationContext &	ctx,
		const MeshData &	mesh,
		SurfaceStateData &	state,
		double	dt_runoff,
		double	abs_time,
		bool	is_raining )

One runoff step: buildup accrual, washoff into the cell rows, street sweeping.

Parameters

	dt_runoff	runoff step (s)
	abs_time	absolute date-time at the START of the step
	is_raining	engine's current-step rainfall flag (sweeping gate)
[in]	ctx	Matching engine land-use schedule, current unit system and external buildup tables. Although const-qualified, external buildup lookups update shared table cursors through const_cast; caller serializes with other cursor users.
[in]	mesh	Matching SI cell area array covering nCells().
[in,out]	state	Prepared matching surface transport. Consumes and zeros each cell_runoff_vol, adds native concentration*m3 washoff inventory to cell_mass/gained_washoff and updates this owner's buildup, calendar sweep clocks and cumulative user-mass/runoff ledgers.

Note: dt_runoff must be finite positive; inactive/nonpositive and mismatched/inactive transport returns without work. abs_time is the engine DateTime in days, not elapsed seconds. Buildup on dry runoff steps precedes scheduled dry/in-season sweeping, then wet washoff/BMP removal. Net positive produced runoff determines the rate, not gross lateral throughput. No hydraulic water is removed. State changes progressively; allocation or lookup failures do not roll back earlier cells/rows.

Here is the call graph for this function:

◆ wetRunoffVolume()

double openswmm::twoD::SurfaceQuality2D::wetRunoffVolume ( int c ) const

inlinenoexcept

…of which on steps fast enough to wash off (legacy MIN_RUNOFF): the volume an EMC washes off at its concentration.

Parameters

[in] c Valid resolved cell index, unchecked.

Returns: Cumulative produced runoff on rate-threshold-eligible wet steps, m3, since resolution. Wet eligibility uses q >= MIN_RUNOFF, while actual washoff requires q > MIN_RUNOFF. This read does not consume the per-step transport runoff accumulator or recompute volume. Requires stable arrays; no allocation/mutation.

Member Data Documentation

◆ coverage_rows

std::vector<CoverageRow2D> openswmm::twoD::SurfaceQuality2D::coverage_rows

◆ curb_rows

std::vector<CurbRow2D> openswmm::twoD::SurfaceQuality2D::curb_rows

◆ loading_rows

std::vector<LoadingRow2D> openswmm::twoD::SurfaceQuality2D::loading_rows

The documentation for this class was generated from the following files:

/home/runner/work/openswmm.engine/openswmm.engine/src/engine/2d/quality/SurfaceQuality2D.hpp
/home/runner/work/openswmm.engine/openswmm.engine/src/engine/2d/quality/SurfaceQuality2D.cpp

Public Member Functions

Public Attributes

Detailed Description

Member Function Documentation

◆ active()

◆ authored()

◆ buildup()

◆ buildupPerArea()

◆ clearRows()

◆ coverage()

◆ curbLength()

◆ initState()

◆ ledBmp()

◆ ledBuildup()

◆ ledInitBuildup()

◆ ledSweeping()

◆ ledWashoff()

◆ mcf()

◆ nCells()

◆ nLandUses()

◆ nSpecies()

◆ resolve()

◆ rowOf()

◆ runoffVolume()

◆ speciesName()

◆ step()

◆ wetRunoffVolume()

Member Data Documentation

◆ coverage_rows

◆ curb_rows

◆ loading_rows