#include <SurfaceTransportState.hpp>

Collaboration diagram for openswmm::twoD::SurfaceTransportState:

Classes
struct	BoundaryQualityRow

Public Member Functions
bool	signedRow (int s) const noexcept
	The temperature row is SIGNED (°C below zero is a state, not an error): every "mass ≥ 0" guard in the marcher and the queue must skip it. Age and every concentration row are non-negative.

int	rowIndex (std::string_view name) const noexcept
	Resolve an exact species name in the current transport layout.

bool	active () const noexcept
	Test whether cell transport arrays have a nonempty layout.

void	resize (int n_spec, int n_tri, int n_coupling_points)
	Reset core transport inventory and ledgers to a new tuple/cell layout.

void	clear ()
	Replace the complete surface transport state with empty defaults.

std::size_t	idx (int s, int c) const noexcept
	Map a species/cell pair into species-major storage.

double	concentration (int s, int c, double volume_m3, double dry_volume_m3) const noexcept
	Reported concentration — derived, never stored. `dry_volume_m3` is the hydraulics' own dry threshold expressed as a volume; below it the cell holds its mass and reports 0 rather than dividing by a vanishing volume (the 2D analogue of the 1D dryness guard).

double	totalIncludingLedgers (int s) const noexcept
	Total mass of one species over the surface + every ledger — the quantity the S1 conservation gate asserts is invariant.

Public Attributes
int	n_species = 0
	rows carried; 0 ⇒ transport is off everywhere

int	n_cells = 0

int	n_pollut = 0

int	n_msx = 0

int	age_row = -1

int	temp_row = -1

std::vector< std::string >	row_names

std::vector< double >	cell_mass

std::vector< double >	lost_infiltration
	left through the bed

std::vector< double >	lost_boundary
	left through an open edge

std::vector< double >	gained_external

std::vector< double >	lost_external

std::vector< double >	gained_bed
	signed finite-bed -> surface exchange; empty in compatibility mode

std::vector< double >	lost_coupling

std::vector< double >	exch_mass

std::vector< double >	exch_spill

std::vector< double >	rain_conc

std::vector< double >	bc_conc

std::map< int, std::vector< double > >	runtime_bc_conc

std::vector< BoundaryQualityRow >	bc_quality_rows

long	dispersion_limiter_binds = 0

std::vector< double >	gained_rainfall

std::vector< double >	gained_boundary

std::vector< double >	gained_coupling

std::vector< double >	gained_exfiltration

std::vector< double >	generated_age

std::vector< double >	gained_washoff

std::vector< double >	cell_runoff_vol

std::vector< double >	coupling_src

Member Function Documentation

◆ active()

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

inlinenoexcept

Test whether cell transport arrays have a nonempty layout.

Returns: True when both n_species and n_cells are positive; this does not verify vector extents or process activation. Read-only and allocation-free.

Here is the caller graph for this function:

◆ clear()

void openswmm::twoD::SurfaceTransportState::clear ( )

inline

Replace the complete surface transport state with empty defaults.

Postcondition: Clears all inventories, ledgers, source caches and row layout, including optional quality stores. Previously borrowed references/indices are invalidated; requires exclusive access.

◆ concentration()

double openswmm::twoD::SurfaceTransportState::concentration	(	int	s,
		int	c,
		double	volume_m3,
		double	dry_volume_m3 ) const

inlinenoexcept

Reported concentration — derived, never stored. dry_volume_m3 is the hydraulics' own dry threshold expressed as a volume; below it the cell holds its mass and reports 0 rather than dividing by a vanishing volume (the 2D analogue of the 1D dryness guard).

Parameters

[in]	s	Valid zero-based species index, unchecked.
[in]	c	Valid zero-based cell index, unchecked.
[in]	volume_m3	Current SI water volume, m3.
[in]	dry_volume_m3	Nonnegative dry threshold, m3.

Returns: Native concentration, age seconds or temperature degrees Celsius; zero when volume_m3 is not strictly greater than dry_volume_m3, including NaN volume.

Note: Does not consume/clip stored mass or validate nonfinite inventory. Requires coherently sized, stable mass storage; no allocation.

Here is the call graph for this function:

◆ idx()

std::size_t openswmm::twoD::SurfaceTransportState::idx	(	int	s,
		int	c ) const

inlinenoexcept

Map a species/cell pair into species-major storage.

Parameters

[in]	s	Valid nonnegative species row in [0,n_species).
[in]	c	Valid nonnegative mixed-cell index in [0,n_cells).

Returns: size_t offset s*n_cells+c; no bounds or overflow checking. No allocation or mutation.

Here is the caller graph for this function:

◆ resize()

void openswmm::twoD::SurfaceTransportState::resize	(	int	n_spec,
		int	n_tri,
		int	n_coupling_points )

inline

Reset core transport inventory and ledgers to a new tuple/cell layout.

Parameters

[in]	n_spec	Requested species count; nonpositive clamps to zero.
[in]	n_tri	Requested mixed-cell count; nonpositive clamps to zero.
[in]	n_coupling_points	Requested coupling-point count; nonpositive clamps to zero.

Postcondition: Sets a provisional pollutant-only layout with age/temp unset, zeroes core cell/ledger/exchange arrays and clears source/boundary caches. The router refines row names/layout after this call.

Note: Existing gained_washoff and cell_runoff_vol vectors are not reset here; their quality owner manages them. Allocations may throw after partial reset. Requires exclusive access; indices/references may be invalidated.

◆ rowIndex()

int openswmm::twoD::SurfaceTransportState::rowIndex ( std::string_view name ) const

inlinenoexcept

Resolve an exact species name in the current transport layout.

Parameters

[in] name Borrowed non-owning name view, used only during this call.

Returns: First exact case-sensitive row index, or -1 when absent. Read-only linear scan; no allocation or retained string view.

◆ signedRow()

bool openswmm::twoD::SurfaceTransportState::signedRow ( int s ) const

inlinenoexcept

The temperature row is SIGNED (°C below zero is a state, not an error): every "mass ≥ 0" guard in the marcher and the queue must skip it. Age and every concentration row are non-negative.

Note: Test whether a transport row uses signed inventory.

Parameters

[in] s Valid zero-based species row; caller excludes the -1 unset sentinel.

Returns: True exactly when s == temp_row; false otherwise. No bounds validation, allocation or state mutation.

◆ totalIncludingLedgers()

double openswmm::twoD::SurfaceTransportState::totalIncludingLedgers ( int s ) const

inlinenoexcept

Total mass of one species over the surface + every ledger — the quantity the S1 conservation gate asserts is invariant.

Parameters

[in] s Valid zero-based species row with all mandatory ledger arrays sized, unchecked.

Returns: Sum of stored inventory plus infiltration/boundary/coupling/external losses minus external/rain/boundary/coupling/washoff/exfiltration/age-production gains, in native concentration*m3.

Note: Optional missing gain arrays contribute zero. gained_bed is not included by this helper, so callers using finite-bed exchange must account for that separate ledger in their conservation statement. No allocation or state mutation; read only accepted stable state.

Member Data Documentation

◆ age_row

int openswmm::twoD::SurfaceTransportState::age_row = -1

◆ bc_conc

std::vector<double> openswmm::twoD::SurfaceTransportState::bc_conc

[bc_slot * n_species + s] concentration carried by INFLOW through a non-WALL boundary edge, from [2D_BOUNDARY_QUALITY]. Sized by the solver to its own bc_cell_ list at initialize; empty ⇒ inflow arrives clean. Outflow always leaves at the cell's concentration.

◆ bc_quality_rows

std::vector<BoundaryQualityRow> openswmm::twoD::SurfaceTransportState::bc_quality_rows

◆ cell_mass

std::vector<double> openswmm::twoD::SurfaceTransportState::cell_mass

[s * n_cells + c] species mass in the cell's water, in the species' own mass units (concentration units × m³, so a report divides by the SI cell volume and needs no further conversion).

◆ cell_runoff_vol

std::vector<double> openswmm::twoD::SurfaceTransportState::cell_runoff_vol

S7: [c] the cell's NET runoff volume (m³, signed) since the last runoff step: + what left across its faces, open boundary edges and drains to nodes, − what arrived across faces, from node spills, outfall discharge, prescribed inflow and inflow boundaries. Rainfall and groundwater return are generation, not inflow, so they are not subtracted: the positive part is the runoff the cell itself produced (rain excess plus storage release, the subcatchment step's q·A) — D-A22 as revised 2026-09-19. Accumulated by the marcher only while non-empty (sized by the router with the coverages); read, clamped at zero and zeroed by SurfaceQuality2D::step.

◆ coupling_src

std::vector<double> openswmm::twoD::SurfaceTransportState::coupling_src

[s * n_cells + c] species mass-rate DENSITY (conc · m/s) riding the positive coupling_flux an outfall scatters onto its cells, so a cell gains coupling_src · area · dt beside the volume coupling_flux · / area · dt. Sized by the router when transport is active and outfall points exist; empty ⇒ outfall discharge arrives clean. The junction spill does NOT use this — it is booked live in the marcher from the node's concentration.

◆ dispersion_limiter_binds

long openswmm::twoD::SurfaceTransportState::dispersion_limiter_binds = 0

Times the explicit dispersive exchange on a face was capped to keep the pair from crossing (the max-principle limiter). Nonzero means the dispersion is under-resolved at the marcher's dt on that face — a modelling signal, not an error, and the reason it is counted rather than hidden.

◆ exch_mass

std::vector<double> openswmm::twoD::SurfaceTransportState::exch_mass

[k * n_species + s] species mass drained through coupling point k this advance (m³·conc, + = 2D→1D). Reset with exch_ per advance; S3's tuple reads it into the node's qual_mass_in.

◆ exch_spill

std::vector<double> openswmm::twoD::SurfaceTransportState::exch_spill

[k] spill VOLUME (m³, 1D→2D side only) through coupling point k this advance. Volume, not mass — it exists for the mass bookkeeping: the volume queue NETS a window's flip-flop while exch_mass holds the drain GROSS, and the router pairs min(spill, drain) of the spill against the queued mass at the node's concentration so a mixed-sign window hands the node mass and water in the same ratio. The net-negative remainder is the part the node's own volume drop removes at the mixed concentration (the plan's §2.1 argument, now scoped to exactly that remainder). Reset with exch_mass.

◆ gained_bed

std::vector<double> openswmm::twoD::SurfaceTransportState::gained_bed

signed finite-bed -> surface exchange; empty in compatibility mode

◆ gained_boundary

std::vector<double> openswmm::twoD::SurfaceTransportState::gained_boundary

◆ gained_coupling

std::vector<double> openswmm::twoD::SurfaceTransportState::gained_coupling

S3: what came in through the 1D→2D coupling (junction spill at the node's published concentration, outfall discharge at the outfall's).

◆ gained_exfiltration

std::vector<double> openswmm::twoD::SurfaceTransportState::gained_exfiltration

T7.1: mass the two-zone aquifer handed back up with its saturation excess. The twin of lost_infiltration, which is what went down.

◆ gained_external

std::vector<double> openswmm::twoD::SurfaceTransportState::gained_external

◆ gained_rainfall

std::vector<double> openswmm::twoD::SurfaceTransportState::gained_rainfall

Source ledgers (per species, m³·conc, cumulative) so the continuity statement can close: what came in through rain and boundaries.

◆ gained_washoff

std::vector<double> openswmm::twoD::SurfaceTransportState::gained_washoff

S7: [s] species mass washed off the cells' land-use surfaces into the rows (cell buildup → water), m³·conc. Sized by the router when [2D_COVERAGES] resolves; empty otherwise.

◆ generated_age

std::vector<double> openswmm::twoD::SurfaceTransportState::generated_age

RK2 age-volume production; empty in first-order compatibility mode

◆ lost_boundary

std::vector<double> openswmm::twoD::SurfaceTransportState::lost_boundary

left through an open edge

◆ lost_coupling

std::vector<double> openswmm::twoD::SurfaceTransportState::lost_coupling

left through the 1D↔2D exchange

◆ lost_external

std::vector<double> openswmm::twoD::SurfaceTransportState::lost_external

◆ lost_infiltration

std::vector<double> openswmm::twoD::SurfaceTransportState::lost_infiltration

left through the bed

◆ n_cells

int openswmm::twoD::SurfaceTransportState::n_cells = 0

◆ n_msx

int openswmm::twoD::SurfaceTransportState::n_msx = 0

◆ n_pollut

int openswmm::twoD::SurfaceTransportState::n_pollut = 0

◆ n_species

int openswmm::twoD::SurfaceTransportState::n_species = 0

rows carried; 0 ⇒ transport is off everywhere

◆ rain_conc

std::vector<double> openswmm::twoD::SurfaceTransportState::rain_conc

[s] concentration carried by rainfall — [POLLUTANTS] rain concentration, set by the router. Empty ⇒ rain arrives clean (S1).

◆ row_names

std::vector<std::string> openswmm::twoD::SurfaceTransportState::row_names

Row names in row order (pollutant ids, MSX ids, __WATER_AGE__, __TEMPERATURE__) — what the HDF5 species attribute and the [2D_INITIAL_QUALITY]/[2D_BOUNDARY_QUALITY] resolvers key on.

◆ runtime_bc_conc

std::map<int, std::vector<double> > openswmm::twoD::SurfaceTransportState::runtime_bc_conc

◆ temp_row

int openswmm::twoD::SurfaceTransportState::temp_row = -1

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

/home/runner/work/openswmm.engine/openswmm.engine/src/engine/2d/data/SurfaceTransportState.hpp

Classes

Public Member Functions

Public Attributes

Member Function Documentation

◆ active()

◆ clear()

◆ concentration()

◆ idx()

◆ resize()

◆ rowIndex()

◆ signedRow()

◆ totalIncludingLedgers()

Member Data Documentation

◆ age_row

◆ bc_conc

◆ bc_quality_rows

◆ cell_mass

◆ cell_runoff_vol

◆ coupling_src

◆ dispersion_limiter_binds

◆ exch_mass

◆ exch_spill

◆ gained_bed

◆ gained_boundary

◆ gained_coupling

◆ gained_exfiltration

◆ gained_external

◆ gained_rainfall

◆ gained_washoff

◆ generated_age

◆ lost_boundary

◆ lost_coupling

◆ lost_external

◆ lost_infiltration

◆ n_cells

◆ n_msx

◆ n_pollut

◆ n_species

◆ rain_conc

◆ row_names

◆ runtime_bc_conc

◆ temp_row