OpenSWMM Engine  6.0.0-alpha.4
Data-oriented, plugin-extensible SWMM Engine (6.0.0-alpha.4)
Loading...
Searching...
No Matches
Classes | Public Member Functions | List of all members
openswmm::twoD::ISurfaceSolver Class Referenceabstract

Abstract time integrator for the 2D surface-routing ODE system. More...

#include <ISurfaceSolver.hpp>

Inheritance diagram for openswmm::twoD::ISurfaceSolver:
Collaboration diagram for openswmm::twoD::ISurfaceSolver:

Classes

struct  RunStats
 

Public Member Functions

virtual ~ISurfaceSolver ()=default
 Destroy a backend solver through its polymorphic interface.
 
virtual void initialize (MeshData &mesh, SurfaceStateData &state, SolverOptions2D &opts)=0
 One-time setup. mesh and state must outlive the solver.
 
virtual double advance (double t_current, double t_target)=0
 Advance the solution from t_current to t_target (s).
 
virtual double completedSourceTime () const noexcept
 Horizon through which ALL cell sources have actually landed, including lazy inactive cells and LTS accumulators. Unsupported backends return -1; an outer routing endpoint alone is not source-completion evidence.
 
virtual void reinitialize (double t0)=0
 Reinitialize the integrator at t0 after external state edits.
 
virtual void resyncFromVolumes (double t0)
 Re-time the integrator at t0 keeping the SIGNED cell volumes from state.volume. Used by the failed-window freeze path: reinitialize() reseeds from the reconstructed head, which clamps at the dry anchor and silently zeroes negative-volume debt (creating water); this variant preserves it. Default falls back to reinitialize() for backends that have not implemented volume-exact resync.
 
virtual void finalize ()=0
 Release all backend resources.
 
virtual long last_num_steps () const noexcept=0
 Number of internal integrator steps in the last advance() call.
 
virtual double last_step_size () const noexcept=0
 Last internal step size used by the integrator.
 
virtual const std::vector< double > & last_coupling_exchange () const noexcept
 Per-point ∫Q dt (m³) from the live node-coupling macro-step path. Default returns empty for backends that do not implement live coupling (so the caller falls back to the held-flux booking). See ExplicitInertialSolver.
 
virtual RunStats run_stats () const noexcept
 Read cumulative statistics. Default: zeros (backend has no counters).
 
virtual bool is_initialized () const noexcept=0
 True once initialize() has completed and the solver is ready.
 

Detailed Description

Abstract time integrator for the 2D surface-routing ODE system.

The method set mirrors the lifecycle SurfaceRouter2D drives: one-time setup, repeated advance, optional reinitialize after external state edits (hot start), and teardown. The status accessors expose the most recent integrator step count and step size for runtime reporting.

Implementations are non-copyable (they own backend resources) and owned by SurfaceRouter2D through a unique_ptr<ISurfaceSolver>; the virtual destructor makes that deletion correct.

Constructor & Destructor Documentation

◆ ~ISurfaceSolver()

virtual openswmm::twoD::ISurfaceSolver::~ISurfaceSolver ( )
virtualdefault

Destroy a backend solver through its polymorphic interface.

Note
Caller first stops concurrent operations and keeps all retained mesh/state/options storage alive until resources are released. Plugin objects require plugin-owned destruction on their controlling thread.

Member Function Documentation

◆ advance()

virtual double openswmm::twoD::ISurfaceSolver::advance ( double t_current,
double t_target )
pure virtual

Advance the solution from t_current to t_target (s).

Returns
the time actually reached (== t_target on success).
Parameters
[in]t_currentFinite elapsed simulation start time, seconds, matching initialized solver time.
[in]t_targetFinite desired elapsed endpoint, seconds, at least t_current.
Postcondition
Mutates accepted hydraulics/transport, accumulators and step telemetry; partial progress/failure handling is backend-specific.
Note
A returned endpoint alone does not prove source completion; query completedSourceTime(). Call synchronously between external edits; references passed at initialize remain valid. Backend exceptions may propagate.

Implemented in openswmm::twoD::ExplicitInertialSolver, openswmm::twoD::gpu::ExplicitKokkosSurfaceSolver, and openswmm::twoD::PluginSurfaceSolver.

◆ completedSourceTime()

virtual double openswmm::twoD::ISurfaceSolver::completedSourceTime ( ) const
inlinevirtualnoexcept

Horizon through which ALL cell sources have actually landed, including lazy inactive cells and LTS accumulators. Unsupported backends return -1; an outer routing endpoint alone is not source-completion evidence.

Returns
Completed source horizon in elapsed simulation seconds, or -1 for unsupported/unavailable evidence. Default returns -1 without mutation/allocation; concrete backends may cache it. Serialize reads with stepping.

Reimplemented in openswmm::twoD::ExplicitInertialSolver, and openswmm::twoD::PluginSurfaceSolver.

◆ finalize()

virtual void openswmm::twoD::ISurfaceSolver::finalize ( )
pure virtual

Release all backend resources.

Postcondition
Releases backend-owned buffers and invalidates initialization state; caller retains mesh/state/options ownership. Concrete lifecycle/idempotence is backend-specific.
Note
Serialize with all calls and respect a plugin's controlling-thread contract. Process Kokkos runtime lifetime is separate from per-solver finalization.

Implemented in openswmm::twoD::ExplicitInertialSolver, openswmm::twoD::gpu::ExplicitKokkosSurfaceSolver, and openswmm::twoD::PluginSurfaceSolver.

◆ initialize()

virtual void openswmm::twoD::ISurfaceSolver::initialize ( MeshData & mesh,
SurfaceStateData & state,
SolverOptions2D & opts )
pure virtual

One-time setup. mesh and state must outlive the solver.

Parameters
[in,out]meshBuilt mesh geometry/topology in SI units, retained by implementations; must outlive the initialized solver.
[in,out]statePreallocated hydrodynamic/transport state, mutated during setup and stepping; must outlive the solver.
[in,out]optsValidated solver configuration, retained by implementations; keep alive and edit only through supported between-step paths.
Precondition
Topology, boundary/coupling wiring and derived storage are prepared by SurfaceRouter2D. Serialize setup/use/finalize on this solver.
Note
May allocate or throw on unsupported configuration/setup failure; the interface provides no transactional rollback guarantee. Caller owns all referenced model storage.

Implemented in openswmm::twoD::ExplicitInertialSolver, openswmm::twoD::gpu::ExplicitKokkosSurfaceSolver, and openswmm::twoD::PluginSurfaceSolver.

◆ is_initialized()

virtual bool openswmm::twoD::ISurfaceSolver::is_initialized ( ) const
pure virtualnoexcept

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

Returns
True only when backend initialization completed and resources are ready.
Note
Read-only nonthrowing status query. Serialize reads with mutations unless the concrete adapter explicitly provides safe snapshots.

Implemented in openswmm::twoD::ExplicitInertialSolver, openswmm::twoD::gpu::ExplicitKokkosSurfaceSolver, and openswmm::twoD::PluginSurfaceSolver.

◆ last_coupling_exchange()

virtual const std::vector< double > & openswmm::twoD::ISurfaceSolver::last_coupling_exchange ( ) const
inlinevirtualnoexcept

Per-point ∫Q dt (m³) from the live node-coupling macro-step path. Default returns empty for backends that do not implement live coupling (so the caller falls back to the held-flux booking). See ExplicitInertialSolver.

Returns
Borrowed per-coupling-point signed integrated volumes in m3, positive 2D-to-1D. Default returns an immutable empty vector. Reference is owned by the solver (or static default), must not be freed, and values may change on the next advance/reinitialize/finalize.
Note
Read only between solver mutations; an empty vector asks the caller to use held-flux accounting instead of live coupling receipts.

Reimplemented in openswmm::twoD::ExplicitInertialSolver, openswmm::twoD::gpu::ExplicitKokkosSurfaceSolver, and openswmm::twoD::PluginSurfaceSolver.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ last_num_steps()

virtual long openswmm::twoD::ISurfaceSolver::last_num_steps ( ) const
pure virtualnoexcept

Number of internal integrator steps in the last advance() call.

Returns
Number of internal substeps from the last advance, as a value copy.
Note
Read-only nonthrowing status query. Serialize reads with mutations unless the concrete adapter explicitly provides safe snapshots.

Implemented in openswmm::twoD::ExplicitInertialSolver, openswmm::twoD::gpu::ExplicitKokkosSurfaceSolver, and openswmm::twoD::PluginSurfaceSolver.

◆ last_step_size()

virtual double openswmm::twoD::ISurfaceSolver::last_step_size ( ) const
pure virtualnoexcept

Last internal step size used by the integrator.

Returns
Last internal accepted substep size in seconds; does not advance time.
Note
Read-only nonthrowing status query. Serialize reads with mutations unless the concrete adapter explicitly provides safe snapshots.

Implemented in openswmm::twoD::ExplicitInertialSolver, openswmm::twoD::gpu::ExplicitKokkosSurfaceSolver, and openswmm::twoD::PluginSurfaceSolver.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ reinitialize()

virtual void openswmm::twoD::ISurfaceSolver::reinitialize ( double t0)
pure virtual

Reinitialize the integrator at t0 after external state edits.

Parameters
[in]t0Finite elapsed time in seconds for reseeding after a hotstart/external state edit.
Note
Requires initialized retained state and serialized access. Backend implementations may rebuild momentum/tier/source caches from edited heads and reset local telemetry; errors may propagate. Use resyncFromVolumes() when signed-volume debt must be preserved.

Implemented in openswmm::twoD::ExplicitInertialSolver, openswmm::twoD::gpu::ExplicitKokkosSurfaceSolver, and openswmm::twoD::PluginSurfaceSolver.

Here is the caller graph for this function:

◆ resyncFromVolumes()

virtual void openswmm::twoD::ISurfaceSolver::resyncFromVolumes ( double t0)
inlinevirtual

Re-time the integrator at t0 keeping the SIGNED cell volumes from state.volume. Used by the failed-window freeze path: reinitialize() reseeds from the reconstructed head, which clamps at the dry anchor and silently zeroes negative-volume debt (creating water); this variant preserves it. Default falls back to reinitialize() for backends that have not implemented volume-exact resync.

Parameters
[in]t0Finite elapsed simulation time, seconds.
Note
Requires initialized retained model arrays and exclusive solver access. The default implementation calls reinitialize(t0), so only overriding backends guarantee exact signed-volume preservation. Backend errors may propagate; no ownership changes.

Reimplemented in openswmm::twoD::ExplicitInertialSolver, openswmm::twoD::gpu::ExplicitKokkosSurfaceSolver, and openswmm::twoD::PluginSurfaceSolver.

Here is the call graph for this function:

◆ run_stats()

virtual RunStats openswmm::twoD::ISurfaceSolver::run_stats ( ) const
inlinevirtualnoexcept

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

Returns
Value-owned cumulative RunStats; the default implementation returns zero/unpopulated counters.
Note
Read-only nonthrowing status query. Serialize reads with mutations unless the concrete adapter explicitly provides safe snapshots.

Reimplemented in openswmm::twoD::ExplicitInertialSolver, openswmm::twoD::gpu::ExplicitKokkosSurfaceSolver, and openswmm::twoD::PluginSurfaceSolver.

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