openswmm::surface::ueb Namespace Reference

Classes
struct	Fluxes
	Integrated accepted point exchanges and final thermal diagnostics. Water depths m and energy kJ/m2 cover the whole requested interval. Temperature Celsius and albedo are final accepted substep values, not interval averages. steps counts accepted leaves; retries counts successful binary splits. More...
struct	Forcing
	Held point meteorology over one requested interval. seconds is duration, precipitation integrated liquid-equivalent m, temperature Celsius, wind m/s, humidity [0,1], incoming radiation W/m2, cosine [0,1]. Catch and drift apply to snowfall; snow_fraction=-1 selects temperature partition. Other fields remain held while advance splits time and apportions precipitation. More...
struct	HeldState
struct	LumpedFluxes
struct	LumpedState
struct	NativeState
	Owned per-surface UEB predictions, accepted outputs and whole-model ledgers. Three surface columns per subcatchment; rain/snow caches are per subcatchment. Held water/energy use m and kJ/m2; global water/energy ledgers use m3 and kJ. Sample/completed clocks are elapsed seconds. last_seconds is the last call span; enabled column clocks can differ when source groups advance independently. Report arrays live in SnowSoA; one serialized owner coordinates both stores. More...
struct	Parameters
	Point UEB material, radiation and integration parameters. Temperatures are Celsius, lengths m, densities kg/m3, heat capacities kJ/(kg K), conductivities kJ/(m K h), drainage/conductance m/h, max_step seconds. Fractions, age responses and stability are dimensionless; low_frequency retains the reference hourly convention. validate() checks all fields before public advance. More...
struct	Site
	Per-column environmental settings. forest is canopy fraction, drift a snow multiplier, pressure Pa, ground_heat prescribed W/m2 into the snow system, extinction_depth m. Public advance checks forest [0,1], drift>=0, positive pressure/depth and finite signed ground heat. More...
struct	State
	One owned point snow/active-soil energy and thermal-memory inventory. energy kJ/m2 may be signed, water m SWE, age dimensionless optical age, refreezing depths m. The duration-weighted history spans at most 24 hours. No forcing/runtime context is shared between independent point states. More...
struct	ThermalSample
	One duration-weighted preceding thermal sample (seconds and Celsius). More...

Enumerations
enum class	TemperatureMethod {   ModifiedForceRestore ,   Equilibrium }

Functions
std::string	prepareHeld (HeldState &state, const Parameters &parameters, const Site &site, const Forcing &forcing, const std::array< double, 10 > &curve)
	Predict one full constant-forcing UEB window while retaining accepted inventory.
std::string	consumeHeld (HeldState &state, double seconds, const std::array< double, 10 > &curve, LumpedFluxes &output)
	Publish only the requested elapsed share of an already solved snow window.
void	closeHeld (HeldState &state) noexcept
	Discard the remaining prediction's active clock while keeping elapsed inventory.
std::string	validateDepletion (const std::array< double, 10 > &curve)
	Check a ten-point snow-cover depletion curve.
double	depletionCover (const std::array< double, 10 > &curve, double relative_water) noexcept
	Interpolate coverage from relative basin-average snow water.
std::string	initializeLumped (LumpedState &state, double water, double point_energy, double maximum, const std::array< double, 10 > &curve)
	Prepare a basin-average water inventory and covered-area point state.
std::string	advanceLumped (LumpedState &state, const Parameters &parameters, const Site &site, const Forcing &forcing, const std::array< double, 10 > &curve, LumpedFluxes &output)
	Trial one UEB point interval then reconcile basin cover and represented energy.
double	bulkTemperature (const State &state, const Parameters &parameters) noexcept
	Convert signed represented snow/active-soil energy to bulk temperature.
std::string	advance (State &state, const Parameters &parameters, const Site &site, const Forcing &forcing, Fluxes &output)
	Advance one isolated point pack with bounded reference solves and whole-call publication.
std::string	initializeSubcatchments (SimulationContext &context, snow::SnowSoA &snow)
	Initialize privately staged UEB columns from authored native snow assignments.
double	nextSnowBoundary (const SimulationContext &context, double elapsed, double proposed) noexcept
	Shorten a proposed span to the next native UEB held-forcing boundary.
std::string	advanceSubcatchments (SimulationContext &context, snow::SnowSoA &native, double date, double elapsed, double seconds, const double *rain, const double *snow)
	Trial accepted UEB snow and plowing over one source/runoff interval.

Enumeration Type Documentation

TemperatureMethod

enum class openswmm::surface::ueb::TemperatureMethod

strong

Enumerator
ModifiedForceRestore
Equilibrium

Function Documentation

advance()

std::string openswmm::surface::ueb::advance	(	State &	state,
		const Parameters &	parameters,
		const Site &	site,
		const Forcing &	forcing,
		Fluxes &	output )

Advance one isolated point pack with bounded reference solves and whole-call publication.

Parameters

[in,out]	state	Valid finite inventory with nonnegative water/age/refreezing depths and positive-duration thermal samples above absolute zero spanning at most 24 hours. Replaced only after the full requested interval is accepted.
	parameters	Valid material/integration configuration, checked on entry.
	site	Finite valid forest/drift/pressure/ground-heat/extinction settings.
	forcing	Positive finite duration seconds; nonnegative precipitation m, wind m/s and incoming W/m2; temperature in (-100,70] Celsius; humidity/cosine [0,1]; nonnegative catch; snow_fraction exactly -1 or [0,1]. Meteorology is held constant.
[out]	output	Replaced on success with integrated m/kJ-per-m2 fluxes, summed water/energy residuals and counts, plus endpoint temperatures/albedo. Retained on normal failure. Signed sublimation includes deposition.

Returns

Empty on success; parameter/state/site/forcing, 100000-substep limit, conservation/nonfinite/convergence or caught solver-exception diagnostic otherwise. Splits by max_step, apportions precipitation exactly, retries rejected steps by halving to depth 16 or 0.001 s, and publishes only a complete private candidate. Candidate copy before the guarded loop can throw; no caller state is then changed. Reference diagnostics reject a leaf. No global clocks, other packs or external water/energy ledgers are mutated. Serialize access to the same state/output.

Here is the call graph for this function:

Here is the caller graph for this function:

advanceLumped()

std::string openswmm::surface::ueb::advanceLumped	(	LumpedState &	state,
		const Parameters &	parameters,
		const Site &	site,
		const Forcing &	forcing,
		const std::array< double, 10 > &	curve,
		LumpedFluxes &	output )

Trial one UEB point interval then reconcile basin cover and represented energy.

Parameters

[in,out]	state	Consistent finite nonnegative water/maximum metres, cover [0,1], positive cover for nonempty water and point.water*cover agreeing with basin water. Owns covered-point thermal history. Publication replaces it only after normal success.
	parameters	Qualified point UEB physical/numerical parameters; advance validates them.
	site	Qualified point site forcing/pressure/forest configuration.
	forcing	Held interval point forcing in UEB units, positive seconds; passed unchanged to the point kernel. Precipitation partition follows that kernel.
	curve	Finite nondecreasing depletion fractions, checked each call.
[out]	output	Assigned on success: whole-element integrated water depths m, point diagnostics and kJ/m2 forcing/geometry-energy accounts; retained on refusal.

Returns

Empty on success, otherwise curve/state/point/conservation diagnostic. Fresh snowfall with positive point-water growth acts over full area; other changes act over prior cover, with uncovered precipitation as throughfall. Coverage remaps point water while preserving bulk temperature/liquid fraction where applicable; geometry_energy separately records that representation change, not numerical physical forcing. Full-cover path keeps point arithmetic. Checks basin water closure and finite geometry energy; caller handles exceptions and external state serialization. Does not update a source clock or settle external runoff water.

Here is the call graph for this function:

Here is the caller graph for this function:

advanceSubcatchments()

std::string openswmm::surface::ueb::advanceSubcatchments	(	SimulationContext &	context,
		snow::SnowSoA &	native,
		double	date,
		double	elapsed,
		double	seconds,
		const double *	rain,
		const double *	snow )

Trial accepted UEB snow and plowing over one source/runoff interval.

Parameters

[in,out]	context	Matching initialized weather/gage/snow configuration. On success replaces UEB runtime and books signed sublimation in runoff balance; weather/table cursors and radiation outputs may change even if trial fails.
[in,out]	native	Compatible native state/owner flags. Enabled external surfaces are advanced; success replaces staged histories/reports, including DD receivers of plowed UEB snow. Caller supplies consistent report and accepted water pools.
	date	Start of interval in native OLE days; must correspond to elapsed.
	elapsed	Start seconds since simulation origin, in the owning source schedule.
	seconds	Positive accepted span, no longer than snow/hour/gage/transient/ simulation boundary; caller qualifies finite time and coherent column clocks.
	rain	Borrowed per-subcatchment finite nonnegative, already partitioned and catch-corrected liquid ft/s; array has at least native.n_subcatch entries.
	snow	Same-layout solid precipitation ft/s. Native drift/catch must already be applied: this adapter forces site drift and snow catch to one.

Returns

Empty on accepted publication or inactive no-op, otherwise diagnostic retaining owned snow/report state. Copies owner/native arrays, invalidates held predictions on override/rate changes or incoming plowed water, resolves held forcing once per subcatchment, consumes only requested shares and then plows. Precipitation, physical/cover-remap energy and transferred/plowed inventories stay separate. Context weather side effects are outside rollback; exceptions propagate. Does not advance global simulation clocks or debit external soil/source owners.

Here is the call graph for this function:

Here is the caller graph for this function:

bulkTemperature()

double openswmm::surface::ueb::bulkTemperature ( const State & state, const Parameters & parameters )

noexcept

Convert signed represented snow/active-soil energy to bulk temperature.

Parameters

state	Finite energy kJ/m2 and water m; nonnegative water required.
parameters	Positive density/depth/heat-capacity fields guaranteeing positive combined snow/soil heat capacity; not validated here.

Returns

Celsius: cold energy/capacity, zero through the latent melt range, or excess positive energy/capacity after complete melting. No state mutation/clamping of invalid inputs; malformed capacity can produce nonfinite output.

Here is the caller graph for this function:

closeHeld()

void openswmm::surface::ueb::closeHeld ( HeldState & state )

noexcept

Discard the remaining prediction's active clock while keeping elapsed inventory.

Parameters

[in,out]

state

Sets duration=elapsed=0 only; accepted state is retained. Begin/end/full flux data remain stored but are no longer pending, and a later prepare replaces them. No water rollback, physical flux booking or allocation.

Here is the caller graph for this function:

consumeHeld()

std::string openswmm::surface::ueb::consumeHeld	(	HeldState &	state,
		double	seconds,
		const std::array< double, 10 > &	curve,
		LumpedFluxes &	output )

Publish only the requested elapsed share of an already solved snow window.

Parameters

[in,out]	state	Consistent prepared window and current accepted partial state; no concurrent forcing/model edits. Updates accepted inventory and elapsed only on normal success, retaining private full predicted end/flux.
	seconds	Finite positive consumption no greater than remaining duration except 1e-5-second calendar roundoff, which snaps exactly to the full endpoint.
	curve	Same qualified depletion curve used at preparation, checked again.
[out]	output	Assigned whole-element integrated depth/energy share on success; retained on normal refusal. point fluxes remain the full prepared solve, not a scaled new solve. Point steps/retries/diagnostics publish only on first consumption.

Returns

Empty on success, otherwise timing/curve/cover/conservation diagnostic. Intermediate basin water/energy and selected point history fields interpolate by window progress; coverage is recomputed and thermal history is truncated to 24 hours. Last consumption adopts exact predicted end. Geometry energy is separately derived from accepted-to-next representation; net physical energy/water scale by consumed share. Allocation exceptions before publication propagate. No new UEB solve, source-clock advancement or external receiver booking is performed here.

Here is the call graph for this function:

Here is the caller graph for this function:

depletionCover()

double openswmm::surface::ueb::depletionCover ( const std::array< double, 10 > & curve, double relative_water )

noexcept

Interpolate coverage from relative basin-average snow water.

Parameters

curve	Qualified finite monotone fraction ordinates from validateDepletion().
relative_water	Finite basin water divided by its maximum reference depth.

Returns

Zero for ratio <= 0, one for >= 1, otherwise linear interpolation including implicit endpoint 1. No curve/finite validation or output clamp. NaN input is not a supported query because the interior ratio converts to an integer index.

Here is the caller graph for this function:

initializeLumped()

std::string openswmm::surface::ueb::initializeLumped	(	LumpedState &	state,
		double	water,
		double	point_energy,
		double	maximum,
		const std::array< double, 10 > &	curve )

Prepare a basin-average water inventory and covered-area point state.

Parameters

[in,out]	state	Replaced only on normal success; prior state retained on refusal.
	water	Finite nonnegative whole-element water-equivalent depth metres.
	point_energy	Finite covered-point energy kJ/m2, assigned directly rather than divided by cover. Physical consistency follows the point model/caller.
	maximum	Finite nonnegative maximum/reference basin SWE metres. Nonempty water raises it to at least water; empty water forces reference zero.
	curve	Valid depletion ordinates; nonempty water must yield positive cover.

Returns

Empty on success, otherwise curve/inventory/zero-cover diagnostic. Creates a fresh default point, water=basin/cover and energy as supplied; other point history is reset. No Parameters/site/thermal equilibrium validation or time advancement.

Here is the call graph for this function:

Here is the caller graph for this function:

initializeSubcatchments()

std::string openswmm::surface::ueb::initializeSubcatchments	(	SimulationContext &	context,
		snow::SnowSoA &	snow )

Initialize privately staged UEB columns from authored native snow assignments.

Parameters

[in,out]	context	Initialized snowpacks/configuration, compatible subcatchment areas/pack indices and unit factors. Replaces only snowpacks.runtime on success.
[in,out]	snow	Initialized three-surface native geometry/history arrays with valid extents and assignments. Replaces external-owner flags and publishes UEB water/cover/cold reports on success; zero-duration publication retains flux fields.

Returns

Empty on success, or removal-fraction/lumped-initialization diagnostic before publication. Marks UEB assignments active even when surface area is zero. Validates removal fractions individually and their sum, initializes positive-area columns using authored free water and latent energy plus pack initial kJ/m2, and computes initial inventory over non-LID horizontal area. Does not check every context index/physical parameter or apply global ignore-snow gating. Allocation/ copy exceptions propagate; serialize access to runtime and native arrays.

Here is the call graph for this function:

Here is the caller graph for this function:

nextSnowBoundary()

double openswmm::surface::ueb::nextSnowBoundary ( const SimulationContext & context, double elapsed, double proposed )

noexcept

Shorten a proposed span to the next native UEB held-forcing boundary.

Parameters

context	Initialized snow runtime/configuration with finite positive step and valid start date; global ignore-snow or inactive runtime bypasses shortening.
elapsed	Current finite elapsed seconds in the source/runoff schedule.
proposed	Proposed finite nonnegative duration seconds.

Returns

Minimum of proposed, next configured snow grid boundary (1e-7 s landing bias), and next clock hour when hourly meteorology exists (1e-5 s bias). Does not limit to gage changes, transient override span or simulation end; caller does so. No state mutation, physical solve or argument validation.

Here is the caller graph for this function:

prepareHeld()

std::string openswmm::surface::ueb::prepareHeld	(	HeldState &	state,
		const Parameters &	parameters,
		const Site &	site,
		const Forcing &	forcing,
		const std::array< double, 10 > &	curve )

Predict one full constant-forcing UEB window while retaining accepted inventory.

Parameters

[in,out]	state	Consistent accepted lumped state with no pending window. Stores begin/end/full-window flux, duration and zero elapsed on success; accepted water/energy remains unchanged until consumed.
	parameters	Qualified UEB physical/numerical parameters.
	site	Qualified UEB site configuration.
	forcing	Held weather/precipitation over positive seconds in UEB point units; drivers must close a window at forcing or SNOW_STEP changes.
	curve	Qualified depletion fractions, checked by advanceLumped().

Returns

Empty after preparation, otherwise pending-window/lumped-solve diagnostic. Normal refusal retains accepted state and previous prediction. Copy/allocation exceptions during preparation can leave prediction bookkeeping partly replaced; caller owns private-state rollback. Serialize prepare/consume/close and snapshots.

Here is the call graph for this function:

Here is the caller graph for this function:

validateDepletion()

std::string openswmm::surface::ueb::validateDepletion

(

const std::array< double, 10 > &

curve

)

Check a ten-point snow-cover depletion curve.

Parameters

curve

Ordinates for relative water 0, 0.1, ..., 0.9; implicit value at1 is1.

Returns

Empty for finite nondecreasing values in [0,1], otherwise diagnostic. First ordinate need not be zero and last need not be one. Does not test whether a particular positive-water state receives positive cover or mutate any values.

Here is the caller graph for this function: