From GridLAB-D Wiki
Jump to: navigation, search

 TODO:  Update for Hassayampa (Version 3.0)

The climate module provides an interface that other objects may use to include weather data in their calculations. 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 Version 1.0 retrieves climate data from TMY2 files, created and maintained by the National Renewable Energy Laboratory (NREL).

Climate Object

The climate object in the climate module is a combined data container and TMY2 file parser. Given a tmy2 file, it will update its contents on an hourly basis from its file. Elsewise, it operates strictly as a constant reference class, with mutable but internally unchanging values.


Property Name Unit Type Default Value Description
city char32 N/A " " The name of the city associated with this climate object.
humidity double  % 0.75 The current humidity
record.high double degF 59.0 The highest air temperature that will be observed in the TMY2 file. Ignored without a TMY2 file.
record.low double degF 59.0 The lowest air temperature that will be observed in the TMY2 file. Ignored without a TMY2 file. double W/sf 0.0 The greatest solar input that will be observed in the TMY2 file. Ignored without a TMY2 file.
solar_flux double W/sf 0.0 The current aggregated solar input for a flat surface.
temperature double degF 59.0 The current air temperature
tmyfile char1024 N/A " " The path to the TMY2 file to use for this object, if any.
wind_speed double degrees 0.0 The way the wind blows, 0 deg being northwards
interpolate enumeration NONE, LINEAR NONE Interpolation method to use on the climate data, if any.

TMY2 Data

TMY is an acronym for typical meteorological year. In a TMY file, weather data for a particular location is aggregated and averaged to provide a typical baseline for the weather of a particular geographical location on a given day at a given hour. TMY data is not suitable for modeling extreme situations and is not necessarily a good indicator for forecasting, but it is an indication of typical weather conditions over an extended period of time. The TMY2 format is an extension of the original TMY format to include information necessary for solar radiation calculations.

Solar Radiation

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:

Q_{solar} = Q_{direct} \cos \left ( \alpha_{incident} \right ) + Q_{diffuse}


  • 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° 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.

D_{solar} & = 23.45 \deg \frac{2 \pi}{360} \sin \left ( \frac{2 \pi 284 + D_{year}}{365}  \right ) \\
 & = 0.409280 \sin \left ( \frac{2 \pi 284 + D_{year}}{365}  \right )

A_{hour} = - \frac{15 \pi}{180} \left ( H_{solar} - 12 \right )

\cos(A_{incident}) & = \sin(D_{solar}) \sin(L) cos(S) \\
 & - \sin(D_{solar}) \cos(L) \sin(S) \cos(Z) \\
 & + \cos(D_{solar}) \cos(L) \cos(S) \cos(A_{hour}) \\
 & + \cos(D_{solar}) \sin(L) \sin(S) \cos(Z) \cos(A_{hour}) \\
 & + \cos(D_{solar}) \sin(S) \sin(Z) \sin(A_{hour})


  • S is the slope of the incident surface (90° 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° 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.

Cloud Model

As of version 3.2 (Jojoba), GridLAB-D contains a cloud model suitable for replicating transients in solar PV production. The cloud model uses the TMY wind speed, wind direction, and the opaque sky value to generate a cloud pattern that moves and covers the sky as indicated by those values in the specified TMY file.

Cloud Model Parameters

Property Name Type Unit Description
cloud_model enumeration N/A The type of clouds generated by the model. At this time only "CUMULUS" is supported.
cloud_opacity double N/A (optional) The opacity of a full thickness cloud. This parameter allows users to model differences between dark thunderstorm clouds and lighter clouds with less moisture. Values must be between zero and one with a default value of 0.7.

Use of this model requires all solar PV installations to in latitude and longitude information. For example

 object solar {
 	name house_solar_panel;
 	phases CS;
 	parent house_solar_inverter
 	weather "Yakima";
 	area 117.34 m^2;
 	tilt_angle 90.0;
 	efficiency 0.05;
 	orientation_azimuth 180; //equator-facing (South)
 	orientation DEFAULT;
 	latitude 21.30812;
 	longitude -158.07935;

A minimal implementation of the cloud model could be:

object climate {
	name "Yakima";
	tmyfile "./WA-Yakima.tmy2";
	interpolate "QUADRATIC";
	cloud_model "CUMULUS";
	cloud_opacity 0.50;

It is highly recommended to use the QUADRATIC interpolation type to produce smooth transitions in cloud speed and direction.


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

Author: Nathan Tenney, Pacific Northwest National Laboratory, Richland, Washington (USA), PNNL-17615, May 2008