Public C API for mesh snow pack assignments and SI-unit overrides. More...

#include "openswmm_snow.h"

Include dependency graph for openswmm_snow2d.h:

This graph shows which files directly or indirectly include this file:

Classes
struct	SWMM_MeshSnowOverrides

struct	SWMM_MeshSnowLedger

Typedefs
typedef struct SWMM_MeshSnowOverrides	SWMM_MeshSnowOverrides

typedef struct SWMM_MeshSnowLedger	SWMM_MeshSnowLedger

Functions
SWMM_ENGINE_API int	swmm_snow2d_get_options (SWMM_Engine engine, int mode, double step_s)
	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_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.

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 *energy_kj)
	Read accumulated UEB geometry-remapping energy for a cell range.

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.

Detailed Description

Public C API for mesh snow pack assignments and SI-unit overrides.

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

Typedef Documentation

◆ SWMM_MeshSnowLedger

typedef struct SWMM_MeshSnowLedger SWMM_MeshSnowLedger

◆ SWMM_MeshSnowOverrides

typedef struct SWMM_MeshSnowOverrides SWMM_MeshSnowOverrides

Function Documentation

◆ 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.

Classes

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ SWMM_MeshSnowLedger

◆ SWMM_MeshSnowOverrides

Function Documentation

◆ 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()