openswmm::twoD::OutfallExchange Class Reference

#include <OutfallExchange.hpp>

Collaboration diagram for openswmm::twoD::OutfallExchange:

Public Member Functions
void	initialize (const MeshData &, const std::vector< CouplingPoint > &, SimulationContext &)
	Build outfall donor partitions, optional spread receivers and native link-limit storage.
void	prepare (const MeshData &, const SurfaceStateData &, const SolverOptions2D &, SimulationContext &, double dt)
	Reserve each outfall's disjoint share of frozen surface water for one routing step.
bool	apply (const MeshData &, SurfaceStateData &, const SolverOptions2D &, SimulationContext &, double dt, std::vector< double > &accumulated, const std::vector< double > *node_conc=nullptr, std::vector< double > *cell_accumulated=nullptr)
	Apply completed routed outfall water and donor-paired species to canonical surface cells.
void	recordTailwater (const SimulationContext &, double dt)
	Accumulate distinct outfall tailwater engagement and crown-submergence diagnostics.
bool	tailwater (int node, double &engaged_s, double &submerged_s, double &max_stage) const
	A coupled outfall's tailwater record for the report: seconds with the 2D tailwater engaged / above the outlet crown, and the highest engaged stage (1D length; -1e30 if never engaged). False for an uncoupled node.

Friends
class	SurfaceRouter2D

Member Function Documentation

apply()

bool openswmm::twoD::OutfallExchange::apply	(	const MeshData &	mesh,
		SurfaceStateData &	state,
		const SolverOptions2D &	opts,
		SimulationContext &	ctx,
		double	dt,
		std::vector< double > &	accumulated,
		const std::vector< double > *	node_conc = nullptr,
		std::vector< double > *	cell_accumulated = nullptr )

Apply completed routed outfall water and donor-paired species to canonical surface cells.

Parameters

[in]	mesh	Prepared SI geometry and reconstruction topology.
[in,out]	state	Matching canonical water/native transport and coupling/runoff ledgers. Updates volume, head/depth, signed coupling_applied, native mass and gained/lost_coupling.
[in]	opts	Positive native-to-SI flow conversion and wet threshold for SPREAD selection.
[in,out]	ctx	Completed native node inflow/outflow, surface_outfall_quality incoming native water/mass queues and 2D mass balance. Negative exchange carries actual surface composition to 1D.
[in]	dt	Finite positive routed duration s, matching the intended prepared reservation window; this function does not validate prepared_ or duration equality itself.
[in,out]	accumulated	At least original cps.size() entries; adds accepted signed source-positive m3 at original point indices, retaining existing values.
[in]	node_conc	Optional borrowed node-major [node*n_species+species] native composition for positive 1D discharge. Missing tuple elements contribute zero mass; null leaves species unchanged.
[in,out]	cell_accumulated	Optional mesh-sized signed m3 receipt vector, incremented per cell; extents are unchecked and it must not alias active owner vectors.

Returns

True when any nonzero point exchange was applied; false otherwise. Clears prepared_ after normal completion, expiring unused reservations without resetting diagnostic donor totals.

Exceptions

std::runtime_error

Routed withdrawal exceeds point/node reservation, overlaps overspend current cell water, or no positive distribution weight exists.

Note

Positive discharge spreads by area over qualified cells; withdrawals use prepared donor shares. Books gross step direction before later netting and pending per-cell receipts. Allocation or a later refusal can follow earlier canonical/quality/ledger updates; no whole-call rollback. Requires initialize/prepare at correct routing cadence and exclusive coupled-owner access.

Here is the call graph for this function:

initialize()

void openswmm::twoD::OutfallExchange::initialize	(	const MeshData &	mesh,
		const std::vector< CouplingPoint > &	cps,
		SimulationContext &	ctx )

Build outfall donor partitions, optional spread receivers and native link-limit storage.

Parameters

[in]	mesh	Prepared SI mesh with valid stencils, neighbors, areas and coupling coordinates.
[in]	cps	Stable resolved coupling order, with valid outfall node/cell/vertex indices.
[in,out]	ctx	Prepared engine graph. Clears/replaces surface_outfall_link_limit; incident links determine equal conservative per-link withdrawal shares.

Exceptions

std::runtime_error	An outfall has no donor cells or no incident hydraulic link.
std::out_of_range	Some invalid resolved cell/node indices hit guarded vector accesses; other geometry indices are unchecked and must already be valid.

Note

Clears prior reservations/window/tailwater state, builds each point's 1/users(cell) donor shares and radius-connected SPREAD set, then initializes native limits to infinity. Allocations can throw after partial reset. Does not transfer water or quality. Requires exclusive context/owner access and matching topology for all future prepare/apply calls.

Here is the call graph for this function:

prepare()

void openswmm::twoD::OutfallExchange::prepare	(	const MeshData &	,
		const SurfaceStateData &	state,
		const SolverOptions2D &	opts,
		SimulationContext &	ctx,
		double	dt )

Reserve each outfall's disjoint share of frozen surface water for one routing step.

Parameters

[in]	state	Prepared nonnegative SI cell volumes, read only.
[in]	opts	Positive finite flow_1d_to_2d conversion from native flow to m3/s.
[in,out]	ctx	Receives aggregate-per-barrel native flow limits per coupled outfall node.
[in]	dt	Finite positive step s; nonpositive/NaN returns leaving prior reservation state.

Note

Mesh reference is a retained unused interface argument. Replaces per-point/per-node volume reservations from max(0,state.volume), sets prepared interval/flag when points exist, and divides withdrawal rate across incident links. Does not remove water or reserve native mass separately. Requires initialized shapes and exclusive owner/context access; no allocation or global rollback.

recordTailwater()

void openswmm::twoD::OutfallExchange::recordTailwater	(	const SimulationContext &	ctx,
		double	dt )

Accumulate distinct outfall tailwater engagement and crown-submergence diagnostics.

Book one routing step of each coupled outfall's tailwater (after updateOutfallBoundaries cached it): time the override is engaged, time the outlet crown is drowned, and the highest engaged stage.

Parameters

[in]	ctx	Prepared outfall subtype/cache arrays and native node invert/full depth.
[in]	dt	Finite positive routed duration s; nonpositive/NaN returns.

Note

Adds engagement when ramp>0 and cached stage exceeds invert; adds submerged duration when stage reaches crown, and updates maximum native length. Multiple points share one distinct-node record. Does not apply boundary stage or water; requires matching stable identity/exclusive counters.

Here is the call graph for this function:

tailwater()

bool openswmm::twoD::OutfallExchange::tailwater	(	int	node,
		double &	engaged_s,
		double &	submerged_s,
		double &	max_stage ) const

A coupled outfall's tailwater record for the report: seconds with the 2D tailwater engaged / above the outlet crown, and the highest engaged stage (1D length; -1e30 if never engaged). False for an uncoupled node.

Parameters

[in]	node	Zero-based original 1D node ID; unmapped returns false.
[out]	engaged_s	Cumulative engaged duration s on true.
[out]	submerged_s	Cumulative crown-submerged duration s on true.
[out]	max_stage	Maximum engaged native 1D stage, -1e30 sentinel if never engaged.

Returns

True after copying all three records for a mapped node. False leaves outputs unchanged. Read-only and allocation-free; caller preserves matching initialized arrays and serializes updates.

Friends And Related Symbol Documentation

SurfaceRouter2D

friend class SurfaceRouter2D

friend

---

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

• /home/runner/work/openswmm.engine/openswmm.engine/src/engine/2d/coupling/OutfallExchange.hpp
• /home/runner/work/openswmm.engine/openswmm.engine/src/engine/2d/coupling/OutfallExchange.cpp