openswmm::twoD::Infil2D Class Reference

Owns per-cell infiltration parameters, kernel state and held rates. More...

#include <Infil2D.hpp>

Collaboration diagram for openswmm::twoD::Infil2D:

Public Member Functions
std::vector< Infil2DDefault > &	defaults () noexcept
	Borrow the authored ordered star/tag fallback rows.
const std::vector< Infil2DDefault > &	defaults () const noexcept
	Borrow the authored ordered star/tag fallback rows.
std::vector< Infil2DOverride > &	overrides () noexcept
	Borrow the authored ordered per-cell overrides.
const std::vector< Infil2DOverride > &	overrides () const noexcept
	Borrow the authored ordered per-cell overrides.
Infil2DOptions &	options () noexcept
	Borrow the authored infiltration cadence options.
const Infil2DOptions &	options () const noexcept
	Borrow the authored infiltration cadence options.
bool	resolve (const MeshData &mesh, const SimulationOptions &opts, std::string &err)
	Resolve tag/override precedence into flat per-cell state.
void	setAquiferOwners (std::vector< uint8_t > owners)
	Effective coverage, not inferred from conductivity or authored rows.
const std::vector< std::string > &	ownershipMessages () const noexcept
	Borrow the most recent successful resolution's default-ownership diagnostics.
void	setAquifer2DAvailable (bool on) noexcept
	G1 — tell validation that a [2D_AQUIFER] resolved, so the AQUIFER_2D destination has somewhere to send its water.
bool	aquifer2DAvailable () const noexcept
	Read the stored aquifer-availability fallback flag.
void	updateRates (const MeshData &mesh, SurfaceStateData &state, double dt, surface::InfilBank::Factors factors={1.0, 1.0})
	Recompute and publish per-cell infiltration rates (D-I1).
void	updateRates (const MeshData &mesh, SurfaceStateData &state, double dt, surface::InfilBank::Factors factors, int num_threads)
surface::InfilBank &	bank () noexcept
	Borrow the canonical mutable per-cell infiltration bank.
bool	active () const noexcept
	True when at least one cell resolved to a model.
void	deactivate () noexcept
	E2: [2D_OPTIONS] INFILTRATION NO — keep the rows (they still save) but run without infiltration. Called after resolve().
const std::vector< Infil2DRow > &	resolvedRows () const noexcept
	Resolved method per triangle; has_method == false entries are NONE.
const std::vector< Infil2DProvenance > &	provenance () const noexcept
	Provenance per triangle (D-I3, for the writer).
const std::vector< double > &	cumulative () const noexcept
	Cumulative infiltration CAPACITY per triangle (m): the integral of the published rate, without the solver's depth ramp. On a drying cell this exceeds the water actually removed, so it is NOT ledger-consistent with MassBalance2D::infil_out. SurfaceRouter2D::infilCumulative() is the ledger-consistent series and is what the sidecar's infil_cum and the C API's *_get_cum_bulk report; this one is retained as the kernel-side diagnostic.
double	stepSeconds () const noexcept
	Resolved cadence in seconds (options_.infil_step, or the project WET_STEP when that was <= 0). Set by resolve().
void	reset ()
	Clear everything back to the unconfigured fast path.

Detailed Description

Owns per-cell infiltration parameters, kernel state and held rates.

Lifecycle:

1. Parsers fill defaults(), overrides(), options().
2. SurfaceRouter2D::initialize() calls resolve() once the mesh (and therefore MeshData::tri_tag) is available.
3. SurfaceRouter2D calls updateRates() every INFIL_STEP.
4. The marcher consumes SurfaceStateData::infil_rate only.

Empty/unconfigured is the fast path: active() is false and no array is allocated, so a project with no [2D_INFILTRATION*] sections is bitwise identical to the pre-track-I engine (gate I7).

Member Function Documentation

active()

bool openswmm::twoD::Infil2D::active ( ) const

inlinenoexcept

True when at least one cell resolved to a model.

Returns

True when successful resolution found ordinary model cells OR externally aquifer-owned cells, unless deactivate() was called. No allocation or runtime initialization; read stable owner state.

Here is the caller graph for this function:

aquifer2DAvailable()

bool openswmm::twoD::Infil2D::aquifer2DAvailable ( ) const

inlinenoexcept

Read the stored aquifer-availability fallback flag.

Returns

The last setAquifer2DAvailable() value, reset false by reset(); not proof of initialized aquifer coverage/runtime. No mutation or allocation.

bank()

surface::InfilBank & openswmm::twoD::Infil2D::bank ( )

inlinenoexcept

Borrow the canonical mutable per-cell infiltration bank.

Returns

Object-owned InfilBank reference, valid until replacement/reset/destruction. Caller must respect owner/cadence rules and serialize with resolve/updateRates; direct edits are not validated here. No allocation or ownership transfer.

cumulative()

const std::vector< double > & openswmm::twoD::Infil2D::cumulative ( ) const

inlinenoexcept

Cumulative infiltration CAPACITY per triangle (m): the integral of the published rate, without the solver's depth ramp. On a drying cell this exceeds the water actually removed, so it is NOT ledger-consistent with MassBalance2D::infil_out. SurfaceRouter2D::infilCumulative() is the ledger-consistent series and is what the sidecar's infil_cum and the C API's *_get_cum_bulk report; this one is retained as the kernel-side diagnostic.

Returns

Borrowed bank-owned per-cell cumulative capacity integral in m; diagnostic capacity, not actual availability-limited surface removal.

Note

Storage remains owned by this object/bank and may be invalidated or updated by resolve/updateRates/reset. Read stable state; do not free or retain element pointers across mutations. No allocation.

deactivate()

void openswmm::twoD::Infil2D::deactivate ( )

inlinenoexcept

E2: [2D_OPTIONS] INFILTRATION NO — keep the rows (they still save) but run without infiltration. Called after resolve().

Postcondition

Clears active_ only; authored rows, resolved arrays and kernel history remain stored. Subsequent updateRates() calls become no-ops; it does not zero already published state.infil_rate.

Note

Caller coordinates disabling consumption/published rates through the router. Exclusive access; no allocation or unit changes.

defaults() [1/2]

const std::vector< Infil2DDefault > & openswmm::twoD::Infil2D::defaults ( ) const

inlinenoexcept

Borrow the authored ordered star/tag fallback rows.

Returns

Const reference owned by this Infil2D, valid until reset, replacement, or object destruction; container element references may be invalidated by edits.

Note

Read only while authoring/resolution is stable. No allocation or ownership transfer.

defaults() [2/2]

std::vector< Infil2DDefault > & openswmm::twoD::Infil2D::defaults ( )

inlinenoexcept

Borrow the authored ordered star/tag fallback rows.

Returns

Mutable reference owned by this Infil2D, valid until reset, replacement, or object destruction; container element references may be invalidated by edits.

Note

Caller edits only during pre-run authoring and calls resolve() afterward; changing rows does not rebuild a running bank automatically. No allocation or ownership transfer.

Here is the caller graph for this function:

options() [1/2]

const Infil2DOptions & openswmm::twoD::Infil2D::options ( ) const

inlinenoexcept

Borrow the authored infiltration cadence options.

Returns

Const reference owned by this Infil2D, valid until reset, replacement, or object destruction; container element references may be invalidated by edits.

Note

Read only while authoring/resolution is stable. No allocation or ownership transfer.

options() [2/2]

Infil2DOptions & openswmm::twoD::Infil2D::options ( )

inlinenoexcept

Borrow the authored infiltration cadence options.

Returns

Mutable reference owned by this Infil2D, valid until reset, replacement, or object destruction; container element references may be invalidated by edits.

Note

Caller edits only during pre-run authoring and calls resolve() afterward; changing rows does not rebuild a running bank automatically. No allocation or ownership transfer.

Here is the caller graph for this function:

overrides() [1/2]

const std::vector< Infil2DOverride > & openswmm::twoD::Infil2D::overrides ( ) const

inlinenoexcept

Borrow the authored ordered per-cell overrides.

Returns

Const reference owned by this Infil2D, valid until reset, replacement, or object destruction; container element references may be invalidated by edits.

Note

Read only while authoring/resolution is stable. No allocation or ownership transfer.

overrides() [2/2]

std::vector< Infil2DOverride > & openswmm::twoD::Infil2D::overrides ( )

inlinenoexcept

Borrow the authored ordered per-cell overrides.

Returns

Mutable reference owned by this Infil2D, valid until reset, replacement, or object destruction; container element references may be invalidated by edits.

Note

Caller edits only during pre-run authoring and calls resolve() afterward; changing rows does not rebuild a running bank automatically. No allocation or ownership transfer.

Here is the caller graph for this function:

ownershipMessages()

const std::vector< std::string > & openswmm::twoD::Infil2D::ownershipMessages ( ) const

inlinenoexcept

Borrow the most recent successful resolution's default-ownership diagnostics.

Returns

Object-owned string vector describing applied/skipped ordinary default counts. Valid until resolve/reset/replacement/destruction; never free it. No allocation; read while state is stable.

provenance()

const std::vector< Infil2DProvenance > & openswmm::twoD::Infil2D::provenance ( ) const

inlinenoexcept

Provenance per triangle (D-I3, for the writer).

Returns

Borrowed per-cell provenance codes; empty after inactive resolution/reset.

Note

Storage remains owned by this object/bank and may be invalidated or updated by resolve/updateRates/reset. Read stable state; do not free or retain element pointers across mutations. No allocation.

reset()

void openswmm::twoD::Infil2D::reset

(

)

Clear everything back to the unconfigured fast path.

Postcondition

Erases authored rows/options, aquifer owners/fallback, diagnostics, resolved rows/provenance and kernel history; active false and cadence zero. Does not clear rates already held in an external SurfaceStateData.

Note

Requires exclusive lifecycle access; invalidates borrowed bank/configuration/state views. No external model ownership is changed.

resolve()

bool openswmm::twoD::Infil2D::resolve	(	const MeshData &	mesh,
		const SimulationOptions &	opts,
		std::string &	err )

Resolve tag/override precedence into flat per-cell state.

D-I3 precedence: override > tag > '' > none. Initializes the hydrology kernel state for every cell that resolved to a model, converting project-unit parameters through `infil::_init`.

Parameters

[in]	mesh	Mesh (uses tri_tag and n_triangles()).
[in]	opts	Simulation options (unit system for the *_init conversions).
[out]	err	[out] Human-readable message when the return is false.

Returns

False on a validation failure (unsupported destination, out-of-range triangle index, unknown method, bad parameters).

Precondition

Called during pre-run setup after aquifer ownership is supplied; mesh cell/tag arrays and simulation unit options are valid.

Postcondition

On success publishes a fully resolved private candidate with newly initialized kernel history and zero capacity integrals. On validation failure this object remains unchanged; err contains a diagnostic. Successful calls need not clear a preexisting err string.

Note

Ownership coverage must match cell_count; star/tag ordinary defaults skip aquifer-owned cells, explicit ordinary model overrides there are refused, and obsolete AQUIFER_2D destinations are rejected. Copy/allocation exceptions propagate without publishing the candidate; no input references retained. Requires exclusive access.

resolvedRows()

const std::vector< Infil2DRow > & openswmm::twoD::Infil2D::resolvedRows ( ) const

inlinenoexcept

Resolved method per triangle; has_method == false entries are NONE.

Returns

Borrowed resolved per-cell parameter vector, in original project units; empty after inactive resolution/reset.

Note

Storage remains owned by this object/bank and may be invalidated or updated by resolve/updateRates/reset. Read stable state; do not free or retain element pointers across mutations. No allocation.

setAquifer2DAvailable()

void openswmm::twoD::Infil2D::setAquifer2DAvailable ( bool on )

inlinenoexcept

G1 — tell validation that a [2D_AQUIFER] resolved, so the AQUIFER_2D destination has somewhere to send its water.

Supplies only fallback owner coverage when an explicit owner mask is empty. AQUIFER_2D remains obsolete and resolve() rejects such rows.

Parameters

[in]

on

Whether aquifer coverage is available as an all-cell fallback when no explicit owner mask exists.

Postcondition

Stores a fallback flag only; does not validate or activate obsolete AQUIFER_2D row destinations. Call before resolve(), with exclusive pre-run access.

setAquiferOwners()

void openswmm::twoD::Infil2D::setAquiferOwners ( std::vector< uint8_t > owners )

inline

Effective coverage, not inferred from conductivity or authored rows.

Replace explicit effective aquifer coverage used by the next resolve.

Parameters

[in]

owners

Owned coverage mask, one entry per mixed cell, zero ordinary/nonzero external aquifer. Moved into this object.

Postcondition

Does not rebuild kernels or validate extent immediately; resolve() checks it. Empty coverage asks resolve to use aquifer2DAvailable() as an all-cell fallback. Requires exclusive pre-run authoring access.

stepSeconds()

double openswmm::twoD::Infil2D::stepSeconds ( ) const

inlinenoexcept

Resolved cadence in seconds (options_.infil_step, or the project WET_STEP when that was <= 0). Set by resolve().

Returns

Resolved cadence in seconds: positive authored infil_step, otherwise the project's wet_step. Zero before resolve/reset. Read-only; this getter does not resolve or validate the cadence.

Here is the caller graph for this function:

updateRates() [1/2]

void openswmm::twoD::Infil2D::updateRates	(	const MeshData &	mesh,
		SurfaceStateData &	state,
		double	dt,
		surface::InfilBank::Factors	factors,
		int	num_threads )

Same cell-local updates with a configured worker count. Distinct prepared bank entries may advance concurrently; source/configuration arrays stay stable and same-entry/lifecycle operations remain exclusive.

updateRates() [2/2]

void openswmm::twoD::Infil2D::updateRates	(	const MeshData &	mesh,
		SurfaceStateData &	state,
		double	dt,
		surface::InfilBank::Factors	factors = {1.0, 1.0} )

Recompute and publish per-cell infiltration rates (D-I1).

Called on the INFIL_STEP cadence. Advances kernel state for EVERY model-carrying cell, including cells the marcher has deactivated — otherwise a dry cell presents full initial capacity when rain finally arrives (§5.5.2).

Writes state.infil_rate[i] in m/s, >= 0. Conversion: precip/depth SI→ft on the way in, rate ft/s→SI on the way out.

Parameters

[in]	mesh	Mesh (unused today; kept for symmetry and future area use).
[in,out]	state	Surface state — reads rainfall/depth, writes infil_rate.
[in]	dt	Elapsed seconds since the previous call (the INFIL_STEP).
[in]	factors	Monthly/global InfilBank adjustment factors, dimensionless; defaults are unity.

Precondition

Resolved bank and source/depth/rate arrays have compatible cell extents; ordinary rows use valid project-unit parameters and finite dt.

Postcondition

Advances ordinary cell infiltration kernel history and publishes held SI m/s rates for model-carrying nonexternal rows. Aquifer-owned/no-method rows remain for their separate owner; cells beyond min(resolved size, output rate size) are untouched.

Note

Inactive or dt <= 0 is a no-op; no explicit NaN dt guard exists. Does not integrate removed surface volume or update mass-balance ledgers. Exclusive bank/output access is required; input pointers are not retained.

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/2d/infil/Infil2D.hpp
• /home/runner/work/openswmm.engine/openswmm.engine/src/engine/2d/infil/Infil2D.cpp