Optional 2D surface routing module — C API. More...

#include "openswmm_callbacks.h"

Include dependency graph for openswmm_2d.h:

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

Macros
#define	SWMM_ENGINE_API __attribute__((visibility("default")))

#define	SWMM_2D_BC_WALL 0

#define	SWMM_2D_BC_NORMAL_FLOW 1

#define	SWMM_2D_BC_SPECIFIED_STAGE 2

#define	SWMM_2D_BC_SPECIFIED_FLOW 3

#define	SWMM_2D_BC_RATING_CURVE 4

Functions
SWMM_ENGINE_API int	swmm_2d_is_active (SWMM_Engine engine, int *active)
	Check whether the 2D module is active for this simulation.

SWMM_ENGINE_API int	swmm_2d_vertex_count (SWMM_Engine engine, int *count)
	Get the number of mesh vertices.

SWMM_ENGINE_API int	swmm_2d_triangle_count (SWMM_Engine engine, int *count)
	Get the number of mesh triangles.

SWMM_ENGINE_API int	swmm_2d_vertex_get_xyz (SWMM_Engine engine, int idx, double x, double y, double *z)
	Get vertex coordinates.

SWMM_ENGINE_API int	swmm_2d_vertex_get_xyz_bulk (SWMM_Engine engine, double x, double y, double *z)
	Bulk get vertex coordinates.

SWMM_ENGINE_API int	swmm_2d_set_vertex_z (SWMM_Engine engine, int idx, double z)
	Set vertex Z (ground elevation).

SWMM_ENGINE_API int	swmm_2d_triangle_get_vertices (SWMM_Engine engine, int idx, int v0, int v1, int *v2)
	Get triangle connectivity (3 vertex indices).

SWMM_ENGINE_API int	swmm_2d_triangle_get_area (SWMM_Engine engine, int idx, double *area)
	Get triangle area.

SWMM_ENGINE_API int	swmm_2d_triangle_get_centroid (SWMM_Engine engine, int idx, double cx, double cy, double *cz)
	Get triangle centroid coordinates.

SWMM_ENGINE_API int	swmm_2d_triangle_get_mannings (SWMM_Engine engine, int idx, double *n)
	Get triangle Manning's roughness.

SWMM_ENGINE_API int	swmm_2d_triangle_get_neighbours (SWMM_Engine engine, int idx, int n0, int n1, int *n2)
	Get triangle neighbour indices (-1 = boundary edge).

SWMM_ENGINE_API int	swmm_2d_edge_get_geometry_bulk (SWMM_Engine engine, double length, double nx, double *ny)
	Bulk get edge geometry — time-invariant edge length and outward unit normal components, indexed `[tri*3 + localEdge]`.

SWMM_ENGINE_API int	swmm_2d_vertex_coupling_count (SWMM_Engine engine, int *count)
	Get the number of vertex-to-node coupling points.

SWMM_ENGINE_API int	swmm_2d_triangle_coupling_count (SWMM_Engine engine, int *count)
	Get the number of triangle-to-node coupling points.

SWMM_ENGINE_API int	swmm_2d_vertex_get_coupled_node (SWMM_Engine engine, int vertex_idx, int *node_idx)
	Get vertex coupling: which SWMM node is coupled to this vertex.

SWMM_ENGINE_API int	swmm_2d_triangle_get_coupled_node (SWMM_Engine engine, int tri_idx, int *node_idx)
	Get triangle coupling: which SWMM node is coupled to this triangle.

SWMM_ENGINE_API int	swmm_2d_get_depth (SWMM_Engine engine, int idx, double *depth)
	Get water depth at a triangle.

SWMM_ENGINE_API int	swmm_2d_get_head (SWMM_Engine engine, int idx, double *head)
	Get total head at a triangle (z + depth).

SWMM_ENGINE_API int	swmm_2d_get_coupling_flux (SWMM_Engine engine, int idx, double *flux)
	Get coupling exchange flux at a triangle (m/s, + = into 2D).

SWMM_ENGINE_API int	swmm_2d_get_rainfall (SWMM_Engine engine, int idx, double *rainfall)
	Get rainfall intensity at a triangle (m/s).

SWMM_ENGINE_API int	swmm_2d_get_net_source (SWMM_Engine engine, int idx, double *net_source)
	Get net source/sink rate at a triangle (m/s).

SWMM_ENGINE_API int	swmm_2d_get_depths_bulk (SWMM_Engine engine, double *depths)
	Bulk get depths for all triangles.

SWMM_ENGINE_API int	swmm_2d_get_heads_bulk (SWMM_Engine engine, double *heads)
	Bulk get heads for all triangles.

SWMM_ENGINE_API int	swmm_2d_get_coupling_fluxes_bulk (SWMM_Engine engine, double *fluxes)
	Bulk get coupling fluxes for all triangles.

SWMM_ENGINE_API int	swmm_2d_get_edge_flux_bulk (SWMM_Engine engine, double *flux)
	Bulk get normal edge flux at every edge of every triangle.

SWMM_ENGINE_API int	swmm_2d_vertex_get_head (SWMM_Engine engine, int idx, double *head)
	Get reconstructed head at a vertex.

SWMM_ENGINE_API int	swmm_2d_vertex_get_heads_bulk (SWMM_Engine engine, double *heads)
	Bulk get reconstructed heads at all vertices.

SWMM_ENGINE_API int	swmm_2d_get_max_depth (SWMM_Engine engine, double *max_depth)
	Get the maximum depth across all triangles.

SWMM_ENGINE_API int	swmm_2d_get_total_volume (SWMM_Engine engine, double *volume)
	Get total 2D surface volume (sum of depth * area).

SWMM_ENGINE_API int	swmm_2d_get_total_exchange_flow (SWMM_Engine engine, double *flow)
	Get total exchange flow rate (sum of all coupling flows, m³/s). Positive = net flow from 2D into 1D network.

SWMM_ENGINE_API int	swmm_2d_get_cvode_steps (SWMM_Engine engine, long *steps)
	Get number of CVODE internal steps taken in the last advance.

SWMM_ENGINE_API int	swmm_2d_get_cvode_last_step (SWMM_Engine engine, double *h_last)
	Get CVODE last internal step size.

SWMM_ENGINE_API int	swmm_2d_get_stat_max_depths (SWMM_Engine engine, double *max_depths)
	Get per-triangle max depth statistics (cumulative).

SWMM_ENGINE_API int	swmm_2d_force_rainfall (SWMM_Engine engine, int idx, double value, int mode, int persist)
	Force rainfall on a specific triangle.

SWMM_ENGINE_API int	swmm_2d_force_rainfall_uniform (SWMM_Engine engine, double value, int mode, int persist)
	Force rainfall on all triangles (uniform).

SWMM_ENGINE_API int	swmm_2d_force_coupling_flux (SWMM_Engine engine, int idx, double value, int mode, int persist)
	Force coupling flux on a specific triangle (override computed exchange).

SWMM_ENGINE_API int	swmm_2d_force_clear_all (SWMM_Engine engine)
	Clear all 2D forcings.

SWMM_ENGINE_API int	swmm_2d_get_dry_depth (SWMM_Engine engine, double *dry_depth)
	Get the dry depth threshold (m).

SWMM_ENGINE_API int	swmm_2d_set_dry_depth (SWMM_Engine engine, double dry_depth)
	Set the dry depth threshold (m).

SWMM_ENGINE_API int	swmm_2d_get_rel_tolerance (SWMM_Engine engine, double *rtol)
	Get CVODE relative tolerance.

SWMM_ENGINE_API int	swmm_2d_set_rel_tolerance (SWMM_Engine engine, double rtol)
	Set CVODE relative tolerance.

SWMM_ENGINE_API int	swmm_2d_get_abs_tolerance (SWMM_Engine engine, double *atol)
	Get CVODE absolute tolerance.

SWMM_ENGINE_API int	swmm_2d_set_abs_tolerance (SWMM_Engine engine, double atol)
	Set CVODE absolute tolerance.

SWMM_ENGINE_API int	swmm_2d_boundary_edge_count (SWMM_Engine engine, int *count)
	Get the number of boundary edges (edges with no neighbour).

SWMM_ENGINE_API int	swmm_2d_get_edge_bc_type (SWMM_Engine engine, int tri_idx, int edge, int *bc_type)
	Get boundary condition type for an edge.

SWMM_ENGINE_API int	swmm_2d_set_edge_bc_type (SWMM_Engine engine, int tri_idx, int edge, int bc_type)
	Set boundary condition type for an edge.

SWMM_ENGINE_API int	swmm_2d_get_edge_bc_head (SWMM_Engine engine, int tri_idx, int edge, double *head)
	Get specified stage boundary head for an edge.

SWMM_ENGINE_API int	swmm_2d_set_edge_bc_head (SWMM_Engine engine, int tri_idx, int edge, double head)
	Set specified stage boundary head for an edge.

SWMM_ENGINE_API int	swmm_2d_get_edge_bc_slope (SWMM_Engine engine, int tri_idx, int edge, double *slope)
	Get normal flow boundary slope for an edge.

SWMM_ENGINE_API int	swmm_2d_set_edge_bc_slope (SWMM_Engine engine, int tri_idx, int edge, double slope)
	Set normal flow boundary slope for an edge.

SWMM_ENGINE_API int	swmm_2d_set_edge_bc_tseries_name (SWMM_Engine engine, int tri_idx, int edge, const char *name)
	Set the timeseries NAME to drive a SPECIFIED_STAGE edge.

SWMM_ENGINE_API int	swmm_2d_get_edge_bc_flow (SWMM_Engine engine, int tri_idx, int edge, double *flow)
	Get prescribed flow per metre of edge (m³/s/m) for a SPECIFIED_FLOW edge. V-E4.

SWMM_ENGINE_API int	swmm_2d_set_edge_bc_flow (SWMM_Engine engine, int tri_idx, int edge, double flow)
	Set prescribed flow per metre of edge (m³/s/m). V-E4.

SWMM_ENGINE_API int	swmm_2d_set_edge_bc_flow_tseries_name (SWMM_Engine engine, int tri_idx, int edge, const char *name)
	Set the timeseries NAME to drive a SPECIFIED_FLOW edge. V-E4 — same resolution contract as `swmm_2d_set_edge_bc_tseries_name`.

SWMM_ENGINE_API int	swmm_2d_set_edge_bc_rating_curve_name (SWMM_Engine engine, int tri_idx, int edge, const char *name)
	Set the curve NAME to drive a RATING_CURVE edge.

SWMM_ENGINE_API int	swmm_2d_get_edge_bc_cum_flux (SWMM_Engine engine, int tri_idx, int edge, double *cum_flux)
	Get cumulative boundary flux at an edge (m³, + = outflow).

Detailed Description

Optional 2D surface routing module — C API.

Provides query and control of the optional 2D surface routing module coupled to the 1D SWMM pipe network. The 2D module is active when [2D_VERTICES] and [2D_TRIANGLES] sections are present in the input file and the engine was compiled with OPENSWMM_BUILD_2D.

All functions require the engine to be in SWMM_STATE_RUNNING unless otherwise noted. Functions return SWMM_ERR_BADPARAM if the 2D module is not active.

Macro Definition Documentation

◆ SWMM_2D_BC_NORMAL_FLOW

#define SWMM_2D_BC_NORMAL_FLOW 1

◆ SWMM_2D_BC_RATING_CURVE

#define SWMM_2D_BC_RATING_CURVE 4

V-E5.

◆ SWMM_2D_BC_SPECIFIED_FLOW

#define SWMM_2D_BC_SPECIFIED_FLOW 3

V-E4.

◆ SWMM_2D_BC_SPECIFIED_STAGE

#define SWMM_2D_BC_SPECIFIED_STAGE 2

◆ SWMM_2D_BC_WALL

#define SWMM_2D_BC_WALL 0

Boundary condition type constants.

WALL / NORMAL_FLOW / SPECIFIED_STAGE were the original three; the SPECIFIED_FLOW (3) and RATING_CURVE (4) values were added per GUI plan §V V-E4 / V-E5. Storage + this C API only at this revision — the FV-SWE flux integration for non-Wall BCs is deferred to a separate slice (V-E-FLUX). The solver still treats every boundary edge as Wall regardless of type today (see SurfaceFluxCalculator.cpp:131).

◆ SWMM_ENGINE_API

#define SWMM_ENGINE_API __attribute__((visibility("default")))

Function Documentation

◆ swmm_2d_set_edge_bc_flow()

SWMM_ENGINE_API int swmm_2d_set_edge_bc_flow	(	SWMM_Engine	engine,
		int	tri_idx,
		int	edge,
		double	flow
	)

Set prescribed flow per metre of edge (m³/s/m). V-E4.

◆ swmm_2d_set_edge_bc_flow_tseries_name()

SWMM_ENGINE_API int swmm_2d_set_edge_bc_flow_tseries_name	(	SWMM_Engine	engine,
		int	tri_idx,
		int	edge,
		const char *	name
	)

Set the timeseries NAME to drive a SPECIFIED_FLOW edge. V-E4 — same resolution contract as swmm_2d_set_edge_bc_tseries_name.

◆ swmm_2d_set_edge_bc_rating_curve_name()

SWMM_ENGINE_API int swmm_2d_set_edge_bc_rating_curve_name	(	SWMM_Engine	engine,
		int	tri_idx,
		int	edge,
		const char *	name
	)

Set the curve NAME to drive a RATING_CURVE edge.

V-E5. Stage → flow lookup is resolved against the existing swmm_curve_* registry on the next forcing-step lookup. Empty name clears the slot.

Macros

Functions