openswmm_links.h

Go to the documentation of this file.

 
#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_RECT_TRIANG     =  8, 
    SWMM_XSECT_RECT_ROUND      =  9, 
    SWMM_XSECT_MOD_BASKET      = 10, 
    SWMM_XSECT_HORIZ_ELLIPSE   = 11, 
    SWMM_XSECT_VERT_ELLIPSE    = 12, 
    SWMM_XSECT_ARCH            = 13, 
    SWMM_XSECT_EGGSHAPED       = 14, 
    SWMM_XSECT_HORSESHOE       = 15, 
    SWMM_XSECT_GOTHIC          = 16, 
    SWMM_XSECT_CATENARY        = 17, 
    SWMM_XSECT_SEMIELLIPTICAL  = 18, 
    SWMM_XSECT_IRREGULAR       = 19  
} 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);
 
/* =========================================================================
 * 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);
 
/* --- 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_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 */