TP-01: Overview and Climate Data | HEM Reference

Overview

TP-01 defines how climate data enters the Home Energy Model and how the simulation timebase is structured. It covers three concerns: parsing hourly weather data from an EPW-format file, establishing the simulation time iterator that controls timestep progression, and constructing the external conditions object that serves climate data to all downstream calculations.

Weather data is supplied as hourly time series covering a full calendar year (8,760 values for a non-leap year). The simulation may run at sub-hourly resolution (commonly 0.5 h or 0.25 h timesteps). When the simulation timestep is shorter than the weather data interval, climate variables are held constant across all sub-hourly steps within each hour, using a floor-based index lookup rather than linear interpolation.

The external conditions object centralises access to air temperature, wind speed, wind direction, and solar radiation data. It also pre-computes annual solar geometry arrays during initialisation, which are documented separately in TP-08: Solar Gains and Shading.

Inputs

Weather Data

Parameter	Symbol	Unit	Description
Air temperature	$T_{ai r}$	degC	Dry-bulb air temperature (one value per hour)
Wind speed	$v_{w in d}$	m/s	Wind speed at weather station height (one value per hour)
Wind direction	$θ_{w in d}$	degrees	Direction from which wind originates; North = 0, East = 90, South = 180, West = 270 (one value per hour)
Direct beam radiation	$I_{b e am}$	W/m²	Direct beam normal irradiance, or direct horizontal irradiance if conversion flag is set (one value per hour)
Diffuse horizontal radiation	$I_{d i f f}$	W/m²	Diffuse irradiance on the horizontal plane (one value per hour)
Solar reflectivity of ground	$ρ_{g r o u n d}$	--	Ground reflectance factor, typically 0.2 (one value per hour)
Latitude	$ϕ$	degrees	Latitude of the weather station; range $- 90$ to $+ 90$
Longitude	$λ$	degrees	Longitude of the weather station; easterly positive, westerly negative; range $- 180$ to $+ 180$

Simulation Time

Parameter	Symbol	Unit	Description
Start time	$t_{s t a r t}$	h	Start time of the simulation, in hours from an arbitrary zero point
End time	$t_{e n d}$	h	End time of the simulation, in hours from the same zero point
Timestep	$Δ t$	h	Duration of each simulation step (e.g. 1.0, 0.5, or 0.25)

External Conditions Configuration

Parameter	Unit	Description
Timezone	--	UTC offset of the weather station ( $- 12$ to $+ 12$ )
Start day	--	First day of the weather time series (day of year, 0-indexed)
End day	--	Last day of the weather time series (day of year, 0-indexed)
Time series step	h	Timestep of the input weather data (typically 1.0 h)
January first	--	Day of the week for 1 January (1 = Monday, 7 = Sunday)
Daylight savings	--	Whether daylight saving time applies and is accounted for
Leap day included	--	Whether the climate data includes 29 February
Direct beam conversion needed	--	Flag indicating whether direct beam radiation must be converted from horizontal to normal incidence
Shading segments	--	Optional array of ground-plane segments (8 to 36) with height and distance to surrounding shading objects

Calculation

Weather File Parsing

The weather file follows the EPW comma-separated format. The first row contains metadata, including longitude (column 8) and latitude (column 7). Weather data rows begin at row 9 (zero-indexed row 8), with each row representing one hour.

The parser extracts six time series from the following columns:

Column index	Variable
6	Dry-bulb air temperature (degC)
14	Direct beam normal irradiance (W/m²)
15	Diffuse horizontal irradiance (W/m²)
20	Wind direction (degrees)
21	Wind speed (m/s)

Ground solar reflectivity is set to a constant value of 0.2 for every hour. This is not read from the file.

The parser also extracts latitude and longitude from the header row and sets a flag indicating whether direct beam radiation values are already at normal incidence (in which case no conversion is needed) or at horizontal incidence (requiring conversion using the solar altitude).

Simulation Time

The simulation time object is an iterator that tracks the current position within the simulation and provides derived time quantities to all other modules.

Construction

Given $t_{s t a r t}$ , $t_{e n d}$ , and $Δ t$ , the total number of timesteps is:

$N_{s t e p s} = ⌈ \frac{t _{e n d} - t _{s t a r t}}{Δ t} ⌉$

The iterator maintains a zero-based index $i$ (starting at 0) and a current time $t_{c u r r e n t}$ (starting at $t_{s t a r t}$ ). On each iteration after the first, both advance:

$i \leftarrow i + 1$ $t_{c u r r e n t} \leftarrow t_{c u r r e n t} + Δ t$

Iteration terminates when $t_{c u r r e n t} \geq t_{e n d}$ .

Derived Quantities

The simulation time object provides several derived quantities used throughout the model:

Current hour. The integer hour of the simulation, obtained by rounding down the current time:

$h_{c u r r e n t} = ⌊ t_{c u r r e n t} ⌋$

Hour of day. The hour within the current day (0 to 23):

$h_{d a y} = ⌊ t_{c u r r e n t} mod 24 ⌋$

Current day. The day number (0-indexed, where day 0 is 1 January):

$d_{c u r r e n t} = ⌊ \frac{t _{c u r r e n t}}{24} ⌋$

Current month. Determined by comparing $h_{c u r r e n t}$ against cumulative hour boundaries for each month. For a non-leap year, the cumulative hours at the start of each month are:

Month	Jan	Feb	Mar	Apr	May	Jun	Jul	Aug	Sep	Oct	Nov	Dec	End
Cumulative hours	0	744	1,416	2,160	2,880	3,624	4,344	5,088	5,832	6,552	7,296	8,016	8,760

The current month (0 for January, 11 for December) is the largest $m$ such that $h_{c u r r e n t} \geq H_{m}$ , where $H_{m}$ is the cumulative hours at the start of month $m$ .

Time Series Index

To map from the current simulation time to an index in the hourly weather data arrays, the model computes:

$i_{t s} = ⌊ \frac{t _{c u r r e n t} - d _{s t a r t} \times 24}{Δ t _{ser i es}} ⌋$

Where:

$t_{c u r r e n t}$ is the current simulation time in hours
$d_{s t a r t}$ is the start day of the time series (day of year, 0-indexed)
$Δ t_{ser i es}$ is the timestep of the time series data (typically 1.0 h)

This floor operation is the mechanism by which sub-hourly timesteps map to hourly weather data. All sub-hourly steps within the same hour return the same index, so weather values are held constant (piecewise-constant interpolation).

External Conditions Initialisation

The external conditions object is constructed once at the start of the simulation. It receives the simulation time object, all weather data arrays, location parameters, and configuration flags.

During construction, the object performs the following steps:

Copy weather data. The hourly arrays for air temperature, wind speed, wind direction, and ground reflectivity are copied into internal storage.
Determine calendar length. If the leap day flag is set, the year has 366 days (8,784 hours); otherwise 365 days (8,760 hours).
Pre-compute solar geometry. Per-day and per-hour solar geometry arrays are calculated for the entire year. These include earth orbit deviation, solar declination, equation of time, solar time, solar hour angle, solar altitude, solar zenith angle, solar azimuth angle, and air mass. This pre-computation is documented in TP-08: Solar Gains and Shading.
Pre-compute per-timestep radiation arrays. For each simulation timestep, the direct beam radiation and diffuse horizontal radiation are looked up from the hourly input data using the time series index. If the direct beam conversion flag is set, horizontal beam values are converted to normal incidence by dividing by the sine of the solar altitude. Per-timestep brightness coefficients ( $F_{1}$ , $F_{2}$ ) are also pre-computed; these are documented in TP-08: Solar Gains and Shading.

Climate Data Access

At each simulation timestep, downstream modules query the external conditions object for climate variables. The lookup uses the time series index described above.

Air temperature. Returns $T_{ai r}$ at the index corresponding to the current simulation time. Supports an optional offset parameter to retrieve the temperature at adjacent hours. If the resulting index exceeds the array bounds, it wraps around.

Wind speed. Returns $v_{w in d}$ at the current time series index.

Wind direction. Returns $θ_{w in d}$ at the current time series index.

Annual averages. The model can compute annual mean air temperature and annual mean wind speed by averaging across all 8,760 hourly values:

$\overset{ˉ}{T}_{ai r} = \frac{1}{N} \sum_{i = 0}^{N - 1} T_{ai r, i}$

$\overset{v}{ˉ}_{w in d} = \frac{1}{N} \sum_{i = 0}^{N - 1} v_{w in d, i}$

where $N = 8, 760$ for a non-leap year.

Monthly averages. Monthly mean air temperature is computed by averaging over the hours within the current month, bounded by the cumulative hour boundaries.

Minimum daily average temperature. The minimum daily average air temperature across the year is computed by first calculating the mean temperature for each 24-hour period, then taking the minimum of those 365 daily means.

Annual mean wind direction. Computed using vector averaging to account for the circular nature of angles. The wind speed and direction for each hour are decomposed into Cartesian components, averaged, and converted back to an angle:

$\overset{ˉ}{θ}_{w in d} = arctan (\frac{v ˉ _{y}}{v ˉ _{x}}) mod 360$

where:

$\overset{v}{ˉ}_{x} = \frac{1}{N} \sum_{i = 0}^{N - 1} v_{w in d, i} cos (θ_{w in d, i})$
$\overset{v}{ˉ}_{y} = \frac{1}{N} \sum_{i = 0}^{N - 1} v_{w in d, i} sin (θ_{w in d, i})$

Outputs

Quantity	Symbol	Unit	Description
Air temperature (current)	$T_{ai r}$	degC	External air temperature at the current timestep
Wind speed (current)	$v_{w in d}$	m/s	Wind speed at the current timestep
Wind direction (current)	$θ_{w in d}$	degrees	Wind direction at the current timestep
Direct beam radiation (current)	$I_{b e am}$	W/m²	Direct beam normal irradiance at the current timestep
Diffuse horizontal radiation (current)	$I_{d i f f}$	W/m²	Diffuse horizontal irradiance at the current timestep
Ground reflectivity (current)	$ρ_{g r o u n d}$	--	Solar reflectivity of the ground at the current timestep
Annual mean air temperature	$\overset{ˉ}{T}_{ai r}$	degC	Mean of all 8,760 hourly air temperature values
Monthly mean air temperature	--	degC	Mean air temperature for the current calendar month
Minimum daily average temperature	--	degC	Lowest 24-hour mean temperature across the year
Annual mean wind speed	$\overset{v}{ˉ}_{w in d}$	m/s	Mean of all 8,760 hourly wind speed values
Total simulation steps	$N_{s t e p s}$	--	Number of timesteps in the simulation
Current timestep index	$i$	--	Zero-based index of the current timestep

Assumptions

Weather data is provided as hourly values. The model does not accept sub-hourly weather inputs.
Sub-hourly simulation timesteps use piecewise-constant interpolation from the hourly weather data. All sub-steps within a given hour receive the same climate values. No linear or higher-order interpolation is applied.
Ground solar reflectivity is fixed at 0.2 for all hours of the year. It is not read from the weather file.
The timezone is fixed at 0 (GMT). It is not read from the input file in the current specification.
Start day defaults to 0 (1 January) and the time series step defaults to 1.0 h.
The calendar year is assumed to be a non-leap year (365 days, 8,760 hours) unless the leap day flag is explicitly set.
Solar geometry arrays are pre-computed for the entire year during initialisation, not calculated on demand at each timestep.
Annual average calculations require a complete year of weather data (exactly 8,760 values for a non-leap year).
Wind direction averaging uses vector decomposition weighted by wind speed, which correctly handles the circular nature of angular data.

Cross-references

TP-02: Wrappers -- wrapper logic that loads the input file and constructs the simulation time and external conditions objects
TP-03: External Conditions -- wind speed adjustment for terrain, operative temperature calculation, and temperature processing that builds on the climate data provided here
TP-06: Ventilation and Infiltration -- uses wind speed and wind direction from external conditions for infiltration calculations
TP-08: Solar Gains and Shading -- solar geometry pre-computation, irradiance on tilted surfaces, and shading calculations that use the radiation data and location parameters initialised here