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:

Classes
struct	SWMM_2DRunStats
	Cumulative explicit-marcher run statistics plus the backend and closure this run is on — the numbers the .rpt "2D Solver Statistics" block prints, readable DURING the run (after swmm_engine_start). More...

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

Typedefs
typedef struct SWMM_2DRunStats	SWMM_2DRunStats
	Cumulative explicit-marcher run statistics plus the backend and closure this run is on — the numbers the .rpt "2D Solver Statistics" block prints, readable DURING the run (after swmm_engine_start).

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_prepare_for_edit (SWMM_Engine engine)
	Make the parsed 2D mesh editable without a full initialize().

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_set_vertex_z_bulk (SWMM_Engine engine, const double *z, int count)
	Set EVERY vertex Z in one call.

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_cell_count (SWMM_Engine engine, int *count)
	Number of cells (triangles + quads) — same value as swmm_2d_triangle_count.

SWMM_ENGINE_API int	swmm_2d_quad_count (SWMM_Engine engine, int *count)
	Number of quadrilateral cells (0 for an all-triangle mesh).

SWMM_ENGINE_API int	swmm_2d_edge_stride (SWMM_Engine engine, int *stride)
	Edge-slot stride of the bulk edge arrays (swmm_2d_get_edge_flux_bulk, swmm_2d_edge_get_geometry_bulk, swmm_2d_get_edge_conveyance_bulk): 3 for an all-triangle mesh (the historical `[tri3 + localEdge]` layout, byte-compatible), 4 once the mesh holds any quad (`[cell4 + localEdge]`, padding slots of a triangle row are 0). Size every bulk buffer as `triangle_count * stride`.

SWMM_ENGINE_API int	swmm_2d_cell_vertex_count (SWMM_Engine engine, int idx, int *nv)
	Vertices (== edges) of a cell: 3 or 4.

SWMM_ENGINE_API int	swmm_2d_cell_get_vertices (SWMM_Engine engine, int idx, int v, int nv)
	Cell connectivity for any shape.

SWMM_ENGINE_API int	swmm_2d_cell_get_neighbours (SWMM_Engine engine, int idx, int n, int nv)
	Neighbour cell across each local edge, any shape.

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_set_triangle_mannings (SWMM_Engine engine, int idx, double n)
	Set triangle Manning's roughness coefficient.

SWMM_ENGINE_API int	swmm_2d_triangle_get_init_depth (SWMM_Engine engine, int idx, double *d)
	Get triangle initial water depth (`[2D_TRIANGLES]` INIT_DEPTH column, default 0 = dry). Value is in MESH length units — feet on a US-FLOW_UNITS project, metres on SI or on a mesh file that declared `;; UNITS: SI (m)` — the same convention as the vertex Z column.

SWMM_ENGINE_API int	swmm_2d_set_triangle_init_depth (SWMM_Engine engine, int idx, double d)
	Set triangle initial water depth (mesh length units, >= 0; SWMM_ERR_BADPARAM otherwise — see the getter for the unit convention). Converted to SI and applied to the solver state when the 2D surface initializes, and persisted in the `INIT_DEPTH` column of `[2D_TRIANGLES]` on save (written before TAG).

SWMM_ENGINE_API int	swmm_2d_triangle_get_init_velocity (SWMM_Engine engine, int idx, double u, double v)
	Get triangle initial velocity (u, v in m/s; `[2D_INITIAL_VELOCITY]` rows, default 0,0).

SWMM_ENGINE_API int	swmm_2d_set_triangle_init_velocity (SWMM_Engine engine, int idx, double u, double v)
	Set triangle initial velocity (u, v in m/s; finite values; SWMM_ERR_BADPARAM otherwise). Projected onto the explicit marcher's face normals as (hu, hv) when the 2D surface initializes (t = 0 only — hotstart/reinitialize still zeroes face momentum), and persisted as sparse `[2D_INITIAL_VELOCITY]` rows on save.

SWMM_ENGINE_API int	swmm_2d_set_vertex_tag (SWMM_Engine engine, int idx, const char *tag)
	Set the descriptive tag of a vertex (the `[2D_VERTICES]` TAG column). Distinct from the 1D<->2D coupling node. Empty / NULL clears it.

SWMM_ENGINE_API int	swmm_2d_set_triangle_tag (SWMM_Engine engine, int idx, const char *tag)
	Set the descriptive tag of a triangle (the `[2D_TRIANGLES]` TAG column, e.g. a region / subcatchment id). Empty / NULL clears it.

SWMM_ENGINE_API int	swmm_2d_get_vertex_tag (SWMM_Engine engine, int idx, char *buf, int buflen)
	Get the descriptive tag of a vertex (the `[2D_VERTICES]` TAG column). Copies up to `buflen-1` bytes into `buf` and always NUL-terminates; empty string when the vertex has no tag.

SWMM_ENGINE_API int	swmm_2d_get_triangle_tag (SWMM_Engine engine, int idx, char *buf, int buflen)
	Get the descriptive tag of a triangle (the `[2D_TRIANGLES]` TAG column). Copies up to `buflen-1` bytes into `buf` and always NUL-terminates; empty string when the triangle has no tag.

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_set_vertex_coupled_node (SWMM_Engine engine, int vertex_idx, const char *node_name)
	Set (or clear) the SWMM node a vertex is coupled to, by name.

SWMM_ENGINE_API int	swmm_2d_add_triangle_coupling (SWMM_Engine engine, int tri_idx, const char *node_name, double cd, double area)
	Append one node→cell coupling row (`[2D_TRIANGLE_NODE_MAP]` repeated-row form).

SWMM_ENGINE_API int	swmm_2d_clear_triangle_couplings (SWMM_Engine engine)
	Remove every authored node→cell coupling row (all triangles).

SWMM_ENGINE_API int	swmm_2d_triangle_coupling_rows (SWMM_Engine engine, int *count)
	Number of authored node→cell coupling rows.

SWMM_ENGINE_API int	swmm_2d_get_triangle_coupling_row (SWMM_Engine engine, int row_idx, int tri_idx, int node_idx, double cd, double area)
	Read one authored node→cell coupling row by row index.

SWMM_ENGINE_API int	swmm_2d_get_vertex_coupling_cd (SWMM_Engine engine, int vertex_idx, double *cd)
	Get the coupling discharge coefficient of a vertex (`[2D_VERTEX_NODE_MAP]` CD column; default 0.65).

SWMM_ENGINE_API int	swmm_2d_set_vertex_coupling_cd (SWMM_Engine engine, int vertex_idx, double cd)
	Set the coupling discharge coefficient of a vertex (`[2D_VERTEX_NODE_MAP]` CD column). Persisted by the `.inp` writer.

SWMM_ENGINE_API int	swmm_2d_get_vertex_coupling_area (SWMM_Engine engine, int vertex_idx, double *area)
	Get the coupling exchange area of a vertex (`[2D_VERTEX_NODE_MAP]` AREA column; default 1.0).

SWMM_ENGINE_API int	swmm_2d_set_vertex_coupling_area (SWMM_Engine engine, int vertex_idx, double area)
	Set the coupling exchange area of a vertex (`[2D_VERTEX_NODE_MAP]` AREA column). Persisted by the `.inp` writer. Same units convention as the getter: mesh length units² (project units before initialize, m² after).

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_rainfall_bulk (SWMM_Engine engine, double *rainfall)
	Bulk get the rainfall intensity (m/s) applied to every triangle this step — the same field the HDF5 `Mesh2_face_rainfall` dataset carries. Output pre-allocated to `triangle_count`.

SWMM_ENGINE_API int	swmm_2d_get_rain_volume_bulk (SWMM_Engine engine, double *volumes)
	Bulk get the cumulative rainfall VOLUME (m³) booked onto every triangle since the start of the run — the `Mesh2_face_rain_cum` field; sums over cells to the 2D mass balance's rainfall inflow. Output pre-allocated to `triangle_count`.

SWMM_ENGINE_API int	swmm_2d_get_coupling_volume_bulk (SWMM_Engine engine, double *volumes)
	Bulk get the SIGNED cumulative 1D↔2D coupling exchange VOLUME (m³) per triangle since the start of the run.

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_get_edge_conveyance (SWMM_Engine engine, int tri, int edge, double *conveyance)
	Get the per-edge conveyance factor for one edge.

SWMM_ENGINE_API int	swmm_2d_set_edge_conveyance (SWMM_Engine engine, int tri, int edge, double conveyance)
	Set the per-edge conveyance factor for one edge.

SWMM_ENGINE_API int	swmm_2d_get_edge_conveyance_bulk (SWMM_Engine engine, double *conveyance)
	Bulk get conveyance factor at every edge of every triangle.

SWMM_ENGINE_API int	swmm_2d_reset_edge_conveyance (SWMM_Engine engine)
	Reset every edge's conveyance factor to 1.0 (unrestricted).

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_vertex_get_render_depths_bulk (SWMM_Engine engine, double *depths)
	Bulk get render-oriented SIGNED vertex depths (m) 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_solver_steps (SWMM_Engine engine, long *steps)
	Get number of explicit-marcher sub-steps taken in the last advance. (Renamed from swmm_2d_get_cvode_steps with the D2 CVODE/ARKODE retirement.)

SWMM_ENGINE_API int	swmm_2d_get_solver_last_step (SWMM_Engine engine, double *h_last)
	Get the explicit marcher's last sub-step size (s). (Renamed from swmm_2d_get_cvode_last_step with the D2 CVODE/ARKODE retirement.)

SWMM_ENGINE_API int	swmm_2d_get_run_stats (SWMM_Engine engine, SWMM_2DRunStats *stats)
	Read the cumulative marcher statistics and backend of the 2D run. Counters are zero (and n_tiers 0) before the first advance and again once the solver has been finalised at swmm_engine_end; backend stays filled.

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_get_stat_max_velocities (SWMM_Engine engine, double *max_velocities)
	Get per-triangle max velocity-magnitude statistics (cumulative, m/s).

SWMM_ENGINE_API int	swmm_2d_get_stat_max_continuity_err (SWMM_Engine engine, double *max_errs)
	Get per-triangle max \|continuity residual\| statistics (cumulative, m3/s).

SWMM_ENGINE_API int	swmm_2d_get_continuity_error (SWMM_Engine engine, double *err)
	Get the global 2D surface continuity error (fraction).

SWMM_ENGINE_API int	swmm_2d_get_mass_balance (SWMM_Engine engine, double init_storage, double final_storage, double rainfall_in, double coupling_1d_to_2d_in, double coupling_2d_to_1d_out, double outfall_in, double outfall_out, double boundary_in, double boundary_out, double evap_out)
	Get the global 2D mass-balance terms (all m3). Any pointer may be NULL.

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_evap (SWMM_Engine engine, int idx, double value, int mode, int persist)
	Force evaporation on a specific triangle.

SWMM_ENGINE_API int	swmm_2d_force_evap_uniform (SWMM_Engine engine, double value, int mode, int persist)
	Force evaporation 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_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 (same units convention as the getter).

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_tseries_name (SWMM_Engine engine, int tri_idx, int edge, char *buf, int buflen)
	Get the timeseries NAME driving 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 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 (same units convention as the getter: display flow units/m before initialize, m³/s/m after). 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_get_edge_bc_flow_tseries_name (SWMM_Engine engine, int tri_idx, int edge, char *buf, int buflen)
	Get the timeseries NAME driving a SPECIFIED_FLOW edge. SVBC A8 — same contract as `swmm_2d_get_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_rating_curve_name (SWMM_Engine engine, int tri_idx, int edge, char *buf, int buflen)
	Get the curve NAME driving a RATING_CURVE edge. SVBC A8 — same contract as `swmm_2d_get_edge_bc_tseries_name`.

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).

SWMM_ENGINE_API int	swmm_2d_output_variable_count (void)

SWMM_ENGINE_API const char *	swmm_2d_output_variable_name (int i)

SWMM_ENGINE_API unsigned	swmm_2d_output_variable_mask (const char *text)

SWMM_ENGINE_API const char *	swmm_2d_output_variable_text (unsigned mask)

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. All five types are enforced at flux time by the explicit marcher (SurfaceFluxCalculator::boundaryEdgeFlux); timeseries and rating-curve driving values are re-resolved every step. Note a NORMAL_FLOW edge with zero bed slope produces zero flux (behaves as a Wall).

◆ SWMM_ENGINE_API

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

Function Documentation

◆ swmm_2d_get_edge_bc_flow_tseries_name()

SWMM_ENGINE_API int swmm_2d_get_edge_bc_flow_tseries_name	(	SWMM_Engine	engine,
		int	tri_idx,
		int	edge,
		char *	buf,
		int	buflen )

Get the timeseries NAME driving a SPECIFIED_FLOW edge. SVBC A8 — same contract as swmm_2d_get_edge_bc_tseries_name.