S7 (2026-09-19) — C API for the 2D surface-quality rows ([2D_COVERAGES], [2D_LOADINGS], [2D_CURB_LENGTH]) and the cell buildup store. More...

#include "openswmm_engine.h"

Include dependency graph for openswmm_sq2d.h:

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

Go to the source code of this file.

Macros
#define	SWMM_SQ2D_SCOPE_GLOBAL 0

#define	SWMM_SQ2D_SCOPE_TAG 1

#define	SWMM_SQ2D_SCOPE_CELL 2

Functions
SWMM_ENGINE_API int	swmm_2d_coverage_count (SWMM_Engine engine, int *count)
	Count authored 2D coverage scope rows.

SWMM_ENGINE_API int	swmm_2d_coverage_set (SWMM_Engine engine, int scope, const char tag, int cell, const char const landuses, const double percents, int n)
	Replace the complete land-use coverage set for one scope.

SWMM_ENGINE_API int	swmm_2d_coverage_row_size (SWMM_Engine engine, int index, int *n)
	Count the land-use pairs in an authored coverage row.

SWMM_ENGINE_API int	swmm_2d_coverage_get (SWMM_Engine engine, int index, int k, int scope, char tag, int taglen, int cell, char landuse, int lulen, double *percent)
	Copy the scope and one land-use/percentage pair of a coverage row.

SWMM_ENGINE_API int	swmm_2d_coverage_remove (SWMM_Engine engine, int index)
	Remove an authored 2D coverage scope row.

SWMM_ENGINE_API int	swmm_2d_loading_count (SWMM_Engine engine, int *count)
	Count authored 2D loading scope rows.

SWMM_ENGINE_API int	swmm_2d_loading_set (SWMM_Engine engine, int scope, const char tag, int cell, const char species, double value)
	Upsert a scope/species initial buildup loading.

SWMM_ENGINE_API int	swmm_2d_loading_get (SWMM_Engine engine, int index, int scope, char tag, int taglen, int cell, char species, int splen, double *value)
	Copy one authored initial-loading scope row.

SWMM_ENGINE_API int	swmm_2d_loading_remove (SWMM_Engine engine, int index)
	Remove an authored 2D loading scope row.

SWMM_ENGINE_API int	swmm_2d_curb_length_count (SWMM_Engine engine, int *count)
	Count authored 2D curb-length scope rows.

SWMM_ENGINE_API int	swmm_2d_curb_length_set (SWMM_Engine engine, int scope, const char *tag, int cell, double length)
	Upsert a scope's authored curb length.

SWMM_ENGINE_API int	swmm_2d_curb_length_get (SWMM_Engine engine, int index, int scope, char tag, int taglen, int cell, double length)
	Copy one authored curb-length scope row.

SWMM_ENGINE_API int	swmm_2d_curb_length_remove (SWMM_Engine engine, int index)
	Remove an authored 2D curb-length scope row.

SWMM_ENGINE_API int	swmm_2d_get_buildup_bulk (SWMM_Engine engine, const char species, double out, int n)
	Read per-cell total land-use buildup for an active surface species.

Detailed Description

S7 (2026-09-19) — C API for the 2D surface-quality rows ([2D_COVERAGES], [2D_LOADINGS], [2D_CURB_LENGTH]) and the cell buildup store.

Rows are authored per SCOPE — the * row, a TAG row (every cell carrying the tag) or a CELL row — and resolve GLOBAL < TAG < CELL at initialize, exactly as the .inp sections do (one parser, one rule). A coverage row is the WHOLE land-use set of its scope: setting it replaces any earlier row with the same scope key.

Row edits need the engine OPENED or BUILDING (SWMM_ERR_LIFECYCLE otherwise); the read-backs work in every state, and the buildup store reads back once the run has started.

Units follow the project: percent for coverages, user mass per acre | hectare for loadings and buildup (lbs | kg; a reactions species declared in UG scales through its own unit factor), and the project's length unit for curb lengths.

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

Macro Definition Documentation

◆ SWMM_SQ2D_SCOPE_CELL

#define SWMM_SQ2D_SCOPE_CELL 2

one cell, 0-based here (1-based in the file)

◆ SWMM_SQ2D_SCOPE_GLOBAL

#define SWMM_SQ2D_SCOPE_GLOBAL 0

the * row

◆ SWMM_SQ2D_SCOPE_TAG

#define SWMM_SQ2D_SCOPE_TAG 1

every cell carrying a tag

Function Documentation

◆ swmm_2d_coverage_count()

SWMM_ENGINE_API int swmm_2d_coverage_count	(	SWMM_Engine	engine,
		int *	count )

Count authored 2D coverage scope rows.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[out]	count	Non-null caller-owned row-count slot; zero when no rows are authored.

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 require initialized surface-quality runtime or resolve scope inheritance.

◆ swmm_2d_coverage_get()

SWMM_ENGINE_API int swmm_2d_coverage_get	(	SWMM_Engine	engine,
		int	index,
		int	k,
		int *	scope,
		char *	tag,
		int	taglen,
		int *	cell,
		char *	landuse,
		int	lulen,
		double *	percent )

Copy the scope and one land-use/percentage pair of a coverage row.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	index	Zero-based authored coverage-row index.
[in]	k	Zero-based pair index, below swmm_2d_coverage_row_size().
[out]	scope	Optional SWMM_SQ2D_SCOPE_* slot; NULL skips it.
[out]	tag	Optional writable tag string buffer.
[in]	taglen	Byte capacity; <= 0 skips the buffer, positive values truncate to len - 1 and append NUL.
[out]	cell	Optional zero-based cell slot; meaningful for CELL scope.
[out]	landuse	Optional writable selected land-use-name buffer.
[in]	lulen	Name-buffer byte capacity, with the same skip/truncation convention.
[out]	percent	Optional selected coverage percentage slot.

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: All outputs may be NULL. Invalid row/pair indices return SWMM_ERR_BADPARAM.

◆ swmm_2d_coverage_remove()

SWMM_ENGINE_API int swmm_2d_coverage_remove	(	SWMM_Engine	engine,
		int	index )

Remove an authored 2D coverage scope row.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	index	Zero-based current row index; later row indices shift on removal.

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.; Out-of-range row indices return SWMM_ERR_BADPARAM, not SWMM_ERR_BADINDEX.

◆ swmm_2d_coverage_row_size()

SWMM_ENGINE_API int swmm_2d_coverage_row_size	(	SWMM_Engine	engine,
		int	index,
		int *	n )

Count the land-use pairs in an authored coverage row.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	index	Zero-based authored row index.
[out]	n	Non-null caller-owned pair-count slot for that row.

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: Invalid row indices return SWMM_ERR_BADPARAM; no runtime resolution occurs.

◆ swmm_2d_coverage_set()

SWMM_ENGINE_API int swmm_2d_coverage_set	(	SWMM_Engine	engine,
		int	scope,
		const char *	tag,
		int	cell,
		const char const	landuses,
		const double *	percents,
		int	n )

Replace the complete land-use coverage set for one scope.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	scope	SWMM_SQ2D_SCOPE_GLOBAL, SWMM_SQ2D_SCOPE_TAG or SWMM_SQ2D_SCOPE_CELL.
[in]	tag	Required nonempty tag for TAG scope; ignored otherwise and may be NULL.
[in]	cell	Nonnegative zero-based cell for CELL scope; ignored otherwise.
[in]	landuses	Non-null borrowed array of n non-null existing land-use names.
[in]	percents	Non-null borrowed n-element percentage array, validated by the shared coverage parser; percentages sum to at most 100.
[in]	n	Positive number of land-use/percentage pairs.

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.; Replaces the whole same-key scope row, rather than adding individual uses. Resolution at initialize follows GLOBAL < TAG < CELL precedence.

Here is the call graph for this function:

◆ swmm_2d_curb_length_count()

SWMM_ENGINE_API int swmm_2d_curb_length_count	(	SWMM_Engine	engine,
		int *	count )

Count authored 2D curb-length scope rows.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[out]	count	Non-null caller-owned row-count slot; zero when no rows are authored.

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 require initialized surface-quality runtime or resolve scope inheritance.

◆ swmm_2d_curb_length_get()

SWMM_ENGINE_API int swmm_2d_curb_length_get	(	SWMM_Engine	engine,
		int	index,
		int *	scope,
		char *	tag,
		int	taglen,
		int *	cell,
		double *	length )

Copy one authored curb-length scope row.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	index	Zero-based current row index; invalid indices return SWMM_ERR_BADPARAM.
[out]	scope	Optional SWMM_SQ2D_SCOPE_* slot.
[out]	tag	Optional writable tag buffer; empty outside TAG scope.
[in]	taglen	Byte capacity; <= 0 skips, positive capacities safely truncate with NUL.
[out]	cell	Optional zero-based cell slot, meaningful for CELL scope.
[out]	length	Optional authored numeric slot in project length units.

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: All outputs may be NULL; reads raw authoring without applying scope precedence.

◆ swmm_2d_curb_length_remove()

SWMM_ENGINE_API int swmm_2d_curb_length_remove	(	SWMM_Engine	engine,
		int	index )

Remove an authored 2D curb-length scope row.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	index	Zero-based current row index; later row indices shift on removal.

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.; Out-of-range row indices return SWMM_ERR_BADPARAM, not SWMM_ERR_BADINDEX.

◆ swmm_2d_curb_length_set()

SWMM_ENGINE_API int swmm_2d_curb_length_set	(	SWMM_Engine	engine,
		int	scope,
		const char *	tag,
		int	cell,
		double	length )

Upsert a scope's authored curb length.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	scope	SWMM_SQ2D_SCOPE_GLOBAL, SWMM_SQ2D_SCOPE_TAG or SWMM_SQ2D_SCOPE_CELL.
[in]	tag	Required nonempty tag for TAG scope; ignored otherwise and may be NULL.
[in]	cell	Nonnegative zero-based cell for CELL scope; ignored otherwise.
[in]	length	Positive curb length in project length units, validated by the shared 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.; Removes any earlier row with the same scope and appends its replacement.

Here is the call graph for this function:

◆ swmm_2d_get_buildup_bulk()

SWMM_ENGINE_API int swmm_2d_get_buildup_bulk	(	SWMM_Engine	engine,
		const char *	species,
		double *	out,
		int	n )

Read per-cell total land-use buildup for an active surface species.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	species	Non-null exact active species name (pollutant or reactions species).
[out]	out	Non-null caller-owned array for every active surface-quality cell, receiving project species mass per acre/hectare summed over land uses.
[in]	n	Output capacity in doubles, at least the active cell count; only the cell-count prefix is written.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE, SWMM_ERR_BADPARAM for a missing name/ buffer, unknown species or short capacity, or SWMM_ERR_LIFECYCLE when the surface-quality runtime is inactive.

Note: No covering rows, IGNORE_QUALITY or RAINFALL_MODE NONE can leave the runtime inactive. The call does not advance buildup or retain the buffer.

◆ swmm_2d_loading_count()

SWMM_ENGINE_API int swmm_2d_loading_count	(	SWMM_Engine	engine,
		int *	count )

Count authored 2D loading scope rows.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[out]	count	Non-null caller-owned row-count slot; zero when no rows are authored.

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 require initialized surface-quality runtime or resolve scope inheritance.

◆ swmm_2d_loading_get()

SWMM_ENGINE_API int swmm_2d_loading_get	(	SWMM_Engine	engine,
		int	index,
		int *	scope,
		char *	tag,
		int	taglen,
		int *	cell,
		char *	species,
		int	splen,
		double *	value )

Copy one authored initial-loading scope row.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	index	Zero-based current row index; invalid indices return SWMM_ERR_BADPARAM.
[out]	scope	Optional SWMM_SQ2D_SCOPE_* slot.
[out]	tag	Optional writable tag buffer; empty outside TAG scope.
[in]	taglen	Byte capacity; <= 0 skips, positive capacities safely truncate with NUL.
[out]	cell	Optional zero-based cell slot, meaningful for CELL scope.
[out]	species	Optional writable species-name buffer.
[in]	splen	Name-buffer byte capacity; <= 0 skips, positive capacities truncate with NUL.
[out]	value	Optional authored numeric slot in project pollutant mass per acre/hectare.

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: All outputs may be NULL; reads raw authoring without applying scope precedence.

◆ swmm_2d_loading_remove()

SWMM_ENGINE_API int swmm_2d_loading_remove	(	SWMM_Engine	engine,
		int	index )

Remove an authored 2D loading scope row.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	index	Zero-based current row index; later row indices shift on removal.

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.; Out-of-range row indices return SWMM_ERR_BADPARAM, not SWMM_ERR_BADINDEX.

◆ swmm_2d_loading_set()

SWMM_ENGINE_API int swmm_2d_loading_set	(	SWMM_Engine	engine,
		int	scope,
		const char *	tag,
		int	cell,
		const char *	species,
		double	value )

Upsert a scope/species initial buildup loading.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	scope	SWMM_SQ2D_SCOPE_GLOBAL, SWMM_SQ2D_SCOPE_TAG or SWMM_SQ2D_SCOPE_CELL.
[in]	tag	Required nonempty tag for TAG scope; ignored otherwise and may be NULL.
[in]	cell	Nonnegative zero-based cell for CELL scope; ignored otherwise.
[in]	species	Non-null existing pollutant or reactions-species name.
[in]	value	Loading in project pollutant mass per acre/hectare; validated by the shared loading parser and retained at exact double precision.

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.; Removes earlier same-scope/species rows and appends the replacement; other species and scopes are preserved.

Here is the call graph for this function:

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ SWMM_SQ2D_SCOPE_CELL

◆ SWMM_SQ2D_SCOPE_GLOBAL

◆ SWMM_SQ2D_SCOPE_TAG

Function Documentation

◆ swmm_2d_coverage_count()

◆ swmm_2d_coverage_get()

◆ swmm_2d_coverage_remove()

◆ swmm_2d_coverage_row_size()

◆ swmm_2d_coverage_set()

◆ swmm_2d_curb_length_count()

◆ swmm_2d_curb_length_get()

◆ swmm_2d_curb_length_remove()

◆ swmm_2d_curb_length_set()

◆ swmm_2d_get_buildup_bulk()

◆ swmm_2d_loading_count()

◆ swmm_2d_loading_get()

◆ swmm_2d_loading_remove()

◆ swmm_2d_loading_set()