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

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_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 */