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

#include "openswmm_api_common.hpp"
#include "../../../include/openswmm/engine/openswmm_links.h"
#include <cmath>

Include dependency graph for openswmm_links_impl.cpp:

Macros
#define	M_PI 3.14159265358979323846

Functions
SWMM_ENGINE_API int	swmm_link_count (SWMM_Engine engine)
	Get the total number of links in the model.

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

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

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

SWMM_ENGINE_API int	swmm_link_set_nodes (SWMM_Engine engine, int idx, int from_node_idx, int to_node_idx)
	Set the upstream and downstream nodes of a link.

SWMM_ENGINE_API int	swmm_link_get_from_node (SWMM_Engine engine, int idx, int *node_idx)
	Get the upstream (inlet) node index of a link.

SWMM_ENGINE_API int	swmm_link_get_to_node (SWMM_Engine engine, int idx, int *node_idx)
	Get the downstream (outlet) node index of a link.

SWMM_ENGINE_API int	swmm_link_set_length (SWMM_Engine engine, int idx, double length)
	Set the conduit length.

SWMM_ENGINE_API int	swmm_link_set_roughness (SWMM_Engine engine, int idx, double n)
	Set the Manning's roughness coefficient.

SWMM_ENGINE_API int	swmm_link_set_offset_up (SWMM_Engine engine, int idx, double offset)
	Set the upstream (inlet) offset above the upstream node invert.

SWMM_ENGINE_API int	swmm_link_set_offset_dn (SWMM_Engine engine, int idx, double offset)
	Set the downstream (outlet) offset above the downstream node invert.

SWMM_ENGINE_API int	swmm_link_set_initial_flow (SWMM_Engine engine, int idx, double flow)
	Set the initial flow in a link at simulation start.

SWMM_ENGINE_API int	swmm_link_set_max_flow (SWMM_Engine engine, int idx, double flow)
	Set the maximum allowable flow in a link.

SWMM_ENGINE_API int	swmm_link_set_xsect (SWMM_Engine engine, int idx, int shape, double geom1, double geom2, double geom3, double geom4)
	Set the cross-section geometry for a conduit link.

SWMM_ENGINE_API int	swmm_link_get_xsect (SWMM_Engine engine, int idx, int shape, double geom1, double geom2, double geom3, double *geom4)
	Get the cross-section geometry for a conduit link.

SWMM_ENGINE_API int	swmm_link_get_type (SWMM_Engine engine, int idx, int *type)
	Get the type of a link.

SWMM_ENGINE_API int	swmm_link_get_length (SWMM_Engine engine, int idx, double *length)
	Get the conduit length.

SWMM_ENGINE_API int	swmm_link_get_roughness (SWMM_Engine engine, int idx, double *n)
	Get the Manning's roughness coefficient.

SWMM_ENGINE_API int	swmm_link_get_flow (SWMM_Engine engine, int idx, double *flow)
	Get the current flow rate in a link.

SWMM_ENGINE_API int	swmm_link_set_flow (SWMM_Engine engine, int idx, double flow)
	Set the flow rate in a link (runtime override).

SWMM_ENGINE_API int	swmm_link_get_depth (SWMM_Engine engine, int idx, double *depth)
	Get the current water depth in a link.

SWMM_ENGINE_API int	swmm_link_get_velocity (SWMM_Engine engine, int idx, double *velocity)
	Get the current flow velocity in a link.

SWMM_ENGINE_API int	swmm_link_get_capacity (SWMM_Engine engine, int idx, double *capacity)
	Get the current flow capacity utilization (depth / full depth).

SWMM_ENGINE_API int	swmm_link_get_volume (SWMM_Engine engine, int idx, double *volume)
	Get the current water volume stored in a link.

SWMM_ENGINE_API int	swmm_link_set_control_setting (SWMM_Engine engine, int idx, double setting)
	Override control/pump setting on a link.

SWMM_ENGINE_API int	swmm_link_get_control_setting (SWMM_Engine engine, int idx, double *setting)
	Get current control setting.

SWMM_ENGINE_API int	swmm_link_set_target_setting (SWMM_Engine engine, int idx, double setting)
	Set the target setting for a link (for gradual transitions).

SWMM_ENGINE_API int	swmm_link_get_target_setting (SWMM_Engine engine, int idx, double *setting)
	Get the current target setting.

SWMM_ENGINE_API int	swmm_link_set_closed (SWMM_Engine engine, int idx, int closed)
	Open or close a link.

SWMM_ENGINE_API int	swmm_link_get_closed (SWMM_Engine engine, int idx, int *closed)
	Get link open/closed status. Returns 1 if closed, 0 if open.

SWMM_ENGINE_API int	swmm_link_get_quality (SWMM_Engine engine, int link_idx, int pollutant_idx, double *conc)
	Get the pollutant concentration in a link.

SWMM_ENGINE_API int	swmm_link_get_flows_bulk (SWMM_Engine engine, double *buf, int count)
	Get flow rates for all links in a single call.

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

SWMM_ENGINE_API int	swmm_link_set_flows_bulk (SWMM_Engine engine, const double *buf, int count)
	Set flow rates for all links in a single call (runtime override).

SWMM_ENGINE_API int	swmm_link_get_quality_bulk (SWMM_Engine engine, int pollutant_idx, double *buf, int count)
	Get pollutant concentrations for all links for one pollutant.

SWMM_ENGINE_API int	swmm_link_set_pump_curve (SWMM_Engine engine, int idx, int curve_idx)
	Assign a pump curve to a pump link.

SWMM_ENGINE_API int	swmm_link_get_pump_curve (SWMM_Engine engine, int idx, int *curve_idx)
	Get the pump curve index assigned to a pump link.

SWMM_ENGINE_API int	swmm_link_set_pump_init_state (SWMM_Engine engine, int idx, int on)
	Set the initial on/off state of a pump at simulation start.

SWMM_ENGINE_API int	swmm_link_get_pump_init_state (SWMM_Engine engine, int idx, int *on)
	Get the initial on/off state of a pump.

SWMM_ENGINE_API int	swmm_link_set_crest_height (SWMM_Engine engine, int idx, double h)
	Set the crest height for a weir link.

SWMM_ENGINE_API int	swmm_link_get_crest_height (SWMM_Engine engine, int idx, double *h)
	Get the crest height for a weir link.

SWMM_ENGINE_API int	swmm_link_set_discharge_coeff (SWMM_Engine engine, int idx, double cd)
	Set the discharge coefficient for a weir link.

SWMM_ENGINE_API int	swmm_link_get_discharge_coeff (SWMM_Engine engine, int idx, double *cd)
	Get the discharge coefficient for a weir link.

SWMM_ENGINE_API int	swmm_link_set_end_contractions (SWMM_Engine engine, int idx, double n)
	Set the number of end contractions for a weir link.

SWMM_ENGINE_API int	swmm_link_get_end_contractions (SWMM_Engine engine, int idx, double *n)
	Get the number of end contractions for a weir link.

SWMM_ENGINE_API int	swmm_link_set_loss_coeff (SWMM_Engine engine, int idx, double inlet, double outlet, double avg)
	Set entry, exit, and average loss coefficients for a conduit.

SWMM_ENGINE_API int	swmm_link_get_loss_coeff (SWMM_Engine engine, int idx, double inlet, double outlet, double *avg)
	Get entry, exit, and average loss coefficients for a conduit.

SWMM_ENGINE_API int	swmm_link_set_flap_gate (SWMM_Engine engine, int idx, int has_gate)
	Set whether a flap gate exists on a link.

SWMM_ENGINE_API int	swmm_link_get_flap_gate (SWMM_Engine engine, int idx, int *has_gate)
	Get whether a flap gate exists on a link.

SWMM_ENGINE_API int	swmm_link_set_seep_rate (SWMM_Engine engine, int idx, double rate)
	Set the seepage loss rate for a conduit.

SWMM_ENGINE_API int	swmm_link_get_seep_rate (SWMM_Engine engine, int idx, double *rate)
	Get the seepage loss rate for a conduit.

SWMM_ENGINE_API int	swmm_link_set_culvert_code (SWMM_Engine engine, int idx, int code)
	Set the FHWA culvert inlet geometry code.

SWMM_ENGINE_API int	swmm_link_get_culvert_code (SWMM_Engine engine, int idx, int *code)
	Get the FHWA culvert inlet geometry code.

SWMM_ENGINE_API int	swmm_link_set_barrels (SWMM_Engine engine, int idx, int n)
	Set the number of parallel barrels in a conduit.

SWMM_ENGINE_API int	swmm_link_get_barrels (SWMM_Engine engine, int idx, int *n)
	Get the number of parallel barrels in a conduit.

SWMM_ENGINE_API int	swmm_link_get_slope (SWMM_Engine engine, int idx, double *slope)
	Get the computed slope of a conduit.

SWMM_ENGINE_API int	swmm_link_get_offset_up (SWMM_Engine engine, int idx, double *offset)
	Get the upstream (inlet) offset.

SWMM_ENGINE_API int	swmm_link_get_offset_dn (SWMM_Engine engine, int idx, double *offset)
	Get the downstream (outlet) offset.

SWMM_ENGINE_API int	swmm_link_get_stat_max_flow (SWMM_Engine engine, int idx, double *val)
	Get the maximum flow recorded in a link during the simulation.

SWMM_ENGINE_API int	swmm_link_get_stat_max_velocity (SWMM_Engine engine, int idx, double *val)
	Get the maximum velocity recorded in a link.

SWMM_ENGINE_API int	swmm_link_get_stat_max_filling (SWMM_Engine engine, int idx, double *val)
	Get the maximum depth/full-depth ratio (filling) in a link.

SWMM_ENGINE_API int	swmm_link_get_stat_vol_flow (SWMM_Engine engine, int idx, double *val)
	Get the total volume conveyed through a link.

SWMM_ENGINE_API int	swmm_link_get_stat_surcharge_time (SWMM_Engine engine, int idx, double *val)
	Get the total surcharge duration for a link.

Detailed Description

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

See also: include/openswmm/engine/openswmm_links.h

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

Copyright: Copyright (c) 2026 HydroCouple. All rights reserved.

License\n MIT License

Macro Definition Documentation

◆ M_PI

#define M_PI 3.14159265358979323846

Function Documentation

◆ swmm_link_add()

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

Add a new link to the model.

The engine must be in SWMM_STATE_BUILDING. After creation, use swmm_link_set_nodes() to specify connectivity and the appropriate geometry/cross-section setters.

Parameters

engine	Engine handle.
id	Unique null-terminated identifier for the new link.
type	Link type (see SWMM_LinkType).

Returns: SWMM_OK on success, or an error code.

◆ swmm_link_count()

SWMM_ENGINE_API int swmm_link_count ( SWMM_Engine engine )

Get the total number of links in the model.

Parameters

engine Engine handle.

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

◆ swmm_link_get_barrels()

SWMM_ENGINE_API int swmm_link_get_barrels	(	SWMM_Engine	engine,
		int	idx,
		int *	n
	)

Get the number of parallel barrels in a conduit.

Parameters

	engine	Engine handle.
	idx	Zero-based link index.
[out]	n	Receives the barrel count.

Returns: SWMM_OK on success, or an error code.

◆ swmm_link_get_capacity()

SWMM_ENGINE_API int swmm_link_get_capacity	(	SWMM_Engine	engine,
		int	idx,
		double *	capacity
	)

Get the current flow capacity utilization (depth / full depth).

Parameters

	engine	Engine handle.
	idx	Zero-based link index.
[out]	capacity	Receives the ratio [0, 1+] (can exceed 1 if surcharged).

Returns: SWMM_OK on success, or an error code.

◆ swmm_link_get_closed()

SWMM_ENGINE_API int swmm_link_get_closed	(	SWMM_Engine	engine,
		int	idx,
		int *	closed
	)

Get link open/closed status. Returns 1 if closed, 0 if open.

◆ swmm_link_get_control_setting()

SWMM_ENGINE_API int swmm_link_get_control_setting	(	SWMM_Engine	engine,
		int	idx,
		double *	setting
	)

Get current control setting.

◆ swmm_link_get_crest_height()

SWMM_ENGINE_API int swmm_link_get_crest_height	(	SWMM_Engine	engine,
		int	idx,
		double *	h
	)

Get the crest height for a weir link.

Parameters

	engine	Engine handle.
	idx	Zero-based link index.
[out]	h	Receives the crest height.

Returns: SWMM_OK on success, or an error code.

◆ swmm_link_get_culvert_code()

SWMM_ENGINE_API int swmm_link_get_culvert_code	(	SWMM_Engine	engine,
		int	idx,
		int *	code
	)

Get the FHWA culvert inlet geometry code.

Parameters

	engine	Engine handle.
	idx	Zero-based link index.
[out]	code	Receives the culvert code.

Returns: SWMM_OK on success, or an error code.

◆ swmm_link_get_depth()

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

Get the current water depth in a link.

Parameters

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

Returns: SWMM_OK on success, or an error code.

◆ swmm_link_get_depths_bulk()

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

Get water depths for all links 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_link_get_discharge_coeff()

SWMM_ENGINE_API int swmm_link_get_discharge_coeff	(	SWMM_Engine	engine,
		int	idx,
		double *	cd
	)

Get the discharge coefficient for a weir link.

Parameters

	engine	Engine handle.
	idx	Zero-based link index.
[out]	cd	Receives the discharge coefficient.

Returns: SWMM_OK on success, or an error code.

◆ swmm_link_get_end_contractions()

SWMM_ENGINE_API int swmm_link_get_end_contractions	(	SWMM_Engine	engine,
		int	idx,
		double *	n
	)

Get the number of end contractions for a weir link.

Parameters

	engine	Engine handle.
	idx	Zero-based link index.
[out]	n	Receives the number of end contractions.

Returns: SWMM_OK on success, or an error code.

◆ swmm_link_get_flap_gate()

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

Get whether a flap gate exists on a link.

Parameters

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

Returns: SWMM_OK on success, or an error code.

◆ swmm_link_get_flow()

SWMM_ENGINE_API int swmm_link_get_flow	(	SWMM_Engine	engine,
		int	idx,
		double *	flow
	)

Get the current flow rate in a link.

Parameters

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

Returns: SWMM_OK on success, or an error code.

◆ swmm_link_get_flows_bulk()

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

Get flow rates for all links 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_link_count()).

Returns: SWMM_OK on success, or an error code.

◆ swmm_link_get_from_node()

SWMM_ENGINE_API int swmm_link_get_from_node	(	SWMM_Engine	engine,
		int	idx,
		int *	node_idx
	)

Get the upstream (inlet) node index of a link.

Parameters

	engine	Engine handle.
	idx	Zero-based link index.
[out]	node_idx	Receives the upstream node index.

Returns: SWMM_OK on success, or an error code.

◆ swmm_link_get_length()

SWMM_ENGINE_API int swmm_link_get_length	(	SWMM_Engine	engine,
		int	idx,
		double *	length
	)

Get the conduit length.

Parameters

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

Returns: SWMM_OK on success, or an error code.

◆ swmm_link_get_loss_coeff()

SWMM_ENGINE_API int swmm_link_get_loss_coeff	(	SWMM_Engine	engine,
		int	idx,
		double *	inlet,
		double *	outlet,
		double *	avg
	)

Get entry, exit, and average loss coefficients for a conduit.

Parameters

	engine	Engine handle.
	idx	Zero-based link index.
[out]	inlet	Receives the inlet loss coefficient.
[out]	outlet	Receives the outlet loss coefficient.
[out]	avg	Receives the average loss coefficient.

Returns: SWMM_OK on success, or an error code.

◆ swmm_link_get_offset_dn()

SWMM_ENGINE_API int swmm_link_get_offset_dn	(	SWMM_Engine	engine,
		int	idx,
		double *	offset
	)

Get the downstream (outlet) offset.

Parameters

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

Returns: SWMM_OK on success, or an error code.

◆ swmm_link_get_offset_up()

SWMM_ENGINE_API int swmm_link_get_offset_up	(	SWMM_Engine	engine,
		int	idx,
		double *	offset
	)

Get the upstream (inlet) offset.

Parameters

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

Returns: SWMM_OK on success, or an error code.

◆ swmm_link_get_pump_curve()

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

Get the pump curve index assigned to a pump link.

Parameters

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

Returns: SWMM_OK on success, or an error code.

◆ swmm_link_get_pump_init_state()

SWMM_ENGINE_API int swmm_link_get_pump_init_state	(	SWMM_Engine	engine,
		int	idx,
		int *	on
	)

Get the initial on/off state of a pump.

Parameters

	engine	Engine handle.
	idx	Zero-based link index.
[out]	on	Receives 1 if initially ON, 0 if OFF.

Returns: SWMM_OK on success, or an error code.

◆ swmm_link_get_quality()

SWMM_ENGINE_API int swmm_link_get_quality	(	SWMM_Engine	engine,
		int	link_idx,
		int	pollutant_idx,
		double *	conc
	)

Get the pollutant concentration in a link.

Parameters

	engine	Engine handle.
	link_idx	Zero-based link 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_link_get_quality_bulk()

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

Get pollutant concentrations for all links 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_link_count()).

Returns: SWMM_OK on success, or an error code.

◆ swmm_link_get_roughness()

SWMM_ENGINE_API int swmm_link_get_roughness	(	SWMM_Engine	engine,
		int	idx,
		double *	n
	)

Get the Manning's roughness coefficient.

Parameters

	engine	Engine handle.
	idx	Zero-based link index.
[out]	n	Receives the Manning's n value.

Returns: SWMM_OK on success, or an error code.

◆ swmm_link_get_seep_rate()

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

Get the seepage loss rate for a conduit.

Parameters

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

Returns: SWMM_OK on success, or an error code.

◆ swmm_link_get_slope()

SWMM_ENGINE_API int swmm_link_get_slope	(	SWMM_Engine	engine,
		int	idx,
		double *	slope
	)

Get the computed slope of a conduit.

Parameters

	engine	Engine handle.
	idx	Zero-based link index.
[out]	slope	Receives the slope (dimensionless, rise/run).

Returns: SWMM_OK on success, or an error code.

◆ swmm_link_get_stat_max_filling()

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

Get the maximum depth/full-depth ratio (filling) in a link.

Parameters

	engine	Engine handle.
	idx	Zero-based link index.
[out]	val	Receives the maximum filling ratio.

Returns: SWMM_OK on success, or an error code.

◆ swmm_link_get_stat_max_flow()

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

Get the maximum flow recorded in a link during the simulation.

Parameters

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

Returns: SWMM_OK on success, or an error code.

◆ swmm_link_get_stat_max_velocity()

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

Get the maximum velocity recorded in a link.

Parameters

	engine	Engine handle.
	idx	Zero-based link index.
[out]	val	Receives the maximum velocity in project velocity units.

Returns: SWMM_OK on success, or an error code.

◆ swmm_link_get_stat_surcharge_time()

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

Get the total surcharge duration for a link.

Parameters

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

Returns: SWMM_OK on success, or an error code.

◆ swmm_link_get_stat_vol_flow()

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

Get the total volume conveyed through a link.

Parameters

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

Returns: SWMM_OK on success, or an error code.

◆ swmm_link_get_target_setting()

SWMM_ENGINE_API int swmm_link_get_target_setting	(	SWMM_Engine	engine,
		int	idx,
		double *	setting
	)

Get the current target setting.

◆ swmm_link_get_to_node()

SWMM_ENGINE_API int swmm_link_get_to_node	(	SWMM_Engine	engine,
		int	idx,
		int *	node_idx
	)

Get the downstream (outlet) node index of a link.

Parameters

	engine	Engine handle.
	idx	Zero-based link index.
[out]	node_idx	Receives the downstream node index.

Returns: SWMM_OK on success, or an error code.

◆ swmm_link_get_type()

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

Get the type of a link.

Parameters

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

Returns: SWMM_OK on success, or an error code.

◆ swmm_link_get_velocity()

SWMM_ENGINE_API int swmm_link_get_velocity	(	SWMM_Engine	engine,
		int	idx,
		double *	velocity
	)

Get the current flow velocity in a link.

Parameters

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

Returns: SWMM_OK on success, or an error code.

◆ swmm_link_get_volume()

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

Get the current water volume stored in a link.

Parameters

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

Returns: SWMM_OK on success, or an error code.

◆ swmm_link_get_xsect()

SWMM_ENGINE_API int swmm_link_get_xsect	(	SWMM_Engine	engine,
		int	idx,
		int *	shape,
		double *	geom1,
		double *	geom2,
		double *	geom3,
		double *	geom4
	)

Get the cross-section geometry for a conduit link.

Parameters

	engine	Engine handle.
	idx	Zero-based link index.
[out]	shape	Receives the shape code (see SWMM_XSectShape).
[out]	geom1	Receives the primary dimension.
[out]	geom2	Receives the secondary dimension.
[out]	geom3	Receives the tertiary dimension.
[out]	geom4	Receives the quaternary dimension.

Returns: SWMM_OK on success, or an error code.

◆ swmm_link_id()

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

Get the string identifier of a link by index.

Parameters

engine	Engine handle.
idx	Zero-based link index.

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

◆ swmm_link_index()

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

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

Parameters

engine	Engine handle.
id	Null-terminated link identifier.

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

◆ swmm_link_set_barrels()

SWMM_ENGINE_API int swmm_link_set_barrels	(	SWMM_Engine	engine,
		int	idx,
		int	n
	)

Set the number of parallel barrels in a conduit.

Parameters

engine	Engine handle.
idx	Zero-based link index.
n	Number of barrels (>= 1).

Returns: SWMM_OK on success, or an error code.

◆ swmm_link_set_closed()

SWMM_ENGINE_API int swmm_link_set_closed	(	SWMM_Engine	engine,
		int	idx,
		int	closed
	)

Open or close a link.

Parameters

engine	Engine handle (RUNNING state).
idx	Link index.
closed	Non-zero to close; zero to open.

◆ swmm_link_set_control_setting()

SWMM_ENGINE_API int swmm_link_set_control_setting	(	SWMM_Engine	engine,
		int	idx,
		double	setting
	)

Override control/pump setting on a link.

For pumps: 0.0 = off, 1.0 = full speed. For orifices/weirs: fractional opening [0, 1]. Applied for current timestep only.

◆ swmm_link_set_crest_height()

SWMM_ENGINE_API int swmm_link_set_crest_height	(	SWMM_Engine	engine,
		int	idx,
		double	h
	)

Set the crest height for a weir link.

Parameters

engine	Engine handle.
idx	Zero-based link index (must be SWMM_LINK_WEIR).
h	Crest height in project length units.

Returns: SWMM_OK on success, or an error code.

◆ swmm_link_set_culvert_code()

SWMM_ENGINE_API int swmm_link_set_culvert_code	(	SWMM_Engine	engine,
		int	idx,
		int	code
	)

Set the FHWA culvert inlet geometry code.

Used for computing inlet-controlled culvert flow. Code values correspond to FHWA HDS-5 chart numbers (0 = not a culvert).

Parameters

engine	Engine handle.
idx	Zero-based link index.
code	Culvert code (0 = none).

Returns: SWMM_OK on success, or an error code.

◆ swmm_link_set_discharge_coeff()

SWMM_ENGINE_API int swmm_link_set_discharge_coeff	(	SWMM_Engine	engine,
		int	idx,
		double	cd
	)

Set the discharge coefficient for a weir link.

Parameters

engine	Engine handle.
idx	Zero-based link index (must be SWMM_LINK_WEIR).
cd	Discharge coefficient (dimensionless).

Returns: SWMM_OK on success, or an error code.

◆ swmm_link_set_end_contractions()

SWMM_ENGINE_API int swmm_link_set_end_contractions	(	SWMM_Engine	engine,
		int	idx,
		double	n
	)

Set the number of end contractions for a weir link.

End contractions reduce the effective crest length. Typical values are 0, 1, or 2 for standard weir configurations.

Parameters

engine	Engine handle.
idx	Zero-based link index (must be SWMM_LINK_WEIR).
n	Number of end contractions.

Returns: SWMM_OK on success, or an error code.

◆ swmm_link_set_flap_gate()

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

Set whether a flap gate exists on a link.

A flap gate prevents reverse flow through the link.

Parameters

engine	Engine handle.
idx	Zero-based link index.
has_gate	Non-zero to enable; zero to disable.

Returns: SWMM_OK on success, or an error code.

◆ swmm_link_set_flow()

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

Set the flow rate in a link (runtime override).

Parameters

engine	Engine handle (RUNNING state).
idx	Zero-based link index.
flow	New flow in project flow units.

Returns: SWMM_OK on success, or an error code.

◆ swmm_link_set_flows_bulk()

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

Set flow rates for all links in a single call (runtime override).

Parameters

engine	Engine handle (RUNNING state).
buf	Array of flow values, one per link.
count	Number of elements.

Returns: SWMM_OK on success, or an error code.

◆ swmm_link_set_initial_flow()

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

Set the initial flow in a link at simulation start.

Parameters

engine	Engine handle.
idx	Zero-based link index.
flow	Initial flow in project flow units.

Returns: SWMM_OK on success, or an error code.

◆ swmm_link_set_length()

SWMM_ENGINE_API int swmm_link_set_length	(	SWMM_Engine	engine,
		int	idx,
		double	length
	)

Set the conduit length.

Parameters

engine	Engine handle.
idx	Zero-based link index.
length	Conduit length in project length units.

Returns: SWMM_OK on success, or an error code.

◆ swmm_link_set_loss_coeff()

SWMM_ENGINE_API int swmm_link_set_loss_coeff	(	SWMM_Engine	engine,
		int	idx,
		double	inlet,
		double	outlet,
		double	avg
	)

Set entry, exit, and average loss coefficients for a conduit.

Parameters

engine	Engine handle.
idx	Zero-based link index (must be SWMM_LINK_CONDUIT).
inlet	Inlet (entry) loss coefficient.
outlet	Outlet (exit) loss coefficient.
avg	Average loss coefficient along the conduit length.

Returns: SWMM_OK on success, or an error code.

◆ swmm_link_set_max_flow()

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

Set the maximum allowable flow in a link.

Parameters

engine	Engine handle.
idx	Zero-based link index.
flow	Maximum flow in project flow units (0 = no limit).

Returns: SWMM_OK on success, or an error code.

◆ swmm_link_set_nodes()

SWMM_ENGINE_API int swmm_link_set_nodes	(	SWMM_Engine	engine,
		int	idx,
		int	from_node_idx,
		int	to_node_idx
	)

Set the upstream and downstream nodes of a link.

Parameters

engine	Engine handle.
idx	Zero-based link index.
from_node_idx	Zero-based index of the upstream (inlet) node.
to_node_idx	Zero-based index of the downstream (outlet) node.

Returns: SWMM_OK on success, or an error code.

◆ swmm_link_set_offset_dn()

SWMM_ENGINE_API int swmm_link_set_offset_dn	(	SWMM_Engine	engine,
		int	idx,
		double	offset
	)

Set the downstream (outlet) offset above the downstream node invert.

Parameters

engine	Engine handle.
idx	Zero-based link index.
offset	Offset in project length units.

Returns: SWMM_OK on success, or an error code.

◆ swmm_link_set_offset_up()

SWMM_ENGINE_API int swmm_link_set_offset_up	(	SWMM_Engine	engine,
		int	idx,
		double	offset
	)

Set the upstream (inlet) offset above the upstream node invert.

Parameters

engine	Engine handle.
idx	Zero-based link index.
offset	Offset in project length units.

Returns: SWMM_OK on success, or an error code.

◆ swmm_link_set_pump_curve()

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

Assign a pump curve to a pump link.

The curve defines the relationship between head (or volume or depth) and pump flow rate.

Parameters

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

Returns: SWMM_OK on success, or an error code.

◆ swmm_link_set_pump_init_state()

SWMM_ENGINE_API int swmm_link_set_pump_init_state	(	SWMM_Engine	engine,
		int	idx,
		int	on
	)

Set the initial on/off state of a pump at simulation start.

Parameters

engine	Engine handle.
idx	Zero-based link index (must be SWMM_LINK_PUMP).
on	Non-zero for ON; zero for OFF.

Returns: SWMM_OK on success, or an error code.

◆ swmm_link_set_roughness()

SWMM_ENGINE_API int swmm_link_set_roughness	(	SWMM_Engine	engine,
		int	idx,
		double	n
	)

Set the Manning's roughness coefficient.

Parameters

engine	Engine handle.
idx	Zero-based link index.
n	Manning's n value.

Returns: SWMM_OK on success, or an error code.

◆ swmm_link_set_seep_rate()

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

Set the seepage loss rate for a conduit.

Parameters

engine	Engine handle.
idx	Zero-based link index.
rate	Seepage rate in project length/time units.

Returns: SWMM_OK on success, or an error code.

◆ swmm_link_set_target_setting()

SWMM_ENGINE_API int swmm_link_set_target_setting	(	SWMM_Engine	engine,
		int	idx,
		double	setting
	)

Set the target setting for a link (for gradual transitions).

The target setting is what the link transitions towards. For pumps/orifices/weirs, the actual setting moves toward the target based on the link's transition rate. Use this when replicating control rule SET actions that specify a target rather than an immediate override.

◆ swmm_link_set_xsect()

SWMM_ENGINE_API int swmm_link_set_xsect	(	SWMM_Engine	engine,
		int	idx,
		int	shape,
		double	geom1,
		double	geom2,
		double	geom3,
		double	geom4
	)

Set the cross-section geometry for a conduit link.

The meaning of geom1–geom4 depends on the shape; see SWMM_XSectShape for per-shape documentation.

Parameters

engine	Engine handle.
idx	Zero-based link index.
shape	Cross-section shape code (see SWMM_XSectShape).
geom1	Primary geometry parameter (usually height or diameter).
geom2	Secondary geometry parameter (usually width).
geom3	Tertiary geometry parameter (shape-dependent).
geom4	Quaternary geometry parameter (shape-dependent).

Returns: SWMM_OK on success, or an error code.

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ M_PI

Function Documentation

◆ swmm_link_add()

◆ swmm_link_count()

◆ swmm_link_get_barrels()

◆ swmm_link_get_capacity()

◆ swmm_link_get_closed()

◆ swmm_link_get_control_setting()

◆ swmm_link_get_crest_height()

◆ swmm_link_get_culvert_code()

◆ swmm_link_get_depth()

◆ swmm_link_get_depths_bulk()

◆ swmm_link_get_discharge_coeff()

◆ swmm_link_get_end_contractions()

◆ swmm_link_get_flap_gate()

◆ swmm_link_get_flow()

◆ swmm_link_get_flows_bulk()

◆ swmm_link_get_from_node()

◆ swmm_link_get_length()

◆ swmm_link_get_loss_coeff()

◆ swmm_link_get_offset_dn()

◆ swmm_link_get_offset_up()

◆ swmm_link_get_pump_curve()

◆ swmm_link_get_pump_init_state()

◆ swmm_link_get_quality()

◆ swmm_link_get_quality_bulk()

◆ swmm_link_get_roughness()

◆ swmm_link_get_seep_rate()

◆ swmm_link_get_slope()

◆ swmm_link_get_stat_max_filling()

◆ swmm_link_get_stat_max_flow()

◆ swmm_link_get_stat_max_velocity()

◆ swmm_link_get_stat_surcharge_time()

◆ swmm_link_get_stat_vol_flow()

◆ swmm_link_get_target_setting()

◆ swmm_link_get_to_node()

◆ swmm_link_get_type()

◆ swmm_link_get_velocity()

◆ swmm_link_get_volume()

◆ swmm_link_get_xsect()

◆ swmm_link_id()

◆ swmm_link_index()

◆ swmm_link_set_barrels()

◆ swmm_link_set_closed()

◆ swmm_link_set_control_setting()

◆ swmm_link_set_crest_height()

◆ swmm_link_set_culvert_code()

◆ swmm_link_set_discharge_coeff()

◆ swmm_link_set_end_contractions()

◆ swmm_link_set_flap_gate()

◆ swmm_link_set_flow()

◆ swmm_link_set_flows_bulk()

◆ swmm_link_set_initial_flow()

◆ swmm_link_set_length()

◆ swmm_link_set_loss_coeff()

◆ swmm_link_set_max_flow()

◆ swmm_link_set_nodes()

◆ swmm_link_set_offset_dn()

◆ swmm_link_set_offset_up()

◆ swmm_link_set_pump_curve()

◆ swmm_link_set_pump_init_state()

◆ swmm_link_set_roughness()

◆ swmm_link_set_seep_rate()

◆ swmm_link_set_target_setting()

◆ swmm_link_set_xsect()