The two-zone kernel. Owned by SurfaceRouter2D; driven by the marcher's tier hooks. More...

#include <SubsurfaceSolver.hpp>

Collaboration diagram for openswmm::twoD::SubsurfaceSolver:

Public Member Functions
std::string	initialize (const MeshData &mesh, const InertialEdges &edges, const SolverOptions2D &opts, const GwUnitFactors &uf, int n_nodes, SubsurfaceConfig &cfg, std::vector< std::string > &warnings)
	Resolve the authored rows onto cells, seed state, size the accumulators.

bool	active () const noexcept

SubsurfaceState &	state () noexcept

const SubsurfaceState &	state () const noexcept

const GwOptions &	options () const noexcept

void	refreshDtCell (const MeshData &mesh, const InertialEdges &edges)

void	assignTiers (double dt0, int n_tiers)

int	requiredTiers (double dt0) const noexcept

void	fireGwFaces (int tier, double dt)
	Lateral Darcy on the faces of one tier; books ±ΔV into `eacc_L/R`.

void	fireGwCells (int tier, double dt, SurfaceStateData &surf)
	Gather + closure + node/deep/ET/Dunne for the cells of one tier.

void	settle (SurfaceStateData &surf)

bool	tierHasCells (int tier) const noexcept
	True when the tier's cell list is non-empty.

bool	tierHasFaces (int tier) const noexcept

int	tierCount () const noexcept

const std::vector< long > &	tierFirings () const noexcept
	Per-tier firing counts — the G-A telemetry (`swmm_gw2d_get_tier_histogram`).

void	bookInfiltrationFromSurface (int cell, double vol_m3) noexcept

double	takeToSurface (int cell) noexcept

const std::vector< int > &	pendingSurfaceCells () const noexcept

void	compactPending () noexcept

void	sampleNodeExchange (const NodeData *nodes, double dt)

const std::vector< double > &	nodeExchangeVolumes () const noexcept

void	resetNodeExchangeVolumes () noexcept
	Zero the per-node ledger at the start of a routing batch.

double	storage () const noexcept
	Storage now, for the continuity ledger.

Detailed Description

The two-zone kernel. Owned by SurfaceRouter2D; driven by the marcher's tier hooks.

Member Function Documentation

◆ active()

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

inlinenoexcept

◆ assignTiers()

void openswmm::twoD::SubsurfaceSolver::assignTiers	(	double	dt0,
		int	n_tiers )

Assign tiers from dt_cell against the marcher's dt0 and tier count, and rebuild the per-tier cell/face lists. G-A: no surface quantity enters this.

Here is the caller graph for this function:

◆ bookInfiltrationFromSurface()

void openswmm::twoD::SubsurfaceSolver::bookInfiltrationFromSurface	(	int	cell,
		double	vol_m3 )

noexcept

The surface books infiltration it delivered to cell i (m³) at its own (finer) cadence; the GW cell gathers it when it fires.

◆ compactPending()

void openswmm::twoD::SubsurfaceSolver::compactPending ( )

noexcept

Drop drained cells from pendingSurfaceCells(). Serial; call from the marcher's rebuild, not from a firing.

Here is the caller graph for this function:

◆ fireGwCells()

void openswmm::twoD::SubsurfaceSolver::fireGwCells	(	int	tier,
		double	dt,
		SurfaceStateData &	surf )

Gather + closure + node/deep/ET/Dunne for the cells of one tier.

Here is the call graph for this function:

◆ fireGwFaces()

void openswmm::twoD::SubsurfaceSolver::fireGwFaces	(	int	tier,
		double	dt )

Lateral Darcy on the faces of one tier; books ±ΔV into eacc_L/R.

Here is the call graph for this function:

◆ initialize()

std::string openswmm::twoD::SubsurfaceSolver::initialize	(	const MeshData &	mesh,
		const InertialEdges &	edges,
		const SolverOptions2D &	opts,
		const GwUnitFactors &	uf,
		int	n_nodes,
		SubsurfaceConfig &	cfg,
		std::vector< std::string > &	warnings )

Resolve the authored rows onto cells, seed state, size the accumulators.

Parameters

mesh	cell areas, centroid elevations and tags
edges	the marcher's unique interior-edge topology, shared
opts	the 2D solver options (LTS ladder, unit factors)
uf	project-unit → SI multipliers for the authored rows
n_nodes	1D node count, to size the node-exchange ledger
cfg	the authored rows — read, never modified
warnings	advisory diagnostics appended here

Returns: a fatal diagnostic; empty on success.

Note: Takes what it needs rather than a SimulationContext. That is not tidiness: it is what lets the numerical gates build a mesh, a soil and a table in twenty lines and check a conservation identity, with no engine, no project file and no units. A kernel that can only be exercised through a full model is a kernel whose failures are found late.

Here is the call graph for this function:

◆ nodeExchangeVolumes()

const std::vector< double > & openswmm::twoD::SubsurfaceSolver::nodeExchangeVolumes ( ) const

inlinenoexcept

Per-node exchange volume this advance (m³ SI, + out of the aquifer into the pipe). The router books it into nodes.coupling_volume through the same flow_2d_to_1d factor the surface exchange uses.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ options()

const GwOptions & openswmm::twoD::SubsurfaceSolver::options ( ) const

inlinenoexcept

◆ pendingSurfaceCells()

const std::vector< int > & openswmm::twoD::SubsurfaceSolver::pendingSurfaceCells ( ) const

inlinenoexcept

Cells with pending surface-bound water, so the marcher can pin them active (a dry surface cell above an exfiltrating column must route). Call compactPending() first — takeToSurface clears flags but does not erase from this list, because it runs inside the parallel cell loop.

◆ refreshDtCell()

void openswmm::twoD::SubsurfaceSolver::refreshDtCell	(	const MeshData &	mesh,
		const InertialEdges &	edges )

Per-cell stability step min(Δt_g, Δt_u), written into state_.dt_cell. Called once per rebuild; cheap enough to be unconditional (the plan's "they rarely bind").

Here is the call graph for this function:

◆ requiredTiers()

int openswmm::twoD::SubsurfaceSolver::requiredTiers ( double dt0 ) const

noexcept

Minimum tier count the ladder needs so it reaches the slowest GW cell (K ≥ 1 + ⌈log2(Δt_gw_max/dt0)⌉, G-A point 3). The marcher grows its ladder to this before assigning.

◆ resetNodeExchangeVolumes()

void openswmm::twoD::SubsurfaceSolver::resetNodeExchangeVolumes ( )

noexcept

Zero the per-node ledger at the start of a routing batch.

◆ sampleNodeExchange()

void openswmm::twoD::SubsurfaceSolver::sampleNodeExchange	(	const NodeData *	nodes,
		double	dt )

Node ↔ aquifer exchange, evaluated at tier-0 cadence against the batch-frozen 1D heads and booked into nacc (G-B row 3). The GW cell gathers its share when IT fires — the node is never pinned to the aquifer's tier and the aquifer is never pinned to tier 0.

Parameters

nodes 1D node data, or nullptr when nothing is coupled.

◆ settle()

void openswmm::twoD::SubsurfaceSolver::settle ( SurfaceStateData & surf )

Flush every pending accumulator into its owner. Mandatory before any re-tier or active-set change (the stranded-flux hazard).

Here is the call graph for this function:

◆ state() [1/2]

const SubsurfaceState & openswmm::twoD::SubsurfaceSolver::state ( ) const

inlinenoexcept

◆ state() [2/2]

SubsurfaceState & openswmm::twoD::SubsurfaceSolver::state ( )

inlinenoexcept

◆ storage()

double openswmm::twoD::SubsurfaceSolver::storage ( ) const

inlinenoexcept

Storage now, for the continuity ledger.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ takeToSurface()

double openswmm::twoD::SubsurfaceSolver::takeToSurface ( int cell )

noexcept

Volume (m³) the subsurface owes the surface twin — Dunne and exfiltration — drained by the surface at its firing.

◆ tierCount()

int openswmm::twoD::SubsurfaceSolver::tierCount ( ) const

inlinenoexcept

◆ tierFirings()

const std::vector< long > & openswmm::twoD::SubsurfaceSolver::tierFirings ( ) const

inlinenoexcept

Per-tier firing counts — the G-A telemetry (swmm_gw2d_get_tier_histogram).

◆ tierHasCells()

bool openswmm::twoD::SubsurfaceSolver::tierHasCells ( int tier ) const

inlinenoexcept

True when the tier's cell list is non-empty.

Here is the caller graph for this function:

◆ tierHasFaces()

bool openswmm::twoD::SubsurfaceSolver::tierHasFaces ( int tier ) const

inlinenoexcept

Here is the caller graph for this function:

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

/home/runner/work/openswmm.engine/openswmm.engine/src/engine/2d/subsurface/SubsurfaceSolver.hpp
/home/runner/work/openswmm.engine/openswmm.engine/src/engine/2d/subsurface/SubsurfaceSolver.cpp

Public Member Functions

Detailed Description

Member Function Documentation

◆ active()

◆ assignTiers()

◆ bookInfiltrationFromSurface()

◆ compactPending()

◆ fireGwCells()

◆ fireGwFaces()

◆ initialize()

◆ nodeExchangeVolumes()

◆ options()

◆ pendingSurfaceCells()

◆ refreshDtCell()

◆ requiredTiers()

◆ resetNodeExchangeVolumes()

◆ sampleNodeExchange()

◆ settle()

◆ state() [1/2]

◆ state() [2/2]

◆ storage()

◆ takeToSurface()

◆ tierCount()

◆ tierFirings()

◆ tierHasCells()

◆ tierHasFaces()