SolarRadiation.hpp File Reference

Phase H6a — where incoming shortwave Jin comes from (heat plan §2.5, D-H6a). More...

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

Go to the source code of this file.

Classes
struct	openswmm::transport::heat::SolarPosition
	Sun geometry at one instant. The SPA swap point's return type. More...

Namespaces
namespace	openswmm
namespace	openswmm::transport
namespace	openswmm::transport::heat

Functions
SolarPosition	openswmm::transport::heat::solarPosition (int day_of_year, double hour_local, double lat_deg, double lon_deg, double tz_hours) noexcept
	Sun position by the Spencer (1971) / NOAA formulation.
double	openswmm::transport::heat::airMass (double zenith_deg) noexcept
double	openswmm::transport::heat::pressureFromElevation (double elevation_m) noexcept
	Station pressure [mb] from elevation [m], standard atmosphere.
double	openswmm::transport::heat::birdClearSkyGHI (const SolarPosition &pos, double pressure_mb, const SolarConfig &cfg) noexcept
	Bird & Hulstrom clear-sky global horizontal irradiance [W/m²].
double	openswmm::transport::heat::cloudShortwaveFactor (double cloud_fraction, double k, double n) noexcept
	Cloud attenuation of shortwave, 1 − k·C^n (Kasten–Czeplak).
double	openswmm::transport::heat::cloudLongwaveFactor (double cloud_fraction, double k_lw) noexcept
	Cloud enhancement of atmospheric emissivity, 1 + k_lw·C² (Bolz).
void	openswmm::transport::heat::updateSolarForcing (SimulationContext &ctx) noexcept
	Resolve Jin and C for this step into ctx.heat_state.

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

Detailed Description

Phase H6a — where incoming shortwave Jin comes from (heat plan §2.5, D-H6a).

H3 took Jin as a static constant. This module adds the two other spellings of plan §2.5: an interpolated timeseries, and a computed clear-sky value from solar position — plus the cloud parameterization that modulates BOTH shortwave and longwave.

Nothing here is a flux family. This module produces a number in W/m² and hands it to H3's existing netShortwave; it adds no term to netFluxOut, touches no sign convention, and introduces no element state. That is why H6a is separable from H6b.

Solar position: NOAA/Spencer, NOT NREL SPA — and why (D-H6a-4, as

amended 2026-08-30) The plan first specified NREL SPA for its published test vectors. Implementing it faithfully needs ~260 rows of periodic-term constants (truncated VSOP87 L/B/R plus the IAU 1980 nutation series). Transcribing those without the source document in reach means the TABLES and the TEST VECTOR would both be recalled — and a consistently misremembered pair gates green on wrong physics. That is the H3 Brunt-in-kPa failure (a plausible wrong number that only a true reference catches) at 260× the surface area, with the reference itself compromised.

So the position solver here is the Spencer (1971) / NOAA formulation: ~40 lines, no constant tables, verifiable by inspection, and independently cross-checkable against two things already in this engine — Climate.cpp:178's declination and its sunrise/sunset hours. Stated accuracy is ~0.1° in declination and ~0.5 min in the equation of time, against SPA's ±0.0003°.

That error is not the binding one. A 0.1° zenith error moves clear-sky GHI by well under 0.1%; the cloud fraction multiplying it is a whole-number guess. Spending 400 lines of unverifiable constants to refine the small term under the large one is the wrong trade.

The SPA swap point

solarPosition() is the ONLY function that knows how a position is obtained. Everything downstream consumes SolarPosition. Landing SPA later is a new implementation of that one function plus a SolarAlgorithm selector — no caller changes. Do it with NREL's published C source open, so the tables can be DIFFED rather than recalled, and gate it against the report's worked example.

Clear-sky: Bird & Hulstrom (1981)

Broadband direct + diffuse on a horizontal surface. Five transmittance terms (Rayleigh, ozone, mixed gases, water vapour, aerosol) and a sky-ground multiple-reflection correction. Defaults are the paper's standard atmosphere.

Warning

The Bird coefficients below are transcribed from the published formulation. The validation handoff instructs the checking agent to re-derive them from the paper before trusting any gate that uses them — see H6A_VALIDATION_HANDOFF_2026-08-30.md §2.

See also

plans/transport/HEAT_TRANSPORT_PLAN.md §2.5, §6 H6a, §6.4

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\n Apache-2.0