openswmm_2d.h File Reference

Optional 2D surface routing module — C API. More...

#include "openswmm_callbacks.h"

Include dependency graph for openswmm_2d.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

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

Macros
#define	SWMM_ENGINE_API   __attribute__((visibility("default")))
#define	SWMM_2D_BC_WALL   0
#define	SWMM_2D_BC_NORMAL_FLOW   1
#define	SWMM_2D_BC_SPECIFIED_STAGE   2
#define	SWMM_2D_BC_SPECIFIED_FLOW   3
#define	SWMM_2D_BC_RATING_CURVE   4
#define	SWMM_2D_QUAL_SCOPE_GLOBAL   0
#define	SWMM_2D_QUAL_SCOPE_TAG   1
#define	SWMM_2D_QUAL_SCOPE_CELL   2

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).
typedef enum SWMM_NodeCoupling2DType	SWMM_NodeCoupling2DType

Enumerations
enum	SWMM_NodeCoupling2DType {   SWMM_2D_COUPLING_NONE = 0 ,   SWMM_2D_COUPLING_MANHOLE = 1 ,   SWMM_2D_COUPLING_GRATE = 2 ,   SWMM_2D_COUPLING_CURB = 3 ,   SWMM_2D_COUPLING_OPEN = 4 ,   SWMM_2D_COUPLING_OUTFALL = 5 }

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_set_auto_backend_cpu (SWMM_Engine engine, int enabled)
	Resolve an unoverridden AUTO backend to the built-in CPU marcher for this session. Valid in BUILDING or OPENED state, including models without a mesh. enabled must be 0 or 1. Does not edit BACKEND, serialize a model option or change checkpoint identity. Explicit BACKEND and OPENSWMM_2D_BACKEND requests retain precedence. Reapply after opening a new model.
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_geometry_scale_to_si (SWMM_Engine engine, double *scale)
	Multiplier converting the current mesh XYZ coordinates and lengths to metres (square it for areas). Available on a parsed mesh before initialize. Accounts for project units, external mesh SI declarations and initialization's in-place SI conversion. Does not initialize, normalize or change the mesh.
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 [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_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 (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_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 [cell*edge_stride + 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, m).
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_rainfall_weights (SWMM_Engine engine, int idx, int *method, int *gage_indices, double *weights, int capacity, int *count)
	Inspect how RAINFALL_MODE maps the gages onto one triangle.
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 (m).
SWMM_ENGINE_API int	swmm_2d_get_heads_bulk (SWMM_Engine engine, double *heads)
	Bulk get heads for all triangles (m).
SWMM_ENGINE_API int	swmm_2d_get_velocities_bulk (SWMM_Engine engine, double *vx, double *vy)
	Bulk cell velocity in physical Cartesian SI m/s, matching Mesh2_face_vx/vy.
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 over the solver's current routing window. Output pre-allocated to triangle_count.
SWMM_ENGINE_API int	swmm_2d_get_report_rainfall_bulk (SWMM_Engine engine, double report_date, double *rainfall)
	Bulk rainfall at a report instant, in SI m/s.
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_species_count (SWMM_Engine engine, int *count)
	How many species rows the surface transports (0 when it carries none). Row order: pollutants, MSX species, __WATER_AGE__, __TEMPERATURE__ — the same order as swmm_gw2d_species_name.
SWMM_ENGINE_API int	swmm_2d_species_name (SWMM_Engine engine, int species, char *buf, int buflen)
	One surface species row's name.
SWMM_ENGINE_API int	swmm_2d_get_cell_conc (SWMM_Engine engine, int species, double *out, int len, int *written)
	Per-cell concentration of one surface species: pollutant and MSX rows in their declared units, __TEMPERATURE__ in degC and __WATER_AGE__ in seconds. A cell at or below the dry depth reports 0 (it keeps its mass). Writes at most len values and sets written.
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, m).
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_concentrations (SWMM_Engine engine, int cell, int edge, const double *values, int species_count)
	Runtime inflow concentrations in the species getter's units/order. Outflow uses donor concentrations. clear_edge_bc restores authored hydraulics/quality.
SWMM_ENGINE_API int	swmm_2d_clear_edge_bc (SWMM_Engine engine, int cell, int edge)
	Restore the authored boundary hydraulics and quality for one edge.
SWMM_ENGINE_API int	swmm_2d_initial_quality_count (SWMM_Engine engine, int *count)
	Read the authored initial water-quality row count.
SWMM_ENGINE_API int	swmm_2d_get_initial_quality (SWMM_Engine engine, int index, int *scope, char *tag, int tag_len, int *cell, char *species, int species_len, double *conc)
	Read one [2D_INITIAL_QUALITY] row. Any out-pointer may be NULL.
SWMM_ENGINE_API int	swmm_2d_set_initial_quality (SWMM_Engine engine, int scope, const char *tag, int cell, const char *species, double conc)
	Add or replace a row keyed by (scope, tag | cell, species).
SWMM_ENGINE_API int	swmm_2d_remove_initial_quality (SWMM_Engine engine, int index)
	Erase one authored initial water-quality row.
SWMM_ENGINE_API int	swmm_2d_initial_bed_quality_count (SWMM_Engine engine, int *count)
	Read the authored finite-bed initial-quality row count.
SWMM_ENGINE_API int	swmm_2d_get_initial_bed_quality (SWMM_Engine engine, int index, int *scope, char *tag, int tag_len, int *cell, char *species, int species_len, double *conc)
	Read one authored finite-bed initial-quality row.
SWMM_ENGINE_API int	swmm_2d_set_initial_bed_quality (SWMM_Engine engine, int scope, const char *tag, int cell, const char *species, double conc)
	Upsert a finite-bed initial-quality row by scope and species.
SWMM_ENGINE_API int	swmm_2d_remove_initial_bed_quality (SWMM_Engine engine, int index)
	Erase one authored finite-bed initial-quality row.
SWMM_ENGINE_API int	swmm_2d_boundary_quality_count (SWMM_Engine engine, int *count)
	Read the authored boundary-quality row count.
SWMM_ENGINE_API int	swmm_2d_get_boundary_quality (SWMM_Engine engine, int index, int *cell, int *edge, char *species, int species_len, double *conc)
	Read one [2D_BOUNDARY_QUALITY] row (inflow concentration through a boundary edge). Any out-pointer may be NULL.
SWMM_ENGINE_API int	swmm_2d_set_boundary_quality (SWMM_Engine engine, int cell, int edge, const char *species, double conc)
	Add or replace the row keyed by (cell, edge, species).
SWMM_ENGINE_API int	swmm_2d_remove_boundary_quality (SWMM_Engine engine, int index)
	Erase one authored boundary-quality row.
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_set_edge_bc_group (SWMM_Engine engine, int tri_idx, int edge, const char *group)
SWMM_ENGINE_API int	swmm_2d_get_edge_wall_drag (SWMM_Engine engine, int tri_idx, int edge, double *cw)
SWMM_ENGINE_API int	swmm_2d_set_edge_wall_drag (SWMM_Engine engine, int tri_idx, int edge, double cw)
SWMM_ENGINE_API int	swmm_2d_get_edge_bc_slope (SWMM_Engine engine, int tri_idx, int edge, double *slope)
	Get normal flow boundary slope for an edge.
SWMM_ENGINE_API int	swmm_2d_set_edge_bc_slope (SWMM_Engine engine, int tri_idx, int edge, double slope)
	Set normal flow boundary slope for an edge.
SWMM_ENGINE_API int	swmm_2d_set_edge_bc_tseries_name (SWMM_Engine engine, int tri_idx, int edge, const char *name)
	Set the timeseries NAME to drive a SPECIFIED_STAGE edge.
SWMM_ENGINE_API int	swmm_2d_get_edge_bc_tseries_name (SWMM_Engine engine, int tri_idx, int edge, char *buf, int buflen)
	Get the timeseries NAME driving a SPECIFIED_STAGE edge.
SWMM_ENGINE_API int	swmm_2d_get_edge_bc_flow (SWMM_Engine engine, int tri_idx, int edge, double *flow)
	Get prescribed flow per metre of edge for a SPECIFIED_FLOW edge. V-E4.
SWMM_ENGINE_API int	swmm_2d_set_edge_bc_flow (SWMM_Engine engine, int tri_idx, int edge, double flow)
	Set prescribed flow per metre of edge (same units convention as the getter: display flow units/m before initialize, m³/s/m after). V-E4.
SWMM_ENGINE_API int	swmm_2d_set_edge_bc_flow_tseries_name (SWMM_Engine engine, int tri_idx, int edge, const char *name)
	Set the timeseries NAME to drive a SPECIFIED_FLOW edge. V-E4 — same resolution contract as swmm_2d_set_edge_bc_tseries_name.
SWMM_ENGINE_API int	swmm_2d_get_edge_bc_flow_tseries_name (SWMM_Engine engine, int tri_idx, int edge, char *buf, int buflen)
	Get the timeseries NAME driving a SPECIFIED_FLOW edge. SVBC A8 — same contract as swmm_2d_get_edge_bc_tseries_name.
SWMM_ENGINE_API int	swmm_2d_set_edge_bc_rating_curve_name (SWMM_Engine engine, int tri_idx, int edge, const char *name)
	Set the curve NAME to drive a RATING_CURVE edge.
SWMM_ENGINE_API int	swmm_2d_get_edge_bc_rating_curve_name (SWMM_Engine engine, int tri_idx, int edge, char *buf, int buflen)
	Get the curve NAME driving a RATING_CURVE edge. SVBC A8 — same contract as swmm_2d_get_edge_bc_tseries_name.
SWMM_ENGINE_API int	swmm_2d_get_edge_bc_cum_flux (SWMM_Engine engine, int tri_idx, int edge, double *cum_flux)
	Get cumulative boundary flux at an edge (m³, + = outflow).
SWMM_ENGINE_API int	swmm_2d_output_variable_count (void)
	Number of selectable dataset groups.
SWMM_ENGINE_API const char *	swmm_2d_output_variable_name (int i)
	Token of group i (0-based, bit i), or "" when out of range.
SWMM_ENGINE_API unsigned	swmm_2d_output_variable_mask (const char *text)
	Bitmask for a preset name ("DEFAULT", "MINIMAL", "ALL") or a token list; returns 0 for an unparseable string.
SWMM_ENGINE_API const char *	swmm_2d_output_variable_text (unsigned mask)
	Preset name or token list for mask (static buffer, valid until the next call).
SWMM_ENGINE_API int	swmm_node_get_2d_coupling_type (SWMM_Engine engine, int node_idx, int *type, int *authored)
	Effective coupling type of a node.
SWMM_ENGINE_API int	swmm_node_get_2d_coupling_default_type (SWMM_Engine engine, int node_idx, int *type)
	Class default coupling type of a node (what it has without a row).
SWMM_ENGINE_API int	swmm_node_set_2d_coupling_type (SWMM_Engine engine, int node_idx, int type)
	Author a node's coupling type. Parameters that do not apply to the new type are dropped.
SWMM_ENGINE_API int	swmm_node_reset_2d_coupling (SWMM_Engine engine, int node_idx)
	Remove a node's [2D_NODE_COUPLING] row (back to the class default).
SWMM_ENGINE_API int	swmm_node_get_2d_coupling_param (SWMM_Engine engine, int node_idx, const char *key, char *value, int value_len)
	Read an authored coupling parameter as its section token, e.g. key "D" → "1.2", key "CREST" → "MESH_BED". Empty when not authored. Keys: D, PERIMETER, AREA, CHAMBER_AREA, LID_OPEN_FRACTION, CREST, COEFFS, CW, CSW, COI, COO, LAW, SPREAD, TAILWATER_RELAX. Lengths and areas are in project units, TAILWATER_RELAX in seconds.
SWMM_ENGINE_API int	swmm_node_set_2d_coupling_param (SWMM_Engine engine, int node_idx, const char *key, const char *value)
	Author a coupling parameter from its section token; NULL or "" clears it. A node without a row gets one at its class default type.

Detailed Description

Optional 2D surface routing module — C API.

Provides query and control of the optional 2D surface routing module coupled to the 1D SWMM pipe network. The 2D module is active when [2D_VERTICES] and [2D_TRIANGLES] sections are present in the input file and the engine was compiled with OPENSWMM_BUILD_2D.

All functions require the engine to be in SWMM_STATE_RUNNING unless otherwise noted. Solver-state functions return SWMM_ERR_LIFECYCLE when the model has a 2D mesh but swmm_engine_initialize() has not run yet, and SWMM_ERR_BADPARAM when the model has no active 2D surface (no mesh, or IGNORE_2D).

Units: swmm_engine_initialize() scales the mesh to SI, so solver state (depths, heads, coordinates, velocities, volumes) is in metres whatever the project's FLOW_UNITS. Mesh values read before initialize are in the mesh's authored units.

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

Apache-2.0

Macro Definition Documentation

SWMM_2D_BC_NORMAL_FLOW

#define SWMM_2D_BC_NORMAL_FLOW   1

SWMM_2D_BC_RATING_CURVE

#define SWMM_2D_BC_RATING_CURVE   4

V-E5.

SWMM_2D_BC_SPECIFIED_FLOW

#define SWMM_2D_BC_SPECIFIED_FLOW   3

V-E4.

SWMM_2D_BC_SPECIFIED_STAGE

#define SWMM_2D_BC_SPECIFIED_STAGE   2

SWMM_2D_BC_WALL

#define SWMM_2D_BC_WALL   0

Boundary condition type constants.

WALL / NORMAL_FLOW / SPECIFIED_STAGE were the original three; the SPECIFIED_FLOW (3) and RATING_CURVE (4) values were added per GUI plan §V V-E4 / V-E5. All five types are enforced at flux time by the explicit marcher (SurfaceFluxCalculator::boundaryEdgeFlux); timeseries and rating-curve driving values are re-resolved every step. Note a NORMAL_FLOW edge with zero bed slope produces zero flux (behaves as a Wall).

SWMM_2D_QUAL_SCOPE_CELL

#define SWMM_2D_QUAL_SCOPE_CELL   2

one cell

SWMM_2D_QUAL_SCOPE_GLOBAL

#define SWMM_2D_QUAL_SCOPE_GLOBAL   0

the * row

SWMM_2D_QUAL_SCOPE_TAG

#define SWMM_2D_QUAL_SCOPE_TAG   1

every cell carrying a tag

SWMM_ENGINE_API

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

Typedef Documentation

SWMM_NodeCoupling2DType

typedef enum SWMM_NodeCoupling2DType SWMM_NodeCoupling2DType

Coupling structure types.

Enumeration Type Documentation

SWMM_NodeCoupling2DType

enum SWMM_NodeCoupling2DType

Coupling structure types.

Enumerator
SWMM_2D_COUPLING_NONE	Not coupleable.
SWMM_2D_COUPLING_MANHOLE
SWMM_2D_COUPLING_GRATE
SWMM_2D_COUPLING_CURB
SWMM_2D_COUPLING_OPEN	Open-top storage under the mesh.
SWMM_2D_COUPLING_OUTFALL	Tailwater + discharge delivery.

Function Documentation

swmm_2d_boundary_quality_count()

SWMM_ENGINE_API int swmm_2d_boundary_quality_count	(	SWMM_Engine	engine,
		int *	count )

Read the authored boundary-quality row count.

Parameters

[out]	count	Required destination for the current count.
[in]	engine	Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits.

Returns

SWMM_OK on success; SWMM_ERR_BADHANDLE for a null engine; SWMM_ERR_BADINDEX for an invalid integer index; SWMM_ERR_BADPARAM for invalid required storage or values. Lifecycle restrictions and additional errors are described above.

swmm_2d_clear_edge_bc()

SWMM_ENGINE_API int swmm_2d_clear_edge_bc	(	SWMM_Engine	engine,
		int	cell,
		int	edge )

Restore the authored boundary hydraulics and quality for one edge.

Parameters

[in]	engine	Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits.
[in]	cell	Zero-based cell index in [0, cell_count); includes triangles and quadrilaterals.
[in]	edge	Zero-based local edge in [0, cell_vertex_count); exterior edge required for boundary edits.

Note

Requires an active surface router. A parsed mesh before initialization returns SWMM_ERR_LIFECYCLE; other inactive/no-mesh cases return SWMM_ERR_BADPARAM.

Boundary storage must be prepared. Edits target exterior unowned edges in OPENED/BUILDING/INITIALIZED/RUNNING. Active edits additionally require an allowed between-step update and the CPU runtime; they synchronize pending work and save the authored prescription for later restoration.

Returns

SWMM_OK on success; SWMM_ERR_BADHANDLE for a null engine; SWMM_ERR_BADINDEX for an invalid integer index; SWMM_ERR_BADPARAM for invalid required storage or values. Lifecycle restrictions and additional errors are described above.

Here is the call graph for this function:

swmm_2d_geometry_scale_to_si()

SWMM_ENGINE_API int swmm_2d_geometry_scale_to_si	(	SWMM_Engine	engine,
		double *	scale )

Multiplier converting the current mesh XYZ coordinates and lengths to metres (square it for areas). Available on a parsed mesh before initialize. Accounts for project units, external mesh SI declarations and initialization's in-place SI conversion. Does not initialize, normalize or change the mesh.

Parameters

[out]	scale	Required result slot, 1.0 or 0.3048; square for area conversion.
[in]	engine	Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits.

Note

Requires a parsed mesh; no initialized hydraulic state is needed.

Returns

SWMM_OK on success; SWMM_ERR_BADHANDLE for a null engine; SWMM_ERR_BADINDEX for an invalid integer index; SWMM_ERR_BADPARAM for invalid required storage or values. Lifecycle restrictions and additional errors are described above.

Here is the call graph for this function:

swmm_2d_get_boundary_quality()

SWMM_ENGINE_API int swmm_2d_get_boundary_quality	(	SWMM_Engine	engine,
		int	index,
		int *	cell,
		int *	edge,
		char *	species,
		int	species_len,
		double *	conc )

Read one [2D_BOUNDARY_QUALITY] row (inflow concentration through a boundary edge). Any out-pointer may be NULL.

Parameters

[out]	cell	Optional zero-based boundary-cell destination.
[out]	edge	Optional zero-based local-edge destination.
[out]	species	Optional species-name destination, safely truncated when capacity is positive.
[in]	species_len	Species-name byte capacity; nonpositive skips the string.
[out]	conc	Optional native-species concentration destination.
[in]	engine	Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits.
[in]	index	Zero-based authored row index; removing a row shifts later indices down.

Returns

SWMM_OK on success; SWMM_ERR_BADHANDLE for a null engine; SWMM_ERR_BADINDEX for an invalid integer index; SWMM_ERR_BADPARAM for invalid required storage or values. Lifecycle restrictions and additional errors are described above.

swmm_2d_get_edge_bc_flow_tseries_name()

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

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

Parameters

[out]	buf	Required writable table-name destination, safely truncated with NUL.
[in]	buflen	Positive byte capacity including the terminator.
[in]	engine	Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits.
[in]	tri_idx	Zero-based cell index in [0, cell_count); includes triangles and quadrilaterals.
[in]	edge	Zero-based local edge in [0, cell_vertex_count); exterior edge required for boundary edits.

Note

Requires a parsed mesh; no initialized hydraulic state is needed.

Returns

SWMM_OK on success; SWMM_ERR_BADHANDLE for a null engine; SWMM_ERR_BADINDEX for an invalid integer index; SWMM_ERR_BADPARAM for invalid required storage or values. Lifecycle restrictions and additional errors are described above.

Here is the call graph for this function:

swmm_2d_get_edge_bc_rating_curve_name()

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

Get the curve NAME driving a RATING_CURVE edge. SVBC A8 — same contract as swmm_2d_get_edge_bc_tseries_name.

Parameters

[out]	buf	Required writable table-name destination, safely truncated with NUL.
[in]	buflen	Positive byte capacity including the terminator.
[in]	engine	Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits.
[in]	tri_idx	Zero-based cell index in [0, cell_count); includes triangles and quadrilaterals.
[in]	edge	Zero-based local edge in [0, cell_vertex_count); exterior edge required for boundary edits.

Note

Requires a parsed mesh; no initialized hydraulic state is needed.

Returns

SWMM_OK on success; SWMM_ERR_BADHANDLE for a null engine; SWMM_ERR_BADINDEX for an invalid integer index; SWMM_ERR_BADPARAM for invalid required storage or values. Lifecycle restrictions and additional errors are described above.

Here is the call graph for this function:

swmm_2d_get_edge_wall_drag()

SWMM_ENGINE_API int swmm_2d_get_edge_wall_drag	(	SWMM_Engine	engine,
		int	tri_idx,
		int	edge,
		double *	cw )

Tangential WALL traction tau/rho=-Cw|ut|ut. Finite Cw>=0, zero free-slip. Getter uses a valid prepared mesh slot. Setter is authoring-only (OPENED/BUILDING); positive values require an exterior WALL edge. CPU FULL_SWE, LTS_TIERS 1, uncoupled hydraulics required when running. No density or 1/2 in Cw convention.

Here is the call graph for this function:

swmm_2d_get_initial_bed_quality()

SWMM_ENGINE_API int swmm_2d_get_initial_bed_quality	(	SWMM_Engine	engine,
		int	index,
		int *	scope,
		char *	tag,
		int	tag_len,
		int *	cell,
		char *	species,
		int	species_len,
		double *	conc )

Read one authored finite-bed initial-quality row.

Parameters

[out]	scope	Optional SWMM_2D_QUAL_SCOPE_* destination.
[out]	tag	Optional tag destination; positive capacity safely truncates with NUL.
[in]	tag_len	Tag capacity in bytes; nonpositive skips copying.
[out]	cell	Optional zero-based cell index; -1 for a non-CELL row.
[out]	species	Optional species-name destination, safely truncated when capacity is positive.
[in]	species_len	Species buffer byte capacity; nonpositive skips copying.
[out]	conc	Optional authored concentration in native species units.
[in]	engine	Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits.
[in]	index	Zero-based authored row index; removing a row shifts later indices down.

Returns

SWMM_OK on success; SWMM_ERR_BADHANDLE for a null engine; SWMM_ERR_BADINDEX for an invalid integer index; SWMM_ERR_BADPARAM for invalid required storage or values. Lifecycle restrictions and additional errors are described above.

swmm_2d_get_initial_quality()

SWMM_ENGINE_API int swmm_2d_get_initial_quality	(	SWMM_Engine	engine,
		int	index,
		int *	scope,
		char *	tag,
		int	tag_len,
		int *	cell,
		char *	species,
		int	species_len,
		double *	conc )

Read one [2D_INITIAL_QUALITY] row. Any out-pointer may be NULL.

Parameters

[out]	scope	Optional SWMM_2D_QUAL_SCOPE_* destination.
[out]	tag	Optional tag destination; positive capacity safely truncates with NUL.
[in]	tag_len	Tag capacity in bytes; nonpositive skips copying.
[out]	cell	Optional zero-based cell index; -1 for a non-CELL row.
[out]	species	Optional species-name destination, safely truncated when capacity is positive.
[in]	species_len	Species buffer byte capacity; nonpositive skips copying.
[out]	conc	Optional authored concentration in native species units.
[in]	engine	Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits.
[in]	index	Zero-based authored row index; removing a row shifts later indices down.

Returns

SWMM_OK on success; SWMM_ERR_BADHANDLE for a null engine; SWMM_ERR_BADINDEX for an invalid integer index; SWMM_ERR_BADPARAM for invalid required storage or values. Lifecycle restrictions and additional errors are described above.

swmm_2d_get_velocities_bulk()

SWMM_ENGINE_API int swmm_2d_get_velocities_bulk	(	SWMM_Engine	engine,
		double *	vx,
		double *	vy )

Bulk cell velocity in physical Cartesian SI m/s, matching Mesh2_face_vx/vy.

FULL_SWE uses accepted conserved cell momentum; other closures use the engine's diagnostic reconstruction. Refreshes derived output fields when stale, without advancing hydraulics. Dry cells have zero velocity. Non-FULL_SWE velocities use wetted-edge normal velocities. Paired NaNs mean a wet cell has no determinate velocity; dry cells return zero. Callers must not substitute zero or a mean-depth reconstruction for NaNs.

Parameters

[in]	engine	Borrowed live engine handle. Serialize with stepping/edits.
[out]	vx	Required distinct caller-owned cell_count-double X array.
[out]	vy	Required distinct caller-owned cell_count-double Y array. No capacity is passed or checked.

Returns

SWMM_OK on success; SWMM_ERR_BADHANDLE for a null handle; SWMM_ERR_BADPARAM for null arrays or inactive/no-mesh state; SWMM_ERR_LIFECYCLE for a parsed mesh before initialization.

swmm_2d_initial_bed_quality_count()

SWMM_ENGINE_API int swmm_2d_initial_bed_quality_count	(	SWMM_Engine	engine,
		int *	count )

Read the authored finite-bed initial-quality row count.

Parameters

[out]	count	Required destination for the current count.
[in]	engine	Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits.

Returns

SWMM_OK on success; SWMM_ERR_BADHANDLE for a null engine; SWMM_ERR_BADINDEX for an invalid integer index; SWMM_ERR_BADPARAM for invalid required storage or values. Lifecycle restrictions and additional errors are described above.

swmm_2d_initial_quality_count()

SWMM_ENGINE_API int swmm_2d_initial_quality_count	(	SWMM_Engine	engine,
		int *	count )

Read the authored initial water-quality row count.

Parameters

[out]	count	Required destination for the current count.
[in]	engine	Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits.

Returns

SWMM_OK on success; SWMM_ERR_BADHANDLE for a null engine; SWMM_ERR_BADINDEX for an invalid integer index; SWMM_ERR_BADPARAM for invalid required storage or values. Lifecycle restrictions and additional errors are described above.

swmm_2d_output_variable_count()

SWMM_ENGINE_API int swmm_2d_output_variable_count

(

void

)

Number of selectable dataset groups.

Returns

Number of known group tokens.

Here is the call graph for this function:

swmm_2d_output_variable_mask()

SWMM_ENGINE_API unsigned swmm_2d_output_variable_mask

(

const char *

text

)

Bitmask for a preset name ("DEFAULT", "MINIMAL", "ALL") or a token list; returns 0 for an unparseable string.

Parameters

[in]

text

Optional null-terminated preset/token list; NULL or unparseable text yields zero.

Returns

Parsed bitmask, or zero for NULL/unparseable input (also a valid empty selection).

Here is the call graph for this function:

swmm_2d_output_variable_name()

SWMM_ENGINE_API const char * swmm_2d_output_variable_name

(

int

i

)

Token of group i (0-based, bit i), or "" when out of range.

Parameters

[in]

i

Zero-based dataset-group token index, in bit order.

Returns

Borrowed immutable token string for the process lifetime, or an empty string for an invalid index. Do not free it.

Here is the call graph for this function:

swmm_2d_output_variable_text()

SWMM_ENGINE_API const char * swmm_2d_output_variable_text

(

unsigned

mask

)

Preset name or token list for mask (static buffer, valid until the next call).

Parameters

[in]

mask

Dataset-group bitmask to format as a preset or token list.

Returns

Borrowed thread-local string; valid until this function is called again on the same thread. Copy before retaining; do not free it.

Here is the call graph for this function:

swmm_2d_remove_boundary_quality()

SWMM_ENGINE_API int swmm_2d_remove_boundary_quality	(	SWMM_Engine	engine,
		int	index )

Erase one authored boundary-quality row.

Parameters

[in]	engine	Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits.
[in]	index	Zero-based authored row index; removing a row shifts later indices down.

Note

Configuration edits require BUILDING/OPENED; later states return SWMM_ERR_LIFECYCLE.

Returns

SWMM_OK on success; SWMM_ERR_BADHANDLE for a null engine; SWMM_ERR_BADINDEX for an invalid integer index; SWMM_ERR_BADPARAM for invalid required storage or values. Lifecycle restrictions and additional errors are described above.

swmm_2d_remove_initial_bed_quality()

SWMM_ENGINE_API int swmm_2d_remove_initial_bed_quality	(	SWMM_Engine	engine,
		int	index )

Erase one authored finite-bed initial-quality row.

Parameters

[in]	engine	Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits.
[in]	index	Zero-based authored row index; removing a row shifts later indices down.

Note

Configuration edits require BUILDING/OPENED; later states return SWMM_ERR_LIFECYCLE.

Returns

SWMM_OK on success; SWMM_ERR_BADHANDLE for a null engine; SWMM_ERR_BADINDEX for an invalid integer index; SWMM_ERR_BADPARAM for invalid required storage or values. Lifecycle restrictions and additional errors are described above.

swmm_2d_remove_initial_quality()

SWMM_ENGINE_API int swmm_2d_remove_initial_quality	(	SWMM_Engine	engine,
		int	index )

Erase one authored initial water-quality row.

Parameters

[in]	engine	Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits.
[in]	index	Zero-based authored row index; removing a row shifts later indices down.

Note

Configuration edits require BUILDING/OPENED; later states return SWMM_ERR_LIFECYCLE.

Returns

SWMM_OK on success; SWMM_ERR_BADHANDLE for a null engine; SWMM_ERR_BADINDEX for an invalid integer index; SWMM_ERR_BADPARAM for invalid required storage or values. Lifecycle restrictions and additional errors are described above.

swmm_2d_set_auto_backend_cpu()

SWMM_ENGINE_API int swmm_2d_set_auto_backend_cpu	(	SWMM_Engine	engine,
		int	enabled )

Resolve an unoverridden AUTO backend to the built-in CPU marcher for this session. Valid in BUILDING or OPENED state, including models without a mesh. enabled must be 0 or 1. Does not edit BACKEND, serialize a model option or change checkpoint identity. Explicit BACKEND and OPENSWMM_2D_BACKEND requests retain precedence. Reapply after opening a new model.

Parameters

[in]	enabled	Exactly 0 to disable or 1 to enable the session preference.
[in]	engine	Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits.

Returns

SWMM_OK on success; SWMM_ERR_BADHANDLE for a null engine; SWMM_ERR_BADINDEX for an invalid integer index; SWMM_ERR_BADPARAM for invalid required storage or values. Lifecycle restrictions and additional errors are described above.

swmm_2d_set_boundary_quality()

SWMM_ENGINE_API int swmm_2d_set_boundary_quality	(	SWMM_Engine	engine,
		int	cell,
		int	edge,
		const char *	species,
		double	conc )

Add or replace the row keyed by (cell, edge, species).

Parameters

[in]	species	Required nonempty copied species name; resolved at initialize.
[in]	conc	Finite nonnegative concentration in native species units.
[in]	engine	Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits.
[in]	cell	Zero-based cell index in [0, cell_count); includes triangles and quadrilaterals.
[in]	edge	Zero-based local edge in [0, cell_vertex_count); exterior edge required for boundary edits.

Note

Configuration edits require BUILDING/OPENED; later states return SWMM_ERR_LIFECYCLE.

Returns

SWMM_OK on success; SWMM_ERR_BADHANDLE for a null engine; SWMM_ERR_BADINDEX for an invalid integer index; SWMM_ERR_BADPARAM for invalid required storage or values. Lifecycle restrictions and additional errors are described above.

Here is the call graph for this function:

swmm_2d_set_edge_bc_concentrations()

SWMM_ENGINE_API int swmm_2d_set_edge_bc_concentrations	(	SWMM_Engine	engine,
		int	cell,
		int	edge,
		const double *	values,
		int	species_count )

Runtime inflow concentrations in the species getter's units/order. Outflow uses donor concentrations. clear_edge_bc restores authored hydraulics/quality.

Restore an edge's pre-runtime boundary prescription, including its time series. Valid between running steps; cumulative flux accounting is preserved.

Parameters

[in]	values	Borrowed species_count-double inflow concentration array; NULL only for zero count. Every value finite; nonsigned species nonnegative.
[in]	species_count	Exactly the active transported species count; order/units match swmm_2d_species_name().
[in]	engine	Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits.
[in]	cell	Zero-based cell index in [0, cell_count); includes triangles and quadrilaterals.
[in]	edge	Zero-based local edge in [0, cell_vertex_count); exterior edge required for boundary edits.

Note

Requires an active surface router. A parsed mesh before initialization returns SWMM_ERR_LIFECYCLE; other inactive/no-mesh cases return SWMM_ERR_BADPARAM.

Boundary storage must be prepared. Edits target exterior unowned edges in OPENED/BUILDING/INITIALIZED/RUNNING. Active edits additionally require an allowed between-step update and the CPU runtime; they synchronize pending work and save the authored prescription for later restoration.

Returns

SWMM_OK on success; SWMM_ERR_BADHANDLE for a null engine; SWMM_ERR_BADINDEX for an invalid integer index; SWMM_ERR_BADPARAM for invalid required storage or values. Lifecycle restrictions and additional errors are described above.

Here is the call graph for this function:

swmm_2d_set_edge_bc_flow()

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

Set prescribed flow per metre of edge (same units convention as the getter: display flow units/m before initialize, m³/s/m after). V-E4.

Parameters

[in]	flow	Finite new signed total discharge per edge width, current boundary length units squared per second.
[in]	engine	Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits.
[in]	tri_idx	Zero-based cell index in [0, cell_count); includes triangles and quadrilaterals.
[in]	edge	Zero-based local edge in [0, cell_vertex_count); exterior edge required for boundary edits.

Note

Requires a parsed mesh; no initialized hydraulic state is needed.

Boundary storage must be prepared. Edits target exterior unowned edges in OPENED/BUILDING/INITIALIZED/RUNNING. Active edits additionally require an allowed between-step update and the CPU runtime; they synchronize pending work and save the authored prescription for later restoration.

Returns

SWMM_OK on success; SWMM_ERR_BADHANDLE for a null engine; SWMM_ERR_BADINDEX for an invalid integer index; SWMM_ERR_BADPARAM for invalid required storage or values. Lifecycle restrictions and additional errors are described above.

Here is the call graph for this function:

swmm_2d_set_edge_bc_flow_tseries_name()

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

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

Parameters

[in]	name	Optional copied table name; NULL or empty clears the binding. Must resolve immediately during an active run; pre-run lookup is deferred.
[in]	engine	Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits.
[in]	tri_idx	Zero-based cell index in [0, cell_count); includes triangles and quadrilaterals.
[in]	edge	Zero-based local edge in [0, cell_vertex_count); exterior edge required for boundary edits.

Note

Requires a parsed mesh; no initialized hydraulic state is needed.

Boundary storage must be prepared. Edits target exterior unowned edges in OPENED/BUILDING/INITIALIZED/RUNNING. Active edits additionally require an allowed between-step update and the CPU runtime; they synchronize pending work and save the authored prescription for later restoration.

Returns

SWMM_OK on success; SWMM_ERR_BADHANDLE for a null engine; SWMM_ERR_BADINDEX for an invalid integer index; SWMM_ERR_BADPARAM for invalid required storage or values. Lifecycle restrictions and additional errors are described above.

Here is the call graph for this function:

swmm_2d_set_edge_bc_group()

SWMM_ENGINE_API int swmm_2d_set_edge_bc_group	(	SWMM_Engine	engine,
		int	tri_idx,
		int	edge,
		const char *	group )

Author a boundary group token (empty clears), preserving the hydraulic prescription. OPENED/BUILDING only; nonempty names require an exterior edge and cannot contain whitespace or INP delimiters. Groups are organizational metadata.

Here is the call graph for this function:

swmm_2d_set_edge_bc_rating_curve_name()

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

Set the curve NAME to drive a RATING_CURVE edge.

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

Parameters

[in]	name	Optional copied table name; NULL or empty clears the binding. Must resolve immediately during an active run; pre-run lookup is deferred.
[in]	engine	Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits.
[in]	tri_idx	Zero-based cell index in [0, cell_count); includes triangles and quadrilaterals.
[in]	edge	Zero-based local edge in [0, cell_vertex_count); exterior edge required for boundary edits.

Note

Requires a parsed mesh; no initialized hydraulic state is needed.

Boundary storage must be prepared. Edits target exterior unowned edges in OPENED/BUILDING/INITIALIZED/RUNNING. Active edits additionally require an allowed between-step update and the CPU runtime; they synchronize pending work and save the authored prescription for later restoration.

Returns

SWMM_OK on success; SWMM_ERR_BADHANDLE for a null engine; SWMM_ERR_BADINDEX for an invalid integer index; SWMM_ERR_BADPARAM for invalid required storage or values. Lifecycle restrictions and additional errors are described above.

Here is the call graph for this function:

swmm_2d_set_edge_wall_drag()

SWMM_ENGINE_API int swmm_2d_set_edge_wall_drag	(	SWMM_Engine	engine,
		int	tri_idx,
		int	edge,
		double	cw )

Here is the call graph for this function:

swmm_2d_set_initial_bed_quality()

SWMM_ENGINE_API int swmm_2d_set_initial_bed_quality	(	SWMM_Engine	engine,
		int	scope,
		const char *	tag,
		int	cell,
		const char *	species,
		double	conc )

Upsert a finite-bed initial-quality row by scope and species.

Parameters

[in]	scope	SWMM_2D_QUAL_SCOPE_GLOBAL, TAG or CELL.
[in]	tag	Required nonempty copied tag for TAG scope; ignored otherwise and may be NULL.
[in]	cell	Zero-based cell for CELL scope; nonnegative, checked against a present mesh, otherwise deferred.
[in]	species	Required nonempty copied species name; resolution deferred to initialize.
[in]	conc	Finite nonnegative concentration in native species units.
[in]	engine	Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits.

Note

Configuration edits require BUILDING/OPENED; later states return SWMM_ERR_LIFECYCLE.

Returns

SWMM_OK on success; SWMM_ERR_BADHANDLE for a null engine; SWMM_ERR_BADINDEX for an invalid integer index; SWMM_ERR_BADPARAM for invalid required storage or values. Lifecycle restrictions and additional errors are described above.

swmm_2d_set_initial_quality()

SWMM_ENGINE_API int swmm_2d_set_initial_quality	(	SWMM_Engine	engine,
		int	scope,
		const char *	tag,
		int	cell,
		const char *	species,
		double	conc )

Add or replace a row keyed by (scope, tag | cell, species).

Parameters

[in]	scope	SWMM_2D_QUAL_SCOPE_GLOBAL, TAG or CELL.
[in]	tag	Required nonempty copied tag for TAG scope; ignored otherwise and may be NULL.
[in]	cell	Zero-based cell for CELL scope; nonnegative, checked against a present mesh, otherwise deferred.
[in]	species	Required nonempty copied species name; resolution deferred to initialize.
[in]	conc	Finite nonnegative concentration in native species units.
[in]	engine	Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits.

Note

Configuration edits require BUILDING/OPENED; later states return SWMM_ERR_LIFECYCLE.

Returns

SWMM_OK on success; SWMM_ERR_BADHANDLE for a null engine; SWMM_ERR_BADINDEX for an invalid integer index; SWMM_ERR_BADPARAM for invalid required storage or values. Lifecycle restrictions and additional errors are described above.