 |
OpenSWMM Engine
6.0.0-alpha.4
Data-oriented, plugin-extensible SWMM Engine (6.0.0-alpha.4)
|
|
OpenSWMM Engine
6.0.0-alpha.4
Data-oriented, plugin-extensible SWMM Engine (6.0.0-alpha.4)
|
Topics | |
| Optional 2D GPU execution | |
| Kokkos device state, surface execution, plugin ABI and host recharge operators. | |
| 2D Infiltration API | |
Files | |
| file | Api2D.cpp |
| C API implementation for the 2D surface routing module. | |
| file | Api2D.hpp |
| C API implementation bridge for the 2D surface routing module. | |
| file | ApiGw2D.cpp |
G-step 19 — implementation of openswmm_gw2d.h. | |
| file | ExchangeLaw.hpp |
| Regime-aware 1D↔2D exchange law (COUPLING_LAW WEIR_ORIFICE): free / submerged weir and orifice, surface→sewer and sewer→surface. | |
| file | ExchangeStructure.cpp |
| resolveExchangeStructure: a junction point's WEIR_ORIFICE law, structure and coefficients from [2D_NODE_COUPLING], presets and the global options. | |
| file | NodeCoupling.cpp |
| Implementation of 2D↔1D node coupling via orifice exchange. | |
| file | NodeCoupling.hpp |
| Orifice-equation exchange between 2D surface and SWMM nodes. | |
| file | PondModel.hpp |
| Above-rim pond of a 2D-coupled junction: a C¹ surface-area ramp, its closed-form volume and inverse, and the head-equalisation cap. | |
| file | BoundaryData.hpp |
| Structure-of-Arrays (SoA) storage for 2D mesh boundary conditions. | |
| file | MeshData.hpp |
| Structure-of-Arrays (SoA) storage for 2D triangular mesh geometry. | |
| file | PendingRows2D.hpp |
| Parse-time scratch rows for [2D_BOUNDARY_CONDITIONS] and [2D_EDGE_CONVEYANCE] input sections. | |
| file | Serialize2D.hpp |
Header-only helpers shared by 2D model serialization consumers (InpWriter [2D_*] emission, GeoPackage writer). | |
| file | SolverOptions2D.hpp |
| Configuration options for the 2D surface routing solver. | |
| file | SurfaceStateData.hpp |
| Structure-of-Arrays (SoA) storage for 2D surface routing state. | |
| file | SurfaceTransportState.hpp |
| Overland transport S1 — per-cell species MASS on the 2D surface. | |
| file | GwTransportData.hpp |
U4 (2026-09-07) — authoring state for subsurface (groundwater) transport: [GW_TRANSPORT_OPTIONS], [GW_TRANSPORT_PARAMS], [GW_SORPTION], [GW_INITIAL_QUALITY], [GW_BOUNDARY_QUALITY] and [GW_SOURCES]. | |
| file | GwTransportSections.hpp |
U4 (2026-09-07) — parsers and registration for the [GW_*] subsurface-transport authoring sections. See GwTransportData.hpp for retained authoring shapes and runtime resolution contracts. | |
| file | Infil2D.cpp |
| Per-cell infiltration for the 2D overland-flow mesh (track I). | |
| file | Infil2D.hpp |
| Per-cell infiltration for the 2D overland-flow mesh (track I). | |
| file | SectionHandlers2D.cpp |
| Implementation of 2D input section parsers. | |
| file | SectionHandlers2D.hpp |
| Input section parsers for the 2D surface routing module. | |
| file | MeshBuilder.cpp |
| Implementation of mesh topology construction and geometry computation. | |
| file | MeshBuilder.hpp |
| Topology construction and geometry precomputation for the 2D mesh. | |
| file | QuadVfr.hpp |
| Volume–free-surface relationship (VFR) for a quadrilateral cell. | |
| file | RainfallInterpolator.cpp |
| Implementation of natural-neighbour / IDW rainfall interpolation. | |
| file | RainfallInterpolator.hpp |
| Static per-cell weights mapping raingage rainfall onto the 2D mesh. | |
| file | VertexReconstruction.cpp |
| Implementation of pseudo-Laplacian vertex stencil construction and head reconstruction. | |
| file | VertexReconstruction.hpp |
| Pseudo-Laplacian vertex reconstruction stencil computation. | |
| file | VfrClosure.hpp |
| Volume–free-surface (VFR) closure for a planar-bed triangular cell. | |
| file | Default2DOutputPlugin.cpp |
| HDF5 output plugin for 2D surface routing results (CF/UGRID). | |
| file | Default2DOutputPlugin.hpp |
| Built-in HDF5 output plugin for 2D surface routing results. | |
| file | SurfaceQuality2D.hpp |
| S7 (2026-09-19) — cell coverages, buildup, washoff and street sweeping on the 2D overland surface. | |
| file | DiffusiveKernels.hpp |
| Face law and step bound for MOMENTUM_EQUATION DIFFUSIVE_WAVE (plans/2D_FULL_SWE_SHOCK_CAPTURING_PLAN_2026-09-05.md §2.3). | |
| file | ExplicitInertialSolver.cpp |
| Implementation of the explicit local-inertial FV marcher with power-of-two tiered local timestepping (LTS). | |
| file | ExplicitInertialSolver.hpp |
| Explicit local-inertial FV time-marcher for the 2D surface. | |
| file | InertialEdges.cpp |
| Implementation of the unique interior-edge builder. | |
| file | InertialEdges.hpp |
| Unique interior-edge structure for the local-inertial momentum DOFs. | |
| file | InertialKernels.hpp |
| Single-source flat kernels for the explicit local-inertial marcher. | |
| file | ISurfaceSolver.hpp |
| Backend-neutral interface for the 2D surface-routing time integrator. | |
| file | SurfaceFluxCalculator.cpp |
| Implementation of gradient computation, slope limiting, and edge fluxes. | |
| file | SurfaceFluxCalculator.hpp |
| Edge flux computation, gradient calculation, and slope limiting. | |
| file | SurfaceSolverFactory.cpp |
| Implementation of runtime 2D surface-solver backend selection. | |
| file | SurfaceSolverFactory.hpp |
| Runtime selection of the 2D surface solver backend (Phase 4). | |
| file | SweKernels.hpp |
| Face kernels for MOMENTUM_EQUATION FULL_SWE — the conservative shallow-water equations with the convective term and shock capturing (plans/2D_FULL_SWE_SHOCK_CAPTURING_PLAN_2026-09-05.md §2.2). | |
| file | SigmaColumn.hpp |
| G-steps 4 and 5 — closure B: the σ-coordinate explicit unsaturated column with a moving lower boundary (the water table). | |
| file | SoilCharacteristic.hpp |
G-steps 2 and 13 — the four production soil-characteristic laws and the closure-A quasi-steady recharge q₀(hᵤ, h_g). | |
| file | SubsurfaceData.cpp |
| Sizing, storage accounting and token round-trip for the two-zone groundwater state (G-step 1). | |
| file | SubsurfaceData.hpp |
| G-step 1 — state, parameters and options for the two-zone groundwater kernel (TWO_ZONE_GROUNDWATER_EXPLICIT_LTS_PLAN §4). | |
| file | SubsurfaceSections.cpp |
Parsers, resolution and writer for the [2D_AQUIFER*] sections. | |
| file | SubsurfaceSections.hpp |
G-step 1 — [2D_AQUIFER_OPTIONS], [2D_AQUIFER] and [2D_AQUIFER_NODE]: parsing, unit resolution and writing. | |
| file | SubsurfaceSolver.cpp |
| The two-zone groundwater kernel (G-steps 3, 6-12, 14, 16). | |
| file | SubsurfaceSolver.hpp |
| G-steps 3, 6-12, 16 — the two-zone groundwater kernel: saturated FV update, lateral Darcy, closure dispatch, node exchange, Dunne transfer, ET, and the LTS tier hooks the surface marcher calls. | |
| file | SubsurfaceTransportState.hpp |
| T7.1 — species / age / enthalpy carried by the two-zone groundwater kernel (GW transport plan §3.4). | |
| file | SurfaceRouter2D.cpp |
| Implementation of the 2D surface routing orchestrator. | |
| file | SurfaceRouter2D.hpp |
| Top-level orchestrator for the optional 2D surface routing module. | |
| file | openswmm_gw2d.h |
G-step 19 — the two-zone groundwater kernel's C API: authoring the [2D_AQUIFER*] rows, and reading the state and ledger while a run is in flight. | |
| file | openswmm_gw_transport.h |
U4 (2026-09-07) — C API for the [GW_*] subsurface-transport authoring sections. | |
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... | |
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). | |
Functions | |
| SWMM_ENGINE_API int | swmm_2d_is_active (SWMM_Engine engine, int *active) |
| Check whether the 2D module is active for this simulation. | |
| SWMM_ENGINE_API int | swmm_2d_prepare_for_edit (SWMM_Engine engine) |
| Make the parsed 2D mesh editable without a full initialize(). | |
| SWMM_ENGINE_API int | swmm_2d_vertex_count (SWMM_Engine engine, int *count) |
| Get the number of mesh vertices. | |
| SWMM_ENGINE_API int | swmm_2d_triangle_count (SWMM_Engine engine, int *count) |
| Get the number of mesh triangles. | |
| SWMM_ENGINE_API int | swmm_2d_vertex_get_xyz (SWMM_Engine engine, int idx, double *x, double *y, double *z) |
| Get vertex coordinates. | |
| SWMM_ENGINE_API int | swmm_2d_vertex_get_xyz_bulk (SWMM_Engine engine, double *x, double *y, double *z) |
| Bulk get vertex coordinates. | |
| SWMM_ENGINE_API int | swmm_2d_set_vertex_z (SWMM_Engine engine, int idx, double z) |
| Set vertex Z (ground elevation). | |
| SWMM_ENGINE_API int | swmm_2d_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_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_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_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_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_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. | |
| 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).
| 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).
A triangle may carry several coupling rows — one per node — so this APPENDS rather than overwrites (contrast swmm_2d_set_vertex_coupled_node). The node NAME is stored verbatim and resolved against the current model (-1 tolerated until re-resolution, mirroring the vertex setter). The .inp writer emits one [2D_TRIANGLE_NODE_MAP] row per coupling.
| [in] | node_name | Required nonempty copied node identifier; an unknown name is deferred. |
| [in] | cd | Positive dimensionless discharge coefficient, or NaN for inherited/unset. |
| [in] | area | Positive area in current mesh length units squared, or NaN for inherited/unset. |
| [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. |
| SWMM_ENGINE_API int swmm_2d_boundary_edge_count | ( | SWMM_Engine | engine, |
| int * | count ) |
Get the number of boundary edges (edges with no neighbour).
| [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. |
| 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.
| [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. |
| 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.
| [out] | nv | Required result slot, 3 or 4. |
| [out] | n | Required writable int[4]; -1 marks an exterior edge and -2 padding. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| [in] | idx | Zero-based cell index in [0, cell_count); includes triangles and quadrilaterals. |
| SWMM_ENGINE_API int swmm_2d_cell_get_vertices | ( | SWMM_Engine | engine, |
| int | idx, | ||
| int * | v, | ||
| int * | nv ) |
Cell connectivity for any shape.
| [out] | nv | Required result slot, 3 or 4. |
| [out] | v | Required writable int[4]; unused entries are -1. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| [in] | idx | Zero-based cell index in [0, cell_count); includes triangles and quadrilaterals. |
| SWMM_ENGINE_API int swmm_2d_cell_vertex_count | ( | SWMM_Engine | engine, |
| int | idx, | ||
| int * | nv ) |
Vertices (== edges) of a cell: 3 or 4.
| [out] | nv | Required result slot, 3 or 4. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| [in] | idx | Zero-based cell index in [0, cell_count); includes triangles and quadrilaterals. |
| SWMM_ENGINE_API int swmm_2d_clear_triangle_couplings | ( | SWMM_Engine | engine | ) |
Remove every authored node→cell coupling row (all triangles).
Also clears the legacy per-triangle mirror (coupled node, CD, AREA back to defaults). Vertex couplings are untouched. Typical use: the GUI's Remap 1D↔2D re-authoring the full cell-coupling set.
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| 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].
Output arrays must be pre-allocated to cell_count * edge_stride doubles each. Local edge e is the edge opposite vertex e (matching the neighbour convention of swmm_2d_triangle_get_neighbours). Outward normals point away from the triangle interior. Provided so client-side velocity reconstruction from swmm_2d_get_edge_flux_bulk can run without re-deriving geometry from the vertex coordinates.
| [out] | length | Required cell_count * edge_stride array of edge lengths in metres. |
| [out] | nx | Required cell_count * edge_stride array of dimensionless outward unit-normal X components. |
| [out] | ny | Required cell_count * edge_stride array of dimensionless outward unit-normal Y components. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| 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.
| [out] | stride | Required destination, 3 for triangle-only meshes or 4 when any quad exists. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| SWMM_ENGINE_API int swmm_2d_force_clear_all | ( | SWMM_Engine | engine | ) |
Clear all 2D forcings.
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| 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).
| [in] | value | Finite rate in m/s; coupling is positive into 2D, evaporation is an extraction demand. |
| [in] | mode | SWMM_FORCING_NONE to clear, SWMM_FORCING_OVERRIDE to replace, or SWMM_FORCING_ADD to add. |
| [in] | persist | SWMM_FORCING_RESET for one routing window or SWMM_FORCING_PERSIST until cleared. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| [in] | idx | Zero-based cell index in [0, cell_count); includes triangles and quadrilaterals. |
| SWMM_ENGINE_API int swmm_2d_force_evap | ( | SWMM_Engine | engine, |
| int | idx, | ||
| double | value, | ||
| int | mode, | ||
| int | persist ) |
Force evaporation on a specific triangle.
The rate is a demand: wet cells lose depth at this rate, shut off smoothly as a cell dries (depths never go negative). Default rate is 0 until forced. Negative values are treated as zero (no condensation).
| [in] | value | Finite rate in m/s; coupling is positive into 2D, evaporation is an extraction demand. |
| [in] | mode | SWMM_FORCING_NONE to clear, SWMM_FORCING_OVERRIDE to replace, or SWMM_FORCING_ADD to add. |
| [in] | persist | SWMM_FORCING_RESET for one routing window or SWMM_FORCING_PERSIST until cleared. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| [in] | idx | Zero-based cell index in [0, cell_count); includes triangles and quadrilaterals. |
| SWMM_ENGINE_API int swmm_2d_force_evap_uniform | ( | SWMM_Engine | engine, |
| double | value, | ||
| int | mode, | ||
| int | persist ) |
Force evaporation on all triangles (uniform).
| [in] | value | Finite rate in m/s; coupling is positive into 2D, evaporation is an extraction demand. |
| [in] | mode | SWMM_FORCING_NONE to clear, SWMM_FORCING_OVERRIDE to replace, or SWMM_FORCING_ADD to add. |
| [in] | persist | SWMM_FORCING_RESET for one routing window or SWMM_FORCING_PERSIST until cleared. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| 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.
| [in] | value | Finite rate in m/s; coupling is positive into 2D, evaporation is an extraction demand. |
| [in] | mode | SWMM_FORCING_NONE to clear, SWMM_FORCING_OVERRIDE to replace, or SWMM_FORCING_ADD to add. |
| [in] | persist | SWMM_FORCING_RESET for one routing window or SWMM_FORCING_PERSIST until cleared. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| [in] | idx | Zero-based cell index in [0, cell_count); includes triangles and quadrilaterals. |
| SWMM_ENGINE_API int swmm_2d_force_rainfall_uniform | ( | SWMM_Engine | engine, |
| double | value, | ||
| int | mode, | ||
| int | persist ) |
Force rainfall on all triangles (uniform).
| [in] | value | Finite rate in m/s; coupling is positive into 2D, evaporation is an extraction demand. |
| [in] | mode | SWMM_FORCING_NONE to clear, SWMM_FORCING_OVERRIDE to replace, or SWMM_FORCING_ADD to add. |
| [in] | persist | SWMM_FORCING_RESET for one routing window or SWMM_FORCING_PERSIST until cleared. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| 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.
| [in] | species | Zero-based active transported species row. |
| [out] | out | Required len-double destination; native species units, age seconds and temperature degrees Celsius. |
| [in] | len | Positive capacity in doubles; partial reads are accepted. |
| [out] | written | Optional count destination, min(len, transport cell count). |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| SWMM_ENGINE_API int swmm_2d_get_continuity_error | ( | SWMM_Engine | engine, |
| double * | err ) |
Get the global 2D surface continuity error (fraction).
| [out] | err | Required destination for signed relative water-balance residual, dimensionless. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| 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).
| [out] | flux | Required destination for coupling flux in m/s, positive into 2D. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| [in] | idx | Zero-based cell index in [0, cell_count); includes triangles and quadrilaterals. |
| SWMM_ENGINE_API int swmm_2d_get_coupling_fluxes_bulk | ( | SWMM_Engine | engine, |
| double * | fluxes ) |
Bulk get coupling fluxes for all triangles.
| [out] | fluxes | Required caller-owned cell_count-double array receiving flux in m/s, positive into 2D. No capacity is passed or checked. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| 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.
Sign is from the 2D cell's point of view: positive = the 1D node delivered water INTO this cell (spill, submerged-outfall discharge); negative = the node abstracted water FROM it (drain). Output pre-allocated to triangle_count.
Summing the array gives coupling_1d_to_2d_in − coupling_2d_to_1d_out from the 2D mass balance — the identity that ties this per-cell series to the domain totals, and the natural check for a validator.
Why signed and per cell: the two domain accumulators are unsigned and cannot answer "what did THIS cell give or take", which is exactly the question at a coupling point that reverses within a batch — the two directions cancel in the net and neither is visible in the totals. swmm_2d_get_coupling_flux is a rate that is overwritten every step.
| [out] | volumes | Required caller-owned cell_count-double array receiving signed cumulative coupling volume in m3, positive into 2D. No capacity is passed or checked. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| SWMM_ENGINE_API int swmm_2d_get_depth | ( | SWMM_Engine | engine, |
| int | idx, | ||
| double * | depth ) |
Get water depth at a triangle.
| [out] | depth | Required destination for water depth in m. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| [in] | idx | Zero-based cell index in [0, cell_count); includes triangles and quadrilaterals. |
| SWMM_ENGINE_API int swmm_2d_get_depths_bulk | ( | SWMM_Engine | engine, |
| double * | depths ) |
Bulk get depths for all triangles (m).
| [out] | depths | Required caller-owned cell_count-double array receiving depth in m. No capacity is passed or checked. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| SWMM_ENGINE_API int swmm_2d_get_dry_depth | ( | SWMM_Engine | engine, |
| double * | dry_depth ) |
Get the dry depth threshold (m).
| [out] | dry_depth | Required destination for dry-depth threshold in m. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| 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).
| [out] | cum_flux | Required destination for cumulative boundary volume in m3, positive outward. |
| [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. |
| 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.
Units: project display flow units per metre (the [2D_BOUNDARY_CONDITIONS] file contract, e.g. CFS/m) before swmm_engine_initialize(); m³/s/m after it (initialize scales the constants in place; the writers scale back).
| [out] | flow | Required destination for 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. |
| 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.
Units follow the mesh vertical datum: mesh length units as authored (feet for a US project without an SI mesh header) before swmm_engine_initialize(), metres after it.
| [out] | head | Required destination for stage elevation in current boundary/mesh length units, metres after initialization. |
| [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. |
| 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.
| [out] | slope | Required destination for dimensionless nonnegative bed slope. |
| [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. |
| 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.
SVBC A8 — the setter's mirror, so a caller can verify what the engine holds after an edit push. Works in the OPENED state (mesh guard, like the setter). Truncating copy into buf, always NUL-terminated.
| [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. |
| 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.
| [out] | bc_type | Required destination for SWMM_2D_BC_* code. |
| [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. |
| 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.
| [out] | conveyance | Required dimensionless edge-factor destination. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| [in] | tri | 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. |
| SWMM_ENGINE_API int swmm_2d_get_edge_conveyance_bulk | ( | SWMM_Engine | engine, |
| double * | conveyance ) |
Bulk get conveyance factor at every edge of every triangle.
Output array must be pre-allocated to cell_count * edge_stride doubles, indexed [tri*3 + edge_local].
| [out] | conveyance | Required caller-owned cell_count * edge_stride-double array receiving dimensionless conveyance in [0,1]. No capacity is passed or checked. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| SWMM_ENGINE_API int swmm_2d_get_edge_flux_bulk | ( | SWMM_Engine | engine, |
| double * | flux ) |
Bulk get normal edge flux at every edge of every triangle.
Output array must be pre-allocated to cell_count * edge_stride doubles, indexed [cell*edge_stride + localEdge]. Sign convention: positive flux flows outward through the edge's outward normal (positive = leaving the cell). NOTE: the integrator stores edge_flux INFLOW-positive internally (a positive value raises the cell depth); this accessor (and the HDF5 Mesh2_edge_flux dataset) flip the sign so the public convention is outward-positive as documented here. Units m^3 s^-1 (total flow through the edge). Combine with swmm_2d_edge_get_geometry_bulk to reconstruct cell-centred velocity (RT0): for each triangle, solve (NᵀN) v = Nᵀ q where rows of N are the outward unit normals and q[e] = flux[e] / length[e]; with the outward-positive sign this yields the physical (down-gradient) velocity.
| [out] | flux | Required caller-owned cell_count * edge_stride-double array receiving total edge flow in m3/s, outward positive. No capacity is passed or checked. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| SWMM_ENGINE_API int swmm_2d_get_head | ( | SWMM_Engine | engine, |
| int | idx, | ||
| double * | head ) |
Get total head at a triangle (z + depth, m).
| [out] | head | Required destination for water-surface head in m. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| [in] | idx | Zero-based cell index in [0, cell_count); includes triangles and quadrilaterals. |
| SWMM_ENGINE_API int swmm_2d_get_heads_bulk | ( | SWMM_Engine | engine, |
| double * | heads ) |
Bulk get heads for all triangles (m).
| [out] | heads | Required caller-owned cell_count-double array receiving head in m. No capacity is passed or checked. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| 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.
| [out] | init_storage | Optional destination for init storage in m3. |
| [out] | final_storage | Optional destination for final storage in m3. |
| [out] | rainfall_in | Optional destination for rainfall in in m3. |
| [out] | coupling_1d_to_2d_in | Optional destination for coupling 1d to 2d in in m3. |
| [out] | coupling_2d_to_1d_out | Optional destination for coupling 2d to 1d out in m3. |
| [out] | outfall_in | Optional destination for outfall in in m3. |
| [out] | outfall_out | Optional destination for outfall out in m3. |
| [out] | boundary_in | Optional destination for boundary in in m3. |
| [out] | boundary_out | Optional destination for boundary out in m3. |
| [out] | evap_out | Optional destination for evap out in m3. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| SWMM_ENGINE_API int swmm_2d_get_max_depth | ( | SWMM_Engine | engine, |
| double * | max_depth ) |
Get the maximum depth across all triangles.
| [out] | max_depth | Required destination for maximum cell depth in m. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| 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).
| [out] | net_source | Required destination for net source rate in m/s. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| [in] | idx | Zero-based cell index in [0, cell_count); includes triangles and quadrilaterals. |
| 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.
| [out] | volumes | Required caller-owned cell_count-double array receiving cumulative rainfall volume in m3. No capacity is passed or checked. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| SWMM_ENGINE_API int swmm_2d_get_rainfall | ( | SWMM_Engine | engine, |
| int | idx, | ||
| double * | rainfall ) |
Get rainfall intensity at a triangle (m/s).
| [out] | rainfall | Required destination for applied rainfall rate in m/s. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| [in] | idx | Zero-based cell index in [0, cell_count); includes triangles and quadrilaterals. |
| 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.
| [out] | rainfall | Required caller-owned cell_count-double array receiving applied rainfall rate in m/s. No capacity is passed or checked. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| 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.
Diagnoses a cell that receives no rain: a zero from a dry contributing gage is a valid reading, not a missing weight.
| [out] | method | Required method-code destination: 0 natural neighbour, 1 IDW fallback, 2 nearest, or -1 without per-cell weights. |
| [out] | gage_indices | Writable capacity-int array; may be NULL only when capacity is zero. |
| [out] | weights | Writable capacity-double array of matching normalized weights; NULL only for zero capacity. |
| [in] | capacity | Nonnegative array capacity; only min(capacity, *count) rows are copied. |
| [out] | count | Required total contributor count, possibly greater than capacity. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| [in] | idx | Zero-based cell index in [0, cell_count); includes triangles and quadrilaterals. |
| 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.
Uses the same gage record conversion and time selection as saved 2D rainfall reports. The solver's applied window mean remains available from swmm_2d_get_rainfall_bulk().
| [out] | rainfall | Required caller-owned cell_count-double array receiving report rainfall in m/s. No capacity is passed or checked. |
| [in] | report_date | Finite absolute SWMM DateTime, in decimal days. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| 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.
| [out] | stats | Required caller-owned SWMM_2DRunStats; replaced on success, no struct_size field required. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| 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.)
| [out] | h_last | Required destination for last marcher substep in seconds. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| 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.)
| [out] | steps | Required destination for substep count from the last advance. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| 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).
| [out] | max_errs | Required caller-owned cell_count-double array receiving cumulative maximum absolute continuity error in m3/s. No capacity is passed or checked. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| SWMM_ENGINE_API int swmm_2d_get_stat_max_depths | ( | SWMM_Engine | engine, |
| double * | max_depths ) |
Get per-triangle max depth statistics (cumulative, m).
| [out] | max_depths | Required caller-owned cell_count-double array receiving cumulative maximum depth in m. No capacity is passed or checked. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| 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).
| [out] | max_velocities | Required caller-owned cell_count-double array receiving cumulative maximum speed in m/s. No capacity is passed or checked. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| 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.
| [out] | flow | Required destination for signed total coupling flow in m3/s, positive into 2D. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| SWMM_ENGINE_API int swmm_2d_get_total_volume | ( | SWMM_Engine | engine, |
| double * | volume ) |
Get total 2D surface volume (sum of depth * area).
| [out] | volume | Required destination for current surface storage in m3. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| 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.
| [in] | row_idx | Zero-based authored coupling-row index. |
| [out] | tri_idx | Required zero-based coupled-cell destination. |
| [out] | node_idx | Required resolved node-index destination, -1 if unresolved. |
| [out] | cd | Required stored dimensionless discharge-coefficient destination. |
| [out] | area | Required stored exchange-area destination in current mesh length units squared. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| 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.
| [out] | buf | Required writable tag 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] | idx | Zero-based cell index in [0, cell_count); includes triangles and quadrilaterals. |
| 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).
Units follow the MESH: mesh length units squared as authored (ft² for a US-FLOW_UNITS project unless the mesh file declares ;; UNITS: SI (m)), converted to m² in place by swmm_engine_initialize() together with the vertex coordinates. Before initialize the value is therefore in mesh (project) units; after it, m².
| [out] | area | Required destination for the stored exchange area in current mesh length units squared. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| [in] | vertex_idx | Zero-based vertex index in [0, vertex_count). |
| 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).
| [out] | cd | Required destination for the stored dimensionless discharge coefficient. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| [in] | vertex_idx | Zero-based vertex index in [0, vertex_count). |
| 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.
| [out] | buf | Required writable tag 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] | idx | Zero-based vertex index in [0, vertex_count). |
| SWMM_ENGINE_API int swmm_2d_is_active | ( | SWMM_Engine | engine, |
| int * | active ) |
Check whether the 2D module is active for this simulation.
| [out] | active | Required result slot, 1 for an active surface router or 0 otherwise. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| SWMM_ENGINE_API int swmm_2d_prepare_for_edit | ( | SWMM_Engine | engine | ) |
Make the parsed 2D mesh editable without a full initialize().
The mesh-edit/query setters work as soon as the mesh is parsed (OPENED state) — they do not require the solver to be initialized. Per-edge BC and conveyance edits additionally need the authored [2D_BOUNDARY_CONDITIONS] / [2D_EDGE_CONVEYANCE] rows drained into live storage first; call this once before editing those so the changes take effect and are written on save. No-op when already initialized/drained; a missing mesh is refused.
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| SWMM_ENGINE_API int swmm_2d_quad_count | ( | SWMM_Engine | engine, |
| int * | count ) |
Number of quadrilateral cells (0 for an all-triangle mesh).
| [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. |
| SWMM_ENGINE_API int swmm_2d_reset_edge_conveyance | ( | SWMM_Engine | engine | ) |
Reset every edge's conveyance factor to 1.0 (unrestricted).
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| SWMM_ENGINE_API int swmm_2d_set_dry_depth | ( | SWMM_Engine | engine, |
| double | dry_depth ) |
Set the dry depth threshold (m).
| [in] | dry_depth | Dry-depth threshold in m; this low-level setter does not validate range or finiteness. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| 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).
| [in] | head | Finite new stage elevation in current boundary/mesh length units, metres after initialization. |
| [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. |
| 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.
| [in] | slope | Finite new dimensionless nonnegative bed slope. |
| [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. |
| SWMM_ENGINE_API int swmm_2d_set_edge_bc_tseries_name | ( | SWMM_Engine | engine, |
| int | tri_idx, | ||
| int | edge, | ||
| const char * | name ) |
Set the timeseries NAME to drive a SPECIFIED_STAGE edge.
V-E2. Stores the name verbatim; the engine resolves it into a table index from SimulationContext::tables on the next forcing-step lookup (until then edge_bc_tseries[idx] is -2). Empty name clears the slot (back to constant edge_bc_head).
| [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. |
| 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.
| [in] | bc_type | New SWMM_2D_BC_* code. |
| [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. |
| SWMM_ENGINE_API int swmm_2d_set_edge_conveyance | ( | SWMM_Engine | engine, |
| int | tri, | ||
| int | edge, | ||
| double | conveyance ) |
Set the per-edge conveyance factor for one edge.
The value is rejected if outside [0, 1] (SWMM_ERR_BADPARAM). When the edge is interior (has a neighbour) the value is mirrored to the partner slot on the neighbour triangle so antisymmetry is preserved.
| [in] | conveyance | Finite factor in [0,1]; interior partner edge receives the same value. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| [in] | tri | 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. |
| 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).
| [in] | d | Nonnegative initial depth in current mesh length units; only initialization applies it to runtime depth. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| [in] | idx | Zero-based cell index in [0, cell_count); includes triangles and quadrilaterals. |
| 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.
| [in] | u | Finite initial velocity component in m/s SI. |
| [in] | v | Finite initial velocity component in m/s SI. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| [in] | idx | Zero-based cell index in [0, cell_count); includes triangles and quadrilaterals. |
| SWMM_ENGINE_API int swmm_2d_set_triangle_mannings | ( | SWMM_Engine | engine, |
| int | idx, | ||
| double | n ) |
Set triangle Manning's roughness coefficient.
Rejected if not strictly positive (SWMM_ERR_BADPARAM). Persists in the MANNINGS_N column of [2D_TRIANGLES] on save.
| [in] | n | Strictly positive Manning roughness, s/m^(1/3). |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| [in] | idx | Zero-based cell index in [0, cell_count); includes triangles and quadrilaterals. |
| 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.
| [in] | tag | Optional copied null-terminated descriptive tag; NULL or empty clears it. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| [in] | idx | Zero-based cell index in [0, cell_count); includes triangles and quadrilaterals. |
| SWMM_ENGINE_API int swmm_2d_set_vertex_coupled_node | ( | SWMM_Engine | engine, |
| int | vertex_idx, | ||
| const char * | node_name ) |
Set (or clear) the SWMM node a vertex is coupled to, by name.
Stores the node NAME verbatim and resolves it to an index against the current model (-1 when not found, mirroring the deferred-resolution rule in SurfaceRouter2D::initialize). An empty / NULL name clears the coupling (name cleared, index set to -1). An assigned nonempty name preserves existing discharge coefficient and exchange area; clearing the row restores defaults 0.65 / 1.0 and clears their authored flags. The .inp writer emits the name in [2D_VERTEX_NODE_MAP], so this is what persists an interactive coupling edit on save.
| [in] | node_name | Optional copied node name; NULL or empty clears the row and restores default CD/AREA. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| [in] | vertex_idx | Zero-based vertex index in [0, vertex_count). |
| 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).
| [in] | area | Strictly positive exchange area in current mesh length units squared. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| [in] | vertex_idx | Zero-based vertex index in [0, vertex_count). |
| 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.
| [in] | cd | Strictly positive dimensionless discharge coefficient. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| [in] | vertex_idx | Zero-based vertex index in [0, vertex_count). |
| 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.
| [in] | tag | Optional copied null-terminated descriptive tag; NULL or empty clears it. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| [in] | idx | Zero-based vertex index in [0, vertex_count). |
| SWMM_ENGINE_API int swmm_2d_set_vertex_z | ( | SWMM_Engine | engine, |
| int | idx, | ||
| double | z ) |
Set vertex Z (ground elevation).
Updates vz[idx] and recomputes the dependent geometry for every triangle incident to this vertex: tri_cz (centroid Z = mean of vertex Zs) and edge_mz (per-edge midpoint Z) so the solver's bed-elevation references stay consistent on the next step. XY-derived fields (tri_area, tri_cx, tri_cy, edge_length, edge_nx, edge_ny, edge_mx, edge_my) are unaffected.
When called while the engine is RUNNING, the solver state (head, depth) is intentionally not rewritten — head remains the value the solver is integrating; the geometric difference head - bed changes, while the stored depth remains untouched until subsequent solver processing.
| [in] | idx | Zero-based vertex index in [0, vertex_count). |
| [in] | z | Ground elevation in current mesh length units; no finite/range validation is performed. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| 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.
Equivalent to calling swmm_2d_set_vertex_z for each vertex in turn — the dependent geometry (tri_cz, edge_mz) ends up bitwise identical — but the scalar setter rescans all triangles on every call, so doing that per vertex is O(nVertices x nTriangles). This writes all Zs first and recomputes the dependent geometry in a single pass, i.e. O(nVertices + nTriangles). On a million-cell mesh that is the difference between minutes and milliseconds, which is why editors that rewrite a whole mesh should prefer it.
XY-derived fields (tri_area, tri_cx, tri_cy, edge_length, edge_nx, edge_ny, edge_mx, edge_my) are unaffected.
When called while the engine is RUNNING, the solver state (head, depth) is intentionally not rewritten — head remains the value the solver is integrating; the geometric difference head - bed changes, while the stored depth remains untouched until subsequent solver processing.
| [in] | z | Required readable vertex_count-double elevation array in current mesh length units. |
| [in] | count | Exactly vertex_count; a different count returns SWMM_ERR_BADPARAM. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| 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.
| [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. |
| SWMM_ENGINE_API int swmm_2d_species_name | ( | SWMM_Engine | engine, |
| int | species, | ||
| char * | buf, | ||
| int | buflen ) |
One surface species row's name.
| [in] | species | Zero-based active transported species row. |
| [out] | buf | Required writable 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. |
| SWMM_ENGINE_API int swmm_2d_triangle_count | ( | SWMM_Engine | engine, |
| int * | count ) |
Get the number of mesh triangles.
| [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. |
| SWMM_ENGINE_API int swmm_2d_triangle_coupling_count | ( | SWMM_Engine | engine, |
| int * | count ) |
Get the number of triangle-to-node coupling points.
| [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. |
| SWMM_ENGINE_API int swmm_2d_triangle_coupling_rows | ( | SWMM_Engine | engine, |
| int * | count ) |
Number of authored node→cell coupling rows.
| [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. |
| SWMM_ENGINE_API int swmm_2d_triangle_get_area | ( | SWMM_Engine | engine, |
| int | idx, | ||
| double * | area ) |
Get triangle area.
| [out] | area | Required area destination in m2; active runtime geometry has been converted to SI. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| [in] | idx | Zero-based cell index in [0, cell_count); includes triangles and quadrilaterals. |
| SWMM_ENGINE_API int swmm_2d_triangle_get_centroid | ( | SWMM_Engine | engine, |
| int | idx, | ||
| double * | cx, | ||
| double * | cy, | ||
| double * | cz ) |
Get triangle centroid coordinates.
| [out] | cx | Required centroid-coordinate destination in metres SI. |
| [out] | cy | Required centroid-coordinate destination in metres SI. |
| [out] | cz | Required centroid-coordinate destination in metres SI. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| [in] | idx | Zero-based cell index in [0, cell_count); includes triangles and quadrilaterals. |
| 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.
| [out] | node_idx | Required resolved zero-based node index; -1 means uncoupled or unresolved. |
| [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. |
| 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.
| [out] | d | Required initial-depth destination in current mesh length units. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| [in] | idx | Zero-based cell index in [0, cell_count); includes triangles and quadrilaterals. |
| 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).
| [out] | u | Required velocity destination in m/s SI. |
| [out] | v | Required velocity destination in m/s SI. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| [in] | idx | Zero-based cell index in [0, cell_count); includes triangles and quadrilaterals. |
| SWMM_ENGINE_API int swmm_2d_triangle_get_mannings | ( | SWMM_Engine | engine, |
| int | idx, | ||
| double * | n ) |
Get triangle Manning's roughness.
| [out] | n | Required Manning roughness destination, s/m^(1/3). |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| [in] | idx | Zero-based cell index in [0, cell_count); includes triangles and quadrilaterals. |
| 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).
| [out] | n0 | Required adjacent-cell destination across the corresponding local edge; -1 means exterior. |
| [out] | n1 | Required adjacent-cell destination across the corresponding local edge; -1 means exterior. |
| [out] | n2 | Required adjacent-cell destination across the corresponding local edge; -1 means exterior. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| [in] | idx | Zero-based cell index in [0, cell_count); includes triangles and quadrilaterals. |
| 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).
| [out] | v0 | Required zero-based connectivity index destination. |
| [out] | v1 | Required zero-based connectivity index destination. |
| [out] | v2 | Required zero-based connectivity index destination. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| [in] | idx | Zero-based cell index in [0, cell_count); includes triangles and quadrilaterals. |
| SWMM_ENGINE_API int swmm_2d_vertex_count | ( | SWMM_Engine | engine, |
| int * | count ) |
Get the number of mesh vertices.
| [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. |
| SWMM_ENGINE_API int swmm_2d_vertex_coupling_count | ( | SWMM_Engine | engine, |
| int * | count ) |
Get the number of vertex-to-node coupling points.
| [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. |
| 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.
| [out] | node_idx | Required resolved zero-based node index; -1 means uncoupled or unresolved. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| [in] | vertex_idx | Zero-based vertex index in [0, vertex_count). |
| SWMM_ENGINE_API int swmm_2d_vertex_get_head | ( | SWMM_Engine | engine, |
| int | idx, | ||
| double * | head ) |
Get reconstructed head at a vertex.
| [in] | idx | Zero-based vertex index in [0, vertex_count). |
| [out] | head | Required destination for reconstructed vertex head in m. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| SWMM_ENGINE_API int swmm_2d_vertex_get_heads_bulk | ( | SWMM_Engine | engine, |
| double * | heads ) |
Bulk get reconstructed heads at all vertices.
| [out] | heads | Required caller-owned vertex_count-double array receiving reconstructed vertex head in m. No capacity is passed or checked. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| 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.
The wet-masked, depth-weighted free-surface reconstruction eta_v - z_v: dry-cell bed elevations never contribute (unlike the vertex heads above, which are the solver field with dry-cell head = bed elevation). Negative over the dry side of partially wet cells (sub-cell shoreline intercept), 0 where no incident cell is wet. This is the field GUIs should interpolate for water-surface rendering and profiles.
| [out] | depths | Required caller-owned vertex_count-double array receiving signed render depth in m. No capacity is passed or checked. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| SWMM_ENGINE_API int swmm_2d_vertex_get_xyz | ( | SWMM_Engine | engine, |
| int | idx, | ||
| double * | x, | ||
| double * | y, | ||
| double * | z ) |
Get vertex coordinates.
| [out] | x | Required coordinate destination in the current mesh length units (metres after initialization). |
| [out] | y | Required coordinate destination in the current mesh length units (metres after initialization). |
| [out] | z | Required coordinate destination in the current mesh length units (metres after initialization). |
| [in] | idx | Zero-based vertex index in [0, vertex_count). |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| SWMM_ENGINE_API int swmm_2d_vertex_get_xyz_bulk | ( | SWMM_Engine | engine, |
| double * | x, | ||
| double * | y, | ||
| double * | z ) |
Bulk get vertex coordinates.
| [out] | x | Required vertex_count-element array in the current mesh length units (metres after initialization). |
| [out] | y | Required vertex_count-element array in the current mesh length units (metres after initialization). |
| [out] | z | Required vertex_count-element array in the current mesh length units (metres after initialization). |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| 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).
| [in] | node_idx | Zero-based existing node index; a surface mesh is not required. |
| [out] | type | Required SWMM_NodeCoupling2DType destination. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| 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.
| [in] | node_idx | Zero-based existing node index; a surface mesh is not required. |
| [in] | key | Required null-terminated coupling section key from the list above. |
| [out] | value | Required writable token buffer, safely truncated with NUL. |
| [in] | value_len | Positive byte capacity including NUL. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| 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.
| [in] | node_idx | Zero-based existing node index; a surface mesh is not required. |
| [out] | type | Required SWMM_NodeCoupling2DType destination. |
| [out] | authored | Optional 0/1 row-provenance destination. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| 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).
| [in] | node_idx | Zero-based existing node index; a surface mesh is not required. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| 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.
| [in] | node_idx | Zero-based existing node index; a surface mesh is not required. |
| [in] | key | Required null-terminated coupling section key from the list above. |
| [in] | value | Copied section token in project units; NULL or empty clears this parameter. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
| 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.
| [in] | node_idx | Zero-based existing node index; a surface mesh is not required. |
| [in] | type | SWMM_NodeCoupling2DType legal for this node class. |
| [in] | engine | Borrowed live engine handle; all caller storage remains caller-owned. Serialize calls with stepping and other engine edits. |
1.13.2