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