openswmm_forcing.h File Reference

Runtime forcing API — inject fluxes with mass-balance tracking. More...

#include "openswmm_callbacks.h"

Include dependency graph for openswmm_forcing.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros
#define	SWMM_ENGINE_API   __attribute__((visibility("default")))

Typedefs
typedef enum SWMM_ForcingMode	SWMM_ForcingMode
	How the forcing value is applied relative to the computed value.
typedef enum SWMM_ForcingPersist	SWMM_ForcingPersist
	Whether the forcing persists across timesteps.
typedef enum SWMM_ForcingType	SWMM_ForcingType
	Forcing channel identifier (for targeted clear).

Enumerations
enum	SWMM_ForcingMode {   SWMM_FORCING_NONE = 0 ,   SWMM_FORCING_OVERRIDE = 1 ,   SWMM_FORCING_ADD = 2 }
	How the forcing value is applied relative to the computed value. More...
enum	SWMM_ForcingPersist {   SWMM_FORCING_RESET = 0 ,   SWMM_FORCING_PERSIST = 1 }
	Whether the forcing persists across timesteps. More...
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 }
	Forcing channel identifier (for targeted clear). More...

Functions
SWMM_ENGINE_API int	swmm_forcing_node_lat_inflow (SWMM_Engine engine, int idx, double value, int mode, int persist)
	Force a lateral inflow at a node.
SWMM_ENGINE_API int	swmm_forcing_node_head_boundary (SWMM_Engine engine, int idx, double value, int mode, int persist)
	Force a head boundary at an outfall node.
SWMM_ENGINE_API int	swmm_forcing_node_quality (SWMM_Engine engine, int node_idx, int pollutant_idx, double mass_rate, int mode, int persist)
	Force a quality mass flux at a node.
SWMM_ENGINE_API int	swmm_forcing_link_flow (SWMM_Engine engine, int idx, double value, int mode, int persist)
	Force a flow in a link.
SWMM_ENGINE_API int	swmm_forcing_link_setting (SWMM_Engine engine, int idx, double value, int mode, int persist)
	Force a control setting on a link (pump, orifice, weir, outlet).
SWMM_ENGINE_API int	swmm_forcing_link_quality (SWMM_Engine engine, int link_idx, int pollutant_idx, double value, int mode, int persist)
	Force pollutant quality on a link.
SWMM_ENGINE_API int	swmm_forcing_subcatch_rainfall (SWMM_Engine engine, int idx, double value, int mode, int persist)
	Force rainfall on a subcatchment (bypasses gage lookup).
SWMM_ENGINE_API int	swmm_forcing_subcatch_evap (SWMM_Engine engine, int idx, double value, int mode, int persist)
	Prescribe a potential evapotranspiration (PET) rate on a subcatchment.
SWMM_ENGINE_API int	swmm_forcing_subcatch_snowfall (SWMM_Engine engine, int idx, double value, int mode, int persist)
	Prescribe snowfall on a subcatchment.
SWMM_ENGINE_API int	swmm_climate_get_evap_rate (SWMM_Engine engine, double *value)
	Get the current climate-derived evaporation rate.
SWMM_ENGINE_API int	swmm_forcing_climate_temperature (SWMM_Engine engine, double value, int mode, int persist)
	Prescribe the air temperature used for snowmelt and temperature-derived evaporation.
SWMM_ENGINE_API int	swmm_climate_get_temperature (SWMM_Engine engine, double *value)
	Get the current air temperature (read-only).
SWMM_ENGINE_API int	swmm_forcing_climate_wind (SWMM_Engine engine, double value, int mode, int persist)
	Prescribe the wind speed used in rain-on-snow melt.
SWMM_ENGINE_API int	swmm_climate_get_wind_speed (SWMM_Engine engine, double *value)
	Get the current wind speed (read-only).
SWMM_ENGINE_API int	swmm_forcing_climate_evap (SWMM_Engine engine, double value, int mode, int persist)
	Prescribe the system-wide evaporation rate.
SWMM_ENGINE_API int	swmm_climate_set_dry_only (SWMM_Engine engine, int flag)
	Set the evaporation DRY_ONLY option at runtime.
SWMM_ENGINE_API int	swmm_climate_get_dry_only (SWMM_Engine engine, int *flag)
	Get the evaporation DRY_ONLY option.
SWMM_ENGINE_API int	swmm_forcing_gage_rainfall (SWMM_Engine engine, int idx, double value, int mode, int persist)
	Force rainfall on a rain gage (affects all linked subcatchments).
SWMM_ENGINE_API int	swmm_forcing_clear (SWMM_Engine engine, int type, int idx)
	Clear forcing on a specific element and channel.
SWMM_ENGINE_API int	swmm_forcing_clear_all (SWMM_Engine engine)
	Clear ALL forcings on ALL elements.

Detailed Description

Runtime forcing API — inject fluxes with mass-balance tracking.

Provides per-element runtime forcing of lateral inflows, head boundaries, rainfall, evaporation, link settings, and quality mass fluxes. Each forcing specifies:

• mode: NONE (disabled), OVERRIDE (replace computed value), ADD (add to computed value)
• persistence: RESET (auto-clear after each timestep), PERSIST (keep until explicitly cleared)

Forced volumes are tracked in the mass balance and reported separately via SWMM_ROUTING_FORCING.

All forcing functions require SWMM_STATE_RUNNING.

Lifecycle

swmm_engine_start(e, 1);
while (swmm_engine_step(e, &elapsed) == SWMM_OK && elapsed > 0) {
    // Set forcings for this step (or let PERSIST carry forward)
    swmm_forcing_node_lat_inflow(e, j1, 10.0,
        SWMM_FORCING_ADD, SWMM_FORCING_PERSIST);
 
    // ... step runs, forcing is applied, mass balance tracks it ...
    // RESET forcings auto-clear; PERSIST forcings remain
}
swmm_engine_end(e);

Note

All value parameters are in the simulation's internal units (ft, sec, CFS) unless otherwise noted. Rainfall values are in user display units (in/hr for US, mm/hr for SI) — the engine converts internally.

Macro Definition Documentation

SWMM_ENGINE_API

#define SWMM_ENGINE_API   __attribute__((visibility("default")))

Typedef Documentation

SWMM_ForcingMode

typedef enum SWMM_ForcingMode SWMM_ForcingMode

How the forcing value is applied relative to the computed value.

SWMM_ForcingPersist

typedef enum SWMM_ForcingPersist SWMM_ForcingPersist

Whether the forcing persists across timesteps.

SWMM_ForcingType

typedef enum SWMM_ForcingType SWMM_ForcingType

Forcing channel identifier (for targeted clear).

Enumeration Type Documentation

SWMM_ForcingMode

enum SWMM_ForcingMode

How the forcing value is applied relative to the computed value.

Enumerator
SWMM_FORCING_NONE	No forcing — use model-computed value.
SWMM_FORCING_OVERRIDE	Replace computed value with user value.
SWMM_FORCING_ADD	Add user value to computed value.

SWMM_ForcingPersist

enum SWMM_ForcingPersist

Whether the forcing persists across timesteps.

Enumerator
SWMM_FORCING_RESET	Auto-clear after each timestep.
SWMM_FORCING_PERSIST	Keep until explicitly cleared.

SWMM_ForcingType

enum SWMM_ForcingType

Forcing channel identifier (for targeted clear).

Enumerator
SWMM_FORCE_NODE_LAT_INFLOW
SWMM_FORCE_NODE_HEAD_BOUNDARY
SWMM_FORCE_NODE_QUALITY
SWMM_FORCE_LINK_FLOW
SWMM_FORCE_LINK_SETTING
SWMM_FORCE_SUBCATCH_RAINFALL
SWMM_FORCE_SUBCATCH_EVAP
SWMM_FORCE_GAGE_RAINFALL
SWMM_FORCE_CLIMATE_TEMPERATURE	System-wide; idx ignored.
SWMM_FORCE_CLIMATE_WIND	System-wide; idx ignored.
SWMM_FORCE_SUBCATCH_SNOWFALL
SWMM_FORCE_CLIMATE_EVAP	System-wide; idx ignored.
SWMM_FORCE_LINK_QUALITY