openswmm::gage Namespace Reference

Classes
struct	GageState
struct	PrecipSplit
	Result of splitting a gage's precipitation for one subcatchment. More...

Enumerations
enum class	RainType : int {   INTENSITY = 0 ,   VOLUME = 1 ,   CUMULATIVE = 2 }

Functions
double	convertRainfall (double raw_value, GageState &state)
	Convert raw rainfall value based on rain type.
PrecipSplit	splitPrecip (const SimulationContext &ctx, std::size_t sub)
	Split a subcatchment's gage precipitation into rain and snow.
void	updatePastRain (GageState &state, double current_time)
	Update past n-hour rainfall accumulation.
double	getPastRain (const GageState &state, int hours)
	Get past n-hour rainfall total.
const Table *	gageRainSeries (const SimulationContext &ctx, int gage_idx)
	The rainfall table a gage actually reads.
double	gageUnitsFactor (const SimulationContext &ctx, int gage_idx)
	The units factor the engine applies to a gage's raw values.
double	convertGageValue (double raw, int rain_type, double interval_sec, double &cumul_accum, double units_factor, double scale_factor)
	Apply the rain-type transform, units factor and scale factor.
void	updateAllGages (SimulationContext &ctx, double current_time)
	Process all gages for one timestep.
double	getReportRainfall (const SimulationContext &ctx, int gage_idx, double report_date)
	Query a gage's rainfall at a specific report date.

Variables
constexpr double	ONE_SECOND = 1.1574074e-5
	One second in days.
constexpr int	MAXPASTRAIN = 48
	Max past hours tracked.

Enumeration Type Documentation

RainType

enum class openswmm::gage::RainType : int

strong

Enumerator
INTENSITY
VOLUME
CUMULATIVE

Function Documentation

convertGageValue()

double openswmm::gage::convertGageValue	(	double	raw,
		int	rain_type,
		double	interval_sec,
		double &	cumul_accum,
		double	units_factor,
		double	scale_factor )

Apply the rain-type transform, units factor and scale factor.

The exact arithmetic updateAllGages performs, factored out so the read-back API cannot drift from what the run actually applies. Operand order is load-bearing for legacy parity: raw / interval * 3600.0 as one divide then one multiply, and units factor BEFORE scale factor.

Parameters

cumul_accum

[in/out] Running total for CUMULATIVE gages; a decrease is read as a counter reset. Ignored for other rain types, but callers walking a whole series must carry it entry to entry or the deltas are wrong.

Here is the caller graph for this function:

convertRainfall()

double openswmm::gage::convertRainfall	(	double	raw_value,
		GageState &	state )

Convert raw rainfall value based on rain type.

Parameters

raw_value	Raw value from timeseries.
state	Gage state (for accumulators, factors).

Returns

Rainfall intensity (project units/sec).

gageRainSeries()

const Table * openswmm::gage::gageRainSeries	(	const SimulationContext &	ctx,
		int	gage_idx )

The rainfall table a gage actually reads.

A FILE_RAIN gage reads its own resolved rain_series, built at load by load_external_rain_files; every other gage reads the shared table pool. Deliberately kept out of ctx.tables so an INP round-trip still emits FILE.

Returns

nullptr when the gage has no usable series (unresolvable file, or a rain-file format the loader does not support).

Here is the call graph for this function:

Here is the caller graph for this function:

gageUnitsFactor()

double openswmm::gage::gageUnitsFactor	(	const SimulationContext &	ctx,
		int	gage_idx )

The units factor the engine applies to a gage's raw values.

25.40 (MMperINCH) for a STANDARD rain-file gage in an SI project, because that loader stores float-quantized INCHES for legacy bit-parity; 1.0 for everything else.

Scoped to STAN_PRCP on purpose. USER_CSV data is stored in the project's own rain units, exactly like a [TIMESERIES] gage, so it must not be rescaled — and pinning the factor to the format keeps the legacy standard-file path byte-identical.

Here is the call graph for this function:

Here is the caller graph for this function:

getPastRain()

double openswmm::gage::getPastRain	(	const GageState &	state,
		int	hours )

Get past n-hour rainfall total.

Parameters

state	Gage state.
hours	Number of past hours (1 to MAXPASTRAIN).

Returns

Cumulative rainfall over past n hours (project depth units).

getReportRainfall()

double openswmm::gage::getReportRainfall	(	const SimulationContext &	ctx,
		int	gage_idx,
		double	report_date )

Query a gage's rainfall at a specific report date.

Matches legacy gage_setReportRainfall(): queries the gage's timeseries at the report time without advancing the cursor. Returns rainfall in user units (in/hr or mm/hr).

Parameters

ctx	Simulation context.
gage_idx	Gage index.
report_date	Absolute OADate (days since 12/30/1899) to query.

Returns

Rainfall rate in user units (in/hr or mm/hr).

Here is the call graph for this function:

Here is the caller graph for this function:

splitPrecip()

PrecipSplit openswmm::gage::splitPrecip	(	const SimulationContext &	ctx,
		std::size_t	sub )

Split a subcatchment's gage precipitation into rain and snow.

The single source of truth for the rain/snow split, mirroring legacy gage_getPrecip() (gage.c:513-523) and adding the subcatchment-level scale factors. Applies, in order:

• the IgnoreSnowmelt guard and the temperature test
• the gage snow catch factor (SCF) on the snow branch
• the subcatchment rain/snow scale factors
• conversion to internal units (ft/sec)

Both the snowpack path (SWMMEngine) and the plain runoff path (RunoffSolver) MUST route through this. They previously duplicated the logic and drifted: the snowpack path dropped the SCF entirely and the runoff path performed no split at all.

API/forcing overrides are applied by the CALLER, after this returns — they are absolute injections and are deliberately not scaled.

Parameters

ctx	Simulation context (gages, subcatchments, climate, options).
sub	Subcatchment index.

Returns

Rainfall and snowfall in ft/sec. Zero if the subcatchment has no gage.

Here is the call graph for this function:

Here is the caller graph for this function:

updateAllGages()

void openswmm::gage::updateAllGages	(	SimulationContext &	ctx,
		double	current_time )

Process all gages for one timestep.

Parameters

ctx	Simulation context (gages + timeseries accessed).
current_time	Current simulation time (seconds).

Here is the call graph for this function:

updatePastRain()

void openswmm::gage::updatePastRain	(	GageState &	state,
		double	current_time )

Update past n-hour rainfall accumulation.

Parameters

state	[in/out] Gage state.
current_time	Current simulation time (seconds from start).

Variable Documentation

MAXPASTRAIN

int openswmm::gage::MAXPASTRAIN = 48

constexpr

Max past hours tracked.

ONE_SECOND

double openswmm::gage::ONE_SECOND = 1.1574074e-5

constexpr

One second in days.