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