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

#include "../hydrology/LidNode.hpp"
#include "openswmm_api_common.hpp"
#include "../../../include/openswmm/engine/openswmm_infrastructure.h"
#include "StringCase.hpp"
#include "ErrorCodes.hpp"
#include "../edit/VirtualJunctionOps.hpp"
#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_rename (SWMM_Engine engine, int idx, const char *new_id)
	Rename a street cross-section in place.

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_rename (SWMM_Engine engine, int idx, const char *new_id)
	Rename an inlet design in place.

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_inlet_get_design (SWMM_Engine engine, int idx, SWMM_InletDesign *out)
	Read every field of an inlet design.

SWMM_ENGINE_API int	swmm_inlet_set_design (SWMM_Engine engine, int idx, const SWMM_InletDesign *design)
	Validate and replace the type-specific inlet design.

SWMM_ENGINE_API int	swmm_inlet_get_comment (SWMM_Engine engine, int idx, char *buf, int buflen)
	Copy an inlet design comment.

SWMM_ENGINE_API int	swmm_inlet_set_comment (SWMM_Engine engine, int idx, const char *text)
	Replace an inlet design comment.

SWMM_ENGINE_API int	swmm_inlet_usage_count (SWMM_Engine engine)
	Count inlet-usage rows of both host kinds.

SWMM_ENGINE_API int	swmm_inlet_usage_find_link (SWMM_Engine engine, int link_idx)
	Find the first inlet-usage row hosted by a link.

SWMM_ENGINE_API int	swmm_inlet_usage_find_node (SWMM_Engine engine, int node_idx)
	Find the first inlet-usage row hosted by a node.

SWMM_ENGINE_API int	swmm_inlet_usage_get (SWMM_Engine engine, int usage_idx, SWMM_InletUsage *out)
	Read a complete inlet placement row.

SWMM_ENGINE_API int	swmm_inlet_usage_set (SWMM_Engine engine, const SWMM_InletUsage usage, int usage_idx)
	Validate and upsert one inlet placement per host.

SWMM_ENGINE_API int	swmm_inlet_usage_remove (SWMM_Engine engine, int usage_idx)
	Remove an inlet-usage row and shift later row indices.

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_rename (SWMM_Engine engine, int idx, const char *new_id)
	Rename an LID control in place.

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_get_removal (SWMM_Engine engine, int idx, int constituent, double *percent)
	Read a constituent underdrain-removal percentage.

SWMM_ENGINE_API int	swmm_lid_set_removal (SWMM_Engine engine, int idx, int constituent, double percent)
	Assign a constituent underdrain-removal percentage.

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 stored surface layer parameters.

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 stored soil layer parameters.

SWMM_ENGINE_API int	swmm_lid_get_storage (SWMM_Engine engine, int idx, double thick, double void_frac, double *ksat)
	Read the stored storage layer parameters.

SWMM_ENGINE_API int	swmm_lid_get_drain (SWMM_Engine engine, int idx, double coeff, double expon, double *offset)
	Read the stored drain layer parameters.

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 stored pavement layer parameters.

SWMM_ENGINE_API int	swmm_lid_get_drainmat (SWMM_Engine engine, int idx, double thick, double void_frac, double *roughness)
	Read the stored drainmat layer parameters.

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)
	Count 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)
	Erase a subcatchment LID-usage row and shift later indices.

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: Apache-2.0

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

[in]	engine	Engine handle; see this operation's lifecycle note.
[in]	id	Unique null-terminated identifier.
[in]	type	Inlet type string (e.g., "GRATE", "CURB", "SLOTTED", "CUSTOM").

Returns: SWMM_OK on success, or an error code.

Note: A null engine returns SWMM_ERR_BADHANDLE. No lifecycle guard in this wrapper; authoring edits do not generally rebuild running hydraulic/geometry caches. Required strings are copied; empty/duplicate IDs and unresolved type tokens are not rejected here.

◆ swmm_inlet_count()

SWMM_ENGINE_API int swmm_inlet_count ( SWMM_Engine engine )

Get the total number of inlet definitions in the model.

Parameters

[in] engine Engine handle.

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

Note: Null engine returns -1.

◆ swmm_inlet_get_comment()

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

Copy an inlet design comment.

No lifecycle guard. Does not change inlet geometry or usages.

Parameters

[in]	engine	Non-null live engine; caller serializes access.
[in]	idx	Zero-based existing object index in this function's table.
[out]	buf	Non-null caller-owned text buffer; NUL-terminated and silently truncated to buflen-1 bytes.
[in]	buflen	Positive capacity in bytes including the terminating NUL.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for a failed index check, or SWMM_ERR_BADPARAM for invalid required arguments.

◆ swmm_inlet_get_design()

SWMM_ENGINE_API int swmm_inlet_get_design	(	SWMM_Engine	engine,
		int	idx,
		SWMM_InletDesign *	out )

Read every field of an inlet design.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based inlet index.
[out]	out	Receives the design (must not be NULL).

Returns: SWMM_OK on success, or an error code.

Note: A null engine returns SWMM_ERR_BADHANDLE. A failed infrastructure/pollutant index check returns SWMM_ERR_BADINDEX.

◆ 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

[in]	engine	Engine handle.
[in]	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.
[in]	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.

Note: length may be NULL to suppress that output. width may be NULL to suppress that output. grate_type may be NULL to suppress that output. open_area may be NULL to suppress that output. splash_veloc may be NULL to suppress that output. A null engine returns SWMM_ERR_BADHANDLE. A failed infrastructure/pollutant index check returns SWMM_ERR_BADINDEX. For CURB/DROP_CURB, length/width map to curb length/height. Other kinds use grate/slot fields. A requested grate buffer must have positive capacity; numeric outputs may already be written if that capacity fails.

◆ 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

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

Returns: SWMM_OK on success, or an error code.

Note: A null engine returns SWMM_ERR_BADHANDLE. A failed infrastructure/pollutant index check returns SWMM_ERR_BADINDEX. Required output buffer must be non-null with positive capacity. Copies a terminating NUL and silently truncates to capacity-1 bytes.

◆ 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

[in]	engine	Engine handle.
[in]	idx	Zero-based inlet index.

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

Note: Returned text borrows engine storage: do not free; copy before editing the table or closing/destroying the engine. NULL is returned for a null engine or invalid index.

◆ 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

[in]	engine	Engine handle.
[in]	id	Null-terminated inlet identifier.

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

Note: Name lookup is case-insensitive; null engine/name or no match returns -1.

Here is the call graph for this function:

◆ swmm_inlet_rename()

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

Rename an inlet design in place.

[INLET_USAGE] rows hold an inlet INDEX, not a name, so usages follow automatically.

Parameters

[in]	engine	Engine handle.
[in]	idx	Inlet index.
[in]	new_id	New unique name (non-empty), compared case-insensitively against the other inlets. A pure case-respelling of this same inlet is allowed.

Returns: SWMM_OK, or SWMM_ERR_BADPARAM on an empty or duplicate name.

Note: A null engine returns SWMM_ERR_BADHANDLE. A failed infrastructure/pollutant index check returns SWMM_ERR_BADINDEX. No lifecycle guard in this wrapper; authoring edits do not generally rebuild running hydraulic/geometry caches.

Here is the call graph for this function:

◆ swmm_inlet_set_comment()

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

Replace an inlet design comment.

No lifecycle guard. Does not change inlet geometry or usages.

Parameters

[in]	engine	Non-null live engine; caller serializes access.
[in]	idx	Zero-based existing object index in this function's table.
[in]	text	Borrowed NUL-terminated text copied into the model; NULL clears it.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for a failed index check, or SWMM_ERR_BADPARAM for invalid required arguments.

◆ swmm_inlet_set_design()

SWMM_ENGINE_API int swmm_inlet_set_design	(	SWMM_Engine	engine,
		int	idx,
		const SWMM_InletDesign *	design )

Validate and replace the type-specific inlet design.

Requires BUILDING/OPENED. Validates only fields used by type: positive geometric dimensions; valid type/grate/throat codes; GENERIC open_area in (0,1]; nonnegative splash velocity. CUSTOM requires nonempty curve_id and a valid curve_kind; existing curves must be DIVERSION/RATING and match any explicit kind. Unresolved custom names are retained for later resolution. Clears fields unused by the new type. Numeric comparison guards are not independent finite checks; supply finite values.

Parameters

[in]	engine	Non-null live engine; caller serializes access.
[in]	idx	Zero-based existing object index in this function's table.
[in]	design	Non-null borrowed design copied on success; embedded curve_id must be NUL-terminated within its 64-byte array. Dimensions use ft/m and velocities ft/s or m/s.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for a failed index check, or SWMM_ERR_BADPARAM for invalid required arguments. SWMM_ERR_LIFECYCLE outside BUILDING/OPENED.

◆ 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

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

Returns: SWMM_OK on success, or an error code.

Note: A null engine returns SWMM_ERR_BADHANDLE. A failed infrastructure/pollutant index check returns SWMM_ERR_BADINDEX. No lifecycle guard in this wrapper; authoring edits do not generally rebuild running hydraulic/geometry caches. Numeric values are stored verbatim without finite/range validation.

◆ swmm_inlet_usage_count()

SWMM_ENGINE_API int swmm_inlet_usage_count ( SWMM_Engine engine )

Count inlet-usage rows of both host kinds.

Parameters

[in] engine Non-null live engine; caller serializes access.

Returns: Nonnegative row count, or -1 for null engine.

◆ swmm_inlet_usage_find_link()

SWMM_ENGINE_API int swmm_inlet_usage_find_link	(	SWMM_Engine	engine,
		int	link_idx )

Find the first inlet-usage row hosted by a link.

Parameters

[in]	engine	Non-null live engine; caller serializes access.
[in]	link_idx	Zero-based host link index; this lookup does not separately validate the host table.

Returns: Matching usage index, or -1 for no match/null engine.

◆ swmm_inlet_usage_find_node()

SWMM_ENGINE_API int swmm_inlet_usage_find_node	(	SWMM_Engine	engine,
		int	node_idx )

Find the first inlet-usage row hosted by a node.

Parameters

[in]	engine	Non-null live engine; caller serializes access.
[in]	node_idx	Zero-based host node index; this lookup does not separately validate the host table.

Returns: Matching usage index, or -1 for no match/null engine.

◆ swmm_inlet_usage_get()

SWMM_ENGINE_API int swmm_inlet_usage_get	(	SWMM_Engine	engine,
		int	usage_idx,
		SWMM_InletUsage *	out )

Read a complete inlet placement row.

Returns percentage clogged as (1-clog_factor)*100; performs no lifecycle check.

Parameters

[in]	engine	Non-null live engine; caller serializes access.
[in]	usage_idx	Zero-based existing usage-row index.
[out]	out	Non-null caller-owned struct receiving host/design/capture indices and display-unit parameters.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for a failed index check, or SWMM_ERR_BADPARAM for invalid required arguments.

◆ swmm_inlet_usage_remove()

SWMM_ENGINE_API int swmm_inlet_usage_remove	(	SWMM_Engine	engine,
		int	usage_idx )

Remove an inlet-usage row and shift later row indices.

Requires BUILDING/OPENED. Removing an inlet junction usage does not fuse/delete the host node or clear its inlet-junction flag.

Parameters

[in]	engine	Non-null live engine; caller serializes access.
[in]	usage_idx	Zero-based existing usage-row index.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for a failed index check, or SWMM_ERR_BADPARAM for invalid required arguments. SWMM_ERR_LIFECYCLE outside BUILDING/OPENED.

◆ swmm_inlet_usage_set()

SWMM_ENGINE_API int swmm_inlet_usage_set	(	SWMM_Engine	engine,
		const SWMM_InletUsage *	usage,
		int *	usage_idx )

Validate and upsert one inlet placement per host.

Requires BUILDING/OPENED. Copies the row and clears deferred design/capture names. Flow and local dimensions are display flow/length units. Supply finite numbers because comparison guards do not independently reject NaN.

Parameters

[in]	engine	Non-null live engine; caller serializes access.
[in]	usage	Non-null borrowed struct. Host must be a conduit or already flagged inlet junction, design/capture indices valid; capture must not be virtual or the host node. num_inlets>=1, clogging 0..99 percent, nonnegative flow_limit/local dimensions and valid placement code.
[out]	usage_idx	Optional row index, written only on success; existing host row is replaced, otherwise appended.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for a failed index check, or SWMM_ERR_BADPARAM for invalid required arguments. SWMM_ERR_LIFECYCLE outside BUILDING/OPENED. Returns ERR_INLET_USAGE_SHAPE for incompatible host/design cross-section.

Here is the call graph for this function:

◆ 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, 8=NODE.

Parameters

[in]	engine	Engine handle; see this operation's lifecycle note.
[in]	id	Unique null-terminated identifier.
[in]	type	LID type code.

Returns: SWMM_OK on success, or an error code.

Note: A null engine returns SWMM_ERR_BADHANDLE. Requires BUILDING/OPENED; other states return SWMM_ERR_LIFECYCLE.

◆ swmm_lid_count()

SWMM_ENGINE_API int swmm_lid_count ( SWMM_Engine engine )

Get the total number of LID controls in the model.

Parameters

[in] engine Engine handle.

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

Note: Null engine returns -1.

◆ 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 stored drain layer parameters.

All outputs may be NULL; returns stored authoring values without runtime conversion or a lifecycle guard.

Parameters

[in]	engine	Non-null live engine; caller serializes access.
[in]	idx	Zero-based existing object index in this function's table.
[out]	coeff	Optional output. User coefficient in the input depth/hour drain power law.
[out]	expon	Optional output. Dimensionless drain power-law exponent.
[out]	offset	Optional output. Drain height above storage bottom, inches/mm.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for a failed index check, or SWMM_ERR_BADPARAM for invalid required arguments.

◆ 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 stored drainmat layer parameters.

All outputs may be NULL; returns stored authoring values without runtime conversion or a lifecycle guard.

Parameters

[in]	engine	Non-null live engine; caller serializes access.
[in]	idx	Zero-based existing object index in this function's table.
[out]	thick	Optional output. Drainage mat thickness, inches/mm.
[out]	void_frac	Optional output. Stored drainage-mat void parameter, as passed to its setter.
[out]	roughness	Optional output. Manning roughness.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for a failed index check, or SWMM_ERR_BADPARAM for invalid required arguments.

◆ 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 stored pavement layer parameters.

All outputs may be NULL; returns stored authoring values without runtime conversion or a lifecycle guard.

Parameters

[in]	engine	Non-null live engine; caller serializes access.
[in]	idx	Zero-based existing object index in this function's table.
[out]	thick	Optional output. Pavement thickness, inches/mm.
[out]	void_ratio	Optional output. Void/solid volume ratio.
[out]	frac_imperv	Optional output. Impervious surface fraction.
[out]	ksat	Optional output. Permeability, inches/hour or mm/hour.
[out]	clog_factor	Optional output. Dimensionless clogging factor; zero disables clogging.
[out]	regen_days	Optional output. Regeneration interval, days; zero disables it.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for a failed index check, or SWMM_ERR_BADPARAM for invalid required arguments.

◆ swmm_lid_get_removal()

SWMM_ENGINE_API int swmm_lid_get_removal	(	SWMM_Engine	engine,
		int	idx,
		int	constituent,
		double *	percent )

Read a constituent underdrain-removal percentage.

No lifecycle guard on get.

Parameters

[in]	engine	Non-null live engine; caller serializes access.
[in]	idx	Zero-based existing object index in this function's table.
[in]	constituent	0..np-1 selects pollutant; np+m selects reaction species m, included only when reactions are configured. Excludes reserved registry species.
[out]	percent	Non-null required output; zero if no row exists.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for a failed index check, or SWMM_ERR_BADPARAM for invalid required arguments.

Here is the call graph for this function:

◆ 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 stored soil layer parameters.

All outputs may be NULL; returns stored authoring values without runtime conversion or a lifecycle guard.

Parameters

[in]	engine	Non-null live engine; caller serializes access.
[in]	idx	Zero-based existing object index in this function's table.
[out]	thick	Optional output. Soil thickness in inches/mm.
[out]	porosity	Optional output. Volumetric porosity fraction.
[out]	fc	Optional output. Field-capacity moisture fraction.
[out]	wp	Optional output. Wilting-point moisture fraction.
[out]	ksat	Optional output. Saturated conductivity in inches/hour or mm/hour.
[out]	kslope	Optional output. Dimensionless exponential conductivity slope.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for a failed index check, or SWMM_ERR_BADPARAM for invalid required arguments.

◆ 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 stored storage layer parameters.

All outputs may be NULL; returns stored authoring values without runtime conversion or a lifecycle guard.

Parameters

[in]	engine	Non-null live engine; caller serializes access.
[in]	idx	Zero-based existing object index in this function's table.
[out]	thick	Optional output. Storage thickness in inches/mm.
[out]	void_frac	Optional output. Void ratio e (void/solid volume), converted to porosity e/(1+e) at initialization.
[out]	ksat	Optional output. Bottom seepage in inches/hour or mm/hour.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for a failed index check, or SWMM_ERR_BADPARAM for invalid required arguments.

◆ 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 stored surface layer parameters.

All outputs may be NULL; returns stored authoring values without runtime conversion or a lifecycle guard.

Parameters

[in]	engine	Non-null live engine; caller serializes access.
[in]	idx	Zero-based existing object index in this function's table.
[out]	storage	Optional output. Surface storage depth in inches/mm.
[out]	roughness	Optional output. Surface Manning roughness.
[out]	slope	Optional output. Surface slope in percent, not fraction.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for a failed index check, or SWMM_ERR_BADPARAM for invalid required arguments.

◆ 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

[in]	engine	Engine handle.
[in]	idx	Zero-based LID index.
[out]	type	Receives the LID type code (0=BIO_CELL … 7=VEGETATIVE_SWALE, 8=NODE; -1 for unknown stored code).

Returns: SWMM_OK on success, or an error code.

Note: type may be NULL to suppress that output. A null engine returns SWMM_ERR_BADHANDLE. A failed infrastructure/pollutant index check returns SWMM_ERR_BADINDEX.

◆ 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

[in]	engine	Engine handle.
[in]	idx	Zero-based LID index.

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

Note: Returned text borrows engine storage: do not free; copy before editing the table or closing/destroying the engine. NULL is returned for a null engine or invalid index.

◆ 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

[in]	engine	Engine handle.
[in]	id	Null-terminated LID identifier.

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

Note: Name lookup is case-insensitive; null engine/name or no match returns -1.

◆ swmm_lid_rename()

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

Rename an LID control in place.

Updates both the name vector (read by swmm_lid_id() and the [LID_CONTROLS] writer) and the name registry (read by swmm_lid_index() and the [LID_USAGE] writer). Usage rows hold an LID INDEX, so subcatchment deployments follow automatically. Lifecycle: BUILDING or OPENED.

Parameters

[in]	engine	Engine handle.
[in]	idx	LID control index.
[in]	new_id	New unique name (non-empty). A pure case-respelling of this same control is allowed.

Returns: SWMM_OK, SWMM_ERR_LIFECYCLE outside BUILDING/OPENED, or SWMM_ERR_BADPARAM on an empty or duplicate name.

Note: A null engine returns SWMM_ERR_BADHANDLE. A failed infrastructure/pollutant index check returns SWMM_ERR_BADINDEX. Requires BUILDING/OPENED; other states return SWMM_ERR_LIFECYCLE.

◆ 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

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

Returns: SWMM_OK on success, or an error code.

Note: A null engine returns SWMM_ERR_BADHANDLE. A failed infrastructure/pollutant index check returns SWMM_ERR_BADINDEX. No lifecycle guard in this wrapper; authoring edits do not generally rebuild running hydraulic/geometry caches. Rejects NODE controls; use the NODE stack configuration API. Supply finite values because scalar comparison guards are not independent finiteness checks. No lifecycle guard; refreshes cached unit drain coefficients for subsequent steps. offset uses inches/mm, expon is dimensionless and coeff follows the input depth/hour power law; all three must be nonnegative.

◆ 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

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

Returns: SWMM_OK on success, or an error code.

Note: A null engine returns SWMM_ERR_BADHANDLE. A failed infrastructure/pollutant index check returns SWMM_ERR_BADINDEX. Requires BUILDING/OPENED; other states return SWMM_ERR_LIFECYCLE. Rejects NODE controls; use the NODE stack configuration API. Supply finite values because scalar comparison guards are not independent finiteness checks. These are pre-initialization authoring parameters. Layer depths use inches/mm, conductivities inches/hour or mm/hour; surface slope is percent.

◆ 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

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

Returns: SWMM_OK on success, or an error code.

Note: A null engine returns SWMM_ERR_BADHANDLE. A failed infrastructure/pollutant index check returns SWMM_ERR_BADINDEX. Requires BUILDING/OPENED; other states return SWMM_ERR_LIFECYCLE. Rejects NODE controls; use the NODE stack configuration API. Supply finite values because scalar comparison guards are not independent finiteness checks. These are pre-initialization authoring parameters. Layer depths use inches/mm, conductivities inches/hour or mm/hour; surface slope is percent.

Here is the call graph for this function:

◆ swmm_lid_set_removal()

SWMM_ENGINE_API int swmm_lid_set_removal	(	SWMM_Engine	engine,
		int	idx,
		int	constituent,
		double	percent )

Assign a constituent underdrain-removal percentage.

Requires BUILDING/OPENED and rejects NODE controls. Updates pollutant rows by index or reaction-species rows by name and the aligned runtime removal array when present.

Parameters

[in]	engine	Non-null live engine; caller serializes access.
[in]	idx	Zero-based existing object index in this function's table.
[in]	constituent	0..np-1 selects pollutant; np+m selects reaction species m, included only when reactions are configured. Excludes reserved registry species.
[in]	percent	Percentage in [0,100]; zero removes the stored entry.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for a failed index check, or SWMM_ERR_BADPARAM for invalid required arguments. SWMM_ERR_LIFECYCLE outside BUILDING/OPENED.

Here is the call graph for this function:

◆ 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

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

Returns: SWMM_OK on success, or an error code.

Note: A null engine returns SWMM_ERR_BADHANDLE. A failed infrastructure/pollutant index check returns SWMM_ERR_BADINDEX. Requires BUILDING/OPENED; other states return SWMM_ERR_LIFECYCLE. Rejects NODE controls; use the NODE stack configuration API. Supply finite values because scalar comparison guards are not independent finiteness checks. These are pre-initialization authoring parameters. Layer depths use inches/mm, conductivities inches/hour or mm/hour; surface slope is percent.

Here is the call graph for this function:

◆ 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

[in]	engine	Engine handle.
[in]	idx	Zero-based LID index.
[in]	thick	Storage layer thickness.
[in]	void_frac	Void ratio (void volume / solid volume); porosity is e/(1+e).
[in]	ksat	Seepage rate through the storage layer bottom.

Returns: SWMM_OK on success, or an error code.

Note: A null engine returns SWMM_ERR_BADHANDLE. A failed infrastructure/pollutant index check returns SWMM_ERR_BADINDEX. Requires BUILDING/OPENED; other states return SWMM_ERR_LIFECYCLE. Rejects NODE controls; use the NODE stack configuration API. Supply finite values because scalar comparison guards are not independent finiteness checks. These are pre-initialization authoring parameters. Layer depths use inches/mm, conductivities inches/hour or mm/hour; surface slope is percent.

Here is the call graph for this function:

◆ 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

[in]	engine	Engine handle.
[in]	idx	Zero-based LID index.
[in]	storage	Surface storage depth.
[in]	roughness	Surface Manning's n.
[in]	slope	Surface slope in percent.

Returns: SWMM_OK on success, or an error code.

Note: A null engine returns SWMM_ERR_BADHANDLE. A failed infrastructure/pollutant index check returns SWMM_ERR_BADINDEX. Requires BUILDING/OPENED; other states return SWMM_ERR_LIFECYCLE. Rejects NODE controls; use the NODE stack configuration API. Supply finite values because scalar comparison guards are not independent finiteness checks. These are pre-initialization authoring parameters. Layer depths use inches/mm, conductivities inches/hour or mm/hour; surface slope is percent.

Here is the call graph for this function:

◆ 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

[in]	engine	Engine handle.
[in]	subcatch_idx	Zero-based subcatchment index.
[in]	lid_idx	Zero-based LID control index.
[in]	number	Number of replicate LID units.
[in]	area	Area of each LID unit in square feet/metres (not acres/hectares).
[in]	width	Top width of the overland flow surface per unit.
[in]	init_sat	Initial saturation of the soil layer in percent (0–100).
[in]	from_imperv	Percentage of impervious runoff treated by this LID (0–100).

Returns: SWMM_OK on success, or an error code.

Note: A null engine returns SWMM_ERR_BADHANDLE. A failed infrastructure/pollutant index check returns SWMM_ERR_BADINDEX. No lifecycle guard in this wrapper; authoring edits do not generally rebuild running hydraulic/geometry caches. Stores an appended configuration row without numeric validation or runtime solver rebuild. Area is square feet/metres per unit (not acres/hectares); width is ft/m, init_sat and from_imperv are PERCENT, not fractions. NODE controls are refused.

◆ swmm_lid_usage_count()

SWMM_ENGINE_API int swmm_lid_usage_count ( SWMM_Engine engine )

Count LID-usage rows across all subcatchments.

Parameters

[in] engine Non-null live engine; caller serializes access.

Returns: Nonnegative row count, or -1 for null engine.

◆ 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

[in]	engine	Engine handle.
[in]	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 in percent (nullable).
[out]	from_imperv	Percentage of impervious runoff treated (nullable).
[out]	to_perv	1 = route outflow to pervious area (nullable).
[out]	from_perv	Percentage of pervious runoff treated (nullable).

Returns: SWMM_OK on success, or an error code.

Note: subcatch_idx may be NULL to suppress that output. lid_idx may be NULL to suppress that output. number may be NULL to suppress that output. area may be NULL to suppress that output. width may be NULL to suppress that output. init_sat may be NULL to suppress that output. from_imperv may be NULL to suppress that output. to_perv may be NULL to suppress that output. from_perv may be NULL to suppress that output. A null engine returns SWMM_ERR_BADHANDLE. A failed infrastructure/pollutant index check returns SWMM_ERR_BADINDEX.

◆ swmm_lid_usage_remove()

SWMM_ENGINE_API int swmm_lid_usage_remove	(	SWMM_Engine	engine,
		int	usage_idx )

Erase a subcatchment LID-usage row and shift later indices.

No lifecycle guard. Erases configuration arrays and resizes balance arrays; does not rebuild running LID solver groups.

Parameters

[in]	engine	Non-null live engine; caller serializes access.
[in]	usage_idx	Zero-based global LID-usage index.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for a failed index check, or SWMM_ERR_BADPARAM for invalid required arguments.

◆ swmm_street_add()

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

Add a new street cross-section definition.

Parameters

[in]	engine	Engine handle; see this operation's lifecycle note.
[in]	id	Unique null-terminated identifier.

Returns: SWMM_OK on success, or an error code.

Note: A null engine returns SWMM_ERR_BADHANDLE. No lifecycle guard in this wrapper; authoring edits do not generally rebuild running hydraulic/geometry caches. Required strings are copied; empty/duplicate IDs and unresolved type tokens are not rejected here.

◆ swmm_street_count()

SWMM_ENGINE_API int swmm_street_count ( SWMM_Engine engine )

Get the total number of street definitions in the model.

Parameters

[in] engine Engine handle.

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

Note: Null engine returns -1.

◆ 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

[in]	engine	Engine handle.
[in]	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.

Note: t_crown may be NULL to suppress that output. h_curb may be NULL to suppress that output. sx may be NULL to suppress that output. n_road may be NULL to suppress that output. gutter_depres may be NULL to suppress that output. gutter_width may be NULL to suppress that output. sides may be NULL to suppress that output. back_width may be NULL to suppress that output. back_slope may be NULL to suppress that output. back_n may be NULL to suppress that output. A null engine returns SWMM_ERR_BADHANDLE. A failed infrastructure/pollutant index check returns SWMM_ERR_BADINDEX.

◆ 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

[in]	engine	Engine handle.
[in]	idx	Zero-based street index.

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

Note: Returned text borrows engine storage: do not free; copy before editing the table or closing/destroying the engine. NULL is returned for a null engine or invalid index.

◆ 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

[in]	engine	Engine handle.
[in]	id	Null-terminated street identifier.

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

Note: Name lookup is case-insensitive; null engine/name or no match returns -1.

Here is the call graph for this function:

◆ swmm_street_rename()

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

Rename a street cross-section in place.

Unlike the other named infrastructure objects, a street is referenced BY NAME after parsing: STREET_XSECT links carry it in their named cross-section slot, which swmm_link_get_xsect resolves and the .inp writer emits as [XSECTIONS] Geom1. This call rewrites every such reference, so renaming cannot leave a link pointing at a street that no longer exists.

Parameters

[in]	engine	Engine handle.
[in]	idx	Street index.
[in]	new_id	New unique name (non-empty), compared case-insensitively against the other streets. A pure case-respelling of this same street is allowed.

Returns: SWMM_OK, or SWMM_ERR_BADPARAM on an empty or duplicate name.

Note: A null engine returns SWMM_ERR_BADHANDLE. A failed infrastructure/pollutant index check returns SWMM_ERR_BADINDEX. No lifecycle guard in this wrapper; authoring edits do not generally rebuild running hydraulic/geometry caches.

Here is the call graph for this function:

◆ 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

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

Returns: SWMM_OK on success, or an error code.

Note: A null engine returns SWMM_ERR_BADHANDLE. A failed infrastructure/pollutant index check returns SWMM_ERR_BADINDEX. No lifecycle guard in this wrapper; authoring edits do not generally rebuild running hydraulic/geometry caches. Numeric values are stored verbatim without finite/range validation.

◆ 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

[in]	engine	Engine handle; see this operation's lifecycle note.
[in]	id	Unique null-terminated identifier.

Returns: SWMM_OK on success, or an error code.

Note: A null engine returns SWMM_ERR_BADHANDLE. No lifecycle guard in this wrapper; authoring edits do not generally rebuild running hydraulic/geometry caches. Rejects case-insensitive duplicate IDs; NULL is refused but an empty ID is accepted.

Here is the call graph for this function:

◆ 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

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

Returns: SWMM_OK on success, or an error code.

Note: A null engine returns SWMM_ERR_BADHANDLE. A failed infrastructure/pollutant index check returns SWMM_ERR_BADINDEX. Numeric values are stored verbatim without finite/range validation.

◆ 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

[in]	engine	Engine handle.
[in]	idx	Zero-based transect index.

Returns: SWMM_OK on success, or an error code.

Note: A null engine returns SWMM_ERR_BADHANDLE. A failed infrastructure/pollutant index check returns SWMM_ERR_BADINDEX. No lifecycle guard in this wrapper; authoring edits do not generally rebuild running hydraulic/geometry caches.

◆ swmm_transect_count()

SWMM_ENGINE_API int swmm_transect_count ( SWMM_Engine engine )

Get the total number of transects in the model.

Parameters

[in] engine Engine handle.

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

Note: Null engine returns -1.

◆ 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

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

Returns: SWMM_OK on success, or an error code.

Note: x_left may be NULL to suppress that output. x_right may be NULL to suppress that output. A null engine returns SWMM_ERR_BADHANDLE. A failed infrastructure/pollutant index check returns SWMM_ERR_BADINDEX.

◆ 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

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

Returns: SWMM_OK on success, or an error code.

Note: A null engine returns SWMM_ERR_BADHANDLE. A failed infrastructure/pollutant index check returns SWMM_ERR_BADINDEX. Required output buffer must be non-null with positive capacity. Copies a terminating NUL and silently truncates to capacity-1 bytes.

◆ 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

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

Returns: SWMM_OK on success, or an error code.

Note: x_left may be NULL to suppress that output. x_right may be NULL to suppress that output. A null engine returns SWMM_ERR_BADHANDLE. A failed infrastructure/pollutant index check returns SWMM_ERR_BADINDEX.

◆ 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

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

Returns: SWMM_OK on success, or an error code.

Note: x_factor may be NULL to suppress that output. y_factor may be NULL to suppress that output. length_factor may be NULL to suppress that output. A null engine returns SWMM_ERR_BADHANDLE. A failed infrastructure/pollutant index check returns SWMM_ERR_BADINDEX.

◆ 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

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

Returns: SWMM_OK on success, or an error code.

Note: n_left may be NULL to suppress that output. n_right may be NULL to suppress that output. n_channel may be NULL to suppress that output. A null engine returns SWMM_ERR_BADHANDLE. A failed infrastructure/pollutant index check returns SWMM_ERR_BADINDEX.

◆ 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

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

Returns: SWMM_OK on success, or an error code.

Note: station may be NULL to suppress that output. elevation may be NULL to suppress that output. A null engine returns SWMM_ERR_BADHANDLE. A failed infrastructure/pollutant index check returns SWMM_ERR_BADINDEX.

◆ 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

[in]	engine	Engine handle.
[in]	idx	Zero-based transect index.

Returns: Station count, or -1 on error.

Note: Null engine returns -1.

◆ 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

[in]	engine	Engine handle.
[in]	idx	Zero-based transect index.

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

Note: Returned text borrows engine storage: do not free; copy before editing the table or closing/destroying the engine. NULL is returned for a null engine or invalid index.

◆ 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

[in]	engine	Engine handle.
[in]	id	Null-terminated transect identifier.

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

Note: Name lookup is case-insensitive; null engine/name or no match returns -1.

Here is the call graph for this function:

◆ 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

[in]	engine	Engine handle.
[in]	idx	Zero-based transect index.

Returns: SWMM_OK on success, or an error code.

Note: A null engine returns SWMM_ERR_BADHANDLE. No lifecycle guard in this wrapper; authoring edits do not generally rebuild running hydraulic/geometry caches. Out-of-range indices succeed without mutation. Erases only the transect arrays; does not nullify/renumber referring link cross-sections. Use swmm_transect_delete() for cascaded reference repair.

◆ 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

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

Returns: SWMM_OK on success, or an error code.

Note: A null engine returns SWMM_ERR_BADHANDLE. A failed infrastructure/pollutant index check returns SWMM_ERR_BADINDEX. No lifecycle guard in this wrapper; authoring edits do not generally rebuild running hydraulic/geometry caches.

Here is the call graph for this function:

◆ 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

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

Returns: SWMM_OK on success, or an error code.

Note: A null engine returns SWMM_ERR_BADHANDLE. A failed infrastructure/pollutant index check returns SWMM_ERR_BADINDEX. No lifecycle guard in this wrapper; authoring edits do not generally rebuild running hydraulic/geometry caches. Numeric values are stored verbatim without finite/range validation.

◆ 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

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

Returns: SWMM_OK on success, or an error code.

Note: A null engine returns SWMM_ERR_BADHANDLE. A failed infrastructure/pollutant index check returns SWMM_ERR_BADINDEX. No lifecycle guard in this wrapper; authoring edits do not generally rebuild running hydraulic/geometry caches. Numeric values are stored verbatim without finite/range validation.

◆ 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

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

Returns: SWMM_OK on success, or an error code.

Note: A null engine returns SWMM_ERR_BADHANDLE. A failed infrastructure/pollutant index check returns SWMM_ERR_BADINDEX. No lifecycle guard in this wrapper; authoring edits do not generally rebuild running hydraulic/geometry caches. Numeric values are stored verbatim without finite/range validation.

◆ 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

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

Returns: SWMM_OK on success, or an error code.

Note: A null engine returns SWMM_ERR_BADHANDLE. A failed infrastructure/pollutant index check returns SWMM_ERR_BADINDEX. No lifecycle guard in this wrapper; authoring edits do not generally rebuild running hydraulic/geometry caches. Numeric values are stored verbatim without finite/range validation.

◆ 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

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

Returns: SWMM_OK on success, or an error code.

Note: A null engine returns SWMM_ERR_BADHANDLE. A failed infrastructure/pollutant index check returns SWMM_ERR_BADINDEX. No lifecycle guard in this wrapper; authoring edits do not generally rebuild running hydraulic/geometry caches. Numeric values are stored verbatim without finite/range validation.

Functions

Detailed Description

Function Documentation

◆ swmm_inlet_add()

◆ swmm_inlet_count()

◆ swmm_inlet_get_comment()

◆ swmm_inlet_get_design()

◆ swmm_inlet_get_params()

◆ swmm_inlet_get_type()

◆ swmm_inlet_id()

◆ swmm_inlet_index()

◆ swmm_inlet_rename()

◆ swmm_inlet_set_comment()

◆ swmm_inlet_set_design()

◆ swmm_inlet_set_params()

◆ swmm_inlet_usage_count()

◆ swmm_inlet_usage_find_link()

◆ swmm_inlet_usage_find_node()

◆ swmm_inlet_usage_get()

◆ swmm_inlet_usage_remove()

◆ swmm_inlet_usage_set()

◆ swmm_lid_add()

◆ swmm_lid_count()

◆ swmm_lid_get_drain()

◆ swmm_lid_get_drainmat()

◆ swmm_lid_get_pavement()

◆ swmm_lid_get_removal()

◆ swmm_lid_get_soil()

◆ swmm_lid_get_storage()

◆ swmm_lid_get_surface()

◆ swmm_lid_get_type()

◆ swmm_lid_id()

◆ swmm_lid_index()

◆ swmm_lid_rename()

◆ swmm_lid_set_drain()

◆ swmm_lid_set_drainmat()

◆ swmm_lid_set_pavement()

◆ swmm_lid_set_removal()

◆ 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_rename()

◆ 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()