openswmm::runoff::RunoffSolver Class Reference

Owned three-pool non-LID reservoir, native soil state and completed routing history. Initialize against one compatible model before use. Geometry is cached; execute mutates both owner and context, invokes an optional borrowed callback, and is not a transaction. Completed-source drivers must trial copies and publish after all coupled water owners accept. Serialize all mutation, borrowing and archives. More...

#include <Runoff.hpp>

Collaboration diagram for openswmm::runoff::RunoffSolver:

Public Types
using	InfiltrationBoundary = std::function<bool(int, double, double, double&)>

Public Member Functions
void	init (SimulationContext &ctx, const std::vector< std::pair< int, double > > &spatial_areas={})
	Rebuild owned runoff/native infiltration state for one initialized model.
std::vector< std::pair< int, double > >	reviewedAreas () const
	Reconstruct only explicitly reviewed non-LID area overrides.
void	execute (SimulationContext &ctx, double dt, double evap_rate=0.0, double infil_factor=1.0, double recovery_factor=1.0, int month=-1, const InfiltrationBoundary *boundary=nullptr, const std::vector< RunoffSourceForcing > *source_forcing=nullptr, const std::vector< double > *spatial_fractions=nullptr, const std::vector< int > *source_owners=nullptr)
	Mutate selected or ordinary three-pool reservoirs over one completed interval.
double	nativeInfilFullLid (SimulationContext &ctx, int i, double dt, double recovery_factor)
	Advance native soil for a full-LID/fully impervious runoff source.
double	infilFactorUsed (int i) const
	Read the last recorded native infiltration multiplier for one source.
const RunoffSoA &	soa () const
	Borrow the current owned reservoir geometry, water and diagnostics.
RunoffSoA &	soa ()
	Borrow mutable reservoir rows for compatible internal hot-start integration.
void	checkpoint (detail::CompletedSourceArchive &archive, bool model)
	Stream either model identity rows or accepted runoff/soil state.
void	validateCheckpoint (const RunoffSolver &model) const
	Validate selected decoded numeric fields against an initialized runoff model.
double	pendingRoutingVolume (const SimulationContext &ctx, int source) const
	Read completed inter-subarea outflow waiting for its next routing interval.
void	infil_get_state (int i, int &model, double state[6]) const noexcept
	Copy one native soil history into the legacy six-double hot-start layout.
void	infil_set_state (int i, int model, const double state[6]) noexcept
	Restore matching native soil history from six legacy hot-start scalars.

Detailed Description

Owned three-pool non-LID reservoir, native soil state and completed routing history. Initialize against one compatible model before use. Geometry is cached; execute mutates both owner and context, invokes an optional borrowed callback, and is not a transaction. Completed-source drivers must trial copies and publish after all coupled water owners accept. Serialize all mutation, borrowing and archives.

Member Typedef Documentation

InfiltrationBoundary

using openswmm::runoff::RunoffSolver::InfiltrationBoundary = std::function<bool(int, double, double, double&)>

Whole-pervious-area external boundary for a trial or bounded solve. Arguments: source index, ponded depth (ft), available water rate after surface evaporation (ft/s), output intake rate (ft/s). False preserves the native kernel. True replaces it without advancing native soil state. The caller must supply completed forcing and commit a validated trial; this boundary does not select sources or schedule. An optional completed spatial fraction weights its rate; the remainder uses native soil once.

Member Function Documentation

checkpoint()

void openswmm::runoff::RunoffSolver::checkpoint	(	detail::CompletedSourceArchive &	archive,
		bool	model )

Stream either model identity rows or accepted runoff/soil state.

Parameters

[in,out]	archive	Compatible native reader/writer; partial field mutation or emission can precede failure. State vectors require matching initialized extents.
	model	True streams geometry/coefficients/area overrides and soil model data; false streams depths/rates/loss diagnostics, factors/routing duration, lazily sized weather buffers, completed pool budgets and native soil dynamic state. Native feet/ft2/ft3/ft-per-second storage units are preserved. Does not stream n_subcatch, finish/version the enclosing archive, compare model rows or generally validate physical state. Reading checks nonempty working buffers match source count. Caller decodes a copy, finishes the outer archive, calls validateCheckpoint and coordinates all context/coupled owners before publication. Exceptions propagate.

execute()

void openswmm::runoff::RunoffSolver::execute	(	SimulationContext &	ctx,
		double	dt,
		double	evap_rate = 0.0,
		double	infil_factor = 1.0,
		double	recovery_factor = 1.0,
		int	month = -1,
		const InfiltrationBoundary *	boundary = nullptr,
		const std::vector< RunoffSourceForcing > *	source_forcing = nullptr,
		const std::vector< double > *	spatial_fractions = nullptr,
		const std::vector< int > *	source_owners = nullptr )

Mutate selected or ordinary three-pool reservoirs over one completed interval.

Parameters

[in,out]	ctx	Compatible initialized model/forcing/history/report/statistic arrays. Publishes rainfall/runoff/ponded and ft/s loss reports, consumes LID return cfs, adds ft3 evaporation/infiltration/subarea statistics and may access gage cursors. Global routing/lateral totals and simulation clocks are handled by the caller.
	dt	Finite positive seconds required on completed path and assumed ordinary.
	evap_rate	Ordinary broadcast PET ft/s, subject to DRY_ONLY and per-source overrides; ignored by completed forcing. Must be finite nonnegative.
	infil_factor	Finite nonnegative default soil multiplier; valid monthly source INFIL pattern replaces it when present. Recorded only when native soil is evaluated.
	recovery_factor	Finite nonnegative native dry-recovery multiplier.
	month	Zero-based calendar month; negative disables monthly infiltration, DSTORE and N-PERV lookups. Out-of-range factors fall back rather than reject.
	boundary	Optional borrowed synchronous pervious intake callback. Arguments: source index, opening ponded feet, nonnegative available ft/s, writable intake ft/s. False keeps native soil; true requires finite nonnegative rate and no lumped aquifer, clips intake to availability, and bypasses native soil on fully spatial area. Callback must outlive call, avoid reentry and keep side effects private until caller accepts.
	source_forcing	Null selects all ordinary sources with native gage/PET handling. Non-null selects strictly increasing unique valid indices with nonnegative finite rain/PET/surface-return ft/s. Empty selects none. Supplied rain bypasses gages; existing enabled snow-net reports can still replace per-pool rain. Optional nonnegative pet_imperv/pet_perv override footprints and must be finite (not separately checked); raw_precipitation is not used here. Uses integrated reservoir storage balance for mean discharge, records completed ft3 pool budgets and rescales prior routed volume by previous/current duration. Ordinary retains endpoint-rate rectangle/history.
	spatial_fractions	Optional n-source [0,1] finite pervious spatial fractions, requires completed forcing. Positive fraction requires successful callback; remaining native fraction advances its soil once with post-evaporation depth. Full native contribution/history remains separate from spatial intake bookkeeping.
	source_owners	Optional ordinary-only n-source map; nonnegative skips that source in every phase, negative processes it. Cannot combine with explicit forcing.

Exceptions

std::invalid_argument	Invalid completed selection/fraction/owner layout or invalid accepted external intake/lumped-aquifer combination.
std::runtime_error	Required spatial callback declined a positive fraction. Preflight checks protect before loop; later callback/solver/allocation failures can leave partial owner/context/callback changes. Native ODE status is not checked. Completed callers must solve on private copies and coordinate external receipts. Unselected/owned rows retain prior reports. Does not itself qualify full water closure.

Here is the call graph for this function:

infil_get_state()

void openswmm::runoff::RunoffSolver::infil_get_state ( int i, int & model, double state[6] ) const

noexcept

Copy one native soil history into the legacy six-double hot-start layout.

Parameters

	i	Source index; invalid returns model zero and six zeros.
[out]	model	Stored InfilModel enum; external ownership still reports its type.
[out]	state	Writable six doubles, nonnull. Horton: tp/Fe/Fmh/0/0/0; Green-Ampt: IMD/F/Fu/T/saturated/0; Curve Number: S/Se/P/F/f/T. Native soil feet/ seconds and stored method conventions are retained. External/stateless returns zeros. Does not serialize parameters, cumulative SI intake or owner identity; no mutation.

Here is the caller graph for this function:

infil_set_state()

void openswmm::runoff::RunoffSolver::infil_set_state ( int i, int model, const double state[6] )

noexcept

Restore matching native soil history from six legacy hot-start scalars.

Parameters

i	Source index; invalid or externally owned is ignored.
model	Must exactly equal initialized method; mismatch silently ignored.
state	Borrowed six doubles in infil_get_state native layout/units, nonnull when used. Green-Ampt saturated is true for any nonzero slot four. Does not validate finite/sign bounds, configure parameters, change owner or restore cumulative SI intake; caller qualifies input and paired checkpoint before publishing.

Here is the caller graph for this function:

infilFactorUsed()

double openswmm::runoff::RunoffSolver::infilFactorUsed ( int i ) const

inline

Read the last recorded native infiltration multiplier for one source.

Parameters

i	Valid nonnegative initialized source index; unchecked vector indexing.

Returns

Factor, initially one. Retained when soil is skipped or fully spatial; therefore not necessarily the factor a current pattern would resolve. No mutation.

init()

void openswmm::runoff::RunoffSolver::init	(	SimulationContext &	ctx,
		const std::vector< std::pair< int, double > > &	spatial_areas = {} )

Rebuild owned runoff/native infiltration state for one initialized model.

Parameters

ctx	Borrowed valid subcatchment geometry/soil parameters and unit enum; width already feet, slope ratio, project area/rain-depth fields and LID area ft2. Does not mutate context; required arrays must have n_subcatches aligned entries.
spatial_areas	Optional unique (zero-based source,m2 non-LID area) overrides; finite nonnegative values bypass project land-area conversion for selected sources.

Exceptions

std::invalid_argument

Invalid/duplicate override, before clearing this owner. Reinitializes reservoir geometry/depths/history, coefficients, infiltration methods and factors. Zero native drying time is normalized to TINY. Override full denominator includes native LID area. Later allocations/native setup can fail after partial replacement; no general rollback. Reinitialize after changing cached geometry/soil.

Here is the call graph for this function:

nativeInfilFullLid()

double openswmm::runoff::RunoffSolver::nativeInfilFullLid	(	SimulationContext &	ctx,
		int	i,
		double	dt,
		double	recovery_factor )

Advance native soil for a full-LID/fully impervious runoff source.

Parameters

ctx	Compatible native rainfall/runon ft/s rows, borrowed unchanged.
i	Valid source index in context, ponding, factors and infiltration bank.
dt	Finite positive seconds.
recovery_factor	Finite nonnegative dry-recovery multiplier.

Returns

Native ft/s from own rainfall+runon, pervious ponded feet and last recorded infiltration factor. Advances soil history without debiting water, checking actual non-LID area, updating context losses or booking an external receipt; call once at its scheduled native boundary. Bounds/finite input are not checked here.

pendingRoutingVolume()

double openswmm::runoff::RunoffSolver::pendingRoutingVolume	(	const SimulationContext &	ctx,
		int	source ) const

Read completed inter-subarea outflow waiting for its next routing interval.

Parameters

ctx	Matching subarea route/pct_routed rows.
source	Valid nonnegative initialized index in geometry and duration arrays.

Returns

ft3 from prior source rates, fractions, routed share, non-LID area and last completed seconds. Zero when wholly impervious/pervious, route disabled or no eligible receiving pool. No bounds/finite validation, water debit or history reset; reading twice returns the same pending volume until another solve/publication.

reviewedAreas()

std::vector< std::pair< int, double > > openswmm::runoff::RunoffSolver::reviewedAreas

(

)

const

Reconstruct only explicitly reviewed non-LID area overrides.

Returns

Copied ordered (source index,m2) pairs. Converts cached ft2 and, if needed, uses one adjacent representable m2 value to reproduce exact division back to ft2. Empty for ordinary initialization. Does not include project/default sources or LID area and does not mutate owner.

Exceptions

std::runtime_error

No exact one-step reconstruction exists. Allocation failures propagate; serialize with initialization/owner mutation.

soa() [1/2]

RunoffSoA & openswmm::runoff::RunoffSolver::soa ( )

inline

Borrow mutable reservoir rows for compatible internal hot-start integration.

Returns

Owned member reference until destruction; same lifetime restrictions as const view. Caller preserves all aligned extents/units and geometry compatibility; manual changes do not rebuild coefficients, soil, routing durations or context reports. Coordinate publication and validation with the surrounding restart owner.

soa() [2/2]

const RunoffSoA & openswmm::runoff::RunoffSolver::soa ( ) const

inline

Borrow the current owned reservoir geometry, water and diagnostics.

Returns

Member reference until destruction; init/execute/restore/assignment can change or invalidate rows/buffers. Serialize access, copy snapshots across mutation and do not free borrowed storage. Does not include all soil/coupling checkpoint data.

validateCheckpoint()

void openswmm::runoff::RunoffSolver::validateCheckpoint

(

const RunoffSolver &

model

)

const

Validate selected decoded numeric fields against an initialized runoff model.

Parameters

model

Borrowed compatible initialization used to compare source count and exact area vector, and qualify native infiltration model identity/state.

Exceptions

std::runtime_error

Count/area mismatch or nonfinite/negative dynamic rates, depths, statistics, factors, routing durations, weather buffers or completed budgets. No mutation. Does not independently compare all runoff geometry vectors, verify all extents, pool water closure or full surrounding context identity; fixed-shape archive and containing restart validation must supply those checks before publication.

---

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

• /home/runner/work/openswmm.engine/openswmm.engine/src/engine/hydrology/Runoff.hpp
• /home/runner/work/openswmm.engine/openswmm.engine/src/engine/hydrology/Runoff.cpp
• /home/runner/work/openswmm.engine/openswmm.engine/src/engine/hydrology/RunoffCheckpoint.cpp