OpenSWMM Engine — Node C API. More...

#include "openswmm_engine.h"

Include dependency graph for openswmm_nodes.h:

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

Classes
struct	SWMM_OutfallExportReceipt

Typedefs
typedef enum SWMM_NodeType	SWMM_NodeType
	Node type classification.

typedef struct SWMM_OutfallExportReceipt	SWMM_OutfallExportReceipt

typedef enum SWMM_DividerType	SWMM_DividerType
	Flow divider method.

Enumerations
enum	SWMM_NodeType { SWMM_NODE_JUNCTION = 0 , SWMM_NODE_OUTFALL = 1 , SWMM_NODE_STORAGE = 2 , SWMM_NODE_DIVIDER = 3 }
	Node type classification. More...

enum	SWMM_StorageShape { SWMM_STORAGE_TABULAR = 0 , SWMM_STORAGE_FUNCTIONAL = 1 , SWMM_STORAGE_CYLINDRICAL = 2 , SWMM_STORAGE_CONICAL = 3 , SWMM_STORAGE_PARABOLOID , SWMM_STORAGE_PYRAMIDAL }
	Storage-unit surface-area relation codes. More...

enum	SWMM_DividerType { SWMM_DIVIDER_CUTOFF = 0 , SWMM_DIVIDER_OVERFLOW = 1 , SWMM_DIVIDER_TABULAR = 2 , SWMM_DIVIDER_WEIR = 3 }
	Flow divider method. More...

Functions
SWMM_ENGINE_API int	swmm_node_count (SWMM_Engine engine)
	Get the total number of nodes in the model.

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

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

SWMM_ENGINE_API int	swmm_node_get_export_receipt (SWMM_Engine engine, int idx, SWMM_OutfallExportReceipt receipt, double pollutant_amounts, int count)
	Read committed external 1D outfall exports without withdrawing water again.

SWMM_ENGINE_API int	swmm_node_add (SWMM_Engine engine, const char *id, int type)
	Add a new node to the model.

SWMM_ENGINE_API int	swmm_node_pop_last (SWMM_Engine engine, const char *id)
	Remove the most recently added node (undo-of-add).

SWMM_ENGINE_API int	swmm_node_set_invert_elev (SWMM_Engine engine, int idx, double elev)
	Set a node's invert elevation.

SWMM_ENGINE_API int	swmm_node_set_max_depth (SWMM_Engine engine, int idx, double depth)
	Set a node's maximum depth (distance from invert to crown).

SWMM_ENGINE_API int	swmm_node_set_surcharge_depth (SWMM_Engine engine, int idx, double depth)
	Set the allowed surcharge depth above the node's crown.

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

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

SWMM_ENGINE_API int	swmm_node_set_pond_area (SWMM_Engine engine, int idx, double area)
	Set the ponded surface area when depth exceeds the maximum.

SWMM_ENGINE_API int	swmm_node_set_initial_depth (SWMM_Engine engine, int idx, double depth)
	Set a node's initial water depth at simulation start.

SWMM_ENGINE_API int	swmm_node_set_rim_depth (SWMM_Engine engine, int idx, double depth)
	Set a node's rendering-only rim (ground) depth above the invert.

SWMM_ENGINE_API int	swmm_node_get_type (SWMM_Engine engine, int idx, int *type)
	Get the type of a node.

SWMM_ENGINE_API int	swmm_node_is_virtual (SWMM_Engine engine, int idx, int *is_virtual)
	Query whether a node is a virtual junction.

SWMM_ENGINE_API int	swmm_node_set_virtual (SWMM_Engine engine, int idx, int make_virtual)
	Set or clear a node's virtual-junction flag.

SWMM_ENGINE_API int	swmm_node_virtual_eligible (SWMM_Engine engine, int idx, int *rule_code)
	Dry-run check of the virtual-junction usage rules for a node.

SWMM_ENGINE_API int	swmm_node_is_inlet (SWMM_Engine engine, int idx, int *is_inlet)
	Read whether a node carries the inlet-junction marker.

SWMM_ENGINE_API int	swmm_node_inlet_eligible (SWMM_Engine engine, int idx, int for_drop_inlet, int *rule_code)
	Evaluate inlet-junction topology rules without changing the node.

SWMM_ENGINE_API int	swmm_node_set_inlet (SWMM_Engine engine, int idx, int make_inlet)
	Enable or disable inlet-junction authoring on an editable node.

SWMM_ENGINE_API int	swmm_node_get_invert_elev (SWMM_Engine engine, int idx, double *elev)
	Get a node's invert elevation.

SWMM_ENGINE_API int	swmm_node_get_max_depth (SWMM_Engine engine, int idx, double *depth)
	Get a node's maximum depth.

SWMM_ENGINE_API int	swmm_node_get_rim_depth (SWMM_Engine engine, int idx, double *depth)
	Get a node's rendering-only rim (ground) depth above the invert.

SWMM_ENGINE_API int	swmm_node_get_depth (SWMM_Engine engine, int idx, double *depth)
	Get the current water depth at a node.

SWMM_ENGINE_API int	swmm_node_set_depth (SWMM_Engine engine, int idx, double depth)
	Set the water depth at a node (runtime override).

SWMM_ENGINE_API int	swmm_node_get_head (SWMM_Engine engine, int idx, double *head)
	Get the current hydraulic head at a node (invert + depth).

SWMM_ENGINE_API int	swmm_node_get_volume (SWMM_Engine engine, int idx, double *volume)
	Get the current stored water volume at a node.

SWMM_ENGINE_API int	swmm_node_get_lateral_inflow (SWMM_Engine engine, int idx, double *inflow)
	Get the current lateral inflow at a node.

SWMM_ENGINE_API int	swmm_node_get_overflow (SWMM_Engine engine, int idx, double *overflow)
	Get the current overflow (flooding) rate at a node.

SWMM_ENGINE_API int	swmm_node_get_inflow (SWMM_Engine engine, int idx, double *inflow)
	Read the current assembled lateral-inflow field.

SWMM_ENGINE_API int	swmm_node_set_lateral_inflow (SWMM_Engine engine, int idx, double flow)
	Set a persistent runtime user lateral-inflow contribution.

SWMM_ENGINE_API int	swmm_node_set_quality_mass_flux (SWMM_Engine engine, int node_idx, int pollutant_idx, double mass_rate)
	Set a persistent additive runtime pollutant amount-rate contribution.

SWMM_ENGINE_API int	swmm_node_set_head_boundary (SWMM_Engine engine, int idx, double head)
	Set an outfall fixed-head boundary retained in its subtype row.

SWMM_ENGINE_API int	swmm_node_get_quality (SWMM_Engine engine, int node_idx, int pollutant_idx, double *conc)
	Get the pollutant concentration at a node.

SWMM_ENGINE_API int	swmm_node_set_storage_curve (SWMM_Engine engine, int idx, int curve_idx)
	Assign a storage curve (depth vs. area) to a storage node.

SWMM_ENGINE_API int	swmm_node_get_storage_curve (SWMM_Engine engine, int idx, int *curve_idx)
	Get the storage curve index assigned to a storage node.

SWMM_ENGINE_API int	swmm_node_set_storage_functional (SWMM_Engine engine, int idx, double a, double b, double c)
	Set functional storage parameters: Area = a * Depth^b + c.

SWMM_ENGINE_API int	swmm_node_get_storage_functional (SWMM_Engine engine, int idx, double a, double b, double *c)
	Get functional storage parameters.

SWMM_ENGINE_API int	swmm_node_set_storage_shape (SWMM_Engine engine, int idx, int shape)
	Set a storage node's surface-area relation.

SWMM_ENGINE_API int	swmm_node_get_storage_shape (SWMM_Engine engine, int idx, int *shape)
	Get a storage node's surface-area relation.

SWMM_ENGINE_API int	swmm_node_set_storage_geometry (SWMM_Engine engine, int idx, double p1, double p2, double p3)
	Set the raw dimensions of a geometric storage shape.

SWMM_ENGINE_API int	swmm_node_get_storage_geometry (SWMM_Engine engine, int idx, double p1, double p2, double *p3)
	Get the raw dimensions of a geometric storage shape.

SWMM_ENGINE_API int	swmm_node_set_storage_seep_rate (SWMM_Engine engine, int idx, double rate)
	Set a constant seepage (exfiltration) rate for a storage node.

SWMM_ENGINE_API int	swmm_node_get_storage_seep_rate (SWMM_Engine engine, int idx, double *rate)
	Get the constant seepage (exfiltration) rate of a storage node.

SWMM_ENGINE_API int	swmm_node_set_exfil_params (SWMM_Engine engine, int idx, double suction, double ksat, double imd)
	Set Green–Ampt exfiltration parameters for a storage node.

SWMM_ENGINE_API int	swmm_node_get_exfil_params (SWMM_Engine engine, int idx, double suction, double ksat, double *imd)
	Get Green–Ampt exfiltration parameters for a storage node.

SWMM_ENGINE_API int	swmm_node_set_outfall_type (SWMM_Engine engine, int idx, int type)
	Set the outfall boundary condition type.

SWMM_ENGINE_API int	swmm_node_get_outfall_type (SWMM_Engine engine, int idx, int *type)
	Get the outfall boundary condition type.

SWMM_ENGINE_API int	swmm_node_set_outfall_stage (SWMM_Engine engine, int idx, double stage)
	Set a fixed outfall stage (for FIXED type outfalls).

SWMM_ENGINE_API int	swmm_node_set_outfall_tidal (SWMM_Engine engine, int idx, int curve_idx)
	Assign a tidal curve to an outfall (for TIDAL type outfalls).

SWMM_ENGINE_API int	swmm_node_set_outfall_timeseries (SWMM_Engine engine, int idx, int ts_idx)
	Assign a time series to an outfall (for TIMESERIES type outfalls).

SWMM_ENGINE_API int	swmm_node_get_outfall_param (SWMM_Engine engine, int idx, double *param)
	Get the outfall stage parameter (fixed stage, or current computed stage).

SWMM_ENGINE_API int	swmm_node_get_outfall_tidal (SWMM_Engine engine, int idx, int *curve_idx)
	Get the tidal curve index assigned to a TIDAL outfall.

SWMM_ENGINE_API int	swmm_node_get_outfall_timeseries (SWMM_Engine engine, int idx, int *ts_idx)
	Get the time-series index assigned to a TIMESERIES outfall.

SWMM_ENGINE_API int	swmm_node_set_outfall_flap_gate (SWMM_Engine engine, int idx, int has_gate)
	Set whether a flap gate exists at the outfall.

SWMM_ENGINE_API int	swmm_node_get_outfall_flap_gate (SWMM_Engine engine, int idx, int *has_gate)
	Get whether a flap gate exists at the outfall.

SWMM_ENGINE_API int	swmm_node_set_divider_type (SWMM_Engine engine, int idx, int type)
	Set the divider method for a flow-divider node.

SWMM_ENGINE_API int	swmm_node_get_divider_type (SWMM_Engine engine, int idx, int *type)
	Get the divider method for a flow-divider node.

SWMM_ENGINE_API int	swmm_node_get_surcharge_depth (SWMM_Engine engine, int idx, double *depth)
	Get the surcharge depth above the node's crown.

SWMM_ENGINE_API int	swmm_node_get_ponded_area (SWMM_Engine engine, int idx, double *area)
	Get the ponded area at a node.

SWMM_ENGINE_API int	swmm_node_get_initial_depth (SWMM_Engine engine, int idx, double *depth)
	Get the initial depth at a node.

SWMM_ENGINE_API int	swmm_node_get_crown_elev (SWMM_Engine engine, int idx, double *elev)
	Get the crown elevation (invert + max depth) at a node.

SWMM_ENGINE_API int	swmm_node_get_full_volume (SWMM_Engine engine, int idx, double *vol)
	Get the full (maximum) stored volume at a node.

SWMM_ENGINE_API int	swmm_node_get_losses (SWMM_Engine engine, int idx, double *losses)
	Get the cumulative water losses at a node (evaporation + exfiltration).

SWMM_ENGINE_API int	swmm_node_get_outflow (SWMM_Engine engine, int idx, double *outflow)
	Get the total outflow from a node through downstream links.

SWMM_ENGINE_API int	swmm_node_get_degree (SWMM_Engine engine, int idx, int *degree)
	Get the degree (number of connected links) of a node.

SWMM_ENGINE_API int	swmm_node_get_stat_max_depth (SWMM_Engine engine, int idx, double *val)
	Get the maximum depth recorded at a node during the simulation.

SWMM_ENGINE_API int	swmm_node_get_stat_max_overflow (SWMM_Engine engine, int idx, double *val)
	Get the maximum overflow rate recorded at a node.

SWMM_ENGINE_API int	swmm_node_get_stat_vol_flooded (SWMM_Engine engine, int idx, double *val)
	Get the total flood volume at a node over the simulation.

SWMM_ENGINE_API int	swmm_node_get_stat_time_flooded (SWMM_Engine engine, int idx, double *val)
	Get the total time a node was flooded during the simulation.

SWMM_ENGINE_API int	swmm_node_get_depths_bulk (SWMM_Engine engine, double *buf, int count)
	Get depths for all nodes in a single call.

SWMM_ENGINE_API int	swmm_node_get_heads_bulk (SWMM_Engine engine, double *buf, int count)
	Get hydraulic heads for all nodes in a single call.

SWMM_ENGINE_API int	swmm_node_get_inflows_bulk (SWMM_Engine engine, double *buf, int count)
	Copy a prefix of the assembled lateral-inflow field.

SWMM_ENGINE_API int	swmm_node_get_overflows_bulk (SWMM_Engine engine, double *buf, int count)
	Get overflow rates for all nodes in a single call.

SWMM_ENGINE_API int	swmm_node_set_depths_bulk (SWMM_Engine engine, const double *buf, int count)
	Set depths for all nodes in a single call (runtime override).

SWMM_ENGINE_API int	swmm_node_set_lat_inflows_bulk (SWMM_Engine engine, const double *buf, int count)
	Overwrite a prefix of the current assembled lateral-inflow field.

SWMM_ENGINE_API int	swmm_node_get_quality_bulk (SWMM_Engine engine, int pollutant_idx, double *buf, int count)
	Get pollutant concentrations at all nodes for one pollutant.

SWMM_ENGINE_API int	swmm_node_get_volumes_bulk (SWMM_Engine engine, double *buf, int count)
	Get current stored volumes for all nodes in a single call.

SWMM_ENGINE_API int	swmm_node_get_outflows_bulk (SWMM_Engine engine, double *buf, int count)
	Get current outflows for all nodes in a single call.

SWMM_ENGINE_API int	swmm_node_get_losses_bulk (SWMM_Engine engine, double *buf, int count)
	Get accumulated node losses (exfil + evap) for all nodes in one call.

SWMM_ENGINE_API int	swmm_node_get_lateral_inflows_bulk (SWMM_Engine engine, double *buf, int count)
	Get current lateral inflows for all nodes in a single call.

SWMM_ENGINE_API int	swmm_node_get_ids_bulk (SWMM_Engine engine, char *buf, int stride, int count)
	Get node IDs for all nodes in a single call (stride-packed UTF-8).

SWMM_ENGINE_API int	swmm_node_set_outfall_route_to (SWMM_Engine engine, int idx, int subcatch_idx)
	Set an outfall route-to subcatchment index directly.

SWMM_ENGINE_API int	swmm_node_get_outfall_route_to (SWMM_Engine engine, int idx, int *subcatch_idx)
	Read the outfall route-to subcatchment index.

SWMM_ENGINE_API int	swmm_node_get_depth_from_volume (SWMM_Engine engine, int idx, double volume, double *depth)
	Evaluate node depth from a supplied display-unit water volume.

SWMM_ENGINE_API int	swmm_node_rename (SWMM_Engine engine, int idx, const char *newId)
	Rename a node in the editable name index.

SWMM_ENGINE_API int	swmm_node_get_tag (SWMM_Engine engine, int idx, char *buf, int buflen)
	Copy a node free-form tag.

SWMM_ENGINE_API int	swmm_node_set_tag (SWMM_Engine engine, int idx, const char *tag)
	Copy or clear a node free-form tag without changing topology.

Detailed Description

OpenSWMM Engine — Node C API.

Node add (BUILDING state), geometry setters, state get/set, lateral inflow injection (RUNNING), bulk access, quality.

See also: openswmm_engine.h

Author: Caleb Buahin caleb.nosp@m..bua.nosp@m.hin@g.nosp@m.mail.nosp@m..com

Copyright: Copyright (c) 2026 Caleb Buahin. All rights reserved.

License: Apache-2.0

Typedef Documentation

◆ SWMM_DividerType

typedef enum SWMM_DividerType SWMM_DividerType

Flow divider method.

Selects how a divider node splits inflow between its diversion link and its main outflow link. The value is stored in the per-node divider_type SoA array and only consulted when type[i] == SWMM_NODE_DIVIDER.

◆ SWMM_NodeType

typedef enum SWMM_NodeType SWMM_NodeType

Node type classification.

Every node in a SWMM model belongs to one of these types. The type governs which property setters/getters are valid and how the node participates in routing.

◆ SWMM_OutfallExportReceipt

typedef struct SWMM_OutfallExportReceipt SWMM_OutfallExportReceipt

Cumulative committed 1D outfall transfers, independent of REPORT_START. Positive exports have already left SWMM: consumers must not withdraw them again. Reverse water is retained separately and is not a one-way export. SI water is m3; heat is J relative to 0 degC using model rho/cp. Pollutant arrays use kg for MG/L and UG/L, and counts for #/L. Read units first. Flags: 1 external water, 2 LEGACY pollutant loads, 4 native heat. Route-to-subcatchment and native 2D-owned outfalls are refused. No MSX or ARD/LARD mass capability is implied by these receipts.

Enumeration Type Documentation

◆ SWMM_DividerType

enum SWMM_DividerType

Flow divider method.

Selects how a divider node splits inflow between its diversion link and its main outflow link. The value is stored in the per-node divider_type SoA array and only consulted when type[i] == SWMM_NODE_DIVIDER.

Enumerator
SWMM_DIVIDER_CUTOFF	Flow above cutoff is diverted.
SWMM_DIVIDER_OVERFLOW	Diverted flow = max link capacity exceedance.
SWMM_DIVIDER_TABULAR	Diverted flow looked up on a curve.
SWMM_DIVIDER_WEIR	Weir equation governs diversion.

◆ SWMM_NodeType

enum SWMM_NodeType

Node type classification.

Every node in a SWMM model belongs to one of these types. The type governs which property setters/getters are valid and how the node participates in routing.

Enumerator
SWMM_NODE_JUNCTION	Standard junction node.
SWMM_NODE_OUTFALL	Outfall boundary node.
SWMM_NODE_STORAGE	Storage unit (pond, tank, etc.).
SWMM_NODE_DIVIDER	Flow divider.

◆ SWMM_StorageShape

enum SWMM_StorageShape

Storage-unit surface-area relation codes.

Ordinals match the legacy solver's enum StorageType, so the same int is valid on both engines. The four geometric shapes take three raw dimensions (see swmm_node_set_storage_geometry); TABULAR takes a curve; FUNCTIONAL takes the a/b/c power-law coefficients.

Enumerator
SWMM_STORAGE_TABULAR	Area vs. depth from a curve.
SWMM_STORAGE_FUNCTIONAL	Area = c + a*d^b.
SWMM_STORAGE_CYLINDRICAL	Elliptical cylinder: p1 = major axis, p2 = minor axis.
SWMM_STORAGE_CONICAL	Elliptical cone: p1, p2 = base axes, p3 = side slope.
SWMM_STORAGE_PARABOLOID	Elliptical paraboloid: p1, p2 = top axes, p3 = height (≠ 0).
SWMM_STORAGE_PYRAMIDAL	Rectangular pyramid: p1 = length, p2 = width, p3 = side slope.

Function Documentation

◆ swmm_node_add()

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

Add a new node to the model.

The engine must be in SWMM_STATE_BUILDING (programmatic construction) or SWMM_STATE_OPENED (interactive editing after the .inp has been parsed). Returns SWMM_ERR_LIFECYCLE for any other state — once the simulation has been initialized, started, or run, the node-count invariant is baked into solver state and the engine must be closed + re-opened to accept new objects.

The node is appended to the model's node list and its index equals the previous count.

Parameters

[in]	engine	Engine handle.
[in]	id	Unique null-terminated identifier for the new node.
[in]	type	Node type (see SWMM_NodeType).

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

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

Here is the call graph for this function:

◆ swmm_node_count()

SWMM_ENGINE_API int swmm_node_count ( SWMM_Engine engine )

Get the total number of nodes in the model.

Parameters

[in] engine Engine handle.

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

◆ swmm_node_get_crown_elev()

SWMM_ENGINE_API int swmm_node_get_crown_elev	(	SWMM_Engine	engine,
		int	idx,
		double *	elev )

Get the crown elevation (invert + max depth) at a node.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based node index.
[out]	elev	Receives the crown elevation in project length units.

Returns: SWMM_OK on success, or an error code.

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

◆ swmm_node_get_degree()

SWMM_ENGINE_API int swmm_node_get_degree	(	SWMM_Engine	engine,
		int	idx,
		int *	degree )

Get the degree (number of connected links) of a node.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based node index.
[out]	degree	Receives the number of links connected to this node.

Returns: SWMM_OK on success, or an error code.

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

◆ swmm_node_get_depth()

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

Get the current water depth at a node.

Parameters

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

Returns: SWMM_OK on success, or an error code.

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

◆ swmm_node_get_depth_from_volume()

SWMM_ENGINE_API int swmm_node_get_depth_from_volume	(	SWMM_Engine	engine,
		int	idx,
		double	volume,
		double *	depth )

Evaluate node depth from a supplied display-unit water volume.

Uses the configured node subtype, storage coefficients/curve and project unit system. Does not change stored volume/depth or validate input finiteness in this wrapper.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access.
[in]	idx	Zero-based node index in [0,swmm_node_count(engine)).
[in]	volume	Water volume in project display volume units; converted internally before evaluating storage geometry.
[out]	depth	Optional destination for depth in project display length units; NULL skips the calculation.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADINDEX for invalid node index.

Here is the call graph for this function:

◆ swmm_node_get_depths_bulk()

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

Get depths for all nodes in a single call.

Parameters

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

Returns: SWMM_OK on success, or an error code.

Note: A null engine returns SWMM_ERR_BADHANDLE. A null buffer or nonpositive count returns SWMM_ERR_BADPARAM. Only min(count,node count) entries are copied; any buffer tail is unchanged.

◆ swmm_node_get_divider_type()

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

Get the divider method for a flow-divider node.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based node index.
[out]	type	Receives the divider type 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 node/pollutant index check returns SWMM_ERR_BADINDEX.

◆ swmm_node_get_exfil_params()

SWMM_ENGINE_API int swmm_node_get_exfil_params	(	SWMM_Engine	engine,
		int	idx,
		double *	suction,
		double *	ksat,
		double *	imd )

Get Green–Ampt exfiltration parameters for a storage node.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based node index.
[out]	suction	Receives the suction head.
[out]	ksat	Receives the saturated hydraulic conductivity.
[out]	imd	Receives the initial moisture deficit.

Returns: SWMM_OK on success, or an error code.

Note: suction may be NULL to suppress that output. ksat may be NULL to suppress that output. imd may be NULL to suppress that output. A null engine returns SWMM_ERR_BADHANDLE. A failed node/pollutant index check returns SWMM_ERR_BADINDEX.

◆ swmm_node_get_export_receipt()

SWMM_ENGINE_API int swmm_node_get_export_receipt	(	SWMM_Engine	engine,
		int	idx,
		SWMM_OutfallExportReceipt *	receipt,
		double *	pollutant_amounts,
		int	count )

Read committed external 1D outfall exports without withdrawing water again.

Requires an outfall with no route-to-subcatchment and no native surface-owned exchange. Cumulative committed transfers are independent of REPORT_START; exported water already left SWMM. Flags 1/2/4 indicate external water/LEGACY pollutant/native heat capability. No MSX or ARD/LARD amount capability is implied.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access.
[in]	idx	Zero-based node index in [0,swmm_node_count(engine)).
[out]	receipt	Non-null water/heat/availability record: exported and separately reversed water in m3, sensible heat in J relative to 0 degrees C using model rho/cp, and capability flags.
[out]	pollutant_amounts	Caller-owned array of count amounts in pollutant order; required only when count>0. MG/L and UG/L pollutants use kg; #/L uses counts.
[in]	count	Must equal the current model pollutant count exactly, including zero.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADINDEX for invalid node index. SWMM_ERR_BADPARAM refuses wrong outputs/count or ineligible node ownership; SWMM_ERR_LIFECYCLE indicates uninitialized receipt arrays.

◆ swmm_node_get_full_volume()

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

Get the full (maximum) stored volume at a node.

Parameters

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

Returns: SWMM_OK on success, or an error code.

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

◆ swmm_node_get_head()

SWMM_ENGINE_API int swmm_node_get_head	(	SWMM_Engine	engine,
		int	idx,
		double *	head )

Get the current hydraulic head at a node (invert + depth).

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based node index.
[out]	head	Receives the head in project length units.

Returns: SWMM_OK on success, or an error code.

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

◆ swmm_node_get_heads_bulk()

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

Get hydraulic heads for all nodes in a single call.

Parameters

[in]	engine	Engine handle.
[out]	buf	Caller-allocated buffer of at least `count` doubles.
[in]	count	Number of elements.

Returns: SWMM_OK on success, or an error code.

Note: A null engine returns SWMM_ERR_BADHANDLE. A null buffer or nonpositive count returns SWMM_ERR_BADPARAM. Only min(count,node count) entries are copied; any buffer tail is unchanged.

◆ swmm_node_get_ids_bulk()

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

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

Each ID is written into a fixed-size slot buf[i*stride .. i*stride+stride-1]. The ID is NUL-terminated within its slot; if the ID is longer than stride-1 bytes it is truncated and still NUL-terminated. The caller can recover each ID via strlen(buf + i*stride) (or equivalent UTF-8-safe slicing).

This is the Phase 3 alternative to looping swmm_node_id N times through the C ABI. A typical stride for SWMM node IDs is 32–64 bytes (SWMM IDs are limited to MAX_ID_CHARS = 31 in legacy); callers should choose a stride that comfortably accommodates the longest ID in their model.

Parameters

[in]	engine	Engine handle.
[out]	buf	Caller-allocated buffer of `stride*count` bytes.
[in]	stride	Per-ID slot size in bytes (must be > 1 to allow at least one character plus the NUL).
[in]	count	Number of IDs to read.

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

Example: int n = swmm_node_count(eng);

int stride = 64;

char* buf = calloc(n, stride);

swmm_node_get_ids_bulk(eng, buf, stride, n);

for (int i = 0; i < n; ++i) {

const char* id = buf + i * stride;

printf("node %d: %s\n", i, id);

}

swmm_node_get_ids_bulk
SWMM_ENGINE_API int swmm_node_get_ids_bulk(SWMM_Engine engine, char *buf, int stride, int count)
Get node IDs for all nodes in a single call (stride-packed UTF-8).
Definition openswmm_nodes_impl.cpp:681

swmm_node_count
SWMM_ENGINE_API int swmm_node_count(SWMM_Engine engine)
Get the total number of nodes in the model.
Definition openswmm_nodes_impl.cpp:55

See also: swmm_node_id

Since: 6.0.0

Note: A null engine returns SWMM_ERR_BADHANDLE. A null buffer or nonpositive count returns SWMM_ERR_BADPARAM. Only min(count,node count) entries are copied; any buffer tail is unchanged.

◆ swmm_node_get_inflow()

SWMM_ENGINE_API int swmm_node_get_inflow	(	SWMM_Engine	engine,
		int	idx,
		double *	inflow )

Read the current assembled lateral-inflow field.

Despite the historical name, this wrapper reads lat_flow only; upstream link contributions are not added. It is equivalent to swmm_node_get_lateral_inflow().

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access.
[in]	idx	Zero-based node index in [0,swmm_node_count(engine)).
[out]	inflow	Optional destination in project display flow units.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADINDEX for invalid node index.

◆ swmm_node_get_inflows_bulk()

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

Copy a prefix of the assembled lateral-inflow field.

Reads lat_flow only, without adding upstream link contributions; equivalent to swmm_node_get_lateral_inflows_bulk().

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access.
[out]	buf	Non-null caller-owned array of count doubles in project display flow units.
[in]	count	Positive capacity/requested prefix length; writes min(count,node count) values and leaves any remaining entries unchanged.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADPARAM for null buf/count<=0.

◆ swmm_node_get_initial_depth()

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

Get the initial depth at a node.

Parameters

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

Returns: SWMM_OK on success, or an error code.

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

◆ swmm_node_get_invert_elev()

SWMM_ENGINE_API int swmm_node_get_invert_elev	(	SWMM_Engine	engine,
		int	idx,
		double *	elev )

Get a node's invert elevation.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based node index.
[out]	elev	Receives the invert elevation in project length units.

Returns: SWMM_OK on success, or an error code.

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

◆ swmm_node_get_lateral_inflow()

SWMM_ENGINE_API int swmm_node_get_lateral_inflow	(	SWMM_Engine	engine,
		int	idx,
		double *	inflow )

Get the current lateral inflow at a node.

Lateral inflow is the externally applied flow (DWF, RDII, user inflows) as opposed to the total inflow which includes upstream link contributions.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based node index.
[out]	inflow	Receives the lateral inflow in project flow units.

Returns: SWMM_OK on success, or an error code.

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

◆ swmm_node_get_lateral_inflows_bulk()

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

Get current lateral inflows for all nodes in a single call.

Single-pass bulk variant of swmm_node_get_lateral_inflow. The matching setter is swmm_node_set_lat_inflows_bulk.

Parameters

[in]	engine	Engine handle.
[out]	buf	Caller-allocated buffer of at least `count` doubles.
[in]	count	Number of elements.

Returns: SWMM_OK on success, or an error code.

Since: 6.0.0

Note: A null engine returns SWMM_ERR_BADHANDLE. A null buffer or nonpositive count returns SWMM_ERR_BADPARAM. Only min(count,node count) entries are copied; any buffer tail is unchanged.

◆ swmm_node_get_losses()

SWMM_ENGINE_API int swmm_node_get_losses	(	SWMM_Engine	engine,
		int	idx,
		double *	losses )

Get the cumulative water losses at a node (evaporation + exfiltration).

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based node index.
[out]	losses	Receives the loss volume in project volume units.

Returns: SWMM_OK on success, or an error code.

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

◆ swmm_node_get_losses_bulk()

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

Get accumulated node losses (exfil + evap) for all nodes in one call.

Single-pass bulk variant of swmm_node_get_losses.

Parameters

[in]	engine	Engine handle.
[out]	buf	Caller-allocated buffer of at least `count` doubles.
[in]	count	Number of elements.

Returns: SWMM_OK on success, or an error code.

Since: 6.0.0

Note: A null engine returns SWMM_ERR_BADHANDLE. A null buffer or nonpositive count returns SWMM_ERR_BADPARAM. Only min(count,node count) entries are copied; any buffer tail is unchanged.

◆ swmm_node_get_max_depth()

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

Get a node's maximum depth.

Parameters

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

Returns: SWMM_OK on success, or an error code.

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

◆ swmm_node_get_outfall_flap_gate()

SWMM_ENGINE_API int swmm_node_get_outfall_flap_gate	(	SWMM_Engine	engine,
		int	idx,
		int *	has_gate )

Get whether a flap gate exists at the outfall.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based node index.
[out]	has_gate	Receives 1 if flap gate present, 0 otherwise.

Returns: SWMM_OK on success, or an error code.

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

◆ swmm_node_get_outfall_param()

SWMM_ENGINE_API int swmm_node_get_outfall_param	(	SWMM_Engine	engine,
		int	idx,
		double *	param )

Get the outfall stage parameter (fixed stage, or current computed stage).

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based node index.
[out]	param	Receives the outfall parameter value.

Returns: SWMM_OK on success, or an error code.

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

◆ swmm_node_get_outfall_route_to()

SWMM_ENGINE_API int swmm_node_get_outfall_route_to	(	SWMM_Engine	engine,
		int	idx,
		int *	subcatch_idx )

Read the outfall route-to subcatchment index.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access.
[in]	idx	Zero-based node index in [0,swmm_node_count(engine)).
[out]	subcatch_idx	Optional destination: stored subcatchment index, or -1 when unset/non-outfall.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADINDEX for invalid node index.

◆ swmm_node_get_outfall_tidal()

SWMM_ENGINE_API int swmm_node_get_outfall_tidal	(	SWMM_Engine	engine,
		int	idx,
		int *	curve_idx )

Get the tidal curve index assigned to a TIDAL outfall.

The outfall parameter slot is union-typed across stage / tidal-idx / ts-idx; this accessor returns the slot interpreted as a curve index only when the outfall is currently of TIDAL type. Returns SWMM_ERR_BADPARAM if the outfall type is not TIDAL, so the caller can distinguish "unassigned" from a genuine index of 0.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based node index.
[out]	curve_idx	Receives the zero-based curve index.

Returns: SWMM_OK on success; SWMM_ERR_BADPARAM if outfall type != TIDAL.

Note: A null engine returns SWMM_ERR_BADHANDLE. A failed node/pollutant index check returns SWMM_ERR_BADINDEX. curve_idx must be non-null and the outfall type must be TIDAL; otherwise returns SWMM_ERR_BADPARAM.

◆ swmm_node_get_outfall_timeseries()

SWMM_ENGINE_API int swmm_node_get_outfall_timeseries	(	SWMM_Engine	engine,
		int	idx,
		int *	ts_idx )

Get the time-series index assigned to a TIMESERIES outfall.

Symmetric to swmm_node_get_outfall_tidal. Returns SWMM_ERR_BADPARAM unless the outfall is currently of TIMESERIES type.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based node index.
[out]	ts_idx	Receives the zero-based time-series index.

Returns: SWMM_OK on success; SWMM_ERR_BADPARAM if outfall type != TIMESERIES.

Note: A null engine returns SWMM_ERR_BADHANDLE. A failed node/pollutant index check returns SWMM_ERR_BADINDEX. ts_idx must be non-null and the outfall type must be TIMESERIES; otherwise returns SWMM_ERR_BADPARAM.

◆ swmm_node_get_outfall_type()

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

Get the outfall boundary condition type.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based node index.
[out]	type	Receives the outfall type 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 node/pollutant index check returns SWMM_ERR_BADINDEX.

◆ swmm_node_get_outflow()

SWMM_ENGINE_API int swmm_node_get_outflow	(	SWMM_Engine	engine,
		int	idx,
		double *	outflow )

Get the total outflow from a node through downstream links.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based node index.
[out]	outflow	Receives the outflow in project flow units.

Returns: SWMM_OK on success, or an error code.

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

◆ swmm_node_get_outflows_bulk()

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

Get current outflows for all nodes in a single call.

Single-pass bulk variant of swmm_node_get_outflow.

Parameters

[in]	engine	Engine handle.
[out]	buf	Caller-allocated buffer of at least `count` doubles.
[in]	count	Number of elements.

Returns: SWMM_OK on success, or an error code (see swmm_node_get_volumes_bulk).

Since: 6.0.0

Note: A null engine returns SWMM_ERR_BADHANDLE. A null buffer or nonpositive count returns SWMM_ERR_BADPARAM. Only min(count,node count) entries are copied; any buffer tail is unchanged.

◆ swmm_node_get_overflow()

SWMM_ENGINE_API int swmm_node_get_overflow	(	SWMM_Engine	engine,
		int	idx,
		double *	overflow )

Get the current overflow (flooding) rate at a node.

Overflow occurs when the water depth exceeds the node's maximum depth and ponding is not enabled (or the ponded area is exceeded).

Parameters

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

Returns: SWMM_OK on success, or an error code.

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

◆ swmm_node_get_overflows_bulk()

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

Get overflow rates for all nodes in a single call.

Parameters

[in]	engine	Engine handle.
[out]	buf	Caller-allocated buffer of at least `count` doubles.
[in]	count	Number of elements.

Returns: SWMM_OK on success, or an error code.

Note: A null engine returns SWMM_ERR_BADHANDLE. A null buffer or nonpositive count returns SWMM_ERR_BADPARAM. Only min(count,node count) entries are copied; any buffer tail is unchanged.

◆ swmm_node_get_ponded_area()

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

Get the ponded area at a node.

Parameters

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

Returns: SWMM_OK on success, or an error code.

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

Here is the call graph for this function:

◆ swmm_node_get_quality()

SWMM_ENGINE_API int swmm_node_get_quality	(	SWMM_Engine	engine,
		int	node_idx,
		int	pollutant_idx,
		double *	conc )

Get the pollutant concentration at a node.

Parameters

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

Returns: SWMM_OK on success, or an error code.

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

◆ swmm_node_get_quality_bulk()

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

Get pollutant concentrations at all nodes for one pollutant.

Parameters

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

Returns: SWMM_OK on success, or an error code.

Note: A null engine returns SWMM_ERR_BADHANDLE. A failed node/pollutant index check returns SWMM_ERR_BADINDEX. A null buffer or nonpositive count returns SWMM_ERR_BADPARAM. Only min(count,node count) entries are copied; any buffer tail is unchanged.

◆ swmm_node_get_rim_depth()

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

Get a node's rendering-only rim (ground) depth above the invert.

See swmm_node_set_rim_depth(). 0 means unset: a renderer drawing a ground line should fall back to swmm_node_get_max_depth(), which for a virtual junction is the pipe crown.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based node index.
[out]	depth	Receives the rim depth in project length units, or 0.

Returns: SWMM_OK on success, or an error code.

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

◆ swmm_node_get_stat_max_depth()

SWMM_ENGINE_API int swmm_node_get_stat_max_depth	(	SWMM_Engine	engine,
		int	idx,
		double *	val )

Get the maximum depth recorded at a node during the simulation.

Parameters

[in]	engine	Engine handle (ENDED or RUNNING state).
[in]	idx	Zero-based node index.
[out]	val	Receives the maximum depth in project length units.

Returns: SWMM_OK on success, or an error code.

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

◆ swmm_node_get_stat_max_overflow()

SWMM_ENGINE_API int swmm_node_get_stat_max_overflow	(	SWMM_Engine	engine,
		int	idx,
		double *	val )

Get the maximum overflow rate recorded at a node.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based node index.
[out]	val	Receives the maximum overflow in project flow units.

Returns: SWMM_OK on success, or an error code.

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

◆ swmm_node_get_stat_time_flooded()

SWMM_ENGINE_API int swmm_node_get_stat_time_flooded	(	SWMM_Engine	engine,
		int	idx,
		double *	val )

Get the total time a node was flooded during the simulation.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based node index.
[out]	val	Receives the flooded duration in seconds.

Returns: SWMM_OK on success, or an error code.

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

◆ swmm_node_get_stat_vol_flooded()

SWMM_ENGINE_API int swmm_node_get_stat_vol_flooded	(	SWMM_Engine	engine,
		int	idx,
		double *	val )

Get the total flood volume at a node over the simulation.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based node index.
[out]	val	Receives the flooded volume in project volume units.

Returns: SWMM_OK on success, or an error code.

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

◆ swmm_node_get_storage_area()

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

Read authored junction storage area in project area units (ft2 or m2) (zero by default).

Here is the call graph for this function:

◆ swmm_node_get_storage_curve()

SWMM_ENGINE_API int swmm_node_get_storage_curve	(	SWMM_Engine	engine,
		int	idx,
		int *	curve_idx )

Get the storage curve index assigned to a storage node.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based node index.
[out]	curve_idx	Receives the curve index, or -1 if functional.

Returns: SWMM_OK on success, or an error code.

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

◆ swmm_node_get_storage_functional()

SWMM_ENGINE_API int swmm_node_get_storage_functional	(	SWMM_Engine	engine,
		int	idx,
		double *	a,
		double *	b,
		double *	c )

Get functional storage parameters.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based node index.
[out]	a	Receives coefficient a.
[out]	b	Receives exponent b.
[out]	c	Receives constant c.

Returns: SWMM_OK on success, or an error code.

Note: a may be NULL to suppress that output. b may be NULL to suppress that output. c may be NULL to suppress that output. A null engine returns SWMM_ERR_BADHANDLE. A failed node/pollutant index check returns SWMM_ERR_BADINDEX.

◆ swmm_node_get_storage_geometry()

SWMM_ENGINE_API int swmm_node_get_storage_geometry	(	SWMM_Engine	engine,
		int	idx,
		double *	p1,
		double *	p2,
		double *	p3 )

Get the raw dimensions of a geometric storage shape.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based node index.
[out]	p1	Receives the major axis / base length.
[out]	p2	Receives the minor axis / base width.
[out]	p3	Receives the side slope / height.

Returns: SWMM_OK on success, or an error code. Returns zeros for a non-geometric shape.

Note: p1 may be NULL to suppress that output. p2 may be NULL to suppress that output. p3 may be NULL to suppress that output. A null engine returns SWMM_ERR_BADHANDLE. A failed node/pollutant index check returns SWMM_ERR_BADINDEX.

◆ swmm_node_get_storage_seep_rate()

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

Get the constant seepage (exfiltration) rate of a storage node.

The exfiltration Ksat when exfiltration uses its constant-rate form (zero suction and IMD); 0 when it uses Green-Ampt parameters or is off, and for a node that is not storage.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based node index.
[out]	rate	Receives the rate, in/hr (US) or mm/hr (SI).

Returns: SWMM_OK on success, or an error code.

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

◆ swmm_node_get_storage_shape()

SWMM_ENGINE_API int swmm_node_get_storage_shape	(	SWMM_Engine	engine,
		int	idx,
		int *	shape )

Get a storage node's surface-area relation.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based node index.
[out]	shape	Receives a SWMM_StorageShape code.

Returns: SWMM_OK on success, or an error code.

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

◆ swmm_node_get_surcharge_depth()

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

Get the surcharge depth above the node's crown.

Parameters

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

Returns: SWMM_OK on success, or an error code.

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

◆ swmm_node_get_tag()

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

Copy a node free-form tag.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access.
[in]	idx	Zero-based node index in [0,swmm_node_count(engine)).
[out]	buf	Non-null caller-owned text buffer; empty when no tag exists, NUL-terminated and silently truncated to buflen-1 bytes.
[in]	buflen	Positive buffer capacity in bytes including NUL.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADINDEX for invalid node index. SWMM_ERR_BADPARAM for null buf/nonpositive capacity.

◆ swmm_node_get_type()

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

Get the type of a node.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based node index.
[out]	type	Receives the node type (see SWMM_NodeType).

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 node/pollutant index check returns SWMM_ERR_BADINDEX.

Here is the call graph for this function:

◆ swmm_node_get_volume()

SWMM_ENGINE_API int swmm_node_get_volume	(	SWMM_Engine	engine,
		int	idx,
		double *	volume )

Get the current stored water volume at a node.

Parameters

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

Returns: SWMM_OK on success, or an error code.

Note: volume may be NULL to suppress that output. A null engine returns SWMM_ERR_BADHANDLE. A failed node/pollutant index check returns SWMM_ERR_BADINDEX. Includes active storage-node LID held water in addition to the node water volume.

Here is the call graph for this function:

◆ swmm_node_get_volumes_bulk()

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

Get current stored volumes for all nodes in a single call.

Single-pass bulk variant of swmm_node_get_volume — avoids N round-trips through the C ABI for whole-network reads. Used by the MCP server's per-node info builders and the mass_balance resource.

Parameters

[in]	engine	Engine handle.
[out]	buf	Caller-allocated buffer of at least `count` doubles.
[in]	count	Number of elements. If smaller than `swmm_node_count()` only the first `min(count, n_nodes)` entries are written.

Returns: SWMM_OK on success; SWMM_ERR_BADHANDLE if engine is invalid; SWMM_ERR_BADPARAM if buf is NULL or count <= 0.

Since: 6.0.0

Note: A null engine returns SWMM_ERR_BADHANDLE. A null buffer or nonpositive count returns SWMM_ERR_BADPARAM. Only min(count,node count) entries are copied; any buffer tail is unchanged. Includes active storage-node LID held water in addition to the node water volume.

Here is the call graph for this function:

◆ swmm_node_id()

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

Get the string identifier of a node by index.

Parameters

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

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

Note: Borrowed ID storage may be invalidated by name/topology edits, close/reopen or engine destruction; copy it when retaining it across operations.

◆ swmm_node_index()

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

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

Parameters

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

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

◆ swmm_node_inlet_eligible()

SWMM_ENGINE_API int swmm_node_inlet_eligible	(	SWMM_Engine	engine,
		int	idx,
		int	for_drop_inlet,
		int *	rule_code )

Evaluate inlet-junction topology rules without changing the node.

A topology refusal is reported in rule_code while the API returns SWMM_OK; inspect the code separately.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access.
[in]	idx	Zero-based node index in [0,swmm_node_count(engine)).
[in]	for_drop_inlet	0 evaluates the street-inlet profile; nonzero evaluates drop-inlet eligibility.
[out]	rule_code	Optional destination: 0 for eligible, otherwise the specific inlet/virtual-junction validation code.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADINDEX for invalid node index.

Here is the call graph for this function:

◆ swmm_node_is_inlet()

SWMM_ENGINE_API int swmm_node_is_inlet	(	SWMM_Engine	engine,
		int	idx,
		int *	is_inlet )

Read whether a node carries the inlet-junction marker.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access.
[in]	idx	Zero-based node index in [0,swmm_node_count(engine)).
[out]	is_inlet	Optional destination: 1 when marked inlet, otherwise 0.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADINDEX for invalid node index.

◆ swmm_node_is_virtual()

SWMM_ENGINE_API int swmm_node_is_virtual	(	SWMM_Engine	engine,
		int	idx,
		int *	is_virtual )

Query whether a node is a virtual junction.

A virtual junction is a zero-storage, momentum-transmitting JUNCTION-typed node connecting exactly two conduits of identical cross-section (INP section [VIRTUAL_JUNCTIONS]; refactored engine only).

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based node index.
[out]	is_virtual	Receives 1 if the node is a virtual junction, else 0.

Returns: SWMM_OK on success, or an error code.

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

◆ swmm_node_pop_last()

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

Remove the most recently added node (undo-of-add).

Pops the tail of the node list. The engine must be in SWMM_STATE_BUILDING or SWMM_STATE_OPENED. Returns SWMM_ERR_BADINDEX if the tail doesn't match id (guards against undo / redo order mismatches), SWMM_ERR_BADPARAM if any link references the tail node (the caller must cascade those removals first via swmm_link_pop_last), or SWMM_ERR_LIFECYCLE for any other state.

This is an intentionally narrow surface that avoids renumbering any cross-references; for a general swmm_node_remove(idx) see the engine roadmap — full remove requires renumbering every link / subcatch / control / report reference and is tracked separately.

Parameters

[in]	engine	Engine handle.
[in]	id	Expected tail identifier (null-terminated).

Returns: SWMM_OK on success, or an error code.

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

◆ swmm_node_rename()

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

Rename a node in the editable name index.

Keeps numeric node indices. Borrowed ID pointers can be invalidated; the wrapper changes the name index and does not itself rewrite arbitrary stored text references.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access.
[in]	idx	Zero-based node index in [0,swmm_node_count(engine)).
[in]	newId	Non-null, nonempty NUL-terminated new ID; copied internally and required to be unique in the node index.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADINDEX for invalid node index. SWMM_ERR_LIFECYCLE outside BUILDING/OPENED or SWMM_ERR_BADPARAM for invalid/duplicate ID.

◆ swmm_node_set_depth()

SWMM_ENGINE_API int swmm_node_set_depth	(	SWMM_Engine	engine,
		int	idx,
		double	depth )

Set the water depth at a node (runtime override).

Parameters

[in]	engine	Engine handle (RUNNING state).
[in]	idx	Zero-based node index.
[in]	depth	New depth in project length units.

Returns: SWMM_OK on success, or an error code.

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

◆ swmm_node_set_depths_bulk()

SWMM_ENGINE_API int swmm_node_set_depths_bulk	(	SWMM_Engine	engine,
		const double *	buf,
		int	count )

Set depths for all nodes in a single call (runtime override).

Parameters

[in]	engine	Engine handle (RUNNING state).
[in]	buf	Array of depth values, one per node.
[in]	count	Number of elements (should equal swmm_node_count()).

Returns: SWMM_OK on success, or an error code.

Note: Requires RUNNING; other states return SWMM_ERR_LIFECYCLE. A null engine returns SWMM_ERR_BADHANDLE. A null buffer or nonpositive count returns SWMM_ERR_BADPARAM. Only min(count,node count) entries are copied; any buffer tail is unchanged.

◆ swmm_node_set_divider_type()

SWMM_ENGINE_API int swmm_node_set_divider_type	(	SWMM_Engine	engine,
		int	idx,
		int	type )

Set the divider method for a flow-divider node.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based node index (must be SWMM_NODE_DIVIDER).
[in]	type	Divider type code (see SWMM_DividerType).

Returns: SWMM_OK on success, or an error code.

Note: Requires BUILDING or OPENED; other states return SWMM_ERR_LIFECYCLE. A null engine returns SWMM_ERR_BADHANDLE. A failed node/pollutant index check returns SWMM_ERR_BADINDEX. For an existing node with no matching subtype row, the subtype assignment is a successful no-op.

◆ swmm_node_set_exfil_params()

SWMM_ENGINE_API int swmm_node_set_exfil_params	(	SWMM_Engine	engine,
		int	idx,
		double	suction,
		double	ksat,
		double	imd )

Set Green–Ampt exfiltration parameters for a storage node.

Exfiltration models soil infiltration losses from the bottom and banks of a storage unit using the Green–Ampt method.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based node index (must be SWMM_NODE_STORAGE).
[in]	suction	Soil capillary suction head (project length units).
[in]	ksat	Saturated hydraulic conductivity (project length/time).
[in]	imd	Initial moisture deficit (fraction: 0–1).

Returns: SWMM_OK on success, or an error code.

Note: Requires BUILDING or OPENED; other states return SWMM_ERR_LIFECYCLE. A null engine returns SWMM_ERR_BADHANDLE. A failed node/pollutant index check returns SWMM_ERR_BADINDEX. For an existing node with no matching subtype row, the subtype assignment is a successful no-op.

◆ swmm_node_set_head_boundary()

SWMM_ENGINE_API int swmm_node_set_head_boundary	(	SWMM_Engine	engine,
		int	idx,
		double	head )

Set an outfall fixed-head boundary retained in its subtype row.

Sets the outfall type to FIXED and stores its stage parameter; it is not automatically reset after one step. Does not check input finiteness or supply a per-boundary clear operation.

Parameters

[in]	engine	Non-null RUNNING engine.
[in]	idx	Zero-based node index in [0,swmm_node_count(engine)).
[in]	head	Datum head in project display length units, converted to internal length.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADINDEX for invalid node index. SWMM_ERR_LIFECYCLE outside RUNNING or SWMM_ERR_BADPARAM for a non-outfall.

◆ swmm_node_set_initial_depth()

SWMM_ENGINE_API int swmm_node_set_initial_depth	(	SWMM_Engine	engine,
		int	idx,
		double	depth )

Set a node's initial water depth at simulation start.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based node index.
[in]	depth	Initial depth in project length units.

Returns: SWMM_OK on success, or an error code.

Note: Sets the authored initial condition, which swmm_node_get_initial_depth() reads, the .inp writer saves and initialization turns into the starting depth, head and volume. Requires BUILDING or OPENED: after initialization the starting state already exists, so other states return SWMM_ERR_LIFECYCLE (swmm_node_set_depth() changes a running depth). A null engine returns SWMM_ERR_BADHANDLE. A failed node index check returns SWMM_ERR_BADINDEX.

◆ swmm_node_set_inlet()

SWMM_ENGINE_API int swmm_node_set_inlet	(	SWMM_Engine	engine,
		int	idx,
		int	make_inlet )

Enable or disable inlet-junction authoring on an editable node.

Validates through the inlet-junction edit helper before applying the requested marker. Treat a nonzero returned rule code as a refused edit.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access.
[in]	idx	Zero-based node index in [0,swmm_node_count(engine)).
[in]	make_inlet	0 clears the marker; nonzero requests inlet conversion under current topology rules.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADINDEX for invalid node index. SWMM_ERR_LIFECYCLE outside BUILDING/OPENED; SWMM_ERR_BADPARAM for a non-junction target, or a specific inlet/virtual-junction rule code.

Here is the call graph for this function:

◆ swmm_node_set_invert_elev()

SWMM_ENGINE_API int swmm_node_set_invert_elev	(	SWMM_Engine	engine,
		int	idx,
		double	elev )

Set a node's invert elevation.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based node index.
[in]	elev	Invert elevation in project length units.

Returns: SWMM_OK on success, or an error code.

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

◆ swmm_node_set_lat_inflows_bulk()

SWMM_ENGINE_API int swmm_node_set_lat_inflows_bulk	(	SWMM_Engine	engine,
		const double *	buf,
		int	count )

Overwrite a prefix of the current assembled lateral-inflow field.

Writes lat_flow directly, unlike the persistent user_lat_flow scalar setter. Subsequent inflow assembly may replace these values. Does not check finite values or promise a persistent forcing prescription.

Parameters

[in]	engine	Non-null RUNNING engine.
[in]	buf	Non-null borrowed array of count project display flow values, converted and copied synchronously.
[in]	count	Positive requested prefix length; uses min(count,node count).

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_LIFECYCLE outside RUNNING or SWMM_ERR_BADPARAM for null buf/count<=0.

◆ swmm_node_set_lateral_inflow()

SWMM_ENGINE_API int swmm_node_set_lateral_inflow	(	SWMM_Engine	engine,
		int	idx,
		double	flow )

Set a persistent runtime user lateral-inflow contribution.

Stores user_lat_flow, not the current assembled lat_flow. Runtime forcing OVERRIDE/ADD can overlay it; ordinary DWF/RDII/input contributions are assembled separately. The value persists across steps and does not replace all authored inflows. No finite/range validation is applied.

Parameters

[in]	engine	Non-null RUNNING engine.
[in]	idx	Zero-based node index in [0,swmm_node_count(engine)).
[in]	flow	Signed project display flow, converted to internal flow and retained until changed; zero stops this contribution.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADINDEX for invalid node index. SWMM_ERR_LIFECYCLE outside RUNNING.

◆ swmm_node_set_max_depth()

SWMM_ENGINE_API int swmm_node_set_max_depth	(	SWMM_Engine	engine,
		int	idx,
		double	depth )

Set a node's maximum depth (distance from invert to crown).

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based node index.
[in]	depth	Maximum depth in project length units.

Returns: SWMM_OK on success, or an error code.

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

◆ swmm_node_set_outfall_flap_gate()

SWMM_ENGINE_API int swmm_node_set_outfall_flap_gate	(	SWMM_Engine	engine,
		int	idx,
		int	has_gate )

Set whether a flap gate exists at the outfall.

A flap gate prevents reverse flow through the outfall.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based node index (must be SWMM_NODE_OUTFALL).
[in]	has_gate	Non-zero to enable flap gate; zero to disable.

Returns: SWMM_OK on success, or an error code.

Note: Requires BUILDING or OPENED; other states return SWMM_ERR_LIFECYCLE. A null engine returns SWMM_ERR_BADHANDLE. A failed node/pollutant index check returns SWMM_ERR_BADINDEX. For an existing node with no matching subtype row, the subtype assignment is a successful no-op.

◆ swmm_node_set_outfall_route_to()

SWMM_ENGINE_API int swmm_node_set_outfall_route_to	(	SWMM_Engine	engine,
		int	idx,
		int	subcatch_idx )

Set an outfall route-to subcatchment index directly.

No lifecycle guard is imposed. For a valid node without an outfall subtype this is a successful no-op; it does not convert the node into an outfall.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access.
[in]	idx	Zero-based node index in [0,swmm_node_count(engine)).
[in]	subcatch_idx	Subcatchment index to store, or -1 for no routing. This wrapper does not validate the supplied subcatchment index.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADINDEX for invalid node index.

◆ swmm_node_set_outfall_stage()

SWMM_ENGINE_API int swmm_node_set_outfall_stage	(	SWMM_Engine	engine,
		int	idx,
		double	stage )

Set a fixed outfall stage (for FIXED type outfalls).

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based node index (must be SWMM_NODE_OUTFALL).
[in]	stage	Fixed stage elevation in project length units.

Returns: SWMM_OK on success, or an error code.

Note: Requires BUILDING or OPENED; other states return SWMM_ERR_LIFECYCLE. A null engine returns SWMM_ERR_BADHANDLE. A failed node/pollutant index check returns SWMM_ERR_BADINDEX. For an existing node with no matching subtype row, the subtype assignment is a successful no-op.

◆ swmm_node_set_outfall_tidal()

SWMM_ENGINE_API int swmm_node_set_outfall_tidal	(	SWMM_Engine	engine,
		int	idx,
		int	curve_idx )

Assign a tidal curve to an outfall (for TIDAL type outfalls).

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based node index (must be SWMM_NODE_OUTFALL).
[in]	curve_idx	Zero-based curve index defining hour-of-day vs. stage.

Returns: SWMM_OK on success, or an error code.

Note: Requires BUILDING or OPENED; other states return SWMM_ERR_LIFECYCLE. A null engine returns SWMM_ERR_BADHANDLE. A failed node/pollutant index check returns SWMM_ERR_BADINDEX. For an existing node with no matching subtype row, the subtype assignment is a successful no-op.

◆ swmm_node_set_outfall_timeseries()

SWMM_ENGINE_API int swmm_node_set_outfall_timeseries	(	SWMM_Engine	engine,
		int	idx,
		int	ts_idx )

Assign a time series to an outfall (for TIMESERIES type outfalls).

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based node index (must be SWMM_NODE_OUTFALL).
[in]	ts_idx	Zero-based time series index defining time vs. stage.

Returns: SWMM_OK on success, or an error code.

Note: Requires BUILDING or OPENED; other states return SWMM_ERR_LIFECYCLE. A null engine returns SWMM_ERR_BADHANDLE. A failed node/pollutant index check returns SWMM_ERR_BADINDEX. For an existing node with no matching subtype row, the subtype assignment is a successful no-op.

◆ swmm_node_set_outfall_type()

SWMM_ENGINE_API int swmm_node_set_outfall_type	(	SWMM_Engine	engine,
		int	idx,
		int	type )

Set the outfall boundary condition type.

Common types: 0=FREE, 1=NORMAL, 2=FIXED, 3=TIDAL, 4=TIMESERIES.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based node index (must be SWMM_NODE_OUTFALL).
[in]	type	Outfall type code.

Returns: SWMM_OK on success, or an error code.

Note: Requires BUILDING or OPENED; other states return SWMM_ERR_LIFECYCLE. A null engine returns SWMM_ERR_BADHANDLE. A failed node/pollutant index check returns SWMM_ERR_BADINDEX. For an existing node with no matching subtype row, the subtype assignment is a successful no-op.

◆ swmm_node_set_pond_area()

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

Set the ponded surface area when depth exceeds the maximum.

When ponding is modeled, excess water is stored on the surface using this area. Set to 0 to disable ponding at this node.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based node index.
[in]	area	Ponded area in project area units (e.g., ft² or m²).

Returns: SWMM_OK on success, or an error code.

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

Here is the call graph for this function:

◆ swmm_node_set_quality_mass_flux()

SWMM_ENGINE_API int swmm_node_set_quality_mass_flux	(	SWMM_Engine	engine,
		int	node_idx,
		int	pollutant_idx,
		double	mass_rate )

Set a persistent additive runtime pollutant amount-rate contribution.

Persists until replaced, then contributes at routing steps. Negative extraction is subject to the quality loader available-mass clamp; this setter itself does not validate a finite/range value.

Parameters

[in]	engine	Non-null RUNNING engine.
[in]	node_idx	Zero-based existing node index.
[in]	pollutant_idx	Zero-based existing pollutant index.
[in]	mass_rate	Raw internal concentration-unit*ft3/s amount rate; passed to the quality loader without a project-mass conversion. Zero stops the retained contribution.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_LIFECYCLE outside RUNNING or SWMM_ERR_BADINDEX for invalid node/pollutant.

◆ swmm_node_set_rim_depth()

SWMM_ENGINE_API int swmm_node_set_rim_depth	(	SWMM_Engine	engine,
		int	idx,
		double	depth )

Set a node's rendering-only rim (ground) depth above the invert.

RENDERING ONLY — no hydraulics, routing, reporting or output-file code reads this value, so setting it can never change a result. It exists for virtual junctions, whose max depth is derived (always the shared pipe crown): without it every viewer drawing a ground line collapses the surface to the crown at each break point. It is the optional third token of a [VIRTUAL_JUNCTIONS] row.

On other node types the value is simply carried; renderers use the real max depth there. Pass 0 to clear it ("unset" — renderers fall back to the max depth). Negative values are clamped to 0.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based node index.
[in]	depth	Rim depth above the invert in project length units.

Returns: SWMM_OK on success, or an error code.

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

◆ swmm_node_set_storage_area()

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

Physical ordinary-junction chamber area in project area units (ft2 or m2). Zero retains legacy behavior. Geometry edits only; nonfinite/negative values and virtual/inlet/nonjunction assignments fail.

Here is the call graph for this function:

◆ swmm_node_set_storage_curve()

SWMM_ENGINE_API int swmm_node_set_storage_curve	(	SWMM_Engine	engine,
		int	idx,
		int	curve_idx )

Assign a storage curve (depth vs. area) to a storage node.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based node index (must be SWMM_NODE_STORAGE).
[in]	curve_idx	Zero-based curve index (from swmm_curve_add()).

Returns: SWMM_OK on success, or an error code.

Note: Requires BUILDING or OPENED; other states return SWMM_ERR_LIFECYCLE. A null engine returns SWMM_ERR_BADHANDLE. A failed node/pollutant index check returns SWMM_ERR_BADINDEX. For an existing node with no matching subtype row, the subtype assignment is a successful no-op.

◆ swmm_node_set_storage_functional()

SWMM_ENGINE_API int swmm_node_set_storage_functional	(	SWMM_Engine	engine,
		int	idx,
		double	a,
		double	b,
		double	c )

Set functional storage parameters: Area = a * Depth^b + c.

Defines the depth–area relationship using a power-law equation instead of a tabular curve.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based node index (must be SWMM_NODE_STORAGE).
[in]	a	Coefficient a.
[in]	b	Exponent b.
[in]	c	Constant c.

Returns: SWMM_OK on success, or an error code.

Note: Requires BUILDING or OPENED; other states return SWMM_ERR_LIFECYCLE. A null engine returns SWMM_ERR_BADHANDLE. A failed node/pollutant index check returns SWMM_ERR_BADINDEX. For an existing node with no matching subtype row, the subtype assignment is a successful no-op.

◆ swmm_node_set_storage_geometry()

SWMM_ENGINE_API int swmm_node_set_storage_geometry	(	SWMM_Engine	engine,
		int	idx,
		double	p1,
		double	p2,
		double	p3 )

Set the raw dimensions of a geometric storage shape.

Meaning of p1/p2/p3 depends on the node's current shape — see SWMM_StorageShape. The engine stores the raw dimensions (so they survive a write back to .inp) and derives the area coefficients from them. The call is atomic: if the dimensions are invalid nothing is written.

Validity (mirrors the legacy solver): p1 > 0, p2 > 0, p3 >= 0, and p3 != 0 for SWMM_STORAGE_PARABOLOID.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based node index (must be SWMM_NODE_STORAGE).
[in]	p1	Major axis / base length.
[in]	p2	Minor axis / base width.
[in]	p3	Side slope (run/rise), or height for SWMM_STORAGE_PARABOLOID.

Returns: SWMM_OK on success; SWMM_ERR_BADPARAM if the node's shape is not geometric or the dimensions are invalid.

Note: Requires BUILDING or OPENED; other states return SWMM_ERR_LIFECYCLE. A null engine returns SWMM_ERR_BADHANDLE. A failed node/pollutant index check returns SWMM_ERR_BADINDEX. For an existing node with no matching subtype row, the subtype assignment is a successful no-op.

Here is the call graph for this function:

◆ swmm_node_set_storage_seep_rate()

SWMM_ENGINE_API int swmm_node_set_storage_seep_rate	(	SWMM_Engine	engine,
		int	idx,
		double	rate )

Set a constant seepage (exfiltration) rate for a storage node.

The constant-rate form of storage exfiltration, as a [STORAGE] row ending in a bare Ksat: sets the exfiltration Ksat to rate with zero suction and IMD, replacing any Green-Ampt parameters (see swmm_node_set_exfil_params). A rate of 0 turns exfiltration off.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based node index (must be SWMM_NODE_STORAGE).
[in]	rate	Seepage rate, in/hr (US) or mm/hr (SI); must be >= 0.

Returns: SWMM_OK on success; SWMM_ERR_BADPARAM on a negative rate.

Note: Requires BUILDING or OPENED; other states return SWMM_ERR_LIFECYCLE. A null engine returns SWMM_ERR_BADHANDLE. A failed node/pollutant index check returns SWMM_ERR_BADINDEX. For an existing node with no matching subtype row, the subtype assignment is a successful no-op.

◆ swmm_node_set_storage_shape()

SWMM_ENGINE_API int swmm_node_set_storage_shape	(	SWMM_Engine	engine,
		int	idx,
		int	shape )

Set a storage node's surface-area relation.

Setting a geometric shape detaches any storage curve and re-derives the internal area coefficients from the node's current raw dimensions; follow with swmm_node_set_storage_geometry() to supply them. Setting SWMM_STORAGE_FUNCTIONAL also detaches the curve. Use swmm_node_set_storage_curve() to make a node TABULAR.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based node index (must be SWMM_NODE_STORAGE).
[in]	shape	A SWMM_StorageShape code.

Returns: SWMM_OK on success, SWMM_ERR_BADPARAM if shape is not a valid code.

Note: Requires BUILDING or OPENED; other states return SWMM_ERR_LIFECYCLE. A null engine returns SWMM_ERR_BADHANDLE. A failed node/pollutant index check returns SWMM_ERR_BADINDEX. For an existing node with no matching subtype row, the subtype assignment is a successful no-op.

Here is the call graph for this function:

◆ swmm_node_set_surcharge_depth()

SWMM_ENGINE_API int swmm_node_set_surcharge_depth	(	SWMM_Engine	engine,
		int	idx,
		double	depth )

Set the allowed surcharge depth above the node's crown.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based node index.
[in]	depth	Surcharge depth in project length units.

Returns: SWMM_OK on success, or an error code.

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

◆ swmm_node_set_tag()

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

Copy or clear a node free-form tag without changing topology.

No lifecycle guard is imposed. Tags are keyed by node index and persist through node rename.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access.
[in]	idx	Zero-based node index in [0,swmm_node_count(engine)).
[in]	tag	Borrowed NUL-terminated tag to copy; NULL/empty clears it.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADINDEX for invalid node index.

◆ swmm_node_set_virtual()

SWMM_ENGINE_API int swmm_node_set_virtual	(	SWMM_Engine	engine,
		int	idx,
		int	make_virtual )

Set or clear a node's virtual-junction flag.

Setting runs full validation of the usage rules and applies the derived-geometry contract (full depth = pipe crown, zero surcharge depth, zero ponded area). Clearing always succeeds for a virtual node. BUILDING or OPENED state only.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based node index (must be a JUNCTION to set).
[in]	make_virtual	1 to set, 0 to clear.

Returns: SWMM_OK on success; SWMM_ERR_LIFECYCLE / SWMM_ERR_BADHANDLE / SWMM_ERR_BADINDEX / SWMM_ERR_BADPARAM for generic failures; or a distinct rule code on a violated usage rule so callers can render actionable messages: 609 = not exactly two conduits, 611 = cross-section mismatch, 613 = nonzero offset at the node, 617 = the node is a 2D surface-coupling point. Point lateral inflows ([INFLOWS], [DWF], RDII, subcatchment outlets, LID drains, the runtime lateral-inflow API) are permitted at a virtual junction.

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

Here is the call graph for this function:

◆ swmm_node_virtual_eligible()

SWMM_ENGINE_API int swmm_node_virtual_eligible	(	SWMM_Engine	engine,
		int	idx,
		int *	rule_code )

Dry-run check of the virtual-junction usage rules for a node.

Read-only: evaluates the same structural rules that swmm_node_set_virtual() enforces (exactly two attached conduits of identical cross-section, zero offsets, no 2D surface coupling, dynamic-wave or FV routing) without changing any state and without requiring the node to currently be a JUNCTION — so callers can offer "convert to virtual junction" only when it would succeed.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based node index.
[out]	rule_code	Receives 0 when the node satisfies every rule, else the distinct ERR_VJ_* rule code (see swmm_node_set_virtual) identifying the violated rule.

Returns: SWMM_OK on success, or an error code for a bad handle/index.

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

Here is the call graph for this function:

Classes

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ SWMM_DividerType

◆ SWMM_NodeType

◆ SWMM_OutfallExportReceipt

Enumeration Type Documentation

◆ SWMM_DividerType

◆ SWMM_NodeType

◆ SWMM_StorageShape

Function Documentation

◆ swmm_node_add()

◆ swmm_node_count()

◆ swmm_node_get_crown_elev()

◆ swmm_node_get_degree()

◆ swmm_node_get_depth()

◆ swmm_node_get_depth_from_volume()

◆ swmm_node_get_depths_bulk()

◆ swmm_node_get_divider_type()

◆ swmm_node_get_exfil_params()

◆ swmm_node_get_export_receipt()

◆ swmm_node_get_full_volume()

◆ swmm_node_get_head()

◆ swmm_node_get_heads_bulk()

◆ swmm_node_get_ids_bulk()

◆ swmm_node_get_inflow()

◆ swmm_node_get_inflows_bulk()

◆ swmm_node_get_initial_depth()

◆ swmm_node_get_invert_elev()

◆ swmm_node_get_lateral_inflow()

◆ swmm_node_get_lateral_inflows_bulk()

◆ swmm_node_get_losses()

◆ swmm_node_get_losses_bulk()

◆ swmm_node_get_max_depth()

◆ swmm_node_get_outfall_flap_gate()

◆ swmm_node_get_outfall_param()

◆ swmm_node_get_outfall_route_to()

◆ swmm_node_get_outfall_tidal()

◆ swmm_node_get_outfall_timeseries()

◆ swmm_node_get_outfall_type()

◆ swmm_node_get_outflow()

◆ swmm_node_get_outflows_bulk()

◆ swmm_node_get_overflow()

◆ swmm_node_get_overflows_bulk()

◆ swmm_node_get_ponded_area()

◆ swmm_node_get_quality()

◆ swmm_node_get_quality_bulk()

◆ swmm_node_get_rim_depth()

◆ swmm_node_get_stat_max_depth()

◆ swmm_node_get_stat_max_overflow()

◆ swmm_node_get_stat_time_flooded()

◆ swmm_node_get_stat_vol_flooded()

◆ swmm_node_get_storage_area()

◆ swmm_node_get_storage_curve()

◆ swmm_node_get_storage_functional()

◆ swmm_node_get_storage_geometry()

◆ swmm_node_get_storage_seep_rate()

◆ swmm_node_get_storage_shape()

◆ swmm_node_get_surcharge_depth()

◆ swmm_node_get_tag()

◆ swmm_node_get_type()

◆ swmm_node_get_volume()

◆ swmm_node_get_volumes_bulk()

◆ swmm_node_id()

◆ swmm_node_index()

◆ swmm_node_inlet_eligible()

◆ swmm_node_is_inlet()

◆ swmm_node_is_virtual()

◆ swmm_node_pop_last()

◆ swmm_node_rename()

◆ swmm_node_set_depth()

◆ swmm_node_set_depths_bulk()

◆ swmm_node_set_divider_type()

◆ swmm_node_set_exfil_params()

◆ swmm_node_set_head_boundary()

◆ swmm_node_set_initial_depth()

◆ swmm_node_set_inlet()