Owned mixed degree-day/UEB snow on remaining mesh weather footprints. Geometry area is horizontal m2; cell slope/aspect are degrees. Water accounts are m3, energy kJ, point energy kJ/m2 and rates m/s. One owner serializes all mutation, borrowing and checkpoint/contact calls. Trial advance protects this snow owner, while shared context weather cursors/diagnostics can still change. Physical ground heat, cover-geometry energy and prescribed energy stay distinct. More...

#include <MeshSnow.hpp>

Collaboration diagram for openswmm::surface::MeshSnow:

Public Member Functions
std::string	initialize (SimulationContext &context, const std::vector< MeshSnowGeometry > &geometry)
	Build a candidate mixed mesh snow owner from resolved authored assignment scopes.

std::string	advance (SimulationContext &context, double start, double end, const std::vector< double > &precipitation_ms, const std::vector< double > &snow_catch)
	Trial a contiguous interval, publishing internal snow state only after success.

std::string	setGroundContactMask (const std::vector< unsigned char > &mask)
	Install reciprocal ground-contact ownership for assigned UEB cells.

std::string	applyGroundContactEnergy (int cell, double soil_j)
	Apply an accepted reciprocal soil energy receipt to one covered-point owner.

std::string	saveCheckpoint () const
	Copy this owner and encode a native version-four accepted/predicted snapshot.

std::string	restoreCheckpoint (const std::string &bytes, bool seed=false)
	Validate a native mesh-snow archive into a private candidate then publish it.

bool	active () const
	Test whether any nonzero assigned snow weather footprint is owned.

bool	hasUeb () const
	Scan active cells for at least one UEB model owner.

bool	owns (int cell) const
	Test resolved snowpack ownership for one indexed mesh cell.

double	completedEnd () const
	Read the accepted snow-source frontier.

double	lastSeconds () const
	Read the latest ordinary accepted advance duration.

SnowKind	kind (int cell) const
	Read stored model kind for one allocated cell row.

const std::array< double, 10 > &	depletionCurve () const
	Borrow owned snow metadata/state without copying it.

const std::vector< double > &	liquidRates () const
	Borrow owned snow metadata/state without copying it.

const std::vector< double > &	exposedFractions () const
	Borrow owned snow metadata/state without copying it.

void	useAcceptedExposure ()
	Replace ET exposure for active cells by one minus accepted endpoint cover. Does not advance snow or alter output cover/water/predictions. Used during split source operators where the previously stored interval-average exposure is unsuitable; inactive/unowned rows remain unchanged. Serialize with source/thermal evaluation.

void	reanchorCompletedEnd (double end)
	Adopt only an ulp-sized driver endpoint change without advancing physics.

const std::string &	configurationIdentity () const
	Borrow owned snow metadata/state without copying it.

const std::vector< MeshSnowGeometry > &	geometry () const
	Borrow owned snow metadata/state without copying it.

const std::vector< SnowOutputs > &	outputs () const
	Borrow owned snow metadata/state without copying it.

const std::vector< MeshSnowLedger > &	ledgers () const
	Borrow owned snow metadata/state without copying it.

bool	groundContactEnabled (int cell) const
	Test the stored per-cell reciprocal contact bit.

double	groundContactFraction (int cell) const
	Read accepted endpoint cover for the next reciprocal thermal interval.

double	groundContactSurfaceTemperature (int cell) const
	Read the latest stored cell snow surface temperature.

const std::vector< unsigned char > &	groundContactMask () const
	Borrow owned snow metadata/state without copying it.

const std::vector< ueb::HeldState > &	columns () const
	Borrow owned snow metadata/state without copying it.

Friends
class	openswmm::twoD::CommonSourceStage

Detailed Description

Owned mixed degree-day/UEB snow on remaining mesh weather footprints. Geometry area is horizontal m2; cell slope/aspect are degrees. Water accounts are m3, energy kJ, point energy kJ/m2 and rates m/s. One owner serializes all mutation, borrowing and checkpoint/contact calls. Trial advance protects this snow owner, while shared context weather cursors/diagnostics can still change. Physical ground heat, cover-geometry energy and prescribed energy stay distinct.

Member Function Documentation

◆ active()

bool openswmm::surface::MeshSnow::active ( ) const

inline

Test whether any nonzero assigned snow weather footprint is owned.

Returns: True exactly when active_cells_ is nonempty; not a test for nonempty pack water, pending predictions or whether every mesh cell is assigned.

Here is the caller graph for this function:

◆ advance()

std::string openswmm::surface::MeshSnow::advance	(	SimulationContext &	context,
		double	start,
		double	end,
		const std::vector< double > &	precipitation_ms,
		const std::vector< double > &	snow_catch )

Trial a contiguous interval, publishing internal snow state only after success.

Parameters

[in,out]	context	Matching initialized weather/configuration/forcing; shared lookup cursors and climate_state.radiation may change even if snow trial fails. Does not update global simulation time or book external mesh water/thermal stores.
	start	Finite elapsed seconds exactly equal completedEnd().
	end	Finite elapsed endpoint strictly after start, within weather/simulation coverage.
	precipitation_ms	One finite nonnegative held raw precipitation m/s per mesh cell; active entries checked. Snow catch/UEB drift can change effective volume.
	snow_catch	Same-sized finite nonnegative catch factors; active entries checked.

Returns: Empty on accepted internal replacement, otherwise diagnostic retaining this owner. Inactive returns immediately without validating inputs. A span<=1e-9seconds only reanchors completedEnd, retaining prior outputs/rates/exposure/lastSeconds. Ordinary work copies mutable runtime while borrowing stable initialized configuration, splits held windows at snow/hour/transient boundaries, then checks per-cell water balance. Copy/solver exceptions can propagate; context or caller side effects are outside rollback. External source bookkeeping follows only after accepted return. Serialize changes to forcing/configuration and contact.

◆ applyGroundContactEnergy()

std::string openswmm::surface::MeshSnow::applyGroundContactEnergy	(	int	cell,
		double	soil_j )

Apply an accepted reciprocal soil energy receipt to one covered-point owner.

Parameters

cell	Valid assigned UEB cell with enabled ground-contact mask; checked here.
soil_j	Finite signed joules into soil; snow receives -soil_j. Zero is a no-op after owner validation. Uses horizontal area times accepted cover (one if snow-free) to convert to point kJ/m2; no water/cover change.

Returns: Empty on accepted energy/temperature/history/ledger publication, otherwise diagnostic retaining state. Checks finite storage, new bulk/surface temperatures, contact/net/stored totals and the implemented initial+net-stored residual. That receipt check does not include geometry_energy, so callers must account for this stricter condition when cover remapping has occurred. Updates last thermal sample, outputs and ground-contact/net/stored kJ; closes a pending prediction on success. Does not itself debit soil energy; caller pairs both owners transactionally. Point-history copy allocations can throw before publication.

Here is the call graph for this function:

◆ columns()

const std::vector< ueb::HeldState > & openswmm::surface::MeshSnow::columns ( ) const

inline

Borrow owned snow metadata/state without copying it.

Returns: UEB accepted/begin/private-predicted states and consumed-window clocks; unowned/DD rows are not active UEB columns. Reference valid until destruction/replacement; initialize/advance/restore/move can invalidate elements or buffers and contact calls mutate relevant contents. Serialize reads with mutation and copy any snapshot needed across publication. Never free.

◆ completedEnd()

double openswmm::surface::MeshSnow::completedEnd ( ) const

inline

Read the accepted snow-source frontier.

Returns: Elapsed seconds, initially zero. Advance/reanchor/restore can change it; predicted held end states are not exposed as accepted time.

◆ configurationIdentity()

const std::string & openswmm::surface::MeshSnow::configurationIdentity ( ) const

inline

Borrow owned snow metadata/state without copying it.

Returns: Native binary configuration/geometry/forcing identity, not display text or a portable cryptographic hash. Reference valid until destruction/replacement; initialize/advance/restore/move can invalidate elements or buffers and contact calls mutate relevant contents. Serialize reads with mutation and copy any snapshot needed across publication. Never free.

◆ depletionCurve()

const std::array< double, 10 > & openswmm::surface::MeshSnow::depletionCurve ( ) const

inline

Borrow owned snow metadata/state without copying it.

Returns: Copied UEB pervious-area ten-point depletion curve; DD uses its own native state. Reference valid until destruction/replacement; initialize/advance/restore/move can invalidate elements or buffers and contact calls mutate relevant contents. Serialize reads with mutation and copy any snapshot needed across publication. Never free.

◆ exposedFractions()

const std::vector< double > & openswmm::surface::MeshSnow::exposedFractions ( ) const

inline

Borrow owned snow metadata/state without copying it.

Returns: Per-cell interval-average snow-free fraction for ET; useAcceptedExposure can replace it with endpoint exposure. Reference valid until destruction/replacement; initialize/advance/restore/move can invalidate elements or buffers and contact calls mutate relevant contents. Serialize reads with mutation and copy any snapshot needed across publication. Never free.

◆ geometry()

const std::vector< MeshSnowGeometry > & openswmm::surface::MeshSnow::geometry ( ) const

inline

Borrow owned snow metadata/state without copying it.

Returns: Resolved tag/horizontal m2/slope-and-aspect-degree geometry after authored overrides. Reference valid until destruction/replacement; initialize/advance/restore/move can invalidate elements or buffers and contact calls mutate relevant contents. Serialize reads with mutation and copy any snapshot needed across publication. Never free.

Here is the caller graph for this function:

◆ groundContactEnabled()

bool openswmm::surface::MeshSnow::groundContactEnabled ( int cell ) const

inline

Test the stored per-cell reciprocal contact bit.

Parameters

cell	Zero-based row; invalid returns false.

Returns: Nonzero stored mask byte. Does not independently recheck UEB/pack validity; setGroundContactMask owns that qualification.

Here is the caller graph for this function:

◆ groundContactFraction()

double openswmm::surface::MeshSnow::groundContactFraction ( int cell ) const

inline

Read accepted endpoint cover for the next reciprocal thermal interval.

Parameters

cell	Cell index; disabled/invalid contact returns zero before output lookup.

Returns: Endpoint cover when contact enabled, not interval-average ET exposure. Does not predict future coverage or impose a separate snow-water threshold.

Here is the call graph for this function:

◆ groundContactMask()

const std::vector< unsigned char > & openswmm::surface::MeshSnow::groundContactMask ( ) const

inline

Borrow owned snow metadata/state without copying it.

Returns: Per-cell reciprocal-contact ownership bits, not predicted snow cover. Reference valid until destruction/replacement; initialize/advance/restore/move can invalidate elements or buffers and contact calls mutate relevant contents. Serialize reads with mutation and copy any snapshot needed across publication. Never free.

◆ groundContactSurfaceTemperature()

double openswmm::surface::MeshSnow::groundContactSurfaceTemperature ( int cell ) const

inline

Read the latest stored cell snow surface temperature.

Parameters

cell	Zero-based allocated output index, checked by vector::at().

Returns: Celsius, potentially NaN for DD/uninitialized outputs. Does not check contact enabled, model, ownership or current accepted clock.

Exceptions

std::out_of_range Invalid index.

◆ hasUeb()

bool openswmm::surface::MeshSnow::hasUeb ( ) const

inline

Scan active cells for at least one UEB model owner.

Returns: True for any active UEB assignment even if its water inventory is zero; false for inactive/DD-only models. Does not resolve current thermal readiness.

◆ initialize()

std::string openswmm::surface::MeshSnow::initialize	(	SimulationContext &	context,
		const std::vector< MeshSnowGeometry > &	geometry )

Build a candidate mixed mesh snow owner from resolved authored assignment scopes.

Parameters

context	Compatible initialized global/mesh snow, named pack/pervious rows, weather identity and valid project units; read here without advancing climate time.
geometry	One indexed horizontal weather footprint m2 per mesh cell, with tag and slope/aspect degrees. Count/products must fit int. Assigned nonzero-area cells require finite positive area, slope[0,90) and aspect[0,360]; skipped/unassigned cells are not fully geometry-qualified. Tag/default/cell rows can override slope/aspect.

Returns: Empty on replacement or diagnostic retaining the old owner. Ignore-snow, mode NO or no assignments installs an empty inactive owner; YES requires an active assigned footprint. Invalid explicit cell indices/pack names are refused. Copies parameters/site/geometry/identity, inherits positive mesh step or shared SNOW_STEP, uses named PERVIOUS initial values without subcatchment plowing/state. UEB initial SWE includes authored free water (uncapped here), adds its latent energy and uses project pervious depletion curve; DD caps free water and retains native default zero-SI/full-cover depletion until melt-out. DD thermal outputs and initial UEB albedo are NaN. Ground contact defaults off, clocks zero, rates zero and exposure matches initial cover. Does not fully validate all physical/weather parameters; initialization/copy/archive exceptions propagate before owner replacement.

Here is the call graph for this function:

◆ kind()

SnowKind openswmm::surface::MeshSnow::kind ( int cell ) const

inline

Read stored model kind for one allocated cell row.

Parameters

cell	Zero-based row, checked through vector::at().

Returns: Stored enum; meaningful only for owned cells (unassigned rows are defaulted).

Exceptions

std::out_of_range Invalid row. No pack/water/contact validation.

◆ lastSeconds()

double openswmm::surface::MeshSnow::lastSeconds ( ) const

inline

Read the latest ordinary accepted advance duration.

Returns: Seconds, initially/seed zero. A sub-nanosecond reanchor or explicit clock reanchor retains it, so it need not equal the last completedEnd increment.

◆ ledgers()

const std::vector< MeshSnowLedger > & openswmm::surface::MeshSnow::ledgers ( ) const

inline

Borrow owned snow metadata/state without copying it.

Returns: Cumulative physical m3 and kJ accounts, including separate cover-remap and reciprocal/prescribed ground-energy diagnostics. Reference valid until destruction/replacement; initialize/advance/restore/move can invalidate elements or buffers and contact calls mutate relevant contents. Serialize reads with mutation and copy any snapshot needed across publication. Never free.

Here is the caller graph for this function:

◆ liquidRates()

const std::vector< double > & openswmm::surface::MeshSnow::liquidRates ( ) const

inline

Borrow owned snow metadata/state without copying it.

Returns: Per-cell accepted liquid (melt+throughfall) m/s over lastSeconds(), zero initially. Reference valid until destruction/replacement; initialize/advance/restore/move can invalidate elements or buffers and contact calls mutate relevant contents. Serialize reads with mutation and copy any snapshot needed across publication. Never free.

◆ outputs()

const std::vector< SnowOutputs > & openswmm::surface::MeshSnow::outputs ( ) const

inline

Borrow owned snow metadata/state without copying it.

Returns: Per-cell accepted output: integrated liquid depths m, SWE m, cover and available Celsius/kJ/m2 fields; DD thermal values can be NaN. Reference valid until destruction/replacement; initialize/advance/restore/move can invalidate elements or buffers and contact calls mutate relevant contents. Serialize reads with mutation and copy any snapshot needed across publication. Never free.

◆ owns()

bool openswmm::surface::MeshSnow::owns ( int cell ) const

inline

Test resolved snowpack ownership for one indexed mesh cell.

Parameters

cell	Zero-based index; invalid returns false.

Returns: True when pack_[cell]>=0. Does not require stored snow, UEB model or contact mask.

Here is the caller graph for this function:

◆ reanchorCompletedEnd()

void openswmm::surface::MeshSnow::reanchorCompletedEnd ( double end )

Adopt only an ulp-sized driver endpoint change without advancing physics.

Parameters

end	Finite nonnegative elapsed seconds within8epsilonmax(1,abs(end),abs(old)).

Exceptions

std::invalid_argument Larger/incompatible landing. On success changes only completed_, retaining lastSeconds, histories, held predictions, outputs and ledgers.

◆ restoreCheckpoint()

std::string openswmm::surface::MeshSnow::restoreCheckpoint	(	const std::string &	bytes,
		bool	seed = false )

Validate a native mesh-snow archive into a private candidate then publish it.

Parameters

bytes	Matching native version4/3/2 archive. Identity/model/geometry must match; old legacy identity is allowed only with all-one depletion curve. Version3/4 contact mask must match, and version2 cannot restore an enabled contact owner. Empty bytes clear owned inventory using the existing assignments and force seeding.
seed	True preserves restored water/thermal state but clears ledgers to new initial inventory, zeroes clocks/last flux/rates, closes future predictions and resets cached rain/catch. False restores exact clocks and pending held predictions.

Returns: Empty on success or caught standard-exception/compatibility/shape/clock/ finite inventory/thermal/closure diagnostic retaining the prior owner. Inactive accepts only empty bytes. Checks entire archive via finish(); no partial normal publication. Does not prepare weather, rebuild geometry, debit soil/source stores or independently qualify the containing engine/surface restart. Caller publishes all paired owners after complete surrounding validation.

Here is the call graph for this function:

◆ saveCheckpoint()

std::string openswmm::surface::MeshSnow::saveCheckpoint ( ) const

Copy this owner and encode a native version-four accepted/predicted snapshot.

Returns: Empty bytes when inactive, otherwise OpenSWMM mesh snow4 archive containing configuration identity, exact clocks/forcing, contact mask, held windows, DD history, outputs and water/physical/geometry/contact energy ledgers. Does not mutate owner, finish an external paired checkpoint or provide portable endian/schema interchange. Copy/archive exceptions propagate; caller serializes snapshot access.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ setGroundContactMask()

std::string openswmm::surface::MeshSnow::setGroundContactMask ( const std::vector< unsigned char > & mask )

Install reciprocal ground-contact ownership for assigned UEB cells.

Parameters

mask	One byte per mesh cell, each zero/one; one requires owns(cell) and UEB.

Returns: Empty after copy, otherwise shape/value/ownership refusal without change. Does not close held predictions, change energy/clocks or validate a ground solver; caller coordinates transitions at an accepted thermal boundary. Allocation may throw.

Here is the call graph for this function:

◆ useAcceptedExposure()

void openswmm::surface::MeshSnow::useAcceptedExposure ( )

Replace ET exposure for active cells by one minus accepted endpoint cover. Does not advance snow or alter output cover/water/predictions. Used during split source operators where the previously stored interval-average exposure is unsuitable; inactive/unowned rows remain unchanged. Serialize with source/thermal evaluation.

Friends And Related Symbol Documentation

◆ openswmm::twoD::CommonSourceStage

friend class openswmm::twoD::CommonSourceStage

friend

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

/home/runner/work/openswmm.engine/openswmm.engine/src/engine/hydrology/surface/MeshSnow.hpp
/home/runner/work/openswmm.engine/openswmm.engine/src/engine/hydrology/surface/MeshSnow.cpp

Public Member Functions

Friends

Detailed Description

Member Function Documentation

◆ active()

◆ advance()

◆ applyGroundContactEnergy()

◆ columns()

◆ completedEnd()

◆ configurationIdentity()

◆ depletionCurve()

◆ exposedFractions()

◆ geometry()

◆ groundContactEnabled()

◆ groundContactFraction()

◆ groundContactMask()

◆ groundContactSurfaceTemperature()

◆ hasUeb()

◆ initialize()

◆ kind()

◆ lastSeconds()

◆ ledgers()

◆ liquidRates()

◆ outputs()

◆ owns()

◆ reanchorCompletedEnd()

◆ restoreCheckpoint()

◆ saveCheckpoint()

◆ setGroundContactMask()

◆ useAcceptedExposure()

Friends And Related Symbol Documentation

◆ openswmm::twoD::CommonSourceStage