openswmm_nodes.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_NODES_H
#define OPENSWMM_NODES_H
 
#include "openswmm_engine.h"
 
#ifdef __cplusplus
extern "C" {
#endif

typedef enum SWMM_NodeType {
    SWMM_NODE_JUNCTION = 0, 
    SWMM_NODE_OUTFALL = 1,  
    SWMM_NODE_STORAGE = 2,  
    SWMM_NODE_DIVIDER = 3   
} SWMM_NodeType;
 
/* =========================================================================
 * Identity
 * ========================================================================= */

SWMM_ENGINE_API int swmm_node_count(SWMM_Engine engine);

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

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

typedef struct SWMM_OutfallExportReceipt {
    double exported_m3;
    double reversed_m3;
    double exported_heat_j;
    unsigned flags;
} SWMM_OutfallExportReceipt;

SWMM_ENGINE_API int swmm_node_get_export_receipt(SWMM_Engine engine, int idx,
                                                 SWMM_OutfallExportReceipt* receipt,
                                                 double* pollutant_amounts, int count);
 
/* =========================================================================
 * Creation (BUILDING or OPENED — "editable" states)
 * ========================================================================= */

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

SWMM_ENGINE_API int swmm_node_pop_last(SWMM_Engine engine, const char* id);
 
/* =========================================================================
 * Geometry setters (BUILDING or OPENED)
 * ========================================================================= */

SWMM_ENGINE_API int swmm_node_set_invert_elev(SWMM_Engine engine, int idx, double elev);

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

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

SWMM_ENGINE_API int swmm_node_set_storage_area(SWMM_Engine engine, int idx, double area);
SWMM_ENGINE_API int swmm_node_get_storage_area(SWMM_Engine engine, int idx, double* area);

SWMM_ENGINE_API int swmm_node_set_pond_area(SWMM_Engine engine, int idx, double area);

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

SWMM_ENGINE_API int swmm_node_set_rim_depth(SWMM_Engine engine, int idx, double depth);
 
/* =========================================================================
 * Geometry getters
 * ========================================================================= */

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

SWMM_ENGINE_API int swmm_node_is_virtual(SWMM_Engine engine, int idx, int* is_virtual);

SWMM_ENGINE_API int swmm_node_set_virtual(SWMM_Engine engine, int idx, int make_virtual);

SWMM_ENGINE_API int swmm_node_virtual_eligible(SWMM_Engine engine, int idx, int* rule_code);
 
/* -------------------------------------------------------------------------
 * Inlet junctions (2026-09-05). An inlet junction is a virtual junction
 * (is_virtual = 1) that additionally carries is_inlet = 1, sits between two
 * STREET conduits (or RECT_OPEN/TRAPEZOIDAL for drop-inlet designs), owns one
 * inlet-usage row (swmm_inlet_usage_set with SWMM_INLET_HOST_NODE) naming the
 * inlet design and the capture node, and — unlike a plain virtual junction —
 * is NOT sealed: it floods above the street section's full depth (or the
 * [INLET_JUNCTIONS] MaxDepth when supplied) and receives the capture node's
 * overflow back as street flow.
 * ------------------------------------------------------------------------- */

SWMM_ENGINE_API int swmm_node_is_inlet(SWMM_Engine engine, int idx, int* is_inlet);

SWMM_ENGINE_API int swmm_node_inlet_eligible(SWMM_Engine engine, int idx, int for_drop_inlet,
                                             int* rule_code);

SWMM_ENGINE_API int swmm_node_set_inlet(SWMM_Engine engine, int idx, int make_inlet);

SWMM_ENGINE_API int swmm_node_get_invert_elev(SWMM_Engine engine, int idx, double* elev);

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

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

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

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

SWMM_ENGINE_API int swmm_node_get_head(SWMM_Engine engine, int idx, double* head);

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

SWMM_ENGINE_API int swmm_node_get_lateral_inflow(SWMM_Engine engine, int idx, double* inflow);

SWMM_ENGINE_API int swmm_node_get_overflow(SWMM_Engine engine, int idx, double* overflow);

SWMM_ENGINE_API int swmm_node_get_inflow(SWMM_Engine engine, int idx, double* inflow);
 
/* =========================================================================
 * Runtime forcing (RUNNING state only)
 * ========================================================================= */

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

SWMM_ENGINE_API int swmm_node_set_quality_mass_flux(SWMM_Engine engine, int node_idx,
                                                    int pollutant_idx, double mass_rate);

SWMM_ENGINE_API int swmm_node_set_head_boundary(SWMM_Engine engine, int idx, double head);
 
/* =========================================================================
 * Water quality
 * ========================================================================= */

SWMM_ENGINE_API int swmm_node_get_quality(SWMM_Engine engine, int node_idx, int pollutant_idx,
                                          double* conc);
 
/* =========================================================================
 * Storage Node API
 * ========================================================================= */

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

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

SWMM_ENGINE_API int swmm_node_set_storage_functional(SWMM_Engine engine, int idx, double a,
                                                     double b, double c);

SWMM_ENGINE_API int swmm_node_get_storage_functional(SWMM_Engine engine, int idx, double* a,
                                                     double* b, double* c);

typedef enum {
    SWMM_STORAGE_TABULAR = 0,     
    SWMM_STORAGE_FUNCTIONAL = 1,  
    SWMM_STORAGE_CYLINDRICAL = 2, 
    SWMM_STORAGE_CONICAL = 3,     
    SWMM_STORAGE_PARABOLOID =
        4, 
    SWMM_STORAGE_PYRAMIDAL =
        5 
} SWMM_StorageShape;

SWMM_ENGINE_API int swmm_node_set_storage_shape(SWMM_Engine engine, int idx, int shape);

SWMM_ENGINE_API int swmm_node_get_storage_shape(SWMM_Engine engine, int idx, int* shape);

SWMM_ENGINE_API int swmm_node_set_storage_geometry(SWMM_Engine engine, int idx, double p1,
                                                   double p2, double p3);

SWMM_ENGINE_API int swmm_node_get_storage_geometry(SWMM_Engine engine, int idx, double* p1,
                                                   double* p2, double* p3);

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

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

SWMM_ENGINE_API int swmm_node_set_exfil_params(SWMM_Engine engine, int idx, double suction,
                                               double ksat, double imd);

SWMM_ENGINE_API int swmm_node_get_exfil_params(SWMM_Engine engine, int idx, double* suction,
                                               double* ksat, double* imd);
 
/* =========================================================================
 * Outfall Node API
 * ========================================================================= */

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

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

SWMM_ENGINE_API int swmm_node_set_outfall_stage(SWMM_Engine engine, int idx, double stage);

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

SWMM_ENGINE_API int swmm_node_set_outfall_timeseries(SWMM_Engine engine, int idx, int ts_idx);

SWMM_ENGINE_API int swmm_node_get_outfall_param(SWMM_Engine engine, int idx, double* param);

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

SWMM_ENGINE_API int swmm_node_get_outfall_timeseries(SWMM_Engine engine, int idx, int* ts_idx);

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

SWMM_ENGINE_API int swmm_node_get_outfall_flap_gate(SWMM_Engine engine, int idx, int* has_gate);
 
/* =========================================================================
 * Divider Node API
 * ========================================================================= */

typedef enum SWMM_DividerType {
    SWMM_DIVIDER_CUTOFF = 0,   
    SWMM_DIVIDER_OVERFLOW = 1, 
    SWMM_DIVIDER_TABULAR = 2,  
    SWMM_DIVIDER_WEIR = 3      
} SWMM_DividerType;

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

SWMM_ENGINE_API int swmm_node_get_divider_type(SWMM_Engine engine, int idx, int* type);
 
/* =========================================================================
 * Additional Geometry / State Getters
 * ========================================================================= */

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

SWMM_ENGINE_API int swmm_node_get_ponded_area(SWMM_Engine engine, int idx, double* area);

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

SWMM_ENGINE_API int swmm_node_get_crown_elev(SWMM_Engine engine, int idx, double* elev);

SWMM_ENGINE_API int swmm_node_get_full_volume(SWMM_Engine engine, int idx, double* vol);

SWMM_ENGINE_API int swmm_node_get_losses(SWMM_Engine engine, int idx, double* losses);

SWMM_ENGINE_API int swmm_node_get_outflow(SWMM_Engine engine, int idx, double* outflow);

SWMM_ENGINE_API int swmm_node_get_degree(SWMM_Engine engine, int idx, int* degree);
 
/* =========================================================================
 * Node Statistics
 * ========================================================================= */

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

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

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

SWMM_ENGINE_API int swmm_node_get_stat_time_flooded(SWMM_Engine engine, int idx, double* val);
 
/* =========================================================================
 * Bulk access
 * ========================================================================= */

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

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

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

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

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

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

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

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

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

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

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

SWMM_ENGINE_API int swmm_node_get_ids_bulk(SWMM_Engine engine, char* buf, int stride, int count);
 
/* =========================================================================
 * Outfall-to-subcatchment routing
 * ========================================================================= */

SWMM_ENGINE_API int swmm_node_set_outfall_route_to(SWMM_Engine engine, int idx, int subcatch_idx);

SWMM_ENGINE_API int swmm_node_get_outfall_route_to(SWMM_Engine engine, int idx, int* subcatch_idx);
 
/* =========================================================================
 * Depth from volume (inverse of getVolume)
 * ========================================================================= */

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

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

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

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