openswmm_quality.h File Reference

OpenSWMM Engine — Water Quality (Landuse / Buildup / Washoff / Treatment) C API. More...

#include "openswmm_engine.h"

Include dependency graph for openswmm_quality.h:

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

Go to the source code of this file.

Functions
SWMM_ENGINE_API int	swmm_landuse_count (SWMM_Engine engine)
	Number of land uses defined.
SWMM_ENGINE_API int	swmm_landuse_index (SWMM_Engine engine, const char *id)
	Look up a land use by name. Returns -1 if not found.
SWMM_ENGINE_API const char *	swmm_landuse_id (SWMM_Engine engine, int idx)
	Return the name of a land use by index. Returns NULL on error.
SWMM_ENGINE_API int	swmm_landuse_add (SWMM_Engine engine, const char *id)
	Add a new land use (BUILDING state only).
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)
	Set sweep interval (days between street sweeps).
SWMM_ENGINE_API int	swmm_landuse_get_sweep_interval (SWMM_Engine engine, int idx, double *days)
	Get sweep interval (days between street sweeps).
SWMM_ENGINE_API int	swmm_landuse_set_sweep_removal (SWMM_Engine engine, int idx, double frac)
	Set sweep removal fraction (0-1).
SWMM_ENGINE_API int	swmm_landuse_get_sweep_removal (SWMM_Engine engine, int idx, double *frac)
	Get sweep removal fraction (0-1).
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

OpenSWMM Engine — Water Quality (Landuse / Buildup / Washoff / Treatment) C API.

Provides functions for managing landuse definitions, buildup/washoff functions per (landuse x pollutant), and treatment expressions per (node x pollutant).

See also

openswmm_engine.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\n 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

	engine	Engine handle.
	lu_idx	Landuse index.
	pollut_idx	Pollutant index.
[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.

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

engine	Engine handle.
lu_idx	Landuse index.
pollut_idx	Pollutant index.
func_type	Buildup function type (0=NONE, 1=POW, 2=EXP, 3=SAT, 4=EXT).
c1	Coefficient 1.
c2	Coefficient 2.
c3	Coefficient 3.
normalizer	Normalizer (0=PER_AREA, 1=PER_CURB).

swmm_landuse_add()

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

Add a new land use (BUILDING state only).

swmm_landuse_count()

SWMM_ENGINE_API int swmm_landuse_count

(

SWMM_Engine

engine

)

Number of land uses defined.

swmm_landuse_get_sweep_interval()

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

Get sweep interval (days between street sweeps).

swmm_landuse_get_sweep_removal()

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

Get sweep removal fraction (0-1).

swmm_landuse_id()

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

Return the name of a land use by index. Returns NULL on error.

swmm_landuse_index()

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

Look up a land use by name. Returns -1 if not found.

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

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

Returns

SWMM_OK, or SWMM_ERR_BADPARAM on empty/duplicate name.

swmm_landuse_set_sweep_interval()

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

Set sweep interval (days between street sweeps).

swmm_landuse_set_sweep_removal()

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

Set sweep removal fraction (0-1).

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

engine	Engine handle.
node_idx	Node index.
pollut_idx	Pollutant index.

Returns

SWMM_OK on success, or an error code.

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

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

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

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

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

	engine	Engine handle (grammar only; no model data is read).
	expr	Expression string ("R = ..." or "C = ...").
[out]	errbuf	Receives the diagnostic on failure ("" on success). May be NULL.
	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.

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

	engine	Engine handle.
	lu_idx	Landuse index.
	pollut_idx	Pollutant 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.

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

engine	Engine handle.
lu_idx	Landuse index.
pollut_idx	Pollutant index.
func_type	Washoff function type (0=NONE, 1=EXP, 2=RC, 3=EMC).
coeff	Washoff coefficient.
expon	Washoff exponent.
sweep_effic	Sweep efficiency (0-100).
bmp_effic	BMP efficiency (0-100).