openswmm_subcatchments.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_SUBCATCHMENTS_H
#define OPENSWMM_SUBCATCHMENTS_H
 
#include "openswmm_engine.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
/* =========================================================================
 * Identity
 * ========================================================================= */

SWMM_ENGINE_API int swmm_subcatch_count(SWMM_Engine engine);

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

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

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

SWMM_ENGINE_API int swmm_subcatch_set_outlet(SWMM_Engine engine, int idx, int node_idx);

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

SWMM_ENGINE_API int swmm_subcatch_set_width(SWMM_Engine engine, int idx, double width);

SWMM_ENGINE_API int swmm_subcatch_set_slope(SWMM_Engine engine, int idx, double slope);

SWMM_ENGINE_API int swmm_subcatch_set_imperv_pct(SWMM_Engine engine, int idx, double pct);

SWMM_ENGINE_API int swmm_subcatch_set_zero_imperv_pct(SWMM_Engine engine, int idx, double pct);

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

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

SWMM_ENGINE_API int swmm_subcatch_set_ds_imperv(SWMM_Engine engine, int idx, double ds);

SWMM_ENGINE_API int swmm_subcatch_set_ds_perv(SWMM_Engine engine, int idx, double ds);

SWMM_ENGINE_API int swmm_subcatch_set_gage(SWMM_Engine engine, int idx, int gage_idx);
 
/* --- Infiltration parameters (BUILDING or OPENED) --- */

SWMM_ENGINE_API int swmm_subcatch_set_infil_horton(SWMM_Engine engine, int idx,
                                                     double f0, double fmin,
                                                     double decay, double dry_time);

SWMM_ENGINE_API int swmm_subcatch_set_infil_green_ampt(SWMM_Engine engine, int idx,
                                                         double suction, double conductivity,
                                                         double initial_deficit);

SWMM_ENGINE_API int swmm_subcatch_set_infil_curve_number(SWMM_Engine engine, int idx,
                                                           double cn, double drying_time);

SWMM_ENGINE_API int swmm_subcatch_set_infil_model(SWMM_Engine engine, int idx, int model);
 
/* =========================================================================
 * Property getters
 * ========================================================================= */

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

SWMM_ENGINE_API int swmm_subcatch_get_imperv_pct(SWMM_Engine engine, int idx, double* pct);

SWMM_ENGINE_API int swmm_subcatch_get_zero_imperv_pct(SWMM_Engine engine, int idx, double* pct);

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

SWMM_ENGINE_API int swmm_subcatch_get_width(SWMM_Engine engine, int idx, double* w);

SWMM_ENGINE_API int swmm_subcatch_get_slope(SWMM_Engine engine, int idx, double* s);

SWMM_ENGINE_API int swmm_subcatch_get_n_imperv(SWMM_Engine engine, int idx, double* n);

SWMM_ENGINE_API int swmm_subcatch_get_n_perv(SWMM_Engine engine, int idx, double* n);

SWMM_ENGINE_API int swmm_subcatch_get_ds_imperv(SWMM_Engine engine, int idx, double* ds);

SWMM_ENGINE_API int swmm_subcatch_get_ds_perv(SWMM_Engine engine, int idx, double* ds);

SWMM_ENGINE_API int swmm_subcatch_get_gage(SWMM_Engine engine, int idx, int* gage_idx);

SWMM_ENGINE_API int swmm_subcatch_set_outlet_subcatch(SWMM_Engine engine, int idx, int sc_idx);

SWMM_ENGINE_API int swmm_subcatch_get_outlet_subcatch(SWMM_Engine engine, int idx, int* sc_idx);
 
/* =========================================================================
 * Infiltration getters
 * ========================================================================= */

SWMM_ENGINE_API int swmm_subcatch_get_infil_model(SWMM_Engine engine, int idx, int* model);

SWMM_ENGINE_API int swmm_subcatch_get_infil_horton(SWMM_Engine engine, int idx,
                                                          double* f0, double* fmin,
                                                          double* decay, double* dry_time);

SWMM_ENGINE_API int swmm_subcatch_get_infil_green_ampt(SWMM_Engine engine, int idx,
                                                          double* suction, double* conductivity,
                                                          double* deficit);

SWMM_ENGINE_API int swmm_subcatch_get_infil_curve_number(SWMM_Engine engine, int idx,
                                                           double* cn, double* drying_time);
 
/* =========================================================================
 * Subcatchment statistics
 * ========================================================================= */

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

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

SWMM_ENGINE_API int swmm_subcatch_get_stat_max_runoff(SWMM_Engine engine, int idx, double* rate);
 
/* =========================================================================
 * Subcatchment landuse coverage
 * ========================================================================= */

SWMM_ENGINE_API int swmm_subcatch_set_coverage(SWMM_Engine engine, int sc_idx, int lu_idx, double fraction);

SWMM_ENGINE_API int swmm_subcatch_get_coverage(SWMM_Engine engine, int sc_idx, int lu_idx, double* fraction);

SWMM_ENGINE_API int swmm_subcatch_get_coverages(SWMM_Engine engine, int sc_idx, double* out, int n);
 
/* =========================================================================
 * Initial pollutant loadings ([LOADINGS])
 * ========================================================================= */

SWMM_ENGINE_API int swmm_subcatch_set_initial_loading(SWMM_Engine engine, int sc_idx, int pollut_idx, double buildup);

SWMM_ENGINE_API int swmm_subcatch_get_initial_loading(SWMM_Engine engine, int sc_idx, int pollut_idx, double* buildup);
 
/* =========================================================================
 * Hydraulic state getters
 * ========================================================================= */

SWMM_ENGINE_API int swmm_subcatch_get_runoff(SWMM_Engine engine, int idx, double* runoff);

SWMM_ENGINE_API int swmm_subcatch_get_groundwater(SWMM_Engine engine, int idx, double* gw_flow);

SWMM_ENGINE_API int swmm_subcatch_get_rainfall(SWMM_Engine engine, int idx, double* rainfall);

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

SWMM_ENGINE_API int swmm_subcatch_get_evap(SWMM_Engine engine, int idx, double* evap);
 
/* =========================================================================
 * Groundwater configuration ([GROUNDWATER])
 * =========================================================================
 * Configure a subcatchment's [GROUNDWATER] flow routing. Values are stored
 * exactly as parsed from the input file (raw user units) so they round-trip
 * identically. Distinct from the runtime gw STATE (theta / lower_depth)
 * injected via swmm_subcatch_set_gw_state. All are BUILDING/OPENED editable.
 */

SWMM_ENGINE_API int swmm_subcatch_set_aquifer(SWMM_Engine engine, int idx, int aquifer_idx);

SWMM_ENGINE_API int swmm_subcatch_get_aquifer(SWMM_Engine engine, int idx, int* aquifer_idx);

SWMM_ENGINE_API int swmm_subcatch_set_gw_node(SWMM_Engine engine, int idx, int node_idx);

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

SWMM_ENGINE_API int swmm_subcatch_set_gw_params(SWMM_Engine engine, int idx,
                                                double surf_elev, double a1, double b1,
                                                double a2, double b2, double a3,
                                                double tw, double hstar);

SWMM_ENGINE_API int swmm_subcatch_get_gw_params(SWMM_Engine engine, int idx,
                                                double* surf_elev, double* a1, double* b1,
                                                double* a2, double* b2, double* a3,
                                                double* tw, double* hstar);
 
/* =========================================================================
 * State injection (data assimilation)
 * ========================================================================= */

SWMM_ENGINE_API int swmm_subcatch_set_gw_state(SWMM_Engine engine, int idx,
                                               double theta, double lower_depth);

SWMM_ENGINE_API int swmm_subcatch_get_gw_state(SWMM_Engine engine, int idx,
                                               double* theta, double* lower_depth);

SWMM_ENGINE_API int swmm_subcatch_set_snow_state(SWMM_Engine engine, int idx,
                                                 int surface, double swe, double fw,
                                                 double ati, double coldc);

SWMM_ENGINE_API int swmm_subcatch_get_snow_state(SWMM_Engine engine, int idx,
                                                 int surface, double* swe, double* fw,
                                                 double* ati, double* coldc);

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

SWMM_ENGINE_API int swmm_subcatch_set_rainfall(SWMM_Engine engine, int idx, double rainfall);
 
/* =========================================================================
 * Water quality
 * ========================================================================= */

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

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

SWMM_ENGINE_API int swmm_subcatch_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-subcatchment scalar accessors. All return a
 * caller-allocated @c double buffer of length @c count (clipped at
 * @c swmm_subcatch_count()); the IDs variant returns a stride-packed
 * UTF-8 buffer following the same format as @ref swmm_node_get_ids_bulk.
 * ========================================================================= */

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

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

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

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

SWMM_ENGINE_API int swmm_subcatch_get_ids_bulk(SWMM_Engine engine,
                                                char* buf,
                                                int stride,
                                                int count);
 
/* =========================================================================
 * Ponded quality (mass in standing water between events)
 * ========================================================================= */

SWMM_ENGINE_API int swmm_subcatch_get_ponded_quality(SWMM_Engine engine,
    int subcatch_idx, int pollutant_idx, double* mass);

SWMM_ENGINE_API int swmm_subcatch_set_ponded_quality(SWMM_Engine engine,
    int subcatch_idx, int pollutant_idx, double mass);

SWMM_ENGINE_API int swmm_subcatch_rename(SWMM_Engine engine, int idx, const char* newId);
 
/* =========================================================================
 * Aquifer definitions ([AQUIFERS] section) — Slice BM.0 / BP.6.6.4
 * ========================================================================= */

SWMM_ENGINE_API int swmm_aquifer_count(SWMM_Engine engine);

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

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

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

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

typedef enum SWMM_AquiferParam {
    SWMM_AQUIFER_POROSITY = 0,
    SWMM_AQUIFER_WILTING_POINT = 1,
    SWMM_AQUIFER_FIELD_CAPACITY = 2,
    SWMM_AQUIFER_CONDUCTIVITY = 3,
    SWMM_AQUIFER_CONDUCT_SLOPE = 4,
    SWMM_AQUIFER_TENSION_SLOPE = 5,
    SWMM_AQUIFER_UPPER_EVAP_FRAC = 6,
    SWMM_AQUIFER_LOWER_EVAP_DEPTH = 7,
    SWMM_AQUIFER_LOWER_LOSS_COEFF = 8,
    SWMM_AQUIFER_BOTTOM_ELEV = 9,
    SWMM_AQUIFER_WATER_TABLE_ELEV = 10,
    SWMM_AQUIFER_UPPER_MOISTURE = 11
} SWMM_AquiferParam;

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

SWMM_ENGINE_API int swmm_aquifer_set_param(SWMM_Engine engine, int idx, int param, double value);

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

SWMM_ENGINE_API int swmm_aquifer_set_evap_pattern(SWMM_Engine engine, int idx, const char* name);
 
/* =========================================================================
 * Snowpack definitions ([SNOWPACKS] section) — Slice BM.0 / BP.6.6.5
 * ========================================================================= */

SWMM_ENGINE_API int swmm_snowpack_count(SWMM_Engine engine);

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

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

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

SWMM_ENGINE_API int swmm_snowpack_rename(SWMM_Engine engine, int idx, const char* new_id);
 
/* -------------------------------------------------------------------------
 * Snowpack surface parameters
 *
 * A snowpack carries three snow-melt surfaces — PLOWABLE, IMPERVIOUS and
 * PERVIOUS — plus an optional REMOVAL row, matching the four line types of
 * the legacy `[SNOWPACKS]` section. Each surface takes seven values in
 * input-file units:
 *
 *   cmin    Minimum melt coefficient                 (in or mm /hr/deg)
 *   cmax    Maximum melt coefficient                 (in or mm /hr/deg)
 *   tbase   Snow-melt base temperature               (deg F or C)
 *   fwfrac  Free-water capacity as a fraction of depth
 *   sd0     Initial snow depth                       (in or mm water equiv.)
 *   fw0     Initial free water                       (in or mm)
 *   last    PLOWABLE: fraction of the impervious area that is plowable;
 *           IMPERVIOUS / PERVIOUS: snow depth above which there is 100% cover
 *           (in or mm).
 *
 * Setters are pre-start-only (BUILDING / OPENED) — the surface parameters seed
 * per-subcatchment snow state at start(); a mid-run change returns
 * SWMM_ERR_LIFECYCLE. Each setter has an inverse getter so the GUI snowpack
 * editor can load existing definitions. Any getter out-param may be null.
 * ------------------------------------------------------------------------- */

SWMM_ENGINE_API int swmm_snowpack_set_plowable(SWMM_Engine engine, int idx,
                                               double cmin, double cmax, double tbase,
                                               double fwfrac, double sd0, double fw0, double last);
SWMM_ENGINE_API int swmm_snowpack_get_plowable(SWMM_Engine engine, int idx,
                                               double* cmin, double* cmax, double* tbase,
                                               double* fwfrac, double* sd0, double* fw0, double* last);

SWMM_ENGINE_API int swmm_snowpack_set_impervious(SWMM_Engine engine, int idx,
                                                 double cmin, double cmax, double tbase,
                                                 double fwfrac, double sd0, double fw0, double last);
SWMM_ENGINE_API int swmm_snowpack_get_impervious(SWMM_Engine engine, int idx,
                                                 double* cmin, double* cmax, double* tbase,
                                                 double* fwfrac, double* sd0, double* fw0, double* last);

SWMM_ENGINE_API int swmm_snowpack_set_pervious(SWMM_Engine engine, int idx,
                                               double cmin, double cmax, double tbase,
                                               double fwfrac, double sd0, double fw0, double last);
SWMM_ENGINE_API int swmm_snowpack_get_pervious(SWMM_Engine engine, int idx,
                                               double* cmin, double* cmax, double* tbase,
                                               double* fwfrac, double* sd0, double* fw0, double* last);

SWMM_ENGINE_API int swmm_snowpack_set_removal(SWMM_Engine engine, int idx,
                                              double dsnow, double fout, double fimp,
                                              double fperv, double fimelt, double fsubcatch);
SWMM_ENGINE_API int swmm_snowpack_get_removal(SWMM_Engine engine, int idx,
                                              double* dsnow, double* fout, double* fimp,
                                              double* fperv, double* fimelt, double* fsubcatch);

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

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

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

SWMM_ENGINE_API int swmm_subcatch_set_rain_scale_factor(SWMM_Engine engine, int idx,
                                            double factor);

SWMM_ENGINE_API int swmm_subcatch_get_rain_scale_factor(SWMM_Engine engine, int idx,
                                            double* factor);

SWMM_ENGINE_API int swmm_subcatch_set_snow_scale_factor(SWMM_Engine engine, int idx,
                                            double factor);

SWMM_ENGINE_API int swmm_subcatch_get_snow_scale_factor(SWMM_Engine engine, int idx,
                                            double* factor);
 
/* =========================================================================
 * Custom groundwater flow expressions ([GWF] section)
 * ========================================================================= */

typedef enum SWMM_GwfType {
    SWMM_GWF_LATERAL = 0,
    SWMM_GWF_DEEP = 1
} SWMM_GwfType;

SWMM_ENGINE_API int swmm_subcatch_get_gwf_expression(SWMM_Engine engine, int index, int type,
                                                     char* buf, int buflen);

SWMM_ENGINE_API int swmm_subcatch_set_gwf_expression(SWMM_Engine engine, int index, int type,
                                                     const char* expr);

SWMM_ENGINE_API int swmm_gwf_validate_expression(SWMM_Engine engine, const char* expr,
                                                 char* errbuf, int buflen, int* col_out);

SWMM_ENGINE_API int swmm_gwf_variable_count(SWMM_Engine engine);

SWMM_ENGINE_API int swmm_gwf_variable_name(SWMM_Engine engine, int i, char* buf, int buflen);

SWMM_ENGINE_API int swmm_gwf_variable_description(SWMM_Engine engine, int i, char* buf, int buflen);

SWMM_ENGINE_API int swmm_gwf_function_count(SWMM_Engine engine);

SWMM_ENGINE_API int swmm_gwf_function_name(SWMM_Engine engine, int i, char* buf, int buflen);
 
#ifdef __cplusplus
} /* extern "C" */
#endif
 
#endif /* OPENSWMM_SUBCATCHMENTS_H */