openswmm_2d.h

Go to the documentation of this file.

// SPDX-License-Identifier: Apache-2.0
//
// Copyright 2026 Caleb Buahin
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.


 
#ifndef OPENSWMM_2D_H
#define OPENSWMM_2D_H
 
#include "openswmm_callbacks.h"
 
#ifdef OPENSWMM_ENGINE_STATIC
#define SWMM_ENGINE_API
#else
#ifdef _WIN32
#ifdef openswmm_engine_EXPORTS
#define SWMM_ENGINE_API __declspec(dllexport)
#else
#define SWMM_ENGINE_API __declspec(dllimport)
#endif
#else
#define SWMM_ENGINE_API __attribute__((visibility("default")))
#endif
#endif
 
#ifdef __cplusplus
extern "C" {
#endif
 
/* =========================================================================
 * 2D Module Status
 * ========================================================================= */

SWMM_ENGINE_API int swmm_2d_is_active(SWMM_Engine engine, int* active);

SWMM_ENGINE_API int swmm_2d_set_auto_backend_cpu(SWMM_Engine engine, int enabled);

SWMM_ENGINE_API int swmm_2d_prepare_for_edit(SWMM_Engine engine);
 
/* =========================================================================
 * Mesh Geometry — Query (read-only after initialization)
 * ========================================================================= */

SWMM_ENGINE_API int swmm_2d_geometry_scale_to_si(SWMM_Engine engine, double* scale);

SWMM_ENGINE_API int swmm_2d_vertex_count(SWMM_Engine engine, int* count);

SWMM_ENGINE_API int swmm_2d_triangle_count(SWMM_Engine engine, int* count);

SWMM_ENGINE_API int swmm_2d_vertex_get_xyz(SWMM_Engine engine, int idx, double* x, double* y,
                                           double* z);

SWMM_ENGINE_API int swmm_2d_vertex_get_xyz_bulk(SWMM_Engine engine, double* x, double* y,
                                                double* z);

SWMM_ENGINE_API int swmm_2d_set_vertex_z(SWMM_Engine engine, int idx, double z);

SWMM_ENGINE_API int swmm_2d_set_vertex_z_bulk(SWMM_Engine engine, const double* z, int count);

SWMM_ENGINE_API int swmm_2d_triangle_get_vertices(SWMM_Engine engine, int idx, int* v0, int* v1,
                                                  int* v2);
 
/* -------------------------------------------------------------------------
 * Mixed triangle / quadrilateral meshes (2D_TRI_QUAD_MESH_PLAN_2026-09-06).
 *
 * A "triangle index" everywhere in this header is a CELL index: cells are
 * numbered triangles first (the [2D_TRIANGLES] rows), then quads (the
 * [2D_QUADS] rows). Every swmm_2d_triangle_* accessor that reads a per-cell
 * scalar (area, centroid, Manning, init depth/velocity, tag, coupling) works
 * on a quad too; only the two 3-slot connectivity getters refuse quads.
 * Local edge k of a cell has endpoints v[(k+1)%nv], v[(k+2)%nv].
 * ------------------------------------------------------------------------- */

SWMM_ENGINE_API int swmm_2d_cell_count(SWMM_Engine engine, int* count);

SWMM_ENGINE_API int swmm_2d_quad_count(SWMM_Engine engine, int* count);

SWMM_ENGINE_API int swmm_2d_edge_stride(SWMM_Engine engine, int* stride);

SWMM_ENGINE_API int swmm_2d_cell_vertex_count(SWMM_Engine engine, int idx, int* nv);

SWMM_ENGINE_API int swmm_2d_cell_get_vertices(SWMM_Engine engine, int idx, int* v, int* nv);

SWMM_ENGINE_API int swmm_2d_cell_get_neighbours(SWMM_Engine engine, int idx, int* n, int* nv);

SWMM_ENGINE_API int swmm_2d_triangle_get_area(SWMM_Engine engine, int idx, double* area);

SWMM_ENGINE_API int swmm_2d_triangle_get_centroid(SWMM_Engine engine, int idx, double* cx,
                                                  double* cy, double* cz);

SWMM_ENGINE_API int swmm_2d_triangle_get_mannings(SWMM_Engine engine, int idx, double* n);

SWMM_ENGINE_API int swmm_2d_set_triangle_mannings(SWMM_Engine engine, int idx, double n);

SWMM_ENGINE_API int swmm_2d_triangle_get_init_depth(SWMM_Engine engine, int idx, double* d);

SWMM_ENGINE_API int swmm_2d_set_triangle_init_depth(SWMM_Engine engine, int idx, double d);

SWMM_ENGINE_API int swmm_2d_triangle_get_init_velocity(SWMM_Engine engine, int idx, double* u,
                                                       double* v);

SWMM_ENGINE_API int swmm_2d_set_triangle_init_velocity(SWMM_Engine engine, int idx, double u,
                                                       double v);

SWMM_ENGINE_API int swmm_2d_set_vertex_tag(SWMM_Engine engine, int idx, const char* tag);

SWMM_ENGINE_API int swmm_2d_set_triangle_tag(SWMM_Engine engine, int idx, const char* tag);

SWMM_ENGINE_API int swmm_2d_get_vertex_tag(SWMM_Engine engine, int idx, char* buf, int buflen);

SWMM_ENGINE_API int swmm_2d_get_triangle_tag(SWMM_Engine engine, int idx, char* buf, int buflen);

SWMM_ENGINE_API int swmm_2d_triangle_get_neighbours(SWMM_Engine engine, int idx, int* n0, int* n1,
                                                    int* n2);

SWMM_ENGINE_API int swmm_2d_edge_get_geometry_bulk(SWMM_Engine engine, double* length, double* nx,
                                                   double* ny);
 
/* =========================================================================
 * Coupling Map — Query
 * ========================================================================= */

SWMM_ENGINE_API int swmm_2d_vertex_coupling_count(SWMM_Engine engine, int* count);

SWMM_ENGINE_API int swmm_2d_triangle_coupling_count(SWMM_Engine engine, int* count);

SWMM_ENGINE_API int swmm_2d_vertex_get_coupled_node(SWMM_Engine engine, int vertex_idx,
                                                    int* node_idx);

SWMM_ENGINE_API int swmm_2d_triangle_get_coupled_node(SWMM_Engine engine, int tri_idx,
                                                      int* node_idx);

SWMM_ENGINE_API int swmm_2d_set_vertex_coupled_node(SWMM_Engine engine, int vertex_idx,
                                                    const char* node_name);

SWMM_ENGINE_API int swmm_2d_add_triangle_coupling(SWMM_Engine engine, int tri_idx,
                                                  const char* node_name, double cd, double area);

SWMM_ENGINE_API int swmm_2d_clear_triangle_couplings(SWMM_Engine engine);

SWMM_ENGINE_API int swmm_2d_triangle_coupling_rows(SWMM_Engine engine, int* count);

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

SWMM_ENGINE_API int swmm_2d_get_vertex_coupling_cd(SWMM_Engine engine, int vertex_idx, double* cd);

SWMM_ENGINE_API int swmm_2d_set_vertex_coupling_cd(SWMM_Engine engine, int vertex_idx, double cd);

SWMM_ENGINE_API int swmm_2d_get_vertex_coupling_area(SWMM_Engine engine, int vertex_idx,
                                                     double* area);

SWMM_ENGINE_API int swmm_2d_set_vertex_coupling_area(SWMM_Engine engine, int vertex_idx,
                                                     double area);
 
/* =========================================================================
 * 2D State — Per-Triangle (read during RUNNING)
 * ========================================================================= */

SWMM_ENGINE_API int swmm_2d_get_depth(SWMM_Engine engine, int idx, double* depth);

SWMM_ENGINE_API int swmm_2d_get_head(SWMM_Engine engine, int idx, double* head);

SWMM_ENGINE_API int swmm_2d_get_coupling_flux(SWMM_Engine engine, int idx, double* flux);

SWMM_ENGINE_API int swmm_2d_get_rainfall(SWMM_Engine engine, int idx, double* rainfall);

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

SWMM_ENGINE_API int swmm_2d_get_net_source(SWMM_Engine engine, int idx, double* net_source);

SWMM_ENGINE_API int swmm_2d_get_depths_bulk(SWMM_Engine engine, double* depths);

SWMM_ENGINE_API int swmm_2d_get_heads_bulk(SWMM_Engine engine, double* heads);

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

SWMM_ENGINE_API int swmm_2d_get_coupling_fluxes_bulk(SWMM_Engine engine, double* fluxes);

SWMM_ENGINE_API int swmm_2d_get_rainfall_bulk(SWMM_Engine engine, double* rainfall);

SWMM_ENGINE_API int swmm_2d_get_report_rainfall_bulk(SWMM_Engine engine, double report_date,
                                                     double* rainfall);

SWMM_ENGINE_API int swmm_2d_get_rain_volume_bulk(SWMM_Engine engine, double* volumes);

SWMM_ENGINE_API int swmm_2d_get_coupling_volume_bulk(SWMM_Engine engine, double* volumes);

SWMM_ENGINE_API int swmm_2d_get_edge_flux_bulk(SWMM_Engine engine, double* flux);
 
/* ---- Overland transport results (read-only during RUNNING) -------------- */

SWMM_ENGINE_API int swmm_2d_species_count(SWMM_Engine engine, int* count);

SWMM_ENGINE_API int swmm_2d_species_name(SWMM_Engine engine, int species, char* buf, int buflen);

SWMM_ENGINE_API int swmm_2d_get_cell_conc(SWMM_Engine engine, int species, double* out, int len,
                                          int* written);
 
/* =========================================================================
 * 2D Edge Conveyance (§11A of docs/2dModelStrategy.md)
 *
 * Per-edge multiplicative factor in [0, 1] that attenuates the
 * diffusion-wave flux across the edge (default 1.0 = unrestricted, 0.0 =
 * wall). Public storage is `[cell * edge_stride + edge_local]`.  Interior edges
 * are symmetric: setting the value on one slot mirrors to the partner
 * slot on the neighbour triangle so mass conservation is preserved.
 *
 * Safe to call between routing steps. Calling during a routing step is
 * undefined — the 2D sub-stepper holds a const reference to the mesh.
 * ========================================================================= */

SWMM_ENGINE_API int swmm_2d_get_edge_conveyance(SWMM_Engine engine, int tri, int edge,
                                                double* conveyance);

SWMM_ENGINE_API int swmm_2d_set_edge_conveyance(SWMM_Engine engine, int tri, int edge,
                                                double conveyance);

SWMM_ENGINE_API int swmm_2d_get_edge_conveyance_bulk(SWMM_Engine engine, double* conveyance);

SWMM_ENGINE_API int swmm_2d_reset_edge_conveyance(SWMM_Engine engine);
 
/* =========================================================================
 * 2D State — Per-Vertex (reconstructed heads)
 * ========================================================================= */

SWMM_ENGINE_API int swmm_2d_vertex_get_head(SWMM_Engine engine, int idx, double* head);

SWMM_ENGINE_API int swmm_2d_vertex_get_heads_bulk(SWMM_Engine engine, double* heads);

SWMM_ENGINE_API int swmm_2d_vertex_get_render_depths_bulk(SWMM_Engine engine, double* depths);
 
/* =========================================================================
 * 2D Solver Statistics
 * ========================================================================= */

SWMM_ENGINE_API int swmm_2d_get_max_depth(SWMM_Engine engine, double* max_depth);

SWMM_ENGINE_API int swmm_2d_get_total_volume(SWMM_Engine engine, double* volume);

SWMM_ENGINE_API int swmm_2d_get_total_exchange_flow(SWMM_Engine engine, double* flow);

SWMM_ENGINE_API int swmm_2d_get_solver_steps(SWMM_Engine engine, long* steps);

SWMM_ENGINE_API int swmm_2d_get_solver_last_step(SWMM_Engine engine, double* h_last);

typedef struct SWMM_2DRunStats {
    char backend[64];       
    int momentum;           
    int lts_tiers;          
    long steps;             
    long face_evals;        
    double last_step;       
    double active_frac_min; 
    double active_frac_mean;
    double active_frac_max;
    int n_tiers;        
    long tier_cells[8]; 
} SWMM_2DRunStats;

SWMM_ENGINE_API int swmm_2d_get_run_stats(SWMM_Engine engine, SWMM_2DRunStats* stats);

SWMM_ENGINE_API int swmm_2d_get_stat_max_depths(SWMM_Engine engine, double* max_depths);

SWMM_ENGINE_API int swmm_2d_get_stat_max_velocities(SWMM_Engine engine, double* max_velocities);

SWMM_ENGINE_API int swmm_2d_get_stat_max_continuity_err(SWMM_Engine engine, double* max_errs);

SWMM_ENGINE_API int swmm_2d_get_continuity_error(SWMM_Engine engine, double* err);

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);
 
/* =========================================================================
 * 2D Forcing — Override rainfall or coupling for external control
 * ========================================================================= */

SWMM_ENGINE_API int swmm_2d_force_rainfall(SWMM_Engine engine, int idx, double value, int mode,
                                           int persist);

SWMM_ENGINE_API int swmm_2d_force_rainfall_uniform(SWMM_Engine engine, double value, int mode,
                                                   int persist);

SWMM_ENGINE_API int swmm_2d_force_evap(SWMM_Engine engine, int idx, double value, int mode,
                                       int persist);

SWMM_ENGINE_API int swmm_2d_force_evap_uniform(SWMM_Engine engine, double value, int mode,
                                               int persist);

SWMM_ENGINE_API int swmm_2d_force_coupling_flux(SWMM_Engine engine, int idx, double value, int mode,
                                                int persist);

SWMM_ENGINE_API int swmm_2d_force_clear_all(SWMM_Engine engine);
 
/* =========================================================================
 * 2D Solver Options — Query/Modify (valid after INITIALIZED)
 * ========================================================================= */

SWMM_ENGINE_API int swmm_2d_get_dry_depth(SWMM_Engine engine, double* dry_depth);

SWMM_ENGINE_API int swmm_2d_set_dry_depth(SWMM_Engine engine, double dry_depth);
 
/* =========================================================================
 * 2D Boundary Conditions
 * ========================================================================= */

#define SWMM_2D_BC_WALL 0
#define SWMM_2D_BC_NORMAL_FLOW 1
#define SWMM_2D_BC_SPECIFIED_STAGE 2
#define SWMM_2D_BC_SPECIFIED_FLOW 3 
#define SWMM_2D_BC_RATING_CURVE 4   

SWMM_ENGINE_API int swmm_2d_boundary_edge_count(SWMM_Engine engine, int* count);

SWMM_ENGINE_API int swmm_2d_get_edge_bc_type(SWMM_Engine engine, int tri_idx, int edge,
                                             int* bc_type);

SWMM_ENGINE_API int swmm_2d_set_edge_bc_concentrations(SWMM_Engine engine, int cell, int edge,
                                                       const double* values, int species_count);
SWMM_ENGINE_API int swmm_2d_clear_edge_bc(SWMM_Engine engine, int cell, int edge);
 
/* -------------------------------------------------------------------------
 * Authored [2D_INITIAL_QUALITY] and [2D_BOUNDARY_QUALITY] rows
 * (closed C-API gaps 2026-10-11)
 *
 * The rows the deck spells, resolved against the mesh, tags and species at
 * swmm_engine_initialize() and written back on save. Editable while BUILDING
 * or OPENED (SWMM_ERR_LIFECYCLE afterwards); concentrations are in species
 * units, finite and >= 0, as the parser requires. Cell indices are 0-based
 * here (the deck's CELL rows are 1-based). A set with the same key as an
 * existing row replaces it.
 * ------------------------------------------------------------------------- */
 
#define SWMM_2D_QUAL_SCOPE_GLOBAL 0 
#define SWMM_2D_QUAL_SCOPE_TAG 1    
#define SWMM_2D_QUAL_SCOPE_CELL 2   

SWMM_ENGINE_API int swmm_2d_initial_quality_count(SWMM_Engine engine, int* count);

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

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

SWMM_ENGINE_API int swmm_2d_remove_initial_quality(SWMM_Engine engine, int index);
 
/* Authored [2D_INITIAL_BED_QUALITY] rows seed finite LOCAL_STORAGE bed
 * porewater. Scope constants and lifecycle match [2D_INITIAL_QUALITY]. */
SWMM_ENGINE_API int swmm_2d_initial_bed_quality_count(SWMM_Engine engine, int* count);
SWMM_ENGINE_API int swmm_2d_get_initial_bed_quality(SWMM_Engine engine, int index, int* scope,
                                                    char* tag, int tag_len, int* cell,
                                                    char* species, int species_len, double* conc);
SWMM_ENGINE_API int swmm_2d_set_initial_bed_quality(SWMM_Engine engine, int scope, const char* tag,
                                                    int cell, const char* species, double conc);
SWMM_ENGINE_API int swmm_2d_remove_initial_bed_quality(SWMM_Engine engine, int index);

SWMM_ENGINE_API int swmm_2d_boundary_quality_count(SWMM_Engine engine, int* count);

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

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

SWMM_ENGINE_API int swmm_2d_remove_boundary_quality(SWMM_Engine engine, int index);

SWMM_ENGINE_API int swmm_2d_set_edge_bc_type(SWMM_Engine engine, int tri_idx, int edge,
                                             int bc_type);

SWMM_ENGINE_API int swmm_2d_get_edge_bc_head(SWMM_Engine engine, int tri_idx, int edge,
                                             double* head);

SWMM_ENGINE_API int swmm_2d_set_edge_bc_head(SWMM_Engine engine, int tri_idx, int edge,
                                             double head);

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

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

SWMM_ENGINE_API int swmm_2d_get_edge_bc_slope(SWMM_Engine engine, int tri_idx, int edge,
                                              double* slope);

SWMM_ENGINE_API int swmm_2d_set_edge_bc_slope(SWMM_Engine engine, int tri_idx, int edge,
                                              double slope);

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

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

SWMM_ENGINE_API int swmm_2d_get_edge_bc_flow(SWMM_Engine engine, int tri_idx, int edge,
                                             double* flow);

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

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

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

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

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

SWMM_ENGINE_API int swmm_2d_get_edge_bc_cum_flux(SWMM_Engine engine, int tri_idx, int edge,
                                                 double* cum_flux);
 
/* =========================================================================
 * Results-file variable selection ([2D_OPTIONS] REPORT_2D_VARIABLES)
 * =========================================================================
 * Engine-independent helpers so a host can build a checklist without
 * re-implementing the token vocabulary. Tokens are listed in bit order; the
 * presets DEFAULT / MINIMAL / ALL map to masks. Use swmm_options_get_ext /
 * swmm_options_set_ext with key "REPORT_2D_VARIABLES" to read/write a model.
 */

SWMM_ENGINE_API int swmm_2d_output_variable_count(void);
SWMM_ENGINE_API const char* swmm_2d_output_variable_name(int i);
SWMM_ENGINE_API unsigned swmm_2d_output_variable_mask(const char* text);
SWMM_ENGINE_API const char* swmm_2d_output_variable_text(unsigned mask);
 
/* =========================================================================
 * Per-node 1D↔2D coupling type ([2D_NODE_COUPLING])
 * =========================================================================
 * A node attribute of the 1D model, held with or without a mesh: whether a
 * node may couple to the 2D surface and through what structure. Map rows
 * ([2D_VERTEX_NODE_MAP] / [2D_TRIANGLE_NODE_MAP]) naming a NONE node are
 * ignored at initialize. A node without an authored row takes its class
 * default: junction or divider → MANHOLE, storage → OPEN, outfall → OUTFALL,
 * inlet or virtual junction → NONE. OUTFALL is legal only on outfalls (an
 * outfall is OUTFALL or NONE); OPEN only on storage nodes. Setters work in
 * the BUILDING and OPENED states.
 */

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

SWMM_ENGINE_API int swmm_node_get_2d_coupling_type(SWMM_Engine engine, int node_idx, int* type,
                                                   int* authored);

SWMM_ENGINE_API int swmm_node_get_2d_coupling_default_type(SWMM_Engine engine, int node_idx,
                                                           int* type);

SWMM_ENGINE_API int swmm_node_set_2d_coupling_type(SWMM_Engine engine, int node_idx, int type);

SWMM_ENGINE_API int swmm_node_reset_2d_coupling(SWMM_Engine engine, int node_idx);

SWMM_ENGINE_API int swmm_node_get_2d_coupling_param(SWMM_Engine engine, int node_idx,
                                                    const char* key, char* value, int value_len);

SWMM_ENGINE_API int swmm_node_set_2d_coupling_param(SWMM_Engine engine, int node_idx,
                                                    const char* key, const char* value);
 
#ifdef __cplusplus
} /* extern "C" */
#endif
 
#endif /* OPENSWMM_2D_H */