Rain records, accepted runoff-clock state and read-only report lookups. Context routines require aligned initialized gage/subcatchment arrays, valid project units and ordered finite table x/y pairs unless stated otherwise. State mutations are immediate; serialize updates with reads and use private copies for trials. Only precipitation splits convert rates to internal ft/s. More...

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)
	Transform one raw rain record with standalone GageState factors.

PrecipSplit	splitPrecip (const SimulationContext &ctx, std::size_t sub)
	Split a subcatchment's current gage intensity into internal rain and snow.

void	updatePastRain (GageState &state, int time_step)
	Accumulate a standalone gage's held intensity into completed-hour history.

void	updatePastRain (SimulationContext &ctx, int time_step)
	Accumulate every gage's current held rate over one accepted runoff step.

double	getPastRain (const GageState &state, int hours)
	Sum completed hourly depth buckets, excluding the current partial hour.

const Table *	gageRainSeries (const SimulationContext &ctx, int gage_idx)
	Borrow the actual resolved source table for a gage.

int	gageSeriesRainType (const SimulationContext &ctx, int gage_idx)
	Select the transform appropriate to resolved source storage.

double	gageUnitsFactor (const SimulationContext &ctx, int gage_idx)
	Return the source-storage-to-project rainfall depth multiplier.

double	convertGageValue (double raw, int rain_type, double interval_sec, double &cumul_accum, double units_factor, double scale_factor)
	Transform one source record and apply units then scale factors.

bool	gageIsUsed (const SimulationContext &ctx, int gage_idx)
	Test whether the model or enabled rainfall mesh consumes a gage.

double	gageNextRainDate (const SimulationContext &ctx, int gage_idx, double t)
	Read the next runoff-clock rainfall boundary from cached gage state.

double	gageNextRateChange (const SimulationContext &ctx, int gage_idx, double date, double limit)
	Forecast the end of the current held rain rate without changing source state.

void	updateAllGages (SimulationContext &ctx, double current_time)
	Advance used gage record state and publish current effective rainfall.

double	getReportRainfall (const SimulationContext &ctx, int gage_idx, double report_date)
	Query rainfall using the most recently advanced runoff-gage state.

double	getReportRainfallFromSeries (const SimulationContext &ctx, int gage_idx, double report_date)
	Query report-time source records independently of a later runoff cursor.

Variables
constexpr double	ONE_SECOND = 1.1574074e-5
	One second in days.

constexpr int	MAXPASTRAIN = 48
	Max past hours tracked.

Detailed Description

Rain records, accepted runoff-clock state and read-only report lookups. Context routines require aligned initialized gage/subcatchment arrays, valid project units and ordered finite table x/y pairs unless stated otherwise. State mutations are immediate; serialize updates with reads and use private copies for trials. Only precipitation splits convert rates to internal ft/s.

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 )

Transform one source record and apply units then scale factors.

Parameters

	raw	Raw intensity per project hour or interval/cumulative depth, depending on type.
	rain_type	Zero intensity, one volume, two cumulative; other integers fall through as raw intensity. No enum/finite validation occurs.
	interval_sec	Positive recording seconds for depth transforms; nonpositive interval skips the transform and returns scaled raw, unlike convertRainfall().
[in,out]	cumul_accum	Previous cumulative raw depth; on a positive-interval cumulative record a decrease resets the counter, otherwise differences it. Retained for other types/invalid intervals. Carry across records in source order.
	units_factor	Source-depth to project-depth multiplier.
	scale_factor	Dimensionless gage scale; no monthly adjustment applied here.

Returns: Intensity per project hour, preserving divide-then-multiply and factor order. Negative/nonfinite inputs are not rejected or clamped.

Here is the caller graph for this function:

◆ convertRainfall()

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

Transform one raw rain record with standalone GageState factors.

Parameters

	raw_value	Intensity in project in/hr or mm/hr, or interval/cumulative depth in project inches/mm according to state.rain_type; caller qualifies finite data.
[in,out]	state	Recording interval seconds and units/scale/monthly factors; only rain_accum changes for CUMULATIVE with a positive interval. A counter decrease starts a new accumulation event. Other rain state fields are retained.

Returns: Project intensity per hour times units_factor*scale_factor*adjust_factor. VOLUME/CUMULATIVE with nonpositive interval and unknown enum return zero before factor multiplication. Does not floor negative records or reject nonfinite inputs.

◆ gageIsUsed()

bool openswmm::gage::gageIsUsed	(	const SimulationContext &	ctx,
		int	gage_idx )

Test whether the model or enabled rainfall mesh consumes a gage.

Parameters

ctx	Compatible initialized subcatchment, hydrograph-name and optional mesh state.
gage_idx	Valid zero-based gage index; no range check is performed here.

Returns: True for a subcatchment binding, a resolved unit-hydrograph gage name, or any nonempty configured mesh with rainfall_mode!=NONE. Mesh selection marks every gage used. Invalid/unresolved -1 is not a supported query. No cache mutation.

Here is the call graph for this function:

◆ gageNextRainDate()

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

Read the next runoff-clock rainfall boundary from cached gage state.

Parameters

ctx	Compatible state last produced by updateAllGages, with aligned state arrays and table indices; does not advance it.
gage_idx	Zero-based gage index; out-of-state-range or unused returns t.
t	Finite absolute SWMM query day; comparisons internally use t plus one second.

Returns: Current interval start/end or next nonzero record start; legacy NO_DATE (-693594 days) if no source/boundary remains. Result is not necessarily later than t; runoff callers apply only a positive difference. Invalidates no borrows.

Here is the call graph for this function:

◆ gageNextRateChange()

double openswmm::gage::gageNextRateChange	(	const SimulationContext &	ctx,
		int	gage_idx,
		double	date,
		double	limit )

Forecast the end of the current held rain rate without changing source state.

Parameters

ctx	Compatible initialized, current gage state and ordered record tables.
gage_idx	Valid zero-based gage with current/next record indices consistent with date; this is a held-state forecast, not an arbitrary historical query.
date	Finite exact interval-start SWMM day (no legacy +1-second shift).
limit	Finite upper-bound SWMM day at/after date.

Returns: Rate-change/gap boundary capped by limit, or limit for missing/ignored rainfall. Joins adjacent exactly equal converted rates within 1e-5-second boundary tolerance. Uses record/unit/scale factors, not monthly adjustment, API or forcing overrides; caller qualifies those separately. Does not mutate table/gage cursors.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ gageRainSeries()

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

Borrow the actual resolved source table for a gage.

Parameters

ctx	Compatible initialized gage source/index arrays and owned table pools.
gage_idx	Zero-based gage index; invalid returns null.

Returns: Borrowed nonempty resolved FILE_RAIN table, or the indexed shared table for other sources (which can itself be empty); null for absent/unresolved source. Never free; owner/table replacement invalidates it. Does not advance a cursor or fall back from an unresolved file gage into the shared table pool.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ gageSeriesRainType()

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

Select the transform appropriate to resolved source storage.

Parameters

ctx	Compatible initialized source/format/rain_type arrays.
gage_idx	Valid zero-based gage index; unchecked.

Returns: VOLUME (1) for STANDARD FILE_RAIN because its loader already converted to interval depths; otherwise the authored rain_type integer unchanged. Does not modify authored type or validate unknown enum values.

Here is the caller graph for this function:

◆ gageUnitsFactor()

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

Return the source-storage-to-project rainfall depth multiplier.

Parameters

ctx	Compatible gage source/format arrays and project unit enum.
gage_idx	Zero-based gage index; invalid returns one.

Returns: 25.40 only for STANDARD FILE_RAIN in SI (enum>=3), otherwise one. STANDARD loader stores float-quantized inches; USER_CSV/shared tables already use project units. Does not convert the record's time interval or apply scale/month factors.

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 )

Sum completed hourly depth buckets, excluding the current partial hour.

Parameters

state	Borrowed standalone history in project inches/mm.
hours	Requested completed hours in [1,48]; other values return zero.

Returns: Sum of newest requested buckets in project depth units. Does not include an exactly full partial hour awaiting the next positive update or mutate state.

◆ getReportRainfall()

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

Query rainfall using the most recently advanced runoff-gage state.

Parameters

ctx	Compatible initialized state/tables/co-gage arrays, borrowed read-only.
gage_idx	Valid zero-based gage index, unchecked before several accesses.
report_date	Finite absolute SWMM/OLE day; lookup uses a one-second shift.

Returns: Project/hour rate from cached current/lookahead records, co-gage scaling or API override, zero when ignored/missing. Does not march cursors or independently search historical records; use the source-series overload when runoff ran ahead. Final gage forcing OVERRIDE/ADD values are not separately applied by this reader.

◆ getReportRainfallFromSeries()

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

Query report-time source records independently of a later runoff cursor.

Parameters

ctx	Compatible initialized gage/table state; st_cur must still be initialized and not NO_STATE even though rate selection searches source timestamps directly.
gage_idx	Valid zero-based gage index, unchecked before several accesses.
report_date	Supported finite SWMM/OLE day; source search uses date plus one second.

Returns: Project/hour rate during the selected record interval, using report-month adjustment, source conversion/scale, co-gage or API override. Zero outside covered intervals or under ignored/missing state. Does not mutate cursors, include final gage forcing OVERRIDE/ADD, or reproduce lookahead adjustment history for source searches.

Here is the caller graph for this function:

◆ splitPrecip()

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

Split a subcatchment's current gage intensity into internal rain and snow.

Parameters

ctx	Compatible initialized arrays, valid units and validated snow parameters; reads climate temperature in F and current effective gage rainfall in project/hour.
sub	Valid zero-based subcatchment index; unchecked before array access.

Returns: ft/s rain/snow, both zero for invalid/no gage. Ignore-snowmelt forces all precipitation to rain. Ordinary snow uses the division temperature; UEB pack assignment can use a mixed-temperature fraction and pack drift. Applies gage snow catch and subcatchment rain/snow scales after unit conversion. Does not mutate state or apply downstream subcatchment forcing overrides; callers add those. No nonnegative/finite output validation is performed.

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 )

Advance used gage record state and publish current effective rainfall.

Parameters

[in,out]	ctx	Compatible initialized model with aligned gage state/source/ forcing arrays, sorted finite resolved tables and coherent co-gage indices. Can initialize used flags, change record/lookahead indices/rates and rainfall; does not update precipitation splits, past-hour history or the simulation date itself.
	current_time	Finite absolute SWMM/OLE day, not elapsed seconds. Monotonic forward requests are required; the state machine does not rewind. Record marching uses current_time plus one second and retains each lookahead's adjustment factor. Unused gages retain seeded rate. Ignore-rainfall wins before overrides; earlier co-gage rates precede API override, then ordinary source resolution. Final used-gage OVERRIDE/ADD forcing applies after all source reads. Rates remain project/hour; no finite/range validation or transaction rollback occurs here.

Here is the call graph for this function:

◆ updatePastRain() [1/2]

void openswmm::gage::updatePastRain	(	GageState &	state,
		int	time_step )

Accumulate a standalone gage's held intensity into completed-hour history.

Parameters

[in,out]	state	rainfall is project/hour; past_rain holds completed project depths and partial accumulator holds current-hour depth. Partial interval must be in [0,3600] seconds, normally integer-valued.
	time_step	Actual accepted runoff duration in integer seconds; nonpositive is a no-op. May span multiple hours. An exactly full hour stays in the partial bucket until a later positive update; completed history excludes it until then. Does not split snow or reset rainfall; caller owns accepted-step invocation.

◆ updatePastRain() [2/2]

void openswmm::gage::updatePastRain	(	SimulationContext &	ctx,
		int	time_step )

Accumulate every gage's current held rate over one accepted runoff step.

Parameters

[in,out]	ctx	Aligned rainfall/partial/history arrays, including n_gages*48 completed-depth slots. Reads final resolved project/hour rates and changes only history accumulators/intervals; processes unused gages too.
	time_step	Integer elapsed seconds, nonpositive no-op. Exact-hour rollover matches the standalone overload; no model clock or rainfall update occurs.

Here is the call graph for this function:

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.

Classes

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ RainType

Function Documentation

◆ convertGageValue()

◆ convertRainfall()

◆ gageIsUsed()

◆ gageNextRainDate()

◆ gageNextRateChange()

◆ gageRainSeries()

◆ gageSeriesRainType()

◆ gageUnitsFactor()

◆ getPastRain()

◆ getReportRainfall()

◆ getReportRainfallFromSeries()

◆ splitPrecip()

◆ updateAllGages()

◆ updatePastRain() [1/2]

◆ updatePastRain() [2/2]

Variable Documentation

◆ MAXPASTRAIN

◆ ONE_SECOND