openswmm_subcatchments.h File Reference

OpenSWMM Engine — Subcatchment C API. More...

#include "openswmm_engine.h"

Include dependency graph for openswmm_subcatchments.h:

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

Go to the source code of this file.

Typedefs
typedef enum SWMM_AquiferParam	SWMM_AquiferParam
	Aquifer parameter codes for swmm_aquifer_get_param / _set_param.

Enumerations
enum	SWMM_AquiferParam {   SWMM_AQUIFER_POROSITY = 0 ,   SWMM_AQUIFER_WILTING_POINT = 1 ,   SWMM_AQUIFER_FIELD_CAPACITY = 2 ,   SWMM_AQUIFER_CONDUCTIVITY = 3 ,   SWMM_AQUIFER_CONDUCT_SLOPE = 4 ,   SWMM_AQUIFER_TENSION_SLOPE = 5 ,   SWMM_AQUIFER_UPPER_EVAP_FRAC = 6 ,   SWMM_AQUIFER_LOWER_EVAP_DEPTH = 7 ,   SWMM_AQUIFER_LOWER_LOSS_COEFF = 8 ,   SWMM_AQUIFER_BOTTOM_ELEV = 9 ,   SWMM_AQUIFER_WATER_TABLE_ELEV = 10 ,   SWMM_AQUIFER_UPPER_MOISTURE = 11 }
	Aquifer parameter codes for swmm_aquifer_get_param / _set_param. More...

Functions
SWMM_ENGINE_API int	swmm_subcatch_count (SWMM_Engine engine)
	Get the total number of subcatchments in the model.
SWMM_ENGINE_API int	swmm_subcatch_index (SWMM_Engine engine, const char *id)
	Look up a subcatchment's zero-based index by its string identifier.
SWMM_ENGINE_API const char *	swmm_subcatch_id (SWMM_Engine engine, int idx)
	Get the string identifier of a subcatchment by index.
SWMM_ENGINE_API int	swmm_subcatch_add (SWMM_Engine engine, const char *id)
	Add a new subcatchment to the model.
SWMM_ENGINE_API int	swmm_subcatch_set_outlet (SWMM_Engine engine, int idx, int node_idx)
	Set the outlet node that receives runoff from this subcatchment.
SWMM_ENGINE_API int	swmm_subcatch_set_area (SWMM_Engine engine, int idx, double area)
	Set the subcatchment area.
SWMM_ENGINE_API int	swmm_subcatch_set_width (SWMM_Engine engine, int idx, double width)
	Set the characteristic overland flow width.
SWMM_ENGINE_API int	swmm_subcatch_set_slope (SWMM_Engine engine, int idx, double slope)
	Set the average surface slope.
SWMM_ENGINE_API int	swmm_subcatch_set_imperv_pct (SWMM_Engine engine, int idx, double pct)
	Set the percentage of impervious area.
SWMM_ENGINE_API int	swmm_subcatch_set_n_imperv (SWMM_Engine engine, int idx, double n)
	Set Manning's n for the impervious area.
SWMM_ENGINE_API int	swmm_subcatch_set_n_perv (SWMM_Engine engine, int idx, double n)
	Set Manning's n for the pervious area.
SWMM_ENGINE_API int	swmm_subcatch_set_ds_imperv (SWMM_Engine engine, int idx, double ds)
	Set the depression storage depth for the impervious area.
SWMM_ENGINE_API int	swmm_subcatch_set_ds_perv (SWMM_Engine engine, int idx, double ds)
	Set the depression storage depth for the pervious area.
SWMM_ENGINE_API int	swmm_subcatch_set_gage (SWMM_Engine engine, int idx, int gage_idx)
	Assign a rain gage to a subcatchment.
SWMM_ENGINE_API int	swmm_subcatch_set_infil_horton (SWMM_Engine engine, int idx, double f0, double fmin, double decay, double dry_time)
	Set Horton infiltration parameters.
SWMM_ENGINE_API int	swmm_subcatch_set_infil_green_ampt (SWMM_Engine engine, int idx, double suction, double conductivity, double initial_deficit)
	Set Green-Ampt infiltration parameters.
SWMM_ENGINE_API int	swmm_subcatch_set_infil_curve_number (SWMM_Engine engine, int idx, double cn)
	Set Curve Number infiltration parameter.
SWMM_ENGINE_API int	swmm_subcatch_set_infil_model (SWMM_Engine engine, int idx, int model)
	Set ONLY the infiltration model code for a subcatchment.
SWMM_ENGINE_API int	swmm_subcatch_get_area (SWMM_Engine engine, int idx, double *area)
	Get the subcatchment area.
SWMM_ENGINE_API int	swmm_subcatch_get_imperv_pct (SWMM_Engine engine, int idx, double *pct)
	Get the percentage of impervious area.
SWMM_ENGINE_API int	swmm_subcatch_get_outlet (SWMM_Engine engine, int idx, int *node_idx)
	Get the outlet node index for a subcatchment.
SWMM_ENGINE_API int	swmm_subcatch_get_width (SWMM_Engine engine, int idx, double *w)
	Get the characteristic overland flow width.
SWMM_ENGINE_API int	swmm_subcatch_get_slope (SWMM_Engine engine, int idx, double *s)
	Get the average surface slope.
SWMM_ENGINE_API int	swmm_subcatch_get_n_imperv (SWMM_Engine engine, int idx, double *n)
	Get Manning's n for the impervious area.
SWMM_ENGINE_API int	swmm_subcatch_get_n_perv (SWMM_Engine engine, int idx, double *n)
	Get Manning's n for the pervious area.
SWMM_ENGINE_API int	swmm_subcatch_get_ds_imperv (SWMM_Engine engine, int idx, double *ds)
	Get the depression storage depth for the impervious area.
SWMM_ENGINE_API int	swmm_subcatch_get_ds_perv (SWMM_Engine engine, int idx, double *ds)
	Get the depression storage depth for the pervious area.
SWMM_ENGINE_API int	swmm_subcatch_get_gage (SWMM_Engine engine, int idx, int *gage_idx)
	Get the rain gage index assigned to a subcatchment.
SWMM_ENGINE_API int	swmm_subcatch_set_outlet_subcatch (SWMM_Engine engine, int idx, int sc_idx)
	Set a subcatchment's outlet to another subcatchment (cascading).
SWMM_ENGINE_API int	swmm_subcatch_get_outlet_subcatch (SWMM_Engine engine, int idx, int *sc_idx)
	Get the downstream subcatchment index (for cascading outlets).
SWMM_ENGINE_API int	swmm_subcatch_get_infil_model (SWMM_Engine engine, int idx, int *model)
	Get the infiltration model type for a subcatchment.
SWMM_ENGINE_API int	swmm_subcatch_get_infil_horton (SWMM_Engine engine, int idx, double *f0, double *fmin, double *decay, double *dry_time)
	Get Horton infiltration parameters for a subcatchment.
SWMM_ENGINE_API int	swmm_subcatch_get_infil_green_ampt (SWMM_Engine engine, int idx, double *suction, double *conductivity, double *deficit)
	Get Green–Ampt infiltration parameters for a subcatchment.
SWMM_ENGINE_API int	swmm_subcatch_get_infil_curve_number (SWMM_Engine engine, int idx, double *cn)
	Get the Curve Number infiltration parameter for a subcatchment.
SWMM_ENGINE_API int	swmm_subcatch_get_stat_precip (SWMM_Engine engine, int idx, double *vol)
	Get the total precipitation volume at a subcatchment.
SWMM_ENGINE_API int	swmm_subcatch_get_stat_runoff_vol (SWMM_Engine engine, int idx, double *vol)
	Get the total runoff volume from a subcatchment.
SWMM_ENGINE_API int	swmm_subcatch_get_stat_max_runoff (SWMM_Engine engine, int idx, double *rate)
	Get the maximum runoff rate from a subcatchment.
SWMM_ENGINE_API int	swmm_subcatch_set_coverage (SWMM_Engine engine, int sc_idx, int lu_idx, double fraction)
	Set the land use coverage fraction for a subcatchment.
SWMM_ENGINE_API int	swmm_subcatch_get_coverage (SWMM_Engine engine, int sc_idx, int lu_idx, double *fraction)
	Get the land use coverage fraction for a subcatchment.
SWMM_ENGINE_API int	swmm_subcatch_get_runoff (SWMM_Engine engine, int idx, double *runoff)
	Get the current runoff rate from a subcatchment.
SWMM_ENGINE_API int	swmm_subcatch_get_groundwater (SWMM_Engine engine, int idx, double *gw_flow)
	Get the current groundwater flow from a subcatchment.
SWMM_ENGINE_API int	swmm_subcatch_get_rainfall (SWMM_Engine engine, int idx, double *rainfall)
	Get the current rainfall intensity at a subcatchment.
SWMM_ENGINE_API int	swmm_subcatch_get_snow_depth (SWMM_Engine engine, int idx, double *depth)
	Get the current snow depth on a subcatchment.
SWMM_ENGINE_API int	swmm_subcatch_get_evap (SWMM_Engine engine, int idx, double *evap)
	Get the current evaporation rate at a subcatchment.
SWMM_ENGINE_API int	swmm_subcatch_set_aquifer (SWMM_Engine engine, int idx, int aquifer_idx)
	Assign the aquifer (by index, -1 = none) used by a subcatchment.
SWMM_ENGINE_API int	swmm_subcatch_get_aquifer (SWMM_Engine engine, int idx, int *aquifer_idx)
	Get the aquifer index assigned to a subcatchment (-1 = none).
SWMM_ENGINE_API int	swmm_subcatch_set_gw_node (SWMM_Engine engine, int idx, int node_idx)
	Set the node (by index, -1 = none) receiving the subcatchment's groundwater flow.
SWMM_ENGINE_API int	swmm_subcatch_get_gw_node (SWMM_Engine engine, int idx, int *node_idx)
	Get the node index receiving the subcatchment's groundwater flow (-1 = none).
SWMM_ENGINE_API int	swmm_subcatch_set_gw_params (SWMM_Engine engine, int idx, double surf_elev, double a1, double b1, double a2, double b2, double a3, double tw, double hstar)
	Set the groundwater flow parameters ([GROUNDWATER] token order).
SWMM_ENGINE_API int	swmm_subcatch_get_gw_params (SWMM_Engine engine, int idx, double *surf_elev, double *a1, double *b1, double *a2, double *b2, double *a3, double *tw, double *hstar)
	Get the groundwater flow parameters (see swmm_subcatch_set_gw_params).
SWMM_ENGINE_API int	swmm_subcatch_set_gw_state (SWMM_Engine engine, int idx, double theta, double lower_depth)
	Set the groundwater state on a subcatchment.
SWMM_ENGINE_API int	swmm_subcatch_get_gw_state (SWMM_Engine engine, int idx, double *theta, double *lower_depth)
	Get the groundwater state on a subcatchment.
SWMM_ENGINE_API int	swmm_subcatch_set_snow_state (SWMM_Engine engine, int idx, int surface, double swe, double fw, double ati, double coldc)
	Set the snow pack state on one snow subarea of a subcatchment.
SWMM_ENGINE_API int	swmm_subcatch_get_snow_state (SWMM_Engine engine, int idx, int surface, double *swe, double *fw, double *ati, double *coldc)
	Get the snow pack state on one snow subarea of a subcatchment.
SWMM_ENGINE_API int	swmm_subcatch_get_infil (SWMM_Engine engine, int idx, double *infil)
	Get the current infiltration rate at a subcatchment.
SWMM_ENGINE_API int	swmm_subcatch_set_rainfall (SWMM_Engine engine, int idx, double rainfall)
	Override rainfall on a subcatchment for the current timestep.
SWMM_ENGINE_API int	swmm_subcatch_get_quality (SWMM_Engine engine, int subcatch_idx, int pollutant_idx, double *conc)
	Get the pollutant concentration in subcatchment runoff.
SWMM_ENGINE_API int	swmm_subcatch_get_runoff_bulk (SWMM_Engine engine, double *buf, int count)
	Get runoff rates for all subcatchments in a single call.
SWMM_ENGINE_API int	swmm_subcatch_get_quality_bulk (SWMM_Engine engine, int pollutant_idx, double *buf, int count)
	Get pollutant concentrations for all subcatchments for one pollutant.
SWMM_ENGINE_API int	swmm_subcatch_get_rainfall_bulk (SWMM_Engine engine, double *buf, int count)
	Get rainfall rates for all subcatchments in a single call.
SWMM_ENGINE_API int	swmm_subcatch_get_evap_bulk (SWMM_Engine engine, double *buf, int count)
	Get evaporation losses for all subcatchments in a single call.
SWMM_ENGINE_API int	swmm_subcatch_get_infil_bulk (SWMM_Engine engine, double *buf, int count)
	Get infiltration losses for all subcatchments in a single call.
SWMM_ENGINE_API int	swmm_subcatch_get_snow_depth_bulk (SWMM_Engine engine, double *buf, int count)
	Get snow depths for all subcatchments in a single call.
SWMM_ENGINE_API int	swmm_subcatch_get_ids_bulk (SWMM_Engine engine, char *buf, int stride, int count)
	Get subcatchment IDs for all subcatchments in a single call (stride-packed UTF-8).
SWMM_ENGINE_API int	swmm_subcatch_get_ponded_quality (SWMM_Engine engine, int subcatch_idx, int pollutant_idx, double *mass)
	Get ponded quality mass for a subcatchment-pollutant pair.
SWMM_ENGINE_API int	swmm_subcatch_set_ponded_quality (SWMM_Engine engine, int subcatch_idx, int pollutant_idx, double mass)
	Set ponded quality mass for a subcatchment-pollutant pair.
SWMM_ENGINE_API int	swmm_subcatch_rename (SWMM_Engine engine, int idx, const char *newId)
	Rename the subcatchment at idx to newId. Returns SWMM_ERR_BADPARAM if newId is null, empty, already in use, or idx is out of range.
SWMM_ENGINE_API int	swmm_aquifer_count (SWMM_Engine engine)
	Get the total number of aquifer definitions in the model.
SWMM_ENGINE_API int	swmm_aquifer_index (SWMM_Engine engine, const char *id)
	Look up an aquifer's zero-based index by its string identifier.
SWMM_ENGINE_API const char *	swmm_aquifer_id (SWMM_Engine engine, int idx)
	Get the string identifier of an aquifer definition by index.
SWMM_ENGINE_API int	swmm_aquifer_add (SWMM_Engine engine, const char *id)
	Add a new aquifer definition with default (zero) parameters.
SWMM_ENGINE_API int	swmm_aquifer_get_param (SWMM_Engine engine, int idx, int param, double *value)
	Get an aquifer parameter (input-file units).
SWMM_ENGINE_API int	swmm_aquifer_set_param (SWMM_Engine engine, int idx, int param, double value)
	Set an aquifer parameter (input-file units).
SWMM_ENGINE_API int	swmm_aquifer_get_evap_pattern (SWMM_Engine engine, int idx, char *buf, int buflen)
	Read the aquifer's upper-zone evaporation pattern name.
SWMM_ENGINE_API int	swmm_aquifer_set_evap_pattern (SWMM_Engine engine, int idx, const char *name)
	Set or clear the aquifer's upper-zone evaporation pattern name.
SWMM_ENGINE_API int	swmm_snowpack_count (SWMM_Engine engine)
	Get the total number of snowpack definitions in the model.
SWMM_ENGINE_API int	swmm_snowpack_index (SWMM_Engine engine, const char *id)
	Look up a snowpack's zero-based index by its string identifier.
SWMM_ENGINE_API const char *	swmm_snowpack_id (SWMM_Engine engine, int idx)
	Get the string identifier of a snowpack definition by index.
SWMM_ENGINE_API int	swmm_snowpack_add (SWMM_Engine engine, const char *id)
	Add a new snowpack definition with default (zero) parameters.
SWMM_ENGINE_API int	swmm_snowpack_set_plowable (SWMM_Engine engine, int idx, double cmin, double cmax, double tbase, double fwfrac, double sd0, double fw0, double last)
	Set the PLOWABLE surface parameters (last = plowable area fraction).
SWMM_ENGINE_API int	swmm_snowpack_get_plowable (SWMM_Engine engine, int idx, double *cmin, double *cmax, double *tbase, double *fwfrac, double *sd0, double *fw0, double *last)
	Read the PLOWABLE surface parameters. Inverse of swmm_snowpack_set_plowable.
SWMM_ENGINE_API int	swmm_snowpack_set_impervious (SWMM_Engine engine, int idx, double cmin, double cmax, double tbase, double fwfrac, double sd0, double fw0, double last)
	Set the IMPERVIOUS surface parameters (last = 100%-cover depth).
SWMM_ENGINE_API int	swmm_snowpack_get_impervious (SWMM_Engine engine, int idx, double *cmin, double *cmax, double *tbase, double *fwfrac, double *sd0, double *fw0, double *last)
	Read the IMPERVIOUS surface parameters. Inverse of swmm_snowpack_set_impervious.
SWMM_ENGINE_API int	swmm_snowpack_set_pervious (SWMM_Engine engine, int idx, double cmin, double cmax, double tbase, double fwfrac, double sd0, double fw0, double last)
	Set the PERVIOUS surface parameters (last = 100%-cover depth).
SWMM_ENGINE_API int	swmm_snowpack_get_pervious (SWMM_Engine engine, int idx, double *cmin, double *cmax, double *tbase, double *fwfrac, double *sd0, double *fw0, double *last)
	Read the PERVIOUS surface parameters. Inverse of swmm_snowpack_set_pervious.
SWMM_ENGINE_API int	swmm_snowpack_set_removal (SWMM_Engine engine, int idx, double dsnow, double fout, double fimp, double fperv, double fimelt, double fsubcatch)
	Set the REMOVAL parameters (snow redistribution at depth dsnow).
SWMM_ENGINE_API int	swmm_snowpack_get_removal (SWMM_Engine engine, int idx, double *dsnow, double *fout, double *fimp, double *fperv, double *fimelt, double *fsubcatch)
	Read the REMOVAL parameters. Inverse of swmm_snowpack_set_removal.
SWMM_ENGINE_API int	swmm_snowpack_set_removal_subcatch (SWMM_Engine engine, int idx, const char *name)
	Set/clear the destination subcatchment for the REMOVAL fsubcatch fraction. Pre-start-only.
SWMM_ENGINE_API int	swmm_snowpack_get_removal_subcatch (SWMM_Engine engine, int idx, char *buf, int buflen)
	Read the REMOVAL destination subcatchment name (empty if none). NUL-terminates, truncates to buflen.
SWMM_ENGINE_API int	swmm_subcatch_get_tag (SWMM_Engine engine, int idx, char *buf, int buflen)
	Read the subcatchment's tag into buf (NUL-terminated, truncated if too small).
SWMM_ENGINE_API int	swmm_subcatch_set_tag (SWMM_Engine engine, int idx, const char *tag)
	Set or clear the subcatchment's tag. Null/empty clears. Persists across rename.
SWMM_ENGINE_API int	swmm_subcatch_set_rain_scale_factor (SWMM_Engine engine, int idx, double factor)
	Set the subcatchment's rainfall scale factor (optional token 9 of [SUBCATCHMENTS]; default 1.0 = no scaling).
SWMM_ENGINE_API int	swmm_subcatch_get_rain_scale_factor (SWMM_Engine engine, int idx, double *factor)
	Get the subcatchment's rainfall scale factor.
SWMM_ENGINE_API int	swmm_subcatch_set_snow_scale_factor (SWMM_Engine engine, int idx, double factor)
	Set the subcatchment's snowfall scale factor (optional token 10 of [SUBCATCHMENTS]; default 1.0 = no scaling).
SWMM_ENGINE_API int	swmm_subcatch_get_snow_scale_factor (SWMM_Engine engine, int idx, double *factor)
	Get the subcatchment's snowfall scale factor.

Detailed Description

OpenSWMM Engine — Subcatchment C API.

Subcatchment add (BUILDING state), property setters, state get, rainfall forcing, bulk access, quality.

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 MIT License

Typedef Documentation

SWMM_AquiferParam

typedef enum SWMM_AquiferParam SWMM_AquiferParam

Aquifer parameter codes for swmm_aquifer_get_param / _set_param.

Values use input-file units (the same columns as the [AQUIFERS] line). The flux-coefficient parameters (CONDUCTIVITY, CONDUCT_SLOPE, TENSION_SLOPE, UPPER_EVAP_FRAC, LOWER_EVAP_DEPTH, LOWER_LOSS_COEFF) are settable both before the simulation starts and while it is running; the structural / initial-condition parameters (POROSITY, WILTING_POINT, FIELD_CAPACITY, BOTTOM_ELEV, WATER_TABLE_ELEV, UPPER_MOISTURE) bound or seed the groundwater state and are pre-start-only.

Enumeration Type Documentation

SWMM_AquiferParam

enum SWMM_AquiferParam

Aquifer parameter codes for swmm_aquifer_get_param / _set_param.

Values use input-file units (the same columns as the [AQUIFERS] line). The flux-coefficient parameters (CONDUCTIVITY, CONDUCT_SLOPE, TENSION_SLOPE, UPPER_EVAP_FRAC, LOWER_EVAP_DEPTH, LOWER_LOSS_COEFF) are settable both before the simulation starts and while it is running; the structural / initial-condition parameters (POROSITY, WILTING_POINT, FIELD_CAPACITY, BOTTOM_ELEV, WATER_TABLE_ELEV, UPPER_MOISTURE) bound or seed the groundwater state and are pre-start-only.

Enumerator
SWMM_AQUIFER_POROSITY
SWMM_AQUIFER_WILTING_POINT
SWMM_AQUIFER_FIELD_CAPACITY
SWMM_AQUIFER_CONDUCTIVITY
SWMM_AQUIFER_CONDUCT_SLOPE
SWMM_AQUIFER_TENSION_SLOPE
SWMM_AQUIFER_UPPER_EVAP_FRAC
SWMM_AQUIFER_LOWER_EVAP_DEPTH
SWMM_AQUIFER_LOWER_LOSS_COEFF
SWMM_AQUIFER_BOTTOM_ELEV
SWMM_AQUIFER_WATER_TABLE_ELEV
SWMM_AQUIFER_UPPER_MOISTURE

Function Documentation

swmm_aquifer_add()

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

Add a new aquifer definition with default (zero) parameters.

Parameters default to 0.0 / empty strings — use the property setters from Slice BP AquiferEditor to configure porosity, conductivity, etc. Lifecycle: BUILDING or OPENED.

Parameters

engine	Engine handle.
id	Unique null-terminated identifier.

Returns

SWMM_OK on success, or an error code.

swmm_aquifer_count()

SWMM_ENGINE_API int swmm_aquifer_count

(

SWMM_Engine

engine

)

Get the total number of aquifer definitions in the model.

Parameters

engine

Engine handle.

Returns

Number of aquifer definitions, or -1 on error.

swmm_aquifer_get_evap_pattern()

SWMM_ENGINE_API int swmm_aquifer_get_evap_pattern	(	SWMM_Engine	engine,
		int	idx,
		char *	buf,
		int	buflen )

Read the aquifer's upper-zone evaporation pattern name.

The optional monthly time pattern ([PATTERNS] MONTHLY) that scales the upper-zone evaporation fraction — the trailing [ETupat] column of the [AQUIFERS] line. The 12 numeric parameters are reached via swmm_aquifer_get_param; this completes the round-trip for the one string-valued column. Writes a NUL-terminated string into buf (empty when no pattern is assigned), truncating if buflen is too small.

Parameters

	engine	Engine handle.
	idx	Zero-based aquifer index.
[out]	buf	Destination buffer for the pattern name.
	buflen	Size of buf in bytes (must be > 0).

Returns

SWMM_OK on success, or an error code.

Here is the call graph for this function:

swmm_aquifer_get_param()

SWMM_ENGINE_API int swmm_aquifer_get_param	(	SWMM_Engine	engine,
		int	idx,
		int	param,
		double *	value )

Get an aquifer parameter (input-file units).

Parameters

engine	Engine handle.
idx	Zero-based aquifer index.
param	A SWMM_AquiferParam code.
value	Receives the parameter value.

Returns

SWMM_OK on success, or an error code.

Here is the call graph for this function:

swmm_aquifer_id()

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

Get the string identifier of an aquifer definition by index.

Parameters

engine	Engine handle.
idx	Zero-based aquifer index.

Returns

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

swmm_aquifer_index()

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

Look up an aquifer's zero-based index by its string identifier.

Parameters

engine	Engine handle.
id	Null-terminated aquifer identifier.

Returns

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

swmm_aquifer_set_evap_pattern()

SWMM_ENGINE_API int swmm_aquifer_set_evap_pattern	(	SWMM_Engine	engine,
		int	idx,
		const char *	name )

Set or clear the aquifer's upper-zone evaporation pattern name.

Inverse of swmm_aquifer_get_evap_pattern. The name is resolved to a [PATTERNS] entry at start(); a null or empty string clears the assignment. Pre-start-only (BUILDING / OPENED): the pattern index is bound when the simulation starts, so a mid-run change returns SWMM_ERR_LIFECYCLE.

Parameters

engine	Engine handle.
idx	Zero-based aquifer index.
name	Pattern name, or null/empty to clear.

Returns

SWMM_OK on success, or an error code.

Here is the call graph for this function:

swmm_aquifer_set_param()

SWMM_ENGINE_API int swmm_aquifer_set_param	(	SWMM_Engine	engine,
		int	idx,
		int	param,
		double	value )

Set an aquifer parameter (input-file units).

Flux-coefficient parameters take effect on the next step when set mid-run (the groundwater solver's per-subcatchment copies are refreshed); structural / initial-condition parameters return SWMM_ERR_LIFECYCLE while the simulation is running.

Parameters

engine	Engine handle.
idx	Zero-based aquifer index.
param	A SWMM_AquiferParam code.
value	New parameter value.

Returns

SWMM_OK on success, or an error code.

Here is the call graph for this function:

swmm_snowpack_add()

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

Add a new snowpack definition with default (zero) parameters.

All three surface arrays (plowable / impervious / pervious) and the removal row are zero-initialised. Use the property setters from Slice BP SnowpackEditor to configure melt coefficients, ATI, negative-melt-ratio, and removal fractions. Lifecycle: BUILDING or OPENED.

Parameters

engine	Engine handle.
id	Unique null-terminated identifier.

Returns

SWMM_OK on success, or an error code.

Here is the call graph for this function:

swmm_snowpack_count()

SWMM_ENGINE_API int swmm_snowpack_count

(

SWMM_Engine

engine

)

Get the total number of snowpack definitions in the model.

Parameters

engine

Engine handle.

Returns

Number of snowpack definitions, or -1 on error.

swmm_snowpack_get_impervious()

SWMM_ENGINE_API int swmm_snowpack_get_impervious	(	SWMM_Engine	engine,
		int	idx,
		double *	cmin,
		double *	cmax,
		double *	tbase,
		double *	fwfrac,
		double *	sd0,
		double *	fw0,
		double *	last )

Read the IMPERVIOUS surface parameters. Inverse of swmm_snowpack_set_impervious.

swmm_snowpack_get_pervious()

SWMM_ENGINE_API int swmm_snowpack_get_pervious	(	SWMM_Engine	engine,
		int	idx,
		double *	cmin,
		double *	cmax,
		double *	tbase,
		double *	fwfrac,
		double *	sd0,
		double *	fw0,
		double *	last )

Read the PERVIOUS surface parameters. Inverse of swmm_snowpack_set_pervious.

swmm_snowpack_get_plowable()

SWMM_ENGINE_API int swmm_snowpack_get_plowable	(	SWMM_Engine	engine,
		int	idx,
		double *	cmin,
		double *	cmax,
		double *	tbase,
		double *	fwfrac,
		double *	sd0,
		double *	fw0,
		double *	last )

Read the PLOWABLE surface parameters. Inverse of swmm_snowpack_set_plowable.

swmm_snowpack_get_removal()

SWMM_ENGINE_API int swmm_snowpack_get_removal	(	SWMM_Engine	engine,
		int	idx,
		double *	dsnow,
		double *	fout,
		double *	fimp,
		double *	fperv,
		double *	fimelt,
		double *	fsubcatch )

Read the REMOVAL parameters. Inverse of swmm_snowpack_set_removal.

Here is the call graph for this function:

swmm_snowpack_get_removal_subcatch()

SWMM_ENGINE_API int swmm_snowpack_get_removal_subcatch	(	SWMM_Engine	engine,
		int	idx,
		char *	buf,
		int	buflen )

Read the REMOVAL destination subcatchment name (empty if none). NUL-terminates, truncates to buflen.

Here is the call graph for this function:

swmm_snowpack_id()

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

Get the string identifier of a snowpack definition by index.

Parameters

engine	Engine handle.
idx	Zero-based snowpack index.

Returns

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

swmm_snowpack_index()

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

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

Parameters

engine	Engine handle.
id	Null-terminated snowpack identifier.

Returns

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

swmm_snowpack_set_impervious()

SWMM_ENGINE_API int swmm_snowpack_set_impervious	(	SWMM_Engine	engine,
		int	idx,
		double	cmin,
		double	cmax,
		double	tbase,
		double	fwfrac,
		double	sd0,
		double	fw0,
		double	last )

Set the IMPERVIOUS surface parameters (last = 100%-cover depth).

swmm_snowpack_set_pervious()

SWMM_ENGINE_API int swmm_snowpack_set_pervious	(	SWMM_Engine	engine,
		int	idx,
		double	cmin,
		double	cmax,
		double	tbase,
		double	fwfrac,
		double	sd0,
		double	fw0,
		double	last )

Set the PERVIOUS surface parameters (last = 100%-cover depth).

swmm_snowpack_set_plowable()

SWMM_ENGINE_API int swmm_snowpack_set_plowable	(	SWMM_Engine	engine,
		int	idx,
		double	cmin,
		double	cmax,
		double	tbase,
		double	fwfrac,
		double	sd0,
		double	fw0,
		double	last )

Set the PLOWABLE surface parameters (last = plowable area fraction).

swmm_snowpack_set_removal()

SWMM_ENGINE_API int swmm_snowpack_set_removal	(	SWMM_Engine	engine,
		int	idx,
		double	dsnow,
		double	fout,
		double	fimp,
		double	fperv,
		double	fimelt,
		double	fsubcatch )

Set the REMOVAL parameters (snow redistribution at depth dsnow).

The six fractions of the [SNOWPACKS] ... REMOVAL line: dsnow (depth at which removal begins, in/mm), then the fractions routed out of the watershed (fout), to impervious area (fimp), to pervious area (fperv), converted to immediate melt (fimelt), and transferred to another subcatchment (fsubcatch). The optional destination subcatchment is named via swmm_snowpack_set_removal_subcatch. Pre-start-only.

Here is the call graph for this function:

swmm_snowpack_set_removal_subcatch()

SWMM_ENGINE_API int swmm_snowpack_set_removal_subcatch	(	SWMM_Engine	engine,
		int	idx,
		const char *	name )

Set/clear the destination subcatchment for the REMOVAL fsubcatch fraction. Pre-start-only.

Here is the call graph for this function:

swmm_subcatch_add()

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

Add a new subcatchment to the model.

The engine must be in SWMM_STATE_BUILDING or SWMM_STATE_OPENED. Returns SWMM_ERR_LIFECYCLE for any other state. After creation, use the property setters to configure area, slope, imperviousness, etc.

Parameters

engine	Engine handle.
id	Unique null-terminated identifier for the new subcatchment.

Returns

SWMM_OK on success, SWMM_ERR_LIFECYCLE if not in an editable state, or another error code.

swmm_subcatch_count()

SWMM_ENGINE_API int swmm_subcatch_count

(

SWMM_Engine

engine

)

Get the total number of subcatchments in the model.

Parameters

engine

Engine handle.

Returns

Number of subcatchments, or -1 on error.

swmm_subcatch_get_aquifer()

SWMM_ENGINE_API int swmm_subcatch_get_aquifer	(	SWMM_Engine	engine,
		int	idx,
		int *	aquifer_idx )

Get the aquifer index assigned to a subcatchment (-1 = none).

swmm_subcatch_get_area()

SWMM_ENGINE_API int swmm_subcatch_get_area	(	SWMM_Engine	engine,
		int	idx,
		double *	area )

Get the subcatchment area.

Parameters

	engine	Engine handle.
	idx	Zero-based subcatchment index.
[out]	area	Receives the area in project area units.

Returns

SWMM_OK on success, or an error code.

swmm_subcatch_get_coverage()

SWMM_ENGINE_API int swmm_subcatch_get_coverage	(	SWMM_Engine	engine,
		int	sc_idx,
		int	lu_idx,
		double *	fraction )

Get the land use coverage fraction for a subcatchment.

Parameters

	engine	Engine handle.
	sc_idx	Zero-based subcatchment index.
	lu_idx	Zero-based land use index.
[out]	fraction	Receives the coverage fraction (0–1).

Returns

SWMM_OK on success, or an error code.

swmm_subcatch_get_ds_imperv()

SWMM_ENGINE_API int swmm_subcatch_get_ds_imperv	(	SWMM_Engine	engine,
		int	idx,
		double *	ds )

Get the depression storage depth for the impervious area.

Parameters

	engine	Engine handle.
	idx	Zero-based subcatchment index.
[out]	ds	Receives the depression storage depth.

Returns

SWMM_OK on success, or an error code.

swmm_subcatch_get_ds_perv()

SWMM_ENGINE_API int swmm_subcatch_get_ds_perv	(	SWMM_Engine	engine,
		int	idx,
		double *	ds )

Get the depression storage depth for the pervious area.

Parameters

	engine	Engine handle.
	idx	Zero-based subcatchment index.
[out]	ds	Receives the depression storage depth.

Returns

SWMM_OK on success, or an error code.

swmm_subcatch_get_evap()

SWMM_ENGINE_API int swmm_subcatch_get_evap	(	SWMM_Engine	engine,
		int	idx,
		double *	evap )

Get the current evaporation rate at a subcatchment.

Parameters

	engine	Engine handle.
	idx	Zero-based subcatchment index.
[out]	evap	Receives the evaporation rate.

Returns

SWMM_OK on success, or an error code.

swmm_subcatch_get_evap_bulk()

SWMM_ENGINE_API int swmm_subcatch_get_evap_bulk	(	SWMM_Engine	engine,
		double *	buf,
		int	count )

Get evaporation losses for all subcatchments in a single call.

Bulk variant of swmm_subcatch_get_evap. Simple SoA copy of the evap_loss column.

Since

6.0.0

swmm_subcatch_get_gage()

SWMM_ENGINE_API int swmm_subcatch_get_gage	(	SWMM_Engine	engine,
		int	idx,
		int *	gage_idx )

Get the rain gage index assigned to a subcatchment.

Parameters

	engine	Engine handle.
	idx	Zero-based subcatchment index.
[out]	gage_idx	Receives the gage index.

Returns

SWMM_OK on success, or an error code.

swmm_subcatch_get_groundwater()

SWMM_ENGINE_API int swmm_subcatch_get_groundwater	(	SWMM_Engine	engine,
		int	idx,
		double *	gw_flow )

Get the current groundwater flow from a subcatchment.

Parameters

	engine	Engine handle.
	idx	Zero-based subcatchment index.
[out]	gw_flow	Receives the groundwater flow in project flow units.

Returns

SWMM_OK on success, or an error code.

swmm_subcatch_get_gw_node()

SWMM_ENGINE_API int swmm_subcatch_get_gw_node	(	SWMM_Engine	engine,
		int	idx,
		int *	node_idx )

Get the node index receiving the subcatchment's groundwater flow (-1 = none).

swmm_subcatch_get_gw_params()

SWMM_ENGINE_API int swmm_subcatch_get_gw_params	(	SWMM_Engine	engine,
		int	idx,
		double *	surf_elev,
		double *	a1,
		double *	b1,
		double *	a2,
		double *	b2,
		double *	a3,
		double *	tw,
		double *	hstar )

Get the groundwater flow parameters (see swmm_subcatch_set_gw_params).

swmm_subcatch_get_gw_state()

SWMM_ENGINE_API int swmm_subcatch_get_gw_state	(	SWMM_Engine	engine,
		int	idx,
		double *	theta,
		double *	lower_depth )

Get the groundwater state on a subcatchment.

Parameters

	engine	Engine handle.
	idx	Subcatchment index (must have groundwater).
[out]	theta	Receives the upper zone moisture content.
[out]	lower_depth	Receives the saturated zone depth (user length units).

Returns

SWMM_OK or error code.

swmm_subcatch_get_ids_bulk()

SWMM_ENGINE_API int swmm_subcatch_get_ids_bulk	(	SWMM_Engine	engine,
		char *	buf,
		int	stride,
		int	count )

Get subcatchment IDs for all subcatchments in a single call (stride-packed UTF-8).

Format identical to swmm_node_get_ids_bulk.

Parameters

	engine	Engine handle.
[out]	buf	Caller-allocated buffer of stride*count bytes.
	stride	Per-ID slot size in bytes (must be > 1).
	count	Number of IDs to read.

Returns

SWMM_OK on success; SWMM_ERR_BADHANDLE if engine is invalid; SWMM_ERR_BADPARAM if buf is NULL, stride < 2, or count <= 0.

See also

swmm_subcatch_id, swmm_node_get_ids_bulk

Since

6.0.0

swmm_subcatch_get_imperv_pct()

SWMM_ENGINE_API int swmm_subcatch_get_imperv_pct	(	SWMM_Engine	engine,
		int	idx,
		double *	pct )

Get the percentage of impervious area.

Parameters

	engine	Engine handle.
	idx	Zero-based subcatchment index.
[out]	pct	Receives the imperviousness percentage (0–100).

Returns

SWMM_OK on success, or an error code.

swmm_subcatch_get_infil()

SWMM_ENGINE_API int swmm_subcatch_get_infil	(	SWMM_Engine	engine,
		int	idx,
		double *	infil )

Get the current infiltration rate at a subcatchment.

Parameters

	engine	Engine handle.
	idx	Zero-based subcatchment index.
[out]	infil	Receives the infiltration rate.

Returns

SWMM_OK on success, or an error code.

swmm_subcatch_get_infil_bulk()

SWMM_ENGINE_API int swmm_subcatch_get_infil_bulk	(	SWMM_Engine	engine,
		double *	buf,
		int	count )

Get infiltration losses for all subcatchments in a single call.

Bulk variant of swmm_subcatch_get_infil. Simple SoA copy of the infil_loss column.

Since

6.0.0

swmm_subcatch_get_infil_curve_number()

SWMM_ENGINE_API int swmm_subcatch_get_infil_curve_number	(	SWMM_Engine	engine,
		int	idx,
		double *	cn )

Get the Curve Number infiltration parameter for a subcatchment.

Parameters

	engine	Engine handle.
	idx	Zero-based subcatchment index.
[out]	cn	Receives the SCS curve number.

Returns

SWMM_OK on success, or an error code.

swmm_subcatch_get_infil_green_ampt()

SWMM_ENGINE_API int swmm_subcatch_get_infil_green_ampt	(	SWMM_Engine	engine,
		int	idx,
		double *	suction,
		double *	conductivity,
		double *	deficit )

Get Green–Ampt infiltration parameters for a subcatchment.

Parameters

	engine	Engine handle.
	idx	Zero-based subcatchment index.
[out]	suction	Receives the soil capillary suction head.
[out]	conductivity	Receives the saturated hydraulic conductivity.
[out]	deficit	Receives the initial moisture deficit (fraction).

Returns

SWMM_OK on success, or an error code.

swmm_subcatch_get_infil_horton()

SWMM_ENGINE_API int swmm_subcatch_get_infil_horton	(	SWMM_Engine	engine,
		int	idx,
		double *	f0,
		double *	fmin,
		double *	decay,
		double *	dry_time )

Get Horton infiltration parameters for a subcatchment.

Parameters

	engine	Engine handle.
	idx	Zero-based subcatchment index.
[out]	f0	Receives the maximum infiltration rate.
[out]	fmin	Receives the minimum infiltration rate.
[out]	decay	Receives the decay constant (1/hr).
[out]	dry_time	Receives the time to fully dry (hours).

Returns

SWMM_OK on success, or an error code.

swmm_subcatch_get_infil_model()

SWMM_ENGINE_API int swmm_subcatch_get_infil_model	(	SWMM_Engine	engine,
		int	idx,
		int *	model )

Get the infiltration model type for a subcatchment.

Returns an integer code: 0=HORTON, 1=MOD_HORTON, 2=GREEN_AMPT, 3=MOD_GREEN_AMPT, 4=CURVE_NUMBER.

Parameters

	engine	Engine handle.
	idx	Zero-based subcatchment index.
[out]	model	Receives the infiltration model code.

Returns

SWMM_OK on success, or an error code.

swmm_subcatch_get_n_imperv()

SWMM_ENGINE_API int swmm_subcatch_get_n_imperv	(	SWMM_Engine	engine,
		int	idx,
		double *	n )

Get Manning's n for the impervious area.

Parameters

	engine	Engine handle.
	idx	Zero-based subcatchment index.
[out]	n	Receives Manning's n.

Returns

SWMM_OK on success, or an error code.

swmm_subcatch_get_n_perv()

SWMM_ENGINE_API int swmm_subcatch_get_n_perv	(	SWMM_Engine	engine,
		int	idx,
		double *	n )

Get Manning's n for the pervious area.

Parameters

	engine	Engine handle.
	idx	Zero-based subcatchment index.
[out]	n	Receives Manning's n.

Returns

SWMM_OK on success, or an error code.

swmm_subcatch_get_outlet()

SWMM_ENGINE_API int swmm_subcatch_get_outlet	(	SWMM_Engine	engine,
		int	idx,
		int *	node_idx )

Get the outlet node index for a subcatchment.

Parameters

	engine	Engine handle.
	idx	Zero-based subcatchment index.
[out]	node_idx	Receives the outlet node index.

Returns

SWMM_OK on success, or an error code.

swmm_subcatch_get_outlet_subcatch()

SWMM_ENGINE_API int swmm_subcatch_get_outlet_subcatch	(	SWMM_Engine	engine,
		int	idx,
		int *	sc_idx )

Get the downstream subcatchment index (for cascading outlets).

Parameters

	engine	Engine handle.
	idx	Zero-based subcatchment index.
[out]	sc_idx	Receives the downstream subcatchment index, or -1 if none.

Returns

SWMM_OK on success, or an error code.

swmm_subcatch_get_ponded_quality()

SWMM_ENGINE_API int swmm_subcatch_get_ponded_quality	(	SWMM_Engine	engine,
		int	subcatch_idx,
		int	pollutant_idx,
		double *	mass )

Get ponded quality mass for a subcatchment-pollutant pair.

swmm_subcatch_get_quality()

SWMM_ENGINE_API int swmm_subcatch_get_quality	(	SWMM_Engine	engine,
		int	subcatch_idx,
		int	pollutant_idx,
		double *	conc )

Get the pollutant concentration in subcatchment runoff.

Parameters

	engine	Engine handle.
	subcatch_idx	Zero-based subcatchment index.
	pollutant_idx	Zero-based pollutant index.
[out]	conc	Receives the concentration in pollutant units.

Returns

SWMM_OK on success, or an error code.

swmm_subcatch_get_quality_bulk()

SWMM_ENGINE_API int swmm_subcatch_get_quality_bulk	(	SWMM_Engine	engine,
		int	pollutant_idx,
		double *	buf,
		int	count )

Get pollutant concentrations for all subcatchments for one pollutant.

Parameters

	engine	Engine handle.
	pollutant_idx	Zero-based pollutant index.
[out]	buf	Caller-allocated buffer of at least count doubles.
	count	Number of elements (should equal swmm_subcatch_count()).

Returns

SWMM_OK on success, or an error code.

swmm_subcatch_get_rain_scale_factor()

SWMM_ENGINE_API int swmm_subcatch_get_rain_scale_factor	(	SWMM_Engine	engine,
		int	idx,
		double *	factor )

Get the subcatchment's rainfall scale factor.

See also

swmm_subcatch_set_rain_scale_factor

Here is the call graph for this function:

swmm_subcatch_get_rainfall()

SWMM_ENGINE_API int swmm_subcatch_get_rainfall	(	SWMM_Engine	engine,
		int	idx,
		double *	rainfall )

Get the current rainfall intensity at a subcatchment.

Parameters

	engine	Engine handle.
	idx	Zero-based subcatchment index.
[out]	rainfall	Receives the rainfall in project rate units.

Returns

SWMM_OK on success, or an error code.

swmm_subcatch_get_rainfall_bulk()

SWMM_ENGINE_API int swmm_subcatch_get_rainfall_bulk	(	SWMM_Engine	engine,
		double *	buf,
		int	count )

Get rainfall rates for all subcatchments in a single call.

Bulk variant of swmm_subcatch_get_rainfall. Simple SoA copy.

Since

6.0.0

swmm_subcatch_get_runoff()

SWMM_ENGINE_API int swmm_subcatch_get_runoff	(	SWMM_Engine	engine,
		int	idx,
		double *	runoff )

Get the current runoff rate from a subcatchment.

Parameters

	engine	Engine handle.
	idx	Zero-based subcatchment index.
[out]	runoff	Receives the runoff rate in project flow units.

Returns

SWMM_OK on success, or an error code.

swmm_subcatch_get_runoff_bulk()

SWMM_ENGINE_API int swmm_subcatch_get_runoff_bulk	(	SWMM_Engine	engine,
		double *	buf,
		int	count )

Get runoff rates for all subcatchments in a single call.

Parameters

	engine	Engine handle.
[out]	buf	Caller-allocated buffer of at least count doubles.
	count	Number of elements (should equal swmm_subcatch_count()).

Returns

SWMM_OK on success, or an error code.

swmm_subcatch_get_slope()

SWMM_ENGINE_API int swmm_subcatch_get_slope	(	SWMM_Engine	engine,
		int	idx,
		double *	s )

Get the average surface slope.

Parameters

	engine	Engine handle.
	idx	Zero-based subcatchment index.
[out]	s	Receives the slope percentage.

Returns

SWMM_OK on success, or an error code.

swmm_subcatch_get_snow_depth()

SWMM_ENGINE_API int swmm_subcatch_get_snow_depth	(	SWMM_Engine	engine,
		int	idx,
		double *	depth )

Get the current snow depth on a subcatchment.

Parameters

	engine	Engine handle.
	idx	Zero-based subcatchment index.
[out]	depth	Receives the snow depth in project length units.

Returns

SWMM_OK on success, or an error code.

swmm_subcatch_get_snow_depth_bulk()

SWMM_ENGINE_API int swmm_subcatch_get_snow_depth_bulk	(	SWMM_Engine	engine,
		double *	buf,
		int	count )

Get snow depths for all subcatchments in a single call.

Bulk variant of swmm_subcatch_get_snow_depth. Snow state currently lives in the SnowSolver, not SubcatchData; like the scalar accessor this returns zeros for every entry pending full snow-state integration (see plan Appendix A).

Since

6.0.0

swmm_subcatch_get_snow_scale_factor()

SWMM_ENGINE_API int swmm_subcatch_get_snow_scale_factor	(	SWMM_Engine	engine,
		int	idx,
		double *	factor )

Get the subcatchment's snowfall scale factor.

See also

swmm_subcatch_set_snow_scale_factor

Here is the call graph for this function:

swmm_subcatch_get_snow_state()

SWMM_ENGINE_API int swmm_subcatch_get_snow_state	(	SWMM_Engine	engine,
		int	idx,
		int	surface,
		double *	swe,
		double *	fw,
		double *	ati,
		double *	coldc )

Get the snow pack state on one snow subarea of a subcatchment.

Parameters

	engine	Engine handle.
	idx	Subcatchment index (must have a snow pack).
	surface	Snow subarea: 0 plowable, 1 impervious, 2 pervious.
[out]	swe	Receives SWE (user depth units); may be NULL.
[out]	fw	Receives free water (user depth units); may be NULL.
[out]	ati	Receives ATI (user temperature units); may be NULL.
[out]	coldc	Receives cold content (user depth units); may be NULL.

Returns

SWMM_OK or error code.

Here is the call graph for this function:

swmm_subcatch_get_stat_max_runoff()

SWMM_ENGINE_API int swmm_subcatch_get_stat_max_runoff	(	SWMM_Engine	engine,
		int	idx,
		double *	rate )

Get the maximum runoff rate from a subcatchment.

Parameters

	engine	Engine handle.
	idx	Zero-based subcatchment index.
[out]	rate	Receives the maximum runoff rate in project flow units.

Returns

SWMM_OK on success, or an error code.

swmm_subcatch_get_stat_precip()

SWMM_ENGINE_API int swmm_subcatch_get_stat_precip	(	SWMM_Engine	engine,
		int	idx,
		double *	vol )

Get the total precipitation volume at a subcatchment.

Parameters

	engine	Engine handle (ENDED or RUNNING state).
	idx	Zero-based subcatchment index.
[out]	vol	Receives the precipitation volume in project volume units.

Returns

SWMM_OK on success, or an error code.

swmm_subcatch_get_stat_runoff_vol()

SWMM_ENGINE_API int swmm_subcatch_get_stat_runoff_vol	(	SWMM_Engine	engine,
		int	idx,
		double *	vol )

Get the total runoff volume from a subcatchment.

Parameters

	engine	Engine handle.
	idx	Zero-based subcatchment index.
[out]	vol	Receives the runoff volume in project volume units.

Returns

SWMM_OK on success, or an error code.

swmm_subcatch_get_tag()

SWMM_ENGINE_API int swmm_subcatch_get_tag	(	SWMM_Engine	engine,
		int	idx,
		char *	buf,
		int	buflen )

Read the subcatchment's tag into buf (NUL-terminated, truncated if too small).

swmm_subcatch_get_width()

SWMM_ENGINE_API int swmm_subcatch_get_width	(	SWMM_Engine	engine,
		int	idx,
		double *	w )

Get the characteristic overland flow width.

Parameters

	engine	Engine handle.
	idx	Zero-based subcatchment index.
[out]	w	Receives the width in project length units.

Returns

SWMM_OK on success, or an error code.

swmm_subcatch_id()

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

Get the string identifier of a subcatchment by index.

Parameters

engine	Engine handle.
idx	Zero-based subcatchment index.

Returns

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

swmm_subcatch_index()

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

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

Parameters

engine	Engine handle.
id	Null-terminated subcatchment identifier.

Returns

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

swmm_subcatch_rename()

SWMM_ENGINE_API int swmm_subcatch_rename	(	SWMM_Engine	engine,
		int	idx,
		const char *	newId )

Rename the subcatchment at idx to newId. Returns SWMM_ERR_BADPARAM if newId is null, empty, already in use, or idx is out of range.

swmm_subcatch_set_aquifer()

SWMM_ENGINE_API int swmm_subcatch_set_aquifer	(	SWMM_Engine	engine,
		int	idx,
		int	aquifer_idx )

Assign the aquifer (by index, -1 = none) used by a subcatchment.

swmm_subcatch_set_area()

SWMM_ENGINE_API int swmm_subcatch_set_area	(	SWMM_Engine	engine,
		int	idx,
		double	area )

Set the subcatchment area.

Parameters

engine	Engine handle.
idx	Zero-based subcatchment index.
area	Area in project area units (acres or hectares).

Returns

SWMM_OK on success, or an error code.

swmm_subcatch_set_coverage()

SWMM_ENGINE_API int swmm_subcatch_set_coverage	(	SWMM_Engine	engine,
		int	sc_idx,
		int	lu_idx,
		double	fraction )

Set the land use coverage fraction for a subcatchment.

Assigns what fraction of a subcatchment's area is covered by a particular land use category (for buildup/washoff modeling).

Parameters

engine	Engine handle.
sc_idx	Zero-based subcatchment index.
lu_idx	Zero-based land use index.
fraction	Coverage fraction (0–1).

Returns

SWMM_OK on success, or an error code.

swmm_subcatch_set_ds_imperv()

SWMM_ENGINE_API int swmm_subcatch_set_ds_imperv	(	SWMM_Engine	engine,
		int	idx,
		double	ds )

Set the depression storage depth for the impervious area.

Parameters

engine	Engine handle.
idx	Zero-based subcatchment index.
ds	Depression storage in project length units.

Returns

SWMM_OK on success, or an error code.

swmm_subcatch_set_ds_perv()

SWMM_ENGINE_API int swmm_subcatch_set_ds_perv	(	SWMM_Engine	engine,
		int	idx,
		double	ds )

Set the depression storage depth for the pervious area.

Parameters

engine	Engine handle.
idx	Zero-based subcatchment index.
ds	Depression storage in project length units.

Returns

SWMM_OK on success, or an error code.

swmm_subcatch_set_gage()

SWMM_ENGINE_API int swmm_subcatch_set_gage	(	SWMM_Engine	engine,
		int	idx,
		int	gage_idx )

Assign a rain gage to a subcatchment.

Parameters

engine	Engine handle.
idx	Zero-based subcatchment index.
gage_idx	Zero-based rain gage index.

Returns

SWMM_OK on success, or an error code.

swmm_subcatch_set_gw_node()

SWMM_ENGINE_API int swmm_subcatch_set_gw_node	(	SWMM_Engine	engine,
		int	idx,
		int	node_idx )

Set the node (by index, -1 = none) receiving the subcatchment's groundwater flow.

swmm_subcatch_set_gw_params()

SWMM_ENGINE_API int swmm_subcatch_set_gw_params	(	SWMM_Engine	engine,
		int	idx,
		double	surf_elev,
		double	a1,
		double	b1,
		double	a2,
		double	b2,
		double	a3,
		double	tw,
		double	hstar )

Set the groundwater flow parameters ([GROUNDWATER] token order).

Parameters

surf_elev	Surface elevation (SurfEl).
a1,b1	Groundwater outflow coefficient & exponent.
a2,b2	Surface-water outflow coefficient & exponent.
a3	Surface/groundwater interaction coefficient.
tw	Threshold groundwater table elevation (Twgr).
hstar	Water-table elevation at which lateral GW flow ceases (Hstar).

Returns

SWMM_OK or error code.

swmm_subcatch_set_gw_state()

SWMM_ENGINE_API int swmm_subcatch_set_gw_state	(	SWMM_Engine	engine,
		int	idx,
		double	theta,
		double	lower_depth )

Set the groundwater state on a subcatchment.

State injection for data assimilation / external coupling. Pass a negative value to leave that component unchanged. Note that mass balance reports will reflect the storage discontinuity, mirroring hotstart loading.

Parameters

engine	Engine handle.
idx	Subcatchment index (must have groundwater).
theta	Upper zone moisture content (0..porosity), or < 0 to keep.
lower_depth	Saturated zone depth above aquifer bottom in user length units (ft US, m SI), or < 0 to keep.

Returns

SWMM_OK or error code.

swmm_subcatch_set_imperv_pct()

SWMM_ENGINE_API int swmm_subcatch_set_imperv_pct	(	SWMM_Engine	engine,
		int	idx,
		double	pct )

Set the percentage of impervious area.

Parameters

engine	Engine handle.
idx	Zero-based subcatchment index.
pct	Imperviousness as a percentage (0–100).

Returns

SWMM_OK on success, or an error code.

swmm_subcatch_set_infil_curve_number()

SWMM_ENGINE_API int swmm_subcatch_set_infil_curve_number	(	SWMM_Engine	engine,
		int	idx,
		double	cn )

Set Curve Number infiltration parameter.

swmm_subcatch_set_infil_green_ampt()

SWMM_ENGINE_API int swmm_subcatch_set_infil_green_ampt	(	SWMM_Engine	engine,
		int	idx,
		double	suction,
		double	conductivity,
		double	initial_deficit )

Set Green-Ampt infiltration parameters.

swmm_subcatch_set_infil_horton()

SWMM_ENGINE_API int swmm_subcatch_set_infil_horton	(	SWMM_Engine	engine,
		int	idx,
		double	f0,
		double	fmin,
		double	decay,
		double	dry_time )

Set Horton infiltration parameters.

swmm_subcatch_set_infil_model()

SWMM_ENGINE_API int swmm_subcatch_set_infil_model	(	SWMM_Engine	engine,
		int	idx,
		int	model )

Set ONLY the infiltration model code for a subcatchment.

model: 0=HORTON, 1=MOD_HORTON, 2=GREEN_AMPT, 3=MOD_GREEN_AMPT, 4=CURVE_NUMBER. The per-model parameters are positionally overloaded, so after switching the model code callers should set the matching parameters via swmm_subcatch_set_infil_horton / _green_ampt / _curve_number.

Parameters

engine	Engine handle.
idx	Zero-based subcatchment index.
model	Infiltration model code (0..4).

Returns

SWMM_OK, or SWMM_ERR_BADPARAM if model is out of range.

swmm_subcatch_set_n_imperv()

SWMM_ENGINE_API int swmm_subcatch_set_n_imperv	(	SWMM_Engine	engine,
		int	idx,
		double	n )

Set Manning's n for the impervious area.

Parameters

engine	Engine handle.
idx	Zero-based subcatchment index.
n	Manning's roughness coefficient.

Returns

SWMM_OK on success, or an error code.

swmm_subcatch_set_n_perv()

SWMM_ENGINE_API int swmm_subcatch_set_n_perv	(	SWMM_Engine	engine,
		int	idx,
		double	n )

Set Manning's n for the pervious area.

Parameters

engine	Engine handle.
idx	Zero-based subcatchment index.
n	Manning's roughness coefficient.

Returns

SWMM_OK on success, or an error code.

swmm_subcatch_set_outlet()

SWMM_ENGINE_API int swmm_subcatch_set_outlet	(	SWMM_Engine	engine,
		int	idx,
		int	node_idx )

Set the outlet node that receives runoff from this subcatchment.

Parameters

engine	Engine handle.
idx	Zero-based subcatchment index.
node_idx	Zero-based node index of the receiving node.

Returns

SWMM_OK on success, or an error code.

swmm_subcatch_set_outlet_subcatch()

SWMM_ENGINE_API int swmm_subcatch_set_outlet_subcatch	(	SWMM_Engine	engine,
		int	idx,
		int	sc_idx )

Set a subcatchment's outlet to another subcatchment (cascading).

When a subcatchment drains to another subcatchment instead of directly to a node, use this function. Mutually exclusive with swmm_subcatch_set_outlet().

Parameters

engine	Engine handle.
idx	Zero-based subcatchment index.
sc_idx	Zero-based index of the receiving subcatchment.

Returns

SWMM_OK on success, or an error code.

swmm_subcatch_set_ponded_quality()

SWMM_ENGINE_API int swmm_subcatch_set_ponded_quality	(	SWMM_Engine	engine,
		int	subcatch_idx,
		int	pollutant_idx,
		double	mass )

Set ponded quality mass for a subcatchment-pollutant pair.

swmm_subcatch_set_rain_scale_factor()

SWMM_ENGINE_API int swmm_subcatch_set_rain_scale_factor	(	SWMM_Engine	engine,
		int	idx,
		double	factor )

Set the subcatchment's rainfall scale factor (optional token 9 of [SUBCATCHMENTS]; default 1.0 = no scaling).

Multiplies the gage-derived rainfall for this subcatchment only, composing multiplicatively with the gage's own scale factor: rainfall = gage_rain * gage_scale_factor * rain_scale_factor API/forcing rainfall overrides are NOT scaled by this.

Settable mid-run (no geometry lock), so it can be driven by a calibration or RTC loop.

Parameters

factor

Must be > 0.0.

Returns

SWMM_OK, or SWMM_ERR_BADPARAM if factor <= 0.0.

Here is the call graph for this function:

swmm_subcatch_set_rainfall()

SWMM_ENGINE_API int swmm_subcatch_set_rainfall	(	SWMM_Engine	engine,
		int	idx,
		double	rainfall )

Override rainfall on a subcatchment for the current timestep.

Overrides the gage-driven rainfall for this subcatchment only. Value is applied for the current timestep; call again each step to sustain. Pass a negative value to revert to gage-driven.

swmm_subcatch_set_slope()

SWMM_ENGINE_API int swmm_subcatch_set_slope	(	SWMM_Engine	engine,
		int	idx,
		double	slope )

Set the average surface slope.

Parameters

engine	Engine handle.
idx	Zero-based subcatchment index.
slope	Slope as a percentage (e.g., 2.0 = 2%).

Returns

SWMM_OK on success, or an error code.

swmm_subcatch_set_snow_scale_factor()

SWMM_ENGINE_API int swmm_subcatch_set_snow_scale_factor	(	SWMM_Engine	engine,
		int	idx,
		double	factor )

Set the subcatchment's snowfall scale factor (optional token 10 of [SUBCATCHMENTS]; default 1.0 = no scaling).

Composes multiplicatively with the gage snow catch factor (SCF): snowfall = gage_rain * gage_scale_factor * gage_snow_factor

• snow_scale_factor Distinct from the gage SCF: SCF corrects a physical gage's snow-catch deficiency, while this represents spatial variation across the catchment (orographic gradient, canopy, drifting).

Settable mid-run (no geometry lock).

Parameters

factor

Must be > 0.0.

Returns

SWMM_OK, or SWMM_ERR_BADPARAM if factor <= 0.0.

Here is the call graph for this function:

swmm_subcatch_set_snow_state()

SWMM_ENGINE_API int swmm_subcatch_set_snow_state	(	SWMM_Engine	engine,
		int	idx,
		int	surface,
		double	swe,
		double	fw,
		double	ati,
		double	coldc )

Set the snow pack state on one snow subarea of a subcatchment.

State injection for data assimilation (e.g. observed SWE). Pass a negative value to leave that component unchanged.

Parameters

engine	Engine handle.
idx	Subcatchment index (must have a snow pack).
surface	Snow subarea: 0 plowable, 1 impervious, 2 pervious.
swe	Snow water equivalent in user depth units (in US, mm SI), or < 0 to keep.
fw	Free water in user depth units, or < 0 to keep.
ati	Antecedent temperature index (deg F US, deg C SI); pass <= -999 to keep (negative temperatures are valid).
coldc	Cold content in user depth units of melt equivalent, or < 0 to keep.

Returns

SWMM_OK or error code.

Here is the call graph for this function:

swmm_subcatch_set_tag()

SWMM_ENGINE_API int swmm_subcatch_set_tag	(	SWMM_Engine	engine,
		int	idx,
		const char *	tag )

Set or clear the subcatchment's tag. Null/empty clears. Persists across rename.

swmm_subcatch_set_width()

SWMM_ENGINE_API int swmm_subcatch_set_width	(	SWMM_Engine	engine,
		int	idx,
		double	width )

Set the characteristic overland flow width.

Parameters

engine	Engine handle.
idx	Zero-based subcatchment index.
width	Width in project length units.

Returns

SWMM_OK on success, or an error code.