C API implementation — runtime forcing with mass-balance tracking. More...

#include "openswmm_api_common.hpp"
#include "../../../include/openswmm/engine/openswmm_forcing.h"
#include "../data/ForcingData.hpp"
#include "UnitConversion.hpp"

Include dependency graph for openswmm_forcing_impl.cpp:

Functions
SWMM_ENGINE_API int	swmm_forcing_node_lat_inflow (SWMM_Engine engine, int idx, double value, int mode, int persist)
	Register lateral user-flow overlay for the next step(s).

SWMM_ENGINE_API int	swmm_forcing_node_head_boundary (SWMM_Engine engine, int idx, double value, int mode, int persist)
	Register outfall head-boundary overlay for the next step(s).

SWMM_ENGINE_API int	swmm_forcing_node_quality (SWMM_Engine engine, int node_idx, int pollutant_idx, double mass_rate, int mode, int persist)
	Register direct pollutant concentration forcing on a node.

SWMM_ENGINE_API int	swmm_forcing_node_temperature (SWMM_Engine engine, int node_idx, double value, int mode, int persist)
	Register reserved-species node water temperature forcing.

SWMM_ENGINE_API int	swmm_forcing_node_age (SWMM_Engine engine, int node_idx, double value, int mode, int persist)
	Register reserved-species node water age forcing.

SWMM_ENGINE_API int	swmm_forcing_link_flow (SWMM_Engine engine, int idx, double value, int mode, int persist)
	Register link flow-state forcing for the next step(s).

SWMM_ENGINE_API int	swmm_forcing_link_setting (SWMM_Engine engine, int idx, double value, int mode, int persist)
	Register link setting forcing for the next step(s).

SWMM_ENGINE_API int	swmm_forcing_link_seepage (SWMM_Engine engine, int idx, double value, int mode, int persist)
	Register conduit groundwater-exchange forcing for the next step(s).

SWMM_ENGINE_API int	swmm_forcing_subcatch_rainfall (SWMM_Engine engine, int idx, double value, int mode, int persist)
	Register subcatchment rainfall forcing for the next step(s).

SWMM_ENGINE_API int	swmm_forcing_subcatch_evap (SWMM_Engine engine, int idx, double value, int mode, int persist)
	Register subcatchment potential-evaporation forcing for the next step(s).

SWMM_ENGINE_API int	swmm_climate_get_evap_rate (SWMM_Engine engine, double *value)
	Read the current broadcast evaporation rate.

SWMM_ENGINE_API int	swmm_forcing_subcatch_snowfall (SWMM_Engine engine, int idx, double value, int mode, int persist)
	Register subcatchment snowfall forcing for the next step(s).

SWMM_ENGINE_API int	swmm_forcing_climate_temperature (SWMM_Engine engine, double value, int mode, int persist)
	Register system air temperature forcing.

SWMM_ENGINE_API int	swmm_climate_get_temperature (SWMM_Engine engine, double *value)
	Read the current air temperature.

SWMM_ENGINE_API int	swmm_forcing_climate_wind (SWMM_Engine engine, double value, int mode, int persist)
	Register system wind speed forcing.

SWMM_ENGINE_API int	swmm_climate_get_wind_speed (SWMM_Engine engine, double *value)
	Read the current wind speed.

SWMM_ENGINE_API int	swmm_forcing_climate_evap (SWMM_Engine engine, double value, int mode, int persist)
	Register system evaporation rate forcing.

SWMM_ENGINE_API int	swmm_climate_set_dry_only (SWMM_Engine engine, int flag)
	Set the stored evaporation DRY_ONLY flag.

SWMM_ENGINE_API int	swmm_climate_get_dry_only (SWMM_Engine engine, int *flag)
	Read the stored evaporation DRY_ONLY flag.

SWMM_ENGINE_API int	swmm_forcing_link_quality (SWMM_Engine engine, int link_idx, int pollutant_idx, double value, int mode, int persist)
	Register direct pollutant concentration forcing on a link.

SWMM_ENGINE_API int	swmm_forcing_gage_rainfall (SWMM_Engine engine, int idx, double value, int mode, int persist)
	Register gage rainfall forcing for the next step(s).

SWMM_ENGINE_API int	swmm_forcing_clear (SWMM_Engine engine, int type, int idx)
	Disable selected forcing modes without clearing their stored values.

SWMM_ENGINE_API int	swmm_forcing_element_climate (SWMM_Engine engine, int kind, int index, int variable, double value, int mode, int persist)
	Register an element-local atmospheric heat-flux forcing.

SWMM_ENGINE_API int	swmm_forcing_element_climate_get (SWMM_Engine engine, int kind, int index, int variable, double value, int mode)
	Read an element-local registered climate prescription.

SWMM_ENGINE_API int	swmm_forcing_clear_all (SWMM_Engine engine)
	Clear all ForcingData channels on the engine.

Detailed Description

C API implementation — runtime forcing with mass-balance tracking.

See also: include/openswmm/engine/openswmm_forcing.h

Author: Caleb Buahin caleb.nosp@m..bua.nosp@m.hin@g.nosp@m.mail.nosp@m..com

Copyright: Copyright (c) 2026 Caleb Buahin. All rights reserved.

License: Apache-2.0

Function Documentation

◆ swmm_climate_get_dry_only()

SWMM_ENGINE_API int swmm_climate_get_dry_only	(	SWMM_Engine	engine,
		int *	flag )

Read the stored evaporation DRY_ONLY flag.

Parameters

[in]	engine	Non-null live engine.
[out]	flag	Optional destination: 0 disabled, 1 enabled.

Returns: SWMM_OK, including NULL flag; SWMM_ERR_BADHANDLE for null engine.

◆ swmm_climate_get_evap_rate()

SWMM_ENGINE_API int swmm_climate_get_evap_rate	(	SWMM_Engine	engine,
		double *	value )

Read the current broadcast evaporation rate.

Reads current stored climate state; before climate initialization/update this need not represent a sampled source. Evaporation is the broadcast state, excluding a per-subcatchment PET override.

Parameters

[in]	engine	Non-null live engine; no RUNNING guard is applied to this getter.
[out]	value	Optional destination in in/day US, mm/day SI.

Returns: SWMM_OK, including NULL value; SWMM_ERR_BADHANDLE for null engine.

Here is the call graph for this function:

◆ swmm_climate_get_temperature()

SWMM_ENGINE_API int swmm_climate_get_temperature	(	SWMM_Engine	engine,
		double *	value )

Read the current air temperature.

Reads current stored climate state; before climate initialization/update this need not represent a sampled source. Evaporation is the broadcast state, excluding a per-subcatchment PET override.

Parameters

[in]	engine	Non-null live engine; no RUNNING guard is applied to this getter.
[out]	value	Optional destination in degrees F US, degrees C SI.

Returns: SWMM_OK, including NULL value; SWMM_ERR_BADHANDLE for null engine.

Here is the call graph for this function:

◆ swmm_climate_get_wind_speed()

SWMM_ENGINE_API int swmm_climate_get_wind_speed	(	SWMM_Engine	engine,
		double *	value )

Read the current wind speed.

Reads current stored climate state; before climate initialization/update this need not represent a sampled source. Evaporation is the broadcast state, excluding a per-subcatchment PET override.

Parameters

[in]	engine	Non-null live engine; no RUNNING guard is applied to this getter.
[out]	value	Optional destination in mph US, km/hr SI.

Returns: SWMM_OK, including NULL value; SWMM_ERR_BADHANDLE for null engine.

Here is the call graph for this function:

◆ swmm_climate_set_dry_only()

SWMM_ENGINE_API int swmm_climate_set_dry_only	(	SWMM_Engine	engine,
		int	flag )

Set the stored evaporation DRY_ONLY flag.

A subcatchment PET OVERRIDE bypasses the native DRY_ONLY rule.

Parameters

[in]	engine	Non-null live engine; no RUNNING guard is imposed.
[in]	flag	0 permits evaporation in rainfall; nonzero suppresses native evaporation during rainfall.

Returns: SWMM_OK, or SWMM_ERR_BADHANDLE for null engine.

◆ swmm_forcing_clear()

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

Disable selected forcing modes without clearing their stored values.

Does not remove the separate persistent user_lat_flow/user_conc_mass_flux fields. Per-element climate can be cleared for both kinds through the shared channel spelling; mode NONE restores use of the global/model input.

Parameters

[in]	engine	Non-null live engine; this clear operation has no RUNNING guard.
[in]	type	SWMM_ForcingType channel. NODE_QUALITY/LINK_QUALITY clear every pollutant for the indexed element.
[in]	idx	Zero-based target element index; ignored for global climate channels. For element-climate channels, clears this index in BOTH node/link tables where present; out-of-range element-climate indices are harmless no-ops.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for invalid ordinary element indices, or SWMM_ERR_BADPARAM for an unknown type.

Here is the call graph for this function:

◆ swmm_forcing_clear_all()

SWMM_ENGINE_API int swmm_forcing_clear_all ( SWMM_Engine engine )

Clear all ForcingData channels on the engine.

Calls the forcing-store clear operation, including reserved-species and element-climate prescriptions. Does not promise to reset state already changed by previous physics or the separate persistent user inflow/quality fields.

Parameters

[in] engine Non-null live engine; no RUNNING guard is applied.

Returns: SWMM_OK, or SWMM_ERR_BADHANDLE for null engine.

◆ swmm_forcing_climate_evap()

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

Register system evaporation rate forcing.

Converted to internal ft/s after sources/monthly adjustments; OVERRIDE refuses value<0. Per-subcatchment PET forcing takes precedence. No separate finite-value check.

Parameters

[in]	engine	Non-null RUNNING engine; exclusive access is required. Call between steps or from a callback where the selected runtime setter is permitted.
[in]	value	in/day US, mm/day SI.
[in]	mode	SWMM_FORCING_NONE (0) disables this channel, OVERRIDE (1) replaces its input/state, ADD (2) applies the channel-specific addition.
[in]	persist	SWMM_FORCING_RESET (0) clears after the next physical step; SWMM_FORCING_PERSIST (1) retains until replaced/cleared.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_LIFECYCLE outside RUNNING, SWMM_ERR_BADINDEX for invalid element/pollutant index, or SWMM_ERR_BADPARAM for invalid mode/persistence or channel-specific refusal.

Here is the call graph for this function:

◆ swmm_forcing_climate_temperature()

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

Register system air temperature forcing.

OVERRIDE replaces the climate source before derived atmospheric/Hargreaves quantities and bypasses monthly adjustment. ADD is a temperature DIFFERENCE; SI conversion scales by 1.8 without a 32-degree offset.

Parameters

[in]	engine	Non-null RUNNING engine; exclusive access is required. Call between steps or from a callback where the selected runtime setter is permitted.
[in]	value	degrees F US, degrees C SI.
[in]	mode	SWMM_FORCING_NONE (0) disables this channel, OVERRIDE (1) replaces its input/state, ADD (2) applies the channel-specific addition.
[in]	persist	SWMM_FORCING_RESET (0) clears after the next physical step; SWMM_FORCING_PERSIST (1) retains until replaced/cleared.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_LIFECYCLE outside RUNNING, SWMM_ERR_BADINDEX for invalid element/pollutant index, or SWMM_ERR_BADPARAM for invalid mode/persistence or channel-specific refusal.

Here is the call graph for this function:

◆ swmm_forcing_climate_wind()

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

Register system wind speed forcing.

Converted to internal mph; OVERRIDE refuses value<0. No separate finite-value check; ADD may be signed.

Parameters

[in]	engine	Non-null RUNNING engine; exclusive access is required. Call between steps or from a callback where the selected runtime setter is permitted.
[in]	value	mph US, km/hr SI.
[in]	mode	SWMM_FORCING_NONE (0) disables this channel, OVERRIDE (1) replaces its input/state, ADD (2) applies the channel-specific addition.
[in]	persist	SWMM_FORCING_RESET (0) clears after the next physical step; SWMM_FORCING_PERSIST (1) retains until replaced/cleared.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_LIFECYCLE outside RUNNING, SWMM_ERR_BADINDEX for invalid element/pollutant index, or SWMM_ERR_BADPARAM for invalid mode/persistence or channel-specific refusal.

Here is the call graph for this function:

◆ swmm_forcing_element_climate()

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

Register an element-local atmospheric heat-flux forcing.

Resolved at the element heat-flux evaluation and does not modify the global climate state used by hydrology, snow or evaporation. The caller owns the heterogeneous forcing schedule; the API does not validate a matching active heat model.

Parameters

[in]	engine	Non-null live engine; this setter has no RUNNING guard and lazily allocates its channel.
[in]	kind	SWMM_HEAT_ELEM_NODE (0) or SWMM_HEAT_ELEM_LINK (1); subcatchments are unsupported.
[in]	index	Zero-based index within the selected node/link table.
[in]	variable	SWMM_FORCE_ELEM_AIR_TEMPERATURE, HUMIDITY, WIND_SPEED or SHORTWAVE.
[in]	value	Air temperature degrees F/C by project system (ADD is a difference), humidity %, wind mph/km/hr, or shortwave W/m2. No finite/range validation is applied.
[in]	mode	SWMM_FORCING_OVERRIDE or ADD only; NONE is refused here. Use targeted clear to disable.
[in]	persist	SWMM_FORCING_RESET (0) clears after the next physical step; SWMM_FORCING_PERSIST (1) retains until replaced/cleared.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for invalid element index, or SWMM_ERR_BADPARAM for unsupported kind/channel/mode/persistence.

◆ swmm_forcing_element_climate_get()

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

Read an element-local registered climate prescription.

Returns the prescription and mode, not the resolved atmospheric value including global source/other heat calculations.

Parameters

[in]	engine	Non-null live engine; no RUNNING guard.
[in]	kind	SWMM_HEAT_ELEM_NODE (0) or SWMM_HEAT_ELEM_LINK (1); subcatchments are unsupported.
[in]	index	Zero-based index within the selected node/link table.
[in]	variable	SWMM_FORCE_ELEM_AIR_TEMPERATURE, HUMIDITY, WIND_SPEED or SHORTWAVE.
[out]	value	Optional output in the same display units as registration; zero when channel is absent/disabled. Temperature ADD is a difference.
[out]	mode	Optional output: NONE when absent/disabled, otherwise OVERRIDE or ADD.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for invalid index, or SWMM_ERR_BADPARAM for unsupported kind/channel.

◆ swmm_forcing_gage_rainfall()

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

Register gage rainfall forcing for the next step(s).

Affects linked subcatchments through gage rainfall assembly, subject to IGNORE_RAINFALL. ADD resolves the unforced rate each step to avoid repeated accumulation into a held rate. No independent finite/nonnegative validation is applied.

Parameters

[in]	engine	Non-null RUNNING engine; exclusive access is required. Call between steps or from a callback where the selected runtime setter is permitted.
[in]	idx	Zero-based gage index.
[in]	value	project rainfall intensity (in/hr US, mm/hr SI).
[in]	mode	SWMM_FORCING_NONE (0) disables this channel, OVERRIDE (1) replaces its input/state, ADD (2) applies the channel-specific addition.
[in]	persist	SWMM_FORCING_RESET (0) clears after the next physical step; SWMM_FORCING_PERSIST (1) retains until replaced/cleared.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_LIFECYCLE outside RUNNING, SWMM_ERR_BADINDEX for invalid element/pollutant index, or SWMM_ERR_BADPARAM for invalid mode/persistence or channel-specific refusal.

◆ swmm_forcing_link_flow()

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

Register link flow-state forcing for the next step(s).

Applied to the current link-flow state before physics. It is not a persistent hydraulic boundary condition or iterative solver constraint; later routing can change flow. ADD increments the current state at each application.

Parameters

[in]	engine	Non-null RUNNING engine; exclusive access is required. Call between steps or from a callback where the selected runtime setter is permitted.
[in]	idx	Zero-based link index.
[in]	value	internal ft3/s (CFS) in every project.
[in]	mode	SWMM_FORCING_NONE (0) disables this channel, OVERRIDE (1) replaces its input/state, ADD (2) applies the channel-specific addition.
[in]	persist	SWMM_FORCING_RESET (0) clears after the next physical step; SWMM_FORCING_PERSIST (1) retains until replaced/cleared.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_LIFECYCLE outside RUNNING, SWMM_ERR_BADINDEX for invalid element/pollutant index, or SWMM_ERR_BADPARAM for invalid mode/persistence or channel-specific refusal.

◆ swmm_forcing_link_quality()

SWMM_ENGINE_API int swmm_forcing_link_quality	(	SWMM_Engine	engine,
		int	link_idx,
		int	pollutant_idx,
		double	value,
		int	mode,
		int	persist )

Register direct pollutant concentration forcing on a link.

Current ADD implementation increments concentration directly and books value*dt in the forcing-quality ledger; it does not normalize a supplied amount rate by water volume. OVERRIDE is a direct published-state assignment rather than a conservative mass injection. Link application clamps the resulting concentration to nonnegative after quality routing.

Parameters

[in]	engine	Non-null RUNNING engine; exclusive access is required. Call between steps or from a callback where the selected runtime setter is permitted.
[in]	link_idx	Zero-based existing link index.
[in]	pollutant_idx	Zero-based existing pollutant index.
[in]	value	Raw value interpreted by the current application path: OVERRIDE sets concentration in pollutant concentration units; ADD directly adds this value to concentration each step.
[in]	mode	SWMM_FORCING_NONE (0) disables this channel, OVERRIDE (1) replaces its input/state, ADD (2) applies the channel-specific addition.
[in]	persist	SWMM_FORCING_RESET (0) clears after the next physical step; SWMM_FORCING_PERSIST (1) retains until replaced/cleared.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_LIFECYCLE outside RUNNING, SWMM_ERR_BADINDEX for invalid element/pollutant index, or SWMM_ERR_BADPARAM for invalid mode/persistence or channel-specific refusal.

◆ swmm_forcing_link_seepage()

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

Register conduit groundwater-exchange forcing for the next step(s).

OVERRIDE replaces native seepage and ADD augments it; negative exchange is a gaining reach booked as SWMM_ROUTING_LINK_GW_INFLOW. Non-conduit links accept the stored prescription but have no seepage consumer. With internal TWO_WAY/AUTO aquifer exchange active, the aquifer is also debited/credited; external-only coupling must leave the internal aquifer out of the reach.

Parameters

[in]	engine	Non-null RUNNING engine; exclusive access is required. Call between steps or from a callback where the selected runtime setter is permitted.
[in]	idx	Zero-based link index.
[in]	value	internal ft3/s (CFS), positive OUT of the conduit in every project.
[in]	mode	SWMM_FORCING_NONE (0) disables this channel, OVERRIDE (1) replaces its input/state, ADD (2) applies the channel-specific addition.
[in]	persist	SWMM_FORCING_RESET (0) clears after the next physical step; SWMM_FORCING_PERSIST (1) retains until replaced/cleared.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_LIFECYCLE outside RUNNING, SWMM_ERR_BADINDEX for invalid element/pollutant index, or SWMM_ERR_BADPARAM for invalid mode/persistence or channel-specific refusal.

◆ swmm_forcing_link_setting()

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

Register link setting forcing for the next step(s).

Application sets both current and target setting for OVERRIDE; ADD increments current setting then sets the target to it. The setter does not clamp/range-check values or remove control rules.

Parameters

[in]	engine	Non-null RUNNING engine; exclusive access is required. Call between steps or from a callback where the selected runtime setter is permitted.
[in]	idx	Zero-based link index.
[in]	value	dimensionless opening/speed (conventionally 0..1).
[in]	mode	SWMM_FORCING_NONE (0) disables this channel, OVERRIDE (1) replaces its input/state, ADD (2) applies the channel-specific addition.
[in]	persist	SWMM_FORCING_RESET (0) clears after the next physical step; SWMM_FORCING_PERSIST (1) retains until replaced/cleared.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_LIFECYCLE outside RUNNING, SWMM_ERR_BADINDEX for invalid element/pollutant index, or SWMM_ERR_BADPARAM for invalid mode/persistence or channel-specific refusal.

◆ swmm_forcing_node_age()

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

Register reserved-species node water age forcing.

Requires WATER_AGE enabled, otherwise BADPARAM. OVERRIDE directly assigns the published state and is not a conservative injection. ADD enters the loader accumulator so it mixes with held water. Age hours are converted to seconds internally; temperature uses degrees C in all project unit systems.

Parameters

[in]	engine	Non-null RUNNING engine; exclusive access is required. Call between steps or from a callback where the selected runtime setter is permitted.
[in]	node_idx	Zero-based existing node with initialized reserved-species forcing storage.
[in]	value	OVERRIDE: hours; ADD: hours*ft3/s age-volume rate. The setter does not validate finiteness or range.
[in]	mode	SWMM_FORCING_NONE (0) disables this channel, OVERRIDE (1) replaces its input/state, ADD (2) applies the channel-specific addition.
[in]	persist	SWMM_FORCING_RESET (0) clears after the next physical step; SWMM_FORCING_PERSIST (1) retains until replaced/cleared.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_LIFECYCLE outside RUNNING, SWMM_ERR_BADINDEX for invalid element/pollutant index, or SWMM_ERR_BADPARAM for invalid mode/persistence or channel-specific refusal.

◆ swmm_forcing_node_head_boundary()

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

Register outfall head-boundary overlay for the next step(s).

Requires an OUTFALL. Only OVERRIDE is consumed by outfall stage evaluation; NONE clears and restores authored behavior. ADD passes this setter validation but is not applied by the stage consumer. Does not rewrite the authored outfall type or parameter.

Parameters

[in]	engine	Non-null RUNNING engine; exclusive access is required. Call between steps or from a callback where the selected runtime setter is permitted.
[in]	idx	Zero-based node index.
[in]	value	internal datum feet (ft) in every project.
[in]	mode	SWMM_FORCING_NONE (0) disables this channel, OVERRIDE (1) replaces its input/state, ADD (2) applies the channel-specific addition.
[in]	persist	SWMM_FORCING_RESET (0) clears after the next physical step; SWMM_FORCING_PERSIST (1) retains until replaced/cleared.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_LIFECYCLE outside RUNNING, SWMM_ERR_BADINDEX for invalid element/pollutant index, or SWMM_ERR_BADPARAM for invalid mode/persistence or channel-specific refusal.

◆ swmm_forcing_node_lat_inflow()

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

Register lateral user-flow overlay for the next step(s).

Overlays the persistent user_lat_flow contribution: OVERRIDE replaces that runtime contribution and ADD adds to it; other authored inflow pathways remain separately assembled. An ADD prescription is reapplied per step without compounding its stored baseline.

Parameters

[in]	engine	Non-null RUNNING engine; exclusive access is required. Call between steps or from a callback where the selected runtime setter is permitted.
[in]	idx	Zero-based node index.
[in]	value	internal ft3/s (CFS) for every project, including SI.
[in]	mode	SWMM_FORCING_NONE (0) disables this channel, OVERRIDE (1) replaces its input/state, ADD (2) applies the channel-specific addition.
[in]	persist	SWMM_FORCING_RESET (0) clears after the next physical step; SWMM_FORCING_PERSIST (1) retains until replaced/cleared.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_LIFECYCLE outside RUNNING, SWMM_ERR_BADINDEX for invalid element/pollutant index, or SWMM_ERR_BADPARAM for invalid mode/persistence or channel-specific refusal.

◆ swmm_forcing_node_quality()

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

Register direct pollutant concentration forcing on a node.

Current ADD implementation increments concentration directly and books value*dt in the forcing-quality ledger; it does not normalize a supplied amount rate by water volume. OVERRIDE is a direct published-state assignment rather than a conservative mass injection. For a conservative persistent node amount-rate injection, use swmm_node_set_quality_mass_flux().

Parameters

[in]	engine	Non-null RUNNING engine; exclusive access is required. Call between steps or from a callback where the selected runtime setter is permitted.
[in]	node_idx	Zero-based existing node index.
[in]	pollutant_idx	Zero-based existing pollutant index.
[in]	mass_rate	Raw value interpreted by the current application path: OVERRIDE sets concentration in pollutant concentration units; ADD directly adds this value to concentration each step.
[in]	mode	SWMM_FORCING_NONE (0) disables this channel, OVERRIDE (1) replaces its input/state, ADD (2) applies the channel-specific addition.
[in]	persist	SWMM_FORCING_RESET (0) clears after the next physical step; SWMM_FORCING_PERSIST (1) retains until replaced/cleared.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_LIFECYCLE outside RUNNING, SWMM_ERR_BADINDEX for invalid element/pollutant index, or SWMM_ERR_BADPARAM for invalid mode/persistence or channel-specific refusal.

◆ swmm_forcing_node_temperature()

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

Register reserved-species node water temperature forcing.

Requires HEAT_TRANSPORT enabled, otherwise BADPARAM. OVERRIDE directly assigns the published state and is not a conservative injection. ADD enters the loader accumulator so it mixes with held water. Age hours are converted to seconds internally; temperature uses degrees C in all project unit systems.

Parameters

[in]	engine	Non-null RUNNING engine; exclusive access is required. Call between steps or from a callback where the selected runtime setter is permitted.
[in]	node_idx	Zero-based existing node with initialized reserved-species forcing storage.
[in]	value	OVERRIDE: degrees C; ADD: degrees C*ft3/s temperature-volume rate. The setter does not validate finiteness or range.
[in]	mode	SWMM_FORCING_NONE (0) disables this channel, OVERRIDE (1) replaces its input/state, ADD (2) applies the channel-specific addition.
[in]	persist	SWMM_FORCING_RESET (0) clears after the next physical step; SWMM_FORCING_PERSIST (1) retains until replaced/cleared.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_LIFECYCLE outside RUNNING, SWMM_ERR_BADINDEX for invalid element/pollutant index, or SWMM_ERR_BADPARAM for invalid mode/persistence or channel-specific refusal.

◆ swmm_forcing_subcatch_evap()

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

Register subcatchment potential-evaporation forcing for the next step(s).

Converted to internal ft/s at registration. Overrides/augments climate PET for surface/LID/upper-zone groundwater evaporation; OVERRIDE bypasses DRY_ONLY and monthly adjustments. Actual loss is capped by available water. This setter does not reject negative or nonfinite values.

Parameters

[in]	engine	Non-null RUNNING engine; exclusive access is required. Call between steps or from a callback where the selected runtime setter is permitted.
[in]	idx	Zero-based subcatchment index.
[in]	value	project evaporation rate (in/day US, mm/day SI).
[in]	mode	SWMM_FORCING_NONE (0) disables this channel, OVERRIDE (1) replaces its input/state, ADD (2) applies the channel-specific addition.
[in]	persist	SWMM_FORCING_RESET (0) clears after the next physical step; SWMM_FORCING_PERSIST (1) retains until replaced/cleared.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_LIFECYCLE outside RUNNING, SWMM_ERR_BADINDEX for invalid element/pollutant index, or SWMM_ERR_BADPARAM for invalid mode/persistence or channel-specific refusal.

Here is the call graph for this function:

◆ swmm_forcing_subcatch_rainfall()

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

Register subcatchment rainfall forcing for the next step(s).

Consumed in runoff rainfall assembly, bypassing/augmenting gage lookup according to mode. The setter stores the display rate and does not independently reject negative or nonfinite values.

Parameters

[in]	engine	Non-null RUNNING engine; exclusive access is required. Call between steps or from a callback where the selected runtime setter is permitted.
[in]	idx	Zero-based subcatchment index.
[in]	value	project rainfall intensity (in/hr US, mm/hr SI).
[in]	mode	SWMM_FORCING_NONE (0) disables this channel, OVERRIDE (1) replaces its input/state, ADD (2) applies the channel-specific addition.
[in]	persist	SWMM_FORCING_RESET (0) clears after the next physical step; SWMM_FORCING_PERSIST (1) retains until replaced/cleared.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_LIFECYCLE outside RUNNING, SWMM_ERR_BADINDEX for invalid element/pollutant index, or SWMM_ERR_BADPARAM for invalid mode/persistence or channel-specific refusal.

◆ swmm_forcing_subcatch_snowfall()

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

Register subcatchment snowfall forcing for the next step(s).

Converted to internal ft/s. OVERRIDE refuses values<0; ADD may be signed. Meaningful for an assigned snow pack, replacing/augmenting temperature-split snowfall for accumulation, plowing and melt. No independent finite-value validation is applied.

Parameters

[in]	engine	Non-null RUNNING engine; exclusive access is required. Call between steps or from a callback where the selected runtime setter is permitted.
[in]	idx	Zero-based subcatchment index.
[in]	value	snow-water-equivalent intensity (in/hr US, mm/hr SI).
[in]	mode	SWMM_FORCING_NONE (0) disables this channel, OVERRIDE (1) replaces its input/state, ADD (2) applies the channel-specific addition.
[in]	persist	SWMM_FORCING_RESET (0) clears after the next physical step; SWMM_FORCING_PERSIST (1) retains until replaced/cleared.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_LIFECYCLE outside RUNNING, SWMM_ERR_BADINDEX for invalid element/pollutant index, or SWMM_ERR_BADPARAM for invalid mode/persistence or channel-specific refusal.

Here is the call graph for this function:

Functions

Detailed Description

Function Documentation

◆ swmm_climate_get_dry_only()

◆ swmm_climate_get_evap_rate()

◆ swmm_climate_get_temperature()

◆ swmm_climate_get_wind_speed()

◆ swmm_climate_set_dry_only()

◆ swmm_forcing_clear()

◆ swmm_forcing_clear_all()

◆ swmm_forcing_climate_evap()

◆ swmm_forcing_climate_temperature()

◆ swmm_forcing_climate_wind()

◆ swmm_forcing_element_climate()

◆ swmm_forcing_element_climate_get()

◆ swmm_forcing_gage_rainfall()

◆ swmm_forcing_link_flow()

◆ swmm_forcing_link_quality()

◆ swmm_forcing_link_seepage()

◆ swmm_forcing_link_setting()

◆ swmm_forcing_node_age()

◆ swmm_forcing_node_head_boundary()

◆ swmm_forcing_node_lat_inflow()

◆ swmm_forcing_node_quality()

◆ swmm_forcing_node_temperature()

◆ swmm_forcing_subcatch_evap()

◆ swmm_forcing_subcatch_rainfall()

◆ swmm_forcing_subcatch_snowfall()