C API implementation — transects, streets, inlets, LID controls, LID usage. More...

#include "openswmm_api_common.hpp"
#include "../../../include/openswmm/engine/openswmm_infrastructure.h"
#include <cctype>
#include <string>

Include dependency graph for openswmm_infrastructure_impl.cpp:

Functions
SWMM_ENGINE_API int	swmm_transect_add (SWMM_Engine engine, const char *id)
	Add a new transect for irregular cross-sections.

SWMM_ENGINE_API int	swmm_transect_set_roughness (SWMM_Engine engine, int idx, double n_left, double n_right, double n_channel)
	Set Manning's roughness for left overbank, right overbank, and channel.

SWMM_ENGINE_API int	swmm_transect_add_station (SWMM_Engine engine, int idx, double station, double elevation)
	Add a station–elevation data point to a transect.

SWMM_ENGINE_API int	swmm_transect_count (SWMM_Engine engine)
	Get the total number of transects in the model.

SWMM_ENGINE_API int	swmm_transect_index (SWMM_Engine engine, const char *id)
	Look up a transect's zero-based index by its string identifier.

SWMM_ENGINE_API const char *	swmm_transect_id (SWMM_Engine engine, int idx)
	Get the string identifier of a transect by index.

SWMM_ENGINE_API int	swmm_transect_get_roughness (SWMM_Engine engine, int idx, double n_left, double n_right, double *n_channel)
	Get the Manning's roughness values for a transect.

SWMM_ENGINE_API int	swmm_transect_set_bank_stations (SWMM_Engine engine, int idx, double x_left, double x_right)
	Set the left and right bank stations for a transect.

SWMM_ENGINE_API int	swmm_transect_get_bank_stations (SWMM_Engine engine, int idx, double x_left, double x_right)
	Get the left and right bank stations for a transect.

SWMM_ENGINE_API int	swmm_transect_set_encroachment_stations (SWMM_Engine engine, int idx, double x_left, double x_right)
	Set the left and right encroachment stations for a transect (BQ-TR-02).

SWMM_ENGINE_API int	swmm_transect_get_encroachment_stations (SWMM_Engine engine, int idx, double x_left, double x_right)
	Get the left and right encroachment stations for a transect (BQ-TR-02).

SWMM_ENGINE_API int	swmm_transect_set_modifiers (SWMM_Engine engine, int idx, double x_factor, double y_factor, double length_factor)
	Set the station, elevation, and meander modifiers for a transect.

SWMM_ENGINE_API int	swmm_transect_get_modifiers (SWMM_Engine engine, int idx, double x_factor, double y_factor, double *length_factor)
	Get the station, elevation, and meander modifiers for a transect.

SWMM_ENGINE_API int	swmm_transect_set_comments (SWMM_Engine engine, int idx, const char *text)
	Set the free-form comments / description for a transect.

SWMM_ENGINE_API int	swmm_transect_get_comments (SWMM_Engine engine, int idx, char *buf, int buflen)
	Get the free-form comments / description for a transect.

SWMM_ENGINE_API int	swmm_transect_get_station_count (SWMM_Engine engine, int idx)
	Get the number of station–elevation points stored for a transect.

SWMM_ENGINE_API int	swmm_transect_get_station (SWMM_Engine engine, int idx, int station_idx, double station, double elevation)
	Get a single station–elevation pair from a transect.

SWMM_ENGINE_API int	swmm_transect_clear_stations (SWMM_Engine engine, int idx)
	Remove all station–elevation pairs from a transect.

SWMM_ENGINE_API int	swmm_transect_rename (SWMM_Engine engine, int idx, const char *new_id)
	Rename an existing transect.

SWMM_ENGINE_API int	swmm_transect_remove (SWMM_Engine engine, int idx)
	Remove a transect by index.

SWMM_ENGINE_API int	swmm_street_add (SWMM_Engine engine, const char *id)
	Add a new street cross-section definition.

SWMM_ENGINE_API int	swmm_street_set_params (SWMM_Engine engine, int idx, double t_crown, double h_curb, double sx, double n_road, double gutter_depres, double gutter_width, int sides, double back_width, double back_slope, double back_n)
	Set the geometric parameters for a street cross-section.

SWMM_ENGINE_API int	swmm_street_count (SWMM_Engine engine)
	Get the total number of street definitions in the model.

SWMM_ENGINE_API int	swmm_street_index (SWMM_Engine engine, const char *id)
	Look up a street's zero-based index by its string identifier.

SWMM_ENGINE_API const char *	swmm_street_id (SWMM_Engine engine, int idx)
	Get the string identifier of a street by index.

SWMM_ENGINE_API int	swmm_street_get_params (SWMM_Engine engine, int idx, double t_crown, double h_curb, double sx, double n_road, double gutter_depres, double gutter_width, int sides, double back_width, double back_slope, double back_n)
	Read back the geometric parameters of a street cross-section.

SWMM_ENGINE_API int	swmm_inlet_add (SWMM_Engine engine, const char id, const char type)
	Add a new inlet definition.

SWMM_ENGINE_API int	swmm_inlet_set_params (SWMM_Engine engine, int idx, double length, double width, const char *grate_type, double open_area, double splash_veloc)
	Set the geometric parameters for an inlet.

SWMM_ENGINE_API int	swmm_inlet_count (SWMM_Engine engine)
	Get the total number of inlet definitions in the model.

SWMM_ENGINE_API int	swmm_inlet_index (SWMM_Engine engine, const char *id)
	Look up an inlet's zero-based index by its string identifier.

SWMM_ENGINE_API const char *	swmm_inlet_id (SWMM_Engine engine, int idx)
	Get the string identifier of an inlet by index.

SWMM_ENGINE_API int	swmm_inlet_get_params (SWMM_Engine engine, int idx, double length, double width, char grate_type, int grate_buflen, double open_area, double *splash_veloc)
	Read an inlet's geometric parameters. Inverse of swmm_inlet_set_params.

SWMM_ENGINE_API int	swmm_inlet_get_type (SWMM_Engine engine, int idx, char *buf, int buflen)
	Read an inlet's type string (the value passed to swmm_inlet_add).

SWMM_ENGINE_API int	swmm_lid_add (SWMM_Engine engine, const char *id, int type)
	Add a new LID (Low Impact Development) control.

SWMM_ENGINE_API int	swmm_lid_set_surface (SWMM_Engine engine, int idx, double storage, double roughness, double slope)
	Set the surface layer properties for a LID control.

SWMM_ENGINE_API int	swmm_lid_set_soil (SWMM_Engine engine, int idx, double thick, double porosity, double fc, double wp, double ksat, double kslope)
	Set the soil layer properties for a LID control.

SWMM_ENGINE_API int	swmm_lid_set_storage (SWMM_Engine engine, int idx, double thick, double void_frac, double ksat)
	Set the storage layer properties for a LID control.

SWMM_ENGINE_API int	swmm_lid_set_drain (SWMM_Engine engine, int idx, double coeff, double expon, double offset)
	Set the underdrain properties for a LID control.

SWMM_ENGINE_API int	swmm_lid_set_pavement (SWMM_Engine engine, int idx, double thick, double void_ratio, double frac_imperv, double ksat, double clog_factor, double regen_days)
	Set the porous-pavement layer properties for a LID control.

SWMM_ENGINE_API int	swmm_lid_set_drainmat (SWMM_Engine engine, int idx, double thick, double void_frac, double roughness)
	Set the drainage-mat layer properties for a LID control.

SWMM_ENGINE_API int	swmm_lid_count (SWMM_Engine engine)
	Get the total number of LID controls in the model.

SWMM_ENGINE_API int	swmm_lid_index (SWMM_Engine engine, const char *id)
	Look up a LID control's zero-based index by its string identifier.

SWMM_ENGINE_API const char *	swmm_lid_id (SWMM_Engine engine, int idx)
	Get the string identifier of a LID control by index.

SWMM_ENGINE_API int	swmm_lid_get_type (SWMM_Engine engine, int idx, int *type)
	Read a LID control's type code. Inverse of the `type` argument to swmm_lid_add.

SWMM_ENGINE_API int	swmm_lid_get_surface (SWMM_Engine engine, int idx, double storage, double roughness, double *slope)
	Read the surface layer properties. Inverse of swmm_lid_set_surface.

SWMM_ENGINE_API int	swmm_lid_get_soil (SWMM_Engine engine, int idx, double thick, double porosity, double fc, double wp, double ksat, double kslope)
	Read the soil layer properties. Inverse of swmm_lid_set_soil. Any out-param may be null.

SWMM_ENGINE_API int	swmm_lid_get_storage (SWMM_Engine engine, int idx, double thick, double void_frac, double *ksat)
	Read the storage layer properties. Inverse of swmm_lid_set_storage. Any out-param may be null.

SWMM_ENGINE_API int	swmm_lid_get_drain (SWMM_Engine engine, int idx, double coeff, double expon, double *offset)
	Read the underdrain properties. Inverse of swmm_lid_set_drain. Any out-param may be null.

SWMM_ENGINE_API int	swmm_lid_get_pavement (SWMM_Engine engine, int idx, double thick, double void_ratio, double frac_imperv, double ksat, double clog_factor, double regen_days)
	Read the porous-pavement layer. Inverse of swmm_lid_set_pavement. Any out-param may be null.

SWMM_ENGINE_API int	swmm_lid_get_drainmat (SWMM_Engine engine, int idx, double thick, double void_frac, double *roughness)
	Read the drainage-mat layer. Inverse of swmm_lid_set_drainmat. Any out-param may be null.

SWMM_ENGINE_API int	swmm_lid_usage_add (SWMM_Engine engine, int subcatch_idx, int lid_idx, int number, double area, double width, double init_sat, double from_imperv)
	Assign a LID control to a subcatchment.

SWMM_ENGINE_API int	swmm_lid_usage_count (SWMM_Engine engine)
	Total number of LID usage rows across all subcatchments.

SWMM_ENGINE_API int	swmm_lid_usage_get (SWMM_Engine engine, int usage_idx, int subcatch_idx, int lid_idx, int number, double area, double width, double init_sat, double from_imperv, int to_perv, double *from_perv)
	Read one LID usage row by global index.

SWMM_ENGINE_API int	swmm_lid_usage_remove (SWMM_Engine engine, int usage_idx)
	Remove one LID usage row by global index.

Detailed Description

C API implementation — transects, streets, inlets, LID controls, LID usage.

See also: include/openswmm/engine/openswmm_infrastructure.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_inlet_add()

SWMM_ENGINE_API int swmm_inlet_add	(	SWMM_Engine	engine,
		const char *	id,
		const char *	type )

Add a new inlet definition.

Parameters

engine	Engine handle (SWMM_STATE_BUILDING).
id	Unique null-terminated identifier.
type	Inlet type string (e.g., "GRATE", "CURB", "SLOTTED", "CUSTOM").

Returns: SWMM_OK on success, or an error code.

◆ swmm_inlet_count()

SWMM_ENGINE_API int swmm_inlet_count ( SWMM_Engine engine )

Get the total number of inlet definitions in the model.

Parameters

engine Engine handle.

Returns: Number of inlets, or -1 on error.

◆ swmm_inlet_get_params()

SWMM_ENGINE_API int swmm_inlet_get_params	(	SWMM_Engine	engine,
		int	idx,
		double *	length,
		double *	width,
		char *	grate_type,
		int	grate_buflen,
		double *	open_area,
		double *	splash_veloc )

Read an inlet's geometric parameters. Inverse of swmm_inlet_set_params.

Lets the GUI inlet editor load an existing definition instead of only writing one. Any out-param may be null. The inlet type string (set at swmm_inlet_add) is read separately via swmm_inlet_get_type.

Parameters

	engine	Engine handle.
	idx	Zero-based inlet index.
[out]	length	Receives the inlet length.
[out]	width	Receives the inlet width.
[out]	grate_type	Buffer for the grate-type string (NUL-terminated, truncated to `grate_buflen`); may be null to skip.
	grate_buflen	Size of `grate_type` in bytes; ignored when `grate_type` is null.
[out]	open_area	Receives the open-area fraction.
[out]	splash_veloc	Receives the splash-over velocity threshold.

Returns: SWMM_OK on success, or an error code.

◆ swmm_inlet_get_type()

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

Read an inlet's type string (the value passed to swmm_inlet_add).

Parameters

	engine	Engine handle.
	idx	Zero-based inlet index.
[out]	buf	Destination buffer (NUL-terminated, truncated to `buflen`).
	buflen	Size of `buf` in bytes (must be > 0).

Returns: SWMM_OK on success, or an error code.

◆ swmm_inlet_id()

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

Get the string identifier of an inlet by index.

Parameters

engine	Engine handle.
idx	Zero-based inlet index.

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

◆ swmm_inlet_index()

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

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

Parameters

engine	Engine handle.
id	Null-terminated inlet identifier.

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

◆ swmm_inlet_set_params()

SWMM_ENGINE_API int swmm_inlet_set_params	(	SWMM_Engine	engine,
		int	idx,
		double	length,
		double	width,
		const char *	grate_type,
		double	open_area,
		double	splash_veloc )

Set the geometric parameters for an inlet.

Parameters

engine	Engine handle.
idx	Zero-based inlet index.
length	Inlet length.
width	Inlet width.
grate_type	Grate type string (e.g., "P-50", "GENERIC").
open_area	Open area fraction (0–1).
splash_veloc	Splash-over velocity threshold.

Returns: SWMM_OK on success, or an error code.

◆ swmm_lid_add()

SWMM_ENGINE_API int swmm_lid_add	(	SWMM_Engine	engine,
		const char *	id,
		int	type )

Add a new LID (Low Impact Development) control.

LID types: 0=BIO_CELL, 1=RAIN_GARDEN, 2=GREEN_ROOF, 3=INFIL_TRENCH, 4=PERM_PAVEMENT, 5=RAIN_BARREL, 6=ROOFTOP_DISCONN, 7=VEGETATIVE_SWALE.

Parameters

engine	Engine handle (SWMM_STATE_BUILDING).
id	Unique null-terminated identifier.
type	LID type code.

Returns: SWMM_OK on success, or an error code.

◆ swmm_lid_count()

SWMM_ENGINE_API int swmm_lid_count ( SWMM_Engine engine )

Get the total number of LID controls in the model.

Parameters

engine Engine handle.

Returns: Number of LID controls, or -1 on error.

◆ swmm_lid_get_drain()

SWMM_ENGINE_API int swmm_lid_get_drain	(	SWMM_Engine	engine,
		int	idx,
		double *	coeff,
		double *	expon,
		double *	offset )

Read the underdrain properties. Inverse of swmm_lid_set_drain. Any out-param may be null.

◆ swmm_lid_get_drainmat()

SWMM_ENGINE_API int swmm_lid_get_drainmat	(	SWMM_Engine	engine,
		int	idx,
		double *	thick,
		double *	void_frac,
		double *	roughness )

Read the drainage-mat layer. Inverse of swmm_lid_set_drainmat. Any out-param may be null.

◆ swmm_lid_get_pavement()

SWMM_ENGINE_API int swmm_lid_get_pavement	(	SWMM_Engine	engine,
		int	idx,
		double *	thick,
		double *	void_ratio,
		double *	frac_imperv,
		double *	ksat,
		double *	clog_factor,
		double *	regen_days )

Read the porous-pavement layer. Inverse of swmm_lid_set_pavement. Any out-param may be null.

◆ swmm_lid_get_soil()

SWMM_ENGINE_API int swmm_lid_get_soil	(	SWMM_Engine	engine,
		int	idx,
		double *	thick,
		double *	porosity,
		double *	fc,
		double *	wp,
		double *	ksat,
		double *	kslope )

Read the soil layer properties. Inverse of swmm_lid_set_soil. Any out-param may be null.

◆ swmm_lid_get_storage()

SWMM_ENGINE_API int swmm_lid_get_storage	(	SWMM_Engine	engine,
		int	idx,
		double *	thick,
		double *	void_frac,
		double *	ksat )

Read the storage layer properties. Inverse of swmm_lid_set_storage. Any out-param may be null.

◆ swmm_lid_get_surface()

SWMM_ENGINE_API int swmm_lid_get_surface	(	SWMM_Engine	engine,
		int	idx,
		double *	storage,
		double *	roughness,
		double *	slope )

Read the surface layer properties. Inverse of swmm_lid_set_surface.

Lets the GUI LID editor load an existing control's layers instead of only writing them. Any out-param may be null.

◆ swmm_lid_get_type()

SWMM_ENGINE_API int swmm_lid_get_type	(	SWMM_Engine	engine,
		int	idx,
		int *	type )

Read a LID control's type code. Inverse of the type argument to swmm_lid_add.

Parameters

	engine	Engine handle.
	idx	Zero-based LID index.
[out]	type	Receives the LID type code (0=BIO_CELL … 7=VEGETATIVE_SWALE).

Returns: SWMM_OK on success, or an error code.

◆ swmm_lid_id()

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

Get the string identifier of a LID control by index.

Parameters

engine	Engine handle.
idx	Zero-based LID index.

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

◆ swmm_lid_index()

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

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

Parameters

engine	Engine handle.
id	Null-terminated LID identifier.

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

◆ swmm_lid_set_drain()

SWMM_ENGINE_API int swmm_lid_set_drain	(	SWMM_Engine	engine,
		int	idx,
		double	coeff,
		double	expon,
		double	offset )

Set the underdrain properties for a LID control.

Parameters

engine	Engine handle.
idx	Zero-based LID index.
coeff	Drain coefficient.
expon	Drain exponent.
offset	Drain offset height above the storage layer bottom.

Returns: SWMM_OK on success, or an error code.

◆ swmm_lid_set_drainmat()

SWMM_ENGINE_API int swmm_lid_set_drainmat	(	SWMM_Engine	engine,
		int	idx,
		double	thick,
		double	void_frac,
		double	roughness )

Set the drainage-mat layer properties for a LID control.

Used by GREEN_ROOF (and any LID with a DRAINMAT line). The three values of the [LID_CONTROLS] ... DRAINMAT line, in input-file units. Pre-start-only (BUILDING/OPENED).

Parameters

engine	Engine handle.
idx	Zero-based LID index.
thick	Drainage-mat thickness.
void_frac	Void fraction of the mat (0–1).
roughness	Manning's n for flow through the mat.

Returns: SWMM_OK on success, or an error code.

◆ swmm_lid_set_pavement()

SWMM_ENGINE_API int swmm_lid_set_pavement	(	SWMM_Engine	engine,
		int	idx,
		double	thick,
		double	void_ratio,
		double	frac_imperv,
		double	ksat,
		double	clog_factor,
		double	regen_days )

Set the porous-pavement layer properties for a LID control.

Used by PERM_PAVEMENT (and any LID with a PAVEMENT line). The six values of the [LID_CONTROLS] ... PAVEMENT line, in input-file units. Pre-start-only (BUILDING/OPENED) — the layer seeds per-unit LID state at start().

Parameters

engine	Engine handle.
idx	Zero-based LID index.
thick	Pavement layer thickness.
void_ratio	Void ratio (volume of voids / volume of solids).
frac_imperv	Impervious surface fraction (0–1).
ksat	Permeability / saturated conductivity.
clog_factor	Clogging factor (0 = no clogging).
regen_days	Days between clogging regeneration (0 = never).

Returns: SWMM_OK on success, or an error code.

◆ swmm_lid_set_soil()

SWMM_ENGINE_API int swmm_lid_set_soil	(	SWMM_Engine	engine,
		int	idx,
		double	thick,
		double	porosity,
		double	fc,
		double	wp,
		double	ksat,
		double	kslope )

Set the soil layer properties for a LID control.

Parameters

engine	Engine handle.
idx	Zero-based LID index.
thick	Soil thickness.
porosity	Soil porosity (fraction).
fc	Field capacity (fraction).
wp	Wilting point (fraction).
ksat	Saturated hydraulic conductivity.
kslope	Slope of the conductivity–moisture curve.

Returns: SWMM_OK on success, or an error code.

◆ swmm_lid_set_storage()

SWMM_ENGINE_API int swmm_lid_set_storage	(	SWMM_Engine	engine,
		int	idx,
		double	thick,
		double	void_frac,
		double	ksat )

Set the storage layer properties for a LID control.

Parameters

engine	Engine handle.
idx	Zero-based LID index.
thick	Storage layer thickness.
void_frac	Void fraction (porosity of gravel/aggregate).
ksat	Seepage rate through the storage layer bottom.

Returns: SWMM_OK on success, or an error code.

◆ swmm_lid_set_surface()

SWMM_ENGINE_API int swmm_lid_set_surface	(	SWMM_Engine	engine,
		int	idx,
		double	storage,
		double	roughness,
		double	slope )

Set the surface layer properties for a LID control.

Parameters

engine	Engine handle.
idx	Zero-based LID index.
storage	Surface storage depth.
roughness	Surface Manning's n.
slope	Surface slope (fraction).

Returns: SWMM_OK on success, or an error code.

◆ swmm_lid_usage_add()

SWMM_ENGINE_API int swmm_lid_usage_add	(	SWMM_Engine	engine,
		int	subcatch_idx,
		int	lid_idx,
		int	number,
		double	area,
		double	width,
		double	init_sat,
		double	from_imperv )

Assign a LID control to a subcatchment.

Multiple LID units of the same or different types can be assigned to a single subcatchment.

Parameters

engine	Engine handle.
subcatch_idx	Zero-based subcatchment index.
lid_idx	Zero-based LID control index.
number	Number of replicate LID units.
area	Area of each LID unit in project area units.
width	Top width of the overland flow surface per unit.
init_sat	Initial saturation of the soil layer (0–1).
from_imperv	Fraction of impervious area runoff treated by this LID (0–1).

Returns: SWMM_OK on success, or an error code.

◆ swmm_lid_usage_count()

SWMM_ENGINE_API int swmm_lid_usage_count ( SWMM_Engine engine )

Total number of LID usage rows across all subcatchments.

To enumerate the usages on one subcatchment, iterate [0, count) and filter on the subcatch index returned by swmm_lid_usage_get.

Returns: The usage count, or -1 on a bad handle.

◆ swmm_lid_usage_get()

SWMM_ENGINE_API int swmm_lid_usage_get	(	SWMM_Engine	engine,
		int	usage_idx,
		int *	subcatch_idx,
		int *	lid_idx,
		int *	number,
		double *	area,
		double *	width,
		double *	init_sat,
		double *	from_imperv,
		int *	to_perv,
		double *	from_perv )

Read one LID usage row by global index.

Parameters

	engine	Engine handle.
	usage_idx	Zero-based global usage index ([0, count)).
[out]	subcatch_idx	Owning subcatchment index (nullable).
[out]	lid_idx	LID control index (nullable).
[out]	number	Number of replicate units (nullable).
[out]	area	Area per unit (nullable).
[out]	width	Overland flow top width (nullable).
[out]	init_sat	Initial saturation 0–1 (nullable).
[out]	from_imperv	Fraction of impervious runoff treated (nullable).
[out]	to_perv	1 = route outflow to pervious area (nullable).
[out]	from_perv	Fraction of pervious runoff treated (nullable).

Returns: SWMM_OK on success, or an error code.

◆ swmm_lid_usage_remove()

SWMM_ENGINE_API int swmm_lid_usage_remove	(	SWMM_Engine	engine,
		int	usage_idx )

Remove one LID usage row by global index.

Later usage indices shift down by one after removal.

Returns: SWMM_OK on success, or an error code.

◆ swmm_street_add()

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

Add a new street cross-section definition.

Parameters

engine	Engine handle (SWMM_STATE_BUILDING).
id	Unique null-terminated identifier.

Returns: SWMM_OK on success, or an error code.

◆ swmm_street_count()

SWMM_ENGINE_API int swmm_street_count ( SWMM_Engine engine )

Get the total number of street definitions in the model.

Parameters

engine Engine handle.

Returns: Number of streets, or -1 on error.

◆ swmm_street_get_params()

SWMM_ENGINE_API int swmm_street_get_params	(	SWMM_Engine	engine,
		int	idx,
		double *	t_crown,
		double *	h_curb,
		double *	sx,
		double *	n_road,
		double *	gutter_depres,
		double *	gutter_width,
		int *	sides,
		double *	back_width,
		double *	back_slope,
		double *	back_n )

Read back the geometric parameters of a street cross-section.

Inverse of swmm_street_set_params. Any out-pointer may be NULL if that field is not needed. Values are returned in the same units they were supplied (display units).

Parameters

	engine	Engine handle.
	idx	Zero-based street index.
[out]	t_crown	Crown thickness.
[out]	h_curb	Curb height.
[out]	sx	Cross slope of the roadway.
[out]	n_road	Manning's n for the road surface.
[out]	gutter_depres	Gutter depression depth.
[out]	gutter_width	Gutter width.
[out]	sides	Number of sides (1 or 2).
[out]	back_width	Backing (sidewalk) width.
[out]	back_slope	Backing slope.
[out]	back_n	Manning's n for the backing area.

Returns: SWMM_OK on success, or an error code.

◆ swmm_street_id()

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

Get the string identifier of a street by index.

Parameters

engine	Engine handle.
idx	Zero-based street index.

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

◆ swmm_street_index()

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

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

Parameters

engine	Engine handle.
id	Null-terminated street identifier.

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

◆ swmm_street_set_params()

SWMM_ENGINE_API int swmm_street_set_params	(	SWMM_Engine	engine,
		int	idx,
		double	t_crown,
		double	h_curb,
		double	sx,
		double	n_road,
		double	gutter_depres,
		double	gutter_width,
		int	sides,
		double	back_width,
		double	back_slope,
		double	back_n )

Set the geometric parameters for a street cross-section.

Parameters

engine	Engine handle.
idx	Zero-based street index.
t_crown	Crown thickness (rise of the crown above the gutter).
h_curb	Curb height.
sx	Cross slope of the roadway.
n_road	Manning's n for the road surface.
gutter_depres	Gutter depression depth.
gutter_width	Gutter width.
sides	Number of sides (1 or 2).
back_width	Backing (sidewalk) width.
back_slope	Backing slope.
back_n	Manning's n for the backing area.

Returns: SWMM_OK on success, or an error code.

◆ swmm_transect_add()

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

Add a new transect for irregular cross-sections.

Parameters

engine	Engine handle (SWMM_STATE_BUILDING).
id	Unique null-terminated identifier.

Returns: SWMM_OK on success, or an error code.

◆ swmm_transect_add_station()

SWMM_ENGINE_API int swmm_transect_add_station	(	SWMM_Engine	engine,
		int	idx,
		double	station,
		double	elevation )

Add a station–elevation data point to a transect.

Stations must be added in order from left to right across the cross-section.

Parameters

engine	Engine handle.
idx	Zero-based transect index.
station	Horizontal distance (station) from a reference.
elevation	Elevation at this station.

Returns: SWMM_OK on success, or an error code.

◆ swmm_transect_clear_stations()

SWMM_ENGINE_API int swmm_transect_clear_stations	(	SWMM_Engine	engine,
		int	idx )

Remove all station–elevation pairs from a transect.

Used by the GUI's snapshot-and-rewrite path: clear then re-add the full station list in one shot.

Parameters

engine	Engine handle.
idx	Zero-based transect index.

Returns: SWMM_OK on success, or an error code.

◆ swmm_transect_count()

SWMM_ENGINE_API int swmm_transect_count ( SWMM_Engine engine )

Get the total number of transects in the model.

Parameters

engine Engine handle.

Returns: Number of transects, or -1 on error.

◆ swmm_transect_get_bank_stations()

SWMM_ENGINE_API int swmm_transect_get_bank_stations	(	SWMM_Engine	engine,
		int	idx,
		double *	x_left,
		double *	x_right )

Get the left and right bank stations for a transect.

Parameters

engine	Engine handle.
idx	Zero-based transect index.
x_left	[out] Station of the left bank. May be NULL.
x_right	[out] Station of the right bank. May be NULL.

Returns: SWMM_OK on success, or an error code.

◆ swmm_transect_get_comments()

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

Get the free-form comments / description for a transect.

Writes the comment into buf with NUL termination; truncates if the buffer is smaller than the comment. Always returns SWMM_OK (an empty comment results in buf[0] == '\0').

Parameters

engine	Engine handle.
idx	Zero-based transect index.
buf	Destination buffer.
buflen	Size of `buf` in bytes (must be > 0).

Returns: SWMM_OK on success, or an error code.

◆ swmm_transect_get_encroachment_stations()

SWMM_ENGINE_API int swmm_transect_get_encroachment_stations	(	SWMM_Engine	engine,
		int	idx,
		double *	x_left,
		double *	x_right )

Get the left and right encroachment stations for a transect (BQ-TR-02).

Parameters

engine	Engine handle.
idx	Zero-based transect index.
x_left	[out] Station of the left encroachment limit. May be NULL.
x_right	[out] Station of the right encroachment limit. May be NULL.

Returns: SWMM_OK on success, or an error code.

◆ swmm_transect_get_modifiers()

SWMM_ENGINE_API int swmm_transect_get_modifiers	(	SWMM_Engine	engine,
		int	idx,
		double *	x_factor,
		double *	y_factor,
		double *	length_factor )

Get the station, elevation, and meander modifiers for a transect.

Parameters

engine	Engine handle.
idx	Zero-based transect index.
x_factor	[out] Station spacing multiplier. May be NULL.
y_factor	[out] Elevation offset. May be NULL.
length_factor	[out] Meander factor. May be NULL.

Returns: SWMM_OK on success, or an error code.

◆ swmm_transect_get_roughness()

SWMM_ENGINE_API int swmm_transect_get_roughness	(	SWMM_Engine	engine,
		int	idx,
		double *	n_left,
		double *	n_right,
		double *	n_channel )

Get the Manning's roughness values for a transect.

Parameters

engine	Engine handle.
idx	Zero-based transect index.
n_left	[out] Manning's n for the left overbank. May be NULL.
n_right	[out] Manning's n for the right overbank. May be NULL.
n_channel	[out] Manning's n for the main channel. May be NULL.

Returns: SWMM_OK on success, or an error code.

◆ swmm_transect_get_station()

SWMM_ENGINE_API int swmm_transect_get_station	(	SWMM_Engine	engine,
		int	idx,
		int	station_idx,
		double *	station,
		double *	elevation )

Get a single station–elevation pair from a transect.

Parameters

engine	Engine handle.
idx	Zero-based transect index.
station_idx	Zero-based station-pair index.
station	[out] Horizontal distance. May be NULL.
elevation	[out] Elevation at this station. May be NULL.

Returns: SWMM_OK on success, or an error code.

◆ swmm_transect_get_station_count()

SWMM_ENGINE_API int swmm_transect_get_station_count	(	SWMM_Engine	engine,
		int	idx )

Get the number of station–elevation points stored for a transect.

Parameters

engine	Engine handle.
idx	Zero-based transect index.

Returns: Station count, or -1 on error.

◆ swmm_transect_id()

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

Get the string identifier of a transect by index.

Parameters

engine	Engine handle.
idx	Zero-based transect index.

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

◆ swmm_transect_index()

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

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

Parameters

engine	Engine handle.
id	Null-terminated transect identifier.

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

◆ swmm_transect_remove()

SWMM_ENGINE_API int swmm_transect_remove	(	SWMM_Engine	engine,
		int	idx )

Remove a transect by index.

Out-of-range indices are a SWMM_OK no-op (mirrors the pattern mutation API — see test_pattern_mutation_api.cpp). Remaining transects preserve their relative order; their indices shift down by one.

Parameters

engine	Engine handle.
idx	Zero-based transect index.

Returns: SWMM_OK on success, or an error code.

◆ swmm_transect_rename()

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

Rename an existing transect.

Refuses on collision with another existing transect name (case insensitive); same-name is a no-op SWMM_OK.

Parameters

engine	Engine handle.
idx	Zero-based transect index.
new_id	New null-terminated identifier.

Returns: SWMM_OK on success, or an error code.

◆ swmm_transect_set_bank_stations()

SWMM_ENGINE_API int swmm_transect_set_bank_stations	(	SWMM_Engine	engine,
		int	idx,
		double	x_left,
		double	x_right )

Set the left and right bank stations for a transect.

Bank stations delimit the main channel from the overbanks; they are independent of the encroachment stations (BQ-TR-02).

Parameters

engine	Engine handle.
idx	Zero-based transect index.
x_left	Station of the left bank.
x_right	Station of the right bank.

Returns: SWMM_OK on success, or an error code.

◆ swmm_transect_set_comments()

SWMM_ENGINE_API int swmm_transect_set_comments	(	SWMM_Engine	engine,
		int	idx,
		const char *	text )

Set the free-form comments / description for a transect.

Parameters

engine	Engine handle.
idx	Zero-based transect index.
text	Null-terminated comment string. NULL clears the comment.

Returns: SWMM_OK on success, or an error code.

◆ swmm_transect_set_encroachment_stations()

SWMM_ENGINE_API int swmm_transect_set_encroachment_stations	(	SWMM_Engine	engine,
		int	idx,
		double	x_left,
		double	x_right )

Set the left and right encroachment stations for a transect (BQ-TR-02).

Encroachment stations are distinct from bank stations and identify floodplain encroachment limits (HEC-RAS convention). On legacy [TRANSECTS] X1 records that omit the trailing encroachment columns, the INP parser may default these to the bank stations to preserve backward compatibility; callers writing programmatic values via this API are setting them explicitly.

Parameters

engine	Engine handle.
idx	Zero-based transect index.
x_left	Station of the left encroachment limit.
x_right	Station of the right encroachment limit.

Returns: SWMM_OK on success, or an error code.

◆ swmm_transect_set_modifiers()

SWMM_ENGINE_API int swmm_transect_set_modifiers	(	SWMM_Engine	engine,
		int	idx,
		double	x_factor,
		double	y_factor,
		double	length_factor )

Set the station, elevation, and meander modifiers for a transect.

Maps to the xFactor, yFactor, and lengthFactor parameters on the [TRANSECTS] X1 record:

x_factor = station-spacing multiplier (default 1.0).
y_factor = elevation offset added to every station elevation (default 0.0 — engine stores 1.0 as a no-op marker at swmm_transect_add time).
length_factor = meander factor = channel / floodplain length ratio (default 1.0).

Parameters

engine	Engine handle.
idx	Zero-based transect index.
x_factor	Station spacing multiplier.
y_factor	Elevation offset.
length_factor	Meander factor (channel/floodplain length ratio).

Returns: SWMM_OK on success, or an error code.

◆ swmm_transect_set_roughness()

SWMM_ENGINE_API int swmm_transect_set_roughness	(	SWMM_Engine	engine,
		int	idx,
		double	n_left,
		double	n_right,
		double	n_channel )

Set Manning's roughness for left overbank, right overbank, and channel.

Parameters

engine	Engine handle.
idx	Zero-based transect index.
n_left	Manning's n for the left overbank.
n_right	Manning's n for the right overbank.
n_channel	Manning's n for the main channel.

Returns: SWMM_OK on success, or an error code.

Functions

Detailed Description

Function Documentation

◆ swmm_inlet_add()

◆ swmm_inlet_count()

◆ swmm_inlet_get_params()

◆ swmm_inlet_get_type()

◆ swmm_inlet_id()

◆ swmm_inlet_index()

◆ swmm_inlet_set_params()

◆ swmm_lid_add()

◆ swmm_lid_count()

◆ swmm_lid_get_drain()

◆ swmm_lid_get_drainmat()

◆ swmm_lid_get_pavement()

◆ swmm_lid_get_soil()

◆ swmm_lid_get_storage()

◆ swmm_lid_get_surface()

◆ swmm_lid_get_type()

◆ swmm_lid_id()

◆ swmm_lid_index()

◆ swmm_lid_set_drain()

◆ swmm_lid_set_drainmat()

◆ swmm_lid_set_pavement()

◆ swmm_lid_set_soil()

◆ swmm_lid_set_storage()

◆ swmm_lid_set_surface()

◆ swmm_lid_usage_add()

◆ swmm_lid_usage_count()

◆ swmm_lid_usage_get()

◆ swmm_lid_usage_remove()

◆ swmm_street_add()

◆ swmm_street_count()

◆ swmm_street_get_params()

◆ swmm_street_id()

◆ swmm_street_index()

◆ swmm_street_set_params()

◆ swmm_transect_add()

◆ swmm_transect_add_station()

◆ swmm_transect_clear_stations()

◆ swmm_transect_count()

◆ swmm_transect_get_bank_stations()

◆ swmm_transect_get_comments()

◆ swmm_transect_get_encroachment_stations()

◆ swmm_transect_get_modifiers()

◆ swmm_transect_get_roughness()

◆ swmm_transect_get_station()

◆ swmm_transect_get_station_count()

◆ swmm_transect_id()

◆ swmm_transect_index()

◆ swmm_transect_remove()

◆ swmm_transect_rename()

◆ swmm_transect_set_bank_stations()

◆ swmm_transect_set_comments()

◆ swmm_transect_set_encroachment_stations()

◆ swmm_transect_set_modifiers()

◆ swmm_transect_set_roughness()