#include <GroundHeat.hpp>

Collaboration diagram for openswmm::twoD::GroundHeatState:

Public Member Functions
bool	active () const noexcept
	Test whether the owner has allocated any thermal cell slots.

void	clear ()
	Reset thermal cells, diagnostics, configuration and borrowed bindings to defaults.

double	activeCapacity (int cell, std::size_t layer) const noexcept
	Remove promised outgoing water capacity from one physical thermal layer.

double	activeTemperature (int cell, std::size_t layer) const noexcept
	Divide physical-layer energy by its unreserved heat capacity.

bool	snowContactEnabled (int cell) const noexcept
	Test reciprocal UEB snow/soil thermal contact availability.

double	snowContactFraction (int cell) const noexcept
	Read the active snow-contact footprint fraction.

bool	appendSnowContact (int cell, double area, std::vector< ThermalBoundary > &) const
	Append the top-layer boundary representing a reciprocal finite snow/soil contact.

std::string	applySnowContactEnergy (int cell, double soil_j)
	Publish reciprocal energy to the active snow owner after a soil contact solve.

std::string	initialize (SimulationContext &, const MeshData &, const SubsurfaceState &, const SubsurfaceTransportState &, const GwTransportData &, const std::vector< uint8_t > &coverage)
	Build physical aquifer thermal layers and seed conserved energy from resolved moisture.

std::string	initializeStandalone (SimulationContext &, const MeshData &, const GwTransportData &, const std::vector< unsigned char > &owned)
	Build fixed saturated physical soil columns for surface-owned transient storage.

void	prepare ()
	Sample top and deep thermal forcing at context.current_date.

void	prepareAt (double elapsed_seconds)
	Sample top/deep thermal forcing at a coupled elapsed horizon.

void	appendRk2Cuts (double start, double end, std::vector< double > &) const
	Append thermal forcing knots inside a coupled interval after validating series support.

void	refreshView (int cell, SubsurfaceTransportState &)
	Publish canonical physical heat/porewater inventories into the derived groundwater view.

double	zoneTemperature (int cell, bool saturated) const
	Read a water-volume-weighted physical-layer temperature for a hydraulic zone.

std::size_t	boundaries (int cell, double exposed_fraction, std::vector< ThermalBoundary > &) const
	Append configured top/deep thermal boundaries for one physical ground column.

std::string	conduct (int cell, double seconds, bool midpoint=false)
	Advance unowned physical-column conduction once after accepted water advection.

Public Attributes
SimulationContext *	context = nullptr

surface::MeshSnow *	snow_owner = nullptr

const GwTransportData *	config = nullptr

std::vector< GroundThermalCell >	cells

std::vector< std::vector< GroundLidThermalOwner > >	lid_owners

double	top_now = 0

double	deep_now = 0

double	density = 1000

double	water_capacity = 4184000

int	top_series = -1

int	deep_series = -1

Member Function Documentation

◆ active()

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

inlinenoexcept

Test whether the owner has allocated any thermal cell slots.

Returns: True when cells is nonempty, including a mesh-sized array containing no active columns. Does not inspect individual capacity, configuration or borrowed context validity. No mutation.

Here is the caller graph for this function:

◆ activeCapacity()

double openswmm::twoD::GroundHeatState::activeCapacity	(	int	i,
		std::size_t	j ) const

noexcept

Remove promised outgoing water capacity from one physical thermal layer.

cell: Valid prepared cell index.
layer: Valid physical layer index.
Returns
Remaining J/K after reserved outgoing water capacity, without positivity clamp or mutation.

Parameters

[in] i Valid prepared cell index (header: cell), unchecked.

[in] j Valid physical layer index (header: layer), unchecked against capacity.

Returns
column.capacity[j]-water_heat_capacity*reserved_out_water[j], J/K. A missing reservation entry contributes zero. No positivity/finiteness clamp occurs; producer must prevent over-reserving. Does not consume any receipt or mutate storage.

Here is the caller graph for this function:

◆ activeTemperature()

double openswmm::twoD::GroundHeatState::activeTemperature	(	int	i,
		std::size_t	j ) const

noexcept

Divide physical-layer energy by its unreserved heat capacity.

cell: Valid prepared cell index.
layer: Valid physical layer index with positive finite active capacity.
Returns
Layer energy/active capacity, degC; unchecked and read-only.

Parameters

[in] i Valid prepared cell index (header: cell).

[in] j Valid physical layer index (header: layer).

Returns
Active temperature degC. Requires positive finite activeCapacity(); division by zero, negative capacity or nonfinite energy is not guarded. Read-only and allocation-free.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ appendRk2Cuts()

void openswmm::twoD::GroundHeatState::appendRk2Cuts	(	double	start,
		double	end,
		std::vector< double > &	cuts ) const

Append thermal forcing knots inside a coupled interval after validating series support.

start: Finite elapsed interval start s.

end: Finite elapsed end s, >= start.

Note: Appends interior top/deep forcing times to the borrowed vector argument; retains existing entries and can throw after partial append. Caller sorts/deduplicates and stages its transaction. Temperature series must cover the full interval; flux series may have finite support.

Parameters

[in]	start	Finite elapsed interval start s.
[in]	end	Finite elapsed end s, at least start; required by the caller, not checked here.
[in,out]	cuts	Appends strictly interior knot times s from top and deep series. Existing entries are retained; output is neither sorted nor deduplicated. May allocate.

Exceptions

std::runtime_error Invalid series index/shape/time ordering/finiteness, elapsed conversion overflow or missing temperature reservoir coverage across the complete interval.

Note: Inactive returns. Does not mutate table cursors/calendar or sample cache. Earlier appended knots remain if a later validation fails; requires stable borrowed context/config and output access.

Here is the call graph for this function:

◆ appendSnowContact()

bool openswmm::twoD::GroundHeatState::appendSnowContact	(	int	i,
		double	area,
		std::vector< ThermalBoundary > &	bc ) const

Append the top-layer boundary representing a reciprocal finite snow/soil contact.

cell: Prepared snow/soil mesh cell.

area: Finite positive contact area m2.

Returns: True after appending one local top-layer boundary to the borrowed vector argument, false for disabled contact/invalid area. Invalid prepared resistance/temperature throws; no energy booked.

Parameters

[in]	i	Prepared mesh cell index (header: cell); disabled returns false.
[in]	area	Finite positive contact area m2; invalid returns false.
[in,out]	bc	Receives one top-store ThermalBoundary with conductance W/K and snow surface temperature degC. Existing records are preserved; local store index is zero.

Returns: True after appending, false for disabled contact or invalid area.

Exceptions

std::runtime_error Missing top-layer geometry or invalid resistance, temperature/conductance.

Note: Requires stable prepared config/column/snow owner; vector growth can throw. Does not apply reciprocal energy or verify the requested area against the snow footprint.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ applySnowContactEnergy()

std::string openswmm::twoD::GroundHeatState::applySnowContactEnergy	(	int	cell,
		double	soil_j )

Publish reciprocal energy to the active snow owner after a soil contact solve.

Parameters

[in]	cell	Matching prepared soil/snow cell.
[in]	soil_j	Signed energy J added to soil; the snow owner applies the matching reciprocal receipt. Caller supplies a finite accepted solve result and serializes owner mutation.

Returns: Empty on snow-owner acceptance, otherwise its diagnostic or a missing-ownership diagnostic. Does not itself update the soil column energy; caller pairs both sides and handles refusal.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ boundaries()

std::size_t openswmm::twoD::GroundHeatState::boundaries	(	int	i,
		double	exposed,
		std::vector< ThermalBoundary > &	bc ) const

Append configured top/deep thermal boundaries for one physical ground column.

cell: Valid prepared column index.

exposed_fraction: Top forcing area fraction in [0,1], unchecked.

Returns: Output vector size after top records and before appended deep records; preexisting entries are included. Supply an empty vector to interpret this as a count. Disabled/empty returns zero.

Note: Appends to the borrowed boundary vector using cached forcing; no energy mutation occurs.

Parameters

[in]	i	Valid prepared cell index (header: cell).
[in]	exposed	Fraction of column area exposed to top forcing, expected in [0,1] but unchecked.
[in,out]	bc	Appended local-store boundary records. Caller normally supplies an empty vector.

Returns: Vector size immediately after top-boundary append, before deep append; includes preexisting records if bc was nonempty. Zero for empty column or disabled conduction.

Note: Uses cached top_now/deep_now, half-layer resistance, configured deep depth and cell geothermal flux. Does not sample forcing, add snow contact or book energy. Geometry, conductivity and cached forcing validity are caller preconditions; vector growth can throw after partial append.

Here is the caller graph for this function:

◆ clear()

void openswmm::twoD::GroundHeatState::clear ( )

inline

Reset thermal cells, diagnostics, configuration and borrowed bindings to defaults.

Note: Releases owned vectors and invalidates element views. Does not mutate external context, mesh snow, hydraulic or transport owners. Caller serializes with all column/contact consumers.

Here is the caller graph for this function:

◆ conduct()

std::string openswmm::twoD::GroundHeatState::conduct	(	int	i,
		double	dt,
		bool	midpoint = false )

Advance unowned physical-column conduction once after accepted water advection.

cell: Valid prepared physical column.
seconds: Finite positive solve duration s, called dt in source.

midpoint: True selects the RK2 thermal contact solver.

Returns: Empty on success/skip, otherwise diagnostic. Allocates and may throw on boundary setup; snow refusal may leave cumulative receipts changed. Surface-owned columns are skipped to avoid advancing the same physical owner twice.

Parameters

[in]	i	Valid prepared column index (header: cell).
[in]	dt	Solve duration s (header: seconds), required finite positive by the thermal solver.
[in]	midpoint	True uses the RK2 thermal contact solver, false the ordinary finite solve.

Returns: Empty for success, empty column, disabled conduction or surface-owned column; diagnostic for unsupported surface-water ownership, solver failure or reciprocal snow refusal.

Note: Builds active-capacity stores, vertical contacts, top/deep and snow boundaries. On successful solve books signed boundary/absolute vertical J then replaces layer energy. Snow refusal can occur after cumulative receipts were changed, before energy replacement; no global rollback. Setup or allocation exceptions propagate. Requires exclusive stable column/config/snow access; does not refresh groundwater derived transport or advance the engine calendar.

Here is the call graph for this function:

◆ initialize()

std::string openswmm::twoD::GroundHeatState::initialize	(	SimulationContext &	ctx,
		const MeshData &	mesh,
		const SubsurfaceState &	water,
		const SubsurfaceTransportState &	tr,
		const GwTransportData &	cfg,
		const std::vector< uint8_t > &	coverage )

Build physical aquifer thermal layers and seed conserved energy from resolved moisture.

Parameters

[in,out]	ctx	Prepared engine context providing water properties, calendar, names and initial heat values; pointer is borrowed for subsequent forcing sampling.
[in]	mesh	SI mesh tags/geometry for scope matching.
[in]	water	Prepared hydraulic cell arrays and SIGMA profile, unchanged by this call.
[in]	tr	Prepared species layout and temperature row, used for activation/layer initial data.
[in]	cfg	Resolved SI groundwater thermal/material/initial conditions, borrowed as config; must remain alive and stable after this call.
[in]	coverage	Exactly water.n_cells ownership bytes; nonzero enables a valid positive-area, positive-depth column. Caller supplies consistent hydraulic/mesh/transport shapes and positive thermal_layers.

Returns: Empty string on success or disabled mode; diagnostic for invalid properties, coverage, series references, moisture projection or initial thermal layer target.

Note: Clears this owner before validation. Stages columns locally, preserves separate saturated and unsaturated seed energy, then installs bindings and calls prepare(). prepare()/allocation can throw after state installation; there is no rollback to the previous owner. Context/config outlive all subsequent uses, and initialization requires exclusive access.

Here is the call graph for this function:

◆ initializeStandalone()

std::string openswmm::twoD::GroundHeatState::initializeStandalone	(	SimulationContext &	ctx,
		const MeshData &	mesh,
		const GwTransportData &	cfg,
		const std::vector< unsigned char > &	owned )

Build fixed saturated physical soil columns for surface-owned transient storage.

Parameters

[in,out]	ctx	Prepared engine context supplying SI water/material and initial temperatures; borrowed after initialization for boundary sampling.
[in]	mesh	SI cell geometry and scoped material identity.
[in]	cfg	Resolved thermal controls, borrowed as config for the owner's lifetime.
[in]	owned	At least mesh.n_cells() bytes; nonzero selects a standalone surface-owned column. Bounds are unchecked. Positive thermal_layers and valid phase/geometry properties are required.

Returns: Empty on success, otherwise a missing-series or column initialization diagnostic.

Note: Clears old owner first; builds saturated profiles at bed_thickness+ground_depth, stages, installs, then samples prepare(). Allocation/conversion/forcing exceptions propagate and can leave old state cleared or new state installed. Does not modify mesh/hydraulic water. Caller serializes initialization and preserves borrowed owner lifetime.

Here is the call graph for this function:

◆ prepare()

void openswmm::twoD::GroundHeatState::prepare ( )

Sample top and deep thermal forcing at context.current_date.

Exceptions

std::runtime_error Missing temperature coverage or nonfinite sampled forcing.

Note: Inactive returns without work. Writes top_now/deep_now and may update shared time-series cursors; scalar parse exceptions propagate. Requires live context/config and serial cursor access. A later boundary failure can leave top_now updated; no energy or calendar advance occurs.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ prepareAt()

void openswmm::twoD::GroundHeatState::prepareAt ( double time )

Sample top/deep thermal forcing at a coupled elapsed horizon.

elapsed_seconds: Finite coupled elapsed time s from options.start_date; source calls this time. Updates cached top/deep forcing only, with cursor-free series interpolation.
Exceptions

std::runtime_error Invalid/uncovered temperature forcing; partially updated caches may remain. Requires live prepared context/config and exclusive access to forcing cache.

Parameters

[in] time Finite elapsed time s from the engine start calendar (header: elapsed_seconds).

Exceptions

std::runtime_error Uncovered/invalid temperature series or nonfinite forcing.

Note
Inactive returns. Writes top_now/deep_now; series lookup does not mutate shared table cursors or engine calendar. AIR still reads current context air forcing. Scalar parse exceptions propagate and a deep failure can leave top_now changed. Requires stable context/config.

Here is the call graph for this function:

◆ refreshView()

void openswmm::twoD::GroundHeatState::refreshView	(	int	i,
		SubsurfaceTransportState &	tr )

Publish canonical physical heat/porewater inventories into the derived groundwater view.

Rebuild groundwater transport views from canonical physical heat and porewater stores.

cell: Valid prepared cell. The transport-reference argument is a writable, matching species layout; saturated/unsaturated/layer temperature-volume is degC*m3.

Note: Inactive/no-temperature returns. Invalid porewater mapping throws and may leave partial derived updates; physical energy/mass is unchanged. Requires exclusive derived-view access.

Parameters

[in]	i	Valid prepared cell index (header: cell), unchecked.
[in,out]	tr	Matching prepared native species/temperature view. Publishes porewater SIGMA mass, saturated/unsaturated temperature-volume degC*m3 and per-SIGMA-layer temperature where mapped; nonlayered non-temperature rows are rebuilt from physical zone mass.

Exceptions

std::runtime_error Porewater publishSigma rejects incompatible mapping/state.

Note: Inactive owner or no temperature row returns. Requires matching prepared array extents, positive active capacities and stable physical inventories. Mutates derived tr views, never canonical physical energy/mass; failures can leave partial derived updates. Caller serializes with producers.

Here is the call graph for this function:

◆ snowContactEnabled()

bool openswmm::twoD::GroundHeatState::snowContactEnabled ( int cell ) const

noexcept

Test reciprocal UEB snow/soil thermal contact availability.

Parameters

[in] cell Cell index, called i in source; invalid returns false.

Returns: True for a nonempty soil column, live snow owner/config, enabled conduction and matching snow-owner contact. Does not infer snow cover from soil alone or book energy; dependencies must not throw under this noexcept query.

Here is the caller graph for this function:

◆ snowContactFraction()

double openswmm::twoD::GroundHeatState::snowContactFraction ( int cell ) const

noexcept

Read the active snow-contact footprint fraction.

Parameters

[in] cell Mesh cell index; invalid/disabled contact returns zero.

Returns: Snow-owner fraction clamped to [0,1] when enabled. No area, water or energy receipt is changed; borrowed snow/config owners must remain stable and noexcept dependencies must not throw.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ zoneTemperature()

double openswmm::twoD::GroundHeatState::zoneTemperature	(	int	i,
		bool	saturated ) const

Read a water-volume-weighted physical-layer temperature for a hydraulic zone.

cell: Valid prepared cell, called i in the definition.
saturated: True for saturated water, false for unsaturated water.
Returns
Physical-water-volume-weighted degC; empty zone falls back to its adjacent bottom/top layer, empty column to zero. Requires consistent positive active capacities; does not mutate state.

Parameters

[in] i Valid prepared cell index (header: cell); arrays are unchecked.

[in] saturated True uses saturated_water, false uses the remaining physical porewater.

Returns
Weighted active temperature degC; absent zone water falls back to bottom/top layer respectively, or zero for an empty energy vector. Requires matching saturated-water and positive active-capacity shapes; no clamp or finite-value check is performed. Read-only and allocation-free.

Here is the call graph for this function:

Member Data Documentation

◆ cells

std::vector<GroundThermalCell> openswmm::twoD::GroundHeatState::cells

◆ config

const GwTransportData* openswmm::twoD::GroundHeatState::config = nullptr

◆ context

SimulationContext* openswmm::twoD::GroundHeatState::context = nullptr

◆ deep_now

double openswmm::twoD::GroundHeatState::deep_now = 0

◆ deep_series

int openswmm::twoD::GroundHeatState::deep_series = -1

◆ density

double openswmm::twoD::GroundHeatState::density = 1000

◆ lid_owners

std::vector<std::vector<GroundLidThermalOwner> > openswmm::twoD::GroundHeatState::lid_owners

◆ snow_owner

surface::MeshSnow* openswmm::twoD::GroundHeatState::snow_owner = nullptr

◆ top_now

double openswmm::twoD::GroundHeatState::top_now = 0

◆ top_series

int openswmm::twoD::GroundHeatState::top_series = -1

◆ water_capacity

double openswmm::twoD::GroundHeatState::water_capacity = 4184000

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

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

Public Member Functions

Public Attributes

Member Function Documentation

◆ active()

◆ activeCapacity()

◆ activeTemperature()

◆ appendRk2Cuts()

◆ appendSnowContact()

◆ applySnowContactEnergy()

◆ boundaries()

◆ clear()

◆ conduct()

◆ initialize()

◆ initializeStandalone()

◆ prepare()

◆ prepareAt()

◆ refreshView()

◆ snowContactEnabled()

◆ snowContactFraction()

◆ zoneTemperature()

Member Data Documentation

◆ cells

◆ config

◆ context

◆ deep_now

◆ deep_series

◆ density

◆ lid_owners

◆ snow_owner

◆ top_now

◆ top_series

◆ water_capacity