openswmm_forcing.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_FORCING_H
#define OPENSWMM_FORCING_H
 
#include "openswmm_callbacks.h"
 
#ifdef OPENSWMM_ENGINE_STATIC
#define SWMM_ENGINE_API
#else
#ifdef _WIN32
#ifdef openswmm_engine_EXPORTS
#define SWMM_ENGINE_API __declspec(dllexport)
#else
#define SWMM_ENGINE_API __declspec(dllimport)
#endif
#else
#define SWMM_ENGINE_API __attribute__((visibility("default")))
#endif
#endif
 
#ifdef __cplusplus
extern "C" {
#endif
 
/* =========================================================================
 * Enumerations
 * ========================================================================= */

typedef enum SWMM_ForcingMode {
    SWMM_FORCING_NONE = 0,     
    SWMM_FORCING_OVERRIDE = 1, 
    SWMM_FORCING_ADD = 2       
} SWMM_ForcingMode;

typedef enum SWMM_ForcingPersist {
    SWMM_FORCING_RESET = 0,  
    SWMM_FORCING_PERSIST = 1 
} SWMM_ForcingPersist;

typedef enum SWMM_ForcingType {
    SWMM_FORCE_NODE_LAT_INFLOW = 0,
    SWMM_FORCE_NODE_HEAD_BOUNDARY = 1,
    SWMM_FORCE_NODE_QUALITY = 2,
    SWMM_FORCE_LINK_FLOW = 3,
    SWMM_FORCE_LINK_SETTING = 4,
    SWMM_FORCE_SUBCATCH_RAINFALL = 5,
    SWMM_FORCE_SUBCATCH_EVAP = 6,
    SWMM_FORCE_GAGE_RAINFALL = 7,
    SWMM_FORCE_CLIMATE_TEMPERATURE = 8, 
    SWMM_FORCE_CLIMATE_WIND = 9,        
    SWMM_FORCE_SUBCATCH_SNOWFALL = 10,
    SWMM_FORCE_CLIMATE_EVAP = 11, 
    SWMM_FORCE_LINK_QUALITY = 12,
    /* PE4 — per-ELEMENT climate. `idx` is the element index and the kind is
       given separately; see swmm_forcing_element_climate. */
    SWMM_FORCE_ELEM_AIR_TEMPERATURE = 13,
    SWMM_FORCE_ELEM_HUMIDITY = 14,
    SWMM_FORCE_ELEM_WIND_SPEED = 15,
    SWMM_FORCE_ELEM_SHORTWAVE = 16,
    SWMM_FORCE_LINK_SEEPAGE = 17 
} SWMM_ForcingType;

typedef enum SWMM_HeatElemKind {
    SWMM_HEAT_ELEM_NODE = 0,
    SWMM_HEAT_ELEM_LINK = 1
} SWMM_HeatElemKind;
 
/* =========================================================================
 * Node forcing
 * ========================================================================= */

SWMM_ENGINE_API int swmm_forcing_node_lat_inflow(SWMM_Engine engine, int idx, double value,
                                                 int mode, int persist);

SWMM_ENGINE_API int swmm_forcing_node_head_boundary(SWMM_Engine engine, int idx, double value,
                                                    int mode, int persist);

SWMM_ENGINE_API int swmm_forcing_node_quality(SWMM_Engine engine, int node_idx, int pollutant_idx,
                                              double mass_rate, int mode, int persist);

SWMM_ENGINE_API int swmm_forcing_node_temperature(SWMM_Engine engine, int node_idx, double value,
                                                  int mode, int persist);

SWMM_ENGINE_API int swmm_forcing_node_age(SWMM_Engine engine, int node_idx, double value, int mode,
                                          int persist);
 
/* =========================================================================
 * Link forcing
 * ========================================================================= */

SWMM_ENGINE_API int swmm_forcing_link_flow(SWMM_Engine engine, int idx, double value, int mode,
                                           int persist);

SWMM_ENGINE_API int swmm_forcing_link_setting(SWMM_Engine engine, int idx, double value, int mode,
                                              int persist);

SWMM_ENGINE_API int swmm_forcing_link_seepage(SWMM_Engine engine, int idx, double value, int mode,
                                              int persist);

SWMM_ENGINE_API int swmm_forcing_link_quality(SWMM_Engine engine, int link_idx, int pollutant_idx,
                                              double value, int mode, int persist);
 
/* =========================================================================
 * Subcatchment forcing
 * ========================================================================= */

SWMM_ENGINE_API int swmm_forcing_subcatch_rainfall(SWMM_Engine engine, int idx, double value,
                                                   int mode, int persist);

SWMM_ENGINE_API int swmm_forcing_subcatch_evap(SWMM_Engine engine, int idx, double value, int mode,
                                               int persist);

SWMM_ENGINE_API int swmm_forcing_subcatch_snowfall(SWMM_Engine engine, int idx, double value,
                                                   int mode, int persist);

SWMM_ENGINE_API int swmm_climate_get_evap_rate(SWMM_Engine engine, double* value);
 
/* =========================================================================
 * Climate forcing (system-wide)
 * ========================================================================= */

SWMM_ENGINE_API int swmm_forcing_climate_temperature(SWMM_Engine engine, double value, int mode,
                                                     int persist);

SWMM_ENGINE_API int swmm_climate_get_temperature(SWMM_Engine engine, double* value);

SWMM_ENGINE_API int swmm_forcing_climate_wind(SWMM_Engine engine, double value, int mode,
                                              int persist);

SWMM_ENGINE_API int swmm_climate_get_wind_speed(SWMM_Engine engine, double* value);

SWMM_ENGINE_API int swmm_forcing_climate_evap(SWMM_Engine engine, double value, int mode,
                                              int persist);

SWMM_ENGINE_API int swmm_climate_set_dry_only(SWMM_Engine engine, int flag);

SWMM_ENGINE_API int swmm_climate_get_dry_only(SWMM_Engine engine, int* flag);
 
/* =========================================================================
 * Gage forcing
 * ========================================================================= */

SWMM_ENGINE_API int swmm_forcing_gage_rainfall(SWMM_Engine engine, int idx, double value, int mode,
                                               int persist);
 
/* =========================================================================
 * Clear forcing
 * ========================================================================= */
 
/* =========================================================================
 * PE4 — per-element climate
 *
 * Air temperature, humidity, wind and incoming shortwave are GLOBAL in every
 * deck and per-element ONLY here. There is no deck syntax for per-element
 * meteorology at any phase, deliberately: `ClimateState` is shared with
 * hydrology, snowmelt and evaporation, so a hand-maintained file that could
 * set a per-conduit air temperature would assert something the snowpack on
 * the subcatchment above permanently disagrees with. A caller of THIS API is
 * a coupled driver asserting the heterogeneity per step and answerable for
 * it — which is how the reference works too: HydroCouple's RHEComponent and
 * CSHComponent receive per-element meteorology through EXCHANGE ITEMS.
 *
 * Values are resolved AT THE FLUX CALL, never written into the climate
 * state, so a per-link push cannot reach snowmelt or evaporation.
 * ========================================================================= */

SWMM_ENGINE_API int swmm_forcing_element_climate(SWMM_Engine engine, int kind, int index,
                                                 int variable, double value, int mode, int persist);

SWMM_ENGINE_API int swmm_forcing_element_climate_get(SWMM_Engine engine, int kind, int index,
                                                     int variable, double* value, int* mode);

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

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