2D Surface Routing API

Collaboration diagram for 2D Surface Routing 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	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	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	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	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	ArkodeSurfaceSolver.cpp
	Implementation of the ARKODE/ARKStep IMEX wrapper for 2D surface routing.
file	ArkodeSurfaceSolver.hpp
	SUNDIALS ARKODE/ARKStep IMEX integrator for the 2D surface routing ODE.
file	CvodeSurfaceSolver.cpp
	Implementation of CVODE wrapper for 2D surface routing.
file	CvodeSurfaceSolver.hpp
	CVODE (SUNDIALS) wrapper for the 2D surface routing ODE system.
file	HypreAmgPreconditioner.cpp
	hypre BoomerAMG preconditioner implementation (built only when OPENSWMM_WITH_HYPRE is ON).
file	HypreAmgPreconditioner.hpp
	hypre BoomerAMG algebraic-multigrid preconditioner for the 2D surface CVODE solver (PRECONDITIONER=AMG).
file	InertialEdges.cpp
	Implementation of the unique interior-edge builder.
file	InertialEdges.hpp
	Unique interior-edge structure for the local-inertial momentum DOFs.
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	SurfaceJacobian.cpp
	Implementation of the CSR Newton-matrix assembly.
file	SurfaceJacobian.hpp
	CSR assembly of the approximate Newton matrix M = I − γ·J for the 2D diffusive-wave surface operator, for use as a preconditioner matrix (hypre BoomerAMG).
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	SurfaceRouter2D.cpp
	Implementation of the 2D surface routing orchestrator.
file	SurfaceRouter2D.hpp
	Top-level orchestrator for the optional 2D surface routing module.

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_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_set_triangle_mannings (SWMM_Engine engine, int idx, double n)
	Set triangle Manning's roughness coefficient.
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_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, m²; 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, m²). Persisted by the .inp writer.
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_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_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_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_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_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 MIT License

Function Documentation

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

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

SWMM_ENGINE_API int swmm_2d_get_abs_tolerance	(	SWMM_Engine	engine,
		double *	atol )

Get CVODE absolute tolerance.

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

SWMM_ENGINE_API int swmm_2d_get_cvode_last_step	(	SWMM_Engine	engine,
		double *	h_last )

Get CVODE last internal step size.

swmm_2d_get_cvode_steps()

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

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 (m³/s/m) for a SPECIFIED_FLOW edge. V-E4.

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.

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.

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: SWMM_2D_BC_WALL, SWMM_2D_BC_NORMAL_FLOW, or SWMM_2D_BC_SPECIFIED_STAGE.

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.

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

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.

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_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_rel_tolerance()

SWMM_ENGINE_API int swmm_2d_get_rel_tolerance	(	SWMM_Engine	engine,
		double *	rtol )

Get CVODE relative tolerance.

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_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, m²; default 1.0).

Parameters

vertex_idx	Vertex index in [0, vertex_count).
area	Output exchange area (m²).

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_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_abs_tolerance()

SWMM_ENGINE_API int swmm_2d_set_abs_tolerance	(	SWMM_Engine	engine,
		double	atol )

Set CVODE absolute tolerance.

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.

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.

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

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.

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.

swmm_2d_set_rel_tolerance()

SWMM_ENGINE_API int swmm_2d_set_rel_tolerance	(	SWMM_Engine	engine,
		double	rtol )

Set CVODE relative tolerance.

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, m²). Persisted by the .inp writer.

Parameters

vertex_idx	Vertex index in [0, vertex_count).
area	Exchange area in m²; 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 CVODE 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_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_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_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	Triangle index (0-based).
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_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).