openswmm::twoD::SurfaceStateData Struct Reference

#include <SurfaceStateData.hpp>

Collaboration diagram for openswmm::twoD::SurfaceStateData:

Public Member Functions
double	liquidRainfall (int i) const
	Resolve the liquid-water precipitation source for one cell.
double	exposedEvaporation (int i) const
	Resolve atmospheric evaporation demand over the snow-exposed surface.
void	resize (int n_triangles, int n_vertices)
	Reset main surface hydraulic arrays to a new mixed-cell/vertex extent.
void	save_state () noexcept
	Save the current depth and conserved-volume arrays for local rollback.
void	reset_state () noexcept
	Restore only the saved depth and conserved-volume arrays.
void	clear_reset_forcings () noexcept
	Clear RESET forcings after each step.
void	update_statistics (const std::vector< double > &tri_area, double dt, int nthreads=1) noexcept
	Update cumulative statistics / rendering envelopes.

Public Attributes
const BoundaryData *	boundary = nullptr
const NodeData *	nodes_1d = nullptr
const std::vector< double > *	node_row_conc = nullptr
const std::vector< CouplingPoint > *	node_coupling = nullptr
const std::vector< double > *	node_pond_base = nullptr
const std::vector< int > *	coupling_head_cells = nullptr
const std::vector< double > *	node_pond_area_m2 = nullptr
double	coupling_window_s = 0.0
SurfaceTransportState	transport
MeshHeatState	heat
std::vector< double >	depth
	Mean wetted depth h̄ = V/A_wet (m) [reconstructed].
std::vector< double >	head
	Free-surface elevation η (m) [reconstructed].
std::vector< double >	volume
	Cell water volume V (m³) — the integrated state.
std::vector< double >	grad_hx
	∂h/∂x (unlimited gradient)
std::vector< double >	grad_hy
	∂h/∂y (unlimited gradient)
std::vector< double >	grad_hx_lim
	Limited gradient X.
std::vector< double >	grad_hy_lim
	Limited gradient Y.
std::vector< double >	vert_head
	Head reconstructed at vertices.
std::vector< double >	vert_depth_signed
std::vector< double >	face_vx
	Cell velocity X component (m/s)
std::vector< double >	face_vy
	Cell velocity Y component (m/s)
std::vector< double >	cell_continuity_err
std::vector< double >	edge_flux
	Normal flux through each edge.
surface::MeshSnow	snow
SimulationContext *	snow_context = nullptr
std::vector< double >	snow_catch
std::vector< double >	rainfall
	Raw precipitation intensity (m/s)
std::vector< double >	evap_rate
	Evaporation demand rate (m/s, >= 0)
std::vector< double >	infil_rate
std::vector< double >	infil_applied
std::vector< double >	coupling_flux
	Exchange with SWMM node (m/s, + = into 2D)
std::vector< double >	coupling_applied
std::vector< int >	boundary_receipt_slots
	padded edge slot for each transfer entry
std::vector< double >	boundary_in_applied
std::vector< double >	boundary_out_applied
std::vector< double >	boundary_requested
	signed cumulative request pending receipt drain
std::vector< double >	boundary_last_flow
	last applied substep flow (m³/s)
std::vector< double >	boundary_last_dt
	last boundary substep duration (s)
std::vector< double >	net_source
	Net source/sink per cell (m/s)
std::vector< int8_t >	rainfall_forced
	0=computed, 1=override, 2=add
std::vector< int8_t >	rainfall_persist
	0=reset, 1=persist
std::vector< double >	rainfall_force_val
	Forced rainfall value.
std::vector< int8_t >	evap_forced
	0=computed, 1=override, 2=add
std::vector< int8_t >	evap_persist
	0=reset, 1=persist
std::vector< double >	evap_force_val
	Forced evaporation value.
std::vector< int8_t >	coupling_forced
	0=computed, 1=override, 2=add
std::vector< int8_t >	coupling_persist
	0=reset, 1=persist
std::vector< double >	coupling_force_val
	Forced coupling value.
RuntimeSources	runtime_sources
RuntimeForcings	runtime_forcings
std::vector< double >	coupling_native
bool	forcing_dirty = false
bool	forcing_ever_set = false
std::vector< double >	old_depth
	Mean depth at start of coupling interval.
std::vector< double >	old_volume
	Volume at start of coupling interval (m³)
std::vector< double >	stat_max_depth
	Maximum depth ψ_o seen at each cell (m)
std::vector< double >	stat_max_velocity
	Max cell speed |v| = √(vx²+vy²) (m/s)
std::vector< double >	stat_max_cont_err
	Max |cell_continuity_err| (m³/s)
std::vector< double >	stat_cum_volume
	Cumulative volume through cell (m³)
double	evap_loss_total = 0.0
std::vector< double >	rk2_rain_pending

Member Function Documentation

clear_reset_forcings()

void openswmm::twoD::SurfaceStateData::clear_reset_forcings ( )

inlinenoexcept

Clear RESET forcings after each step.

Postcondition

If forcing_ever_set is false, no-op. Otherwise disables rainfall/evaporation/coupling one-shot rows with zero persistence, zeroes their values and marks forcing_dirty when anything changed. Persistent rows and provider runtime registries are untouched.

Precondition

All one-shot forcing vectors have matching cell extents. Requires exclusive between-step access; no allocation or expiry/time advancement.

exposedEvaporation()

double openswmm::twoD::SurfaceStateData::exposedEvaporation ( int i ) const

inline

Resolve atmospheric evaporation demand over the snow-exposed surface.

Parameters

[in]

i

Valid zero-based mesh cell; evaporation/snow/runtime arrays are sized.

Returns

Runtime-resolved channel-2 demand in m/s times snow exposed fraction when snow owns the cell, otherwise the full demand.

Note

Read-only demand, not actual extracted water. Does not clamp negatives, apply expiry or mutate ledgers; caller supplies stable initialized owner state.

liquidRainfall()

double openswmm::twoD::SurfaceStateData::liquidRainfall ( int i ) const

inline

Resolve the liquid-water precipitation source for one cell.

Parameters

[in]

i

Valid zero-based mesh cell; rainfall and snow/runtime gather arrays must be sized.

Returns

Liquid rate in m/s: snow-owned cells use the snow process's liquid output, otherwise runtime channel 1 resolves against raw rainfall.

Note

Read-only; does not advance snow, apply forcing expiry, or book precipitation. Caller supplies stable initialized owner state; no allocation/checks.

reset_state()

void openswmm::twoD::SurfaceStateData::reset_state ( )

inlinenoexcept

Restore only the saved depth and conserved-volume arrays.

Precondition

Destinations match old_depth/old_volume extents and copies do not overlap.

Postcondition

Replaces depth m and volume m3 without rebuilding head or any other dependent state. Caller performs any additional rollback/reconstruction. Exclusive access; no allocation/checks.

resize()

void openswmm::twoD::SurfaceStateData::resize ( int n_triangles, int n_vertices )

inline

Reset main surface hydraulic arrays to a new mixed-cell/vertex extent.

Parameters

[in]	n_triangles	Nonnegative target mixed-cell count; historical name includes quads.
[in]	n_vertices	Nonnegative target vertex count.

Postcondition

Zeroes hydraulic state, source arrays, forcing slots, old-state buffers and statistics; clears mesh heat/snow and runtime source/forcing registries. Transport/other externally owned views and forcing summary flags are managed separately by initialization.

Note

Edge arrays use n_triangles*kMaxCellVerts. Allocations may throw after partial reset; all old storage references can be invalidated. Requires exclusive access; no topology/units validation or transactional rollback.

save_state()

void openswmm::twoD::SurfaceStateData::save_state ( )

inlinenoexcept

Save the current depth and conserved-volume arrays for local rollback.

Precondition

old_depth/old_volume are preallocated to matching source extents; copies must not overlap. Requires exclusive state access.

Postcondition

Copies depth (m) and volume (m3) only. Does not save head, momentum, transport, sources, snow, heat or ledgers; no allocation or error status.

update_statistics()

void openswmm::twoD::SurfaceStateData::update_statistics ( const std::vector< double > & tri_area, double dt, int nthreads = 1 )

inlinenoexcept

Update cumulative statistics / rendering envelopes.

Aggregates once per model (routing) step at the accepted end-of-step state. MUST be called after computeFaceVelocity and computeCellContinuity so face_vx/vy and cell_continuity_err hold the accepted values. All envelopes fuse into the single per-cell loop already walked for stat_cum_volume — no extra passes, no sub-step sampling.

Parameters

[in]	tri_area	Compatibility area argument, currently unused; conserved volume is integrated directly.
[in]	dt	Finite nonnegative accepted routing interval in seconds.
[in]	nthreads	Positive OpenMP worker count; 1 serial, ignored without OpenMP.

Postcondition

Updates cumulative depth/speed/absolute-continuity maxima and volume-time integral in m3*s. Statistic/velocity/continuity arrays are preallocated to depth.size(); no bounds checks/allocation.

Note

Read/write only this accepted-state statistics snapshot. Fixed per-cell operation order gives serial-equivalent gathers; caller keeps inputs stable and statistic outputs exclusive while the parallel loop runs.

Member Data Documentation

boundary

const BoundaryData* openswmm::twoD::SurfaceStateData::boundary = nullptr

Non-owning view of the per-edge boundary conditions (owned by SurfaceRouter2D). nullptr ⇒ all boundary edges are no-flux walls (the legacy behaviour, and what the unit-test call sites that build a bare state get). When set, the explicit marcher applies the per-type boundary flux (NORMAL_FLOW / SPECIFIED_STAGE / SPECIFIED_FLOW / RATING_CURVE). The pointer is shallow-copied on assignment (it references config, not per-cell state), which is fine — both copies see the same BC config.

boundary_in_applied

std::vector<double> openswmm::twoD::SurfaceStateData::boundary_in_applied

boundary_last_dt

std::vector<double> openswmm::twoD::SurfaceStateData::boundary_last_dt

last boundary substep duration (s)

boundary_last_flow

std::vector<double> openswmm::twoD::SurfaceStateData::boundary_last_flow

last applied substep flow (m³/s)

boundary_out_applied

std::vector<double> openswmm::twoD::SurfaceStateData::boundary_out_applied

boundary_receipt_slots

std::vector<int> openswmm::twoD::SurfaceStateData::boundary_receipt_slots

padded edge slot for each transfer entry

boundary_requested

std::vector<double> openswmm::twoD::SurfaceStateData::boundary_requested

signed cumulative request pending receipt drain

cell_continuity_err

std::vector<double> openswmm::twoD::SurfaceStateData::cell_continuity_err

coupling_applied

std::vector<double> openswmm::twoD::SurfaceStateData::coupling_applied

SIGNED per-cell coupling exchange VOLUME (m³) accumulated since the last mass-balance read, then zeroed by it. Positive = water arrived in this cell from the 1D node (spill / outfall discharge); negative = water was abstracted from this cell into the node (drain).

Signed on purpose, and per cell on purpose. The domain totals (MassBalance2D::coupling_1d_to_2d_in / coupling_2d_to_1d_out) are two unsigned accumulators and cannot answer "what did THIS cell give or take", which is the question asked of a coupling point that flip-flops within a batch: the two directions cancel in the net and both are invisible in the totals. coupling_flux is a rate that is overwritten every step, so it cannot answer it either.

Booked at the SAME dt and the same share the marcher applied, exactly like infil_applied above and for the same reason — re-deriving it from end-of-step state is first-order and under-books the cells that dried mid-step.

coupling_flux

std::vector<double> openswmm::twoD::SurfaceStateData::coupling_flux

Exchange with SWMM node (m/s, + = into 2D)

coupling_force_val

std::vector<double> openswmm::twoD::SurfaceStateData::coupling_force_val

Forced coupling value.

coupling_forced

std::vector<int8_t> openswmm::twoD::SurfaceStateData::coupling_forced

0=computed, 1=override, 2=add

coupling_head_cells

const std::vector<int>* openswmm::twoD::SurfaceStateData::coupling_head_cells = nullptr

Head-sampling cell lists of the coupling points (COUPLING_HEAD VERTEX / STENCIL_WET_MEAN), indexed by CouplingPoint::head_begin/head_end.

coupling_native

std::vector<double> openswmm::twoD::SurfaceStateData::coupling_native

coupling_persist

std::vector<int8_t> openswmm::twoD::SurfaceStateData::coupling_persist

0=reset, 1=persist

coupling_window_s

double openswmm::twoD::SurfaceStateData::coupling_window_s = 0.0

depth

std::vector<double> openswmm::twoD::SurfaceStateData::depth

Mean wetted depth h̄ = V/A_wet (m) [reconstructed].

edge_flux

std::vector<double> openswmm::twoD::SurfaceStateData::edge_flux

Normal flux through each edge.

evap_force_val

std::vector<double> openswmm::twoD::SurfaceStateData::evap_force_val

Forced evaporation value.

evap_forced

std::vector<int8_t> openswmm::twoD::SurfaceStateData::evap_forced

0=computed, 1=override, 2=add

evap_loss_total

double openswmm::twoD::SurfaceStateData::evap_loss_total = 0.0

Cumulative evaporation loss over the whole simulation (m³). Kept here (not in core's MassBalance2D, owned by another work stream) and folded into the API-level totals by Api2D.cpp.

evap_persist

std::vector<int8_t> openswmm::twoD::SurfaceStateData::evap_persist

0=reset, 1=persist

evap_rate

std::vector<double> openswmm::twoD::SurfaceStateData::evap_rate

Evaporation demand rate (m/s, >= 0)

face_vx

std::vector<double> openswmm::twoD::SurfaceStateData::face_vx

Cell velocity X component (m/s)

face_vy

std::vector<double> openswmm::twoD::SurfaceStateData::face_vy

Cell velocity Y component (m/s)

forcing_dirty

bool openswmm::twoD::SurfaceStateData::forcing_dirty = false

forcing_ever_set

bool openswmm::twoD::SurfaceStateData::forcing_ever_set = false

Sticky companion to forcing_dirty: set by the forcing API the first time any prescription is written, never cleared. clear_reset_forcings() is called once per routing step and is O(n_cells); on a model that never uses the forcing API (every deck without an external controller) the whole sweep is dead work, and this flag skips it.

grad_hx

std::vector<double> openswmm::twoD::SurfaceStateData::grad_hx

∂h/∂x (unlimited gradient)

grad_hx_lim

std::vector<double> openswmm::twoD::SurfaceStateData::grad_hx_lim

Limited gradient X.

grad_hy

std::vector<double> openswmm::twoD::SurfaceStateData::grad_hy

∂h/∂y (unlimited gradient)

grad_hy_lim

std::vector<double> openswmm::twoD::SurfaceStateData::grad_hy_lim

Limited gradient Y.

head

std::vector<double> openswmm::twoD::SurfaceStateData::head

Free-surface elevation η (m) [reconstructed].

heat

MeshHeatState openswmm::twoD::SurfaceStateData::heat

infil_applied

std::vector<double> openswmm::twoD::SurfaceStateData::infil_applied

Infiltration APPLIED depth (m) accumulated since the last mass-balance read, then zeroed by it. Every site that integrates the infiltration sink into volume adds infilSink(...) * dt here with the SAME depth and the SAME dt it used, so the ledger books what the marcher actually removed. Re-deriving the loss from the accepted end-of-step depth is only first-order: a cell that dries mid-step is sunk at the higher early-step rate but re-derived at the ramped end-of-step rate, and the lazy tier integrates a stale depth across a whole sync interval. Both leave storage falling by more than the ledger books.

infil_rate

std::vector<double> openswmm::twoD::SurfaceStateData::infil_rate

Infiltration loss rate (m/s, >= 0) — a HELD rate (plan §5.5.2, D-I1): Infil2D::updateRates republishes it on the INFIL_STEP cadence and it is held constant in between, exactly as rainfall is. The marcher NEVER evaluates an infiltration kernel per substep; it only consumes this array through infilSink(), so infiltration has no interaction with the LTS tiering or active set. All-zero when no [2D_INFILTRATION*] rows resolved — the bitwise-regression fast path (gate I7).

net_source

std::vector<double> openswmm::twoD::SurfaceStateData::net_source

Net source/sink per cell (m/s)

node_coupling

const std::vector<CouplingPoint>* openswmm::twoD::SurfaceStateData::node_coupling = nullptr

non-outfall points

node_pond_area_m2

const std::vector<double>* openswmm::twoD::SurfaceStateData::node_pond_area_m2 = nullptr

COUPLING_EQUALIZE inputs, published by the router before each advance: every coupled node's 1D surface area (m²) and the advance window (s) over which the 1D heads are held.

node_pond_base

const std::vector<double>* openswmm::twoD::SurfaceStateData::node_pond_base = nullptr

Per-node volume (1D ft³) at which a coupled node's pond starts: what the active 1D router books at the rim — rpt_full_volume under DW (0 for a plain junction), full_volume otherwise (FV holds MIN_SURFAREA × full depth below the pond). A 1D→2D spill may only draw volume above it. Null falls back to full_volume.

node_row_conc

const std::vector<double>* openswmm::twoD::SurfaceStateData::node_row_conc = nullptr

S4: the 1D nodes' PUBLISHED row values, [node * n_species + s] in the 2D transport row order (pollutant conc, MSX conc, age, temperature), assembled by the router before each advance and frozen for the batch. What a 1D→2D spill or outfall discharge arrives at.

nodes_1d

const NodeData* openswmm::twoD::SurfaceStateData::nodes_1d = nullptr

Live node-coupling view, set by SurfaceRouter2D. The marcher evaluates the 1D↔2D orifice exchange per substep against the CURRENT 2D head (so it self-limits) and accumulates the exact ∫Q dt per point. nodes_1d is the 1D node data, frozen for the duration of the batch.

old_depth

std::vector<double> openswmm::twoD::SurfaceStateData::old_depth

Mean depth at start of coupling interval.

old_volume

std::vector<double> openswmm::twoD::SurfaceStateData::old_volume

Volume at start of coupling interval (m³)

rainfall

std::vector<double> openswmm::twoD::SurfaceStateData::rainfall

Raw precipitation intensity (m/s)

rainfall_force_val

std::vector<double> openswmm::twoD::SurfaceStateData::rainfall_force_val

Forced rainfall value.

rainfall_forced

std::vector<int8_t> openswmm::twoD::SurfaceStateData::rainfall_forced

0=computed, 1=override, 2=add

rainfall_persist

std::vector<int8_t> openswmm::twoD::SurfaceStateData::rainfall_persist

0=reset, 1=persist

rk2_rain_pending

std::vector<double> openswmm::twoD::SurfaceStateData::rk2_rain_pending

Accepted RK2 rainfall awaiting one router/report consumption (m3/cell). Empty preserves the historical no-runtime-forcing profile.

runtime_forcings

RuntimeForcings openswmm::twoD::SurfaceStateData::runtime_forcings

runtime_sources

RuntimeSources openswmm::twoD::SurfaceStateData::runtime_sources

Set by the forcing API and by clear_reset_forcings() when any flag changes; consumed by the co-advance to bypass its coarse (30 s) forcing-refresh cadence, so a one-shot (RESET) prescription applies on the very next step and expires on the step after — the per-step semantics the swmm_2d_force_* API documents.

snow

surface::MeshSnow openswmm::twoD::SurfaceStateData::snow

snow_catch

std::vector<double> openswmm::twoD::SurfaceStateData::snow_catch

snow_context

SimulationContext* openswmm::twoD::SurfaceStateData::snow_context = nullptr

stat_cum_volume

std::vector<double> openswmm::twoD::SurfaceStateData::stat_cum_volume

Cumulative volume through cell (m³)

stat_max_cont_err

std::vector<double> openswmm::twoD::SurfaceStateData::stat_max_cont_err

Max |cell_continuity_err| (m³/s)

stat_max_depth

std::vector<double> openswmm::twoD::SurfaceStateData::stat_max_depth

Maximum depth ψ_o seen at each cell (m)

stat_max_velocity

std::vector<double> openswmm::twoD::SurfaceStateData::stat_max_velocity

Max cell speed |v| = √(vx²+vy²) (m/s)

transport

SurfaceTransportState openswmm::twoD::SurfaceStateData::transport

S1 — overland species transport. transport.active() is false (and every marcher species branch is skipped) unless the router sized it, so a hydrodynamics-only model pays one predicate per firing and is otherwise untouched. Embedded rather than pointed-to: it is per-cell STATE, sized with volume, and it is copied when the state is.

vert_depth_signed

std::vector<double> openswmm::twoD::SurfaceStateData::vert_depth_signed

Render/output-only SIGNED vertex depth η_v − z_v (m) — wet-masked, depth-weighted reconstruction (reconstructVertexRenderDepths). Unlike vert_head, dry-cell bed elevations never contribute, and a wet cell votes only where its η reaches the corner (wetted-contact gate), so this field is safe to interpolate for the water surface. Emitted values are strictly positive or the 0 no-data sentinel (no qualifying incident cell); negatives appear only in files from older engines — readers stay negative-tolerant. NOT used by the solver.

vert_head

std::vector<double> openswmm::twoD::SurfaceStateData::vert_head

Head reconstructed at vertices.

volume

std::vector<double> openswmm::twoD::SurfaceStateData::volume

Cell water volume V (m³) — the integrated state.

---

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

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