openswmm_nodes_impl.cpp File Reference

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

#include "openswmm_api_common.hpp"
#include "TypeHelpers.hpp"
#include "../../../include/openswmm/engine/openswmm_nodes.h"
#include "../hydraulics/Node.hpp"
#include <algorithm>
#include <cstring>
#include <string>

Include dependency graph for openswmm_nodes_impl.cpp:

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_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_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_get_type (SWMM_Engine engine, int idx, int *type)
	Get the type of a 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_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)
	Get the total inflow to a node (lateral + upstream links).
SWMM_ENGINE_API int	swmm_node_set_lateral_inflow (SWMM_Engine engine, int idx, double flow)
	Override the lateral inflow at a node for the current timestep.
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 quality mass flux at a node (mass/sec).
SWMM_ENGINE_API int	swmm_node_set_head_boundary (SWMM_Engine engine, int idx, double head)
	Set a fixed head boundary condition at a node.
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_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)
	Get total inflows for all nodes in a single call.
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)
	Set lateral inflows for all nodes in a single call (runtime override).
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_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_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_seep_rate (SWMM_Engine engine, int idx, double rate)
	Set the seepage rate for a storage node.
SWMM_ENGINE_API int	swmm_node_get_storage_seep_rate (SWMM_Engine engine, int idx, double *rate)
	Get the seepage rate for 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_set_outfall_route_to (SWMM_Engine engine, int idx, int subcatch_idx)
	Set outfall route-to subcatchment index (-1 = none).
SWMM_ENGINE_API int	swmm_node_get_outfall_route_to (SWMM_Engine engine, int idx, int *subcatch_idx)
	Get outfall route-to subcatchment index (-1 = none).
SWMM_ENGINE_API int	swmm_node_get_depth_from_volume (SWMM_Engine engine, int idx, double volume, double *depth)
	Compute depth from volume for a node (inverse of volume-depth curve).
SWMM_ENGINE_API int	swmm_node_rename (SWMM_Engine engine, int idx, const char *newId)
	Rename the node at idx to newId. Returns SWMM_ERR_BADPARAM if newId is null, empty, already in use, or idx is out of range.
SWMM_ENGINE_API int	swmm_node_get_tag (SWMM_Engine engine, int idx, char *buf, int buflen)
	Read the tag string into buf (NUL-terminated, truncated to buflen-1 chars if necessary). Returns empty string when the node has no tag.
SWMM_ENGINE_API int	swmm_node_set_tag (SWMM_Engine engine, int idx, const char *tag)
	Set or clear the node's tag. Pass null or empty string to clear. Tag persists across swmm_node_rename (it is keyed by index, not name). Writes are honoured in any engine lifecycle state.

Detailed Description

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

See also

include/openswmm/engine/openswmm_nodes.h

Author

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

Copyright

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

License\n MIT License

Function Documentation

swmm_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

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

Returns

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

swmm_node_count()

SWMM_ENGINE_API int swmm_node_count

(

SWMM_Engine

engine

)

Get the total number of nodes in the model.

Parameters

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

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

Returns

SWMM_OK on success, or an error code.

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

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

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

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

Returns

SWMM_OK on success, or an error code.

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
	)

Compute depth from volume for a node (inverse of volume-depth curve).

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

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

Returns

SWMM_OK on success, or an error code.

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

	engine	Engine handle.
	idx	Zero-based node index.
[out]	type	Receives the divider type code.

Returns

SWMM_OK on success, or an error code.

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

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

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

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

Returns

SWMM_OK on success, or an error code.

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

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

Returns

SWMM_OK on success, or an error code.

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

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

Returns

SWMM_OK on success, or an error code.

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

	engine	Engine handle.
[out]	buf	Caller-allocated buffer of stride*count bytes.
	stride	Per-ID slot size in bytes (must be > 1 to allow at least one character plus the NUL).
	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);
}

See also

swmm_node_id

Since

6.0.0

swmm_node_get_inflow()

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

Get the total inflow to a node (lateral + upstream links).

Parameters

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

Returns

SWMM_OK on success, or an error code.

swmm_node_get_inflows_bulk()

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

Get total inflows for all nodes in a single call.

Parameters

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

Returns

SWMM_OK on success, or an error code.

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

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

Returns

SWMM_OK on success, or an error code.

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

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

Returns

SWMM_OK on success, or an error code.

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

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

Returns

SWMM_OK on success, or an error code.

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

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

Returns

SWMM_OK on success, or an error code.

Since

6.0.0

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

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

Returns

SWMM_OK on success, or an error code.

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

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

Returns

SWMM_OK on success, or an error code.

Since

6.0.0

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

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

Returns

SWMM_OK on success, or an error code.

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

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

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

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

Returns

SWMM_OK on success, or an error code.

swmm_node_get_outfall_route_to()

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

Get outfall route-to subcatchment index (-1 = none).

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

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

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

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

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

	engine	Engine handle.
	idx	Zero-based node index.
[out]	type	Receives the outfall type code.

Returns

SWMM_OK on success, or an error code.

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

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

Returns

SWMM_OK on success, or an error code.

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

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

Returns

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

Since

6.0.0

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

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

Returns

SWMM_OK on success, or an error code.

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

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

Returns

SWMM_OK on success, or an error code.

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

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

Returns

SWMM_OK on success, or an error code.

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

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

Returns

SWMM_OK on success, or an error code.

swmm_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

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

Returns

SWMM_OK on success, or an error code.

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

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

Returns

SWMM_OK on success, or an error code.

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

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

Returns

SWMM_OK on success, or an error code.

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

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

Returns

SWMM_OK on success, or an error code.

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

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

Returns

SWMM_OK on success, or an error code.

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

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

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

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

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 seepage rate for a storage node.

Parameters

	engine	Engine handle.
	idx	Zero-based node index.
[out]	rate	Receives the seepage rate.

Returns

SWMM_OK on success, or an error code.

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

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

Returns

SWMM_OK on success, or an error code.

swmm_node_get_tag()

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

Read the tag string into buf (NUL-terminated, truncated to buflen-1 chars if necessary). Returns empty string when the node has no tag.

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

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

Returns

SWMM_OK on success, or an error code.

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

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

Returns

SWMM_OK on success, or an error code.

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

	engine	Engine handle.
[out]	buf	Caller-allocated buffer of at least count doubles.
	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

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

engine	Engine handle.
idx	Zero-based node index.

Returns

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

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

engine	Engine handle.
id	Null-terminated node identifier.

Returns

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

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

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

Returns

SWMM_OK on success, or an error code.

swmm_node_rename()

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

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

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

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

Returns

SWMM_OK on success, or an error code.

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

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

Returns

SWMM_OK on success, or an error code.

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

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

Returns

SWMM_OK on success, or an error code.

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

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

Returns

SWMM_OK on success, or an error code.

swmm_node_set_head_boundary()

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

Set a fixed head boundary condition at a node.

Useful for outfall nodes or real-time coupled boundary conditions. Applied for the current timestep only.

Parameters

engine	Engine handle (RUNNING state).
idx	Zero-based node index.
head	Head boundary in project length units.

Returns

SWMM_OK on success, or an error code.

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

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

Returns

SWMM_OK on success, or an error code.

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

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

Returns

SWMM_OK on success, or an error code.

swmm_node_set_lat_inflows_bulk()

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

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

Parameters

engine	Engine handle (RUNNING state).
buf	Array of lateral inflow values, one per node.
count	Number of elements.

Returns

SWMM_OK on success, or an error code.

swmm_node_set_lateral_inflow()

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

Override the lateral inflow at a node for the current timestep.

Applied for one timestep only; call each step to sustain. This replaces any externally defined inflows (DWF, RDII, etc.) for this node during the current step.

Parameters

engine	Engine handle (RUNNING state).
idx	Zero-based node index.
flow	Lateral inflow in project flow units.

Returns

SWMM_OK on success, or an error code.

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

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

Returns

SWMM_OK on success, or an error code.

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

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

Returns

SWMM_OK on success, or an error code.

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 outfall route-to subcatchment index (-1 = none).

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

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

Returns

SWMM_OK on success, or an error code.

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

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

Returns

SWMM_OK on success, or an error code.

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

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

Returns

SWMM_OK on success, or an error code.

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

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

Returns

SWMM_OK on success, or an error code.

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

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

Returns

SWMM_OK on success, or an error code.

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 quality mass flux at a node (mass/sec).

The mass flux is applied additively at each routing step, converting to a concentration delta: C += (mass_rate * dt) / volume. The value persists until the user explicitly changes it (analogous to swmm_node_set_lateral_inflow for flow). Set to 0.0 to stop.

Parameters

engine	Engine handle (RUNNING state).
node_idx	Zero-based node index.
pollutant_idx	Zero-based pollutant index.
mass_rate	Mass flux in mass/sec (project mass units).

Returns

SWMM_OK on success, or an error code.

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

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

Returns

SWMM_OK on success, or an error code.

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

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

Returns

SWMM_OK on success, or an error code.

swmm_node_set_storage_seep_rate()

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

Set the seepage rate for a storage node.

Parameters

engine	Engine handle.
idx	Zero-based node index (must be SWMM_NODE_STORAGE).
rate	Seepage rate in project length/time units.

Returns

SWMM_OK on success, or an error code.

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

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

Returns

SWMM_OK on success, or an error code.

swmm_node_set_tag()

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

Set or clear the node's tag. Pass null or empty string to clear. Tag persists across swmm_node_rename (it is keyed by index, not name). Writes are honoured in any engine lifecycle state.