openswmm_pollutants_impl.cpp File Reference

C API implementation — pollutant identity, creation, properties, quality injection. More...

#include "openswmm_api_common.hpp"
#include "../../../include/openswmm/engine/openswmm_pollutants.h"

Include dependency graph for openswmm_pollutants_impl.cpp:

Functions
SWMM_ENGINE_API int	swmm_pollutant_count (SWMM_Engine engine)
	Get the total number of pollutants in the model.
SWMM_ENGINE_API int	swmm_pollutant_index (SWMM_Engine engine, const char *id)
	Look up a pollutant's zero-based index by its string identifier.
SWMM_ENGINE_API const char *	swmm_pollutant_id (SWMM_Engine engine, int idx)
	Get the string identifier of a pollutant by index.
SWMM_ENGINE_API int	swmm_pollutant_add (SWMM_Engine engine, const char *id, int units)
	Add a new pollutant to the model.
SWMM_ENGINE_API int	swmm_pollutant_set_kdecay (SWMM_Engine engine, int idx, double k)
	Set the first-order decay coefficient for a pollutant.
SWMM_ENGINE_API int	swmm_pollutant_set_rain_conc (SWMM_Engine engine, int idx, double conc)
	Set the pollutant concentration in rainfall.
SWMM_ENGINE_API int	swmm_pollutant_set_gw_conc (SWMM_Engine engine, int idx, double conc)
	Set the pollutant concentration in groundwater.
SWMM_ENGINE_API int	swmm_pollutant_set_init_conc (SWMM_Engine engine, int idx, double conc)
	Set the initial concentration throughout the conveyance system.
SWMM_ENGINE_API int	swmm_pollutant_set_units (SWMM_Engine engine, int idx, int units)
	Change the concentration units of an existing pollutant.
SWMM_ENGINE_API int	swmm_pollutant_get_units (SWMM_Engine engine, int idx, int *units)
	Get the concentration units code for a pollutant.
SWMM_ENGINE_API int	swmm_pollutant_get_kdecay (SWMM_Engine engine, int idx, double *k)
	Get the first-order decay coefficient.
SWMM_ENGINE_API int	swmm_pollutant_get_rain_conc (SWMM_Engine engine, int idx, double *conc)
	Get the pollutant concentration in rainfall.
SWMM_ENGINE_API int	swmm_pollutant_get_gw_conc (SWMM_Engine engine, int idx, double *conc)
	Get the pollutant concentration in groundwater.
SWMM_ENGINE_API int	swmm_pollutant_get_init_conc (SWMM_Engine engine, int idx, double *conc)
	Get the initial concentration throughout the conveyance system.
SWMM_ENGINE_API int	swmm_pollutant_set_rdii_conc (SWMM_Engine engine, int idx, double conc)
	Set the RDII (Rainfall-Dependent Infiltration/Inflow) concentration.
SWMM_ENGINE_API int	swmm_pollutant_get_rdii_conc (SWMM_Engine engine, int idx, double *conc)
	Get the RDII concentration.
SWMM_ENGINE_API int	swmm_pollutant_set_dwf_conc (SWMM_Engine engine, int idx, double conc)
	Set the default dry weather sanitary flow concentration.
SWMM_ENGINE_API int	swmm_pollutant_get_dwf_conc (SWMM_Engine engine, int idx, double *conc)
	Get the default dry weather sanitary flow concentration.
SWMM_ENGINE_API int	swmm_pollutant_set_mwt (SWMM_Engine engine, int idx, double mwt)
	Set the molecular weight of a pollutant.
SWMM_ENGINE_API int	swmm_pollutant_get_mwt (SWMM_Engine engine, int idx, double *mwt)
	Get the molecular weight of a pollutant.
SWMM_ENGINE_API int	swmm_pollutant_set_co_pollutant (SWMM_Engine engine, int idx, int co_idx, double frac)
	Set a co-pollutant relationship (concentration = fraction * co-pollutant).
SWMM_ENGINE_API int	swmm_pollutant_get_co_pollutant (SWMM_Engine engine, int idx, int *co_idx, double *frac)
	Get a co-pollutant relationship.
SWMM_ENGINE_API int	swmm_pollutant_set_snow_only (SWMM_Engine engine, int idx, int flag)
	Set whether a pollutant only builds up during snowfall events.
SWMM_ENGINE_API int	swmm_pollutant_get_snow_only (SWMM_Engine engine, int idx, int *flag)
	Get whether a pollutant only builds up during snowfall events.
SWMM_ENGINE_API int	swmm_node_set_quality (SWMM_Engine engine, int node_idx, int pollut_idx, double conc)
	Set the pollutant concentration at a node (runtime override).
SWMM_ENGINE_API int	swmm_link_set_quality (SWMM_Engine engine, int link_idx, int pollut_idx, double conc)
	Set the pollutant concentration in a link (runtime override).

Detailed Description

C API implementation — pollutant identity, creation, properties, quality injection.

See also

include/openswmm/engine/openswmm_pollutants.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 MIT License

Function Documentation

swmm_link_set_quality()

SWMM_ENGINE_API int swmm_link_set_quality	(	SWMM_Engine	engine,
		int	link_idx,
		int	pollut_idx,
		double	conc )

Set the pollutant concentration in a link (runtime override).

Parameters

engine	Engine handle (RUNNING state).
link_idx	Zero-based link index.
pollut_idx	Zero-based pollutant index.
conc	Concentration in pollutant units.

Returns

SWMM_OK on success, or an error code.

swmm_node_set_quality()

SWMM_ENGINE_API int swmm_node_set_quality	(	SWMM_Engine	engine,
		int	node_idx,
		int	pollut_idx,
		double	conc )

Set the pollutant concentration at a node (runtime override).

Parameters

engine	Engine handle (RUNNING state).
node_idx	Zero-based node index.
pollut_idx	Zero-based pollutant index.
conc	Concentration in pollutant units.

Returns

SWMM_OK on success, or an error code.

swmm_pollutant_add()

SWMM_ENGINE_API int swmm_pollutant_add	(	SWMM_Engine	engine,
		const char *	id,
		int	units )

Add a new pollutant to the model.

Parameters

engine	Engine handle (SWMM_STATE_BUILDING).
id	Unique null-terminated identifier for the new pollutant.
units	Concentration units code (0=MG/L, 1=UG/L, 2=#/L).

Returns

SWMM_OK on success, or an error code.

swmm_pollutant_count()

SWMM_ENGINE_API int swmm_pollutant_count

(

SWMM_Engine

engine

)

Get the total number of pollutants in the model.

Parameters

engine

Engine handle.

Returns

Number of pollutants, or -1 on error.

swmm_pollutant_get_co_pollutant()

SWMM_ENGINE_API int swmm_pollutant_get_co_pollutant	(	SWMM_Engine	engine,
		int	idx,
		int *	co_idx,
		double *	frac )

Get a co-pollutant relationship.

Parameters

	engine	Engine handle.
	idx	Zero-based pollutant index.
[out]	co_idx	Receives the co-pollutant index (-1 if none).
[out]	frac	Receives the fraction.

Returns

SWMM_OK on success, or an error code.

swmm_pollutant_get_dwf_conc()

SWMM_ENGINE_API int swmm_pollutant_get_dwf_conc	(	SWMM_Engine	engine,
		int	idx,
		double *	conc )

Get the default dry weather sanitary flow concentration.

Parameters

	engine	Engine handle.
	idx	Zero-based pollutant index.
[out]	conc	Receives the DWF concentration.

Returns

SWMM_OK on success, or an error code.

swmm_pollutant_get_gw_conc()

SWMM_ENGINE_API int swmm_pollutant_get_gw_conc	(	SWMM_Engine	engine,
		int	idx,
		double *	conc )

Get the pollutant concentration in groundwater.

Parameters

	engine	Engine handle.
	idx	Zero-based pollutant index.
[out]	conc	Receives the concentration.

Returns

SWMM_OK on success, or an error code.

swmm_pollutant_get_init_conc()

SWMM_ENGINE_API int swmm_pollutant_get_init_conc	(	SWMM_Engine	engine,
		int	idx,
		double *	conc )

Get the initial concentration throughout the conveyance system.

Parameters

	engine	Engine handle.
	idx	Zero-based pollutant index.
[out]	conc	Receives the initial concentration.

Returns

SWMM_OK on success, or an error code.

swmm_pollutant_get_kdecay()

SWMM_ENGINE_API int swmm_pollutant_get_kdecay	(	SWMM_Engine	engine,
		int	idx,
		double *	k )

Get the first-order decay coefficient.

Parameters

	engine	Engine handle.
	idx	Zero-based pollutant index.
[out]	k	Receives the decay coefficient (1/day).

Returns

SWMM_OK on success, or an error code.

swmm_pollutant_get_mwt()

SWMM_ENGINE_API int swmm_pollutant_get_mwt	(	SWMM_Engine	engine,
		int	idx,
		double *	mwt )

Get the molecular weight of a pollutant.

Parameters

	engine	Engine handle.
	idx	Zero-based pollutant index.
[out]	mwt	Receives the molecular weight.

Returns

SWMM_OK on success, or an error code.

swmm_pollutant_get_rain_conc()

SWMM_ENGINE_API int swmm_pollutant_get_rain_conc	(	SWMM_Engine	engine,
		int	idx,
		double *	conc )

Get the pollutant concentration in rainfall.

Parameters

	engine	Engine handle.
	idx	Zero-based pollutant index.
[out]	conc	Receives the concentration.

Returns

SWMM_OK on success, or an error code.

swmm_pollutant_get_rdii_conc()

SWMM_ENGINE_API int swmm_pollutant_get_rdii_conc	(	SWMM_Engine	engine,
		int	idx,
		double *	conc )

Get the RDII concentration.

Parameters

	engine	Engine handle.
	idx	Zero-based pollutant index.
[out]	conc	Receives the RDII concentration.

Returns

SWMM_OK on success, or an error code.

swmm_pollutant_get_snow_only()

SWMM_ENGINE_API int swmm_pollutant_get_snow_only	(	SWMM_Engine	engine,
		int	idx,
		int *	flag )

Get whether a pollutant only builds up during snowfall events.

Parameters

	engine	Engine handle.
	idx	Zero-based pollutant index.
[out]	flag	Receives 1 for snow-only, 0 otherwise.

Returns

SWMM_OK on success, or an error code.

swmm_pollutant_get_units()

SWMM_ENGINE_API int swmm_pollutant_get_units	(	SWMM_Engine	engine,
		int	idx,
		int *	units )

Get the concentration units code for a pollutant.

Parameters

	engine	Engine handle.
	idx	Zero-based pollutant index.
[out]	units	Receives the units code (0=MG/L, 1=UG/L, 2=#/L).

Returns

SWMM_OK on success, or an error code.

swmm_pollutant_id()

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

Get the string identifier of a pollutant by index.

Parameters

engine	Engine handle.
idx	Zero-based pollutant index.

Returns

Null-terminated string owned by the engine, or NULL on error.

swmm_pollutant_index()

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

Look up a pollutant's zero-based index by its string identifier.

Parameters

engine	Engine handle.
id	Null-terminated pollutant identifier.

Returns

Zero-based index, or -1 if not found.

swmm_pollutant_set_co_pollutant()

SWMM_ENGINE_API int swmm_pollutant_set_co_pollutant	(	SWMM_Engine	engine,
		int	idx,
		int	co_idx,
		double	frac )

Set a co-pollutant relationship (concentration = fraction * co-pollutant).

Parameters

engine	Engine handle.
idx	Zero-based pollutant index.
co_idx	Zero-based index of the co-pollutant.
frac	Fraction of the co-pollutant concentration.

Returns

SWMM_OK on success, or an error code.

swmm_pollutant_set_dwf_conc()

SWMM_ENGINE_API int swmm_pollutant_set_dwf_conc	(	SWMM_Engine	engine,
		int	idx,
		double	conc )

Set the default dry weather sanitary flow concentration.

Runtime-settable: the value feeds the dry weather quality inflow term each routing step.

Parameters

engine	Engine handle.
idx	Zero-based pollutant index.
conc	DWF concentration in pollutant units.

Returns

SWMM_OK on success, or an error code.

swmm_pollutant_set_gw_conc()

SWMM_ENGINE_API int swmm_pollutant_set_gw_conc	(	SWMM_Engine	engine,
		int	idx,
		double	conc )

Set the pollutant concentration in groundwater.

Parameters

engine	Engine handle.
idx	Zero-based pollutant index.
conc	Concentration in pollutant units.

Returns

SWMM_OK on success, or an error code.

swmm_pollutant_set_init_conc()

SWMM_ENGINE_API int swmm_pollutant_set_init_conc	(	SWMM_Engine	engine,
		int	idx,
		double	conc )

Set the initial concentration throughout the conveyance system.

Parameters

engine	Engine handle.
idx	Zero-based pollutant index.
conc	Initial concentration in pollutant units.

Returns

SWMM_OK on success, or an error code.

swmm_pollutant_set_kdecay()

SWMM_ENGINE_API int swmm_pollutant_set_kdecay	(	SWMM_Engine	engine,
		int	idx,
		double	k )

Set the first-order decay coefficient for a pollutant.

Parameters

engine	Engine handle.
idx	Zero-based pollutant index.
k	Decay coefficient (1/day).

Returns

SWMM_OK on success, or an error code.

swmm_pollutant_set_mwt()

SWMM_ENGINE_API int swmm_pollutant_set_mwt	(	SWMM_Engine	engine,
		int	idx,
		double	mwt )

Set the molecular weight of a pollutant.

Parameters

engine	Engine handle.
idx	Zero-based pollutant index.
mwt	Molecular weight (g/mol).

Returns

SWMM_OK on success, or an error code.

swmm_pollutant_set_rain_conc()

SWMM_ENGINE_API int swmm_pollutant_set_rain_conc	(	SWMM_Engine	engine,
		int	idx,
		double	conc )

Set the pollutant concentration in rainfall.

Parameters

engine	Engine handle.
idx	Zero-based pollutant index.
conc	Concentration in pollutant units.

Returns

SWMM_OK on success, or an error code.

swmm_pollutant_set_rdii_conc()

SWMM_ENGINE_API int swmm_pollutant_set_rdii_conc	(	SWMM_Engine	engine,
		int	idx,
		double	conc )

Set the RDII (Rainfall-Dependent Infiltration/Inflow) concentration.

Parameters

engine	Engine handle.
idx	Zero-based pollutant index.
conc	RDII concentration in pollutant units.

Returns

SWMM_OK on success, or an error code.

swmm_pollutant_set_snow_only()

SWMM_ENGINE_API int swmm_pollutant_set_snow_only	(	SWMM_Engine	engine,
		int	idx,
		int	flag )

Set whether a pollutant only builds up during snowfall events.

Parameters

engine	Engine handle.
idx	Zero-based pollutant index.
flag	Non-zero for snow-only; zero otherwise.

Returns

SWMM_OK on success, or an error code.

swmm_pollutant_set_units()

SWMM_ENGINE_API int swmm_pollutant_set_units	(	SWMM_Engine	engine,
		int	idx,
		int	units )

Change the concentration units of an existing pollutant.

Inverse of swmm_pollutant_get_units. The units are normally fixed at creation by swmm_pollutant_add; this lets a model builder (e.g. the GUI pollutant editor) correct them afterwards. Editable in the BUILDING or OPENED (pre-start) states only — units define how every stored/reported concentration is interpreted, so a mid-run change has no well-defined meaning and is rejected with SWMM_ERR_LIFECYCLE.

Parameters

engine	Engine handle.
idx	Zero-based pollutant index.
units	Concentration units code (0=MG/L, 1=UG/L, 2=#/L).

Returns

SWMM_OK on success, or an error code.