Owned completed-source water/snow and conservative-pollutant trial driver. Context and kernel histories are copied; callbacks are borrowed synchronously. One owner serializes initialization, crediting, trials, reads and checkpoints. Stage advances private runoff/LID/snow state; commit adopts it with its group clock. Spatial receivers/hydraulic routing must settle separately. Liquid source and solid/liquid snow balances are distinct and paired, not double-counted rain. Qualified pollutants are conservative source-pool mixtures with drain removal; no land-use buildup/washoff, lumped groundwater, age/heat/reactions or production hot-start initialization is supplied. Private accepted-boundary restart requires a matching model and publication with paired source/surface/engine owners. More...

#include <SourceWaterDriver.hpp>

Collaboration diagram for openswmm::runoff::SourceWaterDriver:

Classes
struct	State

Public Types
using	BottomCeiling = std::function<double(int type, int unit, double start, double end)>
	Synchronous LID bottom-capacity callback; caller-owned, never retained. Receives LID type/group and unit indices plus start/end elapsed seconds; returns a finite nonnegative accepted infiltration ceiling ft/s. It can be called for each weather subdivision. External side effects are not rolled back with private source trials.

using	ForcingTransform = std::function<void(SourceForcingInterval&)>
	Synchronous transform of a private resolved forcing-segment copy. Caller supplies completed-interval rates, preserves positive ordered start/ end/cohort indices and finite nonnegative rain/PET/factors. References must not escape the callback. Does not change immutable native clock records; caller-owned side effects are outside source rollback.

Public Member Functions
	SourceWaterDriver ()
	Construct an uninitialized driver without source state or IO. Most data accessors require successful initialize(); clocks() alone can be read.

	~SourceWaterDriver ()
	Release private accepted/trial histories without committing a pending trial. Borrowed state/kernel/ledger references become invalid. Caller ends concurrent access and owns any external callback/receiver rollback or persistence.

	SourceWaterDriver (SourceWaterDriver &&) noexcept
	Move owned accepted/trial histories and source clocks without copying water. Transfers pending-group bookkeeping; caller releases prior borrows and does not use moved-from data accessors until assigning a valid driver. No synchronization or external receiver settlement is performed.

SourceWaterDriver &	operator= (SourceWaterDriver &&) noexcept
	Replace this driver's histories by move, discarding any prior private trial.

SourceWaterDriver	waterTrial () const
	Copy committed water, kernels, ledgers and clocks for an independent trial.

void	checkpoint (detail::CompletedSourceArchive &archive, bool model)
	Stream private native model or accepted runtime source histories.

std::string	initialize (const SimulationContext &context, const std::vector< int > &seeds, const std::vector< std::pair< int, double > > &non_lid_areas={}, const lid::LIDSolver *initial_lids=nullptr, bool hydraulic_returns=false)
	Build private source kernels/ledgers from a simulation-start model snapshot.

std::string	configureSpatialCoverage (const std::vector< double > &inside_fractions)
	Bind uniform inside fractions once before any source advancement.

const std::vector< double > &	spatialFractions () const
	Borrow accepted per-source inside physical-area fractions.

std::string	creditSurfaceReturns (double start, const std::vector< SourceSurfaceReturn > &returns)
	Validate and queue paired aquifer-return water/mass before source trials.

std::string	creditOutfallReturns (double start, double end, const std::vector< double > &volumes)
	Queue one explicitly accepted hydraulic-return interval exactly once.

bool	acceptsOutfallReturns () const
	Read whether explicit water-only hydraulic receipts were enabled.

double	outfallReturnEnd () const
	Read the last credited accepted hydraulic-return endpoint.

const std::vector< SourceOutfallReturn > &	pendingOutfallReturns () const
	Borrow accepted hydraulic receipts waiting for their source clock.

std::string	stage (int group, double end, double completed_through, const RunoffSolver::InfiltrationBoundary boundary=nullptr, const BottomCeiling bottom_ceiling=nullptr, const ForcingTransform *forcing=nullptr)
	Advance one source group into a private completed-interval trial.

std::string	commit ()
	Adopt staged private water and its source-group endpoint together.

void	cancel ()
	Drop an active water trial and its tracked pending group forcing. Retains accepted water/histories and does not undo caller callback/receiver effects. Safe without a tracked trial; cannot repair an untracked clock left by a copy exception before pending_group_ assignment in stage(). Invalidates trial borrows.

const SourceClockGroups &	clocks () const
	Borrow source membership, accepted endpoints and staged forcing clocks.

const surface::SourceSnow &	snow (bool trial=false) const
	Borrow trial or accepted snow state without copying it.

const SimulationContext &	context (bool trial=false) const
	Borrow trial or accepted context state without copying it.

const RunoffSolver &	runoff (bool trial=false) const
	Borrow trial or accepted runoff state without copying it.

const lid::LIDSolver &	lids (bool trial=false) const
	Borrow trial or accepted lids state without copying it.

const std::vector< SourceWaterLedger > &	ledgers (bool trial=false) const
	Borrow trial or accepted ledgers state without copying it.

const std::vector< SourceWaterDelivery > &	deliveries (bool trial=false) const
	Borrow trial or accepted deliveries state without copying it.

const std::vector< SourceAtmosphericLedger > &	atmosphere (bool trial=false) const
	Borrow trial or accepted atmosphere state without copying it.

const std::vector< std::string > &	pollutantNames () const
	Borrow ordered active source-pollutant identifiers from accepted state.

const std::vector< SourcePollutantLedger > &	pollutants (bool trial=false) const
	Borrow trial or accepted pollutants state without copying it.

double	pollutantBalanceResidual (int group, int pollutant, bool trial=false) const
	Read pollutantBalanceResidual for one selected source-clock group.

double	pendingPollutantMass (int group, int pollutant, bool trial=false) const
	Read pendingPollutantMass for one selected source-clock group.

double	pendingVolume (int group, bool trial=false) const
	Read pendingVolume for one selected source-clock group.

double	storedVolume (int source) const
	Sum accepted physical runoff/LID stored water for one source.

double	balanceResidual (int group, bool trial=false) const
	Read balanceResidual for one selected source-clock group.

Detailed Description

Owned completed-source water/snow and conservative-pollutant trial driver. Context and kernel histories are copied; callbacks are borrowed synchronously. One owner serializes initialization, crediting, trials, reads and checkpoints. Stage advances private runoff/LID/snow state; commit adopts it with its group clock. Spatial receivers/hydraulic routing must settle separately. Liquid source and solid/liquid snow balances are distinct and paired, not double-counted rain. Qualified pollutants are conservative source-pool mixtures with drain removal; no land-use buildup/washoff, lumped groundwater, age/heat/reactions or production hot-start initialization is supplied. Private accepted-boundary restart requires a matching model and publication with paired source/surface/engine owners.

Member Typedef Documentation

◆ BottomCeiling

using openswmm::runoff::SourceWaterDriver::BottomCeiling = std::function<double(int type, int unit, double start, double end)>

Synchronous LID bottom-capacity callback; caller-owned, never retained. Receives LID type/group and unit indices plus start/end elapsed seconds; returns a finite nonnegative accepted infiltration ceiling ft/s. It can be called for each weather subdivision. External side effects are not rolled back with private source trials.

◆ ForcingTransform

using openswmm::runoff::SourceWaterDriver::ForcingTransform = std::function<void(SourceForcingInterval&)>

Synchronous transform of a private resolved forcing-segment copy. Caller supplies completed-interval rates, preserves positive ordered start/ end/cohort indices and finite nonnegative rain/PET/factors. References must not escape the callback. Does not change immutable native clock records; caller-owned side effects are outside source rollback.

Constructor & Destructor Documentation

◆ SourceWaterDriver() [1/2]

openswmm::runoff::SourceWaterDriver::SourceWaterDriver ( )

default

Construct an uninitialized driver without source state or IO. Most data accessors require successful initialize(); clocks() alone can be read.

Here is the caller graph for this function:

◆ ~SourceWaterDriver()

openswmm::runoff::SourceWaterDriver::~SourceWaterDriver ( )

default

Release private accepted/trial histories without committing a pending trial. Borrowed state/kernel/ledger references become invalid. Caller ends concurrent access and owns any external callback/receiver rollback or persistence.

◆ SourceWaterDriver() [2/2]

openswmm::runoff::SourceWaterDriver::SourceWaterDriver ( SourceWaterDriver && )

defaultnoexcept

Move owned accepted/trial histories and source clocks without copying water. Transfers pending-group bookkeeping; caller releases prior borrows and does not use moved-from data accessors until assigning a valid driver. No synchronization or external receiver settlement is performed.

Here is the call graph for this function:

Member Function Documentation

◆ acceptsOutfallReturns()

bool openswmm::runoff::SourceWaterDriver::acceptsOutfallReturns ( ) const

Read whether explicit water-only hydraulic receipts were enabled.

Returns: Stored initialization flag; logic_error without accepted state. Does not validate a specific receipt, trial or source/receiving clock.

Here is the caller graph for this function:

◆ atmosphere()

const std::vector< SourceAtmosphericLedger > & openswmm::runoff::SourceWaterDriver::atmosphere ( bool trial = false ) const

Borrow trial or accepted atmosphere state without copying it.

Parameters

trial True selects only an active water trial; false accepted state.

Returns: Physical footprint/eligibility rows with cumulative potential and actual atmospheric ft3.

Exceptions

std::logic_error Requested state absent. No fallback from trial to accepted. Reference/elements are owned by the selected state and can be invalidated by commit/cancel/checkpoint/move/destruction. Serialize reads with mutation and copy snapshots needed across state publication; never modify through a cast.

◆ balanceResidual()

double openswmm::runoff::SourceWaterDriver::balanceResidual	(	int	group,
		bool	trial = false ) const

Read balanceResidual for one selected source-clock group.

Parameters

group	Zero-based group index, bounds checked through groups().at().
trial	True selects active private trial, false accepted state.

Returns: Initial liquid storage+rain+paired aquifer/hydraulic returns minus evaporation, infiltration, outlets, stored and pending water, in ft3. Snow has its own paired balance.

Exceptions

std::logic_error Requested state absent; std::out_of_range invalid group index. No normalization, tolerance test, finite-value repair or state mutation occurs. Callers decide whether the residual is acceptable; trial reads do not commit it.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ cancel()

void openswmm::runoff::SourceWaterDriver::cancel ( )

Drop an active water trial and its tracked pending group forcing. Retains accepted water/histories and does not undo caller callback/receiver effects. Safe without a tracked trial; cannot repair an untracked clock left by a copy exception before pending_group_ assignment in stage(). Invalidates trial borrows.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ checkpoint()

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

Stream private native model or accepted runtime source histories.

Parameters

[in,out]	archive	Matching CompletedSourceArchive reader/writer at the paired schema position; same-platform bytes, no standalone portable file format here.
	model	True streams model/forcing/membership/footprint/configuration identity; false streams accepted water/snow/kernel/transfer/ledger/delivery state and optional hydraulic-return profile. Requires initialized state and no active water trial.

Exceptions

std::runtime_error Pending clocks, kernel/shape/profile, snow-clock, finite water/mass tuple, atmospheric or conservation mismatch; archive errors also propagate. Read mutates this object progressively and may fail after a prefix; restore an isolated waterTrial/fresh matching model, finish containing archive validation, then publish all paired owners together. A write may emit a prefix before a later validation failure. Does not activate production restart or settle external receivers.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ clocks()

const SourceClockGroups & openswmm::runoff::SourceWaterDriver::clocks ( ) const

inline

Borrow source membership, accepted endpoints and staged forcing clocks.

Returns: Owned clocks valid until destruction/move/replacement; stage/commit/cancel/ checkpoint can mutate contents or invalidate elements. Readable before initialize, when empty. No direct mutable clock access or receiver settlement is supplied.

Here is the caller graph for this function:

◆ commit()

std::string openswmm::runoff::SourceWaterDriver::commit ( )

Adopt staged private water and its source-group endpoint together.

Returns: Empty on success, otherwise refusal for no trial or failed clock commit. Clock commits before nonthrowing state swap; old accepted state/trial is discarded, invalidating borrowed kernel/ledger references. Caller first settles matching receiving ownership. No live engine/surface receiver or report writer is advanced.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ configureSpatialCoverage()

std::string openswmm::runoff::SourceWaterDriver::configureSpatialCoverage ( const std::vector< double > & inside_fractions )

Bind uniform inside fractions once before any source advancement.

Parameters

inside_fractions One finite [0,1] value per original subcatchment, including unowned rows. Represents reviewed physical footprint shares, not a water debit.

Returns: Empty after copying/marking partitioned, otherwise shape/state/range refusal. Requires initialized committed state, not already partitioned and all group clocks zero without pending forcing. Allocation can throw; no source water is advanced. Inside native-bottom LID areas later require an explicit spatial bottom ceiling.

◆ context()

const SimulationContext & openswmm::runoff::SourceWaterDriver::context ( bool trial = false ) const

Borrow trial or accepted context state without copying it.

Parameters

trial True selects only an active water trial; false accepted state.

Returns: Private copied SimulationContext, including scratch source arrays; external handles in the copy remain borrowed.

Exceptions

std::logic_error Requested state absent. No fallback from trial to accepted. Reference/elements are owned by the selected state and can be invalidated by commit/cancel/checkpoint/move/destruction. Serialize reads with mutation and copy snapshots needed across state publication; never modify through a cast.

Here is the caller graph for this function:

◆ creditOutfallReturns()

std::string openswmm::runoff::SourceWaterDriver::creditOutfallReturns	(	double	start,
		double	end,
		const std::vector< double > &	volumes )

Queue one explicitly accepted hydraulic-return interval exactly once.

Parameters

start	Finite elapsed seconds exactly equal outfallReturnEnd().
end	Finite later accepted seconds within total simulation duration tolerance; no source group may be pending or physically ahead of this endpoint.
volumes	One finite nonnegative ft3 per original source; nonzero values require an owned source with positive full non-LID+LID footprint. Unowned entries are zero.

Returns: Empty after preparing the whole queue, adding cumulative ledgers and advancing return frontier; otherwise refusal without accepted-state mutation. Requires initialized committed hydraulic-return profile and no water trial. Queue copy/append exceptions propagate before publication. Consumed only from end onward when each source group fires; does not immediately modify its physical water.

◆ creditSurfaceReturns()

std::string openswmm::runoff::SourceWaterDriver::creditSurfaceReturns	(	double	start,
		const std::vector< SourceSurfaceReturn > &	returns )

Validate and queue paired aquifer-return water/mass before source trials.

Parameters

start	Finite exact completed clock for each referenced source group.
returns	Borrowed batch with owned source, originating non-LID pool (type=unit=-1, pool in [0,2]) or exact LID type/unit and positive physical footprint. volume is finite nonnegative ft3; mass has one finite nonnegative concentration*m3 value per source pollutant, all zero for zero water. Entries are not deduplicated: caller credits accepted receipts exactly once.

Returns: Empty after queue/ledger additions, otherwise refusal before mutation. Requires initialized committed state and no pending referenced group interval. All entries are validated first, but append/allocation failures during publication can leave an earlier credited prefix; this method does not provide exception-level atomicity or cumulative overflow checks. Use an isolated snapshot for a transaction. Returns remain pending until the next selected source segment, never as rainfall.

◆ deliveries()

const std::vector< SourceWaterDelivery > & openswmm::runoff::SourceWaterDriver::deliveries ( bool trial = false ) const

Borrow trial or accepted deliveries state without copying it.

Parameters

trial True selects only an active water trial; false accepted state.

Returns: Append-order completed external outlet records: original interval seconds, ft3 and paired concentration*m3 amounts.

Exceptions

std::logic_error Requested state absent. No fallback from trial to accepted. Reference/elements are owned by the selected state and can be invalidated by commit/cancel/checkpoint/move/destruction. Serialize reads with mutation and copy snapshots needed across state publication; never modify through a cast.

Here is the caller graph for this function:

◆ initialize()

std::string openswmm::runoff::SourceWaterDriver::initialize	(	const SimulationContext &	context,
		const std::vector< int > &	seeds,
		const std::vector< std::pair< int, double > > &	non_lid_areas = {},
		const lid::LIDSolver *	initial_lids = nullptr,
		bool	hydraulic_returns = false )

Build private source kernels/ledgers from a simulation-start model snapshot.

Parameters

context	Compatible fully initialized model at current_time==elapsed_ms==0, with aligned geometry/forcing/quality/name arrays and resolved runoff/LID outlets. Selected sources cannot use lumped groundwater or preexisting runon/pervious-return histories. Nonempty selection rejects water age, heat and reactions species; snow-enabled nonempty groups require water-only even without assigned packs. Conservative pollutants otherwise require finite nonnegative rain concentration, no decay/ co-pollutants/snow-only species or land uses. Snow delegates its own qualification.
seeds	Valid subcatchment indices selecting entire weakly connected source graphs through SourceClockGroups. Empty selection is allowed.
non_lid_areas	Optional reviewed (source index,m2) overrides forwarded to RunoffSolver::init instead of rounded project-area conversion.
initial_lids	Optional borrowed matching initialized LID water snapshot; group/usage order and area/source/control mappings must match. Copies water-only history without retaining the pointer/report writers. Null builds fresh LID state.
hydraulic_returns	Explicit accepted water-only outfall-return profile; rejects active source pollutants and requires compatible positive receiving footprints.

Returns: Empty after publishing private state/clocks, otherwise refusal or caught kernel-setup standard exception. Prior uninitialized driver remains uninitialized on normal failure. Reinitialization/hot-start import is refused. Allocation/copy failures before the local setup catch can propagate. Original context is not mutated; no source interval/receiver is advanced. All source pools start with clean solute, not network INIT_CONC; defaults inside fractions to one.

Here is the call graph for this function:

◆ ledgers()

const std::vector< SourceWaterLedger > & openswmm::runoff::SourceWaterDriver::ledgers ( bool trial = false ) const

Borrow trial or accepted ledgers state without copying it.

Parameters

trial True selects only an active water trial; false accepted state.

Returns: Per-original-source cumulative liquid water accounts in ft3, independent of the snow water ledger.

Exceptions

std::logic_error Requested state absent. No fallback from trial to accepted. Reference/elements are owned by the selected state and can be invalidated by commit/cancel/checkpoint/move/destruction. Serialize reads with mutation and copy snapshots needed across state publication; never modify through a cast.

Here is the caller graph for this function:

◆ lids()

const lid::LIDSolver & openswmm::runoff::SourceWaterDriver::lids ( bool trial = false ) const

Borrow trial or accepted lids state without copying it.

Parameters

trial True selects only an active water trial; false accepted state.

Returns: Private LIDSolver physical layer water and completed budgets; report writers are not part of water trials.

Exceptions

std::logic_error Requested state absent. No fallback from trial to accepted. Reference/elements are owned by the selected state and can be invalidated by commit/cancel/checkpoint/move/destruction. Serialize reads with mutation and copy snapshots needed across state publication; never modify through a cast.

Here is the caller graph for this function:

◆ operator=()

SourceWaterDriver & openswmm::runoff::SourceWaterDriver::operator= ( SourceWaterDriver && )

defaultnoexcept

Replace this driver's histories by move, discarding any prior private trial.

Returns: This driver. Caller ends all prior borrows and paired transactions first; no source/receiver commit or file output occurs. Moved-from state is not a usable initialized model; noexcept relies on member ownership/container moves.

Here is the call graph for this function:

◆ outfallReturnEnd()

double openswmm::runoff::SourceWaterDriver::outfallReturnEnd ( ) const

Read the last credited accepted hydraulic-return endpoint.

Returns: Elapsed seconds, zero initially; logic_error without accepted state. Distinct from independently advancing source-group clocks and receiving bridge time.

◆ pendingOutfallReturns()

const std::vector< SourceOutfallReturn > & openswmm::runoff::SourceWaterDriver::pendingOutfallReturns ( ) const

Borrow accepted hydraulic receipts waiting for their source clock.

Returns: Queue of original source, availability seconds and ft3. No trial view; requires accepted state. Credit/commit/checkpoint/move may invalidate elements. Borrow only under serialized access and copy for a stable receiver snapshot.

◆ pendingPollutantMass()

double openswmm::runoff::SourceWaterDriver::pendingPollutantMass	(	int	group,
		int	pollutant,
		bool	trial = false ) const

Read pendingPollutantMass for one selected source-clock group.

Parameters

group	Zero-based group index, bounds checked through groups().at().
pollutant	Zero-based source mass-vector index, checked with names.at().
trial	True selects active private trial, false accepted state.

Returns: Queued runon/pervious-return/internal-routing/aquifer-return mass in concentration*m3; excludes completed external deliveries.

Exceptions

std::logic_error Requested state absent; std::out_of_range invalid group or pollutant index. No normalization, tolerance test, finite-value repair or state mutation occurs. Callers decide whether the residual is acceptable; trial reads do not commit it.

Here is the caller graph for this function:

◆ pendingVolume()

double openswmm::runoff::SourceWaterDriver::pendingVolume	(	int	group,
		bool	trial = false ) const

Read pendingVolume for one selected source-clock group.

Parameters

group	Zero-based group index, bounds checked through groups().at().
trial	True selects active private trial, false accepted state.

Returns: Queued runon, pervious return, internal subarea routing, aquifer and hydraulic-return ft3; excludes stored and external delivered water.

Exceptions

std::logic_error Requested state absent; std::out_of_range invalid group index. No normalization, tolerance test, finite-value repair or state mutation occurs. Callers decide whether the residual is acceptable; trial reads do not commit it.

Here is the caller graph for this function:

◆ pollutantBalanceResidual()

double openswmm::runoff::SourceWaterDriver::pollutantBalanceResidual	(	int	group,
		int	pollutant,
		bool	trial = false ) const

Read pollutantBalanceResidual for one selected source-clock group.

Parameters

group	Zero-based group index, bounds checked through groups().at().
pollutant	Zero-based source mass-vector index, checked with names.at().
trial	True selects active private trial, false accepted state.

Returns: Cumulative rain+aquifer-return input minus infiltration, outlet, removal, stored pools and pending mass, in concentration*m3.

Exceptions

std::logic_error Requested state absent; std::out_of_range invalid group or pollutant index. No normalization, tolerance test, finite-value repair or state mutation occurs. Callers decide whether the residual is acceptable; trial reads do not commit it.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ pollutantNames()

const std::vector< std::string > & openswmm::runoff::SourceWaterDriver::pollutantNames ( ) const

Borrow ordered active source-pollutant identifiers from accepted state.

Returns: Names defining every source mass-vector stride, empty for water-only or ignore-quality profile. logic_error without accepted state; commit/checkpoint/ move/destruction can invalidate references. Does not include network age/heat/MSX.

Here is the caller graph for this function:

◆ pollutants()

const std::vector< SourcePollutantLedger > & openswmm::runoff::SourceWaterDriver::pollutants ( bool trial = false ) const

Borrow trial or accepted pollutants state without copying it.

Parameters

trial True selects only an active water trial; false accepted state.

Returns: Per-source/type/unit conservative pool amounts and completed transfers in concentration*m3.

Exceptions

std::logic_error Requested state absent. No fallback from trial to accepted. Reference/elements are owned by the selected state and can be invalidated by commit/cancel/checkpoint/move/destruction. Serialize reads with mutation and copy snapshots needed across state publication; never modify through a cast.

Here is the caller graph for this function:

◆ runoff()

const RunoffSolver & openswmm::runoff::SourceWaterDriver::runoff ( bool trial = false ) const

Borrow trial or accepted runoff state without copying it.

Parameters

trial True selects only an active water trial; false accepted state.

Returns: Private RunoffSolver subarea water/kernel histories in native feet/seconds.

Exceptions

std::logic_error Requested state absent. No fallback from trial to accepted. Reference/elements are owned by the selected state and can be invalidated by commit/cancel/checkpoint/move/destruction. Serialize reads with mutation and copy snapshots needed across state publication; never modify through a cast.

◆ snow()

const surface::SourceSnow & openswmm::runoff::SourceWaterDriver::snow ( bool trial = false ) const

Borrow trial or accepted snow state without copying it.

Parameters

trial True selects only an active water trial; false accepted state.

Returns: Accepted/trial SourceSnow solid/liquid pack owner and its separate ft3 balance.

Exceptions

std::logic_error Requested state absent. No fallback from trial to accepted. Reference/elements are owned by the selected state and can be invalidated by commit/cancel/checkpoint/move/destruction. Serialize reads with mutation and copy snapshots needed across state publication; never modify through a cast.

◆ spatialFractions()

const std::vector< double > & openswmm::runoff::SourceWaterDriver::spatialFractions ( ) const

Borrow accepted per-source inside physical-area fractions.

Returns: Owned vector in original subcatchment order, initially all one; no trial selector. Requires initialized state (logic_error otherwise). Init/commit/checkpoint/ move/destruction can invalidate elements. Serialize borrows with mutation.

◆ stage()

std::string openswmm::runoff::SourceWaterDriver::stage	(	int	group,
		double	end,
		double	completed_through,
		const RunoffSolver::InfiltrationBoundary *	boundary = nullptr,
		const BottomCeiling *	bottom_ceiling = nullptr,
		const ForcingTransform *	forcing = nullptr )

Advance one source group into a private completed-interval trial.

Parameters

group	Valid initialized source-group index, no active water/pending clock trial.
end	Finite requested elapsed-second endpoint after that group's completed_end.
completed_through	Finite completed-forcing frontier at least end; bounded by simulation interval through SourceClockGroups::stage(). Not a prediction horizon.
boundary	Optional borrowed synchronous non-LID infiltration callback per RunoffSolver::InfiltrationBoundary: source, ponded feet, seconds and output ft/s; return true to use its reviewed capacity. Must not publish trial water externally.
bottom_ceiling	Optional borrowed LID callback returning capacity ft/s for type/unit/start/end. Required for selected inside native-bottom LIDs when partitioned.
forcing	Optional borrowed transform on each private weather subdivision; preserve interval/cohort/index validity and meaningful finite rates. Callback references cannot escape; external effects are not part of source rollback.

Returns: Empty with a viewable unsettled trial, otherwise refusal/standard-kernel exception text. Splits forcing at outfall availability and held snow boundaries, advances runoff/LID/snow mixtures, then checks group water and conservative mass balance at 1e-10 scaled tolerance. Caught standard failures cancel the water/clock trial, retaining accepted water; nonstandard callback exceptions can leave a trial for explicit cancel. Copy allocation occurs after clock staging but outside the catch: failure can leave pending clock state without pending_group_, requiring discard/restoration of the driver. Success requires commit after paired receiver settlement or cancel before retry. Does not settle a live aquifer/engine itself.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ storedVolume()

double openswmm::runoff::SourceWaterDriver::storedVolume ( int source ) const

Sum accepted physical runoff/LID stored water for one source.

Parameters

source Original subcatchment index; bounds checked against accepted ledger.

Returns: ft3 in liquid surface/LID stores, excluding solid/liquid snow, pending runon/returns and external deliveries. logic_error before init, out_of_range for invalid source. Does not require selected ownership or mutate state.

◆ waterTrial()

SourceWaterDriver openswmm::runoff::SourceWaterDriver::waterTrial ( ) const

Copy committed water, kernels, ledgers and clocks for an independent trial.

Returns: Owned snapshot; LID state uses waterTrial() to avoid sharing report writers.

Exceptions

std::logic_error Missing accepted state or an active water trial. Caller must also ensure source clocks are fully committed, including after an exception. Context value copies can retain external handle/callback references; do not use those to publish through a trial. Copy/allocation failures propagate; original accepted water is retained. Use the copy for multi-group/receiver coordination.

Here is the call graph for this function:

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/hydrology/SourceWaterDriver.hpp
/home/runner/work/openswmm.engine/openswmm.engine/src/engine/hydrology/SourceWaterDriver.cpp

Classes

Public Types

Public Member Functions

Detailed Description

Member Typedef Documentation

◆ BottomCeiling

◆ ForcingTransform

Constructor & Destructor Documentation

◆ SourceWaterDriver() [1/2]

◆ ~SourceWaterDriver()

◆ SourceWaterDriver() [2/2]

Member Function Documentation

◆ acceptsOutfallReturns()

◆ atmosphere()

◆ balanceResidual()

◆ cancel()

◆ checkpoint()

◆ clocks()

◆ commit()

◆ configureSpatialCoverage()

◆ context()

◆ creditOutfallReturns()

◆ creditSurfaceReturns()

◆ deliveries()

◆ initialize()

◆ ledgers()

◆ lids()

◆ operator=()

◆ outfallReturnEnd()

◆ pendingOutfallReturns()

◆ pendingPollutantMass()

◆ pendingVolume()

◆ pollutantBalanceResidual()

◆ pollutantNames()

◆ pollutants()

◆ runoff()

◆ snow()

◆ spatialFractions()

◆ stage()

◆ storedVolume()

◆ waterTrial()