openswmm_subcatchments_impl.cpp File Reference

C API implementation — subcatchment identity, creation, properties, state, bulk. More...

#include "openswmm_api_common.hpp"
#include "../../../include/openswmm/engine/openswmm_subcatchments.h"
#include <algorithm>
#include <cstring>
#include <string>

Include dependency graph for openswmm_subcatchments_impl.cpp:

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_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_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_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_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_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.

Detailed Description

C API implementation — subcatchment identity, creation, properties, state, bulk.

See also

include/openswmm/engine/openswmm_subcatchments.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_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_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_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.

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_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_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_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_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_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_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_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_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_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_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_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.