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