ApiSq2D.cpp File Reference

S7 (2026-09-19) — C API over the 2D surface-quality rows and the cell buildup store (openswmm_sq2d.h). More...

#include <openswmm/engine/openswmm_engine.h>
#include <openswmm/engine/openswmm_sq2d.h>
#include "../../core/SWMMEngine.hpp"
#include "../quality/SurfaceQuality2D.hpp"
#include <algorithm>
#include <cstring>
#include <string>
#include <vector>

Include dependency graph for ApiSq2D.cpp:

Macros
#define	SQ_STORE(engine)
#define	SQ_EDITABLE(eng)

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 over the 2D surface-quality rows and the cell buildup store (openswmm_sq2d.h).

Row edits go through the SAME line parsers the .inp sections use (parse2DCoveragesLine & co.), so the API and the file share one grammar, one replace-by-scope rule and one percent check. The names a row refers to are validated here against the model's land uses and species, which the parsers defer to initialize — a host must not be able to build a model the file would refuse.

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

SQ_EDITABLE

#define SQ_EDITABLE

(

eng

)

Value:

    if (eng->context().state != openswmm::EngineState::OPENED &&                                   \
        eng->context().state != openswmm::EngineState::BUILDING)                                   \
    return SWMM_ERR_LIFECYCLE

SQ_STORE

#define SQ_STORE

(

engine

)

Value:

    auto* eng = reinterpret_cast<openswmm::SWMMEngine*>(engine);                                   \
    if (!eng)                                                                                      \
        return SWMM_ERR_BADHANDLE;                                                                 \
    SurfaceQuality2D& sq = eng->surfaceRouter2D().surfaceQuality()

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: