openswmm::runoff::SourceClockGroups Class Reference

#include <SourceClockGroups.hpp>

Collaboration diagram for openswmm::runoff::SourceClockGroups:

Public Member Functions
std::string	initialize (const SimulationContext &ctx, const std::vector< int > &seeds, bool hydraulic_returns=false)
	Build selected connected source groups and snapshot their forcing inputs.
std::string	stage (int group, double end, double completed_through)
	Resolve and stage contiguous forcing from a group's accepted boundary.
std::string	commit (int group)
	Advance a group's accepted clock to the last staged forcing endpoint.
void	cancel (int group)
	Drop staged forcing without changing the accepted clock or water stores.
const std::vector< SourceClockGroup > &	groups () const
	Borrow the group membership, accepted clocks and pending forcing.
int	groupForSubcatch (int source) const
	Look up selected component membership without scanning the graph.
void	checkpoint (detail::CompletedSourceArchive &archive, bool model)
	Stream model forcing/membership or accepted source-clock restart state.

Detailed Description

Internal completed-interval clock/forcing adapter. Seeds select whole weakly connected runoff/LID-drain graphs. Copied source records, not the global gage/climate cursor, supply group rates through SourceWaterDriver. Stage changes no source water. The driver must trial every enabled store, settle intake, install accepted source states, then commit the group marker. Cancellation restores no water: uncommitted source trials must stay private.

Member Function Documentation

cancel()

void openswmm::runoff::SourceClockGroups::cancel

(

int

group

)

Drop staged forcing without changing the accepted clock or water stores.

Parameters

group

Zero-based group index; an invalid index is a no-op. Invalidates references to that group's pending elements. Source trials and any water rollback remain the driver's responsibility.

checkpoint()

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

Stream model forcing/membership or accepted source-clock restart state.

Parameters

[in,out]	archive	Matching CompletedSourceArchive in read or write mode; serialization order/schema and companion model are supplied by the caller.
	model	True streams forcing snapshot and group membership; false streams only completed_end for each group and requires no pending intervals.

Exceptions

std::runtime_error

Pending restart state, invalid restored/written clock, or archive shape/bounds/IO errors. Clocks must be finite, nonnegative and within the stored duration tolerance. Read can partially mutate before a later refusal; use an isolated candidate when transactional restoration is required. Model-mode loading alone is not comprehensive validation of all stored forcing values.

commit()

std::string openswmm::runoff::SourceClockGroups::commit

(

int

group

)

Advance a group's accepted clock to the last staged forcing endpoint.

Parameters

group

Valid zero-based group with a nonempty pending list.

Returns

Empty after updating completed_end and clearing pending, otherwise a refusal. Does not install/verify source water; the driver must first accept all corresponding source states. Borrowed pending element references are invalidated.

groupForSubcatch()

int openswmm::runoff::SourceClockGroups::groupForSubcatch

(

int

source

)

const

Look up selected component membership without scanning the graph.

Parameters

source

Zero-based model subcatchment index.

Returns

Group index or -1 for invalid/unselected sources (including before init). The mapping describes the last successful initialization/model restoration.

Here is the caller graph for this function:

groups()

const std::vector< SourceClockGroup > & openswmm::runoff::SourceClockGroups::groups ( ) const

inline

Borrow the group membership, accepted clocks and pending forcing.

Returns

Const owned vector valid until destruction; initialization/checkpoint replacement can invalidate elements, and stage/commit/cancel mutate their pending storage. Caller copies data needed across such changes and serializes access.

Here is the caller graph for this function:

initialize()

std::string openswmm::runoff::SourceClockGroups::initialize	(	const SimulationContext &	ctx,
		const std::vector< int > &	seeds,
		bool	hydraulic_returns = false )

Build selected connected source groups and snapshot their forcing inputs.

Parameters

ctx	Compatible initialized model with aligned subcatchment/gage/LID arrays, resolved names, valid flow units, calendar dates and forcing persistence arrays. Reads graph, rainfall/PET tables and monthly factors without advancing cursors.
seeds	Zero-based subcatchment indices. Every whole weakly connected component touched by a seed is selected; duplicates are harmless, empty selects none. Runoff, LID drains and enabled snow plowing all connect components.
hydraulic_returns	True permits qualified hydraulic outfall returns and validates their indices; false rejects returns into selected components.

Returns

Empty on success, otherwise a refusal message. Builds a temporary then moves it into this adapter, retaining old state on normal failure. Reinitializing an adapter with pending intervals or a positive committed clock is refused. Selected groups support persistent prescriptions, nonnegative ordered rainfall and constant/monthly/time-series PET; unsupported forcing/precomputed runoff is refused. With no selected groups those weather qualifications are skipped. No borrowed context data is retained; later model/forcing edits require a fresh compatible initialization. Caller serializes all adapter operations.

Here is the call graph for this function:

stage()

std::string openswmm::runoff::SourceClockGroups::stage	(	int	group,
		double	end,
		double	completed_through )

Resolve and stage contiguous forcing from a group's accepted boundary.

Parameters

group	Zero-based initialized group index with no existing pending interval.
end	Finite requested end in elapsed seconds, strictly after completed_end and within simulation duration (relative tolerance 1e-12).
completed_through	Finite elapsed-second frontier at least end; supplied by the driver as proof the forcing interval is completed, not future prediction.

Returns

Empty on success, otherwise a refusal without installing a partial pending list. Splits at month, PET-record, rain-record and rain-expiry boundaries. Resolves monthly adjustments and persistent overrides/additions, dry-only evaporation, and subcatchment scales in internal ft/s. Invalid resolved rates refuse staging. No source water or accepted clock changes. A successful stage requires driver trial/settlement before commit(); cancel() only drops forcing. Allocation and calendar exceptions propagate; dates must be representable by DateTime helpers.

Here is the call 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/SourceClockGroups.hpp
• /home/runner/work/openswmm.engine/openswmm.engine/src/engine/hydrology/SourceClockCheckpoint.cpp
• /home/runner/work/openswmm.engine/openswmm.engine/src/engine/hydrology/SourceClockGroups.cpp