openswmm::climate Namespace Reference

Classes
class	ClimateFileReader
	Stateful forward-only daily climate-file reader with one month cache. One owner serializes open/lookup/close; no concurrent queries. Request months in chronological order in a compatible ordered file. No rewind/index is kept for past months. Parsers are permissive and do not qualify all missing-value flags/calendar dates; successful lookup can return entirely NaN fields. More...
struct	ClimateState
struct	DailyClimateRecord
class	HourlyMeteorology
	Owned consecutive hourly records with interval-weighted means. Concurrent const queries are safe only while the cache is stable; serialize load/read/destruction with readers and release borrowed records before reload. More...
struct	HourlyMetRecord
struct	MovingAvg7
struct	RadiationState
struct	SnowDailyWeather
struct	SolarPosition
	Sun geometry at one instant. The SPA swap point's return type. More...

Enumerations
enum class	EvapMethod : int {   CONSTANT = 0 ,   MONTHLY = 1 ,   TIMESERIES = 2 ,   TEMPERATURE = 3 ,   PAN = 4 }
enum class	ClimateFileFormat {   UNKNOWN ,   USER_PREPARED ,   GHCND ,   TD3200 ,   DLY0204 }
enum	ClimateVar {   TMIN = 0 ,   TMAX = 1 ,   EVAP = 2 ,   WIND = 3 }
	Climate variable indices (matching legacy ClimateVarType) More...
enum	WindFieldType {   WDMV = 0 ,   AWND = 1 }
	Wind field type in GHCND. More...
enum	TempUnits {   DEG_C10 = 0 ,   DEG_C = 1 ,   DEG_F = 2 }
	Temperature unit encoding in GHCND. More...
enum class	RadiationOrigin {   Computed ,   Timeseries ,   MetFile ,   LegacyHeat }

Functions
double	hargreaves (double latitude, int day_of_year, double t_avg, double t_range)
	Estimate potential evapotranspiration using Hargreaves radiation/temperature.
void	updateDailyClimate (ClimateState &state, int day_of_year, int month)
	Update scalar evaporation and snow-related atmospheric coefficients.
void	batchDistributeEvap (double evap_rate, const double *ponded_depth, double *evap_out, int n, double dt)
	Bound one scalar evaporation rate by each ponded-water supply rate.
void	updateTempTimes (ClimateState &state, int doy)
	Derive daily sinusoidal temperature timing from latitude and season.
double	getSubdailyTemp (const ClimateState &state, double hour)
	Evaluate the three-segment native diurnal temperature curve.
SolarPosition	solarPosition (int day_of_year, double hour_local, double lat_deg, double lon_deg, double tz_hours) noexcept
	Compute Spencer/NOAA sun geometry at a local civil-clock instant.
double	airMass (double zenith_deg) noexcept
	Compute Kasten-Young relative optical air mass.
double	pressureFromElevation (double elevation_m) noexcept
	Estimate standard-atmosphere station pressure from elevation.
double	birdClearSkyGHI (const SolarPosition &pos, double pressure_mb, const SolarConfig &cfg) noexcept
	Estimate clear-sky global horizontal irradiance with Bird-Hulstrom terms.
double	cloudShortwaveFactor (double cloud_fraction, double k, double n) noexcept
	Compute the cloud attenuation multiplier max(0,1-k*C^n).
double	cloudLongwaveFactor (double cloud_fraction, double k_lw) noexcept
	Compute the cloud atmospheric-emissivity multiplier 1+k_lw*C^2.
void	updateSolarForcing (SimulationContext &ctx, double seconds=1)
	Update shared heat shortwave/cloud forcing with mesh radiation disabled.
void	updateSolarForcing (SimulationContext &ctx, double seconds, bool mesh_enabled)
	Resolve shared incoming heat shortwave and cloud forcing at current_date.
std::string	resolveRadiation (SimulationContext &ctx, double date, double seconds, RadiationState &output)
	Resolve mean weather/radiation for one interval without advancing climate time.
std::string	initializeRadiation (SimulationContext &ctx)
	Validate snow parameters and prepare site and weather input caches.
std::string	resolveUebForcing (SimulationContext &ctx, double date, double seconds, double slope, double aspect, surface::ueb::Forcing &forcing, double &pressure)
	Merge resolved interval weather and slope-adjusted radiation into a UEB forcing.

Variables
constexpr double	MM_PER_INCH = 25.40
constexpr double	kSolarConstant = 1367.0
	Solar constant, W/m² (Bird & Hulstrom 1981; WMO 1982).
constexpr double	kStdPressureMb = 1013.25
	Sea-level standard pressure, millibars — Bird's pressure reference.

Enumeration Type Documentation

ClimateFileFormat

enum class openswmm::climate::ClimateFileFormat

strong

Enumerator
UNKNOWN
USER_PREPARED	StationID YYYY MM DD TMAX TMIN EVAP WIND.
GHCND	NCDC Global Historical Climatology Network Daily.
TD3200	NCDC TD3200 (NWS cooperative observer)
DLY0204	Canadian DLY02/DLY04.

ClimateVar

enum openswmm::climate::ClimateVar

Climate variable indices (matching legacy ClimateVarType)

Enumerator
TMIN
TMAX
EVAP
WIND

EvapMethod

enum class openswmm::climate::EvapMethod : int

strong

Enumerator
CONSTANT
MONTHLY
TIMESERIES
TEMPERATURE	Hargreaves method.
PAN

RadiationOrigin

enum class openswmm::climate::RadiationOrigin

strong

Enumerator
Computed
Timeseries
MetFile
LegacyHeat

TempUnits

enum openswmm::climate::TempUnits

Temperature unit encoding in GHCND.

Enumerator
DEG_C10
DEG_C
DEG_F

WindFieldType

enum openswmm::climate::WindFieldType

Wind field type in GHCND.

Enumerator
WDMV
AWND

Function Documentation

airMass()

double openswmm::climate::airMass ( double zenith_deg )

noexcept

Compute Kasten-Young relative optical air mass.

Parameters

zenith_deg

Finite solar zenith in degrees, normally [0,180].

Returns

Dimensionless path factor, or zero for zenith>=90 or a nonpositive/NaN denominator. Does not normalize angles or validate negative zenith inputs.

Here is the caller graph for this function:

batchDistributeEvap()

void openswmm::climate::batchDistributeEvap	(	double	evap_rate,
		const double *	ponded_depth,
		double *	evap_out,
		int	n,
		double	dt )

Bound one scalar evaporation rate by each ponded-water supply rate.

Parameters

	evap_rate	Finite potential ft/s, normally nonnegative; no floor at zero.
	ponded_depth	Readable n-element depth array in feet, normally nonnegative; may be null when n<=0.
[out]	evap_out	Writable n-element ft/s array, disjoint from ponded_depth or exactly the same storage for safe in-place use; other overlap is unsupported.
	n	Number of entries; nonpositive performs no array accesses.
	dt	Finite seconds; positive uses 1/dt, nonpositive uses zero reciprocal. Each output is min(evap_rate,depth/dt) for positive dt. Negative inputs can produce negative rates; no finite-value validation, accepted-water booking or mutation of the simulation clock is supplied.

birdClearSkyGHI()

double openswmm::climate::birdClearSkyGHI ( const SolarPosition & pos, double pressure_mb, const SolarConfig & cfg )

noexcept

Estimate clear-sky global horizontal irradiance with Bird-Hulstrom terms.

Parameters

pos	Compatible solarPosition result with nonnegative cosine and valid zenith/eccentricity. The cosine and zenith must describe the same instant.
pressure_mb	Finite nonnegative station pressure in millibars.
cfg	Physical aerosol optical depths, precipitable water/ozone centimetres and land ground-albedo fraction. Caller validates finite model ranges.

Returns

Nonnegative irradiance W/m2, zero without positive cosine/air mass. A nonpositive reflection denominator omits that correction. No diagnostics or complete input-domain validation are supplied by this noexcept numerical helper.

Here is the call graph for this function:

Here is the caller graph for this function:

cloudLongwaveFactor()

double openswmm::climate::cloudLongwaveFactor ( double cloud_fraction, double k_lw )

noexcept

Compute the cloud atmospheric-emissivity multiplier 1+k_lw*C^2.

Parameters

cloud_fraction	Cloud fraction; nonpositive or NaN returns literal one; positive values above one are capped at one.
k_lw	Finite dimensionless enhancement coefficient, normally nonnegative.

Returns

Dimensionless multiplier without an output clamp. Literal clear-sky one avoids evaluating coefficient arithmetic for a cloud-free input.

cloudShortwaveFactor()

double openswmm::climate::cloudShortwaveFactor ( double cloud_fraction, double k, double n )

noexcept

Compute the cloud attenuation multiplier max(0,1-k*C^n).

Parameters

cloud_fraction	Cloud fraction; nonpositive or NaN returns literal one; positive values above one are capped at one.
k	Finite dimensionless attenuation coefficient, normally nonnegative.
n	Finite exponent compatible with the positive cloud fraction.

Returns

Dimensionless factor; lower-bounded at zero but not capped at one when negative k is supplied. No other coefficient validation occurs.

Here is the caller graph for this function:

getSubdailyTemp()

double openswmm::climate::getSubdailyTemp	(	const ClimateState &	state,
		double	hour )

Evaluate the three-segment native diurnal temperature curve.

Parameters

state	Borrowed finite daily min/max/previous-max temperatures in F and consistent timing from updateTempTimes(). has_minmax is not checked here.
hour	Finite local clock hour, normally [0,24]; not normalized/clamped.

Returns

Fahrenheit from the pre-sunrise, daytime or post-maximum sinusoid. Near-zero timing denominators use +1/-1-hour fallbacks. No finite-input checks, clamping to min/max, calendar lookup or state mutation occurs.

Here is the caller graph for this function:

hargreaves()

double openswmm::climate::hargreaves	(	double	latitude,
		int	day_of_year,
		double	t_avg,
		double	t_range )

Estimate potential evapotranspiration using Hargreaves radiation/temperature.

Parameters

latitude	Finite site latitude degrees north, normally [-90,90].
day_of_year	Ordinal [1,366]; seasonal fit uses 365-day denominator.
t_avg	Finite mean temperature Fahrenheit, converted internally to Celsius.
t_range	Finite temperature difference Fahrenheit, converted to Celsius and floored at zero before square root.

Returns

Nonnegative mm/day in every project unit system, not inches/day. Latent heat is floored at 0.01, sunset-angle argument clamped to [-1,1], radiation and ET floored at zero. No input/error validation or state mutation; caller converts the result to internal units as needed.

Here is the caller graph for this function:

initializeRadiation()

std::string openswmm::climate::initializeRadiation

(

SimulationContext &

ctx

)

Validate snow parameters and prepare site and weather input caches.

Parameters

[in,out]

ctx

Compatible initialized model/options with resolved input path, climate/heat/snow configuration and time-series tables. A snow SITE takes precedence over legacy coordinates/elevation and can append one conflict warning. Resolves MET_FILE relative to the input, loads/qualifies coverage, or builds a daily legacy climate cache when needed. Daily gaps retain the preceding temperature/wind values with initial defaults 70 F/zero wind. Does not advance the simulation clock.

Returns

Empty on accepted setup, otherwise diagnostic. Changes made before failure (including site overrides, paths and weather caches) remain; not transactional. Requires caller serialization with forcing resolution and table/cache mutation. Archive/path/allocation exceptions can propagate beyond normal diagnostic returns.

Here is the call graph for this function:

pressureFromElevation()

double openswmm::climate::pressureFromElevation ( double elevation_m )

noexcept

Estimate standard-atmosphere station pressure from elevation.

Parameters

elevation_m

Finite metres above sea level; negative elevations allowed. Keep 1-2.25577e-5*elevation_m nonnegative for the power-law domain.

Returns

Pressure in millibars; no range clamp, finite check or error diagnostic.

Here is the caller graph for this function:

resolveRadiation()

std::string openswmm::climate::resolveRadiation	(	SimulationContext &	ctx,
		double	date,
		double	seconds,
		RadiationState &	output )

Resolve mean weather/radiation for one interval without advancing climate time.

Parameters

[in,out]	ctx	Initialized compatible model with sorted, finite, aligned tables, valid date/unit configuration and caches prepared by initializeRadiation(). Table lookup cursors can advance, although the climate clock and output state do not.
	date	Finite absolute SWMM interval-start date in days within supported calendar range.
	seconds	Finite duration in (0,86400] seconds.
[out]	output	Assigned only on success: horizontal shortwave/longwave W/m2, air temperature C, humidity fraction, wind m/s, pressure Pa, averaged positive horizontal cosine, degree geometry and input-origin markers.

Returns

Empty on success, otherwise a configuration/coverage/value diagnostic. MET_FILE overrides weather and both radiation channels; otherwise authored series and legacy heat forcing can replace computed radiation. Weather prescriptions apply after native/file conversion. Series use piecewise-linear interval means; solar geometry fixes start-instant declination over the interval. Temperature, humidity, wind and radiation are checked, but pressure/geometry are not all individually validated here. Failure retains output but may change lookup cursors. Exceptions from calendar/geometry/allocation helpers are not caught here.

Here is the call graph for this function:

Here is the caller graph for this function:

resolveUebForcing()

std::string openswmm::climate::resolveUebForcing	(	SimulationContext &	ctx,
		double	date,
		double	seconds,
		double	slope,
		double	aspect,
		surface::ueb::Forcing &	forcing,
		double &	pressure )

Merge resolved interval weather and slope-adjusted radiation into a UEB forcing.

Parameters

[in,out]	ctx	Compatible initialized weather configuration; successful return also stores horizontal radiation in climate_state.radiation. Lookup cursors may advance even on failure; no simulation clock advancement occurs.
	date	Absolute SWMM start date in days, as for resolveRadiation().
	seconds	Finite interval seconds in (0,86400].
	slope	Plane inclination in degrees; follows solarIntegral() admissible range.
	aspect	Plane aspect in degrees clockwise from north.
[in,out]	forcing	Existing forcing copied on success, preserving precipitation and unrelated fields. Replaces weather, duration, cosine, longwave and shortwave; division-temperature mode also replaces snow_fraction with zero or one. Shortwave uses horizontal-area slope ratio unless flat or the astronomical denominator is zero.
[out]	pressure	Station pressure Pa, assigned only on success.

Returns

Empty on success, otherwise resolver/standard geometry-exception text. Outputs remain unchanged for normal failures before publication; exceptions from resolveRadiation occur outside the local geometry catch and can propagate.

Here is the call graph for this function:

Here is the caller graph for this function:

solarPosition()

SolarPosition openswmm::climate::solarPosition ( int day_of_year, double hour_local, double lat_deg, double lon_deg, double tz_hours )

noexcept

Compute Spencer/NOAA sun geometry at a local civil-clock instant.

Parameters

day_of_year	Calendar ordinal in [1,366]; the fit uses a 365-day denominator.
hour_local	Finite decimal local hour, normally [0,24).
lat_deg	Latitude degrees north in [-90,90].
lon_deg	Finite longitude degrees east, normally [-180,180].
tz_hours	Finite civil offset hours east of UTC; no daylight-saving lookup.

Returns

Degree-valued declination/hour-angle/zenith/elevation, equation of time in minutes, nonnegative zenith cosine and dimensionless distance correction. Hour angle wraps to [-180,180]. Inputs are not validated; nonfinite hour/longitude can make wrapping nonterminating. This approximation is not a high-precision SPA solver.

Here is the caller graph for this function:

updateDailyClimate()

void openswmm::climate::updateDailyClimate	(	ClimateState &	state,
		int	day_of_year,
		int	month )

Update scalar evaporation and snow-related atmospheric coefficients.

Parameters

[in,out]	state	Initialized climate state with effective temperature/range already resolved in F, finite site latitude/elevation (feet), compatible moving history, positive evaprate_ucf and monthly project evaporation inputs. CONSTANT/ MONTHLY recompute native ft/s, TEMPERATURE pushes one history sample and computes Hargreaves; TIMESERIES/PAN rates are retained for external resolution. Adds monthly adjust_evap only for the first three modes. Updates saturation pressure ea and elevation-based psychrometric gamma. Temperature/wind and source clocks are not resolved or adjusted by this routine.
	day_of_year	Valid ordinal [1,366] used by temperature-derived ET.
	month	Zero-based [0,11], unchecked monthly array index. Call once per desired daily sample for TEMPERATURE to avoid duplicate history; negative adjusted evaporation is not clamped and numeric failure has no status. Caller serializes state mutation; no rollback is supplied.

Here is the call graph for this function:

updateSolarForcing() [1/2]

void openswmm::climate::updateSolarForcing	(	SimulationContext &	ctx,
		double	seconds,
		bool	mesh_enabled )

Resolve shared incoming heat shortwave and cloud forcing at current_date.

Parameters

[in,out]	ctx	Compatible initialized heat/climate/snow state and resolved tables. Writes heat_state.shortwave_now/cloud_now and radiation.shared_heat_forcing; the snow path stores a full resolved radiation record. Table cursors may advance.
	seconds	Positive interval seconds (at most one day) for the authored snow/ MET_FILE path; unused by ordinary constant/series/computed legacy heat lookup.
	mesh_enabled	Enables work for mesh heat even if legacy radiative exchange is off; heat_transport must still be enabled.

Exceptions

std::runtime_error

Authored radiation/weather resolver diagnostic. Disabled work writes shortwave=-1 and cloud=0, retaining the prior radiation record. Legacy series lookup is instantaneous and can return zero beyond coverage; cloud is clamped to [0,1], then attenuates all shortwave modes. Missing computed-site coordinates yield zero. Repeated calls are not free of table-cursor mutations.

Here is the call graph for this function:

updateSolarForcing() [2/2]

void openswmm::climate::updateSolarForcing	(	SimulationContext &	ctx,
		double	seconds = 1 )

Update shared heat shortwave/cloud forcing with mesh radiation disabled.

Parameters

[in,out]	ctx	Initialized heat/climate/snow state at current_date; serializes table cursors and shared output state with other forcing readers/writers.
	seconds	Interval seconds forwarded to the snow resolver when authored radiation/MET_FILE is present; default one. Otherwise legacy heat uses an instant. Equivalent to the three-argument overload with mesh_enabled=false; same failure and mutation behavior. Call before flux evaluation on each consuming clock.

Here is the call graph for this function:

Here is the caller graph for this function:

updateTempTimes()

void openswmm::climate::updateTempTimes	(	ClimateState &	state,
		int	doy )

Derive daily sinusoidal temperature timing from latitude and season.

Parameters

[in,out]	state	Finite latitude degrees north and dtlong hour correction; writes hrsr, hrss, hrday, dhrdy and dydif. Does not update temperature, has_minmax, last_temp_doy or any simulation date; caller manages those markers.
	doy	Ordinal [1,366], not validated. Polar night uses noon/noon, midnight sun uses zero/24; ordinary maxima use sunset minus three hours and the longitude correction. Call before getSubdailyTemp for the selected day; no general finite/range validation or output normalization.

Here is the caller graph for this function:

Variable Documentation

kSolarConstant

double openswmm::climate::kSolarConstant = 1367.0

inlineconstexpr

Solar constant, W/m² (Bird & Hulstrom 1981; WMO 1982).

kStdPressureMb

double openswmm::climate::kStdPressureMb = 1013.25

inlineconstexpr

Sea-level standard pressure, millibars — Bird's pressure reference.

MM_PER_INCH

double openswmm::climate::MM_PER_INCH = 25.40

constexpr