OpenSWMM Engine  6.0.0-alpha.3
Data-oriented, plugin-extensible SWMM Engine (6.0.0-alpha.3)
Loading...
Searching...
No Matches
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 <openswmm/engine/openswmm_forcing.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_2D_MESH(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_prepare_for_edit (SWMM_Engine engine)
 Make the parsed 2D mesh editable without a full initialize().
 
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_set_triangle_mannings (SWMM_Engine engine, int idx, double n)
 Set triangle Manning's roughness coefficient.
 
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.
 
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.
 
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.
 
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.
 
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_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.
 
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).
 
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.
 
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).
 
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.
 
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_conveyance (SWMM_Engine engine, int tri, int edge, double *conveyance)
 Get the per-edge conveyance factor for one edge.
 
int swmm_2d_set_edge_conveyance (SWMM_Engine engine, int tri, int edge, double conveyance)
 Set the per-edge conveyance factor for one edge.
 
int swmm_2d_get_edge_conveyance_bulk (SWMM_Engine engine, double *conveyance)
 Bulk get conveyance factor at every edge of every triangle.
 
int swmm_2d_reset_edge_conveyance (SWMM_Engine engine)
 Reset every edge's conveyance factor to 1.0 (unrestricted).
 
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_get_stat_max_velocities (SWMM_Engine engine, double *max_velocities)
 Get per-triangle max velocity-magnitude statistics (cumulative, m/s).
 
int swmm_2d_get_stat_max_continuity_err (SWMM_Engine engine, double *max_errs)
 Get per-triangle max |continuity residual| statistics (cumulative, m3/s).
 
int swmm_2d_get_continuity_error (SWMM_Engine engine, double *err)
 Get the global 2D surface continuity error (fraction).
 
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.
 
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_evap (SWMM_Engine engine, int idx, double value, int mode, int persist)
 Force evaporation on a specific triangle.
 
int swmm_2d_force_evap_uniform (SWMM_Engine engine, double value, int mode, int persist)
 Force evaporation 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
@ SWMM_ERR_BADPARAM
Definition openswmm_engine.h:110

◆ CHECK_2D_MESH

#define CHECK_2D_MESH ( eng)
Value:
auto& router2d = eng->surfaceRouter2D(); \
if (router2d.mesh().n_vertices() <= 0) return SWMM_ERR_BADPARAM

◆ CHECK_TRI_IDX

#define CHECK_TRI_IDX ( idx,
router2d )
Value:
if ((idx) < 0 || (idx) >= router2d.mesh().n_triangles()) \
@ SWMM_ERR_BADINDEX
Definition openswmm_engine.h:109

◆ CHECK_VERT_IDX

#define CHECK_VERT_IDX ( idx,
router2d )
Value:
if ((idx) < 0 || (idx) >= router2d.mesh().n_vertices()) \

◆ GET_ENGINE

#define GET_ENGINE ( engine)
Value:
auto* eng = reinterpret_cast<openswmm::SWMMEngine*>(engine); \
if (!eng) return SWMM_ERR_BADHANDLE
@ SWMM_ERR_BADHANDLE
Definition openswmm_engine.h:108

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.