Public C API implementation for snow models and meteorology. More...

#include "openswmm_api_common.hpp"
#include "../../../include/openswmm/engine/openswmm_snow.h"
#include "../../../include/openswmm/engine/openswmm_snow2d.h"
#include "../input/Tokenizer.hpp"
#include "PathResolver.hpp"
#include "UnitConversion.hpp"
#include <iomanip>
#include <sstream>
#include <cmath>
#include <limits>

Include dependency graph for openswmm_snow_impl.cpp:

Functions
SWMM_ENGINE_API int	swmm_snow_get_model (SWMM_Engine engine, int *model)
	Read the global snow-process model.

SWMM_ENGINE_API int	swmm_snow_set_model (SWMM_Engine engine, int model)
	Select the global snow-process model.

SWMM_ENGINE_API int	swmm_snow_get_step (SWMM_Engine engine, double *seconds)
	Read the snow-process cadence in seconds.

SWMM_ENGINE_API int	swmm_snow_set_step (SWMM_Engine engine, double seconds)
	Configure the snow-process cadence in seconds.

SWMM_ENGINE_API int	swmm_ueb_option_get (SWMM_Engine engine, const char key, char out, int size)
	Read a recognized UEB option in its input-section text format.

SWMM_ENGINE_API int	swmm_ueb_option_set (SWMM_Engine engine, const char key, const char value)
	Parse and assign one UEB option from a textual value.

SWMM_ENGINE_API int	swmm_ueb_get_monthly_ranges (SWMM_Engine engine, double *values)
	Read twelve authored UEB monthly daily-temperature-range overrides.

SWMM_ENGINE_API int	swmm_ueb_set_monthly_ranges (SWMM_Engine engine, const double *values)
	Replace twelve UEB monthly daily-temperature-range overrides.

SWMM_ENGINE_API int	swmm_snowpack_get_ueb (SWMM_Engine engine, int pack, SWMM_UebSnowpack *value)
	Read a named pack's UEB/model overrides.

SWMM_ENGINE_API int	swmm_snowpack_set_ueb (SWMM_Engine engine, int pack, const SWMM_UebSnowpack *value)
	Replace a named pack's UEB/model overrides.

SWMM_ENGINE_API int	swmm_snowpack_apply (SWMM_Engine engine, const SWMM_SnowpackEdit edits, int count, char diagnostic, int capacity)
	Validate and upsert a batch of named snowpacks as one atomic edit.

SWMM_ENGINE_API int	swmm_subcatch_get_snow_process_state (SWMM_Engine engine, int sc, int surface, SWMM_SnowState *value)
	Snapshot one subcatchment snow surface's accepted process state.

SWMM_ENGINE_API int	swmm_snow_get_ueb_ledger (SWMM_Engine engine, SWMM_SnowLedger *value)
	Aggregate the active UEB subcatchment water and energy inventory.

SWMM_ENGINE_API int	swmm_climate_get_radiation (SWMM_Engine engine, SWMM_RadiationConfig *value)
	Read the shared radiation site and source selectors.

SWMM_ENGINE_API int	swmm_climate_set_radiation (SWMM_Engine engine, const SWMM_RadiationConfig *value)
	Replace the shared radiation site and source selectors.

SWMM_ENGINE_API int	swmm_climate_get_radiation_source (SWMM_Engine engine, int channel, char *value, int capacity)
	Read one radiation source name or meteorology path.

SWMM_ENGINE_API int	swmm_climate_set_radiation_source (SWMM_Engine engine, int channel, const char *value)
	Bind one radiation source name or meteorology path.

SWMM_ENGINE_API int	swmm_snow_apply_configuration (SWMM_Engine engine, const char temperature_rows, const char ueb_rows, char *diagnostic, int capacity)
	Atomically replace global snow/radiation section configuration.

SWMM_ENGINE_API int	swmm_climate_preview_meteorology (SWMM_Engine engine, const char path, SWMM_ClimateMetSummary result, char *diagnostic, int capacity)
	Read and validate hourly meteorology without changing the model binding.

SWMM_ENGINE_API int	swmm_climate_get_cloud (SWMM_Engine engine, SWMM_ClimateCloudConfig config, char series, int capacity)
	Snapshot the shared heat/climatology cloud configuration and series name.

SWMM_ENGINE_API int	swmm_snow_apply_configuration_with_cloud (SWMM_Engine engine, const char temperature_rows, const char ueb_rows, const SWMM_ClimateCloudConfig cloud, const char cloud_series, char *diagnostic, int capacity)
	Atomically replace global snow/radiation section configuration, optionally including clouds.

SWMM_ENGINE_API int	swmm_snow2d_get_options (SWMM_Engine engine, int mode, double step)
	Read mesh snow enable mode and authored cadence.

SWMM_ENGINE_API int	swmm_snow2d_defaults_count (SWMM_Engine engine)
	Count authored mesh-snow default/tag rows.

SWMM_ENGINE_API int	swmm_snow2d_cells_count (SWMM_Engine engine)
	Count authored mesh-snow explicit cell rows.

SWMM_ENGINE_API int	swmm_snow2d_get_configuration (SWMM_Engine engine, int section, char buffer, int capacity, int required)
	Serialize one mesh-snow section body and report its required capacity.

SWMM_ENGINE_API int	swmm_snow2d_apply_configuration (SWMM_Engine engine, const char options, const char defaults, const char cells, char diagnostic, int capacity)
	Validate and atomically replace all mesh-snow authored section bodies.

SWMM_ENGINE_API int	swmm_snow2d_get_row (SWMM_Engine engine, int section, int index, int cell, char tag, int tag_capacity, char pack, int pack_capacity, SWMM_MeshSnowOverrides values)
	Read an authored mesh-snow assignment without resolving inherited overrides.

SWMM_ENGINE_API int	swmm_snow2d_get_states (SWMM_Engine engine, int first, int count, SWMM_SnowState *output)
	Snapshot a contiguous range of accepted mesh-snow states.

SWMM_ENGINE_API int	swmm_snow2d_get_ledgers (SWMM_Engine engine, int first, int count, SWMM_MeshSnowLedger *output)
	Snapshot a contiguous range of accepted mesh-snow ledgers.

SWMM_ENGINE_API int	swmm_snow2d_get_geometry_energy (SWMM_Engine engine, int first, int count, double *output)
	Read accumulated UEB geometry-remapping energy for a cell range.

Detailed Description

Public C API implementation for snow models and meteorology.

Author: Caleb Buahin caleb.nosp@m..bua.nosp@m.hin@g.nosp@m.mail.nosp@m..com

Copyright: Copyright (c) 2026 Caleb Buahin. All rights reserved.

License: Apache-2.0

Function Documentation

◆ swmm_climate_get_cloud()

SWMM_ENGINE_API int swmm_climate_get_cloud	(	SWMM_Engine	engine,
		SWMM_ClimateCloudConfig *	config,
		char *	series,
		int	capacity )

Snapshot the shared heat/climatology cloud configuration and series name.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[out]	config	Non-null configuration: mode 0 default, 1 constant or 2 series, fraction dimensionless and attenuation coefficients in their authored convention.
[out]	series	Non-null writable name buffer; empty when no valid series binding exists.
[in]	capacity	Positive byte capacity including the terminator; a short buffer returns SWMM_ERR_BUFSIZE and writes nothing.

Returns: SWMM_OK on success, SWMM_ERR_BADHANDLE for an invalid handle, SWMM_ERR_BUFSIZE for a short buffer, or SWMM_ERR_BADPARAM for invalid arguments. Output storage is caller-owned.

Note: The config structure is assigned only after the series text fits.

◆ swmm_climate_get_radiation()

SWMM_ENGINE_API int swmm_climate_get_radiation	(	SWMM_Engine	engine,
		SWMM_RadiationConfig *	value )

Read the shared radiation site and source selectors.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[out]	value	Non-null configuration. Site latitude/longitude are degrees, timezone hours and elevation m. Modes are 0 computed, 1 time series, 2 met file; authored flags control legacy-alias preservation.

Returns: SWMM_OK on success, SWMM_ERR_BADHANDLE for an invalid handle, or SWMM_ERR_BADPARAM for invalid arguments. Output storage is caller-owned.

Note: If no explicit site exists, resolves a fallback from shared heat/climate location settings.

Here is the call graph for this function:

◆ swmm_climate_get_radiation_source()

SWMM_ENGINE_API int swmm_climate_get_radiation_source	(	SWMM_Engine	engine,
		int	channel,
		char *	value,
		int	capacity )

Read one radiation source name or meteorology path.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	channel	0 shortwave time series, 1 longwave time series, 2 met-file path.
[out]	value	Non-null writable string buffer.
[in]	capacity	Positive byte capacity including the terminator; insufficient capacity returns SWMM_ERR_BUFSIZE and writes nothing.

Returns: SWMM_OK on success, SWMM_ERR_BADHANDLE for an invalid handle, SWMM_ERR_BUFSIZE for a short buffer, or SWMM_ERR_BADPARAM for invalid arguments (including an unknown channel). Output storage is caller-owned.

Note: Binds text only; change the source mode separately with swmm_climate_set_radiation(). The returned text is copied and output storage is not retained.

◆ swmm_climate_preview_meteorology()

SWMM_ENGINE_API int swmm_climate_preview_meteorology	(	SWMM_Engine	engine,
		const char *	path,
		SWMM_ClimateMetSummary *	result,
		char *	diagnostic,
		int	capacity )

Read and validate hourly meteorology without changing the model binding.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	path	Non-null filename; relative paths resolve from the input file's parent directory.
[out]	result	Non-null summary with record count, half-open SWMM-date coverage, and min/max columns in degrees C, relative-humidity percent, m/s, and W/m2 radiation.
[out]	diagnostic	Non-null writable text buffer; empty on success.
[in]	capacity	Positive byte capacity; an error message may be safely truncated.

Returns: SWMM_OK on success, SWMM_ERR_BADHANDLE for an invalid handle, or SWMM_ERR_BADPARAM for invalid arguments. Output storage is caller-owned.

Note: Checks coverage of the configured simulation date interval when it has positive duration. Model configuration and runtime are unchanged.

Here is the call graph for this function:

◆ swmm_climate_set_radiation()

SWMM_ENGINE_API int swmm_climate_set_radiation	(	SWMM_Engine	engine,
		const SWMM_RadiationConfig *	value )

Replace the shared radiation site and source selectors.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	value	Non-null configuration. Site latitude/longitude are degrees, timezone hours and elevation m. Modes are 0 computed, 1 time series, 2 met file; authored flags control legacy-alias preservation.

Returns: SWMM_OK on success, SWMM_ERR_BADHANDLE for an invalid handle, or SWMM_ERR_BADPARAM for invalid arguments. Output storage is caller-owned.

Note: Requires an editable BUILDING or OPENED model; later states return SWMM_ERR_LIFECYCLE. Input data is copied and no input storage is retained.

Here is the call graph for this function:

◆ swmm_climate_set_radiation_source()

SWMM_ENGINE_API int swmm_climate_set_radiation_source	(	SWMM_Engine	engine,
		int	channel,
		const char *	value )

Bind one radiation source name or meteorology path.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	channel	0 shortwave time series, 1 longwave time series, 2 met-file path.
[in]	value	Non-null null-terminated source text; newline and quote characters are rejected.

Returns: SWMM_OK on success, SWMM_ERR_BADHANDLE for an invalid handle, or SWMM_ERR_BADPARAM for invalid arguments. Output storage is caller-owned.

Note: Binds text only; change the source mode separately with swmm_climate_set_radiation(). Requires an editable BUILDING or OPENED model; later states return SWMM_ERR_LIFECYCLE. Input data is copied and no input storage is retained.

◆ swmm_snow2d_apply_configuration()

SWMM_ENGINE_API int swmm_snow2d_apply_configuration	(	SWMM_Engine	engine,
		const char *	options,
		const char *	defaults,
		const char *	cells,
		char *	diagnostic,
		int	capacity )

Validate and atomically replace all mesh-snow authored section bodies.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	options	Non-null options text without a section header.
[in]	defaults	Non-null whole-mesh/tag rows; precedence is cell > tag > whole mesh.
[in]	cells	Non-null explicit-cell rows; section text uses one-based cell keys. Empty section strings clear their section. NONE explicitly disables a scope.
[out]	diagnostic	Non-null writable diagnostic text; empty on success.
[in]	capacity	Positive byte capacity; failure text is safely truncated if necessary.

Returns: SWMM_OK on success, SWMM_ERR_BADHANDLE for an invalid handle, or SWMM_ERR_BADPARAM for invalid arguments. Output storage is caller-owned.

Note: Validates all parsers and named-pack references on a copy before publication. Requires an editable BUILDING or OPENED model; later states return SWMM_ERR_LIFECYCLE. Input data is copied and no input storage is retained.

Here is the call graph for this function:

◆ swmm_snow2d_cells_count()

SWMM_ENGINE_API int swmm_snow2d_cells_count ( SWMM_Engine engine )

Count authored mesh-snow explicit cell rows.

Parameters

[in] engine Borrowed live engine handle; not retained by this call.

Returns: Nonnegative row count; a null engine returns zero rather than an error status. Does not require an initialized surface runtime.

◆ swmm_snow2d_defaults_count()

SWMM_ENGINE_API int swmm_snow2d_defaults_count ( SWMM_Engine engine )

Count authored mesh-snow default/tag rows.

Parameters

[in] engine Borrowed live engine handle; not retained by this call.

Returns: Nonnegative row count; a null engine returns zero rather than an error status. Does not require an initialized surface runtime.

◆ swmm_snow2d_get_configuration()

SWMM_ENGINE_API int swmm_snow2d_get_configuration	(	SWMM_Engine	engine,
		int	section,
		char *	buffer,
		int	capacity,
		int *	required )

Serialize one mesh-snow section body and report its required capacity.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	section	0 options, 1 defaults/tags, 2 explicit cells.
[out]	buffer	Writable text buffer, or NULL with capacity == 0 for a size query.
[in]	capacity	Nonnegative byte capacity; must include the terminal NUL for copying.
[out]	required	Non-null slot for exact required bytes including NUL, set before a short-buffer failure when section serialization succeeds.

Returns: SWMM_OK on success, SWMM_ERR_BADHANDLE for an invalid handle, SWMM_ERR_BUFSIZE when a buffer is shorter than *required, or SWMM_ERR_BADPARAM for invalid arguments. Output storage is caller-owned.

Note: Returns newline-terminated body rows without section headers; no partial successful truncation is allowed.

Here is the call graph for this function:

◆ swmm_snow2d_get_geometry_energy()

SWMM_ENGINE_API int swmm_snow2d_get_geometry_energy	(	SWMM_Engine	engine,
		int	first,
		int	count,
		double *	energy_kj )

Read accumulated UEB geometry-remapping energy for a cell range.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	first	First zero-based mesh cell, at most cell count.
[in]	count	Nonnegative number of cells; the full range must fit the mesh.
[out]	energy_kj	Borrowed count-element destination in kJ; NULL allowed for zero count.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE, or SWMM_ERR_BADPARAM for an inactive/unbuilt 2D module, invalid range, or missing nonempty output buffer.

Note: Unassigned and non-UEB cells return NaN. No runtime state is advanced.

◆ swmm_snow2d_get_ledgers()

SWMM_ENGINE_API int swmm_snow2d_get_ledgers	(	SWMM_Engine	engine,
		int	first,
		int	count,
		SWMM_MeshSnowLedger *	output )

Snapshot a contiguous range of accepted mesh-snow ledgers.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	first	First zero-based cell index, at most the mesh cell count.
[in]	count	Nonnegative range length; first + count must fit the mesh.
[out]	output	Borrowed writable array of count SWMM_MeshSnowLedger entries; may be NULL for count == 0. Values use seconds, m3 water inventories and kJ energy inventories.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE, or SWMM_ERR_BADPARAM for invalid ranges, buffers, inactive surface routing, or builds without 2D support.

Note: Unassigned cells contain NaN quantities; UEB-only energy fields also remain NaN for non-UEB cells. No storage is retained.

◆ swmm_snow2d_get_options()

SWMM_ENGINE_API int swmm_snow2d_get_options	(	SWMM_Engine	engine,
		int *	mode,
		double *	step_s )

Read mesh snow enable mode and authored cadence.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[out]	mode	Non-null slot: 0 AUTO, 1 YES, 2 NO.
[out]	step_s	Non-null authored seconds; zero inherits the shared cadence.

Returns: SWMM_OK on success, SWMM_ERR_BADHANDLE for an invalid handle, or SWMM_ERR_BADPARAM for invalid arguments. Output storage is caller-owned.

Note: Returns configuration even before the mesh snow runtime is active.

◆ swmm_snow2d_get_row()

SWMM_ENGINE_API int swmm_snow2d_get_row	(	SWMM_Engine	engine,
		int	section,
		int	row,
		int *	cell,
		char *	tag,
		int	tag_capacity,
		char *	pack,
		int	pack_capacity,
		SWMM_MeshSnowOverrides *	values )

Read an authored mesh-snow assignment without resolving inherited overrides.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	section	1 for default/tag rows, 2 for explicit cell rows.
[in]	row	Zero-based position in that section's current map iteration order.
[out]	cell	Non-null slot; -1 for defaults or the zero-based cell for explicit rows.
[out]	tag	Non-null writable tag buffer; empty for explicit cell rows.
[in]	tag_capacity	Positive capacity including the terminator; short buffers fail.
[out]	pack	Non-null writable pack-name buffer; NONE explicitly disables snow.
[in]	pack_capacity	Positive pack-name capacity including the terminator.
[out]	values	Non-null override structure, with NaN for inherited fields. SI values use W/m2 and m; slope/aspect are degrees and fraction/drift dimensionless.

Returns: SWMM_OK on success, SWMM_ERR_BADHANDLE for an invalid handle, SWMM_ERR_BADINDEX for a row outside the section, SWMM_ERR_BUFSIZE when the tag or pack buffer is too short (nothing is written), or SWMM_ERR_BADPARAM for invalid arguments, including a section other than 1 or 2. Output storage is caller-owned. The setter/parser maintains paired slope/aspect inheritance.

◆ swmm_snow2d_get_states()

SWMM_ENGINE_API int swmm_snow2d_get_states	(	SWMM_Engine	engine,
		int	first,
		int	count,
		SWMM_SnowState *	output )

Snapshot a contiguous range of accepted mesh-snow states.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	first	First zero-based cell index, at most the mesh cell count.
[in]	count	Nonnegative range length; first + count must fit the mesh.
[out]	output	Borrowed writable array of count SWMM_SnowState entries; may be NULL for count == 0. Values use m SWE, m/s water rates, degrees C temperatures, kJ/m2 energy and dimensionless fractions/age.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE, or SWMM_ERR_BADPARAM for invalid ranges, buffers, inactive surface routing, or builds without 2D support.

Note: Unassigned cells contain NaN quantities and model SWMM_SNOW_DEFAULT; UEB-only energy fields also remain NaN for non-UEB cells. No storage is retained.

◆ swmm_snow_apply_configuration()

SWMM_ENGINE_API int swmm_snow_apply_configuration	(	SWMM_Engine	engine,
		const char *	temperature_rows,
		const char *	ueb_rows,
		char *	diagnostic,
		int	capacity )

Atomically replace global snow/radiation section configuration.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	temperature_rows	Non-null null-terminated TEMPERATURE section body without headers.
[in]	ueb_rows	Non-null null-terminated UEB section body without headers. Empty bodies restore defaults; existing named-pack assignments are preserved.
[out]	diagnostic	Non-null writable buffer, empty on success or a validation message on failure.
[in]	capacity	Positive byte capacity; diagnostics are truncated safely to fit.

Returns: SWMM_OK on success, SWMM_ERR_BADHANDLE for an invalid handle, or SWMM_ERR_BADPARAM for invalid arguments. Output storage is caller-owned.

Note: Parses and validates copies, meteorology coverage and named radiation series before publishing any configuration. Relative met paths resolve from the input-file directory. Requires an editable BUILDING or OPENED model; later states return SWMM_ERR_LIFECYCLE. Input data is copied and no input storage is retained.

Here is the call graph for this function:

◆ swmm_snow_apply_configuration_with_cloud()

SWMM_ENGINE_API int swmm_snow_apply_configuration_with_cloud	(	SWMM_Engine	engine,
		const char *	temperature_rows,
		const char *	ueb_rows,
		const SWMM_ClimateCloudConfig *	cloud,
		const char *	cloud_series,
		char *	diagnostic,
		int	capacity )

Atomically replace global snow/radiation section configuration, optionally including clouds.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	temperature_rows	Non-null null-terminated TEMPERATURE section body without headers.
[in]	ueb_rows	Non-null null-terminated UEB section body without headers. Empty bodies restore defaults; existing named-pack assignments are preserved.
[in]	cloud	Optional shared cloud configuration; NULL preserves it. Mode is 0 default, 1 constant or 2 time series; fraction is [0, 1] and attenuation coefficients/exponents are finite nonnegative values.
[in]	cloud_series	Required existing series name for cloud mode 2; ignored when cloud is NULL or a non-series mode is selected.
[out]	diagnostic	Non-null writable buffer, empty on success or a validation message on failure.
[in]	capacity	Positive byte capacity; diagnostics are truncated safely to fit.

Returns: SWMM_OK on success, SWMM_ERR_BADHANDLE for an invalid handle, or SWMM_ERR_BADPARAM for invalid arguments. Output storage is caller-owned.

Note: Parses and validates copies, meteorology coverage and named radiation series before publishing any configuration. Relative met paths resolve from the input-file directory. Requires an editable BUILDING or OPENED model; later states return SWMM_ERR_LIFECYCLE. Input data is copied and no input storage is retained.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ swmm_snow_get_model()

SWMM_ENGINE_API int swmm_snow_get_model	(	SWMM_Engine	engine,
		int *	model )

Read the global snow-process model.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[out]	model	Non-null result slot: SWMM_SNOW_DEGREE_DAY (0) or SWMM_SNOW_UEB (1).

Returns: SWMM_OK on success, SWMM_ERR_BADHANDLE for an invalid handle, or SWMM_ERR_BADPARAM for invalid arguments. Output storage is caller-owned.

Note: Reads authored configuration, not the model resolved for a particular pack.

◆ swmm_snow_get_step()

SWMM_ENGINE_API int swmm_snow_get_step	(	SWMM_Engine	engine,
		double *	seconds )

Read the snow-process cadence in seconds.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[out]	seconds	Non-null result slot for the authored cadence.

Returns: SWMM_OK on success, SWMM_ERR_BADHANDLE for an invalid handle, or SWMM_ERR_BADPARAM for invalid arguments. Output storage is caller-owned.

Note: Does not advance the snow solver; returns the stored global cadence.

◆ swmm_snow_get_ueb_ledger()

SWMM_ENGINE_API int swmm_snow_get_ueb_ledger	(	SWMM_Engine	engine,
		SWMM_SnowLedger *	value )

Aggregate the active UEB subcatchment water and energy inventory.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[out]	value	Non-null caller-owned ledger: elapsed_s in seconds, water categories in m3, and energy categories in kJ. Transfers are signed into the inventory; inactive duplicate native columns are excluded.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE, SWMM_ERR_BADPARAM for a null result, or SWMM_ERR_LIFECYCLE when UEB runtime is inactive.

Note: Recomputes stored inventory and residuals from accepted states without advancing them.

Here is the call graph for this function:

◆ swmm_snow_set_model()

SWMM_ENGINE_API int swmm_snow_set_model	(	SWMM_Engine	engine,
		int	model )

Select the global snow-process model.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	model	SWMM_SNOW_DEGREE_DAY (0) or SWMM_SNOW_UEB (1).

Returns: SWMM_OK on success, SWMM_ERR_BADHANDLE for an invalid handle, or SWMM_ERR_BADPARAM for invalid arguments. Output storage is caller-owned.

Note: Requires an editable BUILDING or OPENED model; later states return SWMM_ERR_LIFECYCLE. Input data is copied and no input storage is retained.

◆ swmm_snow_set_step()

SWMM_ENGINE_API int swmm_snow_set_step	(	SWMM_Engine	engine,
		double	seconds )

Configure the snow-process cadence in seconds.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	seconds	Finite cadence in [1, 21600] seconds, validated by the SNOW_STEP parser.

Returns: SWMM_OK on success, SWMM_ERR_BADHANDLE for an invalid handle, or SWMM_ERR_BADPARAM for invalid arguments. Output storage is caller-owned.

Note: Requires an editable BUILDING or OPENED model; later states return SWMM_ERR_LIFECYCLE. Input data is copied and no input storage is retained.

Here is the call graph for this function:

◆ swmm_snowpack_apply()

SWMM_ENGINE_API int swmm_snowpack_apply	(	SWMM_Engine	engine,
		const SWMM_SnowpackEdit *	edits,
		int	count,
		char *	diagnostic,
		int	capacity )

Validate and upsert a batch of named snowpacks as one atomic edit.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	edits	Borrowed count-element edit array; may be NULL only for count == 0. Pack names must be nonempty, unique case-insensitively within the batch, and contain no newline/quote characters. Surface/removal units follow the existing three snowpack rows; UEB fields use SI units from SWMM_UebSnowpack.
[in]	count	Nonnegative number of pack edits; omitted existing packs are preserved.
[out]	diagnostic	Non-null writable diagnostic buffer; empty on successful validation.
[in]	capacity	Positive diagnostic byte capacity; error text may be truncated with a terminator.

Returns: SWMM_OK on success, SWMM_ERR_BADHANDLE for an invalid handle, or SWMM_ERR_BADPARAM for invalid arguments. Output storage is caller-owned.

Note: Validates on copies before publishing names and pack arrays. No partial pack changes are saved on an argument/validation error. Requires an editable BUILDING or OPENED model; later states return SWMM_ERR_LIFECYCLE. Input data is copied and no input storage is retained.

Here is the call graph for this function:

◆ swmm_snowpack_get_ueb()

SWMM_ENGINE_API int swmm_snowpack_get_ueb	(	SWMM_Engine	engine,
		int	pack,
		SWMM_UebSnowpack *	value )

Read a named pack's UEB/model overrides.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	pack	Zero-based snowpack index, in [0, snowpack count).
[out]	value	Non-null destination structure. Forest/drift are dimensionless, ground heat W/m2, extinction depth m and initial energy kJ/m2. An absent row returns SWMM_SNOW_DEFAULT with standard site defaults.

Returns: SWMM_OK on success, SWMM_ERR_BADHANDLE for an invalid handle, or SWMM_ERR_BADPARAM for invalid arguments. Output storage is caller-owned.

Note: Returns authored/default values without resolving every inherited pack parameter.

◆ swmm_snowpack_set_ueb()

SWMM_ENGINE_API int swmm_snowpack_set_ueb	(	SWMM_Engine	engine,
		int	pack,
		const SWMM_UebSnowpack *	value )

Replace a named pack's UEB/model overrides.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	pack	Zero-based snowpack index, in [0, snowpack count).
[in]	value	Non-null configuration structure. Forest/drift are dimensionless, ground heat W/m2, extinction depth m and initial energy kJ/m2. SWMM_SNOW_DEFAULT removes the explicit override; other models and site values are validated by the snowpack parser.

Returns: SWMM_OK on success, SWMM_ERR_BADHANDLE for an invalid handle, or SWMM_ERR_BADPARAM for invalid arguments. Output storage is caller-owned.

Note: Requires an editable BUILDING or OPENED model; later states return SWMM_ERR_LIFECYCLE. Input data is copied and no input storage is retained.

Here is the call graph for this function:

◆ swmm_subcatch_get_snow_process_state()

SWMM_ENGINE_API int swmm_subcatch_get_snow_process_state	(	SWMM_Engine	engine,
		int	subcatch,
		int	surface,
		SWMM_SnowState *	value )

Snapshot one subcatchment snow surface's accepted process state.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	subcatch	Zero-based valid subcatchment index.
[in]	surface	0 plowable, 1 impervious, or 2 pervious.
[out]	value	Non-null caller-owned state. SWE/depth is subarea-averaged m, liquid/sublimation rates m/s, temperatures degrees C, covered-pack energy kJ/m2, water age seconds, and other fractions/age terms dimensionless.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE, SWMM_ERR_BADPARAM for invalid indices/output, SWMM_ERR_LIFECYCLE when runtime state is unavailable, or SWMM_ERR_BADINDEX when the subcatchment has no snowpack assignment.

Note: UEB-only fields are NaN for degree-day snow. Completed source-driver state is selected when it owns the subcatchment; no time integration occurs.

Here is the call graph for this function:

◆ swmm_ueb_get_monthly_ranges()

SWMM_ENGINE_API int swmm_ueb_get_monthly_ranges	(	SWMM_Engine	engine,
		double *	values )

Read twelve authored UEB monthly daily-temperature-range overrides.

Writes range in degC, with zero representing inheritance from current climate DTR; does not compute the effective climate-derived monthly value. No allocation or clock advancement.

Parameters

[in]	engine	Live engine handle; no lifecycle-state guard beyond non-NULL handle.
[out]	values	Caller-owned writable array of at least twelve doubles in January..December order.

Returns: SWMM_OK on success, SWMM_ERR_BADHANDLE for NULL engine, SWMM_ERR_BADPARAM for NULL values.

◆ swmm_ueb_option_get()

SWMM_ENGINE_API int swmm_ueb_option_get	(	SWMM_Engine	engine,
		const char *	key,
		char *	value,
		int	capacity )

Read a recognized UEB option in its input-section text format.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	key	Non-null null-terminated UEB key, accepted by uebOptionValue().
[out]	value	Non-null writable string buffer; receives the complete value and terminator.
[in]	capacity	Positive byte capacity including the terminator; insufficient capacity returns SWMM_ERR_BUFSIZE and writes nothing.

Returns: SWMM_OK on success, SWMM_ERR_BADHANDLE for an invalid handle, SWMM_ERR_BUFSIZE for a short buffer, or SWMM_ERR_BADPARAM for invalid arguments. Output storage is caller-owned.

Note: Unknown keys return SWMM_ERR_BADPARAM. Reads authored configuration.

Here is the call graph for this function:

◆ swmm_ueb_option_set()

SWMM_ENGINE_API int swmm_ueb_option_set	(	SWMM_Engine	engine,
		const char *	key,
		const char *	value )

Parse and assign one UEB option from a textual value.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	key	Non-null null-terminated UEB option key.
[in]	value	Non-null null-terminated value text, tokenized using input-file syntax.

Returns: SWMM_OK on success, SWMM_ERR_BADHANDLE for an invalid handle, or SWMM_ERR_BADPARAM for invalid arguments. Output storage is caller-owned.

Note: Requires an editable BUILDING or OPENED model; later states return SWMM_ERR_LIFECYCLE. Input data is copied and no input storage is retained.

Here is the call graph for this function:

◆ swmm_ueb_set_monthly_ranges()

SWMM_ENGINE_API int swmm_ueb_set_monthly_ranges	(	SWMM_Engine	engine,
		const double *	values )

Replace twelve UEB monthly daily-temperature-range overrides.

Validates all values before any assignment. Positive values set authored overrides, zero restores inheritance; no climate table mutation or simulation step.

Parameters

[in]	engine	Live editable engine handle in BUILDING or OPENED state.
[in]	values	Caller-owned readable array of twelve January..December values, each finite and within [0,100] degC.

Returns: SWMM_OK on success, BADHANDLE for NULL engine, LIFECYCLE outside editable states, BADPARAM for NULL/out-of-range array.

Functions

Detailed Description

Function Documentation

◆ swmm_climate_get_cloud()

◆ swmm_climate_get_radiation()

◆ swmm_climate_get_radiation_source()

◆ swmm_climate_preview_meteorology()

◆ swmm_climate_set_radiation()

◆ swmm_climate_set_radiation_source()

◆ swmm_snow2d_apply_configuration()

◆ swmm_snow2d_cells_count()

◆ swmm_snow2d_defaults_count()

◆ swmm_snow2d_get_configuration()

◆ swmm_snow2d_get_geometry_energy()

◆ swmm_snow2d_get_ledgers()

◆ swmm_snow2d_get_options()

◆ swmm_snow2d_get_row()

◆ swmm_snow2d_get_states()

◆ swmm_snow_apply_configuration()

◆ swmm_snow_apply_configuration_with_cloud()

◆ swmm_snow_get_model()

◆ swmm_snow_get_step()

◆ swmm_snow_get_ueb_ledger()

◆ swmm_snow_set_model()

◆ swmm_snow_set_step()

◆ swmm_snowpack_apply()

◆ swmm_snowpack_get_ueb()

◆ swmm_snowpack_set_ueb()

◆ swmm_subcatch_get_snow_process_state()

◆ swmm_ueb_get_monthly_ranges()

◆ swmm_ueb_option_get()

◆ swmm_ueb_option_set()

◆ swmm_ueb_set_monthly_ranges()