#include <ChannelGround.hpp>

Collaboration diagram for openswmm::twoD::ChannelGroundState:

Public Member Functions
void	clear ()
	Release this contact mapping, borrowed bindings and diagnostic storage.

bool	active () const noexcept
	Test whether any prepared channel/ground contact exists.

bool	ownsCell (int i) const noexcept
	Test the resolved thermal contact ownership mask for one cell.

bool	ownsLink (int i) const noexcept
	Test the resolved thermal contact ownership mask for one link.

const std::vector< int > &	cells () const noexcept
	Borrow the prepared unique owned cells in increasing mesh-index order.

const std::vector< ChannelGroundContact > &	contacts () const noexcept
	Borrow the prepared contact segments sorted by link, begin fraction and cell.

std::size_t	contactCount (int link) const noexcept
	Read the number of mapped contact pieces for a routed link.

double	bedTemperature (int link, double begin=0, double end=1) const noexcept
	Read the capacity-weighted temperature of physical soil beneath a channel reach.

std::string	initialize (SimulationContext &, const MeshData &, GroundHeatState &, SubsurfaceTransportState &, SurfaceStateData &, double coordinate_to_si)
	Resolve channel geometry onto shared porous thermal columns and bind borrowed owners.

std::string	advance (const SolverOptions2D &, const std::vector< SurfaceThermalSample > &, double seconds, std::vector< double > &surface_mass)
	Advance the shared finite channel/soil solve and publish surface temperature-volume.

const std::vector< double > &	channelAtmosphere () const noexcept
	Borrow cumulative signed atmospheric energy added to routed channel water.

const std::vector< double > &	channelToGround () const noexcept
	Borrow cumulative signed channel-to-ground contact energy.

const std::vector< double > &	channelSpeciesToGround () const noexcept
	Borrow cumulative signed species exchange into physical porewater.

const std::vector< double > &	channelThermalIncrement () const noexcept
	Borrow cumulative net finite thermal energy change of routed water.

std::string	modelIdentity () const
	Serialize the prepared ownership, contact geometry and transport row identity.

void	checkpoint (openswmm::detail::CompletedSourceArchive &)
	Read/write mutable contact receipts through the completed-source archive.

Member Function Documentation

◆ active()

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

inlinenoexcept

Test whether any prepared channel/ground contact exists.

Returns: True when contacts_ is nonempty. Does not validate the borrowed owners, current channel wetness or enabled transport rows; no allocation or state change occurs.

Here is the caller graph for this function:

◆ advance()

std::string openswmm::twoD::ChannelGroundState::advance	(	const SolverOptions2D &	options,
		const std::vector< SurfaceThermalSample > &	samples,
		double	dt,
		std::vector< double > &	surface_mass )

Advance the shared finite channel/soil solve and publish surface temperature-volume.

Solve channels, shared ground columns and optional surface water over one source interval.

seconds: Finite positive duration s, called dt in the definition.

surface_mass: Replaced on successful active solve with mesh-cell degC*m3 values; retained on inactive return or prepublication refusal.

Returns: Empty on success/inactive state, otherwise detailed failure text. Mixed sample layout, borrowed owner lifetime, callback publication and partial-update rules are documented on the definition. This operation allocates and requires exclusive owner access.

Parameters

[in]	options	Resolved SI solver/thermal controls for column assembly.
[in]	samples	Mixed pre-sink surface temperature-volume (degC*m3), water volume m3 and already evaporated volume m3 per mesh cell. Exactly mesh.n_cells() entries are required when surface heat uses ground columns; otherwise samples are unused. Borrowed only during the call.
[in]	dt	Finite positive interval s, named seconds in the declaration.
[out]	surface_mass	Replaced on success by one degC*m3 value per mesh cell, zero for cells outside this contact solve. Unchanged on inactive return or validation failure before final publish.

Returns: Empty string for success/inactive state; diagnostic for binding, geometry, footprint, thermal/species solve, callback refusal or caught exception.

Note: Builds finite energy stores and conductive/hyporheic contacts, excluding promised porewater exports. Atmospheric channel flux is linearized around current temperature. Shared non-temperature rows are matched by exact names and exchanged in a separate conservative finite-store solve. External channel thermal increments publish first; a species refusal attempts their inverse rollback and reports rollback refusal. Then physical ground/porewater state, cumulative J/native receipts, derived views, footprint and output are committed. Callbacks must honor their own refusal contract; exceptions or failed rollback can leave partial external updates. No blanket atomicity is promised. Requires exclusive stable access to every borrowed owner and callbacks; allocates temporary stores.

Here is the call graph for this function:

◆ bedTemperature()

double openswmm::twoD::ChannelGroundState::bedTemperature	(	int	link,
		double	begin = 0,
		double	end = 1 ) const

noexcept

Read the capacity-weighted temperature of physical soil beneath a channel reach.

Parameters

[in]	link	Zero-based owned routed-link index.
[in]	begin	Finite normalized start fraction along the complete link, in [0,1).
[in]	end	Finite normalized end fraction, begin < end <= 1.

Returns: Capacity-weighted temperature degC of existing soil energy beneath the requested bed reach, including dry channels. Quiet NaN for invalid/unowned reach or no positive active capacity.

Note: Requires stable initialized context, mesh, ground and material bindings. Uses overlap of the full bed thickness with physical layers, excluding reserved capacity through activeCapacity(). No channel/soil energy, receipt or clock is changed; noexcept dependencies must not throw.

Here is the call graph for this function:

◆ cells()

const std::vector< int > & openswmm::twoD::ChannelGroundState::cells ( ) const

inlinenoexcept

Borrow the prepared unique owned cells in increasing mesh-index order.

Returns: Solver-owned const vector; valid during stable object access. clear(), initialize() or replacement invalidates element views. Contact lengths/elevations use SI geometry and normalized along-link fractions. No copy, reservation, mutation or ownership transfer occurs.

Here is the caller graph for this function:

◆ channelAtmosphere()

const std::vector< double > & openswmm::twoD::ChannelGroundState::channelAtmosphere ( ) const

inlinenoexcept

Borrow cumulative signed atmospheric energy added to routed channel water.

Returns: Solver-owned const vector in J per link, initialized to zero on successful binding. Values change on successful advances/checkpoint restore. clear()/initialize() invalidates views; requires stable read access. No copy, reset or receipt consumption occurs.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ channelSpeciesToGround()

const std::vector< double > & openswmm::twoD::ChannelGroundState::channelSpeciesToGround ( ) const

inlinenoexcept

Borrow cumulative signed species exchange into physical porewater.

Returns: Solver-owned const vector in native inventory in species-major [row*n_links+link] order, initialized to zero on successful binding. Values change on successful advances/checkpoint restore. clear()/initialize() invalidates views; requires stable read access. No copy, reset or receipt consumption occurs.

◆ channelThermalIncrement()

const std::vector< double > & openswmm::twoD::ChannelGroundState::channelThermalIncrement ( ) const

inlinenoexcept

Borrow cumulative net finite thermal energy change of routed water.

Returns: Solver-owned const vector in J per link, initialized to zero on successful binding. Values change on successful advances/checkpoint restore. clear()/initialize() invalidates views; requires stable read access. No copy, reset or receipt consumption occurs.

◆ channelToGround()

const std::vector< double > & openswmm::twoD::ChannelGroundState::channelToGround ( ) const

inlinenoexcept

Borrow cumulative signed channel-to-ground contact energy.

Returns: Solver-owned const vector in J per link, positive into ground, initialized to zero on successful binding. Values change on successful advances/checkpoint restore. clear()/initialize() invalidates views; requires stable read access. No copy, reset or receipt consumption occurs.

◆ checkpoint()

void openswmm::twoD::ChannelGroundState::checkpoint ( openswmm::detail::CompletedSourceArchive & )

Read/write mutable contact receipts through the completed-source archive.

Archive mutable channel thermal and native-species cumulative receipts.

Note: The archive parameter is caller-owned and borrowed during the call. Restored vector sizes must match the initialized link/species identity and all entries must be finite. Restore can throw after vector mutation; caller stages the owning checkpoint transaction.

Argument a (in,out): Completed-source archive: writes four vectors or restores them into this object.
Exceptions

std::runtime_error Restored vector shapes differ from prepared link/species identity or any value is nonfinite; archive truncation/format failures also propagate.

Note
Requires initialized stable owners/masks and matching separately checked model identity. On read, vectors are mutated before semantic checks, so caller uses a staged object for atomic restore. Does not archive external channel/ground energy or change borrowed owner bindings.

◆ clear()

void openswmm::twoD::ChannelGroundState::clear ( )

inline

Release this contact mapping, borrowed bindings and diagnostic storage.

Note: Resets the object to its default state, invalidating all element views. Does not clear external mesh-contact flags, ground-cell surface_owned flags or mutate the borrowed owners. Call serially after consumers finish; initialize() also clears the context mesh-contact mask.

Here is the caller graph for this function:

◆ contactCount()

std::size_t openswmm::twoD::ChannelGroundState::contactCount ( int link ) const

inlinenoexcept

Read the number of mapped contact pieces for a routed link.

Parameters

[in] link Zero-based link; invalid/unowned returns zero.

Returns: Difference of the link's prepared contact range endpoints, including multiple cells and layers. Requires matching prepared ranges; no geometry rebuild or wetness test occurs.

Here is the call graph for this function:

◆ contacts()

const std::vector< ChannelGroundContact > & openswmm::twoD::ChannelGroundState::contacts ( ) const

inlinenoexcept

Borrow the prepared contact segments sorted by link, begin fraction and cell.

Returns: Solver-owned const vector; valid during stable object access. clear(), initialize() or replacement invalidates element views. Contact lengths/elevations use SI geometry and normalized along-link fractions. No copy, reservation, mutation or ownership transfer occurs.

Here is the caller graph for this function:

◆ initialize()

std::string openswmm::twoD::ChannelGroundState::initialize	(	SimulationContext &	ctx,
		const MeshData &	mesh,
		GroundHeatState &	soil,
		SubsurfaceTransportState &	transport,
		SurfaceStateData &	surface,
		double	coordinate_scale )

Resolve channel geometry onto shared porous thermal columns and bind borrowed owners.

Resolve shared finite channel/soil contacts and borrow their canonical owners.

coordinate_to_si: Finite positive XY-to-m conversion; passed as coordinate_scale in the definition. Context, mesh, ground, transport and surface arguments are borrowed as described in the definition and must remain stable/alive through all subsequent advances.

Returns: Empty string for success/no selected contacts, otherwise a configuration diagnostic.

Note: Resets this mapping and the context mesh-contact mask first. Successful initialization marks participating ground cells surface-owned; errors do not restore prior mapping/flags.

Parameters

[in,out]	ctx	Prepared 1D context, spatial geometry, heat overrides and accessors. Clears heat_state.mesh_contact_link first; publishes the new link mask on success.
[in]	mesh	SI mesh geometry and cell topology, alive and stable for subsequent advances.
[in,out]	soil	Active porous-equilibrium ground heat owner. Selected cells gain surface_owned on successful binding, joining the shared finite thermal solve.
[in,out]	transport	Prepared matching groundwater species layout and physical porewater view.
[in,out]	surface	Prepared surface state and heat owner used by later advances.
[in]	coordinate_scale	Finite positive multiplier converting context XY coordinates to m. Header calls this coordinate_to_si; 1D hydraulic elevations are separately converted from feet.

Returns: Empty string for success or no applicable contacts; diagnostic for unsupported MSX, invalid/open-channel ownership, missing coordinates, incomplete mesh coverage or invalid profiles.

Note: Clears this object's old state before validation. Builds a local next mapping, splits bed segments at physical layers, then binds borrowed pointers and owned masks/receipts. External owners must outlive this object and retain topology/layout. Allocation can throw; failure can leave the old object cleared, while previously external surface_owned flags are not automatically undone. Caller serializes initialization with all thermal, channel and groundwater activity.

Here is the call graph for this function:

◆ modelIdentity()

std::string openswmm::twoD::ChannelGroundState::modelIdentity ( ) const

Serialize the prepared ownership, contact geometry and transport row identity.

Returns: Owned binary archive bytes for masks, ordered cells/ranges/contact fields and row names. Excludes mutable thermal/species receipts and external owner state; not a portable text ID/hash.

Note: Allocates copies/serialized bytes and can throw. Requires stable prepared mapping and live transport binding when present; no state or clock mutation occurs.

Here is the call graph for this function:

◆ ownsCell()

bool openswmm::twoD::ChannelGroundState::ownsCell ( int i ) const

inlinenoexcept

Test the resolved thermal contact ownership mask for one cell.

Parameters

[in] i Zero-based cell index; negative/out-of-range returns false.

Returns: Stored nonzero ownership flag. Does not rebuild geometry, infer current wetness or validate external-owner lifetime. Read-only and allocation-free.

◆ ownsLink()

bool openswmm::twoD::ChannelGroundState::ownsLink ( int i ) const

inlinenoexcept

Test the resolved thermal contact ownership mask for one link.

Parameters

[in] i Zero-based link index; negative/out-of-range returns false.

Returns: Stored nonzero ownership flag. Does not rebuild geometry, infer current wetness or validate external-owner lifetime. Read-only and allocation-free.

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

Public Member Functions

Member Function Documentation

◆ active()

◆ advance()

◆ bedTemperature()

◆ cells()

◆ channelAtmosphere()

◆ channelSpeciesToGround()

◆ channelThermalIncrement()

◆ channelToGround()

◆ checkpoint()

◆ clear()

◆ contactCount()

◆ contacts()

◆ initialize()

◆ modelIdentity()

◆ ownsCell()

◆ ownsLink()