Namespaces
namespace	detail

Functions
std::vector< LidNodeLayer >	layers (const SimulationContext &ctx, int control)
	Copy an authored node layer stack or adapt a supported conventional LID control.

bool	validLayer (const LidNodeLayer &l)
	Check one authored node-layer material record.

std::string	validateStack (const std::vector< LidNodeLayer > &stack)
	Validate layer material/order and optional Richards requirements.

double	thickness (const std::vector< LidNodeLayer > &stack)
	Sum all physical layer thicknesses while excluding the bottom boundary record.

void	readNodes (SimulationContext &ctx, const std::vector< std::string > &lines)
	Parse LID storage-node assignments and bottom-boundary modes.

void	readOutlets (SimulationContext &ctx, const std::vector< std::string > &lines)
	Parse hydraulic outlet anchors to numbered LID layer interfaces.

double	portOffset (const SimulationContext &ctx, int link, int node)
	Resolve the actual hydraulic port elevation relative to a selected node invert.

void	validate (SimulationContext &ctx)
	Validate node-LID model references, layers, supported physics and anchored geometry.

void	sync (SimulationContext &ctx, int control)
	Synchronize dependent storage depth and authored outlet anchors after a control edit.

bool	active (const SimulationContext &ctx, int node)
	Check whether a node has initialized physical LID cells.

double	heldVolume (const SimulationContext &ctx, int node)
	Read retained node-LID water outside the mobile hydraulic volume.

void	initializeInfiltration (SimulationContext &ctx, int node)
	Initialize/reconstruct node-LID surface Green-Ampt history from physical moisture.

void	initialize (SimulationContext &ctx)
	Build node-LID hydraulic cells and initial retained/mobile water state.

void	prepareStep (SimulationContext &ctx, double dt, double evaporation)
	Prepare one node-LID moisture/routing interval before hydraulic mutation.

void	prepareStepAfterMesh (SimulationContext &ctx, double dt, double evaporation)
	Prepare mixed-mode LID rows after Mesh Richards owners accepted this interval.

void	finishStep (SimulationContext &ctx)
	Finish all node-LID port transfers at a common accepted boundary.

void	finishRichardsNodes (SimulationContext &ctx, double start, double end, const std::vector< int > &nodes)
	Finish exactly one connected accepted Mesh Richards owner cohort.

LidNodeBottom	bottomMode (const SimulationContext &c, int node)
	Read the assigned bottom-boundary policy for a node.

double	bottomConductivity (const SimulationContext &c, int storage_row)
	Select the authored conductivity driving native storage bottom exfiltration.

double	bottomCloggingFactor (const SimulationContext &c, int storage_row)
	Evaluate the node-LID bottom clogging multiplier from cumulative treated water.

int	portCell (const LidNodeState &state, double offset)
	Map a hydraulic port offset to a physical LID cell with stable interface ownership.

void	resetPorts (SimulationContext &ctx)
	Clear trial port-transfer accumulators before a fresh hydraulic iteration.

double	portDepth (const SimulationContext &ctx, int node, double offset)
	Read the port hydraulic head as a node-relative depth.

double	exchangePorts (SimulationContext &ctx, int link, double flow, double dt)
	Limit and book one trial link transfer through LID mobile/retained ports.

bool	richardsMode (const SimulationContext &ctx, int node)
	Read the initialized LID Richards mode flag for a node.

double	exchangeRichardsPorts (SimulationContext &ctx, int link, double flow, double dt)
	Limit and book a link transfer involving Richards or mixed retained-water ports.

void	prepareRichardsStep (SimulationContext &ctx, double dt, double evaporation, bool mesh_prepared=false)
	Advance non-Mesh Richards owners privately, then publish the whole successful batch.

void	refreshRichardsState (SimulationContext &ctx, int row)
	Recompute one initialized Richards row pressure, moisture and retained inventory.

void	readRichards (SimulationContext &ctx, const std::vector< std::string > &lines)
	Parse node-LID Richards numerical options and layer retention/storage materials.

bool	validateRichardsRouting (const SimulationContext &ctx, double dt)
	Preflight the common accepted Mesh Richards routing interval without mutation.

bool	validTreatment (const SimulationContext &ctx, const LidLayerTreatment &rule, std::string &error)
	Validate a layer pollutant rule and optional legacy treatment expression.

void	readTreatment (SimulationContext &ctx, const std::vector< std::string > &lines)
	Parse authored node-LID layer treatment rows.

void	prepareQuality (SimulationContext &ctx, double dt)
	Apply accepted LID vertical/retained-port transfers and resident decay to pollutant mass.

void	prepareOutletQuality (SimulationContext &ctx, double dt, bool book_reaction)
	Refresh mobile outlet treatment against the current coupled node mixture.

bool	receiveQuality (SimulationContext &ctx, int node, int link, double volume, int pollutant, double mass, double dt)
	Divert the retained fraction of an arriving pollutant load into its LID port cell.

double	outletQuality (const SimulationContext &ctx, int node, int link, int pollutant, double fallback)
	Read a cached treated outlet concentration with a caller fallback.

double	heldMass (const SimulationContext &ctx, int node, int pollutant)
	Sum retained pollutant inventory across all initialized LID cells.

void	prepareMeshRichardsStep (SimulationContext &ctx, twoD::SubsurfaceSolver &gw, twoD::SurfaceStateData &surface, double dt, double evaporation)
	Prepare global-cadence Richards LID nodes and retain completed aquifer receipts.

twoD::RichardsBedAcceptance	acceptRichardsNodesAtFiring (SimulationContext &ctx, twoD::SubsurfaceSolver &gw, twoD::SurfaceStateData &surface, double start, double end, double evaporation, const std::vector< int > &nodes)
	Settle a closed owner interval and publish corresponding real Richards node state.

twoD::RichardsBedAcceptance	acceptRichardsNodesForTier (SimulationContext &ctx, twoD::SubsurfaceSolver &gw, twoD::SurfaceStateData &surface, int tier, double start, double end, double evaporation, const std::vector< int > &nodes)
	Replace one due groundwater tier firing with a paired Richards-node settlement.

twoD::RichardsBedAcceptance	routeRichardsNodesForTierWindow (SimulationContext &ctx, Router &router, twoD::SubsurfaceSolver &gw, twoD::SurfaceStateData &surface, int tier, double start, double end, const std::vector< double > &step_ends, double evaporation, const std::vector< int > &nodes)
	Trial and publish a fixed-forcing native dynamic-wave/Richards tier window.

Function Documentation

◆ acceptRichardsNodesAtFiring()

twoD::RichardsBedAcceptance openswmm::lidnode::acceptRichardsNodesAtFiring	(	SimulationContext &	ctx,
		twoD::SubsurfaceSolver &	gw,
		twoD::SurfaceStateData &	surface,
		double	start,
		double	end,
		double	evaporation,
		const std::vector< int > &	nodes )

Settle a closed owner interval and publish corresponding real Richards node state.

Parameters

[in,out]	ctx	Compatible initialized water-only LID-node context; each selected node is an initialized STORAGE Mesh column with completed clock equal start, no pending finish/capture/mobile/port trial, finite qualified geometry and forcing.
[in,out]	gw	Matching active aquifer with one resolved exchange bed per node and sufficient paired directional reservations; thermal owner required for heat.
[in,out]	surface	Compatible surface state settled by the groundwater firing.
	start	Finite nonnegative elapsed simulation seconds, exact prior owner boundary.
	end	Finite elapsed seconds strictly after start, with representable end-start.
	evaporation	Finite nonnegative potential ft/s held over this interval.
	nodes	Nonempty unique valid node indices; copied/sorted internally. Caller supplies the complete cohort required by the lower-level firing acceptance.

Returns: Acceptance reports/receipts or nonempty error. Trial aquifer/surface copies and all real-node publication drafts qualify before ordinary publication. Normal refusal retains real water states; exceptions before publication can propagate. Successful return marks node mesh_pending_finish: route accepted ports and finish exactly once. Does not advance the global context clock or route links itself. No qualified ponding/flooding, pollutant/age/reaction or joint restart path here; caller serializes stable context/solver ownership and retained thermal references.

◆ acceptRichardsNodesForTier()

twoD::RichardsBedAcceptance openswmm::lidnode::acceptRichardsNodesForTier	(	SimulationContext &	ctx,
		twoD::SubsurfaceSolver &	gw,
		twoD::SurfaceStateData &	surface,
		int	tier,
		double	start,
		double	end,
		double	evaporation,
		const std::vector< int > &	nodes )

Replace one due groundwater tier firing with a paired Richards-node settlement.

Parameters

[in,out]	ctx	Compatible water-only initialized storage/LID context with selected owners closed at start and no unresolved capture/port/finish trials.
[in,out]	gw	Active matching tiered aquifer, qualified bed reservations and thermal owner when heat is enabled. Includes ordinary due cells in that tier.
[in,out]	surface	Matching surface state used by the accepted firing.
	tier	Nonnegative due tier index; negative returns an error before delegation.
	start	Finite nonnegative exact accepted elapsed-second boundary.
	end	Finite elapsed-second endpoint strictly after start.
	evaporation	Finite nonnegative held potential ft/s.
	nodes	Nonempty unique valid Mesh Richards STORAGE owners, complete for the requested tier. Uses the same qualification/publication and required subsequent routing/finish contract as acceptRichardsNodesAtFiring().

Returns: Reports/receipts or error; normal refusal retains real candidate water states. Exceptions outside draft conversion may propagate. Does not itself route links or advance the global context clock; serialize all related operations.

◆ active()

bool openswmm::lidnode::active	(	const SimulationContext &	ctx,
		int	node )

Check whether a node has initialized physical LID cells.

Parameters

[in]	ctx	Borrowed resolved context with coherent subtype/configuration/runtime arrays; no pointer is retained.
[in]	node	Global node index resolved through storage_row.

Returns: True for a storage join whose runtime cells are nonempty; false without that join. Assignment alone is insufficient.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ bottomCloggingFactor()

double openswmm::lidnode::bottomCloggingFactor	(	const SimulationContext &	c,
		int	storage_row )

Evaluate the node-LID bottom clogging multiplier from cumulative treated water.

Pore capacity excludes SURFACE cells and uses native ft3 consistently; configured clogging factor is dimensionless. Does not apply monthly conductivity or mutate cumulative treated volume.

Parameters

[in]	c	Borrowed configuration and initialized cell pore volumes/treated_volume.
[in]	storage_row	Valid dense storage row or negative absent sentinel.

Returns: max(0,1-treated_volume/(clog_factor*porous_volume)), or one when no positive bottom clogging law/porous capacity applies.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ bottomConductivity()

double openswmm::lidnode::bottomConductivity	(	const SimulationContext &	c,
		int	storage_row )

Select the authored conductivity driving native storage bottom exfiltration.

No unit conversion, monthly factor or clogging is applied here. Explicit SEALED/MESH_AQUIFER suppress the ordinary exfiltration path; their owner supplies any qualified exchange separately.

Parameters

[in]	c	Borrowed resolved LID/storage configuration.
[in]	storage_row	Valid dense storage row or a negative absent sentinel; upper bounds are unchecked.

Returns: Project rainfall-intensity conductivity from an explicit BOTTOM row or storage exfil_ksat; zero for negative rows or assigned non-CURRENT bottoms.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ bottomMode()

LidNodeBottom openswmm::lidnode::bottomMode	(	const SimulationContext &	c,
		int	node )

Read the assigned bottom-boundary policy for a node.

Parameters

[in]	c	Borrowed resolved configuration with valid subtype arrays.
[in]	node	Global node index; invalid values use the default.

Returns: Assigned CURRENT/SEALED/MESH_AQUIFER mode, or CURRENT for an invalid/nonassigned node.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ exchangePorts()

double openswmm::lidnode::exchangePorts	(	SimulationContext &	ctx,
		int	link,
		double	flow,
		double	dt )

Limit and book one trial link transfer through LID mobile/retained ports.

Delegates if either endpoint uses Richards. Ordinary LID donors below the water table share old mobile+net-lateral+trial allowance; above-table ports draw retained water down to wilting with a media saturation throttle. Receivers hold available above-table cell pore water and leave the remainder mobile. Books equal hydraulic compensating inflow/outflow plus per-cell signed water/quality receipts so retained water moves once. Does not commit theta until finish; resetPorts starts a new Picard trial, so every candidate must rebuild its ledger consistently.

Parameters

[in,out]	ctx	Borrowed initialized native hydraulic/node-LID context with valid subtype joins and dimension-aligned runtime arrays; caller serializes lifecycle/routing phases.
[in]	link	Valid global hydraulic link index with valid endpoint nodes and actual crest/offset joins.
[in]	flow	Signed proposed aggregate flow in native ft3/s, positive node1 to node2.
[in]	dt	Finite positive accepted routing interval in seconds.

Returns: Accepted signed flow in ft3/s; nonpositive dt, zero flow or no active LID endpoints return the proposal unchanged.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ exchangeRichardsPorts()

double openswmm::lidnode::exchangeRichardsPorts	(	SimulationContext &	ctx,
		int	link,
		double	flow,
		double	dt )

Limit and book a link transfer involving Richards or mixed retained-water ports.

Mesh endpoints must share a pending accepted owner interval with matching dt and cannot already await routed finish; violations throw before transfer mutation. Richards retained donors preserve water below the pressure needed to reach the port elevation; Richards receivers admit water only up to donor absolute head through their retention/storage relation. Ordinary media donors retain the saturation throttle and wilting limit. Books signed per-cell port/quality water plus compensating hydraulic inflow/outflow/mobile receipts; does not commit theta/water until finish. General numeric/layout/material preconditions remain caller-owned.

Parameters

[in,out]	ctx	Borrowed initialized native node-LID context with coherent storage/cell/material and link/node joins; serial lifecycle ownership is required.
[in]	link	Valid global link with valid endpoint nodes, initialized port cells and materials.
[in]	flow	Finite signed aggregate ft3/s proposal, positive node1 to node2.
[in]	dt	Finite positive routing interval in seconds; required even for non-Mesh direct calls.

Returns: Accepted signed aggregate ft3/s after donor and receiver-head storage limits.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ finishRichardsNodes()

void openswmm::lidnode::finishRichardsNodes	(	SimulationContext &	ctx,
		double	start,
		double	end,
		const std::vector< int > &	nodes )

Finish exactly one connected accepted Mesh Richards owner cohort.

Validates all selected interval receipts and requires every connected Mesh endpoint belongs to the same selected cohort. Sorts storage rows, privately qualifies pending routed port state then finishes only those rows. Other LID rows/groundwater clocks remain untouched. Throws on missing/duplicate/wrong owner, interval or connected-cohort mismatch before finish publication; allocation can throw.

Parameters

[in,out]	ctx	Borrowed initialized native hydraulic/node-LID context with valid subtype joins and dimension-aligned runtime arrays; caller serializes lifecycle/routing phases.
[in]	start	Finite accepted interval start in native simulation seconds.
[in]	end	Accepted interval end in seconds matching every selected owner.
[in]	nodes	Nonempty unique valid node indices, each a MESH_AQUIFER Richards owner.

Here is the call graph for this function:

◆ finishStep()

void openswmm::lidnode::finishStep ( SimulationContext & ctx )

Finish all node-LID port transfers at a common accepted boundary.

First checks every Mesh Richards owner agrees on accepted interval, then qualifies all pending Mesh routed port states before publishing any row. Applies non-Mesh retained/Richards deltas, refreshes retained inventory/capacity/head/infiltration, restores captured lateral forcing and books ET/bottom-loss ft3. Mesh completion clears owned pending routing/port state. Call exactly once after successful routing; repeated calls can double-book non-Mesh port/loss receipts. Does not advance the global clock.

Parameters

[in,out] ctx Borrowed initialized native hydraulic/node-LID context with valid subtype joins and dimension-aligned runtime arrays; caller serializes lifecycle/routing phases.

Here is the call graph for this function:

◆ heldMass()

double openswmm::lidnode::heldMass	(	const SimulationContext &	ctx,
		int	node,
		int	pollutant )

Sum retained pollutant inventory across all initialized LID cells.

Sums every cell-major quality_mass entry for the pollutant. Before lazy mass allocation, falls back to heldVolume*current node concentration if available. Does not include mobile hydraulic node mass or pending unprocessed transfer rates.

Parameters

[in]	ctx	Borrowed coherent pollutant/node-LID state; no mutation or pointer retention.
[in]	node	Global node index resolved through storage_row.
[in]	pollutant	Requested pollutant index; invalid values return zero.

Returns: Engine mass basis concentration*ft3, or zero without storage/valid pollutant.

Here is the call graph for this function:

◆ heldVolume()

double openswmm::lidnode::heldVolume	(	const SimulationContext &	ctx,
		int	node )

Read retained node-LID water outside the mobile hydraulic volume.

Does not rescan cells or reconcile pending port deltas; query after the appropriate finish/publication phase for a completed inventory.

Parameters

[in]	ctx	Borrowed resolved context with coherent subtype/configuration/runtime arrays; no pointer is retained.
[in]	node	Global node index resolved through storage_row.

Returns: Cached retained water in native ft3, or zero for a non-storage node.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ initialize()

void openswmm::lidnode::initialize ( SimulationContext & ctx )

Build node-LID hydraulic cells and initial retained/mobile water state.

Resets every storage LID state and materializes valid assigned stacks in native ft geometry. Ordinary MEDIA uses five slices; Richards porous layers use configured cells_per_layer. Converts authored conductivity/suction, computes geometric volume/area and initial moisture, records invalid nonpositive areas, and initializes ordinary Green-Ampt or Richards water/pressure state. Invalid stacks are skipped after state reset; validation is a separate phase. Without 2D support a MESH_AQUIFER assignment appends an error and returns before initialization. Resets derived full volumes for later preparation; allocations can leave partial state.

Parameters

[in,out] ctx Borrowed initialized native hydraulic/node-LID context with valid subtype joins and dimension-aligned runtime arrays; caller serializes lifecycle/routing phases.

Here is the call graph for this function:

◆ initializeInfiltration()

void openswmm::lidnode::initializeInfiltration	(	SimulationContext &	ctx,
		int	node )

Initialize/reconstruct node-LID surface Green-Ampt history from physical moisture.

Clears history/entry marker, then enables only a SURFACE over positive-conductivity MEDIA. Initializes native Green-Ampt material, bounds empirical upper zone to the authored media layer and seeds deficit/upper water/saturation using current hydraulic depth and retained moisture. Used for pre-V10 hot starts; reconstructed history approximates prior wetting and is not an exact continuation of missing cumulative history.

Parameters

[in,out]	ctx	Borrowed initialized native hydraulic/node-LID context with valid subtype joins and dimension-aligned runtime arrays; caller serializes lifecycle/routing phases.
[in]	node	Valid storage node with initialized positive-area cells; unchecked storage row.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ layers()

std::vector< LidNodeLayer > openswmm::lidnode::layers	(	const SimulationContext &	ctx,
		int	control )

Copy an authored node layer stack or adapt a supported conventional LID control.

NODE copies its explicit layers. BC/RG/IT/PP adapt positive surface, PP pavement, soil and storage thicknesses, converting void ratios to pore fractions; conventional storage adds effectively free-draining aggregate plus a separate native-soil bottom law. Does not validate or convert the full stack to hydraulic feet; callers use validateStack and the appropriate unit conversion. Allocation can throw.

Parameters

[in]	ctx	Borrowed resolved LID controls; authored layer depths/conductivities remain in project rainfall/rain-depth units.
[in]	control	LID control index; negative/out-of-range values return an empty stack.

Returns: Owned layer copies; empty for unsupported types or absent NODE layers.

Here is the caller graph for this function:

◆ outletQuality()

double openswmm::lidnode::outletQuality	(	const SimulationContext &	ctx,
		int	node,
		int	link,
		int	pollutant,
		double	fallback )

Read a cached treated outlet concentration with a caller fallback.

Does not evaluate treatment, validate link/source incidence or change a cached value. Call after the appropriate retained/mobile preparation phase.

Parameters

[in]	ctx	Borrowed coherent pollutant/node-LID state; no mutation or pointer retention.
[in]	node	Global source node index resolved through storage_row.
[in]	link	Global link index in the link-major concentration cache.
[in]	pollutant	Pollutant index used in link*n_pollutants+pollutant; valid indices expected.
[in]	fallback	Untreated concentration in the same engine units.

Returns: Finite cached concentration when the flattened index is within storage, otherwise fallback.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ portCell()

int openswmm::lidnode::portCell	(	const LidNodeState &	state,
		double	offset )

Map a hydraulic port offset to a physical LID cell with stable interface ownership.

Intervals include the bottom and exclude the top after a 32*epsilon*max(1,abs(offset/bounds)) roundoff tolerance, so an exact shared interface belongs to the cell above. Physical near-interface differences larger than roundoff are not snapped.

Parameters

[in]	state	Initialized top-to-bottom positive-thickness native-ft cells; no mutation.
[in]	offset	Finite port elevation relative to the node bottom, in ft.

Returns: Matching cell index; -1 for empty cells, otherwise surface index zero if outside all intervals.

Here is the caller graph for this function:

◆ portDepth()

double openswmm::lidnode::portDepth	(	const SimulationContext &	ctx,
		int	node,
		double	offset )

Read the port hydraulic head as a node-relative depth.

Ordinary/non-LID returns nodes.depth. A retained SURFACE pool can raise its port head to bottom+theta/porosity*thickness. A porous Richards cell returns center elevation plus its native-ft pressure head. Uses current state, not pending port water; no state changes.

Parameters

[in]	ctx	Borrowed resolved context with coherent subtype/configuration/runtime arrays; no pointer is retained.
[in]	node	Valid global node index, unchecked.
[in]	offset	Finite physical port offset in ft, used for cell ownership.

Returns: Native ft head-depth for the selected hydraulic port.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ portOffset()

double openswmm::lidnode::portOffset	(	const SimulationContext &	ctx,
		int	link,
		int	node )

Resolve the actual hydraulic port elevation relative to a selected node invert.

Keeps same-node crest subtraction exact by adding only the invert difference. No geometry mutation or finite/index validation.

Parameters

[in]	ctx	Resolved native-ft link/node/subtype geometry with valid joins.
[in]	link	Valid global link index, unchecked.
[in]	node	Valid endpoint node index whose invert is the requested datum.

Returns: Native ft offset: physical weir/outlet crest translated from node1 datum, otherwise the matching endpoint offset.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ prepareMeshRichardsStep()

void openswmm::lidnode::prepareMeshRichardsStep	(	SimulationContext &	ctx,
		twoD::SubsurfaceSolver &	gw,
		twoD::SurfaceStateData &	surface,
		double	dt,
		double	evaporation )

Prepare global-cadence Richards LID nodes and retain completed aquifer receipts.

Parameters

[in,out]	ctx	Compatible initialized node/storage/LID geometry, held forcing and empty prior port/capture trials at current_time. Uses internal feet/ft3 at the node boundary and converts kernel columns/receipts to SI. Changes real accepted node state and later ordinary mixed-row preparation state.
[in,out]	gw	Active matching aquifer with resolved unique node-bed mappings and an enabled receipt owner; gross downward/upward receipts are reserved/queued for each receiving cell's later clock, not immediately netted into its water.
[in,out]	surface	Compatible shared surface owner, passed to acceptance; queued preparation itself does not advance surface/aquifer physical water.
	dt	Finite positive interval seconds from ctx.current_time.
	evaporation	Finite nonnegative potential ft/s for node evaporation.

Exceptions

std::runtime_error Missing receipt owner or acceptance/preparation refusal. With no Mesh Richards nodes delegates to ordinary prepareStep. Water-only routing is required (no pollutants, water age or configured reactions); heat additionally requires an active ground thermal owner. On successful preparation route once, then finishStep once. A later prepareStepAfterMesh exception can follow accepted node/receipt publication; this facade is not a rollback boundary. Build with OPENSWMM_HAS_2D and serialize all related model/solver operations.

Here is the caller graph for this function:

◆ prepareOutletQuality()

void openswmm::lidnode::prepareOutletQuality	(	SimulationContext &	ctx,
		double	dt,
		bool	book_reaction )

Refresh mobile outlet treatment against the current coupled node mixture.

Requires prepareQuality to size/cache link-major outlets. Reads current node concentrations and outgoing link direction, evaluates only treatment-bearing mobile ports, and preserves already-debited retained outlet concentrations. No hydraulic water or resident mass is removed here; optional ledger increment is (Cin-Cout)*abs(Q)*dt in the engine mass basis. No-pollutant calls are a no-op.

Parameters

[in,out]	ctx	Borrowed resolved pollutant/node-LID context with initialized hydraulic quality-water/transfer/port receipts and aligned legacy concentration/mass arrays.
[in]	dt	Positive routing seconds used by expression residence-time evaluation and optional mass booking.
[in]	book_reaction	True only for the final accepted mixture to add removal mass to qual_routing_reacted; false during repeated mixture trials.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ prepareQuality()

void openswmm::lidnode::prepareQuality	(	SimulationContext &	ctx,
		double	dt )

Apply accepted LID vertical/retained-port transfers and resident decay to pollutant mass.

Requires hydraulic preparation snapshots and accepted quality transfer/port receipts; rows lacking water snapshots are skipped. Lazily seeds per-cell concentration*ft3 inventories, conservatively transfers mobile/lateral/retained mass, leaves solute behind during ET, applies fixed/expression removal only at authored layer exits and books reaction/seep ledgers. Debits retained outlet mass once and caches its fixed link-major concentration. Applies background and layer decay (1/day converted to 1/s), returns updated mobile old concentration or preserves dry solute for later redissolution. Mutates incoming quality rate/volume ledgers and must run once per accepted interval; repeated calls double-process receipts. Allocation/expression failures can leave partial state.

Parameters

[in,out]	ctx	Borrowed resolved pollutant/node-LID context with initialized hydraulic quality-water/transfer/port receipts and aligned legacy concentration/mass arrays.
[in]	dt	Positive native routing seconds; <=0 or no pollutants is a no-op.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ prepareRichardsStep()

void openswmm::lidnode::prepareRichardsStep	(	SimulationContext &	ctx,
		double	dt,
		double	evaporation,
		bool	mesh_prepared = false )

Advance non-Mesh Richards owners privately, then publish the whole successful batch.

Without mesh_prepared rejects any Mesh Richards owner before collecting/capturing forcing. Converts other rows to private SI columns, advances the batch, rejects any failed report, constructs every native publication draft and only then swaps all drafts into live state. Solve/draft failure preserves live hydraulic/retained state; allocations and kernel diagnostics can throw. Does not advance the global clock or perform final routing-port finish.

Parameters

[in,out]	ctx	Borrowed initialized native node-LID context with coherent storage/cell/material and link/node joins; serial lifecycle ownership is required.
[in]	dt	Finite positive interval in seconds for the kernel and capture accounting.
[in]	evaporation	Nonnegative finite potential ET in native ft/s.
[in]	mesh_prepared	True only after matching Mesh owner preparation; preflights those intervals and skips their independently owned columns.

Here is the call graph for this function:

◆ prepareStep()

void openswmm::lidnode::prepareStep	(	SimulationContext &	ctx,
		double	dt,
		double	evaporation )

Prepare one node-LID moisture/routing interval before hydraulic mutation.

Nonpositive dt is a no-op. Prepares qualified non-Mesh Richards owners, then ordinary retained/mobile split: snapshots quality water/transfers, reconciles infiltration, captures positive top lateral water, removes retained ET down to wilting point and substeps vertical drainage with <=1-second intervals and shared donor/receiver capacity limits. Accepted transfers update Green-Ampt history. Reconciles mobile volume, derived capacity/head and temporarily subtracts captured lateral flow. finishStep must run once after routing to restore forcing and book receipts. Exceptions can leave partial ordinary state; Mesh owners require the paired prepareStepAfterMesh path.

Parameters

[in,out]	ctx	Borrowed initialized native hydraulic/node-LID context with valid subtype joins and dimension-aligned runtime arrays; caller serializes lifecycle/routing phases.
[in]	dt	Finite positive accepted routing interval in seconds.
[in]	evaporation	Finite nonnegative potential evaporation rate in native ft/s.

◆ prepareStepAfterMesh()

void openswmm::lidnode::prepareStepAfterMesh	(	SimulationContext &	ctx,
		double	dt,
		double	evaporation )

Prepare mixed-mode LID rows after Mesh Richards owners accepted this interval.

Requires validateRichardsRouting to confirm a prepared matching Mesh cohort, otherwise throws runtime_error. Skips Mesh columns already advanced by their owner, prepares other Richards and ordinary LID rows through the common path. Does not advance groundwater clocks or finish the Mesh owner; caller preserves the accepted interval ordering.

Parameters

[in,out]	ctx	Borrowed initialized native hydraulic/node-LID context with valid subtype joins and dimension-aligned runtime arrays; caller serializes lifecycle/routing phases.
[in]	dt	Finite positive accepted routing interval in seconds.
[in]	evaporation	Finite nonnegative potential evaporation rate in native ft/s.

Here is the call graph for this function:

◆ readNodes()

void openswmm::lidnode::readNodes	(	SimulationContext &	ctx,
		const std::vector< std::string > &	lines )

Parse LID storage-node assignments and bottom-boundary modes.

Requires finite initial saturation in [0,100], a storage node and no existing assignment. Unknown node/control names defer the entire row; malformed rows append diagnostics and processing continues. Valid rows replace only the corresponding configuration. Does not initialize physical cells or synchronize depths; partial successful rows remain when later input fails.

Parameters

[in,out]	ctx	Model name/subtype stores and LID assignment rows; errors/deferred_section_rows are appended.
[in]	lines	Authored [LID_NODES] lines: node control saturation-percent, optionally BOTTOM CURRENT\|SEALED\|MESH_AQUIFER.

Here is the call graph for this function:

◆ readOutlets()

void openswmm::lidnode::readOutlets	(	SimulationContext &	ctx,
		const std::vector< std::string > &	lines )

Parse hydraulic outlet anchors to numbered LID layer interfaces.

Layer number must fit signed int. Unknown link names defer the row; duplicate link anchors and malformed tokens append errors without aborting later rows. Physical endpoint ambiguity, actual layer range and current offset agreement are checked later by validate. No hydraulic offset is changed here.

Parameters

[in,out]	ctx	Model link names and LID outlet-anchor vector; errors/deferred rows are appended.
[in]	lines	[LID_NODE_OUTLETS] rows: link, positive integer physical layer number, TOP or BOTTOM.

Here is the call graph for this function:

◆ readRichards()

void openswmm::lidnode::readRichards	(	SimulationContext &	ctx,
		const std::vector< std::string > &	lines )

Parse node-LID Richards numerical options and layer retention/storage materials.

Unknown/unavailable explicit NODE stacks defer complete rows. OPTIONS enables the first stack row; material rows require a valid porous layer and kernel-valid retention parameters. Duplicate options/materials, trailing tokens and invalid values append errors while later rows continue. Stores kernel SI retention/pressure options as authored, not hydraulic-ft conversions. Does not initialize cells or advance a column.

Parameters

[in,out]	ctx	Borrowed initialized native node-LID context with coherent storage/cell/material and link/node joins; serial lifecycle ownership is required.
[in]	lines	[LID_RICHARDS] authored lines: control OPTIONS cells_per_layer atol rtol max_step, or control layer theta_r alpha n l specific_storage.

Here is the call graph for this function:

◆ readTreatment()

void openswmm::lidnode::readTreatment	(	SimulationContext &	ctx,
		const std::vector< std::string > &	lines )

Parse authored node-LID layer treatment rows.

Unresolved controls/stacks/pollutants defer whole rows. Rejects invalid/Bottom layer selection, rule bounds/syntax and duplicate pollutant rules per layer by appending errors; successful earlier rows remain installed. Converts percent removal to a fraction, retains decay/day and expression text. Does not initialize runtime pollutant inventories.

Parameters

[in,out]	ctx	Borrowed resolved pollutant/node-LID context with initialized hydraulic quality-water/transfer/port receipts and aligned legacy concentration/mass arrays.
[in]	lines	Rows: control, one-based layer, pollutant, removal-percent, decay per day, optional expression (a lone dash means absent).

Here is the call graph for this function:

◆ receiveQuality()

bool openswmm::lidnode::receiveQuality	(	SimulationContext &	ctx,
		int	node,
		int	link,
		double	volume,
		int	pollutant,
		double	mass,
		double	dt )

Divert the retained fraction of an arriving pollutant load into its LID port cell.

Uses clamp(port.volume/volume,0,1), adds held_rate*dt only when the flattened cell-mass index exists, and subtracts the held rate from node.qual_mass_in. Caller must ensure mass storage is initialized and invoke once per arriving load to preserve accounting. Does not consume or clear the port receipt.

Parameters

[in,out]	ctx	Borrowed resolved pollutant/node-LID context with initialized hydraulic quality-water/transfer/port receipts and aligned legacy concentration/mass arrays.
[in]	node	Valid receiving node index; no storage join returns false.
[in]	link	Global link identifying a positive accepted quality_ports receipt.
[in]	volume	Positive total arriving water volume in native ft3; <=0 returns false.
[in]	pollutant	Valid pollutant index, unchecked against the incoming node rate array.
[in]	mass	Arriving pollutant rate in engine concentration*ft3/s, despite the historical argument name.
[in]	dt	Positive routing seconds converting the diverted rate to retained mass.

Returns: True on the first matching positive port, even if retained mass storage was not sized; false when none exists.

Here is the call graph for this function:

◆ refreshRichardsState()

void openswmm::lidnode::refreshRichardsState	(	SimulationContext &	ctx,
		int	row )

Recompute one initialized Richards row pressure, moisture and retained inventory.

Sets surface retained theta to zero, inverts each porous water/geometric-volume through the SI storage law, stores pressure converted to native ft and physical theta, and resums held_volume ft3. Throws runtime_error on nonfinite pressure; earlier cells may already be updated. Does not change conserved richards_water or mobile node volume.

Parameters

[in,out]	ctx	Borrowed initialized native node-LID context with coherent storage/cell/material and link/node joins; serial lifecycle ownership is required.
[in]	row	Valid dense storage row with aligned cells/richards_water/richards_pressure and valid authored retention materials.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ resetPorts()

void openswmm::lidnode::resetPorts ( SimulationContext & ctx )

Clear trial port-transfer accumulators before a fresh hydraulic iteration.

Throws before mutation if any Mesh Richards row has already routed and awaits finish. Otherwise zeroes per-cell port_delta/mobile_delta and clears quality_ports for all storage rows. Does not change retained theta, Richards water, mobile node volume or completed quality transfers; caller must not discard an accepted unfinished port ledger.

Parameters

[in,out] ctx Borrowed initialized native hydraulic/node-LID context with valid subtype joins and dimension-aligned runtime arrays; caller serializes lifecycle/routing phases.

Here is the caller graph for this function:

◆ richardsMode()

bool openswmm::lidnode::richardsMode	(	const SimulationContext &	ctx,
		int	node )

Read the initialized LID Richards mode flag for a node.

Parameters

[in]	ctx	Borrowed resolved context; no mutation or pointer retention.
[in]	node	Global node index resolved through the storage subtype map.

Returns: True for a joined storage state with richards enabled; false without a storage join.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ routeRichardsNodesForTierWindow()

twoD::RichardsBedAcceptance openswmm::lidnode::routeRichardsNodesForTierWindow	(	SimulationContext &	ctx,
		Router &	router,
		twoD::SubsurfaceSolver &	gw,
		twoD::SurfaceStateData &	surface,
		int	tier,
		double	start,
		double	end,
		const std::vector< double > &	step_ends,
		double	evaporation,
		const std::vector< int > &	nodes )

Trial and publish a fixed-forcing native dynamic-wave/Richards tier window.

Parameters

[in,out]	ctx	Initialized compatible water-only context at current_time==start, DYNWAVE routing, conduit-only links and no enabled ponding. All global Mesh owners must be included. Native link/LID state and elapsed/date clocks publish on success. Live 2D IO/accessor handles are cleared in the private trial then restored unchanged.
[in,out]	router	Initialized native dynamic-wave router outside a checkpoint session; its private solver/group window state publishes after accepted context.
[in,out]	gw	Matching active aquifer with the selected due tier/bed/thermal owners.
[in,out]	surface	Matching surface state; other tiers retain their clocks.
	tier	Nonnegative actual due groundwater tier.
	start	Finite nonnegative exact current elapsed-second boundary.
	end	Finite endpoint seconds strictly later than start.
	step_ends	Ordered native routing substep endpoints spanning the closed window, as qualified by acceptRichardsBedsForTierAcrossSteps().
	evaporation	Finite nonnegative potential ft/s held across all substeps.
	nodes	Nonempty unique complete cohort of Mesh Richards STORAGE node owners; omitted global Mesh nodes are refused even if another tier would otherwise retain time.

Returns: Acceptance/receipts, or error for validation, convergence, nonfinite state, flooding, lower-level refusal or caught standard exception. Trials use private context/aquifer/surface/router copies; publish uses nonthrowing moves/swaps only after success. Does not install live source/face drivers, structure callbacks or restart support; caller supplies stable fixed forcing and serializes publication.

◆ sync()

void openswmm::lidnode::sync	(	SimulationContext &	ctx,
		int	control )

Synchronize dependent storage depth and authored outlet anchors after a control edit.

For a valid stack converts its thickness to hydraulic ft and resets every storage using that control. Repositions valid anchors at selected layer top/bottom, writing physical crest for weir/rating outlets or endpoint offset for other links. Does not rebuild derived volumes/cells immediately; initialize must run before simulation. Can invalidate borrowed runtime-cell references.

Parameters

[in,out]	ctx	Resolved model; matching storage LID state is cleared, full depth replaced and full volume marked zero for later initialization.
[in]	control	LID control index; invalid/unsupported stack yields a no-op.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ thickness()

double openswmm::lidnode::thickness ( const std::vector< LidNodeLayer > & stack )

Sum all physical layer thicknesses while excluding the bottom boundary record.

Parameters

[in] stack Authored layer rows; no validation is performed.

Returns: Sum of params[0] in the stack shared rain-depth unit; zero for an empty stack.

Here is the caller graph for this function:

◆ validate()

void openswmm::lidnode::validate ( SimulationContext & ctx )

Validate node-LID model references, layers, supported physics and anchored geometry.

Checks NODE treatment rules/material stacks, DW routing and qualified quality/age/heat/reaction adapters, MaxDepth equal to layer-thickness sum after conversion, and unique LID endpoint/interface anchors. Conventional surface roughness/slopes/drains ignored by node hydraulics generate warnings. Does not initialize cells, fix depths or stop after the first error; allocations can throw.

Parameters

[in,out] ctx Resolved context; errors/warnings are appended while valid authored values remain unchanged.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ validateRichardsRouting()

bool openswmm::lidnode::validateRichardsRouting	(	const SimulationContext &	ctx,
		double	dt )

Preflight the common accepted Mesh Richards routing interval without mutation.

Every present owner must be pending finish, not already routed, start exactly at ctx.current_time and share the same completed end. Throws on mismatch before hydraulic loss/flow/Picard mutation. No-Mesh calls do not independently validate dt.

Parameters

[in]	ctx	Borrowed resolved context; no mutation or pointer retention.
[in]	dt	Finite positive routing seconds, required to match each present owner interval within eight-epsilon clock tolerance.

Returns: True when at least one MESH_AQUIFER Richards owner is present, false when none exists.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ validateStack()

std::string openswmm::lidnode::validateStack ( const std::vector< LidNodeLayer > & stack )

Validate layer material/order and optional Richards requirements.

Requires at least one MEDIA/AGGREGATE, a SURFACE only once first and BOTTOM only once last. Enabled Richards options on the first row require a surface layer, valid numerical settings and retention/specific-storage records on every porous layer, with residual moisture below media wilting point. Treatment rules and model references are validated separately.

Parameters

[in] stack Authored top-to-bottom layer records, read-only.

Returns: Empty string when valid, otherwise the first descriptive error.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ validLayer()

bool openswmm::lidnode::validLayer ( const LidNodeLayer & l )

Check one authored node-layer material record.

Surface requires positive thickness and vegetation fraction<1; media requires 0<=wilting<field capacity<porosity<=1; aggregate requires positive thickness/pore fraction<=1. Bottom accepts nonnegative active coefficients. Does not validate stack order, Richards retention/options or treatment rules.

Parameters

[in] l Layer kind and seven numeric parameters, inspected without mutation.

Returns: True for finite nonnegative parameters, zero unused slots and valid kind-specific thickness/pore/moisture ordering.

Here is the caller graph for this function:

◆ validTreatment()

bool openswmm::lidnode::validTreatment	(	const SimulationContext &	ctx,
		const LidLayerTreatment &	rule,
		std::string &	error )

Validate a layer pollutant rule and optional legacy treatment expression.

Validates syntax and pollutant references using the legacy treatment parser; does not attach the rule, validate layer selection or evaluate a concentration. Temporary parser allocations may throw.

Parameters

[in]	ctx	Borrowed coherent pollutant/node-LID state; no mutation or pointer retention.
[in]	rule	Known pollutant name, finite removal fraction [0,1], finite nonnegative decay in 1/day and optional expression.
[in,out]	error	Receives validation diagnostic on failure; success does not clear a prior string.

Returns: True for a known pollutant, valid bounds and parseable expression; false otherwise.

Here is the call graph for this function:

Here is the caller graph for this function:

Namespaces

Functions

Function Documentation

◆ acceptRichardsNodesAtFiring()

◆ acceptRichardsNodesForTier()

◆ active()

◆ bottomCloggingFactor()

◆ bottomConductivity()

◆ bottomMode()

◆ exchangePorts()

◆ exchangeRichardsPorts()

◆ finishRichardsNodes()

◆ finishStep()

◆ heldMass()

◆ heldVolume()

◆ initialize()

◆ initializeInfiltration()

◆ layers()

◆ outletQuality()

◆ portCell()

◆ portDepth()

◆ portOffset()

◆ prepareMeshRichardsStep()

◆ prepareOutletQuality()

◆ prepareQuality()

◆ prepareRichardsStep()

◆ prepareStep()

◆ prepareStepAfterMesh()

◆ readNodes()

◆ readOutlets()

◆ readRichards()

◆ readTreatment()

◆ receiveQuality()

◆ refreshRichardsState()

◆ resetPorts()

◆ richardsMode()

◆ routeRichardsNodesForTierWindow()

◆ sync()

◆ thickness()

◆ validate()

◆ validateRichardsRouting()

◆ validateStack()

◆ validLayer()

◆ validTreatment()