openswmm_infrastructure.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_INFRASTRUCTURE_H
#define OPENSWMM_INFRASTRUCTURE_H
 
#include "openswmm_engine.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
/* =========================================================================
 * Transects
 * ========================================================================= */

SWMM_ENGINE_API int swmm_transect_add(SWMM_Engine engine, const char* id);

SWMM_ENGINE_API int swmm_transect_set_roughness(SWMM_Engine engine, int idx, double n_left,
                                                double n_right, double n_channel);

SWMM_ENGINE_API int swmm_transect_add_station(SWMM_Engine engine, int idx, double station,
                                              double elevation);

SWMM_ENGINE_API int swmm_transect_count(SWMM_Engine engine);

SWMM_ENGINE_API int swmm_transect_index(SWMM_Engine engine, const char* id);

SWMM_ENGINE_API const char* swmm_transect_id(SWMM_Engine engine, int idx);
 
/* -------------------------------------------------------------------------
 * Per-field getters / setters (DA-ENG-09 + BQ-TR-02)
 *
 * GUI editors (Slice BQ Phase 6.7.4 TransectEditor) need round-trip access
 * to every transect field; the legacy 3-function surface (add / set_roughness
 * / add_station) only covers a fraction. The functions below close that gap.
 * ------------------------------------------------------------------------- */

SWMM_ENGINE_API int swmm_transect_get_roughness(SWMM_Engine engine, int idx, double* n_left,
                                                double* n_right, double* n_channel);

SWMM_ENGINE_API int swmm_transect_set_bank_stations(SWMM_Engine engine, int idx, double x_left,
                                                    double x_right);

SWMM_ENGINE_API int swmm_transect_get_bank_stations(SWMM_Engine engine, int idx, double* x_left,
                                                    double* x_right);

SWMM_ENGINE_API int swmm_transect_set_encroachment_stations(SWMM_Engine engine, int idx,
                                                            double x_left, double x_right);

SWMM_ENGINE_API int swmm_transect_get_encroachment_stations(SWMM_Engine engine, int idx,
                                                            double* x_left, double* x_right);

SWMM_ENGINE_API int swmm_transect_set_modifiers(SWMM_Engine engine, int idx, double x_factor,
                                                double y_factor, double length_factor);

SWMM_ENGINE_API int swmm_transect_get_modifiers(SWMM_Engine engine, int idx, double* x_factor,
                                                double* y_factor, double* length_factor);

SWMM_ENGINE_API int swmm_transect_set_comments(SWMM_Engine engine, int idx, const char* text);

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

SWMM_ENGINE_API int swmm_transect_get_station_count(SWMM_Engine engine, int idx);

SWMM_ENGINE_API int swmm_transect_get_station(SWMM_Engine engine, int idx, int station_idx,
                                              double* station, double* elevation);

SWMM_ENGINE_API int swmm_transect_clear_stations(SWMM_Engine engine, int idx);

SWMM_ENGINE_API int swmm_transect_rename(SWMM_Engine engine, int idx, const char* new_id);

SWMM_ENGINE_API int swmm_transect_remove(SWMM_Engine engine, int idx);
 
/* =========================================================================
 * Streets
 * ========================================================================= */

SWMM_ENGINE_API int swmm_street_add(SWMM_Engine engine, const char* id);

SWMM_ENGINE_API int swmm_street_rename(SWMM_Engine engine, int idx, const char* new_id);

SWMM_ENGINE_API int swmm_street_set_params(SWMM_Engine engine, int idx, double t_crown,
                                           double h_curb, double sx, double n_road,
                                           double gutter_depres, double gutter_width, int sides,
                                           double back_width, double back_slope, double back_n);

SWMM_ENGINE_API int swmm_street_count(SWMM_Engine engine);

SWMM_ENGINE_API int swmm_street_index(SWMM_Engine engine, const char* id);

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

SWMM_ENGINE_API int swmm_street_get_params(SWMM_Engine engine, int idx, double* t_crown,
                                           double* h_curb, double* sx, double* n_road,
                                           double* gutter_depres, double* gutter_width, int* sides,
                                           double* back_width, double* back_slope, double* back_n);
 
/* =========================================================================
 * Inlets
 * ========================================================================= */

SWMM_ENGINE_API int swmm_inlet_add(SWMM_Engine engine, const char* id, const char* type);

SWMM_ENGINE_API int swmm_inlet_rename(SWMM_Engine engine, int idx, const char* new_id);

SWMM_ENGINE_API int swmm_inlet_set_params(SWMM_Engine engine, int idx, double length, double width,
                                          const char* grate_type, double open_area,
                                          double splash_veloc);

SWMM_ENGINE_API int swmm_inlet_count(SWMM_Engine engine);

SWMM_ENGINE_API int swmm_inlet_index(SWMM_Engine engine, const char* id);

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

SWMM_ENGINE_API int swmm_inlet_get_params(SWMM_Engine engine, int idx, double* length,
                                          double* width, char* grate_type, int grate_buflen,
                                          double* open_area, double* splash_veloc);

SWMM_ENGINE_API int swmm_inlet_get_type(SWMM_Engine engine, int idx, char* buf, int buflen);
 
/* -------------------------------------------------------------------------
 * Full inlet-design surface (2026-09-05). swmm_inlet_set_params/get_params
 * above remain as a GRATE/SLOTTED convenience; the struct API below covers
 * every field of the [INLETS] grammar including curb height, throat angle,
 * combination inlets and custom capture curves.
 * ------------------------------------------------------------------------- */

enum SWMM_InletType {
    SWMM_INLET_GRATE = 0,
    SWMM_INLET_CURB = 1,
    SWMM_INLET_COMBO = 2,
    SWMM_INLET_SLOTTED = 3,
    SWMM_INLET_DROP_GRATE = 4,
    SWMM_INLET_DROP_CURB = 5,
    SWMM_INLET_CUSTOM = 6
};

enum SWMM_GrateType {
    SWMM_GRATE_P_BAR_50 = 0,
    SWMM_GRATE_P_BAR_50x100 = 1,
    SWMM_GRATE_P_BAR_30 = 2,
    SWMM_GRATE_CURVED_VANE = 3,
    SWMM_GRATE_TILT_BAR_45 = 4,
    SWMM_GRATE_TILT_BAR_30 = 5,
    SWMM_GRATE_RETICULINE = 6,
    SWMM_GRATE_GENERIC = 7
};

enum SWMM_ThroatType {
    SWMM_THROAT_HORIZONTAL = 0,
    SWMM_THROAT_INCLINED = 1,
    SWMM_THROAT_VERTICAL = 2
};

enum SWMM_InletCurveKind {
    SWMM_INLET_CURVE_NONE = 0,
    SWMM_INLET_CURVE_DIVERSION = 1, 
    SWMM_INLET_CURVE_RATING = 2     
};

enum SWMM_InletPlacement {
    SWMM_INLET_AUTOMATIC = 0,
    SWMM_INLET_ON_GRADE = 1,
    SWMM_INLET_ON_SAG = 2
};

typedef struct SWMM_InletDesign {
    int type; 
    /* GRATE / DROP_GRATE / COMBO */
    double grate_length;
    double grate_width;
    int grate_type;      
    double open_area;    
    double splash_veloc; 
    /* CURB / DROP_CURB / COMBO */
    double curb_length;
    double curb_height;
    int throat; 
    /* SLOTTED */
    double slot_length;
    double slot_width;
    /* CUSTOM */
    char curve_id[64];
    int curve_kind; 
} SWMM_InletDesign;

SWMM_ENGINE_API int swmm_inlet_get_design(SWMM_Engine engine, int idx, SWMM_InletDesign* out);

SWMM_ENGINE_API int swmm_inlet_set_design(SWMM_Engine engine, int idx,
                                          const SWMM_InletDesign* design);

SWMM_ENGINE_API int swmm_inlet_get_comment(SWMM_Engine engine, int idx, char* buf, int buflen);
SWMM_ENGINE_API int swmm_inlet_set_comment(SWMM_Engine engine, int idx, const char* text);
 
/* -------------------------------------------------------------------------
 * Inlet usage rows — one per placement. Two host kinds:
 *   host_kind = SWMM_INLET_HOST_LINK : a conduit ([INLET_USAGE] row)
 *   host_kind = SWMM_INLET_HOST_NODE : an inlet junction ([INLET_JUNCTIONS] row)
 * ------------------------------------------------------------------------- */
 
enum SWMM_InletHostKind { SWMM_INLET_HOST_LINK = 0, SWMM_INLET_HOST_NODE = 1 };
 
typedef struct SWMM_InletUsage {
    int host_kind;        
    int host_idx;         
    int design_idx;       
    int capture_node_idx; 
    int num_inlets;       
    double pct_clogged;   
    double flow_limit;    
    double local_depress; 
    double local_width;   
    int placement;        
} SWMM_InletUsage;

SWMM_ENGINE_API int swmm_inlet_usage_count(SWMM_Engine engine);

SWMM_ENGINE_API int swmm_inlet_usage_find_link(SWMM_Engine engine, int link_idx);

SWMM_ENGINE_API int swmm_inlet_usage_find_node(SWMM_Engine engine, int node_idx);

SWMM_ENGINE_API int swmm_inlet_usage_get(SWMM_Engine engine, int usage_idx, SWMM_InletUsage* out);

SWMM_ENGINE_API int swmm_inlet_usage_set(SWMM_Engine engine, const SWMM_InletUsage* usage,
                                         int* usage_idx);

SWMM_ENGINE_API int swmm_inlet_usage_remove(SWMM_Engine engine, int usage_idx);
 
/* =========================================================================
 * LID controls
 * ========================================================================= */

SWMM_ENGINE_API int swmm_lid_add(SWMM_Engine engine, const char* id, int type);

enum SWMM_LidNodeLayerKind {
    SWMM_LID_NODE_SURFACE = 0,
    SWMM_LID_NODE_MEDIA = 1,
    SWMM_LID_NODE_AGGREGATE = 2,
    SWMM_LID_NODE_BOTTOM = 3
};
typedef struct SWMM_LidNodeLayer {
    int kind;
    double params[7];
} SWMM_LidNodeLayer;

typedef struct SWMM_LidRichardsOptions {
    int model, cells_per_layer;
    double atol, rtol, max_step;
} SWMM_LidRichardsOptions;

typedef struct SWMM_LidRichardsMaterial {
    double theta_r, alpha, n, l, specific_storage;
} SWMM_LidRichardsMaterial;

SWMM_ENGINE_API int swmm_lid_richards_options_get(SWMM_Engine engine, int control,
                                                  SWMM_LidRichardsOptions* out);
SWMM_ENGINE_API int swmm_lid_richards_material_get(SWMM_Engine engine, int control, int row,
                                                   SWMM_LidRichardsMaterial* out);
typedef struct SWMM_LidLayerTreatment {
    int layer;
    int pollutant;
    double removal_percent;
    double decay_per_day;
    const char* expression;
} SWMM_LidLayerTreatment;

SWMM_ENGINE_API int swmm_lid_node_treatment_count(SWMM_Engine engine, int control);
SWMM_ENGINE_API int swmm_lid_node_treatment_get(SWMM_Engine engine, int control, int row,
                                                SWMM_LidLayerTreatment* out);
SWMM_ENGINE_API int swmm_lid_node_configure(SWMM_Engine engine, int control,
                                            const SWMM_LidNodeLayer* layers, int count,
                                            const SWMM_LidLayerTreatment* treatment,
                                            int treatment_count);
SWMM_ENGINE_API int swmm_lid_node_configure_flow(SWMM_Engine engine, int control,
                                                 const SWMM_LidNodeLayer* layers, int count,
                                                 const SWMM_LidLayerTreatment* treatment,
                                                 int treatment_count,
                                                 const SWMM_LidRichardsOptions* options,
                                                 const SWMM_LidRichardsMaterial* material);
SWMM_ENGINE_API int swmm_lid_node_layer_count(SWMM_Engine engine, int control);
SWMM_ENGINE_API int swmm_lid_node_layer_get(SWMM_Engine engine, int control, int row,
                                            SWMM_LidNodeLayer* out);
SWMM_ENGINE_API int swmm_lid_node_layers_set(SWMM_Engine engine, int control,
                                             const SWMM_LidNodeLayer* rows, int count);
SWMM_ENGINE_API int swmm_node_get_lid(SWMM_Engine engine, int node, int* control,
                                      double* saturation);
SWMM_ENGINE_API int swmm_node_set_lid(SWMM_Engine engine, int node, int control, double saturation);
enum SWMM_LidNodeBottom {
    SWMM_LID_BOTTOM_CURRENT = 0,
    SWMM_LID_BOTTOM_SEALED = 1,
    SWMM_LID_BOTTOM_MESH_AQUIFER = 2
};

SWMM_ENGINE_API int swmm_node_get_lid_bottom(SWMM_Engine engine, int node, int* mode);
SWMM_ENGINE_API int swmm_node_set_lid_bottom(SWMM_Engine engine, int node, int mode);
SWMM_ENGINE_API int swmm_lid_node_base_area(SWMM_Engine engine, int node, double* area);
typedef struct SWMM_LidBottomState {
    int flow_model; /* 0 existing/backwater, 1 Richards */
    int cell, valid_sample;
    double contact_area_m2, surface_head_m, aquifer_head_m, aquifer_time_s;
    double down_cumulative_m3, up_cumulative_m3, net_cumulative_m3;
    double pending_down_m3, pending_up_m3, groundwater_residual_m3;
    double sample_start_s, sample_end_s, sampled_aquifer_time_s;
    double sampled_lid_head_m, sampled_aquifer_head_m;
    double requested_down_m3, requested_up_m3, reserved_down_m3, reserved_up_m3;
    double accepted_down_m3, accepted_up_m3, net_rate_m3s;
} SWMM_LidBottomState;

SWMM_ENGINE_API int swmm_lid_node_bottom_state_get(SWMM_Engine engine, int node,
                                                   SWMM_LidBottomState* out);

SWMM_ENGINE_API int swmm_lid_node_outlet_get(SWMM_Engine engine, int link, int* layer, int* top);
SWMM_ENGINE_API int swmm_lid_node_outlet_set(SWMM_Engine engine, int link, int layer, int top);
SWMM_ENGINE_API int swmm_lid_node_state_count(SWMM_Engine engine, int node);
SWMM_ENGINE_API int swmm_lid_node_state_get(SWMM_Engine engine, int node, int row, int* layer,
                                            double* bottom, double* top, double* moisture);
SWMM_ENGINE_API int swmm_lid_richards_state_get(SWMM_Engine engine, int node, int row,
                                                double* pressure, double* head, double* water);
typedef struct SWMM_LidRichardsStatistics {
    int accepted, rejected, rhs, newton;
    double min_step, balance_m3;
} SWMM_LidRichardsStatistics;

SWMM_ENGINE_API int swmm_lid_richards_statistics_get(SWMM_Engine engine, int node,
                                                     SWMM_LidRichardsStatistics* out);

SWMM_ENGINE_API int swmm_lid_rename(SWMM_Engine engine, int idx, const char* new_id);

SWMM_ENGINE_API int swmm_lid_set_surface(SWMM_Engine engine, int idx, double storage,
                                         double roughness, double slope);

SWMM_ENGINE_API int swmm_lid_set_soil(SWMM_Engine engine, int idx, double thick, double porosity,
                                      double fc, double wp, double ksat, double kslope);

SWMM_ENGINE_API int swmm_lid_set_storage(SWMM_Engine engine, int idx, double thick,
                                         double void_frac, double ksat);

SWMM_ENGINE_API int swmm_lid_set_drain(SWMM_Engine engine, int idx, double coeff, double expon,
                                       double offset);

SWMM_ENGINE_API int swmm_lid_get_removal(SWMM_Engine engine, int idx, int constituent,
                                         double* percent);
SWMM_ENGINE_API int swmm_lid_set_removal(SWMM_Engine engine, int idx, int constituent,
                                         double percent);

SWMM_ENGINE_API int swmm_lid_set_pavement(SWMM_Engine engine, int idx, double thick,
                                          double void_ratio, double frac_imperv, double ksat,
                                          double clog_factor, double regen_days);

SWMM_ENGINE_API int swmm_lid_set_drainmat(SWMM_Engine engine, int idx, double thick,
                                          double void_frac, double roughness);

SWMM_ENGINE_API int swmm_lid_count(SWMM_Engine engine);

SWMM_ENGINE_API int swmm_lid_index(SWMM_Engine engine, const char* id);

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

SWMM_ENGINE_API int swmm_lid_get_type(SWMM_Engine engine, int idx, int* type);

SWMM_ENGINE_API int swmm_lid_get_surface(SWMM_Engine engine, int idx, double* storage,
                                         double* roughness, double* slope);

SWMM_ENGINE_API int swmm_lid_get_soil(SWMM_Engine engine, int idx, double* thick, double* porosity,
                                      double* fc, double* wp, double* ksat, double* kslope);

SWMM_ENGINE_API int swmm_lid_get_storage(SWMM_Engine engine, int idx, double* thick,
                                         double* void_frac, double* ksat);

SWMM_ENGINE_API int swmm_lid_get_drain(SWMM_Engine engine, int idx, double* coeff, double* expon,
                                       double* offset);

SWMM_ENGINE_API int swmm_lid_get_pavement(SWMM_Engine engine, int idx, double* thick,
                                          double* void_ratio, double* frac_imperv, double* ksat,
                                          double* clog_factor, double* regen_days);

SWMM_ENGINE_API int swmm_lid_get_drainmat(SWMM_Engine engine, int idx, double* thick,
                                          double* void_frac, double* roughness);
 
/* =========================================================================
 * LID usage (assign LID to subcatchment)
 * ========================================================================= */

SWMM_ENGINE_API int swmm_lid_usage_add(SWMM_Engine engine, int subcatch_idx, int lid_idx,
                                       int number, double area, double width, double init_sat,
                                       double from_imperv);

SWMM_ENGINE_API int swmm_lid_usage_count(SWMM_Engine engine);

SWMM_ENGINE_API int swmm_lid_usage_get(SWMM_Engine engine, int usage_idx, int* subcatch_idx,
                                       int* lid_idx, int* number, double* area, double* width,
                                       double* init_sat, double* from_imperv, int* to_perv,
                                       double* from_perv);

SWMM_ENGINE_API int swmm_lid_usage_remove(SWMM_Engine engine, int usage_idx);
 
#ifdef __cplusplus
} /* extern "C" */
#endif
 
#endif /* OPENSWMM_INFRASTRUCTURE_H */