Climate Module

The climate module provides an interface that other objects may use to include weather data in their calculations; it provides weather and solar data to other modules and objects. Objects such as houses and buildings rely on this data to factor outdoor weather into their calculations for internal temperature. The climate data includes temperature, humidity, and solar radiation, which is used to calculate temperature gain that is the result of heat gained from direct exposure of a surface to sunlight.

The climate module supports manual control, TMY2/TMY3-style file parsing, and CSV-driven weather feeds through a csv_reader object.

Climate Object

The climate object is the top-level weather data container and runtime provider. At initialization, it can:

• operate in manual/FNCS/HELICS mode when no weather file is specified,
• load TMY/TMY2/TMY3-compatible weather data, or
• read CSV weather data using a linked csv_reader object.

During synchronization, the climate object updates weather and solar values for the current simulation time. Optional interpolation modes can smooth values between discrete samples.

Input Data Modes

Manual mode

If tmyfile is empty, climate runs in manual control mode and initializes at simulation start.

TMY/TMY2/TMY3 file mode

If tmyfile ends with .tmy or .tmy2, climate uses the TMY reader path. TMY3-style rows are also parsed by the same reader logic when the input format matches the TMY3 CSV row structure.

Notes:

• TMY2 DST handling has caveats in code; TMY3-style data is preferred for DST-corrected behavior.
• Solar values are converted internally from W/m^2 to W/sf.
• Temperature is converted from degC to degF for published temperature.

CSV reader mode

If tmyfile ends with .csv, climate requires a reader object of class csv_reader.

The CSV reader supports:

• property lines ($name=value),
• header-driven column mapping,
• multiple timestamp formats,
• weather sample scheduling via get_data.

Read more about the csv_reader.

Core Properties

Published climate properties include the following groups.

Location and source

Weather state

Solar state

Record values

Interpolation

Mode behavior:

• NONE: hold source sample values until next sample.
• LINEAR: linear interpolation between adjacent samples.
• QUADRATIC: quadratic interpolation using successive samples.

Cloud Model

The climate class includes an optional cloud model.

Notes:

• Cloud parameters are bounded in code (for example, opacity in [0,1]).
• The cumulus cloud model can be computationally expensive.

Published Functions

The climate class publishes solar calculation functions:

• calculate_solar_radiation_degrees
• calculate_solar_radiation_radians
• calculate_solar_radiation_shading_degrees
• calculate_solar_radiation_shading_radians
• calculate_solar_radiation_shading_position_radians
• calculate_solpos_radiation_shading_position_radians
• calc_solar_ideal_shading_position_radians

These functions provide multiple solar models and coordinate/angle conventions for module integration and custom irradiance calculations.

Solar Radiation Model Background

In the climate module, calculations are performed for solar radiation on a surface facing each of the eight major compass points (N, S, E, W, NE, NW, SE, SW) and a horizontal surface. For each surface, the total incident solar radiation is calculated by the following equation:

where

• \(Q_{direct}\) is the direct normal radiation for time and day.
• \(Q_{diffuse}\) is the diffuse horizontal radiation.
• \(A_{incident}\) = the angle of the sun relative to the surface (assuming the surface to be perpendicular to the Earth at that point, excepting the horizontal surface).

The incident angle is calculated by first calculating the solar time, which accounts for the change in the tilt of the earth polar axis with respect to the plane of the orbit around the sun through the year. The solar time is combined with the latitude of the surface, the slope of the surface relative to the horizontal (90 deg for all surfaces except the horizontal surface), and the azimuth angle relative to south (+ east of south, - west of south), and the day of the year (which is used in a calculation of the solar declination angle) to produce the cosine of the incident angle as follows.

where:

• \(S\) is the slope of the incident surface (90 deg is vertical);
• \(Z\) is the surface azimuth angle (angle between the incident surface's origanization (zero is true south, east is positive, west is negative));
• \(L\) is the latitude (north is positive);
• \(A_{hour}\) is hour angle, solar noon is zero, and each hour represents 15 deg of longitude with mornings positive and afternoons negative;
• \(D_{solar}\) is the declination of the sun (the angular position of the sun at solar noon with respect to the plane of the equator).

Leap years are handled by the fact that an hour of year calculation on February 29 would result in the same hour of year as March 1 on a normal year. March 1 would be used twice in a simulation involving a leap year.

Climate Data Sources

Climate data is commonly obtained from NREL NSRDB:

Useful references:

• TMY2 format
• TMY3 format
• Sample weather datasets

Reference

John A. Duffie and William A. Beckman, Solar Energy Thermal Processes, John Wiley and Sons, 1974.