openswmm::twoD::SurfaceRouter2D Class Reference

Top-level orchestrator for the 2D surface routing module. More...

#include <SurfaceRouter2D.hpp>

Collaboration diagram for openswmm::twoD::SurfaceRouter2D:

Classes
struct	RestartState

Public Types
using	PendingBoundaryRow = twoD::PendingBoundaryRow
	Per-row buffer for [2D_BOUNDARY_CONDITIONS] parse output.
using	PendingInitialQualityRow = twoD::PendingInitialQualityRow
using	PendingInitialBedQualityRow = twoD::PendingInitialBedQualityRow
using	PendingBoundaryQualityRow = twoD::PendingBoundaryQualityRow
using	PendingEdgeConveyanceRow = twoD::PendingEdgeConveyanceRow
	Per-row buffer for [2D_EDGE_CONVEYANCE] parse output (§11A).

Public Member Functions
	SurfaceRouter2D ()=default
	Create an inactive authoring router with empty owned physical/source state.
	~SurfaceRouter2D ()=default
	Destroy owned router members and release solver/plugin resources.
	SurfaceRouter2D (const SurfaceRouter2D &)=delete
SurfaceRouter2D &	operator= (const SurfaceRouter2D &)=delete
	SurfaceRouter2D (SurfaceRouter2D &&)=default
	Move owned router members using their ordinary default move operations.
SurfaceRouter2D &	operator= (SurfaceRouter2D &&)=default
	Replace owned router members by default move assignment.
void	initialize (SimulationContext &ctx)
	Initialize the 2D module after input parsing is complete.
void	initializeChannelGround (SimulationContext &ctx)
	Bind selected finite channel contacts after 1D heat state is seeded.
const ChannelGroundState &	channelGround () const noexcept
	Borrow the shared finite channel/physical-soil thermal contact owner and cumulative J/native receipts.
ChannelGroundState &	channelGround () noexcept
	Borrow the shared finite channel/physical-soil thermal contact owner and cumulative J/native receipts.
void	setCommonSourceStage (SimulationContext &ctx, CommonSourceStage &stage)
	Internal qualification hook: externally owned stage, all cells managed, wall boundaries, no live 1D exchanges. Does not activate authored ownership.
void	setJointSourceStage (SimulationContext &ctx, CommonSourceStage &stage, Router &hydraulic)
	Internal water-only joint DW/source checkpoint, including non-outfall surface exchange and pending node delivery. Attach after both routers and LID initialization; the hydraulic router must track accepted steps. External providers, node beds and whole-engine/output state remain excluded.
void	setSourceResultHistory (SourceResultHistory &history)
	Attach a fresh borrowed accepted-source history recorder through the CPU source marcher.
void	resumeSourceResultHistory (SourceResultHistory &history)
	Resume a saved accepted-source recorder prefix at a completed router boundary.
std::string	saveCheckpoint (const SimulationContext &ctx, const std::string &path) const
	Internal router/CPU/source boundary; not a full-project hotstart.
std::string	loadCheckpoint (SimulationContext &ctx, const std::string &path)
	Read and stage a router component checkpoint into fresh matching attached owners.
void	step (SimulationContext &ctx, double dt, double t)
	Advance the 2D surface routing by one SWMM routing step.
void	updateOutfallsPreRouting (SimulationContext &ctx, double dt=0.0)
	Pre-routing hook: update outfall boundaries from 2D surface heads.
void	advancePostRouting (SimulationContext &ctx, double dt, double t)
	Post-routing hook: compute coupling exchange and advance 2D solver.
void	prepareOneShotForcing (SimulationContext &ctx)
	Prepare a RESET 2D forcing to apply on the next routing step.
void	flushPendingBatch (SimulationContext &ctx)
	Flush the pending (partial) sync batch, if any.
double	reportWeight (double report_ms) const noexcept
	Report-time interpolation weight for the 2D snapshot blend: f = (report_ms − window_old_ms)/(window_new_ms − window_old_ms), clamped to [0,1]; returns 1.0 (pure current state) when no batch has crossed a report instant yet. Unlike the 1D weight there is no legacy bit pattern to reproduce, so the clamp simply absorbs ulp-level clock skew between the router's and the engine's ms accumulators.
void	bookGageRates (const SimulationContext &ctx, double runoff_start_s)
	Book the gage rates a runoff step starting at runoff_start_s (seconds since the run start) takes, after the monthly adjustment. The 2D integrates these piecewise-constant rates over each of its own windows, so a cell receives exactly the gage depth the subcatchments do over the same interval.
void	reportRainfall (const SimulationContext &ctx, double report_date, std::vector< double > &out) const
	Per-cell rainfall (m/s) as the .out reports subcatchment rainfall: the source gage rate at report_date, independent of runoff cursor, mapped through RAINFALL_MODE, with the per-cell rainfall forcings applied.
const std::vector< double > &	reportRainCumulative (double report_ms) const noexcept
	Rainfall volume (m³) integrated to the report boundary, excluding the part of a routing/sync window after that boundary. Runtime totals remain available through rainCumulative().
const std::vector< double > &	reportOldDepth () const noexcept
	Cell depth (m) at the start of the sync batch that crossed the current report instant (meaningful when reportWeight() < 1).
const std::vector< double > &	reportOldHead () const noexcept
	Cell head (m) at the start of that batch.
void	finalize (SimulationContext &ctx)
	Finalize the 2D module at simulation end.
bool	isActive () const noexcept
	Check if the 2D module is active.
void	prepareLidStep (SimulationContext &, double dt, double evaporation)
	Prepare the next finite Richards LID/mesh acceptance and conduit donor budgets.
const std::vector< std::string > &	threadWarnings () const noexcept
	Thread-count advisories produced by initialize() (THREADS above the machine limits, triangle gate reducing an explicit request). The engine forwards them to the report warnings and the host warning callback.
void	computeCouplingConductances (const SimulationContext &ctx, std::vector< std::pair< int, double > > &out) const
	Windowless-coupling stabilizer: per coupled node, the exchange head sensitivity G = Σ_points −∂Q/∂h_1d ≥ 0 converted to 1D units (ft³/s per ft), for the caller to add into the dynamic-wave sumdqdh each Picard iteration. Appends (node_idx, G) pairs; cheap (O(points)).
void	prepareForEdit ()
	Make the parsed mesh editable without a full initialize().
const MeshData &	mesh () const noexcept
	Access mesh data (read-only).
MeshData &	mesh () noexcept
	Access mesh data (mutable, for input parsing).
const SurfaceStateData &	state () const noexcept
	Access surface state (read-only).
SurfaceStateData &	state () noexcept
	Access surface state (mutable, for forcing).
double	surfaceReactionLoss (int row) const noexcept
	Signed native surface reaction loss for the qualified RK2 owner.
const SolverOptions2D &	options () const noexcept
	Access solver options (read-only).
SolverOptions2D &	options () noexcept
	Access solver options (mutable).
const BoundaryData &	boundary () const noexcept
	Access per-edge boundary-condition data (read-only).
BoundaryData &	boundary () noexcept
	Access per-edge boundary-condition data (mutable, for forcing/parsing).
bool	runtimeCpuAvailable () const noexcept
	Announce that a boundary slot's TYPE changed (the API BC-type setter), so the compact non-WALL slot list the per-step boundary passes walk is rebuilt before it is next used.
RuntimeSources &	runtimeSources () noexcept
	Borrow mutable runtime prescriptions/receipts for the surface owner.
bool	commonSourceAttached () const noexcept
	Test whether an external common-source stage pointer is attached.
const CommonSourceStage *	commonSourceStage () const noexcept
	Borrow the externally attached common-source stage, if any.
bool	runtimeWaterCheckpointing () const noexcept
	Test qualification ownership for managed runtime water checkpointing.
bool	runtimeBoundaryCheckpointing () const noexcept
	Test whether the attached common source owns runtime boundary checkpointing.
bool	outfallTailwaterCheckpointing () const noexcept
	Joint checkpoints of a model with coupled outfalls carry each one's tailwater record — a distinct checkpoint version.
const OutfallExchange &	outfallExchange () const noexcept
	Coupled-outfall delivery and tailwater records (report).
std::string	validateRuntimeWater (const RuntimeSources &, const RuntimeSources &, const RuntimeForcings &, double time, const BoundaryData *boundary=nullptr) const
	Validate copied runtime water proposals through the attached common-source owner.
bool	runtimeActive () const noexcept
	Test whether any runtime surface/aquifer source, boundary override or forcing is retained.
double	nextRuntimeTime (double now) const noexcept
	Read the earliest scheduled source/forcing transition after a given time.
void	expireRuntime (double now)
	Retire all runtime source and forcing entries at an accepted completed horizon.
void	invalidateBoundaryIndex ()
	Mark the compact non-wall boundary index stale and refresh attached CPU boundary work lists.
void	invalidateBoundaryNames () noexcept
	Mark symbolic boundary names unresolved after authoring/name changes.
void	refreshRenderFieldsIfStale ()
	Bring the render fields (face velocity, vertex heads, output gradients, vertex render depths) up to date with the current solver state if a batch has run since they were last computed. The API getters that expose those fields call this so a reader arriving between reports is never served a stale field; it is a no-op at a report instant, where the refresh already ran.
Infil2D &	infil () noexcept
	Access the per-cell infiltration model (plan §5.5, track I).
const Infil2D &	infil () const noexcept
	Borrow the owned per-cell infiltration authoring, held capacity and model memory.
GwTransportData &	gwTransport () noexcept
	U4 (2026-09-07): the [GW_*] subsurface-transport authoring rows. Reached by the parser, the writer and the C API through SimulationContext::twod_io.gw; resolved owners consume them during initialization.
const GwTransportData &	gwTransport () const noexcept
	Borrow the owned groundwater quality/thermal/source authoring and resolved SI transport metadata.
SurfaceQuality2D &	surfaceQuality () noexcept
	S7: cell coverages / buildup / washoff / sweeping (authoring + state).
const SurfaceQuality2D &	surfaceQuality () const noexcept
	Borrow the owned land-use coverage/buildup/washoff/sweeping authoring and runtime ledgers.
SubsurfaceConfig &	aquiferConfig () noexcept
	G1: the authored [2D_AQUIFER*] rows, in the user's own units. Reached by the section handlers and the InpWriter through SimulationContext::twod_io.aquifer.
const SubsurfaceConfig &	aquiferConfig () const noexcept
	Borrow the owned aquifer authoring rows, retained in project input units.
std::vector< std::string > &	aquiferNodeNames () noexcept
	Borrow the owned node names parallel to aquiferConfig().node_beds authoring identity.
const std::vector< std::string > &	aquiferNodeNames () const noexcept
	Borrow the owned node names parallel to aquiferConfig().node_beds authoring identity.
std::vector< std::string > &	aquiferLinkNames () noexcept
	G-X4: the [2D_AQUIFER_LINKS] row names, parallel to aquiferConfig().link_rows — the writer's round-trip key.
const std::vector< std::string > &	aquiferLinkNames () const noexcept
	Borrow the owned conduit names parallel to aquiferConfig().link_rows authoring identity.
SubsurfaceSolver &	subsurface () noexcept
	The running kernel. active() is false until [2D_AQUIFER] resolves.
const SubsurfaceSolver &	subsurface () const noexcept
	Borrow the owned groundwater solver with SI hydraulic state, native rows and paired physical/source/LID receipts.
const std::vector< double > &	subcatchRecharge () const noexcept
	Ledger-consistent cumulative infiltrated depth per cell (m).
void	drainSubcatchRecharge (std::vector< double > &out)
	Move the pending recharge into out (m³ per subcatchment) and zero the accumulator. out is sized to the accumulator (empty when the destination is not in use).
const std::vector< int > &	cellSubcatchment () const noexcept
	Cell → containing subcatchment index (-1 = none). Empty unless the SUBCATCH_AQUIFER destination resolved.
double	infiltrationElapsed () const noexcept
	Read elapsed duration since the last held infiltration model rate refresh.
void	restoreInfiltration (const std::vector< double > &cumulative, double elapsed)
	Replace router applied-infiltration reporting and held-model elapsed accounting.
const std::vector< double > &	infilCumulative () const noexcept
	Borrow actually applied cumulative infiltration depth.
const std::vector< double > &	couplingCumulative () const noexcept
	Signed cumulative coupling exchange per cell (m³).
const std::vector< double > &	rainCumulative () const noexcept
	Ledger-consistent cumulative rainfall volume per cell (m³).
const RainfallInterpolator &	rainfallInterpolator () const noexcept
	Static rainfall weights built at initialize() (diagnostic inspection).
std::vector< PendingInitialQualityRow > &	pendingInitialQualityRows () noexcept
	S1/S2: raw [2D_INITIAL_QUALITY] rows, resolved at initialize().
std::vector< PendingInitialBedQualityRow > &	pendingInitialBedQualityRows () noexcept
	Borrow retained local-bed initial native quality authoring rows.
std::vector< PendingBoundaryQualityRow > &	pendingBoundaryQualityRows () noexcept
	Borrow retained boundary native quality authoring rows.
std::vector< PendingBoundaryRow > &	pendingBCRows () noexcept
	Borrow retained hydraulic boundary authoring rows.
const std::vector< PendingBoundaryRow > &	pendingBCRows () const noexcept
	Borrow retained hydraulic boundary authoring rows.
std::vector< PendingEdgeConveyanceRow > &	pendingEdgeConveyanceRows () noexcept
	Borrow retained interior/exterior edge conveyance authoring rows.
const std::vector< PendingEdgeConveyanceRow > &	pendingEdgeConveyanceRows () const noexcept
	Borrow retained interior/exterior edge conveyance authoring rows.
double	totalVolume () const
	Get total 2D surface volume (sum of depth * area).
double	totalExchangeFlow () const
	Get total exchange flow (sum of coupling flows, m³/s).
long	lastSolverSteps () const
	Read the last surface advance's base substep count.
double	lastSolverStepSize () const
	Read the last accepted surface base/tail step duration.
const std::string &	backendName () const noexcept
	Backend label chosen by SurfaceSolverFactory at initialize() ("cpu (explicit marcher)", "omp (…)", …); empty before that.

Friends
class	openswmm::SWMMEngine

Detailed Description

Top-level orchestrator for the 2D surface routing module.

Member Typedef Documentation

PendingBoundaryQualityRow

using openswmm::twoD::SurfaceRouter2D::PendingBoundaryQualityRow = twoD::PendingBoundaryQualityRow

PendingBoundaryRow

using openswmm::twoD::SurfaceRouter2D::PendingBoundaryRow = twoD::PendingBoundaryRow

Per-row buffer for [2D_BOUNDARY_CONDITIONS] parse output.

V-E3. Populated by the input parser during reading (before the mesh is finalized), drained into boundary_ during initialize() after boundary_.resize() allocates the per-edge slots. Retained after the drain so serialization (InpWriter / GeoPackage) can re-emit the authored rows (group label, TS-vs-constant choice). Hoisted to data/PendingRows2D.hpp; alias kept for call sites.

PendingEdgeConveyanceRow

using openswmm::twoD::SurfaceRouter2D::PendingEdgeConveyanceRow = twoD::PendingEdgeConveyanceRow

Per-row buffer for [2D_EDGE_CONVEYANCE] parse output (§11A).

Populated by the input parser during reading (vertices known but mesh topology not yet built), drained into mesh_.edge_conveyance during initialize() after buildMeshTopology has populated the neighbour table. Mirrored to both slots of an interior edge so antisymmetric FV flux integration stays mass-conservative. Retained after the drain for faithful re-serialization.

PendingInitialBedQualityRow

using openswmm::twoD::SurfaceRouter2D::PendingInitialBedQualityRow = twoD::PendingInitialBedQualityRow

PendingInitialQualityRow

using openswmm::twoD::SurfaceRouter2D::PendingInitialQualityRow = twoD::PendingInitialQualityRow

Constructor & Destructor Documentation

SurfaceRouter2D() [1/3]

openswmm::twoD::SurfaceRouter2D::SurfaceRouter2D ( )

default

Create an inactive authoring router with empty owned physical/source state.

Note

No solver/context attachment or physics advance. initialize() resolves a run before routing; member allocation follows ordinary C++ construction.

Here is the caller graph for this function:

~SurfaceRouter2D()

openswmm::twoD::SurfaceRouter2D::~SurfaceRouter2D ( )

default

Destroy owned router members and release solver/plugin resources.

Note

Does not call finalize(ctx) or flush pending physics. Caller finalizes while borrowed contexts/source/history owners remain alive. All router/member views become invalid.

SurfaceRouter2D() [2/3]

openswmm::twoD::SurfaceRouter2D::SurfaceRouter2D ( const SurfaceRouter2D & )

delete

Here is the call graph for this function:

SurfaceRouter2D() [3/3]

openswmm::twoD::SurfaceRouter2D::SurfaceRouter2D ( SurfaceRouter2D && )

default

Move owned router members using their ordinary default move operations.

Note

Source object remains destructible with moved-from containers. Raw borrowed/self-member pointers are copied without automatic rebinding; move only an unattached inactive authoring router, or reinitialize/rebind before routing. Retained member/solver views can become invalid.

Here is the call graph for this function:

Member Function Documentation

advancePostRouting()

void openswmm::twoD::SurfaceRouter2D::advancePostRouting	(	SimulationContext &	ctx,
		double	routing_dt,
		double	t )

Post-routing hook: compute coupling exchange and advance 2D solver.

Consume accepted hydraulic exchange and schedule or execute the pending 2D batch.

Must be called AFTER the 1D routing step.

• Argument ctx: Simulation context.
• Argument dt: SWMM routing timestep (seconds).
• Argument t: Current simulation time (seconds from start).

Consume accepted hydraulic exchange and schedule or execute the pending 2D batch.

• Argument ctx (in,out): Matching accepted native hydraulic/quality state after its routing solve.
• Argument dt (in): Positive finite accepted routing duration s (routing_dt in the definition).
• Argument t (in): Elapsed accepted interval start s, matching sim_time_+pending_dt_ for common sources.

  Note

  Inactive router returns. Common/joint profiles require ready boundary/context/clock and matching pre-routing outfall reservation. Completes LID thermal interval, updates bed clogging, publishes node native values and applies only accepted reserved outfall transfers. Books conduit seepage/native mass into aquifer or gained quality into native end-node receivers, then freezes next two-way budgets. Accumulates pending time and co-advances when sync threshold (or LID heat) requires; source boundary becomes ready after completion. No 1D solve/engine clock increment. Invalid chronology throws std::invalid_argument; physics/owner/allocation can throw after partial receipts, queues and pending-time changes. Do not retry as an idempotent operation; serialize owners.

  Parameters

  [in,out]	ctx	Matching accepted native hydraulic/quality state after its routing solve.
  [in]	routing_dt	Positive finite accepted routing duration s, called dt in the declaration.
  [in]	t	Elapsed accepted interval start s, matching sim_time_+pending_dt_ for common sources.

  Note

  Inactive router returns. Common/joint profiles require ready boundary/context/clock and matching pre-routing outfall reservation. Completes LID thermal interval, updates bed clogging, publishes node native values and applies only accepted reserved outfall transfers. Books conduit seepage/native mass into aquifer or gained quality into native end-node receivers, then freezes next two-way budgets. Accumulates pending time and co-advances when sync threshold (or LID heat) requires; source boundary becomes ready after completion. No 1D solve/engine clock increment. Invalid chronology throws std::invalid_argument; physics/owner/allocation can throw after partial receipts, queues and pending-time changes. Do not retry as an idempotent operation; serialize owners.

Here is the call graph for this function:

Here is the caller graph for this function:

aquiferConfig() [1/2]

const SubsurfaceConfig & openswmm::twoD::SurfaceRouter2D::aquiferConfig ( ) const

inlinenoexcept

Borrow the owned aquifer authoring rows, retained in project input units.

Returns

Reference to this router's member, with mutability determined by the overload. No copy, validation or ownership transfer occurs. Router must remain alive/stable; initialization, restore, move/replacement and vector edits can invalidate contained views.

Note

Mutable access requires exclusive ownership and preservation of prepared topology, row shapes, unit convention, source clocks and receipt phase. Authoring edits may require resolution/rebuild before routing. This getter performs no automatic cache/solver synchronization or physical update.

aquiferConfig() [2/2]

SubsurfaceConfig & openswmm::twoD::SurfaceRouter2D::aquiferConfig ( )

inlinenoexcept

G1: the authored [2D_AQUIFER*] rows, in the user's own units. Reached by the section handlers and the InpWriter through SimulationContext::twod_io.aquifer.

Borrow the owned aquifer authoring rows, retained in project input units.

Returns

Reference to this router's member, with mutability determined by the overload. No copy, validation or ownership transfer occurs. Router must remain alive/stable; initialization, restore, move/replacement and vector edits can invalidate contained views.

Note

Mutable access requires exclusive ownership and preservation of prepared topology, row shapes, unit convention, source clocks and receipt phase. Authoring edits may require resolution/rebuild before routing. This getter performs no automatic cache/solver synchronization or physical update.

aquiferLinkNames() [1/2]

const std::vector< std::string > & openswmm::twoD::SurfaceRouter2D::aquiferLinkNames ( ) const

inlinenoexcept

Borrow the owned conduit names parallel to aquiferConfig().link_rows authoring identity.

Returns

Reference to this router's member, with mutability determined by the overload. No copy, validation or ownership transfer occurs. Router must remain alive/stable; initialization, restore, move/replacement and vector edits can invalidate contained views.

Note

Mutable access requires exclusive ownership and preservation of prepared topology, row shapes, unit convention, source clocks and receipt phase. Authoring edits may require resolution/rebuild before routing. This getter performs no automatic cache/solver synchronization or physical update.

aquiferLinkNames() [2/2]

std::vector< std::string > & openswmm::twoD::SurfaceRouter2D::aquiferLinkNames ( )

inlinenoexcept

G-X4: the [2D_AQUIFER_LINKS] row names, parallel to aquiferConfig().link_rows — the writer's round-trip key.

Borrow the owned conduit names parallel to aquiferConfig().link_rows authoring identity.

Returns

Reference to this router's member, with mutability determined by the overload. No copy, validation or ownership transfer occurs. Router must remain alive/stable; initialization, restore, move/replacement and vector edits can invalidate contained views.

Note

Mutable access requires exclusive ownership and preservation of prepared topology, row shapes, unit convention, source clocks and receipt phase. Authoring edits may require resolution/rebuild before routing. This getter performs no automatic cache/solver synchronization or physical update.

aquiferNodeNames() [1/2]

const std::vector< std::string > & openswmm::twoD::SurfaceRouter2D::aquiferNodeNames ( ) const

inlinenoexcept

Borrow the owned node names parallel to aquiferConfig().node_beds authoring identity.

Returns

Reference to this router's member, with mutability determined by the overload. No copy, validation or ownership transfer occurs. Router must remain alive/stable; initialization, restore, move/replacement and vector edits can invalidate contained views.

Note

Mutable access requires exclusive ownership and preservation of prepared topology, row shapes, unit convention, source clocks and receipt phase. Authoring edits may require resolution/rebuild before routing. This getter performs no automatic cache/solver synchronization or physical update.

aquiferNodeNames() [2/2]

std::vector< std::string > & openswmm::twoD::SurfaceRouter2D::aquiferNodeNames ( )

inlinenoexcept

Borrow the owned node names parallel to aquiferConfig().node_beds authoring identity.

Returns

Reference to this router's member, with mutability determined by the overload. No copy, validation or ownership transfer occurs. Router must remain alive/stable; initialization, restore, move/replacement and vector edits can invalidate contained views.

Note

Mutable access requires exclusive ownership and preservation of prepared topology, row shapes, unit convention, source clocks and receipt phase. Authoring edits may require resolution/rebuild before routing. This getter performs no automatic cache/solver synchronization or physical update.

backendName()

const std::string & openswmm::twoD::SurfaceRouter2D::backendName ( ) const

inlinenoexcept

Backend label chosen by SurfaceSolverFactory at initialize() ("cpu (explicit marcher)", "omp (…)", …); empty before that.

Borrow selected surface solver backend label.

Returns

Router-owned const reference in owned UTF-8 string, empty before backend selection. Valid only during stable router access; initialization, restore, replacement or corresponding producer updates can change contents/invalidate views. No copy, reset, queue consumption, ownership transfer or synchronization occurs in this query.

bookGageRates()

void openswmm::twoD::SurfaceRouter2D::bookGageRates	(	const SimulationContext &	ctx,
		double	runoff_start_s )

Book the gage rates a runoff step starting at runoff_start_s (seconds since the run start) takes, after the monthly adjustment. The 2D integrates these piecewise-constant rates over each of its own windows, so a cell receives exactly the gage depth the subcatchments do over the same interval.

• Argument ctx (in): Matching post-monthly-adjustment native gage rainfall vector, extent>=n_gages.
• Argument runoff_start_s (in): Finite nondecreasing elapsed runoff interval start s.

  Note

  Integrates previous held rates to this boundary and installs current rates; stores depth at a report instant crossed by the change. Resizes/resets all gage histories when count changes. No water advance or gage cursor mutation; exactly once per accepted runoff rate change and exclusive history access required. Does not reject backwards/nonfinite input; allocation may partially reset.

  Parameters

  [in]	ctx	Matching post-monthly-adjustment native gage rainfall vector, extent>=n_gages.
  [in]	runoff_start_s	Finite nondecreasing elapsed runoff interval start s.

  Note

  Integrates previous held rates to this boundary and installs current rates; stores depth at a report instant crossed by the change. Resizes/resets all gage histories when count changes. No water advance or gage cursor mutation; exactly once per accepted runoff rate change and exclusive history access required. Does not reject backwards/nonfinite input; allocation may partially reset.

Here is the call graph for this function:

Here is the caller graph for this function:

boundary() [1/2]

const BoundaryData & openswmm::twoD::SurfaceRouter2D::boundary ( ) const

inlinenoexcept

Access per-edge boundary-condition data (read-only).

Borrow the owned per-edge boundary descriptors/forcing/receipts, indexed by MeshData::slot.

Returns

Reference to this router's member, with mutability determined by the overload. No copy, validation or ownership transfer occurs. Router must remain alive/stable; initialization, restore, move/replacement and vector edits can invalidate contained views.

Note

Mutable access requires exclusive ownership and preservation of prepared topology, row shapes, unit convention, source clocks and receipt phase. Authoring edits may require resolution/rebuild before routing. This getter performs no automatic cache/solver synchronization or physical update.

Here is the caller graph for this function:

boundary() [2/2]

BoundaryData & openswmm::twoD::SurfaceRouter2D::boundary ( )

inlinenoexcept

Access per-edge boundary-condition data (mutable, for forcing/parsing).

Borrow the owned per-edge boundary descriptors/forcing/receipts, indexed by MeshData::slot.

Returns

Reference to this router's member, with mutability determined by the overload. No copy, validation or ownership transfer occurs. Router must remain alive/stable; initialization, restore, move/replacement and vector edits can invalidate contained views.

Note

Mutable access requires exclusive ownership and preservation of prepared topology, row shapes, unit convention, source clocks and receipt phase. Authoring edits may require resolution/rebuild before routing. This getter performs no automatic cache/solver synchronization or physical update.

cellSubcatchment()

const std::vector< int > & openswmm::twoD::SurfaceRouter2D::cellSubcatchment ( ) const

inlinenoexcept

Cell → containing subcatchment index (-1 = none). Empty unless the SUBCATCH_AQUIFER destination resolved.

Borrow resolved recharge destination lookup.

Returns

Router-owned const reference in zero-based containing subcatchment per cell, -1 for none. Valid only during stable router access; initialization, restore, replacement or corresponding producer updates can change contents/invalidate views. No copy, reset, queue consumption, ownership transfer or synchronization occurs in this query.

channelGround() [1/2]

const ChannelGroundState & openswmm::twoD::SurfaceRouter2D::channelGround ( ) const

inlinenoexcept

Borrow the shared finite channel/physical-soil thermal contact owner and cumulative J/native receipts.

Returns

Reference to this router's member, with mutability determined by the overload. No copy, validation or ownership transfer occurs. Router must remain alive/stable; initialization, restore, move/replacement and vector edits can invalidate contained views.

Note

Mutable access requires exclusive ownership and preservation of prepared topology, row shapes, unit convention, source clocks and receipt phase. Authoring edits may require resolution/rebuild before routing. This getter performs no automatic cache/solver synchronization or physical update.

Here is the caller graph for this function:

channelGround() [2/2]

ChannelGroundState & openswmm::twoD::SurfaceRouter2D::channelGround ( )

inlinenoexcept

Borrow the shared finite channel/physical-soil thermal contact owner and cumulative J/native receipts.

Returns

Reference to this router's member, with mutability determined by the overload. No copy, validation or ownership transfer occurs. Router must remain alive/stable; initialization, restore, move/replacement and vector edits can invalidate contained views.

Note

Mutable access requires exclusive ownership and preservation of prepared topology, row shapes, unit convention, source clocks and receipt phase. Authoring edits may require resolution/rebuild before routing. This getter performs no automatic cache/solver synchronization or physical update.

commonSourceAttached()

bool openswmm::twoD::SurfaceRouter2D::commonSourceAttached ( ) const

inlinenoexcept

Test whether an external common-source stage pointer is attached.

Returns

common_stage_!=nullptr, independent of its current eligibility/validity. Does not dereference it, validate the owner lifetime or activate authored ownership. No allocation or state change.

commonSourceStage()

const CommonSourceStage * openswmm::twoD::SurfaceRouter2D::commonSourceStage ( ) const

inlinenoexcept

Borrow the externally attached common-source stage, if any.

Returns

Nonowning const pointer, null when detached. Stage must outlive router/marcher uses; attachments/restore/replacement can change the pointer. No stage advance, copy or validation occurs.

computeCouplingConductances()

void openswmm::twoD::SurfaceRouter2D::computeCouplingConductances	(	const SimulationContext &	ctx,
		std::vector< std::pair< int, double > > &	out ) const

Windowless-coupling stabilizer: per coupled node, the exchange head sensitivity G = Σ_points −∂Q/∂h_1d ≥ 0 converted to 1D units (ft³/s per ft), for the caller to add into the dynamic-wave sumdqdh each Picard iteration. Appends (node_idx, G) pairs; cheap (O(points)).

Append positive live non-outfall coupling head derivatives in native hydraulic units.

Append positive live non-outfall coupling head derivatives in native hydraulic units.

• Argument ctx (in): Matching live native node heads/depths and prepared coupling model.
• Argument out (in,out): Existing vector retained; appends (zero-based node index,G) per positive point, where G is ft3/s per ft of native 1D head. Entries for shared nodes are not aggregated here.

  Note

  Inactive router returns. Evaluates current SI law then multiplies flow and length conversion; no state/canonical water/calendar mutation. Allocation may leave an appended prefix. Requires stable mesh/native views; caller sums point derivatives in its hydraulic assembly.

  Parameters

  [in]	ctx	Matching live native node heads/depths and prepared coupling model.
  [in,out]	out	Existing vector retained; appends (zero-based node index,G) per positive point, where G is ft3/s per ft of native 1D head. Entries for shared nodes are not aggregated here.

  Note

  Inactive router returns. Evaluates current SI law then multiplies flow and length conversion; no state/canonical water/calendar mutation. Allocation may leave an appended prefix. Requires stable mesh/native views; caller sums point derivatives in its hydraulic assembly.

Here is the call graph for this function:

Here is the caller graph for this function:

couplingCumulative()

const std::vector< double > & openswmm::twoD::SurfaceRouter2D::couplingCumulative ( ) const

inlinenoexcept

Signed cumulative coupling exchange per cell (m³).

Positive = water the 1D node delivered INTO this cell (spill, submerged-outfall discharge); negative = water the node abstracted FROM it (drain). Summing the vector gives coupling_1d_to_2d_in − coupling_2d_to_1d_out, which is the check that ties this series to the domain totals.

Borrow signed accepted cumulative native-node/surface exchange.

Returns

Router-owned const reference in m3 per cell, positive into surface. Valid only during stable router access; initialization, restore, replacement or corresponding producer updates can change contents/invalidate views. No copy, reset, queue consumption, ownership transfer or synchronization occurs in this query.

drainSubcatchRecharge()

void openswmm::twoD::SurfaceRouter2D::drainSubcatchRecharge ( std::vector< double > & out )

inline

Move the pending recharge into out (m³ per subcatchment) and zero the accumulator. out is sized to the accumulator (empty when the destination is not in use).

Parameters

[out]

out

Replaced by pending SI m3 per original subcatchment, then the owned accumulator is zeroed. Must not alias subcatch_recharge_ itself. Empty destination mapping yields empty output.

Note

Copy allocation can throw before the accumulator is cleared. Call once on the matching runoff handoff cadence; does not inject legacy groundwater itself or update canonical hydraulic storage. Requires exclusive accumulator/consumer access to avoid duplicate delivery.

expireRuntime()

void openswmm::twoD::SurfaceRouter2D::expireRuntime ( double now )

inline

Retire all runtime source and forcing entries at an accepted completed horizon.

Parameters

[in]

now

Finite elapsed completed time s used by each owner expire() policy.

Note

Applies surface sources, aquifer sources then forcings, including their prescribed expiry/ receipt handling. Does not restore boundary runtime_original slots itself or advance physical water. Requires exclusive validated owner access; exceptions can leave earlier owners expired. No whole- router rollback is provided by this wrapper.

finalize()

void openswmm::twoD::SurfaceRouter2D::finalize

(

SimulationContext &

ctx

)

Finalize the 2D module at simulation end.

Flushes any partial macro-step window (routing time accumulated since the last 2D advance) so the 2D clock ends at the simulation end instead of up to one window short, then releases the solver.

• Argument ctx: Simulation context (needed for the flush advance).
• Argument ctx (in,out): Matching live context for pending physics, solver statistics and warning receipts.

  Note

  Flushes remaining batch first; captures solver statistics and finalizes solver internals, then records dispersion limiter advisories, clears source/checkpoint attachments and marks inactive. Retains router mesh/state and solver object for inspection; does not destroy the solver pointer. Delegated advance/finalize or warning allocation can throw after partial cleanup. Must be called serially with borrowed owners still alive, before their destruction.

  Parameters

  [in,out]

  ctx

  Matching live context for pending physics, solver statistics and warning receipts.

  Note

  Flushes remaining batch first; captures solver statistics and finalizes solver internals, then records dispersion limiter advisories, clears source/checkpoint attachments and marks inactive. Retains router mesh/state and solver object for inspection; does not destroy the solver pointer. Delegated advance/finalize or warning allocation can throw after partial cleanup. Must be called serially with borrowed owners still alive, before their destruction.

Here is the call graph for this function:

Here is the caller graph for this function:

flushPendingBatch()

void openswmm::twoD::SurfaceRouter2D::flushPendingBatch

(

SimulationContext &

ctx

)

Flush the pending (partial) sync batch, if any.

Closes the accumulated routing span with one co-advance so the 2D clock reaches the current routing time. A no-op under default per-routing-step coupling (the batch closes every step). Used before a report snapshot — so the report-time blend brackets the report instant — and before a one-shot forcing.

• Argument ctx (in,out): Matching live context; common-source mode requires the exact attached identity and a completed ready source boundary.

  Note

  Throws std::invalid_argument on common-source readiness mismatch. Inactive/no pending batch returns. Clears pending duration before coAdvanceStep; delegated failure can leave partial state and is not automatically replayable. Exclusive router/context access required.

  Parameters

  [in,out]

  ctx

  Matching live context; common-source mode requires the exact attached identity and a completed ready source boundary.

  Note

  Throws std::invalid_argument on common-source readiness mismatch. Inactive/no pending batch returns. Clears pending duration before coAdvanceStep; delegated failure can leave partial state and is not automatically replayable. Exclusive router/context access required.

Here is the call graph for this function:

Here is the caller graph for this function:

gwTransport() [1/2]

const GwTransportData & openswmm::twoD::SurfaceRouter2D::gwTransport ( ) const

inlinenoexcept

Borrow the owned groundwater quality/thermal/source authoring and resolved SI transport metadata.

Returns

Reference to this router's member, with mutability determined by the overload. No copy, validation or ownership transfer occurs. Router must remain alive/stable; initialization, restore, move/replacement and vector edits can invalidate contained views.

Note

Mutable access requires exclusive ownership and preservation of prepared topology, row shapes, unit convention, source clocks and receipt phase. Authoring edits may require resolution/rebuild before routing. This getter performs no automatic cache/solver synchronization or physical update.

gwTransport() [2/2]

GwTransportData & openswmm::twoD::SurfaceRouter2D::gwTransport ( )

inlinenoexcept

U4 (2026-09-07): the [GW_*] subsurface-transport authoring rows. Reached by the parser, the writer and the C API through SimulationContext::twod_io.gw; resolved owners consume them during initialization.

Borrow the owned groundwater quality/thermal/source authoring and resolved SI transport metadata.

Returns

Reference to this router's member, with mutability determined by the overload. No copy, validation or ownership transfer occurs. Router must remain alive/stable; initialization, restore, move/replacement and vector edits can invalidate contained views.

Note

Mutable access requires exclusive ownership and preservation of prepared topology, row shapes, unit convention, source clocks and receipt phase. Authoring edits may require resolution/rebuild before routing. This getter performs no automatic cache/solver synchronization or physical update.

Here is the caller graph for this function:

infil() [1/2]

const Infil2D & openswmm::twoD::SurfaceRouter2D::infil ( ) const

inlinenoexcept

Borrow the owned per-cell infiltration authoring, held capacity and model memory.

Returns

Reference to this router's member, with mutability determined by the overload. No copy, validation or ownership transfer occurs. Router must remain alive/stable; initialization, restore, move/replacement and vector edits can invalidate contained views.

Note

Mutable access requires exclusive ownership and preservation of prepared topology, row shapes, unit convention, source clocks and receipt phase. Authoring edits may require resolution/rebuild before routing. This getter performs no automatic cache/solver synchronization or physical update.

infil() [2/2]

Infil2D & openswmm::twoD::SurfaceRouter2D::infil ( )

inlinenoexcept

Access the per-cell infiltration model (plan §5.5, track I).

Mutable so SWMMEngine can publish it on ctx.twod_io.infil — the [2D_INFILTRATION*] section handlers and the InpWriter reach it there. The router owns the object, resolves it against the mesh in initialize(), and drives its INFIL_STEP cadence in coAdvanceStep().

Borrow the owned per-cell infiltration authoring, held capacity and model memory.

Returns

Reference to this router's member, with mutability determined by the overload. No copy, validation or ownership transfer occurs. Router must remain alive/stable; initialization, restore, move/replacement and vector edits can invalidate contained views.

Note

Mutable access requires exclusive ownership and preservation of prepared topology, row shapes, unit convention, source clocks and receipt phase. Authoring edits may require resolution/rebuild before routing. This getter performs no automatic cache/solver synchronization or physical update.

Here is the caller graph for this function:

infilCumulative()

const std::vector< double > & openswmm::twoD::SurfaceRouter2D::infilCumulative ( ) const

inlinenoexcept

Borrow actually applied cumulative infiltration depth.

Returns

Router-owned const reference in m per mesh cell, empty when no model resolved. Valid only during stable router access; initialization, restore, replacement or corresponding producer updates can change contents/invalidate views. No copy, reset, queue consumption, ownership transfer or synchronization occurs in this query.

infiltrationElapsed()

double openswmm::twoD::SurfaceRouter2D::infiltrationElapsed ( ) const

inlinenoexcept

Read elapsed duration since the last held infiltration model rate refresh.

Returns

Stored duration s on router/co-advance cadence, not total simulation time or marcher substep count. No rate update, reset or allocation occurs; caller reads stable state.

initialize()

void openswmm::twoD::SurfaceRouter2D::initialize

(

SimulationContext &

ctx

)

Initialize the 2D module after input parsing is complete.

Prepare authored mesh, coupling, physical source owners and selected solver for a new run.

Builds mesh topology, vertex stencils, resolves coupling names, and initializes the explicit 2D solver.

• Argument ctx: Simulation context (must have mesh_2d populated from parsing).

Prepare authored mesh, coupling, physical source owners and selected solver for a new run.

• Argument ctx (in,out): Fully parsed matching engine context with prepared node/link/gage/tables, quality/reaction/heat configuration; borrowed context/node/thermal views must outlive routing.

  Note

  Requires serial lifecycle access and no concurrent retained mutable mesh/state views. Clears source/checkpoint bindings and channel contacts, refuses unqualified surface recharge ownership, and disables routing for missing mesh or IGNORE_2D. Converts authored geometry and boundary units to SI, builds/validates topology and stencils, resolves named coupling and pond footprints, selects CPU/plugin eligibility and initializes native rows, groundwater/heat/snow/quality/infiltration. 1D remains internally ft/ft3, even for metric display projects. Surface/GW native inventories use concentration*m3, age s*m3, temperature degC*m3. Authored age concentrations convert hours to s.

  Seeds initial water/native/bed storage, source rate capacities, report/render fields and water ledgers. May alter options from environment, coupling/pond/exfiltration ownership in ctx, quality queues and warnings. Does not advance the engine calendar. Channel contacts are separately bound after 1D heat initialization. Profile/name/layout/ownership errors throw std::runtime_error; allocation and delegated validation can throw after partial setup. This is not a transactional reinitialization or a safe way to preserve an evolved model's inventories.

Parameters

[in,out]

ctx

Fully parsed matching engine context with prepared node/link/gage/tables, quality/reaction/heat configuration; borrowed context/node/thermal views must outlive routing.

Note

Requires serial lifecycle access and no concurrent retained mutable mesh/state views. Clears source/checkpoint bindings and channel contacts, refuses unqualified surface recharge ownership, and disables routing for missing mesh or IGNORE_2D. Converts authored geometry and boundary units to SI, builds/validates topology and stencils, resolves named coupling and pond footprints, selects CPU/plugin eligibility and initializes native rows, groundwater/heat/snow/quality/infiltration. 1D remains internally ft/ft3, even for metric display projects. Surface/GW native inventories use concentration*m3, age s*m3, temperature degC*m3. Authored age concentrations convert hours to s.

Seeds initial water/native/bed storage, source rate capacities, report/render fields and water ledgers. May alter options from environment, coupling/pond/exfiltration ownership in ctx, quality queues and warnings. Does not advance the engine calendar. Channel contacts are separately bound after 1D heat initialization. Profile/name/layout/ownership errors throw std::runtime_error; allocation and delegated validation can throw after partial setup. This is not a transactional reinitialization or a safe way to preserve an evolved model's inventories.

Here is the call graph for this function:

initializeChannelGround()

void openswmm::twoD::SurfaceRouter2D::initializeChannelGround

(

SimulationContext &

ctx

)

Bind selected finite channel contacts after 1D heat state is seeded.

Resolve requested finite conduit/physical-ground contacts after native 1D heat initialization.

Resolve requested finite conduit/physical-ground contacts after native 1D heat initialization.

• Argument ctx (in,out): Matching prepared heat/node/link context; retained thermal views must stay alive.

  Note

  No requested mesh contact returns. Requires active mesh, compatible porous aquifer heat/native owners and CPU solver. Converts authored map coordinates to m, initializes the shared finite contact owner and binds it into CPU marcher. Refusal throws std::runtime_error; initialization/allocation can leave partially prepared contact state. No water/thermal advance; exclusive lifecycle access.

  Parameters

  [in,out]

  ctx

  Matching prepared heat/node/link context; retained thermal views must stay alive.

  Note

  No requested mesh contact returns. Requires active mesh, compatible porous aquifer heat/native owners and CPU solver. Converts authored map coordinates to m, initializes the shared finite contact owner and binds it into CPU marcher. Refusal throws std::runtime_error; initialization/allocation can leave partially prepared contact state. No water/thermal advance; exclusive lifecycle access.

Here is the call graph for this function:

Here is the caller graph for this function:

invalidateBoundaryIndex()

void openswmm::twoD::SurfaceRouter2D::invalidateBoundaryIndex

(

)

Mark the compact non-wall boundary index stale and refresh attached CPU boundary work lists.

Note

No time-series name reset or physics/clock advance. CPU refresh may allocate/throw after the dirty flag is set and can alter pin/layout caches. Call serially after compatible boundary edits; retained work-list views may become invalid.

Here is the call graph for this function:

Here is the caller graph for this function:

invalidateBoundaryNames()

void openswmm::twoD::SurfaceRouter2D::invalidateBoundaryNames ( )

inlinenoexcept

Mark symbolic boundary names unresolved after authoring/name changes.

Note

Sets boundary_names_resolved_=false only. Does not modify slots, force immediate name resolution, rebuild compact solver topology or alter existing forcing. Caller serializes edits.

isActive()

bool openswmm::twoD::SurfaceRouter2D::isActive ( ) const

inlinenoexcept

Check if the 2D module is active.

Returns

Stored router activation flag. Does not validate borrowed solver/context bindings, inspect current wetness or complete a pending batch. Read-only and allocation-free; serialize with lifecycle.

Here is the caller graph for this function:

lastSolverSteps()

long openswmm::twoD::SurfaceRouter2D::lastSolverSteps ( ) const

inline

Read the last surface advance's base substep count.

Returns

Delegated last_num_steps() when the optional backend exists; zero otherwise or when built without 2D. No solver advance/device synchronization or reset; access serialized with lifecycle.

lastSolverStepSize()

double openswmm::twoD::SurfaceRouter2D::lastSolverStepSize ( ) const

inline

Read the last accepted surface base/tail step duration.

Returns

Delegated last_step_size() in seconds when a backend exists, zero otherwise or without 2D. No stability recomputation/device synchronization or reset; access serialized with lifecycle.

loadCheckpoint()

std::string openswmm::twoD::SurfaceRouter2D::loadCheckpoint	(	SimulationContext &	ctx,
		const std::string &	path )

Read and stage a router component checkpoint into fresh matching attached owners.

• Argument ctx (in,out): Exact fresh attached context; successful install updates checkpointed clocks, gage rainfall/evaporation, mass balance and qualified native/source owners.
• Argument path (in): Readable nonempty bounded checkpoint file.

  Returns

  Empty on success, otherwise freshness/profile/model/file/decode diagnostic. Engine-owned managed RK2 or joint sessions must use the engine checkpoint route.

  Note

  Delegates private staged load; no general whole-engine/output hotstart. Requires exclusive live prepared owners and no evolution since attachment; does not physically replay saved intervals.

  Parameters

  [in,out]	ctx	Exact fresh attached context; successful install updates checkpointed clocks, gage rainfall/evaporation, mass balance and qualified native/source owners.
  [in]	path	Readable nonempty bounded checkpoint file.

  Returns

  Empty on success, otherwise freshness/profile/model/file/decode diagnostic. Engine-owned managed RK2 or joint sessions must use the engine checkpoint route.

  Note

  Delegates private staged load; no general whole-engine/output hotstart. Requires exclusive live prepared owners and no evolution since attachment; does not physically replay saved intervals.

mesh() [1/2]

const MeshData & openswmm::twoD::SurfaceRouter2D::mesh ( ) const

inlinenoexcept

Access mesh data (read-only).

Borrow the owned mesh geometry/topology; runtime coordinates are SI after initialization, authoring may precede conversion.

Returns

Reference to this router's member, with mutability determined by the overload. No copy, validation or ownership transfer occurs. Router must remain alive/stable; initialization, restore, move/replacement and vector edits can invalidate contained views.

Note

Mutable access requires exclusive ownership and preservation of prepared topology, row shapes, unit convention, source clocks and receipt phase. Authoring edits may require resolution/rebuild before routing. This getter performs no automatic cache/solver synchronization or physical update.

Here is the caller graph for this function:

mesh() [2/2]

MeshData & openswmm::twoD::SurfaceRouter2D::mesh ( )

inlinenoexcept

Access mesh data (mutable, for input parsing).

Borrow the owned mesh geometry/topology; runtime coordinates are SI after initialization, authoring may precede conversion.

Returns

Reference to this router's member, with mutability determined by the overload. No copy, validation or ownership transfer occurs. Router must remain alive/stable; initialization, restore, move/replacement and vector edits can invalidate contained views.

Note

Mutable access requires exclusive ownership and preservation of prepared topology, row shapes, unit convention, source clocks and receipt phase. Authoring edits may require resolution/rebuild before routing. This getter performs no automatic cache/solver synchronization or physical update.

nextRuntimeTime()

double openswmm::twoD::SurfaceRouter2D::nextRuntimeTime ( double now ) const

inlinenoexcept

Read the earliest scheduled source/forcing transition after a given time.

Parameters

[in]

now

Finite elapsed time s, in the same origin as runtime source/forcing windows.

Returns

Minimum nextTime() across surface sources, aquifer sources and forcing; infinity if none. Does not include unrelated reporting, project boundary-series or solver stability cuts. No queue consumption or mutation; caller serializes scheduling state with runtime edits.

operator=() [1/2]

SurfaceRouter2D & openswmm::twoD::SurfaceRouter2D::operator= ( const SurfaceRouter2D & )

delete

Here is the call graph for this function:

operator=() [2/2]

SurfaceRouter2D & openswmm::twoD::SurfaceRouter2D::operator= ( SurfaceRouter2D && )

default

Replace owned router members by default move assignment.

Returns

This router reference.

Note

Finalize/detach the previous run before replacement. Raw pointers are copied without self-member rebinding; move only inactive unattached authoring state or reinitialize/rebind before use. Source remains destructible; all prior destination member/solver views may be invalidated.

Here is the call graph for this function:

options() [1/2]

const SolverOptions2D & openswmm::twoD::SurfaceRouter2D::options ( ) const

inlinenoexcept

Access solver options (read-only).

Borrow the owned resolved surface solver controls, SI for runtime geometry/rates.

Returns

Reference to this router's member, with mutability determined by the overload. No copy, validation or ownership transfer occurs. Router must remain alive/stable; initialization, restore, move/replacement and vector edits can invalidate contained views.

Note

Mutable access requires exclusive ownership and preservation of prepared topology, row shapes, unit convention, source clocks and receipt phase. Authoring edits may require resolution/rebuild before routing. This getter performs no automatic cache/solver synchronization or physical update.

Here is the caller graph for this function:

options() [2/2]

SolverOptions2D & openswmm::twoD::SurfaceRouter2D::options ( )

inlinenoexcept

Access solver options (mutable).

Borrow the owned resolved surface solver controls, SI for runtime geometry/rates.

Returns

Reference to this router's member, with mutability determined by the overload. No copy, validation or ownership transfer occurs. Router must remain alive/stable; initialization, restore, move/replacement and vector edits can invalidate contained views.

Note

Mutable access requires exclusive ownership and preservation of prepared topology, row shapes, unit convention, source clocks and receipt phase. Authoring edits may require resolution/rebuild before routing. This getter performs no automatic cache/solver synchronization or physical update.

outfallExchange()

const OutfallExchange & openswmm::twoD::SurfaceRouter2D::outfallExchange ( ) const

inlinenoexcept

Coupled-outfall delivery and tailwater records (report).

Borrow coupled outfall reservations, accepted receipts and tailwater diagnostics.

Returns

Router-owned const reference in SI water m3 and native 1D tailwater length with elapsed seconds. Valid only during stable router access; initialization, restore, replacement or corresponding producer updates can change contents/invalidate views. No copy, reset, queue consumption, ownership transfer or synchronization occurs in this query.

outfallTailwaterCheckpointing()

bool openswmm::twoD::SurfaceRouter2D::outfallTailwaterCheckpointing ( ) const

inlinenoexcept

Joint checkpoints of a model with coupled outfalls carry each one's tailwater record — a distinct checkpoint version.

Returns

True when a joint hydraulic owner is attached and prepared outfall points are nonempty. This qualifies the specific tailwater checkpoint extension, not whole-engine restart validity. No reservation, file access, mutation or synchronization occurs.

Here is the call graph for this function:

Here is the caller graph for this function:

pendingBCRows() [1/2]

const std::vector< PendingBoundaryRow > & openswmm::twoD::SurfaceRouter2D::pendingBCRows ( ) const

inlinenoexcept

Borrow retained hydraulic boundary authoring rows.

Returns

Router-owned row vector reference, mutable only in the mutable overload. Kept for faithful input serialization and later resolution; changing it does not automatically update prepared live mesh/solver fields. No copy/validation/ownership transfer occurs.

Note

Caller preserves input unit/one-based token versus internal index conventions defined by PendingRows2D and coordinates drain/resolution before use. Router/vector mutations invalidate views; exclusive edit access is required.

pendingBCRows() [2/2]

std::vector< PendingBoundaryRow > & openswmm::twoD::SurfaceRouter2D::pendingBCRows ( )

inlinenoexcept

Borrow retained hydraulic boundary authoring rows.

Returns

Router-owned row vector reference, mutable only in the mutable overload. Kept for faithful input serialization and later resolution; changing it does not automatically update prepared live mesh/solver fields. No copy/validation/ownership transfer occurs.

Note

Caller preserves input unit/one-based token versus internal index conventions defined by PendingRows2D and coordinates drain/resolution before use. Router/vector mutations invalidate views; exclusive edit access is required.

pendingBoundaryQualityRows()

std::vector< PendingBoundaryQualityRow > & openswmm::twoD::SurfaceRouter2D::pendingBoundaryQualityRows ( )

inlinenoexcept

Borrow retained boundary native quality authoring rows.

Returns

Router-owned row vector reference, mutable only in the mutable overload. Kept for faithful input serialization and later resolution; changing it does not automatically update prepared live mesh/solver fields. No copy/validation/ownership transfer occurs.

Note

Caller preserves input unit/one-based token versus internal index conventions defined by PendingRows2D and coordinates drain/resolution before use. Router/vector mutations invalidate views; exclusive edit access is required.

Here is the caller graph for this function:

pendingEdgeConveyanceRows() [1/2]

const std::vector< PendingEdgeConveyanceRow > & openswmm::twoD::SurfaceRouter2D::pendingEdgeConveyanceRows ( ) const

inlinenoexcept

Borrow retained interior/exterior edge conveyance authoring rows.

Returns

Router-owned row vector reference, mutable only in the mutable overload. Kept for faithful input serialization and later resolution; changing it does not automatically update prepared live mesh/solver fields. No copy/validation/ownership transfer occurs.

Note

Caller preserves input unit/one-based token versus internal index conventions defined by PendingRows2D and coordinates drain/resolution before use. Router/vector mutations invalidate views; exclusive edit access is required.

pendingEdgeConveyanceRows() [2/2]

std::vector< PendingEdgeConveyanceRow > & openswmm::twoD::SurfaceRouter2D::pendingEdgeConveyanceRows ( )

inlinenoexcept

Borrow retained interior/exterior edge conveyance authoring rows.

Returns

Router-owned row vector reference, mutable only in the mutable overload. Kept for faithful input serialization and later resolution; changing it does not automatically update prepared live mesh/solver fields. No copy/validation/ownership transfer occurs.

Note

Caller preserves input unit/one-based token versus internal index conventions defined by PendingRows2D and coordinates drain/resolution before use. Router/vector mutations invalidate views; exclusive edit access is required.

pendingInitialBedQualityRows()

std::vector< PendingInitialBedQualityRow > & openswmm::twoD::SurfaceRouter2D::pendingInitialBedQualityRows ( )

inlinenoexcept

Borrow retained local-bed initial native quality authoring rows.

Returns

Router-owned row vector reference, mutable only in the mutable overload. Kept for faithful input serialization and later resolution; changing it does not automatically update prepared live mesh/solver fields. No copy/validation/ownership transfer occurs.

Note

Caller preserves input unit/one-based token versus internal index conventions defined by PendingRows2D and coordinates drain/resolution before use. Router/vector mutations invalidate views; exclusive edit access is required.

pendingInitialQualityRows()

std::vector< PendingInitialQualityRow > & openswmm::twoD::SurfaceRouter2D::pendingInitialQualityRows ( )

inlinenoexcept

S1/S2: raw [2D_INITIAL_QUALITY] rows, resolved at initialize().

Borrow retained surface initial native quality authoring rows.

Returns

Router-owned row vector reference, mutable only in the mutable overload. Kept for faithful input serialization and later resolution; changing it does not automatically update prepared live mesh/solver fields. No copy/validation/ownership transfer occurs.

Note

Caller preserves input unit/one-based token versus internal index conventions defined by PendingRows2D and coordinates drain/resolution before use. Router/vector mutations invalidate views; exclusive edit access is required.

prepareForEdit()

void openswmm::twoD::SurfaceRouter2D::prepareForEdit

(

)

Make the parsed mesh editable without a full initialize().

The GUI keeps the engine in OPENED (not INITIALIZED) state so 1D property edits stay legal. In that state the 2D mesh is parsed but the [2D_BOUNDARY_CONDITIONS] / [2D_EDGE_CONVEYANCE] rows still live in the pending-row buffers, which the serializer prefers over live state. This drains those rows into BoundaryData / mesh edge slots (the same drain initialize() performs) so per-edge API edits take effect and are written on save. No-op once drained or when no mesh is loaded.

prepareLidStep()

void openswmm::twoD::SurfaceRouter2D::prepareLidStep	(	SimulationContext &	ctx,
		double	dt,
		double	evaporation )

Prepare the next finite Richards LID/mesh acceptance and conduit donor budgets.

Prepare finite Richards LID/mesh acceptance for the next hydraulic interval.

• Argument dt (in): Positive finite interval duration s.
• Argument evaporation (in): Held native evaporation passed to the LID admission owner.

  Note

  The unnamed writable context reference is the matching prepared native LID/hydraulic owner. Delegates admission against mesh/GW state and republishes gain budgets when required. May throw after partial preparation; requires exclusive interval ownership. Definition details receipts.

  Parameters

  [in,out]	ctx	Matching prepared native LID/hydraulic context, borrowed for the operation.
  [in]	dt	Positive finite interval duration s required by the admission owner.
  [in]	evaporation	Held native evaporation input passed to prepareMeshRichardsStep.

  Note

  Delegates admission/reservation work against subsurface and surface owners, then republishes conduit gain budgets when LID receipts and link shares exist. Can throw after partial delegated preparation; no independent rollback. Requires exclusive matching lifecycle and one interval owner.

Here is the call graph for this function:

Here is the caller graph for this function:

prepareOneShotForcing()

void openswmm::twoD::SurfaceRouter2D::prepareOneShotForcing

(

SimulationContext &

ctx

)

Prepare a RESET 2D forcing to apply on the next routing step.

Flushes any already accumulated macro-window before the new one-shot is recorded, then forces the next routing step to fire a 2D advance so the prescription applies to future time only and is cleared after use.

• Argument ctx (in,out): Matching active context used to close old pending time before caller edits forcing.

  Note

  Inactive router returns. This method only flushes existing time; it does not record/reset any forcing or independently force the next batch. flushPendingBatch exceptions/partial-state contract apply. Exclusive lifecycle/forcing edit access required.

  Parameters

  [in,out]

  ctx

  Matching active context used to close old pending time before caller edits forcing.

  Note

  Inactive router returns. This method only flushes existing time; it does not record/reset any forcing or independently force the next batch. flushPendingBatch exceptions/partial-state contract apply. Exclusive lifecycle/forcing edit access required.

Here is the call graph for this function:

Here is the caller graph for this function:

rainCumulative()

const std::vector< double > & openswmm::twoD::SurfaceRouter2D::rainCumulative ( ) const

inlinenoexcept

Ledger-consistent cumulative rainfall volume per cell (m³).

Booked in accumulateMassBalance() from the SAME per-cell rainfall term that feeds MassBalance2D::rainfall_in, so sum(rainCumulative()[i]) == rainfall_in holds by construction. Sized [n_triangles] from initialize(); zero-filled when no rain.

Borrow accepted cumulative rainfall source volume.

Returns

Router-owned const reference in m3 per mesh cell. Valid only during stable router access; initialization, restore, replacement or corresponding producer updates can change contents/invalidate views. No copy, reset, queue consumption, ownership transfer or synchronization occurs in this query.

rainfallInterpolator()

const RainfallInterpolator & openswmm::twoD::SurfaceRouter2D::rainfallInterpolator ( ) const

inlinenoexcept

Static rainfall weights built at initialize() (diagnostic inspection).

Borrow prepared static gage-to-cell weights and mapping.

Returns

Router-owned const reference in SI mesh identity and the configured rainfall interpolation policy. Valid only during stable router access; initialization, restore, replacement or corresponding producer updates can change contents/invalidate views. No copy, reset, queue consumption, ownership transfer or synchronization occurs in this query.

refreshRenderFieldsIfStale()

void openswmm::twoD::SurfaceRouter2D::refreshRenderFieldsIfStale ( )

inline

Bring the render fields (face velocity, vertex heads, output gradients, vertex render depths) up to date with the current solver state if a batch has run since they were last computed. The API getters that expose those fields call this so a reader arriving between reports is never served a stale field; it is a no-op at a report instant, where the refresh already ran.

Note

When render_dirty_ is true, mutates derived head/gradient/render-depth caches by calling refreshRenderFields(); otherwise no-op. Requires live matching geometry/solver state and exclusive cache access. May allocate/throw through reconstruction; does not advance physical solver/source clocks.

reportOldDepth()

const std::vector< double > & openswmm::twoD::SurfaceRouter2D::reportOldDepth ( ) const

inlinenoexcept

Cell depth (m) at the start of the sync batch that crossed the current report instant (meaningful when reportWeight() < 1).

Borrow surface depth at the old side of the last report-crossing sync batch.

Returns

Router-owned const reference in m per mesh cell. Valid only during stable router access; initialization, restore, replacement or corresponding producer updates can change contents/invalidate views. No copy, reset, queue consumption, ownership transfer or synchronization occurs in this query.

reportOldHead()

const std::vector< double > & openswmm::twoD::SurfaceRouter2D::reportOldHead ( ) const

inlinenoexcept

Cell head (m) at the start of that batch.

Borrow surface head at the old side of the last report-crossing sync batch.

Returns

Router-owned const reference in absolute SI elevation m per cell. Valid only during stable router access; initialization, restore, replacement or corresponding producer updates can change contents/invalidate views. No copy, reset, queue consumption, ownership transfer or synchronization occurs in this query.

reportRainCumulative()

const std::vector< double > & openswmm::twoD::SurfaceRouter2D::reportRainCumulative ( double report_ms ) const

inlinenoexcept

Rainfall volume (m³) integrated to the report boundary, excluding the part of a routing/sync window after that boundary. Runtime totals remain available through rainCumulative().

Parameters

[in]

report_ms

Requested engine report boundary in elapsed milliseconds; compared exactly to stored report_rain_ms_, without tolerance or finite-value checks.

Returns

Borrowed report-boundary integrated m3 vector only on exact timestamp equality, otherwise current runtime rain_cum_. Does not interpolate, integrate, flush or consume source history. Router must remain stable; later rainfall/report bookkeeping can change either vector/invalidate views.

reportRainfall()

void openswmm::twoD::SurfaceRouter2D::reportRainfall	(	const SimulationContext &	ctx,
		double	report_date,
		std::vector< double > &	out ) const

Per-cell rainfall (m/s) as the .out reports subcatchment rainfall: the source gage rate at report_date, independent of runoff cursor, mapped through RAINFALL_MODE, with the per-cell rainfall forcings applied.

• Argument ctx (in): Prepared matching gage/time-series/report-unit configuration.
• Argument report_date (in): Absolute engine DateTime days, not elapsed seconds.
• Argument out (out): Resized per-cell rainfall m/s, mapped by rainfall policy then composed with current per-cell replace/add forcing arrays; previous contents replaced.

  Note

  Queries reporting series independently of runoff-held rate history. No canonical water/rain cumulative/clock advance; may allocate and delegates series lookup. Stable model/forcing and exclusive output buffer required; no generic finite/shape repair.

  Parameters

  [in]	ctx	Prepared matching gage/time-series/report-unit configuration.
  [in]	report_date	Absolute engine DateTime days, not elapsed seconds.
  [out]	out	Resized per-cell rainfall m/s, mapped by rainfall policy then composed with current per-cell replace/add forcing arrays; previous contents replaced.

  Note

  Queries reporting series independently of runoff-held rate history. No canonical water/rain cumulative/clock advance; may allocate and delegates series lookup. Stable model/forcing and exclusive output buffer required; no generic finite/shape repair.

Here is the call graph for this function:

Here is the caller graph for this function:

reportWeight()

double openswmm::twoD::SurfaceRouter2D::reportWeight ( double report_ms ) const

noexcept

Report-time interpolation weight for the 2D snapshot blend: f = (report_ms − window_old_ms)/(window_new_ms − window_old_ms), clamped to [0,1]; returns 1.0 (pure current state) when no batch has crossed a report instant yet. Unlike the 1D weight there is no legacy bit pattern to reproduce, so the clamp simply absorbs ulp-level clock skew between the router's and the engine's ms accumulators.

• Argument report_ms (in): Requested elapsed report time in ms, normally finite.

  Returns

  Clamped interpolation fraction [0,1] or 1 for no valid old side/nonpositive window span. NaN is not independently rejected and can propagate. Read-only, allocation-free; no flush or refresh.

  Parameters

  [in]

  report_ms

  Requested elapsed report time in ms, normally finite.

  Returns

  Clamped interpolation fraction [0,1] or 1 for no valid old side/nonpositive window span. NaN is not independently rejected and can propagate. Read-only, allocation-free; no flush or refresh.

Here is the call graph for this function:

Here is the caller graph for this function:

restoreInfiltration()

void openswmm::twoD::SurfaceRouter2D::restoreInfiltration ( const std::vector< double > & cumulative, double elapsed )

inline

Replace router applied-infiltration reporting and held-model elapsed accounting.

Parameters

[in]	cumulative	Matching per-cell actually applied depth m, copied verbatim with no shape, sign or finite-value validation.
[in]	elapsed	Finite nonnegative held-rate elapsed duration s, assigned without validation.

Note

Does not restore Infil2D physical model memory, state_.infil_applied, mass balance or groundwater receipts; caller coordinates the full qualified restore. Copy may throw before elapsed assignment. Requires exclusive prepared owner access; element views may be invalidated.

resumeSourceResultHistory()

void openswmm::twoD::SurfaceRouter2D::resumeSourceResultHistory

(

SourceResultHistory &

history

)

Resume a saved accepted-source recorder prefix at a completed router boundary.

• Argument history (in,out): Compatible borrowed saved recorder prefix with exact checkpoint match; must remain stable/alive through recording.

  Note

  Requires attached common stage and ready boundary, then delegates exact prefix/phase checks to CPU marcher. Throws on refusal; does not replay physical intervals or advance engine calendar. Exclusive router/source/recorder access required.

  Parameters

  [in,out]

  history

  Compatible borrowed saved recorder prefix with exact checkpoint match; must remain stable/alive through recording.

  Note

  Requires attached common stage and ready boundary, then delegates exact prefix/phase checks to CPU marcher. Throws on refusal; does not replay physical intervals or advance engine calendar. Exclusive router/source/recorder access required.

Here is the call graph for this function:

runtimeActive()

bool openswmm::twoD::SurfaceRouter2D::runtimeActive ( ) const

inlinenoexcept

Test whether any runtime surface/aquifer source, boundary override or forcing is retained.

Returns

OR of stored active source/forcing states and nonempty boundary runtime_original map. Does not expire stale prescriptions, validate callbacks or imply every source is enabled. Read-only; requires stable matching owners, no allocation or physical update.

runtimeBoundaryCheckpointing()

bool openswmm::twoD::SurfaceRouter2D::runtimeBoundaryCheckpointing ( ) const

noexcept

Test whether the attached common source owns runtime boundary checkpointing.

Returns

True only with common source and its runtime-boundary enable. No state validation, mutation or allocation occurs; standalone RK2 uses its separate qualification route.

Here is the call graph for this function:

Here is the caller graph for this function:

runtimeCpuAvailable()

bool openswmm::twoD::SurfaceRouter2D::runtimeCpuAvailable ( ) const

noexcept

Announce that a boundary slot's TYPE changed (the API BC-type setter), so the compact non-WALL slot list the per-step boundary passes walk is rebuilt before it is next used.

Test active CPU support for the runtime prescription API route.

Test active CPU support for the runtime prescription API route.

Returns

True for an active CPU marcher and either non-FULL_SWE or qualified coupled second-order FULL_SWE with groundwater and no common stage, with no foreign joint owner. This is a capability gate, not full current-boundary validation. No allocation, state change or lifecycle synchronization.

True for an active CPU marcher and either non-FULL_SWE or qualified coupled second-order FULL_SWE with groundwater and no common stage, with no foreign joint owner. This is a capability gate, not full current-boundary validation. No allocation, state change or lifecycle synchronization.

Here is the call graph for this function:

Here is the caller graph for this function:

runtimeSources()

RuntimeSources & openswmm::twoD::SurfaceRouter2D::runtimeSources ( )

inlinenoexcept

Borrow mutable runtime prescriptions/receipts for the surface owner.

Returns

Router-owned state_.runtime_sources. Caller preserves validated row identity, per-cell lookup, units and accepted phase, and serializes mutations with routing/checkpointing. No callback, validation, cache rebuild or ownership activation occurs; external provider resources remain borrowed.

Here is the call graph for this function:

Here is the caller graph for this function:

runtimeWaterCheckpointing()

bool openswmm::twoD::SurfaceRouter2D::runtimeWaterCheckpointing ( ) const

noexcept

Test qualification ownership for managed runtime water checkpointing.

Returns

True for attached standalone RK2 owner or common source with runtime water enabled. Read-only, allocation-free; does not validate a complete boundary or save/restore anything.

Here is the call graph for this function:

Here is the caller graph for this function:

saveCheckpoint()

std::string openswmm::twoD::SurfaceRouter2D::saveCheckpoint	(	const SimulationContext &	ctx,
		const std::string &	path ) const

Internal router/CPU/source boundary; not a full-project hotstart.

Serialize and publish a qualified source/router or joint component boundary.

Serialize and publish a qualified source/router or joint component boundary.

• Argument ctx (in): Exact attached context, held stable/exclusive through qualification/serialization.
• Argument path (in): Writable destination with existing parent; existing record must match profile magic.

  Returns

  Empty on success, otherwise owner, qualification, archive, publication or caught standard exception diagnostic. Engine-owned managed RK2/joint sessions require engine checkpoint entry.

  Note

  Does not flush pending physics or advance clocks. Component scope includes qualified router, CPU/source, optional channel/native hydraulic state; whole-engine/output state is separate. Publisher uses exclusive temporary+rename and may leave temporary files on exceptional filesystem failure.

  Parameters

  [in]	ctx	Exact attached context, held stable/exclusive through qualification/serialization.
  [in]	path	Writable destination with existing parent; existing record must match profile magic.

  Returns

  Empty on success, otherwise owner, qualification, archive, publication or caught standard exception diagnostic. Engine-owned managed RK2/joint sessions require engine checkpoint entry.

  Note

  Does not flush pending physics or advance clocks. Component scope includes qualified router, CPU/source, optional channel/native hydraulic state; whole-engine/output state is separate. Publisher uses exclusive temporary+rename and may leave temporary files on exceptional filesystem failure.

setCommonSourceStage()

void openswmm::twoD::SurfaceRouter2D::setCommonSourceStage	(	SimulationContext &	ctx,
		CommonSourceStage &	stage )

Internal qualification hook: externally owned stage, all cells managed, wall boundaries, no live 1D exchanges. Does not activate authored ownership.

Attach a borrowed all-cell source stage to a fresh first-order CPU router.

Attach a borrowed all-cell source stage to a fresh first-order CPU router.

• Argument ctx (in,out): Exact matching initial context without live network coupling.
• Argument stage (in,out): Prepared matching mesh/surface/subsurface owner spanning all cells; borrowed for later routing/checkpoint and must outlive attachment with stable identities.

  Note

  Delegates attachment validation/setup with no hydraulic joint owner. Does not activate authored recharge ownership or advance physics. Throws std::invalid_argument on profile/phase refusal and may allocate after partial preparation; exclusive fresh lifecycle access required.

  Parameters

  [in,out]	ctx	Exact matching initial context without live network coupling.
  [in,out]	stage	Prepared matching mesh/surface/subsurface owner spanning all cells; borrowed for later routing/checkpoint and must outlive attachment with stable identities.

  Note

  Delegates attachment validation/setup with no hydraulic joint owner. Does not activate authored recharge ownership or advance physics. Throws std::invalid_argument on profile/phase refusal and may allocate after partial preparation; exclusive fresh lifecycle access required.

setJointSourceStage()

void openswmm::twoD::SurfaceRouter2D::setJointSourceStage	(	SimulationContext &	ctx,
		CommonSourceStage &	stage,
		Router &	hydraulic )

Internal water-only joint DW/source checkpoint, including non-outfall surface exchange and pending node delivery. Attach after both routers and LID initialization; the hydraulic router must track accepted steps. External providers, node beds and whole-engine/output state remain excluded.

Attach matching first-order source and tracked native hydraulic owners for joint checkpoints.

Attach matching first-order source and tracked native hydraulic owners for joint checkpoints.

• Argument ctx (in,out): Exact prepared initial context shared by both routers and LID setup.
• Argument stage (in,out): Borrowed matching all-cell common-source stage, stable/alive through routing.
• Argument hydraulic (in,out): Borrowed initialized tracked hydraulic owner sharing ctx; must remain alive.

  Note

  Delegates joint ownership, quality/thermal, LID, boundary and coupling qualification. Disallows unsupported external head ramps/conduit owners. No physics advance; refusal throws, allocation or delegated setup may leave partial preparation. Call serially after native routers/LID initialize.

  Parameters

  [in,out]	ctx	Exact prepared initial context shared by both routers and LID setup.
  [in,out]	stage	Borrowed matching all-cell common-source stage, stable/alive through routing.
  [in,out]	hydraulic	Borrowed initialized tracked hydraulic owner sharing ctx; must remain alive.

  Note

  Delegates joint ownership, quality/thermal, LID, boundary and coupling qualification. Disallows unsupported external head ramps/conduit owners. No physics advance; refusal throws, allocation or delegated setup may leave partial preparation. Call serially after native routers/LID initialize.

setSourceResultHistory()

void openswmm::twoD::SurfaceRouter2D::setSourceResultHistory

(

SourceResultHistory &

history

)

Attach a fresh borrowed accepted-source history recorder through the CPU source marcher.

• Argument history (in,out): Prepared compatible recorder; borrowed and must outlive attachment/use.

  Note

  Requires common stage and disallows directly attaching to an engine-owned joint checkpoint session. Delegates recorder freshness/identity/boundary validation and throws on refusal. No physics or calendar advance; exclusive source/history/lifecycle access, no duplicate recorder ownership.

  Parameters

  [in,out]

  history

  Prepared compatible recorder; borrowed and must outlive attachment/use.

  Note

  Requires common stage and disallows directly attaching to an engine-owned joint checkpoint session. Delegates recorder freshness/identity/boundary validation and throws on refusal. No physics or calendar advance; exclusive source/history/lifecycle access, no duplicate recorder ownership.

Here is the call graph for this function:

state() [1/2]

const SurfaceStateData & openswmm::twoD::SurfaceRouter2D::state ( ) const

inlinenoexcept

Access surface state (read-only).

Borrow the owned canonical surface water/native/thermal state and pending producer receipts.

Returns

Reference to this router's member, with mutability determined by the overload. No copy, validation or ownership transfer occurs. Router must remain alive/stable; initialization, restore, move/replacement and vector edits can invalidate contained views.

Note

Mutable access requires exclusive ownership and preservation of prepared topology, row shapes, unit convention, source clocks and receipt phase. Authoring edits may require resolution/rebuild before routing. This getter performs no automatic cache/solver synchronization or physical update.

Here is the caller graph for this function:

state() [2/2]

SurfaceStateData & openswmm::twoD::SurfaceRouter2D::state ( )

inlinenoexcept

Access surface state (mutable, for forcing).

Borrow the owned canonical surface water/native/thermal state and pending producer receipts.

Returns

Reference to this router's member, with mutability determined by the overload. No copy, validation or ownership transfer occurs. Router must remain alive/stable; initialization, restore, move/replacement and vector edits can invalidate contained views.

Note

Mutable access requires exclusive ownership and preservation of prepared topology, row shapes, unit convention, source clocks and receipt phase. Authoring edits may require resolution/rebuild before routing. This getter performs no automatic cache/solver synchronization or physical update.

step()

void openswmm::twoD::SurfaceRouter2D::step	(	SimulationContext &	ctx,
		double	dt,
		double	t )

Advance the 2D surface routing by one SWMM routing step.

Invoke the pre-outfall and post-routing surface hooks consecutively.

Sequence:

1. Update outfall boundary heads from 2D state (before 1D routing)
2. After 1D routing: compute coupling exchange flows
3. Update 2D rainfall from system gages
4. Advance the explicit 2D solver by dt_swmm
5. Transfer outfall discharges into 2D cells
6. Update statistics

• Argument ctx: Simulation context.
• Argument dt: SWMM routing timestep (seconds).
• Argument t: Current simulation time (seconds from start).

Invoke the pre-outfall and post-routing surface hooks consecutively.

• Argument ctx (in,out): Matching prepared engine context with accepted hydraulic state for post-routing.
• Argument dt (in): Positive finite routing duration s expected by prepared exchange owners.
• Argument t (in): Elapsed routing interval start s, matching completed/pending source clock.

  Note

  Inactive router returns. This convenience wrapper does not run the 1D hydraulic solve; SWMMEngine interleaves that solve between the separate hooks. Hook validation/exceptions and partial-state effects apply; caller must enforce the intended hydraulic chronology and exclusive context/router access. Does not itself advance the engine calendar.

  Parameters

  [in,out]	ctx	Matching prepared engine context with accepted hydraulic state for post-routing.
  [in]	dt	Positive finite routing duration s expected by prepared exchange owners.
  [in]	t	Elapsed routing interval start s, matching completed/pending source clock.

  Note

  Inactive router returns. This convenience wrapper does not run the 1D hydraulic solve; SWMMEngine interleaves that solve between the separate hooks. Hook validation/exceptions and partial-state effects apply; caller must enforce the intended hydraulic chronology and exclusive context/router access. Does not itself advance the engine calendar.

Here is the call graph for this function:

Here is the caller graph for this function:

subcatchRecharge()

const std::vector< double > & openswmm::twoD::SurfaceRouter2D::subcatchRecharge ( ) const

inlinenoexcept

Ledger-consistent cumulative infiltrated depth per cell (m).

Drains the SAME SurfaceStateData::infil_applied accumulator that MassBalance2D::infil_out books — the depth the marcher actually removed, summed as it was removed — so sum(infilCumulative()[i] * tri_area[i]) == infil_out holds by construction. Prefer this over Infil2D::cumulative(), which is the unramped capacity the kernels offered and therefore exceeds the applied loss on drying cells. Empty when no [2D_INFILTRATION*] model resolved.

U3 (track I-b) — per-subcatchment 2D infiltration recharge pending delivery to the legacy aquifer, in m³.

Filled in accumulateMassBalance() for every cell whose resolved row says SUBCATCH_AQUIFER and that a subcatchment contains. drainSubcatchRecharge() hands it to the runoff step (which adds it to that subcatchment's infiltration rate for GWSolver::execute) and zeroes it, so the accumulator is drained exactly once per runoff step. Empty when the destination is not in use.

Borrow unconsumed infiltration recharge awaiting legacy subcatchment delivery.

Returns

Router-owned const reference in m3 per original subcatchment. Valid only during stable router access; initialization, restore, replacement or corresponding producer updates can change contents/invalidate views. No copy, reset, queue consumption, ownership transfer or synchronization occurs in this query.

subsurface() [1/2]

const SubsurfaceSolver & openswmm::twoD::SurfaceRouter2D::subsurface ( ) const

inlinenoexcept

Borrow the owned groundwater solver with SI hydraulic state, native rows and paired physical/source/LID receipts.

Returns

Reference to this router's member, with mutability determined by the overload. No copy, validation or ownership transfer occurs. Router must remain alive/stable; initialization, restore, move/replacement and vector edits can invalidate contained views.

Note

Mutable access requires exclusive ownership and preservation of prepared topology, row shapes, unit convention, source clocks and receipt phase. Authoring edits may require resolution/rebuild before routing. This getter performs no automatic cache/solver synchronization or physical update.

subsurface() [2/2]

SubsurfaceSolver & openswmm::twoD::SurfaceRouter2D::subsurface ( )

inlinenoexcept

The running kernel. active() is false until [2D_AQUIFER] resolves.

Borrow the owned groundwater solver with SI hydraulic state, native rows and paired physical/source/LID receipts.

Returns

Reference to this router's member, with mutability determined by the overload. No copy, validation or ownership transfer occurs. Router must remain alive/stable; initialization, restore, move/replacement and vector edits can invalidate contained views.

Note

Mutable access requires exclusive ownership and preservation of prepared topology, row shapes, unit convention, source clocks and receipt phase. Authoring edits may require resolution/rebuild before routing. This getter performs no automatic cache/solver synchronization or physical update.

Here is the caller graph for this function:

surfaceQuality() [1/2]

const SurfaceQuality2D & openswmm::twoD::SurfaceRouter2D::surfaceQuality ( ) const

inlinenoexcept

Borrow the owned land-use coverage/buildup/washoff/sweeping authoring and runtime ledgers.

Returns

Reference to this router's member, with mutability determined by the overload. No copy, validation or ownership transfer occurs. Router must remain alive/stable; initialization, restore, move/replacement and vector edits can invalidate contained views.

Note

Mutable access requires exclusive ownership and preservation of prepared topology, row shapes, unit convention, source clocks and receipt phase. Authoring edits may require resolution/rebuild before routing. This getter performs no automatic cache/solver synchronization or physical update.

surfaceQuality() [2/2]

SurfaceQuality2D & openswmm::twoD::SurfaceRouter2D::surfaceQuality ( )

inlinenoexcept

S7: cell coverages / buildup / washoff / sweeping (authoring + state).

Borrow the owned land-use coverage/buildup/washoff/sweeping authoring and runtime ledgers.

Returns

Reference to this router's member, with mutability determined by the overload. No copy, validation or ownership transfer occurs. Router must remain alive/stable; initialization, restore, move/replacement and vector edits can invalidate contained views.

Note

Mutable access requires exclusive ownership and preservation of prepared topology, row shapes, unit convention, source clocks and receipt phase. Authoring edits may require resolution/rebuild before routing. This getter performs no automatic cache/solver synchronization or physical update.

surfaceReactionLoss()

double openswmm::twoD::SurfaceRouter2D::surfaceReactionLoss ( int row ) const

noexcept

Signed native surface reaction loss for the qualified RK2 owner.

Read a CPU RK2 surface native reaction loss without consuming its receipt.

Read a CPU RK2 surface native reaction loss without consuming its receipt.

• Argument row (in): Zero-based canonical native row; invalid rows return zero through CPU owner.

  Returns

  Cumulative signed native inventory loss for supported CPU row, otherwise zero (including plugin/no-2D build). No conversion, allocation, physical/clock mutation or report delivery occurs.

  Parameters

  [in]

  row

  Zero-based canonical native row; invalid rows return zero through CPU owner.

  Returns

  Cumulative signed native inventory loss for supported CPU row, otherwise zero (including plugin/no-2D build). No conversion, allocation, physical/clock mutation or report delivery occurs.

Here is the call graph for this function:

Here is the caller graph for this function:

threadWarnings()

const std::vector< std::string > & openswmm::twoD::SurfaceRouter2D::threadWarnings ( ) const

inlinenoexcept

Thread-count advisories produced by initialize() (THREADS above the machine limits, triangle gate reducing an explicit request). The engine forwards them to the report warnings and the host warning callback.

Borrow initialization thread-count advisories.

Returns

Router-owned const reference in owned diagnostic strings. Valid only during stable router access; initialization, restore, replacement or corresponding producer updates can change contents/invalidate views. No copy, reset, queue consumption, ownership transfer or synchronization occurs in this query.

totalExchangeFlow()

double openswmm::twoD::SurfaceRouter2D::totalExchangeFlow

(

)

const

Get total exchange flow (sum of coupling flows, m³/s).

Sum the current held surface coupling source-rate field over cell areas.

Sum the current held surface coupling source-rate field over cell areas.

Returns

Sum coupling_flux[i]*area[i] in m3/s, positive into surface. This is not the accepted per-point integrated drain receipt and does not consume any queue.

Note

Requires matching prepared cell arrays; active flag is not checked. Read-only, no validation, reconstruction, allocation, physical or clock change.

Returns

Sum coupling_flux[i]*area[i] in m3/s, positive into surface. This is not the accepted per-point integrated drain receipt and does not consume any queue.

Note

Requires matching prepared cell arrays; active flag is not checked. Read-only, no validation, reconstruction, allocation, physical or clock change.

Here is the call graph for this function:

Here is the caller graph for this function:

totalVolume()

double openswmm::twoD::SurfaceRouter2D::totalVolume

(

)

const

Get total 2D surface volume (sum of depth * area).

Sum canonical surface water volume over all prepared mesh cells.

Sum canonical surface water volume over all prepared mesh cells.

Returns

Surface storage m3, in ascending cell order; no depth*area reconstruction or finite repair.

Note

Requires state.volume extent>=n_cells and stable exclusive/const-consistent model. No physics, allocation or clock change; active flag is not checked.

Returns

Surface storage m3, in ascending cell order; no depth*area reconstruction or finite repair.

Note

Requires state.volume extent>=n_cells and stable exclusive/const-consistent model. No physics, allocation or clock change; active flag is not checked.

Here is the call graph for this function:

Here is the caller graph for this function:

updateOutfallsPreRouting()

void openswmm::twoD::SurfaceRouter2D::updateOutfallsPreRouting	(	SimulationContext &	ctx,
		double	dt = 0.0 )

Pre-routing hook: update outfall boundaries from 2D surface heads.

Freeze outfall tailwater and donor reservations before the matching 1D routing solve.

Must be called BEFORE the 1D routing step, after setOutfallDepths().

• Argument ctx: Simulation context.

Freeze outfall tailwater and donor reservations before the matching 1D routing solve.

• Argument ctx (in,out): Matching live node/hydraulic state, with native outfall depth setup completed.
• Argument dt (in): Routing interval duration s; default zero supplies no positive donor interval and cannot qualify a live joint-outfall tracked interval.

  Note

  Inactive router returns. Joint outfalls require a ready source boundary, unused reservation, matching context/time and tracked hydraulic interval. Updates native tailwater, captures prepared outfall budgets, and relaxes tracking ponds without changing their held pond volume. Throws on joint chronology or delegated validation; partial preparation is possible. Exclusive owners required.

  Parameters

  [in,out]	ctx	Matching live node/hydraulic state, with native outfall depth setup completed.
  [in]	dt	Routing interval duration s; default zero supplies no positive donor interval and cannot qualify a live joint-outfall tracked interval.

  Note

  Inactive router returns. Joint outfalls require a ready source boundary, unused reservation, matching context/time and tracked hydraulic interval. Updates native tailwater, captures prepared outfall budgets, and relaxes tracking ponds without changing their held pond volume. Throws on joint chronology or delegated validation; partial preparation is possible. Exclusive owners required.

Here is the call graph for this function:

Here is the caller graph for this function:

validateRuntimeWater()

std::string openswmm::twoD::SurfaceRouter2D::validateRuntimeWater	(	const RuntimeSources &	surface,
		const RuntimeSources &	groundwater,
		const RuntimeForcings &	forcing,
		double	time,
		const BoundaryData *	boundary = nullptr ) const

Validate copied runtime water proposals through the attached common-source owner.

Ask an attached common-source owner to admit proposed copied runtime water prescriptions.

• Argument time (in): Proposed finite elapsed boundary s, matching the prepared source clock.
• Argument boundary (in): Optional borrowed proposed boundary; required by its active profile.

  Returns

  Delegated diagnostic, or empty without validation when no common stage is attached.

  Note

  First three unnamed const references are proposed surface sources, groundwater sources and held forcings, in that order, with matching cell/native layouts. No adoption/physics advance. Read-only stable views and exclusive source lifecycle required; allocation/delegated checks may throw.

  Parameters

  [in]	surface	Proposed immutable surface runtime rows and receipts.
  [in]	groundwater	Proposed groundwater runtime rows and receipts.
  [in]	forcing	Proposed held forcing rows and accepted rain receipts.
  [in]	time	Finite elapsed proposed boundary s, matching the source owner's required phase.
  [in]	boundary	Optional borrowed proposed boundary owner; required by active boundary profile.

  Returns

  Delegated diagnostic or empty on qualification. With no common stage returns empty without validating any proposed record, including the standalone RK2 route.

  Note

  Read-only proposal check; allocations/delegated validation may throw. Matching prepared row/cell identities and exclusive stable source views are required; no adoption/advance occurs.

Here is the call graph for this function:

Here is the caller graph for this function:

Friends And Related Symbol Documentation

openswmm::SWMMEngine

friend class openswmm::SWMMEngine

friend

---

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

• /home/runner/work/openswmm.engine/openswmm.engine/src/engine/2d/SurfaceRouter2D.hpp
• /home/runner/work/openswmm.engine/openswmm.engine/src/engine/2d/SurfaceRouter2D.cpp
• /home/runner/work/openswmm.engine/openswmm.engine/src/engine/2d/SurfaceRouterCheckpoint.cpp