openswmm_inflows.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_INFLOWS_H
#define OPENSWMM_INFLOWS_H
 
#include "openswmm_engine.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
/* =========================================================================
 * External inflows
 * ========================================================================= */

SWMM_ENGINE_API int swmm_ext_inflow_add(SWMM_Engine engine, int node_idx, const char* constituent,
                                          const char* ts_name, const char* type,
                                          double m_factor, double s_factor, double baseline,
                                          const char* pattern);

SWMM_ENGINE_API int swmm_ext_inflow_get(SWMM_Engine engine, int entry_idx,
                                          int* node_idx,
                                          char* constituent_buf, int constituent_buflen,
                                          char* ts_buf,          int ts_buflen,
                                          char* type_buf,        int type_buflen,
                                          double* m_factor, double* s_factor, double* baseline,
                                          char* pattern_buf,     int pattern_buflen);

SWMM_ENGINE_API int swmm_ext_inflow_remove(SWMM_Engine engine, int entry_idx);

SWMM_ENGINE_API int swmm_ext_inflow_set_scale(SWMM_Engine engine, int entry_idx, double scale);

SWMM_ENGINE_API int swmm_ext_inflow_set_baseline(SWMM_Engine engine, int entry_idx, double baseline);
 
/* =========================================================================
 * Dry weather flow
 * ========================================================================= */

SWMM_ENGINE_API int swmm_dwf_add(SWMM_Engine engine, int node_idx, const char* constituent,
                                   double avg_value, const char* pat1, const char* pat2,
                                   const char* pat3, const char* pat4);

SWMM_ENGINE_API int swmm_dwf_get(SWMM_Engine engine, int entry_idx,
                                   int* node_idx,
                                   char* constituent_buf, int constituent_buflen,
                                   double* avg_value,
                                   char* pat1_buf, int pat1_buflen,
                                   char* pat2_buf, int pat2_buflen,
                                   char* pat3_buf, int pat3_buflen,
                                   char* pat4_buf, int pat4_buflen);

SWMM_ENGINE_API int swmm_dwf_remove(SWMM_Engine engine, int entry_idx);

SWMM_ENGINE_API int swmm_dwf_set_baseline(SWMM_Engine engine, int entry_idx, double avg_value);
 
/* =========================================================================
 * RDII (Rainfall-Dependent Infiltration/Inflow)
 * ========================================================================= */

SWMM_ENGINE_API int swmm_rdii_add(SWMM_Engine engine, int node_idx, const char* uh_name, double area);

SWMM_ENGINE_API int swmm_rdii_get(SWMM_Engine engine, int entry_idx,
                                    int* node_idx, char* uh_buf, int buflen,
                                    double* area);

SWMM_ENGINE_API int swmm_rdii_remove(SWMM_Engine engine, int entry_idx);
 
/* =========================================================================
 * Unit hydrographs ([HYDROGRAPHS] section)
 * =========================================================================
 *
 * A unit hydrograph group is identified by name and has two kinds of input
 * lines:
 *   - A gage assignment line: "UHname  RainGage"
 *   - One or more parameter lines: "UHname Month Response R T K [Dmax Drecov Dinit]"
 *
 * Both kinds are added separately. `swmm_hydrograph_add` adds a parameter
 * line, `swmm_hydrograph_add_gage` adds the gage assignment. Counts and
 * getters are also separated.
 *
 * `response` is encoded as: 0 = SHORT, 1 = MEDIUM, 2 = LONG.
 * `month` is encoded as: 0..11 = JAN..DEC, or -1 = ALL.
 * ========================================================================= */

SWMM_ENGINE_API int swmm_hydrograph_add(SWMM_Engine engine, const char* uh_name,
                                          int month, int response,
                                          double r, double t, double k,
                                          double dmax, double drecov, double dinit);

SWMM_ENGINE_API int swmm_hydrograph_get(SWMM_Engine engine, int entry_idx,
                                          char* uh_buf, int buflen,
                                          int* month, int* response,
                                          double* r, double* t, double* k,
                                          double* dmax, double* drecov, double* dinit);

SWMM_ENGINE_API int swmm_hydrograph_count(SWMM_Engine engine);

SWMM_ENGINE_API int swmm_hydrograph_add_gage(SWMM_Engine engine,
                                               const char* uh_name,
                                               const char* gage_name);

SWMM_ENGINE_API int swmm_hydrograph_get_gage(SWMM_Engine engine, int entry_idx,
                                               char* uh_buf, int uh_buflen,
                                               char* gage_buf, int gage_buflen);

SWMM_ENGINE_API int swmm_hydrograph_gage_count(SWMM_Engine engine);

SWMM_ENGINE_API int swmm_hydrograph_group_count(SWMM_Engine engine);

SWMM_ENGINE_API int swmm_hydrograph_group_id(SWMM_Engine engine, int idx,
                                               char* buf, int buflen);
 
/* =========================================================================
 * Mutation surface (BS-02) — upsert + key-based remove + rename
 * =========================================================================
 *
 * The legacy `swmm_hydrograph_add` / `swmm_hydrograph_add_gage` surface above
 * is append-only, which prevents in-place edits from a UI. The following
 * setters/removers support the `HydrographGroupEditor` MVC layer in
 * openswmm.gui: every mutation in the editor routes through one of these
 * symbols, and the GUI's `SWMMModelLayer` emits a `hydrographChanged(uhName)`
 * signal so all subscribed views (Object Browser, property panel, picker
 * combos, etc.) refresh in lock-step.
 *
 * Upsert contract (set_rtk, set_ia, decay_set):
 *   - If an entry matching the supplied key exists, update only the fields
 *     this setter owns and leave the rest untouched.
 *   - Otherwise append a new entry with the supplied fields set and the
 *     unspecified fields zeroed (so set_rtk followed by set_ia on the same
 *     key composes correctly).
 *
 * Remove contract (remove_entry, remove_group, decay_remove):
 *   - Key-based, not index-based — indices shift as entries are removed and
 *     a UI cannot keep them in sync. Idempotent: returns SWMM_OK if no
 *     match is found.
 *
 * Group remove cascades to: [HYDROGRAPHS] parameter rows, gage assignments,
 * [RDII_DECAY] rows, AND any [RDII] node assignments referencing the group
 * (so the engine never sees a dangling UH-name reference after a delete).
 * ========================================================================= */

SWMM_ENGINE_API int swmm_hydrograph_set_rtk(SWMM_Engine engine, const char* uh_name,
                                              int month, int response,
                                              double r, double t, double k);

SWMM_ENGINE_API int swmm_hydrograph_set_ia(SWMM_Engine engine, const char* uh_name,
                                             int month, int response,
                                             double dmax, double drecov, double dinit);

SWMM_ENGINE_API int swmm_hydrograph_remove_entry(SWMM_Engine engine, const char* uh_name,
                                                   int month, int response);

SWMM_ENGINE_API int swmm_hydrograph_remove_group(SWMM_Engine engine, const char* uh_name);

SWMM_ENGINE_API int swmm_hydrograph_clear_group_months(SWMM_Engine engine, const char* uh_name);

SWMM_ENGINE_API int swmm_hydrograph_set_gage(SWMM_Engine engine, const char* uh_name,
                                               const char* gage_name);

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

SWMM_ENGINE_API int swmm_rdii_decay_set(SWMM_Engine engine, const char* uh_name,
                                          int response,
                                          double k_dep, double k_0, double k_T,
                                          double T_ref, double theta_rec, double T_freeze,
                                          int snow_on, double snow_T, double snow_ddf);

SWMM_ENGINE_API int swmm_rdii_decay_remove(SWMM_Engine engine, const char* uh_name, int response);
 
/* =========================================================================
 * Exponential IA decay ([RDII_DECAY] section)
 * =========================================================================
 *
 * Physics-based replacement for the legacy linear IA recovery. When a row
 * is present for a (UH group, response) pair, the exponential depletion /
 * temperature-dependent recovery model is used in place of the linear
 * `drecov` rate from the corresponding [HYDROGRAPHS] entry.
 *
 * @see docs/RDII_ExpDecay_Implementation.md
 * ========================================================================= */

SWMM_ENGINE_API int swmm_rdii_decay_add(SWMM_Engine engine, const char* uh_name,
                                          int response,
                                          double k_dep, double k_0, double k_T,
                                          double T_ref, double theta_rec, double T_freeze,
                                          int snow_on, double snow_T, double snow_ddf);

SWMM_ENGINE_API int swmm_rdii_decay_get(SWMM_Engine engine, int entry_idx,
                                          char* uh_buf, int buflen,
                                          int* response,
                                          double* k_dep, double* k_0, double* k_T,
                                          double* T_ref, double* theta_rec, double* T_freeze,
                                          int* snow_on, double* snow_T, double* snow_ddf);

SWMM_ENGINE_API int swmm_rdii_decay_count(SWMM_Engine engine);
 
/* =========================================================================
 * Count queries
 * ========================================================================= */

SWMM_ENGINE_API int swmm_ext_inflow_count(SWMM_Engine engine);

SWMM_ENGINE_API int swmm_dwf_count(SWMM_Engine engine);

SWMM_ENGINE_API int swmm_rdii_count(SWMM_Engine engine);
 
#ifdef __cplusplus
} /* extern "C" */
#endif
 
#endif /* OPENSWMM_INFLOWS_H */