Collaboration diagram for 2D Surface Routing API:

Topics
	2D Infiltration API

Files
file	Api2D.cpp
	C API implementation for the 2D surface routing module.

file	Api2D.hpp
	C API implementation bridge for the 2D surface routing module.

file	ApiGw2D.cpp
	G-step 19 — implementation of `openswmm_gw2d.h`.

file	NodeCoupling.cpp
	Implementation of 2D↔1D node coupling via orifice exchange.

file	NodeCoupling.hpp
	Orifice-equation exchange between 2D surface and SWMM nodes.

file	BoundaryData.hpp
	Structure-of-Arrays (SoA) storage for 2D mesh boundary conditions.

file	MeshData.hpp
	Structure-of-Arrays (SoA) storage for 2D triangular mesh geometry.

file	PendingRows2D.hpp
	Parse-time scratch rows for [2D_BOUNDARY_CONDITIONS] and [2D_EDGE_CONVEYANCE] input sections.

file	Serialize2D.hpp
	Header-only helpers shared by 2D model serialization consumers (InpWriter `[2D_*]` emission, GeoPackage writer).

file	SolverOptions2D.hpp
	Configuration options for the 2D surface routing solver.

file	SurfaceStateData.hpp
	Structure-of-Arrays (SoA) storage for 2D surface routing state.

file	SurfaceTransportState.hpp
	Overland transport S1 — per-cell species MASS on the 2D surface.

file	GwTransportData.hpp
	U4 (2026-09-07) — authoring state for subsurface (groundwater) transport: `[GW_TRANSPORT_OPTIONS]`, `[GW_TRANSPORT_PARAMS]`, `[GW_SORPTION]`, `[GW_INITIAL_QUALITY]`, `[GW_BOUNDARY_QUALITY]` and `[GW_SOURCES]`.

file	GwTransportSections.hpp
	U4 (2026-09-07) — parsers and registration for the `[GW_*]` subsurface-transport authoring sections. See GwTransportData.hpp for the shape and the authoring-only contract.

file	SectionHandlers2D.cpp
	Implementation of 2D input section parsers.

file	SectionHandlers2D.hpp
	Input section parsers for the 2D surface routing module.

file	MeshBuilder.cpp
	Implementation of mesh topology construction and geometry computation.

file	MeshBuilder.hpp
	Topology construction and geometry precomputation for the 2D mesh.

file	QuadVfr.hpp
	Volume–free-surface relationship (VFR) for a quadrilateral cell.

file	RainfallInterpolator.cpp
	Implementation of natural-neighbour / IDW rainfall interpolation.

file	RainfallInterpolator.hpp
	Static per-cell weights mapping raingage rainfall onto the 2D mesh.

file	VertexReconstruction.cpp
	Implementation of pseudo-Laplacian vertex stencil construction and head reconstruction.

file	VertexReconstruction.hpp
	Pseudo-Laplacian vertex reconstruction stencil computation.

file	VfrClosure.hpp
	Volume–free-surface (VFR) closure for a planar-bed triangular cell.

file	Default2DOutputPlugin.cpp
	HDF5 output plugin for 2D surface routing results (CF/UGRID).

file	Default2DOutputPlugin.hpp
	Built-in HDF5 output plugin for 2D surface routing results.

file	DiffusiveKernels.hpp
	Face law and step bound for MOMENTUM_EQUATION DIFFUSIVE_WAVE (plans/2D_FULL_SWE_SHOCK_CAPTURING_PLAN_2026-09-05.md §2.3).

file	ExplicitInertialSolver.cpp
	Implementation of the explicit local-inertial FV marcher with power-of-two tiered local timestepping (LTS).

file	ExplicitInertialSolver.hpp
	Explicit local-inertial FV time-marcher for the 2D surface.

file	InertialEdges.cpp
	Implementation of the unique interior-edge builder.

file	InertialEdges.hpp
	Unique interior-edge structure for the local-inertial momentum DOFs.

file	InertialKernels.hpp
	Single-source flat kernels for the explicit local-inertial marcher.

file	ISurfaceSolver.hpp
	Backend-neutral interface for the 2D surface-routing time integrator.

file	SurfaceFluxCalculator.cpp
	Implementation of gradient computation, slope limiting, and edge fluxes.

file	SurfaceFluxCalculator.hpp
	Edge flux computation, gradient calculation, and slope limiting.

file	SurfaceSolverFactory.cpp
	Implementation of runtime 2D surface-solver backend selection.

file	SurfaceSolverFactory.hpp
	Runtime selection of the 2D surface solver backend (Phase 4).

file	SweKernels.hpp
	Face kernels for MOMENTUM_EQUATION FULL_SWE — the conservative shallow-water equations with the convective term and shock capturing (plans/2D_FULL_SWE_SHOCK_CAPTURING_PLAN_2026-09-05.md §2.2).

file	SigmaColumn.hpp
	G-steps 4 and 5 — closure B: the σ-coordinate explicit unsaturated column with a moving lower boundary (the water table).

file	SoilCharacteristic.hpp
	G-steps 2 and 13 — the four production soil-characteristic laws and the closure-A quasi-steady recharge `q₀(hᵤ, h_g)`.

file	SubsurfaceData.cpp
	Sizing, storage accounting and token round-trip for the two-zone groundwater state (G-step 1).

file	SubsurfaceData.hpp
	G-step 1 — state, parameters and options for the two-zone groundwater kernel (TWO_ZONE_GROUNDWATER_EXPLICIT_LTS_PLAN §4).

file	SubsurfaceSections.cpp
	Parsers, resolution and writer for the `[2D_AQUIFER*]` sections.

file	SubsurfaceSections.hpp
	G-step 1 — `[2D_AQUIFER_OPTIONS]`, `[2D_AQUIFER]` and `[2D_AQUIFER_NODE]`: parsing, unit resolution and writing.

file	SubsurfaceSolver.cpp
	The two-zone groundwater kernel (G-steps 3, 6-12, 14, 16).

file	SubsurfaceSolver.hpp
	G-steps 3, 6-12, 16 — the two-zone groundwater kernel: saturated FV update, lateral Darcy, closure dispatch, node exchange, Dunne transfer, ET, and the LTS tier hooks the surface marcher calls.

file	SurfaceRouter2D.cpp
	Implementation of the 2D surface routing orchestrator.

file	SurfaceRouter2D.hpp
	Top-level orchestrator for the optional 2D surface routing module.

file	openswmm_gw2d.h
	G-step 19 — the two-zone groundwater kernel's C API: authoring the `[2D_AQUIFER*]` rows, and reading the state and ledger while a run is in flight.

file	openswmm_gw_transport.h
	U4 (2026-09-07) — C API for the `[GW_*]` subsurface-transport authoring sections.

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

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_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

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_2DRunStats

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

Function Documentation

◆ swmm_2d_add_triangle_coupling()

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

A triangle may carry several coupling rows — one per node — so this APPENDS rather than overwrites (contrast swmm_2d_set_vertex_coupled_node). The node NAME is stored verbatim and resolved against the current model (-1 tolerated until re-resolution, mirroring the vertex setter). The .inp writer emits one [2D_TRIANGLE_NODE_MAP] row per coupling.

Parameters

tri_idx	Triangle index in `[0, triangle_count)`.
node_name	SWMM node id (must be non-empty).
cd	Discharge coefficient; must be > 0 (engine default 0.65).
area	Effective exchange area, m²; must be > 0.

Returns: SWMM_OK; SWMM_ERR_BADINDEX on bad triangle; SWMM_ERR_BADPARAM on empty name / non-positive cd or area.

◆ swmm_2d_boundary_edge_count()

SWMM_ENGINE_API int swmm_2d_boundary_edge_count	(	SWMM_Engine	engine,
		int *	count )

Get the number of boundary edges (edges with no neighbour).

Here is the call graph for this function:

◆ swmm_2d_cell_count()

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

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.

Parameters

n	Caller-provided int[4]; −1 = boundary edge, −2 = padding slot.
nv	Output edge count (3 or 4).

◆ swmm_2d_cell_get_vertices()

SWMM_ENGINE_API int swmm_2d_cell_get_vertices	(	SWMM_Engine	engine,
		int	idx,
		int *	v,
		int *	nv )

Cell connectivity for any shape.

Parameters

v	Caller-provided int[4]; slots beyond `nv` are −1.
nv	Output vertex count (3 or 4).

◆ swmm_2d_cell_vertex_count()

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

SWMM_ENGINE_API int swmm_2d_clear_triangle_couplings ( SWMM_Engine engine )

Remove every authored node→cell coupling row (all triangles).

Also clears the legacy per-triangle mirror (coupled node, CD, AREA back to defaults). Vertex couplings are untouched. Typical use: the GUI's Remap 1D↔2D re-authoring the full cell-coupling set.

◆ swmm_2d_edge_get_geometry_bulk()

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

Output arrays must be pre-allocated to triangle_count * 3 doubles each. Local edge e is the edge opposite vertex e (matching the neighbour convention of swmm_2d_triangle_get_neighbours). Outward normals point away from the triangle interior. Provided so client-side velocity reconstruction from swmm_2d_get_edge_flux_bulk can run without re-deriving geometry from the vertex coordinates.

Here is the call graph for this function:

◆ swmm_2d_edge_stride()

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 [tri*3 + localEdge] layout, byte-compatible), 4 once the mesh holds any quad ([cell*4 + localEdge], padding slots of a triangle row are 0). Size every bulk buffer as triangle_count * stride.

◆ swmm_2d_force_clear_all()

SWMM_ENGINE_API int swmm_2d_force_clear_all ( SWMM_Engine engine )

Clear all 2D forcings.

◆ swmm_2d_force_coupling_flux()

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

Parameters

value Flux rate (m/s, + = into 2D).

◆ swmm_2d_force_evap()

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.

The rate is a demand: wet cells lose depth at this rate, shut off smoothly as a cell dries (depths never go negative). Default rate is 0 until forced. Negative values are treated as zero (no condensation).

Parameters

idx	Triangle index.
value	Evaporation rate (m/s — same SI convention as rainfall).
mode	SWMM_FORCING_OVERRIDE or SWMM_FORCING_ADD.
persist	SWMM_FORCING_RESET or SWMM_FORCING_PERSIST.

◆ swmm_2d_force_evap_uniform()

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

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.

Parameters

idx	Triangle index.
value	Rainfall rate (m/s).
mode	SWMM_FORCING_OVERRIDE or SWMM_FORCING_ADD.
persist	SWMM_FORCING_RESET or SWMM_FORCING_PERSIST.

◆ swmm_2d_force_rainfall_uniform()

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

SWMM_ENGINE_API int swmm_2d_get_continuity_error	(	SWMM_Engine	engine,
		double *	err )

Get the global 2D surface continuity error (fraction).

Parameters

err	Output: (total_in - total_out) / total_in.

◆ swmm_2d_get_coupling_flux()

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

SWMM_ENGINE_API int swmm_2d_get_coupling_fluxes_bulk	(	SWMM_Engine	engine,
		double *	fluxes )

Bulk get coupling fluxes for all triangles.

◆ swmm_2d_get_coupling_volume_bulk()

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.

Sign is from the 2D cell's point of view: positive = the 1D node delivered water INTO this cell (spill, submerged-outfall discharge); negative = the node abstracted water FROM it (drain). Output pre-allocated to triangle_count.

Summing the array gives coupling_1d_to_2d_in − coupling_2d_to_1d_out from the 2D mass balance — the identity that ties this per-cell series to the domain totals, and the natural check for a validator.

Why signed and per cell: the two domain accumulators are unsigned and cannot answer "what did THIS cell give or take", which is exactly the question at a coupling point that reverses within a batch — the two directions cancel in the net and neither is visible in the totals. swmm_2d_get_coupling_flux is a rate that is overwritten every step.

◆ swmm_2d_get_depth()

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

Get water depth at a triangle.

Parameters

idx	Triangle index.
depth	Output depth (m or ft).

◆ swmm_2d_get_depths_bulk()

SWMM_ENGINE_API int swmm_2d_get_depths_bulk	(	SWMM_Engine	engine,
		double *	depths )

Bulk get depths for all triangles.

Parameters

depths Output array (pre-allocated to triangle_count).

◆ swmm_2d_get_dry_depth()

SWMM_ENGINE_API int swmm_2d_get_dry_depth	(	SWMM_Engine	engine,
		double *	dry_depth )

Get the dry depth threshold (m).

◆ swmm_2d_get_edge_bc_cum_flux()

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

Here is the call graph for this function:

◆ swmm_2d_get_edge_bc_flow()

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.

Units: project display flow units per metre (the [2D_BOUNDARY_CONDITIONS] file contract, e.g. CFS/m) before swmm_engine_initialize(); m³/s/m after it (initialize scales the constants in place; the writers scale back).

Here is the call graph for this function:

◆ swmm_2d_get_edge_bc_head()

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.

Units follow the mesh vertical datum: mesh length units as authored (feet for a US project without an SI mesh header) before swmm_engine_initialize(), metres after it.

Here is the call graph for this function:

◆ swmm_2d_get_edge_bc_slope()

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.

Here is the call graph for this function:

◆ swmm_2d_get_edge_bc_tseries_name()

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.

SVBC A8 — the setter's mirror, so a caller can verify what the engine holds after an edit push. Works in the OPENED state (mesh guard, like the setter). Truncating copy into buf, always NUL-terminated.

Here is the call graph for this function:

◆ swmm_2d_get_edge_bc_type()

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.

Parameters

tri_idx	Triangle index (0-based).
edge	Local edge index (0, 1, or 2).
bc_type	Output: one of the SWMM_2D_BC_* constants.

Here is the call graph for this function:

◆ swmm_2d_get_edge_conveyance()

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.

Parameters

tri	Triangle index in `[0, triangle_count)`.
edge	Local edge index in `{0, 1, 2}`.
conveyance	Output value in `[0, 1]`.

Returns: SWMM_OK on success; SWMM_ERR_BADINDEX on out-of-range tri/edge.

Here is the call graph for this function:

◆ swmm_2d_get_edge_conveyance_bulk()

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.

Output array must be pre-allocated to triangle_count * 3 doubles, indexed [tri*3 + edge_local].

Here is the call graph for this function:

◆ swmm_2d_get_edge_flux_bulk()

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.

Output array must be pre-allocated to triangle_count * 3 doubles, indexed [tri*3 + localEdge]. Sign convention: positive flux flows outward through the edge's outward normal (positive = leaving the cell). NOTE: the integrator stores edge_flux INFLOW-positive internally (a positive value raises the cell depth); this accessor (and the HDF5 Mesh2_edge_flux dataset) flip the sign so the public convention is outward-positive as documented here. Units m^2 s^-1 (depth-integrated normal speed). Combine with swmm_2d_edge_get_geometry_bulk to reconstruct cell-centred velocity (RT0): for each triangle, solve (NᵀN) v = Nᵀ q where rows of N are the outward unit normals and q[e] = flux[e] / length[e]; with the outward-positive sign this yields the physical (down-gradient) velocity.

Here is the call graph for this function:

◆ swmm_2d_get_head()

SWMM_ENGINE_API int swmm_2d_get_head	(	SWMM_Engine	engine,
		int	idx,
		double *	head )

Get total head at a triangle (z + depth).

◆ swmm_2d_get_heads_bulk()

SWMM_ENGINE_API int swmm_2d_get_heads_bulk	(	SWMM_Engine	engine,
		double *	heads )

Bulk get heads for all triangles.

◆ swmm_2d_get_mass_balance()

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.

Parameters

outfall_out	Cumulative 2D→pipe withdrawal at submerged outfalls (m3).
evap_out	Cumulative evaporation loss from the 2D surface (m3).

◆ swmm_2d_get_max_depth()

SWMM_ENGINE_API int swmm_2d_get_max_depth	(	SWMM_Engine	engine,
		double *	max_depth )

Get the maximum depth across all triangles.

◆ swmm_2d_get_net_source()

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

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

SWMM_ENGINE_API int swmm_2d_get_rainfall	(	SWMM_Engine	engine,
		int	idx,
		double *	rainfall )

Get rainfall intensity at a triangle (m/s).

◆ swmm_2d_get_rainfall_bulk()

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

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

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

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

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

Parameters

max_errs Output array (pre-allocated to triangle_count).

◆ swmm_2d_get_stat_max_depths()

SWMM_ENGINE_API int swmm_2d_get_stat_max_depths	(	SWMM_Engine	engine,
		double *	max_depths )

Get per-triangle max depth statistics (cumulative).

Parameters

max_depths Output array (pre-allocated to triangle_count).

◆ swmm_2d_get_stat_max_velocities()

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

Parameters

max_velocities Output array (pre-allocated to triangle_count).

◆ swmm_2d_get_total_exchange_flow()

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

SWMM_ENGINE_API int swmm_2d_get_total_volume	(	SWMM_Engine	engine,
		double *	volume )

Get total 2D surface volume (sum of depth * area).

◆ swmm_2d_get_triangle_coupling_row()

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.

Parameters

row_idx	Row index in `[0, swmm_2d_triangle_coupling_rows)`.
tri_idx	Output triangle index.
node_idx	Output SWMM node index (-1 if unresolved).
cd	Output discharge coefficient.
area	Output exchange area (m²).

◆ swmm_2d_get_triangle_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_2d_get_vertex_coupling_area()

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

Units follow the MESH: mesh length units squared as authored (ft² for a US-FLOW_UNITS project unless the mesh file declares ;; UNITS: SI (m)), converted to m² in place by swmm_engine_initialize() together with the vertex coordinates. Before initialize the value is therefore in mesh (project) units; after it, m².

Parameters

vertex_idx	Vertex index in `[0, vertex_count)`.
area	Output exchange area (mesh length units²).

◆ swmm_2d_get_vertex_coupling_cd()

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

Parameters

vertex_idx	Vertex index in `[0, vertex_count)`.
cd	Output discharge coefficient.

◆ swmm_2d_get_vertex_tag()

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

SWMM_ENGINE_API int swmm_2d_is_active	(	SWMM_Engine	engine,
		int *	active )

Check whether the 2D module is active for this simulation.

Parameters

engine	Engine handle.
active	Output: 1 if 2D is active, 0 otherwise.

Returns: SWMM_OK or error code.

Note: Valid after SWMM_STATE_INITIALIZED.

◆ swmm_2d_prepare_for_edit()

SWMM_ENGINE_API int swmm_2d_prepare_for_edit ( SWMM_Engine engine )

Make the parsed 2D mesh editable without a full initialize().

The mesh-edit/query setters work as soon as the mesh is parsed (OPENED state) — they do not require the solver to be initialized. Per-edge BC and conveyance edits additionally need the authored [2D_BOUNDARY_CONDITIONS] / [2D_EDGE_CONVEYANCE] rows drained into live storage first; call this once before editing those so the changes take effect and are written on save. No-op when already initialized/drained or when no mesh is loaded.

Returns: SWMM_OK, or SWMM_ERR_BADPARAM when no 2D mesh is present.

◆ swmm_2d_quad_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_2d_reset_edge_conveyance()

SWMM_ENGINE_API int swmm_2d_reset_edge_conveyance ( SWMM_Engine engine )

Reset every edge's conveyance factor to 1.0 (unrestricted).

◆ swmm_2d_set_dry_depth()

SWMM_ENGINE_API int swmm_2d_set_dry_depth	(	SWMM_Engine	engine,
		double	dry_depth )

Set the dry depth threshold (m).

◆ swmm_2d_set_edge_bc_head()

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

Here is the call graph for this function:

◆ swmm_2d_set_edge_bc_slope()

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.

Here is the call graph for this function:

◆ swmm_2d_set_edge_bc_tseries_name()

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.

V-E2. Stores the name verbatim; the engine resolves it into a table index from SimulationContext::tables on the next forcing-step lookup (until then edge_bc_tseries[idx] is -2). Empty name clears the slot (back to constant edge_bc_head).

Here is the call graph for this function:

◆ swmm_2d_set_edge_bc_type()

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.

Here is the call graph for this function:

◆ swmm_2d_set_edge_conveyance()

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.

The value is rejected if outside [0, 1] (SWMM_ERR_BADPARAM). When the edge is interior (has a neighbour) the value is mirrored to the partner slot on the neighbour triangle so antisymmetry is preserved.

Parameters

tri	Triangle index in `[0, triangle_count)`.
edge	Local edge index in `{0, 1, 2}`.
conveyance	New value in `[0, 1]`.

Returns: SWMM_OK on success; SWMM_ERR_BADINDEX / SWMM_ERR_BADPARAM on invalid arguments.

Here is the call graph for this function:

◆ swmm_2d_set_triangle_init_depth()

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

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 (h*u, h*v) 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_2d_set_triangle_mannings()

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

Set triangle Manning's roughness coefficient.

Rejected if not strictly positive (SWMM_ERR_BADPARAM). Persists in the MANNINGS_N column of [2D_TRIANGLES] on save.

◆ swmm_2d_set_triangle_tag()

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

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.

Stores the node NAME verbatim and resolves it to an index against the current model (-1 when not found, mirroring the deferred-resolution rule in SurfaceRouter2D::initialize). An empty / NULL name clears the coupling (name cleared, index set to -1). Discharge coefficient and exchange area keep their existing values (defaults 0.65 / 1.0 for a freshly coupled vertex); only the node association is changed. The .inp writer emits the name in [2D_VERTEX_NODE_MAP], so this is what persists an interactive coupling edit on save.

Parameters

vertex_idx	Vertex index in `[0, vertex_count)`.
node_name	SWMM node id, or "" / NULL to clear.

Returns: SWMM_OK on success; SWMM_ERR_BADINDEX on out-of-range vertex.

◆ swmm_2d_set_vertex_coupling_area()

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

Parameters

vertex_idx	Vertex index in `[0, vertex_count)`.
area	Exchange area in mesh length units²; must be > 0.

Returns: SWMM_OK on success; SWMM_ERR_BADPARAM on non-positive area.

◆ swmm_2d_set_vertex_coupling_cd()

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.

Parameters

vertex_idx	Vertex index in `[0, vertex_count)`.
cd	Discharge coefficient; must be > 0.

Returns: SWMM_OK on success; SWMM_ERR_BADPARAM on non-positive cd.

◆ swmm_2d_set_vertex_tag()

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

SWMM_ENGINE_API int swmm_2d_set_vertex_z	(	SWMM_Engine	engine,
		int	idx,
		double	z )

Set vertex Z (ground elevation).

Updates vz[idx] and recomputes the dependent geometry for every triangle incident to this vertex: tri_cz (centroid Z = mean of vertex Zs) and edge_mz (per-edge midpoint Z) so the solver's bed-elevation references stay consistent on the next step. XY-derived fields (tri_area, tri_cx, tri_cy, edge_length, edge_nx, edge_ny, edge_mx, edge_my) are unaffected.

When called while the engine is RUNNING, the solver state (head, depth) is intentionally not rewritten — head remains the value the solver is integrating; the implied depth = head - bed therefore changes by the same amount as bed. This is the expected physical semantics ("raising the bed under water reduces water depth there").

Parameters

idx	Vertex index (0-based).
z	New ground elevation (project vertical units).

Here is the call graph for this function:

◆ swmm_2d_set_vertex_z_bulk()

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.

Equivalent to calling swmm_2d_set_vertex_z for each vertex in turn — the dependent geometry (tri_cz, edge_mz) ends up bitwise identical — but the scalar setter rescans all triangles on every call, so doing that per vertex is O(nVertices x nTriangles). This writes all Zs first and recomputes the dependent geometry in a single pass, i.e. O(nVertices + nTriangles). On a million-cell mesh that is the difference between minutes and milliseconds, which is why editors that rewrite a whole mesh should prefer it.

XY-derived fields (tri_area, tri_cx, tri_cy, edge_length, edge_nx, edge_ny, edge_mx, edge_my) are unaffected.

When called while the engine is RUNNING, the solver state (head, depth) is intentionally not rewritten — head remains the value the solver is integrating; the implied depth = head - bed therefore changes by the same amount as bed. This is the expected physical semantics ("raising the bed under water reduces water depth there").

Parameters

z	Array of `count` new ground elevations (project vertical units), indexed by vertex.
count	Must equal swmm_2d_vertex_count, else SWMM_ERR_BADPARAM.

Here is the call graph for this function:

◆ swmm_2d_triangle_count()

SWMM_ENGINE_API int swmm_2d_triangle_count	(	SWMM_Engine	engine,
		int *	count )

Get the number of mesh triangles.

◆ swmm_2d_triangle_coupling_count()

SWMM_ENGINE_API int swmm_2d_triangle_coupling_count	(	SWMM_Engine	engine,
		int *	count )

Get the number of triangle-to-node coupling points.

◆ swmm_2d_triangle_coupling_rows()

SWMM_ENGINE_API int swmm_2d_triangle_coupling_rows	(	SWMM_Engine	engine,
		int *	count )

Number of authored node→cell coupling rows.

Parameters

count Output row count (>= number of distinct coupled triangles).

◆ swmm_2d_triangle_get_area()

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

Get triangle area.

Parameters

idx	Triangle index.
area	Output area (m² or ft²).

◆ swmm_2d_triangle_get_centroid()

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

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.

Parameters

tri_idx	Triangle index.
node_idx	Output: SWMM node index, or -1 if uncoupled.

◆ swmm_2d_triangle_get_init_depth()

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

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

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

Get triangle Manning's roughness.

◆ swmm_2d_triangle_get_neighbours()

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

Parameters

n0,n1,n2 Adjacent triangle indices across edges opposite v0,v1,v2.

◆ swmm_2d_triangle_get_vertices()

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

Parameters

idx	Cell index (0-based). Returns SWMM_ERR_BADPARAM when the cell is a quadrilateral — use swmm_2d_cell_get_vertices.
v0,v1,v2	Output vertex indices.

◆ swmm_2d_vertex_count()

SWMM_ENGINE_API int swmm_2d_vertex_count	(	SWMM_Engine	engine,
		int *	count )

Get the number of mesh vertices.

◆ swmm_2d_vertex_coupling_count()

SWMM_ENGINE_API int swmm_2d_vertex_coupling_count	(	SWMM_Engine	engine,
		int *	count )

Get the number of vertex-to-node coupling points.

◆ swmm_2d_vertex_get_coupled_node()

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.

Parameters

vertex_idx	Vertex index.
node_idx	Output: SWMM node index, or -1 if uncoupled.

◆ swmm_2d_vertex_get_head()

SWMM_ENGINE_API int swmm_2d_vertex_get_head	(	SWMM_Engine	engine,
		int	idx,
		double *	head )

Get reconstructed head at a vertex.

◆ swmm_2d_vertex_get_heads_bulk()

SWMM_ENGINE_API int swmm_2d_vertex_get_heads_bulk	(	SWMM_Engine	engine,
		double *	heads )

Bulk get reconstructed heads at all vertices.

◆ swmm_2d_vertex_get_render_depths_bulk()

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.

The wet-masked, depth-weighted free-surface reconstruction eta_v - z_v: dry-cell bed elevations never contribute (unlike the vertex heads above, which are the solver field with dry-cell head = bed elevation). Negative over the dry side of partially wet cells (sub-cell shoreline intercept), 0 where no incident cell is wet. This is the field GUIs should interpolate for water-surface rendering and profiles.

◆ swmm_2d_vertex_get_xyz()

SWMM_ENGINE_API int swmm_2d_vertex_get_xyz	(	SWMM_Engine	engine,
		int	idx,
		double *	x,
		double *	y,
		double *	z )

Get vertex coordinates.

Parameters

idx	Vertex index (0-based).
x,y,z	Output coordinates.

◆ swmm_2d_vertex_get_xyz_bulk()

SWMM_ENGINE_API int swmm_2d_vertex_get_xyz_bulk	(	SWMM_Engine	engine,
		double *	x,
		double *	y,
		double *	z )

Bulk get vertex coordinates.

Parameters

x,y,z Output arrays (must be pre-allocated to vertex_count).

Topics

Files

Classes

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ SWMM_2DRunStats

Function Documentation

◆ swmm_2d_add_triangle_coupling()

◆ swmm_2d_boundary_edge_count()

◆ swmm_2d_cell_count()

◆ swmm_2d_cell_get_neighbours()

◆ swmm_2d_cell_get_vertices()

◆ swmm_2d_cell_vertex_count()

◆ swmm_2d_clear_triangle_couplings()

◆ swmm_2d_edge_get_geometry_bulk()

◆ swmm_2d_edge_stride()

◆ swmm_2d_force_clear_all()

◆ swmm_2d_force_coupling_flux()

◆ swmm_2d_force_evap()

◆ swmm_2d_force_evap_uniform()

◆ swmm_2d_force_rainfall()

◆ swmm_2d_force_rainfall_uniform()

◆ swmm_2d_get_continuity_error()

◆ swmm_2d_get_coupling_flux()

◆ swmm_2d_get_coupling_fluxes_bulk()

◆ swmm_2d_get_coupling_volume_bulk()

◆ swmm_2d_get_depth()

◆ swmm_2d_get_depths_bulk()

◆ swmm_2d_get_dry_depth()

◆ swmm_2d_get_edge_bc_cum_flux()

◆ swmm_2d_get_edge_bc_flow()

◆ swmm_2d_get_edge_bc_head()

◆ swmm_2d_get_edge_bc_slope()

◆ swmm_2d_get_edge_bc_tseries_name()

◆ swmm_2d_get_edge_bc_type()

◆ swmm_2d_get_edge_conveyance()

◆ swmm_2d_get_edge_conveyance_bulk()

◆ swmm_2d_get_edge_flux_bulk()

◆ swmm_2d_get_head()

◆ swmm_2d_get_heads_bulk()

◆ swmm_2d_get_mass_balance()

◆ swmm_2d_get_max_depth()

◆ swmm_2d_get_net_source()

◆ swmm_2d_get_rain_volume_bulk()

◆ swmm_2d_get_rainfall()

◆ swmm_2d_get_rainfall_bulk()

◆ swmm_2d_get_run_stats()

◆ swmm_2d_get_solver_last_step()

◆ swmm_2d_get_solver_steps()

◆ swmm_2d_get_stat_max_continuity_err()

◆ swmm_2d_get_stat_max_depths()

◆ swmm_2d_get_stat_max_velocities()

◆ swmm_2d_get_total_exchange_flow()

◆ swmm_2d_get_total_volume()

◆ swmm_2d_get_triangle_coupling_row()

◆ swmm_2d_get_triangle_tag()

◆ swmm_2d_get_vertex_coupling_area()

◆ swmm_2d_get_vertex_coupling_cd()

◆ swmm_2d_get_vertex_tag()

◆ swmm_2d_is_active()

◆ swmm_2d_prepare_for_edit()

◆ swmm_2d_quad_count()

◆ swmm_2d_reset_edge_conveyance()

◆ swmm_2d_set_dry_depth()

◆ swmm_2d_set_edge_bc_head()

◆ swmm_2d_set_edge_bc_slope()

◆ swmm_2d_set_edge_bc_tseries_name()

◆ swmm_2d_set_edge_bc_type()

◆ swmm_2d_set_edge_conveyance()

◆ swmm_2d_set_triangle_init_depth()

◆ swmm_2d_set_triangle_init_velocity()

◆ swmm_2d_set_triangle_mannings()

◆ swmm_2d_set_triangle_tag()

◆ swmm_2d_set_vertex_coupled_node()

◆ swmm_2d_set_vertex_coupling_area()

◆ swmm_2d_set_vertex_coupling_cd()

◆ swmm_2d_set_vertex_tag()

◆ swmm_2d_set_vertex_z()