openswmm_links.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_LINKS_H
#define OPENSWMM_LINKS_H
 
#include "openswmm_engine.h"
 
#ifdef __cplusplus
extern "C" {
#endif

typedef enum SWMM_LinkType {
    SWMM_LINK_CONDUIT = 0, 
    SWMM_LINK_PUMP = 1,    
    SWMM_LINK_ORIFICE = 2, 
    SWMM_LINK_WEIR = 3,    
    SWMM_LINK_OUTLET = 4   
} SWMM_LinkType;

typedef enum SWMM_XSectShape {
    SWMM_XSECT_CIRCULAR = 0, 
    SWMM_XSECT_FILLED_CIRCULAR =
        1, 
    SWMM_XSECT_RECT_CLOSED =
        2, 
    SWMM_XSECT_RECT_OPEN =
        3, 
    SWMM_XSECT_TRAPEZOIDAL =
        4, 
    SWMM_XSECT_TRIANGULAR =
        5, 
    SWMM_XSECT_PARABOLIC =
        6, 
    SWMM_XSECT_POWER =
        7, 
    SWMM_XSECT_MOD_BASKET =
        8, 
    SWMM_XSECT_EGGSHAPED = 9,       
    SWMM_XSECT_HORSESHOE = 10,      
    SWMM_XSECT_GOTHIC = 11,         
    SWMM_XSECT_CATENARY = 12,       
    SWMM_XSECT_SEMIELLIPTICAL = 13, 
    SWMM_XSECT_BASKETHANDLE = 14,   
    SWMM_XSECT_SEMICIRCULAR = 15,   
    SWMM_XSECT_RECT_TRIANG =
        16, 
    SWMM_XSECT_RECT_ROUND =
        17, 
    SWMM_XSECT_HORIZ_ELLIPSE =
        18, 
    SWMM_XSECT_VERT_ELLIPSE =
        19,               
    SWMM_XSECT_ARCH = 20, 
    SWMM_XSECT_IRREGULAR = 21, 
    SWMM_XSECT_CUSTOM =
        22, 
    SWMM_XSECT_FORCE_MAIN =
        23, 
    SWMM_XSECT_STREET = 24, 
    SWMM_XSECT_DUMMY = 25   
} SWMM_XSectShape;
 
/* =========================================================================
 * Identity
 * ========================================================================= */

SWMM_ENGINE_API int swmm_link_count(SWMM_Engine engine);

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

SWMM_ENGINE_API const char* swmm_link_id(SWMM_Engine engine, int idx);
 
/* =========================================================================
 * Creation (BUILDING or OPENED — "editable" states)
 * ========================================================================= */

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

SWMM_ENGINE_API int swmm_link_pop_last(SWMM_Engine engine, const char* id);
 
/* =========================================================================
 * Connectivity (BUILDING or OPENED)
 * ========================================================================= */

SWMM_ENGINE_API int swmm_link_set_nodes(SWMM_Engine engine, int idx, int from_node_idx,
                                        int to_node_idx);

SWMM_ENGINE_API int swmm_link_get_from_node(SWMM_Engine engine, int idx, int* node_idx);

SWMM_ENGINE_API int swmm_link_get_to_node(SWMM_Engine engine, int idx, int* node_idx);

SWMM_ENGINE_API int swmm_links_restore_authored_orientation(SWMM_Engine engine, int* count);
 
/* =========================================================================
 * Geometry setters (BUILDING or OPENED)
 * ========================================================================= */

SWMM_ENGINE_API int swmm_link_set_length(SWMM_Engine engine, int idx, double length);

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

SWMM_ENGINE_API int swmm_link_set_offset_up(SWMM_Engine engine, int idx, double offset);

SWMM_ENGINE_API int swmm_link_set_offset_dn(SWMM_Engine engine, int idx, double offset);

SWMM_ENGINE_API int swmm_link_set_initial_flow(SWMM_Engine engine, int idx, double flow);

SWMM_ENGINE_API int swmm_link_set_max_flow(SWMM_Engine engine, int idx, double flow);

SWMM_ENGINE_API int swmm_link_get_initial_flow(SWMM_Engine engine, int idx, double* flow);

SWMM_ENGINE_API int swmm_link_get_max_flow(SWMM_Engine engine, int idx, double* flow);

typedef enum SWMM_OrificeType {
    SWMM_ORIFICE_SIDE = 0,   
    SWMM_ORIFICE_BOTTOM = 1, 
} SWMM_OrificeType;

SWMM_ENGINE_API int swmm_link_set_orifice_type(SWMM_Engine engine, int idx, int type);

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

typedef enum SWMM_WeirType {
    SWMM_WEIR_TRANSVERSE = 0,  
    SWMM_WEIR_SIDEFLOW = 1,    
    SWMM_WEIR_VNOTCH = 2,      
    SWMM_WEIR_TRAPEZOIDAL = 3, 
    SWMM_WEIR_ROADWAY = 4,     
} SWMM_WeirType;

SWMM_ENGINE_API int swmm_link_set_weir_type(SWMM_Engine engine, int idx, int type);

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

typedef enum SWMM_OutletRatingType {
    SWMM_OUTLET_FUNCTIONAL_HEAD = 0,  
    SWMM_OUTLET_FUNCTIONAL_DEPTH = 1, 
    SWMM_OUTLET_TABULAR_HEAD = 2,     
    SWMM_OUTLET_TABULAR_DEPTH = 3,    
} SWMM_OutletRatingType;

SWMM_ENGINE_API int swmm_link_set_outlet_rating_type(SWMM_Engine engine, int idx, int type);

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

SWMM_ENGINE_API int swmm_link_set_outlet_expon(SWMM_Engine engine, int idx, double expon);

SWMM_ENGINE_API int swmm_link_get_outlet_expon(SWMM_Engine engine, int idx, double* expon);

SWMM_ENGINE_API int swmm_link_set_pump_startup_depth(SWMM_Engine engine, int idx, double depth);

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

SWMM_ENGINE_API int swmm_link_set_pump_shutoff_depth(SWMM_Engine engine, int idx, double depth);

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

SWMM_ENGINE_API int swmm_link_set_orifice_open_close_rate(SWMM_Engine engine, int idx, double rate);

SWMM_ENGINE_API int swmm_link_get_orifice_open_close_rate(SWMM_Engine engine, int idx,
                                                          double* rate);
 
/* =========================================================================
 * Cross-section (BUILDING or OPENED)
 * ========================================================================= */

SWMM_ENGINE_API int swmm_link_set_xsect(SWMM_Engine engine, int idx, int shape, double geom1,
                                        double geom2, double geom3, double geom4);

SWMM_ENGINE_API int swmm_link_get_xsect(SWMM_Engine engine, int idx, int* shape, double* geom1,
                                        double* geom2, double* geom3, double* geom4);
 
/* =========================================================================
 * Geometry getters
 * ========================================================================= */

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

SWMM_ENGINE_API int swmm_link_get_length(SWMM_Engine engine, int idx, double* length);

SWMM_ENGINE_API int swmm_link_get_roughness(SWMM_Engine engine, int idx, double* n);
 
/* =========================================================================
 * Hydraulic state getters/setters
 * ========================================================================= */

SWMM_ENGINE_API int swmm_link_get_flow(SWMM_Engine engine, int idx, double* flow);

SWMM_ENGINE_API int swmm_link_set_flow(SWMM_Engine engine, int idx, double flow);

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

SWMM_ENGINE_API int swmm_link_get_velocity(SWMM_Engine engine, int idx, double* velocity);

SWMM_ENGINE_API int swmm_link_get_capacity(SWMM_Engine engine, int idx, double* capacity);

SWMM_ENGINE_API int swmm_link_get_volume(SWMM_Engine engine, int idx, double* volume);

SWMM_ENGINE_API int swmm_link_get_slot_volume(SWMM_Engine engine, int idx, double* volume);
 
/* --- Runtime forcing (RUNNING state only) --- */

SWMM_ENGINE_API int swmm_link_set_control_setting(SWMM_Engine engine, int idx, double setting);

SWMM_ENGINE_API int swmm_link_get_control_setting(SWMM_Engine engine, int idx, double* setting);

SWMM_ENGINE_API int swmm_link_set_target_setting(SWMM_Engine engine, int idx, double setting);

SWMM_ENGINE_API int swmm_link_get_target_setting(SWMM_Engine engine, int idx, double* setting);

SWMM_ENGINE_API int swmm_link_set_closed(SWMM_Engine engine, int idx, int closed);

SWMM_ENGINE_API int swmm_link_get_closed(SWMM_Engine engine, int idx, int* closed);
 
/* =========================================================================
 * Pump Link API
 * ========================================================================= */

SWMM_ENGINE_API int swmm_link_set_pump_curve(SWMM_Engine engine, int idx, int curve_idx);

SWMM_ENGINE_API int swmm_link_get_pump_curve(SWMM_Engine engine, int idx, int* curve_idx);

SWMM_ENGINE_API int swmm_link_set_pump_init_state(SWMM_Engine engine, int idx, int on);

SWMM_ENGINE_API int swmm_link_get_pump_init_state(SWMM_Engine engine, int idx, int* on);
 
/* =========================================================================
 * Weir Link API
 * ========================================================================= */

SWMM_ENGINE_API int swmm_link_set_crest_height(SWMM_Engine engine, int idx, double h);

SWMM_ENGINE_API int swmm_link_get_crest_height(SWMM_Engine engine, int idx, double* h);

SWMM_ENGINE_API int swmm_link_set_discharge_coeff(SWMM_Engine engine, int idx, double cd);

SWMM_ENGINE_API int swmm_link_get_discharge_coeff(SWMM_Engine engine, int idx, double* cd);

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

SWMM_ENGINE_API int swmm_link_get_end_contractions(SWMM_Engine engine, int idx, double* n);
 
/* =========================================================================
 * Conduit Loss Coefficients
 * ========================================================================= */

SWMM_ENGINE_API int swmm_link_set_loss_coeff(SWMM_Engine engine, int idx, double inlet,
                                             double outlet, double avg);

SWMM_ENGINE_API int swmm_link_get_loss_coeff(SWMM_Engine engine, int idx, double* inlet,
                                             double* outlet, double* avg);

SWMM_ENGINE_API int swmm_link_set_flap_gate(SWMM_Engine engine, int idx, int has_gate);

SWMM_ENGINE_API int swmm_link_get_flap_gate(SWMM_Engine engine, int idx, int* has_gate);

SWMM_ENGINE_API int swmm_link_set_seep_rate(SWMM_Engine engine, int idx, double rate);

SWMM_ENGINE_API int swmm_link_get_seep_rate(SWMM_Engine engine, int idx, double* rate);

SWMM_ENGINE_API int swmm_link_set_culvert_code(SWMM_Engine engine, int idx, int code);

SWMM_ENGINE_API int swmm_link_get_culvert_code(SWMM_Engine engine, int idx, int* code);

SWMM_ENGINE_API int swmm_link_set_barrels(SWMM_Engine engine, int idx, int n);

SWMM_ENGINE_API int swmm_link_get_barrels(SWMM_Engine engine, int idx, int* n);

SWMM_ENGINE_API int swmm_link_get_slope(SWMM_Engine engine, int idx, double* slope);

SWMM_ENGINE_API int swmm_link_get_offset_up(SWMM_Engine engine, int idx, double* offset);

SWMM_ENGINE_API int swmm_link_get_offset_dn(SWMM_Engine engine, int idx, double* offset);
 
/* =========================================================================
 * Link Statistics
 * ========================================================================= */

SWMM_ENGINE_API int swmm_link_get_stat_max_flow(SWMM_Engine engine, int idx, double* val);

SWMM_ENGINE_API int swmm_link_get_stat_max_velocity(SWMM_Engine engine, int idx, double* val);

SWMM_ENGINE_API int swmm_link_get_stat_max_filling(SWMM_Engine engine, int idx, double* val);

SWMM_ENGINE_API int swmm_link_get_stat_peak_slot_share(SWMM_Engine engine, int idx, double* val);

SWMM_ENGINE_API int swmm_link_get_stat_slot_share(SWMM_Engine engine, int idx, double* val);

SWMM_ENGINE_API int swmm_link_get_stat_vol_flow(SWMM_Engine engine, int idx, double* val);

SWMM_ENGINE_API int swmm_link_get_stat_surcharge_time(SWMM_Engine engine, int idx, double* val);
 
/* =========================================================================
 * Water quality
 * ========================================================================= */

SWMM_ENGINE_API int swmm_link_get_quality(SWMM_Engine engine, int link_idx, int pollutant_idx,
                                          double* conc);
 
/* =========================================================================
 * Bulk access
 * ========================================================================= */

SWMM_ENGINE_API int swmm_link_get_flows_bulk(SWMM_Engine engine, double* buf, int count);

SWMM_ENGINE_API int swmm_link_get_depths_bulk(SWMM_Engine engine, double* buf, int count);

SWMM_ENGINE_API int swmm_link_set_flows_bulk(SWMM_Engine engine, const double* buf, int count);

SWMM_ENGINE_API int swmm_link_get_quality_bulk(SWMM_Engine engine, int pollutant_idx, double* buf,
                                               int count);
 
/* =========================================================================
 * Phase 3 bulk getters — added in OpenSWMM 6.0.0 to eliminate the N
 * round-trip cost of per-link scalar accessors in whole-network consumers
 * (notably the MCP server's get_link_info(all) path and post-run reports).
 *
 * Note: velocities, capacities, and hydraulic powers are *derived* values
 * (depth/flow ratios; flow * head loss). Their bulk variants do a per-link
 * loop in C — there is no SoA column to memcpy from — but they still
 * eliminate the C ABI crossing overhead and any Python-level looping cost.
 * ========================================================================= */

SWMM_ENGINE_API int swmm_link_get_velocities_bulk(SWMM_Engine engine, double* buf, int count);

SWMM_ENGINE_API int swmm_link_get_capacities_bulk(SWMM_Engine engine, double* buf, int count);

SWMM_ENGINE_API int swmm_link_get_volumes_bulk(SWMM_Engine engine, double* buf, int count);

SWMM_ENGINE_API int swmm_link_get_control_settings_bulk(SWMM_Engine engine, double* buf, int count);

SWMM_ENGINE_API int swmm_link_get_target_settings_bulk(SWMM_Engine engine, double* buf, int count);

SWMM_ENGINE_API int swmm_link_get_hyd_powers_bulk(SWMM_Engine engine, double* buf, int count);

SWMM_ENGINE_API int swmm_link_get_ids_bulk(SWMM_Engine engine, char* buf, int stride, int count);
 
/* =========================================================================
 * Pump utilization statistics
 * ========================================================================= */

SWMM_ENGINE_API int swmm_link_get_stat_pump_cycles(SWMM_Engine engine, int idx, int* cycles);

SWMM_ENGINE_API int swmm_link_get_stat_pump_on_time(SWMM_Engine engine, int idx, double* seconds);

SWMM_ENGINE_API int swmm_link_get_stat_pump_volume(SWMM_Engine engine, int idx, double* volume);

SWMM_ENGINE_API int swmm_link_get_pump_stats_bulk(SWMM_Engine engine, int* cycles, double* on_time,
                                                  double* volume, int count);
 
/* =========================================================================
 * Hydraulic power
 * ========================================================================= */

SWMM_ENGINE_API int swmm_link_get_hyd_power(SWMM_Engine engine, int idx, double* power);

SWMM_ENGINE_API int swmm_link_rename(SWMM_Engine engine, int idx, const char* newId);
 
/* =========================================================================
 * Tag — free-form string label from the INP `[TAGS]` section
 * ========================================================================= */

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

SWMM_ENGINE_API int swmm_link_set_tag(SWMM_Engine engine, int idx, const char* tag);
 
#ifdef __cplusplus
} /* extern "C" */
#endif
 
#endif /* OPENSWMM_LINKS_H */