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_prepare_for_edit(SWMM_Engine engine);
 
/* =========================================================================
 * Mesh Geometry — Query (read-only after initialization)
 * ========================================================================= */

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_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_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_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);
 
/* =========================================================================
 * 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). Storage is flat 2D `[tri * 3 + 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_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_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);
 
#ifdef __cplusplus
} /* extern "C" */
#endif
 
#endif /* OPENSWMM_2D_H */