Api2D.cpp File Reference

C API implementation for the 2D surface routing module. More...

#include <openswmm/engine/openswmm_engine.h>
#include <openswmm/engine/openswmm_2d.h>
#include "../../core/SWMMEngine.hpp"
#include "../mesh/MeshBuilder.hpp"
#include <cstring>
#include <cstdint>
#include <algorithm>

Include dependency graph for Api2D.cpp:

Macros
#define	GET_ENGINE(engine)
#define	CHECK_2D_ACTIVE(eng)
#define	CHECK_TRI_IDX(idx, router2d)
#define	CHECK_VERT_IDX(idx, router2d)

Functions
int	swmm_2d_is_active (SWMM_Engine engine, int *active)
	Check whether the 2D module is active for this simulation.
int	swmm_2d_vertex_count (SWMM_Engine engine, int *count)
	Get the number of mesh vertices.
int	swmm_2d_triangle_count (SWMM_Engine engine, int *count)
	Get the number of mesh triangles.
int	swmm_2d_vertex_get_xyz (SWMM_Engine engine, int idx, double *x, double *y, double *z)
	Get vertex coordinates.
int	swmm_2d_vertex_get_xyz_bulk (SWMM_Engine engine, double *x, double *y, double *z)
	Bulk get vertex coordinates.
int	swmm_2d_set_vertex_z (SWMM_Engine engine, int idx, double z)
	Set vertex Z (ground elevation).
int	swmm_2d_triangle_get_vertices (SWMM_Engine engine, int idx, int *v0, int *v1, int *v2)
	Get triangle connectivity (3 vertex indices).
int	swmm_2d_triangle_get_area (SWMM_Engine engine, int idx, double *area)
	Get triangle area.
int	swmm_2d_triangle_get_centroid (SWMM_Engine engine, int idx, double *cx, double *cy, double *cz)
	Get triangle centroid coordinates.
int	swmm_2d_triangle_get_mannings (SWMM_Engine engine, int idx, double *n)
	Get triangle Manning's roughness.
int	swmm_2d_triangle_get_neighbours (SWMM_Engine engine, int idx, int *n0, int *n1, int *n2)
	Get triangle neighbour indices (-1 = boundary edge).
int	swmm_2d_vertex_coupling_count (SWMM_Engine engine, int *count)
	Get the number of vertex-to-node coupling points.
int	swmm_2d_triangle_coupling_count (SWMM_Engine engine, int *count)
	Get the number of triangle-to-node coupling points.
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.
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.
int	swmm_2d_get_depth (SWMM_Engine engine, int idx, double *depth)
	Get water depth at a triangle.
int	swmm_2d_get_head (SWMM_Engine engine, int idx, double *head)
	Get total head at a triangle (z + depth).
int	swmm_2d_get_coupling_flux (SWMM_Engine engine, int idx, double *flux)
	Get coupling exchange flux at a triangle (m/s, + = into 2D).
int	swmm_2d_get_rainfall (SWMM_Engine engine, int idx, double *rainfall)
	Get rainfall intensity at a triangle (m/s).
int	swmm_2d_get_net_source (SWMM_Engine engine, int idx, double *net_source)
	Get net source/sink rate at a triangle (m/s).
int	swmm_2d_get_depths_bulk (SWMM_Engine engine, double *depths)
	Bulk get depths for all triangles.
int	swmm_2d_get_heads_bulk (SWMM_Engine engine, double *heads)
	Bulk get heads for all triangles.
int	swmm_2d_get_coupling_fluxes_bulk (SWMM_Engine engine, double *fluxes)
	Bulk get coupling fluxes for all triangles.
int	swmm_2d_get_edge_flux_bulk (SWMM_Engine engine, double *flux)
	Bulk get normal edge flux at every edge of every triangle.
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].
int	swmm_2d_vertex_get_head (SWMM_Engine engine, int idx, double *head)
	Get reconstructed head at a vertex.
int	swmm_2d_vertex_get_heads_bulk (SWMM_Engine engine, double *heads)
	Bulk get reconstructed heads at all vertices.
int	swmm_2d_get_max_depth (SWMM_Engine engine, double *max_depth)
	Get the maximum depth across all triangles.
int	swmm_2d_get_total_volume (SWMM_Engine engine, double *volume)
	Get total 2D surface volume (sum of depth * area).
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.
int	swmm_2d_get_cvode_steps (SWMM_Engine engine, long *steps)
	Get number of CVODE internal steps taken in the last advance.
int	swmm_2d_get_cvode_last_step (SWMM_Engine engine, double *h_last)
	Get CVODE last internal step size.
int	swmm_2d_get_stat_max_depths (SWMM_Engine engine, double *max_depths)
	Get per-triangle max depth statistics (cumulative).
int	swmm_2d_force_rainfall (SWMM_Engine engine, int idx, double value, int mode, int persist)
	Force rainfall on a specific triangle.
int	swmm_2d_force_rainfall_uniform (SWMM_Engine engine, double value, int mode, int persist)
	Force rainfall on all triangles (uniform).
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).
int	swmm_2d_force_clear_all (SWMM_Engine engine)
	Clear all 2D forcings.
int	swmm_2d_get_dry_depth (SWMM_Engine engine, double *dry_depth)
	Get the dry depth threshold (m).
int	swmm_2d_set_dry_depth (SWMM_Engine engine, double dry_depth)
	Set the dry depth threshold (m).
int	swmm_2d_get_rel_tolerance (SWMM_Engine engine, double *rtol)
	Get CVODE relative tolerance.
int	swmm_2d_set_rel_tolerance (SWMM_Engine engine, double rtol)
	Set CVODE relative tolerance.
int	swmm_2d_get_abs_tolerance (SWMM_Engine engine, double *atol)
	Get CVODE absolute tolerance.
int	swmm_2d_set_abs_tolerance (SWMM_Engine engine, double atol)
	Set CVODE absolute tolerance.
int	swmm_2d_boundary_edge_count (SWMM_Engine engine, int *count)
	Get the number of boundary edges (edges with no neighbour).
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.
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.
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.
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.
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.
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.
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).
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.
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.
int	swmm_2d_set_edge_bc_flow (SWMM_Engine engine, int tri_idx, int edge, double flow)
	Set prescribed flow per metre of edge (m³/s/m). V-E4.
int	swmm_2d_set_edge_bc_flow_tseries_name (SWMM_Engine engine, int tri_idx, int edge, const char *name)
	Set the timeseries NAME to drive a SPECIFIED_FLOW edge. V-E4 — same resolution contract as swmm_2d_set_edge_bc_tseries_name.
int	swmm_2d_set_edge_bc_rating_curve_name (SWMM_Engine engine, int tri_idx, int edge, const char *name)
	Set the curve NAME to drive a RATING_CURVE edge.

Detailed Description

C API implementation for the 2D surface routing module.

Implements all functions declared in openswmm_2d.h. Each function extracts the SWMMEngine from the opaque handle, accesses the SurfaceRouter2D, and delegates the operation.

Macro Definition Documentation

CHECK_2D_ACTIVE

#define CHECK_2D_ACTIVE

(

eng

)

Value:

    auto& router2d = eng->surfaceRouter2D(); \
    if (!router2d.isActive()) return SWMM_ERR_BADPARAM

CHECK_TRI_IDX

#define CHECK_TRI_IDX	(		idx,
			router2d
	)

Value:

    if ((idx) < 0 || (idx) >= router2d.mesh().n_triangles()) \
        return SWMM_ERR_BADINDEX

CHECK_VERT_IDX

#define CHECK_VERT_IDX	(		idx,
			router2d
	)

Value:

    if ((idx) < 0 || (idx) >= router2d.mesh().n_vertices()) \
        return SWMM_ERR_BADINDEX

GET_ENGINE

#define GET_ENGINE

(

engine

)

Value:

    auto* eng = reinterpret_cast<openswmm::SWMMEngine*>(engine); \
    if (!eng) return SWMM_ERR_BADHANDLE

Function Documentation

swmm_2d_set_edge_bc_flow()

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

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

swmm_2d_set_edge_bc_flow_tseries_name()

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

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

swmm_2d_set_edge_bc_rating_curve_name()

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

Set the curve NAME to drive a RATING_CURVE edge.

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