#include <GroundPorewater.hpp>

Collaboration diagram for openswmm::twoD::GroundPorewaterColumn:

Public Member Functions
std::string	publishSigma (SubsurfaceTransportState &, int cell)
	Publish pending SIGMA contact receipts and refresh the derived physical-layer views.

void	refreshSigmaView ()
	Rebuild physical-layer mass and reservation views from an active SIGMA overlap map.

bool	active () const noexcept
	Test whether at least one species row is configured.

std::string	initialize (const PorousHeatColumn &, const std::vector< double > &saturated_water, const std::vector< double > &saturated_mass, const std::vector< double > &unsaturated_mass, const std::vector< double > &kd, int age, int temperature)
	Seed canonical physical-layer species inventories from saturated/unsaturated totals.

std::pair< std::vector< double >, std::vector< double > >	zoneMasses (const PorousHeatColumn &, const std::vector< double > &saturated_water) const
	Derive saturated and unsaturated totals without creating another inventory.

std::pair< double, double >	zoneMass (const PorousHeatColumn &, const std::vector< double > &saturated_water, int species) const noexcept
	Derive one species' saturated/unsaturated split from physical-layer mass.

bool	generateAge (const PorousHeatColumn &, double seconds) noexcept
	Add elapsed water age to every physical layer and its generation ledger.

double	contactAvailableMass (int species, std::size_t layer) const noexcept
	Read unreserved physical-layer inventory available to a finite contact.

bool	canReserveOutgoing (int species, std::size_t layer, double amount) const noexcept
	Preflight an outgoing reservation against unreserved canonical mass.

bool	reserveOutgoing (int species, std::size_t layer, double amount) noexcept
	Reserve accepted outgoing inventory without subtracting its canonical mass.

bool	settleOutgoingReservation (int species, std::size_t layer, double amount) noexcept
	Release a queued outgoing reservation after its owning gather has consumed the packet.

bool	canApplyContactMassIncrement (int species, std::size_t layer, double increment) const noexcept
	Preflight a signed contact receipt without spending reserved outgoing inventory.

bool	applyContactMassIncrement (int species, std::size_t layer, double increment) noexcept
	Apply a signed finite-contact receipt to the physical layer and optional SIGMA view.

Public Attributes
int	n_species = 0

int	age_row = -1

int	temp_row = -1

std::vector< double >	mass

std::vector< double >	retention

std::vector< double >	initial_mass

std::vector< double >	contact_mass

std::vector< double >	reserved_out

std::vector< double >	generated_age

SigmaPorewaterMap	sigma

Member Function Documentation

◆ active()

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

inlinenoexcept

Test whether at least one species row is configured.

Returns: n_species > 0; does not validate inventory shapes or SIGMA mapping state.

◆ applyContactMassIncrement()

bool openswmm::twoD::GroundPorewaterColumn::applyContactMassIncrement	(	int	r,
		std::size_t	j,
		double	increment )

noexcept

Apply a signed finite-contact receipt to the physical layer and optional SIGMA view.

Declaration arguments

species (in): Valid non-temperature species row.
layer (in): Physical layer index.
increment (in): Finite signed native inventory change, positive into this layer.

Returns: True after increasing mass/contact_mass and, when active, distributing the same receipt through sigma.apply(). False leaves state unchanged on shape/value/budget or SIGMA refusal.

Note: Does not consume outgoing reservation overlays. Requires exclusive access to this column.

Parameters

[in]	r	Valid non-temperature species row.
[in]	j	Physical layer index.
[in]	increment	Finite signed native inventory change, positive into this layer.

Returns: True after increasing mass/contact_mass and, when active, distributing the same receipt through sigma.apply(). False leaves state unchanged on shape/value/budget or SIGMA refusal.

Note: Does not consume outgoing reservation overlays. Requires exclusive access to this column.

Here is the call graph for this function:

◆ canApplyContactMassIncrement()

bool openswmm::twoD::GroundPorewaterColumn::canApplyContactMassIncrement	(	int	r,
		std::size_t	j,
		double	increment ) const

noexcept

Preflight a signed contact receipt without spending reserved outgoing inventory.

Declaration arguments

species (in): Valid non-temperature species row.
layer (in): Physical layer index.
increment (in): Finite signed native inventory change; positive enters the layer.

Returns: True when mass, reservation and contact ledger shapes match, resulting mass remains at least the nonnegative reservation, and both mass and receipt sums stay finite. No state changes; this check alone does not preflight SIGMA overlap distribution.

Parameters

[in]	r	Valid non-temperature species row.
[in]	j	Physical layer index.
[in]	increment	Finite signed native inventory change; positive enters the layer.

Returns: True when mass, reservation and contact ledger shapes match, resulting mass remains at least the nonnegative reservation, and both mass and receipt sums stay finite. No state changes; this check alone does not preflight SIGMA overlap distribution.

Here is the caller graph for this function:

◆ canReserveOutgoing()

bool openswmm::twoD::GroundPorewaterColumn::canReserveOutgoing	(	int	r,
		std::size_t	j,
		double	amount ) const

noexcept

Preflight an outgoing reservation against unreserved canonical mass.

Declaration arguments

species (in): Non-temperature species index.
layer (in): Physical layer index.
amount (in): Finite nonnegative native inventory amount to reserve.

Returns: True when indices/shapes and available mass are valid, amount fits, and the reservation sum remains finite. False leaves all state unchanged; no reservation is created.

Parameters

[in]	r	Non-temperature species index.
[in]	j	Physical layer index.
[in]	amount	Finite nonnegative native inventory amount to reserve.

Returns: True when indices/shapes and available mass are valid, amount fits, and the reservation sum remains finite. False leaves all state unchanged; no reservation is created.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ contactAvailableMass()

double openswmm::twoD::GroundPorewaterColumn::contactAvailableMass	(	int	r,
		std::size_t	j ) const

noexcept

Read unreserved physical-layer inventory available to a finite contact.

Declaration arguments

species (in): Species index; temperature rows are unsupported.
layer (in): Physical layer index, derived from retention.size()/n_species.

Returns: mass-reserved_out in native inventory units. Returns NaN for invalid indices/shapes, temperature rows, nonfinite or negative inventory/reservation, or over-reservation.

Note: Read-only, allocation-free and noexcept; canonical mass still includes queued reservations.

Parameters

[in]	r	Species index; temperature rows are unsupported.
[in]	j	Physical layer index, derived from retention.size()/n_species.

Returns: mass-reserved_out in native inventory units. Returns NaN for invalid indices/shapes, temperature rows, nonfinite or negative inventory/reservation, or over-reservation.

Note: Read-only, allocation-free and noexcept; canonical mass still includes queued reservations.

Here is the caller graph for this function:

◆ generateAge()

bool openswmm::twoD::GroundPorewaterColumn::generateAge	(	const PorousHeatColumn &	soil,
		double	dt )

noexcept

Add elapsed water age to every physical layer and its generation ledger.

Declaration arguments

unnamed soil column (in): Prepared physical column, with stable moisture and geometry in SI units.
seconds (in): Finite nonnegative interval s; ignored when age_row is absent.

Returns: True after adding dt*water volume (m3 s) to age inventory and generated_age, or true without mutation when no age row exists. False on invalid interval/shapes or finite overflow, with no updates. Prepared age_row must be within n_species and soil geometry consistent.

Parameters

[in]	soil	Prepared physical column, with stable moisture and geometry in SI units.
[in]	dt	Finite nonnegative interval s; ignored when age_row is absent.

Returns: True after adding dt*water volume (m3 s) to age inventory and generated_age, or true without mutation when no age row exists. False on invalid interval/shapes or finite overflow, with no updates. Prepared age_row must be within n_species and soil geometry consistent.

◆ initialize()

std::string openswmm::twoD::GroundPorewaterColumn::initialize	(	const PorousHeatColumn &	soil,
		const std::vector< double > &	saturated,
		const std::vector< double > &	sat_mass,
		const std::vector< double > &	unsat_mass,
		const std::vector< double > &	kd,
		int	age,
		int	temperature )

Seed canonical physical-layer species inventories from saturated/unsaturated totals.

Declaration arguments

unnamed soil column (in): Prepared thermal geometry, moisture and material; layer count is theta.size().
saturated_water (in): Finite nonnegative saturated water volume m3 per layer, no greater than physical layer water except the 1e-12*max(1,water) roundoff allowance.
saturated_mass (in): Nonempty species totals for the saturated zone in native inventory units.
unsaturated_mass (in): Same-size unsaturated species totals. Non-temperature rows must be finite and nonnegative and nonzero inventory requires positive finite physical zone capacity.
kd (in): Finite nonnegative distribution coefficient m3/kg per species. Age ignores retention; temperature rows are not represented in porewater mass and their totals are ignored.
age (in): Optional age row index, -1 when absent; otherwise within species count.
temperature (in): Optional distinct temperature row index, -1 when absent.

Returns: Empty on success after replacing this object; diagnostic on validation refusal with this unchanged. Initial masses are copied, contact/reservation/generated-age ledgers start zero.

Note: Species-major layout is row*layer_count+layer. Sorption capacity uses solid density and solid volume; zone totals are distributed in proportion to water plus retained capacity. The input soil arrays must have consistent extents. Allocation errors propagate before publication.

Parameters

[in]	soil	Prepared thermal geometry, moisture and material; layer count is theta.size().
[in]	saturated	Finite nonnegative saturated water volume m3 per layer, no greater than physical layer water except the 1e-12*max(1,water) roundoff allowance.
[in]	sat_mass	Nonempty species totals for the saturated zone in native inventory units.
[in]	unsat_mass	Same-size unsaturated species totals. Non-temperature rows must be finite and nonnegative and nonzero inventory requires positive finite physical zone capacity.
[in]	kd	Finite nonnegative distribution coefficient m3/kg per species. Age ignores retention; temperature rows are not represented in porewater mass and their totals are ignored.
[in]	age	Optional age row index, -1 when absent; otherwise within species count.
[in]	temperature	Optional distinct temperature row index, -1 when absent.

Returns: Empty on success after replacing this object; diagnostic on validation refusal with this unchanged. Initial masses are copied, contact/reservation/generated-age ledgers start zero.

Note: Species-major layout is row*layer_count+layer. Sorption capacity uses solid density and solid volume; zone totals are distributed in proportion to water plus retained capacity. The input soil arrays must have consistent extents. Allocation errors propagate before publication.

◆ publishSigma()

std::string openswmm::twoD::GroundPorewaterColumn::publishSigma	(	SubsurfaceTransportState &	tr,
		int	cell )

Publish pending SIGMA contact receipts and refresh the derived physical-layer views.

Declaration arguments

unnamed transport owner (in,out): Canonical transport owner with matching SIGMA species/layers and cell extent.
cell (in): Target cell index in that owner.

Returns: Empty when inactive or successfully published/refreshed; otherwise sigma.publish()'s diagnostic, without refreshing the derived views. The map handles pending receipt validation.

Note: This method borrows the owner only for the call; publication requires exclusive access to both objects and must occur at the phase where pending contact receipts become canonical.

Parameters

[in,out]	tr	Canonical transport owner with matching SIGMA species/layers and cell extent.
[in]	cell	Target cell index in that owner.

Returns: Empty when inactive or successfully published/refreshed; otherwise sigma.publish()'s diagnostic, without refreshing the derived views. The map handles pending receipt validation.

Note: This method borrows the owner only for the call; publication requires exclusive access to both objects and must occur at the phase where pending contact receipts become canonical.

Here is the call graph for this function:

◆ refreshSigmaView()

void openswmm::twoD::GroundPorewaterColumn::refreshSigmaView ( )

Rebuild physical-layer mass and reservation views from an active SIGMA overlap map.

Note: Does nothing without an active map. Otherwise zeros mass/reserved_out and gathers every species/overlap into its physical layer. Prepared n_species, inventory sizes and overlap indices must be consistent; no validation or rollback occurs. Contact/initial/age ledgers are retained. Canonical SIGMA inventories and pending receipts are unchanged; no allocation occurs.

Here is the caller graph for this function:

◆ reserveOutgoing()

bool openswmm::twoD::GroundPorewaterColumn::reserveOutgoing	(	int	r,
		std::size_t	j,
		double	amount )

noexcept

Reserve accepted outgoing inventory without subtracting its canonical mass.

Declaration arguments

species (in): Non-temperature species index.
layer (in): Physical layer index.
amount (in): Finite nonnegative amount in native inventory units.

Returns: True after increasing reserved_out; false with no mutation when canReserveOutgoing() refuses. The existing gather, not this overlay, eventually removes canonical outgoing mass.

Parameters

[in]	r	Non-temperature species index.
[in]	j	Physical layer index.
[in]	amount	Finite nonnegative amount in native inventory units.

Returns: True after increasing reserved_out; false with no mutation when canReserveOutgoing() refuses. The existing gather, not this overlay, eventually removes canonical outgoing mass.

Here is the call graph for this function:

◆ settleOutgoingReservation()

bool openswmm::twoD::GroundPorewaterColumn::settleOutgoingReservation	(	int	r,
		std::size_t	j,
		double	amount )

noexcept

Release a queued outgoing reservation after its owning gather has consumed the packet.

Declaration arguments

species (in): Species index in [0,n_species).
layer (in): Physical layer index for a consistently prepared inventory layout.
amount (in): Finite nonnegative native amount, no greater than the existing reservation.

Returns: True after subtracting only reserved_out, setting exact complete settlement to zero; false on invalid index/shape/value or insufficient reservation, with no mutation.

Note: Does not subtract mass or update contact receipts; callers perform the matching inventory gather separately. Prepared retention/mass extents must describe the same physical-layer count.

Parameters

[in]	r	Species index in [0,n_species).
[in]	j	Physical layer index for a consistently prepared inventory layout.
[in]	amount	Finite nonnegative native amount, no greater than the existing reservation.

Returns: True after subtracting only reserved_out, setting exact complete settlement to zero; false on invalid index/shape/value or insufficient reservation, with no mutation.

Note: Does not subtract mass or update contact receipts; callers perform the matching inventory gather separately. Prepared retention/mass extents must describe the same physical-layer count.

◆ zoneMass()

std::pair< double, double > openswmm::twoD::GroundPorewaterColumn::zoneMass	(	const PorousHeatColumn &	soil,
		const std::vector< double > &	saturated,
		int	r ) const

noexcept

Derive one species' saturated/unsaturated split from physical-layer mass.

Declaration arguments

unnamed soil column (in): Stable prepared geometry/moisture; all depth and layer arrays must be valid.
saturated_water (in): Saturated water volume m3 per layer, with soil.theta.size() entries.
species (in): Species row in [0,n_species); temperature/invalid rows return zeros immediately.

Returns: Pair (saturated,unsaturated) in native species inventory units. Shares use water plus retention and are clipped to [0,1], so the pair sums to canonical mass for the species.

Note: noexcept does not validate array extents; mass/retention must each have n_species*layers entries. No allocation, mutation or receipt consumption occurs.

Parameters

[in]	soil	Stable prepared geometry/moisture; all depth and layer arrays must be valid.
[in]	saturated	Saturated water volume m3 per layer, with soil.theta.size() entries.
[in]	r	Species row in [0,n_species); temperature/invalid rows return zeros immediately.

Returns: Pair (saturated,unsaturated) in native species inventory units. Shares use water plus retention and are clipped to [0,1], so the pair sums to canonical mass for the species.

Note: noexcept does not validate array extents; mass/retention must each have n_species*layers entries. No allocation, mutation or receipt consumption occurs.

Here is the caller graph for this function:

◆ zoneMasses()

std::pair< std::vector< double >, std::vector< double > > openswmm::twoD::GroundPorewaterColumn::zoneMasses	(	const PorousHeatColumn &	soil,
		const std::vector< double > &	saturated ) const

Derive saturated and unsaturated totals without creating another inventory.

Declaration arguments

unnamed soil column (in): Stable prepared physical layer geometry/moisture consistent with this column.
saturated_water (in): Saturated water volume m3 per physical layer.

Returns: Owned pair of species vectors (saturated,unsaturated), length n_species. The temperature row contributes zero; mass is apportioned using water and retained capacity.

Exceptions

std::invalid_argument On saturated, mass or retention shape mismatch.

Note: Remaining soil geometry is assumed valid. Allocation failures propagate; no state changes.

Parameters

[in]	soil	Stable prepared physical layer geometry/moisture consistent with this column.
[in]	saturated	Saturated water volume m3 per physical layer.

Returns: Owned pair of species vectors (saturated,unsaturated), length n_species. The temperature row contributes zero; mass is apportioned using water and retained capacity.

Exceptions

std::invalid_argument On saturated, mass or retention shape mismatch.

Note: Remaining soil geometry is assumed valid. Allocation failures propagate; no state changes.

Here is the call graph for this function:

Member Data Documentation

◆ age_row

int openswmm::twoD::GroundPorewaterColumn::age_row = -1

◆ contact_mass

std::vector<double> openswmm::twoD::GroundPorewaterColumn::contact_mass

◆ generated_age

std::vector<double> openswmm::twoD::GroundPorewaterColumn::generated_age

◆ initial_mass

std::vector<double> openswmm::twoD::GroundPorewaterColumn::initial_mass

◆ mass

std::vector<double> openswmm::twoD::GroundPorewaterColumn::mass

◆ n_species

int openswmm::twoD::GroundPorewaterColumn::n_species = 0

◆ reserved_out

std::vector<double> openswmm::twoD::GroundPorewaterColumn::reserved_out

◆ retention

std::vector<double> openswmm::twoD::GroundPorewaterColumn::retention

◆ sigma

SigmaPorewaterMap openswmm::twoD::GroundPorewaterColumn::sigma

◆ temp_row

int openswmm::twoD::GroundPorewaterColumn::temp_row = -1

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

/home/runner/work/openswmm.engine/openswmm.engine/src/engine/2d/heat/GroundPorewater.hpp
/home/runner/work/openswmm.engine/openswmm.engine/src/engine/2d/heat/GroundPorewater.cpp

Public Member Functions

Public Attributes

Member Function Documentation

◆ active()

◆ applyContactMassIncrement()

◆ canApplyContactMassIncrement()

◆ canReserveOutgoing()

◆ contactAvailableMass()

◆ generateAge()

◆ initialize()

◆ publishSigma()

◆ refreshSigmaView()

◆ reserveOutgoing()

◆ settleOutgoingReservation()

◆ zoneMass()

◆ zoneMasses()

Member Data Documentation

◆ age_row

◆ contact_mass

◆ generated_age

◆ initial_mass

◆ mass

◆ n_species

◆ reserved_out

◆ retention

◆ sigma

◆ temp_row