#include <ExplicitFvSolver.hpp>

Inheritance diagram for openswmm::fv::ExplicitFvSolver:

Collaboration diagram for openswmm::fv::ExplicitFvSolver:

Public Types
using	ConduitStepSink = void ()(void user, int conduit, double dt, double dur)

Public Member Functions
	ExplicitFvSolver ()=default
	Construct an unbound solver with no borrowed mesh/state.

	~ExplicitFvSolver () override=default
	Destroy owned solver scratch without deleting borrowed mesh/state.

	ExplicitFvSolver (const ExplicitFvSolver &)=delete
	Disallow copying a solver and its borrowed state/scratch ownership.

ExplicitFvSolver &	operator= (const ExplicitFvSolver &)=delete
	Disallow copy assignment of a live solver.

void	enablePressureStorageCandidate (const NonlinearPressureStorage::Controls &controls={})
	Enable the restricted native nonlinear pressure-storage experiment.

const NonlinearPressureStorage::Result &	pressureCandidateResult () const noexcept
	Borrow the most recently attempted nonlinear pressure candidate diagnostics.

long	pressureCandidateRejections () const noexcept
	Read the current restricted-candidate routing-window rejection count.

void	initialize (NetworkMeshData &mesh, NetworkStateData &state, const FvOptions &opts) override
	Bind a mesh/state and initialize native solver scratch and static eligibility.

double	advance (double t_current, double t_target, const FvStepForcing &forcing) override
	Advance the borrowed native state over one requested routing window.

void	reinitialize (double t0) override
	Invalidate stepping caches and refresh derived state after external restoration.

void	finalize () override
	Detach the borrowed mesh and state.

long	last_num_steps () const noexcept override
	Substep count used by the last advance() call.

double	last_step_size () const noexcept override
	Last internal substep size (s).

double	suggested_step () const noexcept override
	Read the next CFL step suggestion from the latest backend census.

RunStats	run_stats () const noexcept override
	Read cumulative statistics. Default: zeros (backend has no counters).

bool	is_initialized () const noexcept override
	True once initialize() has completed and the solver is ready.

bool	divergence (Divergence &d) const noexcept override
	Report the last advance's worst physical-bound/nonfinite offender when supported.

void	setConduitStepSink (ConduitStepSink fn, void *user) noexcept
	Set an optional synchronous per-conduit accepted-step reporting observer.

const std::vector< double > &	node_exchange () const noexcept
	Borrow the last-window signed node exchange receipt.

void	trackAcceptedWater (bool enabled)

const AcceptedWaterVolumes &	acceptedWater () const noexcept

void	requireConservativeNodeBalance (bool enabled) noexcept

std::vector< double > &	withdrawalRates () noexcept

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

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

const std::vector< double > &	node_continuity_carry () const noexcept
	Borrow the signed numerical node-continuity carry.

const std::vector< std::uint8_t > &	pressure_folded_nodes () const noexcept
	Borrow the most recent pressure-classification folded-node mask.

const std::vector< double > &	node_inflow_volume () const noexcept
	Borrow accumulated arriving conduit-face volume magnitudes.

const std::vector< double > &	node_outflow_volume () const noexcept
	Borrow accumulated departing conduit-face/diverted-lateral volume magnitudes.

void	bookDivertedLateral (std::size_t un, double dt, const FvStepForcing &forcing) noexcept
	Book positive node lateral volume that entered cells without crossing node faces.

const std::vector< uint8_t > &	inlet_control () const noexcept
	Borrow culvert inlet-control occurrence flags for the last window.

const std::vector< double > &	node_flood_volume () const noexcept
	Per-node flooding VOLUME (ft³) over the last advance().

const std::vector< double > &	dummy_volume () const noexcept
	Borrow per-structure-entry DUMMY pass-through receipts.

const std::vector< std::uint8_t > &	node_passthrough () const noexcept
	Borrow the current direct-face algebraic-node bypass mask.

const std::vector< std::uint8_t > &	node_publish_stage () const noexcept
	Borrow eligibility for reconstructing reported node stage from adjacent wet cells.

const std::vector< double > &	cell_flow_integral () const noexcept
	Borrow the last-window time integral of mean face through-flow per cell.

double	nodeVolumeFromDepth (int node, double depth) const
	Evaluate native node storage volume from depth.

int	lts_tiers () const noexcept
	Read the most recent local-time-stepping tier count.

const std::array< long, kMaxLtsTiers > &	tier_occupancy () const noexcept
	Borrow the run tier-occupancy histogram.

Public Member Functions inherited from openswmm::fv::INetworkSolver
virtual	~INetworkSolver ()=default
	Destroy a concrete backend through the network-solver interface.

Member Typedef Documentation

◆ ConduitStepSink

using openswmm::fv::ExplicitFvSolver::ConduitStepSink = void (*)(void* user, int conduit, double dt, double dur)

Per-conduit local-step sink for the "Conduit Time Step Summary" ([REPORT] LINK_STEPS). When set, every accepted global substep and LTS macro cycle calls fn(user, conduit_row, dt, duration) once per conduit row, with dt the conduit's governing (finest-cell) step. Reporting only: never read by the integrator. Null (default) = off.

Constructor & Destructor Documentation

◆ ExplicitFvSolver() [1/2]

openswmm::fv::ExplicitFvSolver::ExplicitFvSolver ( )

default

Construct an unbound solver with no borrowed mesh/state.

Call initialize before using geometry/state helpers or advancing physical time.

Here is the caller graph for this function:

◆ ~ExplicitFvSolver()

openswmm::fv::ExplicitFvSolver::~ExplicitFvSolver ( )

overridedefault

Destroy owned solver scratch without deleting borrowed mesh/state.

All returned member references and raw views become invalid; no final advance, report publication or external callback is performed.

◆ ExplicitFvSolver() [2/2]

openswmm::fv::ExplicitFvSolver::ExplicitFvSolver ( const ExplicitFvSolver & )

delete

Disallow copying a solver and its borrowed state/scratch ownership.

Here is the call graph for this function:

Member Function Documentation

◆ acceptedWater()

const AcceptedWaterVolumes & openswmm::fv::ExplicitFvSolver::acceptedWater ( ) const

inlinenoexcept

◆ advance()

double openswmm::fv::ExplicitFvSolver::advance	(	double	t_current,
		double	t_target,
		const FvStepForcing &	forcing )

overridevirtual

Advance the borrowed native state over one requested routing window.

Resets per-window receipts, reseeds nonalgebraic node volume from heads, subcycles globally or by eligible LTS tiers and publishes current state/telemetry. Ordinary retry exhaustion or minimum substep accepts the last state; inspect divergence() and reached time. General allocation/callback failures can leave partial advance. The enabled restricted pressure candidate instead validates supported water-only Euler options and restores its routing-window physical state/accepted receipts on exceptions, then rethrows; work diagnostics remain attempted-work telemetry. Callbacks must be synchronous and non-reentrant. External edits to cell A/Q require reinitialize to invalidate derived-state caching.

Parameters

[in]	t_current	Finite current simulation time in seconds.
[in]	t_target	Finite target seconds, normally >=t_current; an unbound solver or nonforward interval returns t_target without advancing.
[in]	forcing	Borrowed step arrays/callback context, dimension-aligned and live for the entire call; values may be synchronously refreshed by the documented callback.

Returns: Reached time in seconds; can stop short after the ordinary-path two-million-operator-step backstop.

Implements openswmm::fv::INetworkSolver.

◆ bookDivertedLateral()

void openswmm::fv::ExplicitFvSolver::bookDivertedLateral	(	std::size_t	un,
		double	dt,
		const FvStepForcing &	forcing )

inlinenoexcept

Book positive node lateral volume that entered cells without crossing node faces.

If node_lat_div is set and lateral is positive, adds lateral*dt to node_out. Does not inject water again, change forcing or handle negative lateral withdrawals. Caller invokes exactly once per node update on either stepping path.

Parameters

[in]	un	Valid initialized global node index, unchecked when the diversion mask is present.
[in]	dt	Nonnegative accepted substep duration in seconds.
[in]	forcing	Borrowed aligned node_lateral ft3/s array or a null lateral pointer.

◆ cell_flow_integral()

const std::vector< double > & openswmm::fv::ExplicitFvSolver::cell_flow_integral ( ) const

inlinenoexcept

Borrow the last-window time integral of mean face through-flow per cell.

Const references remain valid only while this solver lives; their underlying element pointers/contents can change on initialization or later stepping. Serialize reads with mutation.

Returns: Cell-indexed aggregate ft3 used for routing-window mean discharge, rather than a final snapshot.

◆ divergence()

bool openswmm::fv::ExplicitFvSolver::divergence ( Divergence & d ) const

inlineoverridevirtualnoexcept

Report the last advance's worst physical-bound/nonfinite offender when supported.

Returned what pointer is borrowed backend-defined text; caller must respect concrete implementation lifetime. Does not run another advance or repair state.

Parameters

[out] d Populated only when backend returns true; default implementation leaves destination unchanged.

Returns: True for a reported offender; default false for backends without this check.

Reimplemented from openswmm::fv::INetworkSolver.

◆ dummy_volume()

const std::vector< double > & openswmm::fv::ExplicitFvSolver::dummy_volume ( ) const

inlinenoexcept

Borrow per-structure-entry DUMMY pass-through receipts.

Const references remain valid only while this solver lives; their underlying element pointers/contents can change on initialization or later stepping. Serialize reads with mutation.

Returns: ft3 over the last window, aligned with mesh.struct_link; real structure entries remain zero.

◆ enablePressureStorageCandidate()

void openswmm::fv::ExplicitFvSolver::enablePressureStorageCandidate ( const NonlinearPressureStorage::Controls & controls = {} )

inline

Enable the restricted native nonlinear pressure-storage experiment.

Sets a persistent enable flag and copies controls; no immediate feature validation or solve occurs. advance rejects unsupported options/forcing. There is no disable method on this instance; initialize does not clear this flag. Serialize configuration with solver execution.

Parameters

[in] controls Copied nonlinear stopping/work controls; no referenced caller storage is retained.

◆ finalize()

void openswmm::fv::ExplicitFvSolver::finalize ( )

overridevirtual

Detach the borrowed mesh and state.

Sets only mesh_/state_ to null. Does not delete external storage, clear owned capacities/statistics/receipts, invoke callbacks or advance time. Reinitialize via initialize before accessing state-dependent helpers.

Implements openswmm::fv::INetworkSolver.

◆ initialize()

void openswmm::fv::ExplicitFvSolver::initialize	(	NetworkMeshData &	mesh,
		NetworkStateData &	state,
		const FvOptions &	opts )

overridevirtual

Bind a mesh/state and initialize native solver scratch and static eligibility.

Mesh/state must remain alive at stable addresses and retain coherent dimensions/topology until finalize or rebinding. Initializes owned face/cell/node/LTS/transport arrays, resets major run statistics and builds algebraic/pass-through/rim caches. Does not validate every required array/index; callers provide a constructed mesh and sized state. Allocation can throw after binding and partial mutation, so is_initialized alone cannot certify successful completion. Concurrent use of one solver or its borrowed state is unsupported.

Parameters

[in,out]	mesh	Borrowed validated mesh/topology and geometry; fills short optional node surcharge/ponding and face gate/culvert arrays, and derives missing face geometry.
[in,out]	state	Borrowed dimension-aligned conserved/node/species state in native ft units. Refreshes derived depths/velocities/areas, floors negative cell area and clears dry Q; initializes/clears TPA regime flags.
[in]	opts	Copied FV options; development environment switches are read synchronously and may override selected options.

Implements openswmm::fv::INetworkSolver.

Here is the call graph for this function:

◆ inlet_control()

const std::vector< uint8_t > & openswmm::fv::ExplicitFvSolver::inlet_control ( ) const

inlinenoexcept

Borrow culvert inlet-control occurrence flags for the last window.

Const references remain valid only while this solver lives; their underlying element pointers/contents can change on initialization or later stepping. Serialize reads with mutation.

Returns: Conduit-row-indexed flags set when any substep inlet cap controlled; reset at advance entry.

◆ is_initialized()

bool openswmm::fv::ExplicitFvSolver::is_initialized ( ) const

inlineoverridevirtualnoexcept

True once initialize() has completed and the solver is ready.

Implements openswmm::fv::INetworkSolver.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ last_num_steps()

long openswmm::fv::ExplicitFvSolver::last_num_steps ( ) const

inlineoverridevirtualnoexcept

Substep count used by the last advance() call.

Implements openswmm::fv::INetworkSolver.

◆ last_step_size()

double openswmm::fv::ExplicitFvSolver::last_step_size ( ) const

inlineoverridevirtualnoexcept

Last internal substep size (s).

Implements openswmm::fv::INetworkSolver.

◆ lts_tiers()

int openswmm::fv::ExplicitFvSolver::lts_tiers ( ) const

inlinenoexcept

Read the most recent local-time-stepping tier count.

Returns: One means no separated tiering; otherwise the last assigned macro-cycle tier count.

◆ node_continuity_carry()

const std::vector< double > & openswmm::fv::ExplicitFvSolver::node_continuity_carry ( ) const

inlinenoexcept

Borrow the signed numerical node-continuity carry.

Const references remain valid only while this solver lives; their underlying element pointers/contents can change on initialization or later stepping. Serialize reads with mutation.

Returns: Node-indexed ft3. Positive carry is already in node_volume; inventory audits add only negative carry, avoiding double counting.

◆ node_exchange()

const std::vector< double > & openswmm::fv::ExplicitFvSolver::node_exchange ( ) const

inlinenoexcept

Borrow the last-window signed node exchange receipt.

Const references remain valid only while this solver lives; their underlying element pointers/contents can change on initialization or later stepping. Serialize reads with mutation.

Returns: Node-indexed ft3 positive into each node; storage is solver-owned and can change on advance/init.

◆ node_flood_volume()

const std::vector< double > & openswmm::fv::ExplicitFvSolver::node_flood_volume ( ) const

inlinenoexcept

Per-node flooding VOLUME (ft³) over the last advance().

◆ node_inflow_volume()

const std::vector< double > & openswmm::fv::ExplicitFvSolver::node_inflow_volume ( ) const

inlinenoexcept

Borrow accumulated arriving conduit-face volume magnitudes.

Const references remain valid only while this solver lives; their underlying element pointers/contents can change on initialization or later stepping. Serialize reads with mutation.

Returns: Node-indexed nonnegative ft3 over the last advance; do not reconstruct this split from net exchange.

◆ node_outflow_volume()

const std::vector< double > & openswmm::fv::ExplicitFvSolver::node_outflow_volume ( ) const

inlinenoexcept

Borrow accumulated departing conduit-face/diverted-lateral volume magnitudes.

Const references remain valid only while this solver lives; their underlying element pointers/contents can change on initialization or later stepping. Serialize reads with mutation.

Returns: Node-indexed ft3 over the last advance, kept separately from arrival for report/mass ledgers.

◆ node_passthrough()

const std::vector< std::uint8_t > & openswmm::fv::ExplicitFvSolver::node_passthrough ( ) const

inlinenoexcept

Borrow the current direct-face algebraic-node bypass mask.

Const references remain valid only while this solver lives; their underlying element pointers/contents can change on initialization or later stepping. Serialize reads with mutation.

Returns: Node-indexed flags refreshed with structure/lateral/carry/pressure state; solver head remains a stable diagnostic wet mean.

◆ node_publish_stage()

const std::vector< std::uint8_t > & openswmm::fv::ExplicitFvSolver::node_publish_stage ( ) const

inlinenoexcept

Borrow eligibility for reconstructing reported node stage from adjacent wet cells.

Const references remain valid only while this solver lives; their underlying element pointers/contents can change on initialization or later stepping. Serialize reads with mutation.

Returns: Node-indexed reporting mask, broader than degree-two solver pass-through eligibility. Demoted real ponds are excluded before return from advance.

◆ nodeVolumeFromDepth()

double openswmm::fv::ExplicitFvSolver::nodeVolumeFromDepth	(	int	node,
		double	depth ) const

Evaluate native node storage volume from depth.

Pondable depth above a positive full_depth uses its rim volume plus ponded_area*(depth-full_depth). A non-storage-table node uses its current node_surf_area*depth; a table node interpolates 129 uniform samples and extends above table top using node_vol_atop. Requires positive table spacing and valid nondegenerate geometry. No allocation, state mutation or independent validation.

Parameters

[in]	node	Valid initialized global node index with coherent storage arrays.
[in]	depth	Finite depth in ft; <=0 returns zero.

Returns: Volume in ft3.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ operator=()

ExplicitFvSolver & openswmm::fv::ExplicitFvSolver::operator= ( const ExplicitFvSolver & )

delete

Disallow copy assignment of a live solver.

Here is the call graph for this function:

◆ pressure_folded_nodes()

const std::vector< std::uint8_t > & openswmm::fv::ExplicitFvSolver::pressure_folded_nodes ( ) const

inlinenoexcept

Borrow the most recent pressure-classification folded-node mask.

Const references remain valid only while this solver lives; their underlying element pointers/contents can change on initialization or later stepping. Serialize reads with mutation.

Returns: Node-indexed flags. Historical if no current pressure pass ran; combine with current regime/forcing before interpreting.

◆ pressureCandidateRejections()

long openswmm::fv::ExplicitFvSolver::pressureCandidateRejections ( ) const

inlinenoexcept

Read the current restricted-candidate routing-window rejection count.

Returns: Retry count reset at entry to a nonempty enabled-candidate advance; may retain history when that path is not entered.

◆ pressureCandidateResult()

const NonlinearPressureStorage::Result & openswmm::fv::ExplicitFvSolver::pressureCandidateResult ( ) const

inlinenoexcept

Borrow the most recently attempted nonlinear pressure candidate diagnostics.

Returns: Const member reference; content changes when a later candidate is attempted and expires at solver destruction.

◆ reinitialize()

void openswmm::fv::ExplicitFvSolver::reinitialize ( double t0 )

overridevirtual

Invalidate stepping caches and refresh derived state after external restoration.

No-op when unbound. Invalidates LTS/active-list/CFL caches, refreshes depths/velocity/closure and node areas. Does not clear run statistics, numerical carry, borrowed topology, existing TPA history or all report receipts; use initialize for a new run. Does not rebuild static topology/eligibility caches.

Parameters

[in] t0 Compatibility time in seconds; ignored by this implementation.

Implements openswmm::fv::INetworkSolver.

◆ requireConservativeNodeBalance()

void openswmm::fv::ExplicitFvSolver::requireConservativeNodeBalance ( bool enabled )

inlinenoexcept

◆ run_stats()

INetworkSolver::RunStats openswmm::fv::ExplicitFvSolver::run_stats ( ) const

overridevirtualnoexcept

Read cumulative statistics. Default: zeros (backend has no counters).

Reimplemented from openswmm::fv::INetworkSolver.

◆ setConduitStepSink()

void openswmm::fv::ExplicitFvSolver::setConduitStepSink	(	ConduitStepSink	fn,
		void *	user )

inlinenoexcept

Set an optional synchronous per-conduit accepted-step reporting observer.

Every accepted global step/LTS macro cycle invokes once per conduit. The sink is reporting-only, must not throw, retain transient arguments, reenter the solver or mutate its mesh/state. Restricted nonlinear candidate validation disallows the sink. Replacing a sink does not release user storage.

Parameters

[in]	fn	Callback(user,conduit_row,governing_dt,duration), or nullptr to disable; dt/duration are seconds and conduit row is mesh ConduitData indexing.
[in]	user	Opaque borrowed callback context retained alongside fn; caller keeps it live until replaced or solver destruction.

◆ suggested_step()

double openswmm::fv::ExplicitFvSolver::suggested_step ( ) const

inlineoverridevirtualnoexcept

Read the next CFL step suggestion from the latest backend census.

Returns: Suggested seconds interpreted by Router adaptive routing; concrete backend defines values before initialization or after finalize.

Implements openswmm::fv::INetworkSolver.

◆ tier_occupancy()

const std::array< long, kMaxLtsTiers > & openswmm::fv::ExplicitFvSolver::tier_occupancy ( ) const

inlinenoexcept

Borrow the run tier-occupancy histogram.

Const references remain valid only while this solver lives; their underlying element pointers/contents can change on initialization or later stepping. Serialize reads with mutation.

Returns: Counts cells on every re-tier, including assignments whose macro cycle did not fit. It does not by itself count accepted macro cycles.

◆ trackAcceptedWater()

void openswmm::fv::ExplicitFvSolver::trackAcceptedWater ( bool enabled )

inline

Enable optional water-transfer observations after initialize(). Disabled runs allocate/record nothing. Changing this invalidates borrowed rows.

◆ unmetWithdrawalVolumes()

const std::vector< double > & openswmm::fv::ExplicitFvSolver::unmetWithdrawalVolumes ( ) const

inlinenoexcept

◆ withdrawalRates() [1/2]

const std::vector< double > & openswmm::fv::ExplicitFvSolver::withdrawalRates ( ) const

inlinenoexcept

◆ withdrawalRates() [2/2]

std::vector< double > & openswmm::fv::ExplicitFvSolver::withdrawalRates ( )

inlinenoexcept

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

/home/runner/work/openswmm.engine/openswmm.engine/src/engine/hydraulics/fv/ExplicitFvSolver.hpp
/home/runner/work/openswmm.engine/openswmm.engine/src/engine/hydraulics/fv/ExplicitFvSolver.cpp

Public Types

Public Member Functions

Member Typedef Documentation

◆ ConduitStepSink

Constructor & Destructor Documentation

◆ ExplicitFvSolver() [1/2]

◆ ~ExplicitFvSolver()

◆ ExplicitFvSolver() [2/2]

Member Function Documentation

◆ acceptedWater()

◆ advance()

◆ bookDivertedLateral()

◆ cell_flow_integral()

◆ divergence()

◆ dummy_volume()

◆ enablePressureStorageCandidate()

◆ finalize()

◆ initialize()

◆ inlet_control()

◆ is_initialized()

◆ last_num_steps()

◆ last_step_size()

◆ lts_tiers()

◆ node_continuity_carry()

◆ node_exchange()

◆ node_flood_volume()

◆ node_inflow_volume()

◆ node_outflow_volume()

◆ node_passthrough()

◆ node_publish_stage()

◆ nodeVolumeFromDepth()

◆ operator=()

◆ pressure_folded_nodes()

◆ pressureCandidateRejections()

◆ pressureCandidateResult()

◆ reinitialize()

◆ requireConservativeNodeBalance()

◆ run_stats()

◆ setConduitStepSink()

◆ suggested_step()

◆ tier_occupancy()

◆ trackAcceptedWater()

◆ unmetWithdrawalVolumes()

◆ withdrawalRates() [1/2]

◆ withdrawalRates() [2/2]