openswmm_links.h File Reference

OpenSWMM Engine — Link (conduit/pump/orifice/weir/outlet) C API. More...

#include "openswmm_engine.h"

Include dependency graph for openswmm_links.h:

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

Go to the source code of this file.

Typedefs
typedef enum SWMM_LinkType	SWMM_LinkType
	Link type classification.
typedef enum SWMM_XSectShape	SWMM_XSectShape
	Cross-section shape codes for conduit links.
typedef enum SWMM_OrificeType	SWMM_OrificeType
	Orifice flow-attack classification.
typedef enum SWMM_WeirType	SWMM_WeirType
	Weir-flow classification.
typedef enum SWMM_OutletRatingType	SWMM_OutletRatingType
	Outlet rating-curve classification.

Enumerations
enum	SWMM_LinkType {   SWMM_LINK_CONDUIT = 0 ,   SWMM_LINK_PUMP = 1 ,   SWMM_LINK_ORIFICE = 2 ,   SWMM_LINK_WEIR = 3 ,   SWMM_LINK_OUTLET = 4 }
	Link type classification. More...
enum	SWMM_XSectShape {   SWMM_XSECT_CIRCULAR = 0 ,   SWMM_XSECT_FILLED_CIRCULAR = 1 ,   SWMM_XSECT_RECT_CLOSED = 2 ,   SWMM_XSECT_RECT_OPEN = 3 ,   SWMM_XSECT_TRAPEZOIDAL = 4 ,   SWMM_XSECT_TRIANGULAR = 5 ,   SWMM_XSECT_PARABOLIC = 6 ,   SWMM_XSECT_POWER = 7 ,   SWMM_XSECT_MOD_BASKET = 8 ,   SWMM_XSECT_EGGSHAPED = 9 ,   SWMM_XSECT_HORSESHOE = 10 ,   SWMM_XSECT_GOTHIC = 11 ,   SWMM_XSECT_CATENARY = 12 ,   SWMM_XSECT_SEMIELLIPTICAL = 13 ,   SWMM_XSECT_BASKETHANDLE = 14 ,   SWMM_XSECT_SEMICIRCULAR = 15 ,   SWMM_XSECT_RECT_TRIANG = 16 ,   SWMM_XSECT_RECT_ROUND = 17 ,   SWMM_XSECT_HORIZ_ELLIPSE = 18 ,   SWMM_XSECT_VERT_ELLIPSE = 19 ,   SWMM_XSECT_ARCH = 20 ,   SWMM_XSECT_IRREGULAR = 21 ,   SWMM_XSECT_CUSTOM = 22 ,   SWMM_XSECT_FORCE_MAIN = 23 ,   SWMM_XSECT_STREET = 24 ,   SWMM_XSECT_DUMMY = 25 }
	Cross-section shape codes for conduit links. More...
enum	SWMM_OrificeType {   SWMM_ORIFICE_SIDE = 0 ,   SWMM_ORIFICE_BOTTOM = 1 }
	Orifice flow-attack classification. More...
enum	SWMM_WeirType {   SWMM_WEIR_TRANSVERSE = 0 ,   SWMM_WEIR_SIDEFLOW = 1 ,   SWMM_WEIR_VNOTCH = 2 ,   SWMM_WEIR_TRAPEZOIDAL = 3 ,   SWMM_WEIR_ROADWAY = 4 }
	Weir-flow classification. More...
enum	SWMM_OutletRatingType {   SWMM_OUTLET_FUNCTIONAL_HEAD = 0 ,   SWMM_OUTLET_FUNCTIONAL_DEPTH = 1 ,   SWMM_OUTLET_TABULAR_HEAD = 2 ,   SWMM_OUTLET_TABULAR_DEPTH = 3 }
	Outlet rating-curve classification. More...

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_pop_last (SWMM_Engine engine, const char *id)
	Remove the most recently added link (undo-of-add).
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_links_restore_authored_orientation (SWMM_Engine engine, int *count)
	Restore authored From/To orientation on every conduit the parser reversed for adverse slope (DYNWAVE/FV routing).
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_get_initial_flow (SWMM_Engine engine, int idx, double *flow)
	Get the initial flow in a link at simulation start.
SWMM_ENGINE_API int	swmm_link_get_max_flow (SWMM_Engine engine, int idx, double *flow)
	Get the maximum allowable flow in a link.
SWMM_ENGINE_API int	swmm_link_set_orifice_type (SWMM_Engine engine, int idx, int type)
	Set the orifice flow-attack classification (SIDE / BOTTOM).
SWMM_ENGINE_API int	swmm_link_get_orifice_type (SWMM_Engine engine, int idx, int *type)
	Get the orifice flow-attack classification.
SWMM_ENGINE_API int	swmm_link_set_weir_type (SWMM_Engine engine, int idx, int type)
	Set the weir flow classification.
SWMM_ENGINE_API int	swmm_link_get_weir_type (SWMM_Engine engine, int idx, int *type)
	Get the weir flow classification.
SWMM_ENGINE_API int	swmm_link_set_outlet_rating_type (SWMM_Engine engine, int idx, int type)
	Set the outlet rating-curve classification.
SWMM_ENGINE_API int	swmm_link_get_outlet_rating_type (SWMM_Engine engine, int idx, int *type)
	Get the outlet rating-curve classification.
SWMM_ENGINE_API int	swmm_link_set_outlet_expon (SWMM_Engine engine, int idx, double expon)
	Set the outlet functional-form exponent.
SWMM_ENGINE_API int	swmm_link_get_outlet_expon (SWMM_Engine engine, int idx, double *expon)
	Get the outlet functional-form exponent.
SWMM_ENGINE_API int	swmm_link_set_pump_startup_depth (SWMM_Engine engine, int idx, double depth)
	Set the pump startup depth (depth at upstream node when the pump turns on, project length units).
SWMM_ENGINE_API int	swmm_link_get_pump_startup_depth (SWMM_Engine engine, int idx, double *depth)
	Get the pump startup depth.
SWMM_ENGINE_API int	swmm_link_set_pump_shutoff_depth (SWMM_Engine engine, int idx, double depth)
	Set the pump shutoff depth (depth at upstream node when the pump turns off, project length units).
SWMM_ENGINE_API int	swmm_link_get_pump_shutoff_depth (SWMM_Engine engine, int idx, double *depth)
	Get the pump shutoff depth.
SWMM_ENGINE_API int	swmm_link_set_orifice_open_close_rate (SWMM_Engine engine, int idx, double rate)
	Set the orifice open/close rate (fraction per second).
SWMM_ENGINE_API int	swmm_link_get_orifice_open_close_rate (SWMM_Engine engine, int idx, double *rate)
	Get the orifice open/close rate (fraction per second).
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_get_slot_volume (SWMM_Engine engine, int idx, double *volume)
	Get the portion of a link's stored volume held in the Preissmann slot.
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_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_peak_slot_share (SWMM_Engine engine, int idx, double *val)
	Peak instantaneous Preissmann-slot storage share of a link.
SWMM_ENGINE_API int	swmm_link_get_stat_slot_share (SWMM_Engine engine, int idx, double *val)
	Run-level Preissmann-slot storage share of 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.
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_get_velocities_bulk (SWMM_Engine engine, double *buf, int count)
	Get cross-sectional velocities for all links in a single call.
SWMM_ENGINE_API int	swmm_link_get_capacities_bulk (SWMM_Engine engine, double *buf, int count)
	Get capacity ratios (q/q_full) for all links in a single call.
SWMM_ENGINE_API int	swmm_link_get_volumes_bulk (SWMM_Engine engine, double *buf, int count)
	Get stored volumes for all links in a single call.
SWMM_ENGINE_API int	swmm_link_get_control_settings_bulk (SWMM_Engine engine, double *buf, int count)
	Get active control settings (0..1) for all links in a single call.
SWMM_ENGINE_API int	swmm_link_get_target_settings_bulk (SWMM_Engine engine, double *buf, int count)
	Get target control settings for all links in a single call.
SWMM_ENGINE_API int	swmm_link_get_hyd_powers_bulk (SWMM_Engine engine, double *buf, int count)
	Get hydraulic power dissipated in every link in a single call.
SWMM_ENGINE_API int	swmm_link_get_ids_bulk (SWMM_Engine engine, char *buf, int stride, int count)
	Get link IDs for all links in a single call (stride-packed UTF-8).
SWMM_ENGINE_API int	swmm_link_get_stat_pump_cycles (SWMM_Engine engine, int idx, int *cycles)
	Get pump on/off cycle count.
SWMM_ENGINE_API int	swmm_link_get_stat_pump_on_time (SWMM_Engine engine, int idx, double *seconds)
	Get pump total on-time (seconds).
SWMM_ENGINE_API int	swmm_link_get_stat_pump_volume (SWMM_Engine engine, int idx, double *volume)
	Get pump total volume pumped (ft3).
SWMM_ENGINE_API int	swmm_link_get_pump_stats_bulk (SWMM_Engine engine, int *cycles, double *on_time, double *volume, int count)
	Get pump utilization statistics for all links in a single call.
SWMM_ENGINE_API int	swmm_link_get_hyd_power (SWMM_Engine engine, int idx, double *power)
	Get hydraulic power dissipated in a link (ft-lb/s). P = gamma * |Q| * |hL|.
SWMM_ENGINE_API int	swmm_link_rename (SWMM_Engine engine, int idx, const char *newId)
	Rename the link 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_link_get_tag (SWMM_Engine engine, int idx, char *buf, int buflen)
	Read the link's tag into buf (NUL-terminated, truncated if too small).
SWMM_ENGINE_API int	swmm_link_set_tag (SWMM_Engine engine, int idx, const char *tag)
	Set or clear the link's tag. Null/empty clears. Persists across rename.

Detailed Description

OpenSWMM Engine — Link (conduit/pump/orifice/weir/outlet) C API.

Link add (BUILDING state), geometry/cross-section setters, connectivity, state get/set, control setting injection, bulk access.

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\n Apache-2.0

Typedef Documentation

SWMM_LinkType

typedef enum SWMM_LinkType SWMM_LinkType

Link type classification.

Every link in a SWMM model belongs to one of these types. The type determines which property setters are valid (e.g., pump curves only apply to SWMM_LINK_PUMP).

SWMM_OrificeType

typedef enum SWMM_OrificeType SWMM_OrificeType

Orifice flow-attack classification.

Used with swmm_link_set_orifice_type and swmm_link_get_orifice_type. Order matches the legacy SWMM-GUI combo (SWMM-GUI/Epaswmm5/objprops.txt:862).

Since

6.0.0 (engine gap BN-LINK-02, added 2026-05-25)

SWMM_OutletRatingType

typedef enum SWMM_OutletRatingType SWMM_OutletRatingType

Outlet rating-curve classification.

Used with swmm_link_set_outlet_rating_type and swmm_link_get_outlet_rating_type. Numeric encoding matches the legacy LinksHandler::handle_outlets convention (src/engine/input/handlers/LinksHandler.cpp:214-221) and the legacy SWMM-GUI combo order at SWMM-GUI/Epaswmm5/objprops.txt:913.

FUNCTIONAL types use the cd (coefficient) and the outlet exponent (see swmm_link_set_outlet_expon) to define the rating curve; TABULAR types use the curve assigned via swmm_link_set_pump_curve (the engine shares the curve-index slot between pumps and tabular outlets).

Since

6.0.0 (engine gap BN-LINK-04, added 2026-05-25)

SWMM_WeirType

typedef enum SWMM_WeirType SWMM_WeirType

Weir-flow classification.

Used with swmm_link_set_weir_type and swmm_link_get_weir_type. Numeric order matches the legacy WeirType enum in legacy/engine/enums.h:925 and the legacy SWMM-GUI combo (SWMM-GUI/Epaswmm5/objprops.txt:160).

The companion "Shape" attribute in the legacy GUI is derived from the weir type (see objprops.txt:162 for the mapping) and need not be stored separately; clients that want the shape should consult swmm_link_get_xsect.

Since

6.0.0 (engine gap BN-LINK-03, added 2026-05-25)

SWMM_XSectShape

typedef enum SWMM_XSectShape SWMM_XSectShape

Cross-section shape codes for conduit links.

Used with swmm_link_set_xsect() and swmm_link_get_xsect(). The interpretation of geom1–geom4 depends on the shape; see the SWMM 5.2 reference manual for cross-section geometry definitions.

Warning

Renumbered in 6.0. These codes are the engine's own storage codes (openswmm::XsectShape). Prior to 6.0 every constant from 8 upward named a different shape than the one the engine stored, so e.g. SWMM_XSECT_IRREGULAR silently produced a vertical ellipse. Code that passed these constants symbolically and is recompiled against this header is corrected automatically; code that hard-coded the old integers must be renumbered. swmm_xsect_shape_name() is provided to check a code at runtime.

Note

These are NOT the legacy SWMM 5 XsectType codes (which put DUMMY at 0 and are used internally by the geometry kernels); the engine translates between the two at its own boundary.

Enumeration Type Documentation

SWMM_LinkType

enum SWMM_LinkType

Link type classification.

Every link in a SWMM model belongs to one of these types. The type determines which property setters are valid (e.g., pump curves only apply to SWMM_LINK_PUMP).

Enumerator
SWMM_LINK_CONDUIT	Closed or open conduit conveying flow by gravity.
SWMM_LINK_PUMP	Pump link (flow determined by pump curve).
SWMM_LINK_ORIFICE	Orifice (circular or rectangular opening).
SWMM_LINK_WEIR	Weir (transverse/side/V-notch/trapezoidal).
SWMM_LINK_OUTLET	Flow-vs-head outlet structure.

SWMM_OrificeType

enum SWMM_OrificeType

Orifice flow-attack classification.

Used with swmm_link_set_orifice_type and swmm_link_get_orifice_type. Order matches the legacy SWMM-GUI combo (SWMM-GUI/Epaswmm5/objprops.txt:862).

Since

6.0.0 (engine gap BN-LINK-02, added 2026-05-25)

Enumerator
SWMM_ORIFICE_SIDE	Orifice opens on the side of the upstream node.
SWMM_ORIFICE_BOTTOM	Orifice opens through the bottom of the upstream node.

SWMM_OutletRatingType

enum SWMM_OutletRatingType

Outlet rating-curve classification.

Used with swmm_link_set_outlet_rating_type and swmm_link_get_outlet_rating_type. Numeric encoding matches the legacy LinksHandler::handle_outlets convention (src/engine/input/handlers/LinksHandler.cpp:214-221) and the legacy SWMM-GUI combo order at SWMM-GUI/Epaswmm5/objprops.txt:913.

FUNCTIONAL types use the cd (coefficient) and the outlet exponent (see swmm_link_set_outlet_expon) to define the rating curve; TABULAR types use the curve assigned via swmm_link_set_pump_curve (the engine shares the curve-index slot between pumps and tabular outlets).

Since

6.0.0 (engine gap BN-LINK-04, added 2026-05-25)

Enumerator
SWMM_OUTLET_FUNCTIONAL_HEAD	Q = Cd · H^expon (head above invert).
SWMM_OUTLET_FUNCTIONAL_DEPTH	Q = Cd · y^expon (depth at upstream node).
SWMM_OUTLET_TABULAR_HEAD	Q from rating curve indexed by head.
SWMM_OUTLET_TABULAR_DEPTH	Q from rating curve indexed by depth.

SWMM_WeirType

enum SWMM_WeirType

Weir-flow classification.

Used with swmm_link_set_weir_type and swmm_link_get_weir_type. Numeric order matches the legacy WeirType enum in legacy/engine/enums.h:925 and the legacy SWMM-GUI combo (SWMM-GUI/Epaswmm5/objprops.txt:160).

The companion "Shape" attribute in the legacy GUI is derived from the weir type (see objprops.txt:162 for the mapping) and need not be stored separately; clients that want the shape should consult swmm_link_get_xsect.

Since

6.0.0 (engine gap BN-LINK-03, added 2026-05-25)

Enumerator
SWMM_WEIR_TRANSVERSE	Sharp-crested transverse weir.
SWMM_WEIR_SIDEFLOW	Side-flow weir (USBR formula).
SWMM_WEIR_VNOTCH	Triangular / V-notch weir.
SWMM_WEIR_TRAPEZOIDAL	Trapezoidal weir.
SWMM_WEIR_ROADWAY	FHWA HDS-5 roadway weir.

SWMM_XSectShape

enum SWMM_XSectShape

Cross-section shape codes for conduit links.

Used with swmm_link_set_xsect() and swmm_link_get_xsect(). The interpretation of geom1–geom4 depends on the shape; see the SWMM 5.2 reference manual for cross-section geometry definitions.

Warning

Renumbered in 6.0. These codes are the engine's own storage codes (openswmm::XsectShape). Prior to 6.0 every constant from 8 upward named a different shape than the one the engine stored, so e.g. SWMM_XSECT_IRREGULAR silently produced a vertical ellipse. Code that passed these constants symbolically and is recompiled against this header is corrected automatically; code that hard-coded the old integers must be renumbered. swmm_xsect_shape_name() is provided to check a code at runtime.

Note

These are NOT the legacy SWMM 5 XsectType codes (which put DUMMY at 0 and are used internally by the geometry kernels); the engine translates between the two at its own boundary.

Enumerator
SWMM_XSECT_CIRCULAR	Full circular pipe. geom1=diameter.
SWMM_XSECT_FILLED_CIRCULAR	Circular pipe with sediment deposit. geom1=diameter, geom2=filled depth.
SWMM_XSECT_RECT_CLOSED	Closed rectangular conduit. geom1=height, geom2=width.
SWMM_XSECT_RECT_OPEN	Open rectangular channel. geom1=height, geom2=width, geom3=# sides removed (0/1/2).
SWMM_XSECT_TRAPEZOIDAL	Trapezoidal channel. geom1=height, geom2=bottom width, geom3/geom4=side slopes.
SWMM_XSECT_TRIANGULAR	Triangular channel. geom1=height, geom2=top width.
SWMM_XSECT_PARABOLIC	Parabolic channel. geom1=height, geom2=top width.
SWMM_XSECT_POWER	Power-law shaped channel. geom1=height, geom2=top width, geom3=exponent.
SWMM_XSECT_MOD_BASKET	Modified baskethandle. geom1=height, geom2=bottom width, geom3=top radius.
SWMM_XSECT_EGGSHAPED	Egg-shaped (standard). geom1=height.
SWMM_XSECT_HORSESHOE	Horseshoe. geom1=height.
SWMM_XSECT_GOTHIC	Gothic. geom1=height.
SWMM_XSECT_CATENARY	Catenary. geom1=height.
SWMM_XSECT_SEMIELLIPTICAL	Semi-elliptical. geom1=height.
SWMM_XSECT_BASKETHANDLE	Baskethandle. geom1=height.
SWMM_XSECT_SEMICIRCULAR	Semi-circular. geom1=height.
SWMM_XSECT_RECT_TRIANG	Rectangular-triangular channel. geom1=height, geom2=top width, geom3=triangle height.
SWMM_XSECT_RECT_ROUND	Rectangular-round channel. geom1=height, geom2=top width, geom3=bottom radius.
SWMM_XSECT_HORIZ_ELLIPSE	Horizontal ellipse. geom1=height, geom2=width.
SWMM_XSECT_VERT_ELLIPSE	Vertical ellipse. geom1=height, geom2=width.
SWMM_XSECT_ARCH	Arch pipe. geom1=height, geom2=width.
SWMM_XSECT_IRREGULAR	Irregular (from transect data). geom1=transect index.
SWMM_XSECT_CUSTOM	Custom shape (from a shape curve). geom1=height, geom2=shape-curve index.
SWMM_XSECT_FORCE_MAIN	Circular force main. geom1=diameter, geom2=roughness (H-W C or D-W eps).
SWMM_XSECT_STREET	Street cross-section (from [STREETS]). geom1=street index.
SWMM_XSECT_DUMMY	Dummy — no geometry; all queries return 0.

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 (programmatic construction) or SWMM_STATE_OPENED (interactive editing after the .inp has been parsed). Returns SWMM_ERR_LIFECYCLE for any other state. 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, SWMM_ERR_LIFECYCLE if not in an editable state, or another error code.

Here is the call graph for this function:

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

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

Get capacity ratios (q/q_full) for all links in a single call.

Bulk variant of swmm_link_get_capacity. Per-link loop (capacity is derived from flow / full-flow).

Since

6.0.0

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

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

Get active control settings (0..1) for all links in a single call.

Bulk variant of swmm_link_get_control_setting.

Since

6.0.0

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

SWMM_ENGINE_API int swmm_link_get_hyd_power	(	SWMM_Engine	engine,
		int	idx,
		double *	power )

Get hydraulic power dissipated in a link (ft-lb/s). P = gamma * |Q| * |hL|.

swmm_link_get_hyd_powers_bulk()

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

Get hydraulic power dissipated in every link in a single call.

Bulk variant of swmm_link_get_hyd_power. Per-link loop: P = gamma * |Q| * |h_up - h_dn| (ft-lb/s); non-conduit links produce the same expression with whatever flow they report. Use cycles[i] from swmm_link_get_pump_stats_bulk to filter to pumps if needed.

Since

6.0.0

swmm_link_get_ids_bulk()

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

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

Stride-packed format matching swmm_node_get_ids_bulk: each ID is written into the slot buf[i*stride .. i*stride+stride-1] and NUL-terminated within its slot (truncated to stride-1 bytes if longer). The function zero-fills the requested region on entry so trailing bytes are always NUL.

Parameters

	engine	Engine handle.
[out]	buf	Caller-allocated buffer of stride*count bytes.
	stride	Per-ID slot size in bytes (must be > 1).
	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.

See also

swmm_link_id, swmm_node_get_ids_bulk

Since

6.0.0

swmm_link_get_initial_flow()

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

Get the initial flow in a link at simulation start.

Symmetric getter for swmm_link_set_initial_flow. Reads the same SoA slot the setter writes; safe to call in any post-construction engine state.

Parameters

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

Returns

SWMM_OK on success, or an error code.

Since

6.0.0 (engine gap BN-LINK-01a, added 2026-05-25)

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

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

Get the maximum allowable flow in a link.

Symmetric getter for swmm_link_set_max_flow. Returns 0.0 when no limit is configured (mirrors the setter's contract).

Parameters

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

Returns

SWMM_OK on success, or an error code.

Since

6.0.0 (engine gap BN-LINK-01b, added 2026-05-25)

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

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

Get the orifice open/close rate (fraction per second).

Since

6.0.0 (BN-LINK-06)

swmm_link_get_orifice_type()

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

Get the orifice flow-attack classification.

Parameters

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

Returns

SWMM_OK on success, SWMM_ERR_BADPARAM if idx names a non-orifice link.

Since

6.0.0 (engine gap BN-LINK-02, added 2026-05-25)

swmm_link_get_outlet_expon()

SWMM_ENGINE_API int swmm_link_get_outlet_expon	(	SWMM_Engine	engine,
		int	idx,
		double *	expon )

Get the outlet functional-form exponent.

Returns

SWMM_OK on success, SWMM_ERR_BADPARAM if idx names a non-outlet link.

Since

6.0.0 (engine gap BN-LINK-04, added 2026-05-25)

swmm_link_get_outlet_rating_type()

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

Get the outlet rating-curve classification.

Returns

SWMM_OK on success, SWMM_ERR_BADPARAM if idx names a non-outlet link.

Since

6.0.0 (engine gap BN-LINK-04, added 2026-05-25)

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

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

Get the pump shutoff depth.

Since

6.0.0 (BN-LINK-05)

swmm_link_get_pump_startup_depth()

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

Get the pump startup depth.

Since

6.0.0 (BN-LINK-05)

swmm_link_get_pump_stats_bulk()

SWMM_ENGINE_API int swmm_link_get_pump_stats_bulk	(	SWMM_Engine	engine,
		int *	cycles,
		double *	on_time,
		double *	volume,
		int	count )

Get pump utilization statistics for all links in a single call.

Single-pass bulk accessor that avoids N round-trips through the C ABI when caller needs pump stats across the network (e.g. when building a network-wide pump summary report). For links whose type is not LinkType::PUMP, the corresponding cycles entry is set to -1 and the on_time / volume entries to 0.0 — this allows the caller to distinguish "non-pump" from "pump with zero cycles".

Any of cycles, on_time, volume may be NULL if the caller does not need that output; the function still iterates the full link array (the cost is identical) but skips the store.

Parameters

	engine	Engine handle (must be in INITIALIZED state or later so the statistics vectors are sized).
[out]	cycles	Caller-allocated int buffer of at least count entries, or NULL. Non-pump links get -1.
[out]	on_time	Caller-allocated double buffer of at least count entries (seconds), or NULL.
[out]	volume	Caller-allocated double buffer of at least count entries (ft3), or NULL.
	count	Length of the caller-allocated buffers. If smaller than the link count, only the first min(count, n_links) entries are written.

Returns

SWMM_OK on success; SWMM_ERR_BADHANDLE if engine is invalid; SWMM_ERR_BADPARAM if count is non-positive or all three output pointers are NULL.

Example

int n = swmm_link_count(eng);
int* cycles = malloc(n * sizeof(int));
double* on_time = malloc(n * sizeof(double));
double* volume = malloc(n * sizeof(double));
swmm_link_get_pump_stats_bulk(eng, cycles, on_time, volume, n);
for (int i = 0; i < n; ++i) {
    if (cycles[i] < 0) continue;            // not a pump
    printf("link %d: %d cycles, %.1f s, %.2f ft3\n",
           i, cycles[i], on_time[i], volume[i]);
}

Note

Equivalent to calling swmm_link_get_stat_pump_cycles, swmm_link_get_stat_pump_on_time, and swmm_link_get_stat_pump_volume for every link, but with one C ABI crossing instead of 3N.

See also

swmm_link_get_stat_pump_cycles

swmm_link_get_stat_pump_on_time

swmm_link_get_stat_pump_volume

Since

6.0.0

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

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

Get the portion of a link's stored volume held in the Preissmann slot.

Finite-volume routing only: the water standing above the pipe crown in the slot (sum over cells of max(0, A - A_crown) * dx). Always a subset of swmm_link_get_volume; reads 0.0 under the dynamic-wave router and whenever the conduit is below its crown.

Parameters

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

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

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

Peak instantaneous Preissmann-slot storage share of a link.

FV routing only: max over the run of slot_volume/volume (0..1). Reads 0.0 under the dynamic-wave router.

swmm_link_get_stat_pump_cycles()

SWMM_ENGINE_API int swmm_link_get_stat_pump_cycles	(	SWMM_Engine	engine,
		int	idx,
		int *	cycles )

Get pump on/off cycle count.

swmm_link_get_stat_pump_on_time()

SWMM_ENGINE_API int swmm_link_get_stat_pump_on_time	(	SWMM_Engine	engine,
		int	idx,
		double *	seconds )

Get pump total on-time (seconds).

swmm_link_get_stat_pump_volume()

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

Get pump total volume pumped (ft3).

swmm_link_get_stat_slot_share()

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

Run-level Preissmann-slot storage share of a link.

FV routing only: the ratio of time integrals (∫ slot_volume dt)/(∫ volume dt) over the run (0..1) — never an average of instantaneous ratios. Reads 0.0 under dynamic wave.

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

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

Read the link's tag into buf (NUL-terminated, truncated if too small).

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

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

Get target control settings for all links in a single call.

Bulk variant of swmm_link_get_target_setting.

Since

6.0.0

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

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

Get cross-sectional velocities for all links in a single call.

Bulk variant of swmm_link_get_velocity. The C side recomputes q / area per link (area approximated from d / y_full * a_full), so this is a per-link loop rather than a memcpy — but still O(n_links) and free of per-call ABI overhead.

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.

Since

6.0.0

Here is the call graph for this function:

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.

Here is the call graph for this function:

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

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

Get stored volumes for all links in a single call.

Bulk variant of swmm_link_get_volume. Simple SoA memcpy.

Since

6.0.0

swmm_link_get_weir_type()

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

Get the weir flow classification.

Parameters

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

Returns

SWMM_OK on success, SWMM_ERR_BADPARAM if idx names a non-weir link.

Since

6.0.0 (engine gap BN-LINK-03, added 2026-05-25)

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.

Here is the call graph for this function:

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

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

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

Pops the tail of the link list. The engine must be in SWMM_STATE_BUILDING or SWMM_STATE_OPENED. Returns SWMM_ERR_BADINDEX if the tail doesn't match id, or SWMM_ERR_LIFECYCLE if the state is wrong.

As with swmm_node_pop_last, this is the narrow "rollback-of-add" surface; a general swmm_link_remove(idx) requires renumbering every reference (controls, reports, etc.) and is tracked separately.

Parameters

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

Returns

SWMM_OK on success, or an error code.

swmm_link_rename()

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

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

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

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

Set the orifice open/close rate (fraction per second).

0 means instantaneous open/close. The legacy SWMM-GUI surfaces this field as "Time to Open/Close" measured in hours; clients that want the hours-based UX should compute rate = 1.0 / (3600 * hours) before calling this setter.

Returns

SWMM_OK on success, SWMM_ERR_BADPARAM if idx names a non-orifice link.

Since

6.0.0 (engine gap BN-LINK-06, added 2026-05-25)

swmm_link_set_orifice_type()

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

Set the orifice flow-attack classification (SIDE / BOTTOM).

Only valid on links of type SWMM_LINK_ORIFICE; returns SWMM_ERR_BADPARAM otherwise.

Parameters

engine	Engine handle.
idx	Zero-based link index.
type	Orifice type (see SWMM_OrificeType).

Returns

SWMM_OK on success, SWMM_ERR_BADPARAM if idx names a non-orifice link or type is out of range.

Since

6.0.0 (engine gap BN-LINK-02, added 2026-05-25)

swmm_link_set_outlet_expon()

SWMM_ENGINE_API int swmm_link_set_outlet_expon	(	SWMM_Engine	engine,
		int	idx,
		double	expon )

Set the outlet functional-form exponent.

Only meaningful for FUNCTIONAL_* rating types — the engine ignores the stored value when the type is TABULAR_*. The coefficient term (Cd) is accessed via swmm_link_set_discharge_coeff / swmm_link_get_discharge_coeff.

Returns

SWMM_OK on success, SWMM_ERR_BADPARAM if idx names a non-outlet link.

Since

6.0.0 (engine gap BN-LINK-04, added 2026-05-25)

swmm_link_set_outlet_rating_type()

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

Set the outlet rating-curve classification.

Returns

SWMM_OK on success, SWMM_ERR_BADPARAM if idx names a non-outlet link or type is out of range.

Since

6.0.0 (engine gap BN-LINK-04, added 2026-05-25)

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

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

Set the pump shutoff depth (depth at upstream node when the pump turns off, project length units).

Returns

SWMM_OK on success, SWMM_ERR_BADPARAM if idx names a non-pump link.

Since

6.0.0 (engine gap BN-LINK-05, added 2026-05-25)

swmm_link_set_pump_startup_depth()

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

Set the pump startup depth (depth at upstream node when the pump turns on, project length units).

Returns

SWMM_OK on success, SWMM_ERR_BADPARAM if idx names a non-pump link.

Since

6.0.0 (engine gap BN-LINK-05, added 2026-05-25)

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.

Here is the call graph for this function:

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

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

Set or clear the link's tag. Null/empty clears. Persists across rename.

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

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

Set the weir flow classification.

Only valid on links of type SWMM_LINK_WEIR; returns SWMM_ERR_BADPARAM otherwise.

Parameters

engine	Engine handle.
idx	Zero-based link index.
type	Weir type (see SWMM_WeirType).

Returns

SWMM_OK on success, SWMM_ERR_BADPARAM if idx names a non-weir link or type is out of range.

Since

6.0.0 (engine gap BN-LINK-03, added 2026-05-25)

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.

Here is the call graph for this function:

swmm_links_restore_authored_orientation()

SWMM_ENGINE_API int swmm_links_restore_authored_orientation	(	SWMM_Engine	engine,
		int *	count )

Restore authored From/To orientation on every conduit the parser reversed for adverse slope (DYNWAVE/FV routing).

At open, adverse-slope conduits have node1/node2, offset1/offset2, initial flow sign and inlet/outlet losses swapped in place. An editing host that displays and saves the live context should call this once after open so the user sees and edits the orientation they authored. Not needed for simulation-only hosts. The .inp writer undoes the reversal on its own regardless.

Parameters

	engine	Engine handle.
[out]	count	Optional; receives the number of conduits restored.

Returns

SWMM_OK on success, or an error code.

Here is the call graph for this function: