#include <ImplicitReachSolver.hpp>

Collaboration diagram for openswmm::fv::ImplicitReachSolver:

Classes
struct	BlockDiagnostics

struct	Controls

struct	Endpoint

struct	LinearControls

struct	Linearization

struct	LinearResult

struct	Problem

struct	Result

Public Types
enum class	LinearMethod { StructuredThenGmres , StructuredOnly , GmresOnly }

enum class	Preconditioner { BlockLine , BlockJacobi }

enum class	Status { Converged , InvalidInput , NonFinite , LinearFailure , LineSearchFailed , IterationLimit }

using	Pair = std::array<double, 2>

using	Block = std::array<double, 4>

Public Member Functions
Result	solve (const Problem &p, double dt, const Controls &controls, Endpoint &output)
	Solve one supported implicit reach timestep with bounded Newton/backtracking.

Static Public Member Functions
static bool	residual (const Problem &p, const std::vector< Pair > &trial, double dt, std::vector< Pair > &output, std::vector< kernels::FaceFlux > *faces=nullptr)
	Evaluate backward-Euler integrated volume and momentum residuals.

static bool	linearize (const Problem &p, const std::vector< Pair > &trial, double dt, double difference_step, Linearization &out)
	Build the scaled local block-tridiagonal finite-difference Jacobian.

static bool	solveBlocks (const Linearization &l, const std::vector< Pair > &rhs, std::vector< Pair > &output, double &relative_residual, BlockDiagnostics *diagnostics=nullptr)
	Solve the scaled block-tridiagonal system with native two-by-two Thomas elimination.

static LinearResult	solveLinear (const Linearization &l, const std::vector< Pair > &rhs, const LinearControls &controls, std::vector< Pair > &output)
	Solve the original scaled reach system with structured elimination or fixed right-preconditioned GMRES.

Detailed Description

Standalone P1 experiment. No routing factory, input option or GUI selects it. Backward Euler on the original cell (A,Q) equations with the existing HLL flux. Only a flat, prismatic, single reach, fully above the SLOT taper is supported. Each end is a wall or a prescribed stage with extrapolated interior velocity. No nodes, structures, transport, TPA or forcing are solved.

Member Typedef Documentation

◆ Block

using openswmm::fv::ImplicitReachSolver::Block = std::array<double, 4>

◆ Pair

using openswmm::fv::ImplicitReachSolver::Pair = std::array<double, 2>

Member Enumeration Documentation

◆ LinearMethod

enum class openswmm::fv::ImplicitReachSolver::LinearMethod

strong

Enumerator
StructuredThenGmres
StructuredOnly
GmresOnly

◆ Preconditioner

enum class openswmm::fv::ImplicitReachSolver::Preconditioner

strong

Enumerator
BlockLine
BlockJacobi

◆ Status

enum class openswmm::fv::ImplicitReachSolver::Status

strong

Enumerator
Converged
InvalidInput
NonFinite
LinearFailure
LineSearchFailed
IterationLimit

Member Function Documentation

◆ linearize()

bool openswmm::fv::ImplicitReachSolver::linearize	(	const Problem &	p,
		const std::vector< Pair > &	trial,
		double	dt,
		double	difference_step,
		Linearization &	out )

static

Build the scaled local block-tridiagonal finite-difference Jacobian.

Only the two faces adjoining each perturbed cell and its friction term are recomputed, giving O(N) local work. Depth scale is 1 ft; discharge scale is max(c*T) over the old state. Physical row scales are dx*T_old and dx*qscale. No global dense Jacobian is formed. Allocations propagate; finite coefficients are checked by the subsequent linear solve.

Parameters

[in]	p	Borrowed mesh and copied old-state arrays for >=2 cells in one flat prismatic closed reach, one geometry and one conduit. Old A/Q must be finite and within [lower_depth,upper_depth] after inversion; lower_depth>=y_full, upper_depth>lower_depth. End stages are finite depths within bounds or NaN for reflective walls. No gates, culverts, offsets, local losses, force mains, TPA, nodes, structures or species are supported; no pointer is retained.
[in]	trial	One {depth ft, aggregate discharge ft3/s} pair per cell, finite and within the problem depth bounds.
[in]	dt	Finite positive substep in seconds.
[in]	difference_step	Finite positive relative perturbation, multiplied by max(1,abs(component)); depth perturbations clip to problem bounds.
[out]	out	Receives a complete scaled Jacobian/residual and row/column scales only on success.

Returns: False for invalid problem/trial, collapsed perturbation or invalid scaling/residual; true publishes the linearization.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ residual()

bool openswmm::fv::ImplicitReachSolver::residual	(	const Problem &	p,
		const std::vector< Pair > &	trial,
		double	dt,
		std::vector< Pair > &	output,
		std::vector< kernels::FaceFlux > *	faces = nullptr )

static

Evaluate backward-Euler integrated volume and momentum residuals.

Volume uses dx*(A(h)-old_area)+dt*(Fright-Fleft). Momentum uses dx*(Q-oldQ)+dt*(Gright-Gleft+dx*friction). Face fluxes re-evaluate the actual shared HLL branches; prescribed stages extrapolate interior velocity and walls reflect it. Allocations can throw. A valid physical closure with positive wet area/radius remains a caller precondition.

Parameters

[in]	p	Borrowed mesh and copied old-state arrays for >=2 cells in one flat prismatic closed reach, one geometry and one conduit. Old A/Q must be finite and within [lower_depth,upper_depth] after inversion; lower_depth>=y_full, upper_depth>lower_depth. End stages are finite depths within bounds or NaN for reflective walls. No gates, culverts, offsets, local losses, force mains, TPA, nodes, structures or species are supported; no pointer is retained.
[in]	trial	One {depth ft, aggregate discharge ft3/s} pair per cell, finite and within the problem depth bounds.
[in]	dt	Finite positive substep in seconds.
[out]	output	Receives per-cell {volume defect ft3, integrated-discharge defect ft4/s} only after all checks pass.
[out]	faces	Optional writable n+1 face-flux array, or nullptr; published only on success.

Returns: True for a supported problem and finite admissible residual/flux evaluation; false leaves outputs unchanged.

Here is the caller graph for this function:

◆ solve()

ImplicitReachSolver::Result openswmm::fv::ImplicitReachSolver::solve	(	const Problem &	p,
		double	dt,
		const Controls &	controls,
		Endpoint &	output )

Solve one supported implicit reach timestep with bounded Newton/backtracking.

Starts from actual old conserved area/discharge, re-evaluates true integrated equations every trial, and accepts only budget satisfaction or Armijo reduction. Halves line-search steps without clipping/repairing accepted area or momentum. The endpoint is built locally before publication, so returned failures preserve output. Allocations can throw; this standalone experiment is not selected by routing/input/GUI options.

Parameters

[in]	p	Borrowed mesh and copied old-state arrays for >=2 cells in one flat prismatic closed reach, one geometry and one conduit. Old A/Q must be finite and within [lower_depth,upper_depth] after inversion; lower_depth>=y_full, upper_depth>lower_depth. End stages are finite depths within bounds or NaN for reflective walls. No gates, culverts, offsets, local losses, force mains, TPA, nodes, structures or species are supported; no pointer is retained.
[in]	dt	Finite positive timestep in seconds.
[in]	controls	Nonnegative Newton/backtrack limits; positive difference_step; nonnegative finite absolute/relative volume and momentum budgets, with a positive budget combination for each row kind.
[out]	output	Receives complete area ft2, discharge ft3/s, depth ft and n+1 face-flux arrays only on convergence.

Returns: Converged, InvalidInput, NonFinite, LinearFailure, LineSearchFailed or IterationLimit with residual/work counters.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ solveBlocks()

bool openswmm::fv::ImplicitReachSolver::solveBlocks	(	const Linearization &	l,
		const std::vector< Pair > &	rhs,
		std::vector< Pair > &	output,
		double &	relative_residual,
		BlockDiagnostics *	diagnostics = nullptr )

static

Solve the scaled block-tridiagonal system with native two-by-two Thomas elimination.

Allocates O(N) temporary factors/solution without a workspace cap. Output may alias rhs because publication follows every read. Allocation exceptions propagate.

Parameters

[in]	l	Nonempty equal-sized lower/diagonal/upper block arrays; each block is row-major. No cross-block pivoting is available.
[in]	rhs	Finite two-component scaled right-hand side per block.
[out]	output	Receives scaled solution pairs only after finite and true-residual acceptance.
[in,out]	relative_residual	Written after residual evaluation as \|\|Ax-b\|\|/\|\|b\|\| (or absolute norm for zero RHS); earlier pivot/shape failures leave the prior value.
[out]	diagnostics	Optional writable pivot diagnostics; reset on entry, then records minimum elimination-pivot/scale ratio and failing block.

Returns: True if local pivots exceed 1e-14 of block scale and true error <=1e-12+1e-10*||rhs||; false leaves solution unchanged.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ solveLinear()

ImplicitReachSolver::LinearResult openswmm::fv::ImplicitReachSolver::solveLinear	(	const Linearization &	l,
		const std::vector< Pair > &	rhs,
		const LinearControls &	controls,
		std::vector< Pair > &	output )

static

Solve the original scaled reach system with structured elimination or fixed right-preconditioned GMRES.

StructuredThenGmres attempts direct Thomas first; StructuredOnly returns its failure. Unsafe line preconditioner blocks receive bounded diagonal shifts, while unsafe Jacobi blocks use identity; the actual matrix is never altered. GMRES budget includes wrapper buffers plus native workspace, but the preceding direct solve is not workspace-capped. Allocation exceptions outside NativeGmres propagate. No mesh/state is retained or modified.

Parameters

[in]	l	Equal-sized finite nonempty block-tridiagonal matrix; row/column scaling metadata is not consumed here.
[in]	rhs	Finite scaled RHS pair per block.
[in]	controls	Structured/GMRES selection, BlockLine/BlockJacobi preconditioner and native GMRES budgets.
[out]	output	Receives scaled correction pairs only on convergence; failure preserves prior contents.

Returns: Convergence/fallback/residual/preconditioner/workspace diagnostics.

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/hydraulics/fv/ImplicitReachSolver.hpp
/home/runner/work/openswmm.engine/openswmm.engine/src/engine/hydraulics/fv/ImplicitReachSolver.cpp

Classes

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Typedef Documentation

◆ Block

◆ Pair

Member Enumeration Documentation

◆ LinearMethod

◆ Preconditioner

◆ Status

Member Function Documentation

◆ linearize()

◆ residual()

◆ solve()

◆ solveBlocks()

◆ solveLinear()