openswmm_quality_impl.cpp File Reference

C API implementation — landuse, buildup, washoff, treatment. More...

#include "openswmm_api_common.hpp"
#include "../../../include/openswmm/engine/openswmm_quality.h"
#include "../quality/Treatment.hpp"
#include "../quality/MsxSurfaceQuality.hpp"
#include <cstring>

Include dependency graph for openswmm_quality_impl.cpp:

Functions
SWMM_ENGINE_API int	swmm_landuse_count (SWMM_Engine engine)
	Count land-use definitions in the current model.
SWMM_ENGINE_API int	swmm_landuse_index (SWMM_Engine engine, const char *id)
	Resolve a land-use identifier to its row index.
SWMM_ENGINE_API const char *	swmm_landuse_id (SWMM_Engine engine, int idx)
	Borrow a land-use identifier from the model name index.
SWMM_ENGINE_API int	swmm_landuse_add (SWMM_Engine engine, const char *id)
	Append a land use while preserving existing model parameter columns.
SWMM_ENGINE_API int	swmm_landuse_rename (SWMM_Engine engine, int idx, const char *new_id)
	Rename a land use in place.
SWMM_ENGINE_API int	swmm_landuse_set_sweep_interval (SWMM_Engine engine, int idx, double days)
	Assign the configured interval between street sweeps.
SWMM_ENGINE_API int	swmm_landuse_get_sweep_interval (SWMM_Engine engine, int idx, double *days)
	Read the configured interval between street sweeps.
SWMM_ENGINE_API int	swmm_landuse_set_sweep_removal (SWMM_Engine engine, int idx, double frac)
	Assign the land-use sweep-removal fraction.
SWMM_ENGINE_API int	swmm_landuse_get_sweep_removal (SWMM_Engine engine, int idx, double *frac)
	Read the land-use sweep-removal fraction.
SWMM_ENGINE_API int	swmm_buildup_set (SWMM_Engine engine, int lu_idx, int pollut_idx, int func_type, double c1, double c2, double c3, int normalizer)
	Set buildup function parameters for a (landuse, pollutant) pair.
SWMM_ENGINE_API int	swmm_buildup_get (SWMM_Engine engine, int lu_idx, int pollut_idx, int *func_type, double *c1, double *c2, double *c3, int *normalizer)
	Get buildup function parameters for a (landuse, pollutant) pair.
SWMM_ENGINE_API int	swmm_washoff_set (SWMM_Engine engine, int lu_idx, int pollut_idx, int func_type, double coeff, double expon, double sweep_effic, double bmp_effic)
	Set washoff function parameters for a (landuse, pollutant) pair.
SWMM_ENGINE_API int	swmm_washoff_get (SWMM_Engine engine, int lu_idx, int pollut_idx, int *func_type, double *coeff, double *expon, double *sweep_effic, double *bmp_effic)
	Get washoff function parameters for a (landuse, pollutant) pair.
SWMM_ENGINE_API int	swmm_treatment_set (SWMM_Engine engine, int node_idx, int pollut_idx, const char *expression)
	Set a treatment expression for a (node, pollutant) pair.
SWMM_ENGINE_API int	swmm_treatment_get (SWMM_Engine engine, int node_idx, int pollut_idx, char *buf, int buflen)
	Get a treatment expression for a (node, pollutant) pair.
SWMM_ENGINE_API int	swmm_treatment_clear (SWMM_Engine engine, int node_idx, int pollut_idx)
	Clear a treatment expression for a (node, pollutant) pair.
SWMM_ENGINE_API int	swmm_treatment_validate_expression (SWMM_Engine engine, const char *expr, char *errbuf, int buflen, int *col_out)
	Validate a treatment expression WITHOUT modifying engine state.

Detailed Description

C API implementation — landuse, buildup, washoff, treatment.

See also

include/openswmm/engine/openswmm_quality.h

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

SWMM_ENGINE_API int swmm_buildup_get	(	SWMM_Engine	engine,
		int	lu_idx,
		int	pollut_idx,
		int *	func_type,
		double *	c1,
		double *	c2,
		double *	c3,
		int *	normalizer )

Get buildup function parameters for a (landuse, pollutant) pair.

Parameters

[in]	engine	Engine handle.
[in]	lu_idx	Landuse index.
[in]	pollut_idx	Surface-species index: a pollutant index, or n_pollutants + m for the reactions component's m-th species (BW-MSX, 2026-09-19 — MSX species build up and wash off by the same relations).
[out]	func_type	Buildup function type (0=NONE, 1=POW, 2=EXP, 3=SAT, 4=EXT).
[out]	c1	Coefficient 1.
[out]	c2	Coefficient 2.
[out]	c3	Coefficient 3.
[out]	normalizer	Normalizer (0=PER_AREA, 1=PER_CURB).

Returns

SWMM_OK on success, or an error code.

Note

func_type may be NULL to suppress that output. c1 may be NULL to suppress that output. c2 may be NULL to suppress that output. c3 may be NULL to suppress that output. normalizer may be NULL to suppress that output. A null engine returns SWMM_ERR_BADHANDLE. A failed land-use/node/pollutant/pollutant index check returns SWMM_ERR_BADINDEX. pollut_idx addresses a pollutant row or n_pollutants+reaction_species_index. Reaction rows with no dimensioned parameter store read as zero/NONE; missing native pollutant matrix entries return BADINDEX.

swmm_buildup_set()

SWMM_ENGINE_API int swmm_buildup_set	(	SWMM_Engine	engine,
		int	lu_idx,
		int	pollut_idx,
		int	func_type,
		double	c1,
		double	c2,
		double	c3,
		int	normalizer )

Set buildup function parameters for a (landuse, pollutant) pair.

Parameters

[in]	engine	Engine handle.
[in]	lu_idx	Landuse index.
[in]	pollut_idx	Surface-species index: pollutant, or n_pollutants + reaction species index.
[in]	func_type	Buildup function type (0=NONE, 1=POW, 2=EXP, 3=SAT, 4=EXT).
[in]	c1	Coefficient 1.
[in]	c2	Coefficient 2.
[in]	c3	Coefficient 3.
[in]	normalizer	Normalizer (0=PER_AREA, 1=PER_CURB).

Note

A null engine returns SWMM_ERR_BADHANDLE. A failed land-use/node/pollutant/pollutant index check returns SWMM_ERR_BADINDEX. No lifecycle guard is imposed. Coefficients, enum selectors and percentage/fraction ranges are stored without separate validation; units and meanings follow the selected input function. Pollutant rows refresh the runtime land-use cache for subsequent steps.

Here is the call graph for this function:

swmm_landuse_add()

SWMM_ENGINE_API int swmm_landuse_add	(	SWMM_Engine	engine,
		const char *	id )

Append a land use while preserving existing model parameter columns.

Grows sweeping and buildup/washoff rows and repacks subcatchment land-use coverage when its existing dimensions match. New rows default to zero. Configure parameters/coverage before initialization.

Parameters

[in]	engine	Non-null live engine; caller provides exclusive access.
[in]	id	Non-null copied identifier; an existing land-use ID is refused.

Returns

SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_LIFECYCLE outside BUILDING/OPENED, or SWMM_ERR_BADPARAM for null/duplicate ID.

swmm_landuse_count()

SWMM_ENGINE_API int swmm_landuse_count

(

SWMM_Engine

engine

)

Count land-use definitions in the current model.

Parameters

[in]

engine

Non-null live engine; caller provides exclusive access.

Returns

Nonnegative count, or -1 for null engine.

swmm_landuse_get_sweep_interval()

SWMM_ENGINE_API int swmm_landuse_get_sweep_interval	(	SWMM_Engine	engine,
		int	idx,
		double *	days )

Read the configured interval between street sweeps.

Parameters

[in]	engine	Non-null live engine; caller provides exclusive access.
[in]	idx	Zero-based existing land-use index.
[out]	days	Optional destination in days.

Returns

SWMM_OK; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADINDEX for invalid land-use index.

swmm_landuse_get_sweep_removal()

SWMM_ENGINE_API int swmm_landuse_get_sweep_removal	(	SWMM_Engine	engine,
		int	idx,
		double *	frac )

Read the land-use sweep-removal fraction.

Parameters

[in]	engine	Non-null live engine; caller provides exclusive access.
[in]	idx	Zero-based existing land-use index.
[out]	frac	Optional destination for the stored dimensionless fraction.

Returns

SWMM_OK; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADINDEX for invalid land-use index.

swmm_landuse_id()

SWMM_ENGINE_API const char * swmm_landuse_id	(	SWMM_Engine	engine,
		int	idx )

Borrow a land-use identifier from the model name index.

Parameters

[in]	engine	Non-null live engine; caller provides exclusive access.
[in]	idx	Zero-based existing land-use index.

Returns

Engine-owned NUL-terminated ID, or NULL for invalid handle/index. Never free it; copy before name/topology edits, close/reopen or destruction.

swmm_landuse_index()

SWMM_ENGINE_API int swmm_landuse_index	(	SWMM_Engine	engine,
		const char *	id )

Resolve a land-use identifier to its row index.

Parameters

[in]	engine	Non-null live engine; caller provides exclusive access.
[in]	id	Non-null NUL-terminated identifier, borrowed for the lookup.

Returns

Zero-based index, or -1 for null engine/ID or absent name.

swmm_landuse_rename()

SWMM_ENGINE_API int swmm_landuse_rename	(	SWMM_Engine	engine,
		int	idx,
		const char *	new_id )

Rename a land use in place.

Land uses are referenced positionally (matrix dimensions), so the rename only touches the name registry — buildup/washoff rows and subcatchment coverages follow automatically.

Parameters

[in]	engine	Engine handle.
[in]	idx	Land use index.
[in]	new_id	New unique name (non-empty).

Returns

SWMM_OK, or SWMM_ERR_BADPARAM on empty/duplicate name.

Note

Requires BUILDING or OPENED; other states return SWMM_ERR_LIFECYCLE. A null engine returns SWMM_ERR_BADHANDLE. A failed land-use/node/pollutant/pollutant index check returns SWMM_ERR_BADINDEX.

swmm_landuse_set_sweep_interval()

SWMM_ENGINE_API int swmm_landuse_set_sweep_interval	(	SWMM_Engine	engine,
		int	idx,
		double	days )

Assign the configured interval between street sweeps.

No lifecycle guard is imposed. This stores the parameter without rescheduling a previously completed sweep.

Parameters

[in]	engine	Non-null live engine; caller provides exclusive access.
[in]	idx	Zero-based existing land-use index.
[in]	days	Interval in days; stored without finite/nonnegative validation.

Returns

SWMM_OK; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADINDEX for invalid land-use index.

swmm_landuse_set_sweep_removal()

SWMM_ENGINE_API int swmm_landuse_set_sweep_removal	(	SWMM_Engine	engine,
		int	idx,
		double	frac )

Assign the land-use sweep-removal fraction.

No lifecycle guard is imposed.

Parameters

[in]	engine	Non-null live engine; caller provides exclusive access.
[in]	idx	Zero-based existing land-use index.
[in]	frac	Dimensionless removal fraction, conventionally [0,1]; stored without clamping/finite/range checks.

Returns

SWMM_OK; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADINDEX for invalid land-use index.

swmm_treatment_clear()

SWMM_ENGINE_API int swmm_treatment_clear	(	SWMM_Engine	engine,
		int	node_idx,
		int	pollut_idx )

Clear a treatment expression for a (node, pollutant) pair.

Parameters

[in]	engine	Engine handle.
[in]	node_idx	Node index.
[in]	pollut_idx	Pollutant index.

Returns

SWMM_OK on success, or an error code.

Note

A null engine returns SWMM_ERR_BADHANDLE. A failed land-use/node/pollutant/pollutant index check returns SWMM_ERR_BADINDEX. No lifecycle guard is imposed. Clearing an unset valid cell succeeds; clears/recompiles the cached treatment so the next step sees the removal.

swmm_treatment_get()

SWMM_ENGINE_API int swmm_treatment_get	(	SWMM_Engine	engine,
		int	node_idx,
		int	pollut_idx,
		char *	buf,
		int	buflen )

Get a treatment expression for a (node, pollutant) pair.

Parameters

[in]	engine	Engine handle.
[in]	node_idx	Node index.
[in]	pollut_idx	Pollutant index.
[out]	buf	Buffer to receive the expression string.
[in]	buflen	Size of buf.

Note

A null engine returns SWMM_ERR_BADHANDLE. A failed land-use/node/pollutant/pollutant index check returns SWMM_ERR_BADINDEX. buf must be non-null and buflen positive or BADPARAM is returned. Empty when no stored expression exists; NUL-terminated and silently truncated to buflen-1 bytes.

swmm_treatment_set()

SWMM_ENGINE_API int swmm_treatment_set	(	SWMM_Engine	engine,
		int	node_idx,
		int	pollut_idx,
		const char *	expression )

Set a treatment expression for a (node, pollutant) pair.

Parameters

[in]	engine	Engine handle.
[in]	node_idx	Node index.
[in]	pollut_idx	Pollutant index.
[in]	expression	Treatment expression string (e.g. "R = 0.5 * exp(-0.1 * DT)").

Note

A null engine returns SWMM_ERR_BADHANDLE. A failed land-use/node/pollutant/pollutant index check returns SWMM_ERR_BADINDEX. expression must be non-null or BADPARAM is returned. Copies and compiles the expression immediately, including mid-run; parser refusal restores the previous text/compiled cell and returns BADPARAM. Does not install an uncompiled text-only placeholder.

swmm_treatment_validate_expression()

SWMM_ENGINE_API int swmm_treatment_validate_expression	(	SWMM_Engine	engine,
		const char *	expr,
		char *	errbuf,
		int	buflen,
		int *	col_out )

Validate a treatment expression WITHOUT modifying engine state.

Editor-support peer of swmm_control_validate_rule: parses expr through the production treatment grammar and reports a human-readable diagnostic plus the 0-based character offset of the error. Unlike swmm_treatment_set (which recompiles the node's treatment on success), this call never mutates the engine, so it is safe to invoke per keystroke. Note the validator is deliberately stricter than the tokenizer in one way: unknown characters are an error rather than silently skipped. Co-pollutant references (R_name/C_name) are reported as unsupported.

Parameters

[in]	engine	Engine handle (grammar only; no model data is read).
[in]	expr	Expression string ("R = ..." or "C = ...").
[out]	errbuf	Receives the diagnostic on failure ("" on success). May be NULL.
[in]	buflen	Size of errbuf in bytes.
[out]	col_out	Receives the 0-based character offset of the error, or -1 when not attributable. May be NULL.

Returns

SWMM_OK when the expression is valid, SWMM_ERR_BADPARAM when invalid (diagnostic in errbuf/col_out) or on NULL expr.

Note

col_out may be NULL to suppress that output. A null engine returns SWMM_ERR_BADHANDLE. The engine must still be non-null or BADHANDLE is returned. Optional errbuf is NUL-terminated/truncated only when buflen>0; a nonpositive length suppresses message copying. Sets col_out=-1 before validating, including null-expression refusal.

Here is the call graph for this function:

swmm_washoff_get()

SWMM_ENGINE_API int swmm_washoff_get	(	SWMM_Engine	engine,
		int	lu_idx,
		int	pollut_idx,
		int *	func_type,
		double *	coeff,
		double *	expon,
		double *	sweep_effic,
		double *	bmp_effic )

Get washoff function parameters for a (landuse, pollutant) pair.

Parameters

[in]	engine	Engine handle.
[in]	lu_idx	Landuse index.
[in]	pollut_idx	Surface-species index: pollutant, or n_pollutants + reaction species index.
[out]	func_type	Washoff function type (0=NONE, 1=EXP, 2=RC, 3=EMC).
[out]	coeff	Washoff coefficient.
[out]	expon	Washoff exponent.
[out]	sweep_effic	Sweep efficiency (0-100).
[out]	bmp_effic	BMP efficiency (0-100).

Returns

SWMM_OK on success, or an error code.

Note

func_type may be NULL to suppress that output. coeff may be NULL to suppress that output. expon may be NULL to suppress that output. sweep_effic may be NULL to suppress that output. bmp_effic may be NULL to suppress that output. A null engine returns SWMM_ERR_BADHANDLE. A failed land-use/node/pollutant/pollutant index check returns SWMM_ERR_BADINDEX. pollut_idx addresses a pollutant row or n_pollutants+reaction_species_index. Reaction rows with no dimensioned parameter store read as zero/NONE; missing native pollutant matrix entries return BADINDEX.

swmm_washoff_set()

SWMM_ENGINE_API int swmm_washoff_set	(	SWMM_Engine	engine,
		int	lu_idx,
		int	pollut_idx,
		int	func_type,
		double	coeff,
		double	expon,
		double	sweep_effic,
		double	bmp_effic )

Set washoff function parameters for a (landuse, pollutant) pair.

Parameters

[in]	engine	Engine handle.
[in]	lu_idx	Landuse index.
[in]	pollut_idx	Surface-species index (pollutant, or n_pollutants + m for the m-th reactions-component species — BW-MSX).
[in]	func_type	Washoff function type (0=NONE, 1=EXP, 2=RC, 3=EMC).
[in]	coeff	Washoff coefficient.
[in]	expon	Washoff exponent.
[in]	sweep_effic	Sweep efficiency (0-100).
[in]	bmp_effic	BMP efficiency (0-100).

Note

A null engine returns SWMM_ERR_BADHANDLE. A failed land-use/node/pollutant/pollutant index check returns SWMM_ERR_BADINDEX. No lifecycle guard is imposed. Coefficients, enum selectors and percentage/fraction ranges are stored without separate validation; units and meanings follow the selected input function. Pollutant rows refresh the runtime land-use cache for subsequent steps.