OpenSWMM Engine  6.0.0-alpha.4
Data-oriented, plugin-extensible SWMM Engine (6.0.0-alpha.4)
Loading...
Searching...
No Matches

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 "../../core/UnitConversion.hpp"
#include "../mesh/MeshBuilder.hpp"
#include "../data/Report2DVars.hpp"
#include <cmath>
#include <cctype>
#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_EDGE_IDX(cell, edge, router2d)
 Local edge index must be < the cell's vertex count (3 or 4).
 
#define CHECK_VERT_IDX(idx, router2d)
 
#define CHECK_BC_SIZED(vec, idx)
 

Functions

int swmm_2d_is_active (SWMM_Engine engine, int *active)
 Check whether the 2D module is active for this simulation.
 
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.
 
int swmm_2d_prepare_for_edit (SWMM_Engine engine)
 Make the parsed 2D mesh editable without a full initialize().
 
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.
 
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_set_vertex_z_bulk (SWMM_Engine engine, const double *z, int count)
 Set EVERY vertex Z in one call.
 
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_cell_count (SWMM_Engine engine, int *count)
 Number of cells (triangles + quads) — same value as swmm_2d_triangle_count.
 
int swmm_2d_quad_count (SWMM_Engine engine, int *count)
 Number of quadrilateral cells (0 for an all-triangle mesh).
 
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.
 
int swmm_2d_cell_vertex_count (SWMM_Engine engine, int idx, int *nv)
 Vertices (== edges) of a cell: 3 or 4.
 
int swmm_2d_cell_get_vertices (SWMM_Engine engine, int idx, int *v, int *nv)
 Cell connectivity for any shape.
 
int swmm_2d_cell_get_neighbours (SWMM_Engine engine, int idx, int *n, int *nv)
 Neighbour cell across each local edge, any shape.
 
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_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.
 
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).
 
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).
 
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.
 
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_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).
 
int swmm_2d_clear_triangle_couplings (SWMM_Engine engine)
 Remove every authored node→cell coupling row (all triangles).
 
int swmm_2d_triangle_coupling_rows (SWMM_Engine engine, int *count)
 Number of authored node→cell coupling rows.
 
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.
 
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; 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). Persisted by the .inp writer. Same units convention as the getter: mesh length units² (project units before initialize, m² after).
 
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, m).
 
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_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.
 
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 (m).
 
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.
 
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.
 
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.
 
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.
 
int swmm_2d_get_heads_bulk (SWMM_Engine engine, double *heads)
 Bulk get heads for all triangles (m).
 
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.
 
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_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.
 
int swmm_2d_species_name (SWMM_Engine engine, int species, char *buf, int buflen)
 One surface species row's name.
 
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.
 
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].
 
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_vertex_get_render_depths_bulk (SWMM_Engine engine, double *depths)
 Bulk get render-oriented SIGNED vertex depths (m) 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_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.)
 
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.)
 
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.
 
int swmm_2d_get_stat_max_depths (SWMM_Engine engine, double *max_depths)
 Get per-triangle max depth statistics (cumulative, m).
 
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_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_concentrations (SWMM_Engine engine, int cell, int edge, const double *values, int count)
 Runtime inflow concentrations in the species getter's units/order. Outflow uses donor concentrations. clear_edge_bc restores authored hydraulics/quality.
 
int swmm_2d_clear_edge_bc (SWMM_Engine engine, int tri_idx, int edge)
 Restore the authored boundary hydraulics and quality for one 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 (same units convention as the getter).
 
int swmm_2d_set_edge_bc_group (SWMM_Engine engine, int tri_idx, int edge, const char *group)
 
int swmm_2d_get_edge_wall_drag (SWMM_Engine engine, int tri_idx, int edge, double *cw)
 
int swmm_2d_set_edge_wall_drag (SWMM_Engine engine, int tri_idx, int edge, double cw)
 
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 for a SPECIFIED_FLOW edge. V-E4.
 
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.
 
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.
 
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.
 
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.
 
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.
 
int swmm_2d_output_variable_count (void)
 Number of selectable dataset groups.
 
const char * swmm_2d_output_variable_name (int i)
 Token of group i (0-based, bit i), or "" when out of range.
 
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.
 
const char * swmm_2d_output_variable_text (unsigned mask)
 Preset name or token list for mask (static buffer, valid until the next call).
 
int swmm_2d_initial_quality_count (SWMM_Engine engine, int *count)
 Read the authored initial water-quality row count.
 
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.
 
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).
 
int swmm_2d_remove_initial_quality (SWMM_Engine engine, int index)
 Erase one authored initial water-quality row.
 
int swmm_2d_initial_bed_quality_count (SWMM_Engine engine, int *count)
 Read the authored finite-bed initial-quality row count.
 
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.
 
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.
 
int swmm_2d_remove_initial_bed_quality (SWMM_Engine engine, int index)
 Erase one authored finite-bed initial-quality row.
 
int swmm_2d_boundary_quality_count (SWMM_Engine engine, int *count)
 Read the authored boundary-quality row count.
 
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.
 
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).
 
int swmm_2d_remove_boundary_quality (SWMM_Engine engine, int index)
 Erase one authored boundary-quality row.
 

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.

Author
Caleb Buahin caleb.nosp@m..bua.nosp@m.hin@g.nosp@m.mail.nosp@m..com
License
Apache-2.0

Macro Definition Documentation

◆ CHECK_2D_ACTIVE

#define CHECK_2D_ACTIVE ( eng)
Value:
auto& router2d = eng->surfaceRouter2D(); \
if (!router2d.isActive()) \
return inactive2DError(*eng)

◆ CHECK_2D_MESH

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

◆ CHECK_BC_SIZED

#define CHECK_BC_SIZED ( vec,
idx )
Value:
if ((idx) < 0 || static_cast<std::size_t>(idx) >= (vec).size()) \

◆ CHECK_EDGE_IDX

#define CHECK_EDGE_IDX ( cell,
edge,
router2d )
Value:
do { \
if ((edge) < 0 || (edge) >= (router2d).mesh().cell_vertex_count(cell)) \
} while (0)
@ SWMM_ERR_BADINDEX
Definition openswmm_engine.h:133

Local edge index must be < the cell's vertex count (3 or 4).

◆ CHECK_TRI_IDX

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

◆ 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) \
@ SWMM_ERR_BADHANDLE
Definition openswmm_engine.h:132

Function Documentation

◆ swmm_2d_boundary_quality_count()

int swmm_2d_boundary_quality_count ( SWMM_Engine engine,
int * count )

Read the authored boundary-quality row count.

Parameters
[out]countRequired destination for the current count.
[in]engineBorrowed 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()

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]engineBorrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits.
[in]cellZero-based cell index in [0, cell_count); includes triangles and quadrilaterals.
[in]edgeZero-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()

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]scaleRequired result slot, 1.0 or 0.3048; square for area conversion.
[in]engineBorrowed 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()

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]cellOptional zero-based boundary-cell destination.
[out]edgeOptional zero-based local-edge destination.
[out]speciesOptional species-name destination, safely truncated when capacity is positive.
[in]species_lenSpecies-name byte capacity; nonpositive skips the string.
[out]concOptional native-species concentration destination.
[in]engineBorrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits.
[in]indexZero-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()

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]bufRequired writable table-name destination, safely truncated with NUL.
[in]buflenPositive byte capacity including the terminator.
[in]engineBorrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits.
[in]tri_idxZero-based cell index in [0, cell_count); includes triangles and quadrilaterals.
[in]edgeZero-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()

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]bufRequired writable table-name destination, safely truncated with NUL.
[in]buflenPositive byte capacity including the terminator.
[in]engineBorrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits.
[in]tri_idxZero-based cell index in [0, cell_count); includes triangles and quadrilaterals.
[in]edgeZero-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()

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

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]scopeOptional SWMM_2D_QUAL_SCOPE_* destination.
[out]tagOptional tag destination; positive capacity safely truncates with NUL.
[in]tag_lenTag capacity in bytes; nonpositive skips copying.
[out]cellOptional zero-based cell index; -1 for a non-CELL row.
[out]speciesOptional species-name destination, safely truncated when capacity is positive.
[in]species_lenSpecies buffer byte capacity; nonpositive skips copying.
[out]concOptional authored concentration in native species units.
[in]engineBorrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits.
[in]indexZero-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()

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]scopeOptional SWMM_2D_QUAL_SCOPE_* destination.
[out]tagOptional tag destination; positive capacity safely truncates with NUL.
[in]tag_lenTag capacity in bytes; nonpositive skips copying.
[out]cellOptional zero-based cell index; -1 for a non-CELL row.
[out]speciesOptional species-name destination, safely truncated when capacity is positive.
[in]species_lenSpecies buffer byte capacity; nonpositive skips copying.
[out]concOptional authored concentration in native species units.
[in]engineBorrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits.
[in]indexZero-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()

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]engineBorrowed live engine handle. Serialize with stepping/edits.
[out]vxRequired distinct caller-owned cell_count-double X array.
[out]vyRequired 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()

int swmm_2d_initial_bed_quality_count ( SWMM_Engine engine,
int * count )

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

Parameters
[out]countRequired destination for the current count.
[in]engineBorrowed 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()

int swmm_2d_initial_quality_count ( SWMM_Engine engine,
int * count )

Read the authored initial water-quality row count.

Parameters
[out]countRequired destination for the current count.
[in]engineBorrowed 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()

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

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]textOptional 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()

const char * swmm_2d_output_variable_name ( int i)

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

Parameters
[in]iZero-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()

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]maskDataset-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()

int swmm_2d_remove_boundary_quality ( SWMM_Engine engine,
int index )

Erase one authored boundary-quality row.

Parameters
[in]engineBorrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits.
[in]indexZero-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()

int swmm_2d_remove_initial_bed_quality ( SWMM_Engine engine,
int index )

Erase one authored finite-bed initial-quality row.

Parameters
[in]engineBorrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits.
[in]indexZero-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()

int swmm_2d_remove_initial_quality ( SWMM_Engine engine,
int index )

Erase one authored initial water-quality row.

Parameters
[in]engineBorrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits.
[in]indexZero-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()

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]enabledExactly 0 to disable or 1 to enable the session preference.
[in]engineBorrowed 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()

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]speciesRequired nonempty copied species name; resolved at initialize.
[in]concFinite nonnegative concentration in native species units.
[in]engineBorrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits.
[in]cellZero-based cell index in [0, cell_count); includes triangles and quadrilaterals.
[in]edgeZero-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()

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]valuesBorrowed species_count-double inflow concentration array; NULL only for zero count. Every value finite; nonsigned species nonnegative.
[in]species_countExactly the active transported species count; order/units match swmm_2d_species_name().
[in]engineBorrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits.
[in]cellZero-based cell index in [0, cell_count); includes triangles and quadrilaterals.
[in]edgeZero-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()

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]flowFinite new signed total discharge per edge width, current boundary length units squared per second.
[in]engineBorrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits.
[in]tri_idxZero-based cell index in [0, cell_count); includes triangles and quadrilaterals.
[in]edgeZero-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()

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]nameOptional copied table name; NULL or empty clears the binding. Must resolve immediately during an active run; pre-run lookup is deferred.
[in]engineBorrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits.
[in]tri_idxZero-based cell index in [0, cell_count); includes triangles and quadrilaterals.
[in]edgeZero-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()

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

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]nameOptional copied table name; NULL or empty clears the binding. Must resolve immediately during an active run; pre-run lookup is deferred.
[in]engineBorrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits.
[in]tri_idxZero-based cell index in [0, cell_count); includes triangles and quadrilaterals.
[in]edgeZero-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()

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

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]scopeSWMM_2D_QUAL_SCOPE_GLOBAL, TAG or CELL.
[in]tagRequired nonempty copied tag for TAG scope; ignored otherwise and may be NULL.
[in]cellZero-based cell for CELL scope; nonnegative, checked against a present mesh, otherwise deferred.
[in]speciesRequired nonempty copied species name; resolution deferred to initialize.
[in]concFinite nonnegative concentration in native species units.
[in]engineBorrowed 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()

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]scopeSWMM_2D_QUAL_SCOPE_GLOBAL, TAG or CELL.
[in]tagRequired nonempty copied tag for TAG scope; ignored otherwise and may be NULL.
[in]cellZero-based cell for CELL scope; nonnegative, checked against a present mesh, otherwise deferred.
[in]speciesRequired nonempty copied species name; resolution deferred to initialize.
[in]concFinite nonnegative concentration in native species units.
[in]engineBorrowed 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.