This weather plugin provides compatibility with the THERM weather files employed by DIRSIG since the earliest versions.

Plugin Input

The inputs to the plugin are given via a JSON object embedded directly into the plugin list of a simulation in the JSIM file. Below is an example of the input object:

{
  "name": "ThermWeather",
  "inputs": {
    "filename": "$DIRSIG_HOME/lib/data/weather/rochester_23_jun_1992.wth"
  }
}

In the example, filename is the name of a THERM formatted .wth file. The $DIRSIG_HOME variable allows the user to specify the default set of weather files included in each DIRSIG release.

A THERM weather history file (usually named with a .wth file extension) contain a time history of meteorological conditions at the scene site. Although this data is primarily used to drive temperature predictions, this file is required for all simulations because it is also used to update the boundary layer temperature in MODTRAN-based atmospheres. The format of the file dates back to the earliest days of DIRSIG, and that age shows in the simplicity of the file. The following is a list of notable things the user should be aware of about the file:

  • The file must contain exactly 48-hours of weather data so that DIRSIG can simulate any time during the current day and have at least 24-hours of previous weather history available to it.

  • The time resolution must be 15 minute (0.25 hour) intervals. DIRSIG will not interpolate the data from finer or courser data.

  • The time in the file is local time.

  • The date is not specified in the file, therefore the user can mistakenly use a file characterizing a summer day in a simulation for December. DIRSIG has no way to detect this problem.

  • The location is not specified in the files, therefore the user can mistakenly use a file characterizing an equatorial region in a simulation of an arctic region. DIRSIG has no way to detect this problem.

Tip Consider naming your weather files with the location and date encoded into the filename. For example, rochester_ny_23_jun_1992.wth. This will help you manually manage these files and overcome the limitations that the date and location are not explicitly stored in the file.

Format Details

The following example file can be found in $DIRSIG_HOME/lib/data/rochester_23_jun_1992.wth.

The first line indicates (a) the number of entries in the file (193 in this example) and (b) the time between entries (0.25 in this example).

Important The number of entries and delta time must be 193 and 0.25, respectively (193 entries results from 48 hours at 0.25, inclusively).

The remainder of the weather history file is organized as whitespace (spaces, tabs, etc.) separated column data, where each row contains values for a various fields at a given time.

 193 0.25
 0.00	 7.8	 1.0156e+3 .930	-1 1	 0	 0	 0.0 5 1 .025 7
 0.25	 7.8	 1.0156e+3 .930	-1 1	 0	 0	 0.0 5 1 .025 7
 0.50	 7.8	 1.0157e+3 .930	-1 1	 0	 0	 0.0 5 1 .025 7
 0.75	 7.8	 1.0158e+3 .930	-1 1	 0	 0	 0.0 5 1 .025 7
 1.00	 7.8	 1.0158e+3 .930	-1 1	 0	 0	 0.0 5 0 0 0
 [lines deleted for documentation purposes]
 11.50	 12.1	 1.0176e+3 .630	-1 2	 24.768  33.024  .40 5 0 0 0
 11.75	 12.5	 1.0176e+3 .590	-1 3	 54.352  28.483  .50 5 0 0 0
 12.00	 12.8	 1.0176e+3 .570	-1 3	 42.656  30.960  .50 5 0 0 0
 12.25	 13.0	 1.0175e+3 .560	-1 3	 42.312  33.850  .50 3 0 0 0
 12.50	 13.2	 1.0175e+3 .550	-1 3	 41.280  30.134  .50 3 0 0 0
 [lines deleted for documentation purposes]
 23.00	 10.5	 1.0148e+3 .621	-1 0.32	 0	 0	 1.0 0 0 0 0
 23.25	 10.1	 1.0140e+3 .719	-1 1.09	 0	 0	 1.0 0 0 0 0
 23.50	 9.0 	 1.0140e+3 .783	-1 0.01	 0	 0	 1.0 0 0 0 0
 23.75	 9.1	 1.0139e+3 .830	-1 0.01	 0	 0	 1.0 0 0 0 0
 24.00	 9.1	 1.0140e+3 .871	-1 0.00	 0	 0	 1.0 0 0 0 0
 24.25	 8.7	 1.0140e+3 .893	-1 0.01	 0	 0	 1.0 0 0 0 0
 24.50	 8.3	 1.0140e+3 .905	-1 0.01	 0	 0	 1.0 0 0 0 0
 24.75	 8.3	 1.0140e+3 .927	-1 0.00	 0	 0	 1.0 0 0 0 0
 25.00	 8.0	 1.0140e+3 .936	-1 0.01	 0	 0	 1.0 0 0 0 0
 [lines deleted for documentation purposes]
 36.00	 15.8	 1.0143e+3 .412	-1 0.05	 43.344	 21.053	 .50 6 0 0 0
 36.25	 16.3	 1.0143e+3 .390	-1 0.00	 59.856	 15.686	 .65 6 0 0 0
 36.50	 16.8	 1.0141e+3 .375	-1 0.59	 63.296	 13.622	 .70 6 0 0 0
 36.75	 16.5	 1.0141e+3 .378	-1 1.24	 67.080	 14.448	 .60 6 0 0 0
 37.00	 17.0	 1.0140e+3 .360	-1 0.36	 64.328	 16.925	 .70 6 0 0 0
 [lines deleted for documentation purposes]
 47.00	 13.8	 1.0101e+3 .763	-1 0.01	 0	 0	 0.0 6 0 0 0
 47.25	 13.9	 1.0100e+3 .787	-1 0.00	 0	 0	 0.0 6 0 0 0
 47.50	 13.5	 1.0098e+3 .770	-1 0.01	 0	 0	 0.0 6 0 0 0
 47.75	 13.7	 1.0098e+3 .710	-1 0.02	 0	 0	 0.0 6 0 0 0
 48.00	 13.9	 1.0098e+3 .687	-1 0.00	 0	 0	 0.0 6 0 0 0

Column Descriptions

Relative Time

The relative time in hours, where 0.00 corresponds to 0000 hours local time the day before the simulation, 24.00 corresponds to 0000 hours local time the day of the simulation and 48.00 corresponds to 2400 hours local time the day of the simulation.

Air Temperature

The air temperature in Celsius.

Air Pressure

The air pressure in mbar.

Relative Humidity

The relative humidity expressed as a fraction. This column can be set to -1 as long as the Dew Point column is valid.

Dew Point

The dew point in Celsius. This column can be set to -1 as long as the Relative Humidity column is valid.

Wind Speed

The wind speed in meters per second.

Direct Insolation

The broadband, direct (solar) irradiance in Langleys per hour. The conversion factor from watts/m2 to Langley/hour is 0.0860.

Diffuse Insolation

The broadband, diffuse (sky) irradiance in Langleys per hour. The conversion factor from watts/m2 to Langley/hour is 0.0860.

Sky Exposure

The relative sky exposure (clear sky vs. cloud) expresses as a fraction from 0 to 1, where a value of 1 indicates a 100% clear sky and and value of 0 indicates a 100% cloudy sky.

Cloud Type

If the Sky Exposure is less than 1, this column indicates the cloud type for the unexposed sky.
0 None
1 Cirrus
2 Cirrostratus
3 Altocumulus
4 Altostratus
5 Stratocumulus
6 Stratus
7 Nimbostratus
8 Fog

Rain Flag

This column controls the appearance of rain during the observation window. If this value is set to 0, then no rain was observed. If this value is set to 1 then the Rain Rate and Rain Temperature values are used.

Rain Rate

The rain rate in centimeters per hour.

Rain Temperature

The rain temperature in Celsius.

Note
Relative Humidity versus Dew Point
You only need a valid value (not -1) in either the Relative Humidity or the Dew Point column, not both.
Note
Wind Speed
It is strongly recommended to avoid wind speeds lower than 4 meters/second because the temperature predictions can become unstable when low wind speeds give rise to strong self-induced convection.
Note
Precipitation
The precipitation feature is very experimental, therefore, using this feature is strongly discouraged.

Usage by the THERM model

This weather file is predominately used by the THERM temperature prediction model, and this section attempts to explain how these weather parameters are used by the model:

Direct and Diffuse Solar Radiational Loads

The direct insolation represents the direct irradiance from the Sun. It is weighted by the solar absorption coefficient (material specific), the absolute value of the exposed area (material specific) and the relative cosine of the angle to the sun (geometry specific). The indirect of diffuse insolation is the indirect irradiance from the Sun (e.g. scattered sunlight or skylight). It is weighted by the solar absorption coefficient (material specific) and the absolute value of the exposed area (material specific).

Note Solar radiation is the dominant radiational load during daytime hours.

Under sunny conditions, direct radiation is the primary source of heating. The material’s solar absorption indicates how "dark" the surface is, which describes its ability to absorb the solar radiation. This is why darker objects tend to get warmer than lighter colored objects. If it is a cloudy day, the direct solar is lower as this radiation is absorbed or scattered by the clouds. As a result, objects will tend to be cooler on a cloudy day and temperature differences between sun and shadow areas will be less.

Sky Exposure, Cloud Type and Thermal Radiational Loads

The initial effective sky emissivity is computed using the air temperature and relative humidity. If the sky exposure is less than 1, then the effective sky emissivity is modified based the cloud type and the cloud coverage (1 minus the sky exposure). The total thermal radiation load is based on the air temperature weighted by the computed effective sky emissivity and the thermal emissivity (material specific).

Note Thermal radiation is the dominant radiational load during night hours or when the solar radiation is very low (overcast day).

A surface is constantly radiating away heat in the thermal wavelengths. If the net thermal radiation flux is negative, you get "radiational cooling", which is common in overnight hours under certain conditions. If the night sky is clear, the effective sky emissivity is low and the apparent sky temperature will be low. It is under these conditions that the net radiation out of the surface is positive, causing the surface to cool. On a cloudy night, the effective sky emissivity is higher resulting in an apparent sky temperature that is higher. Under these conditions, the net radiation out of the surface can be low (or even negative), causing the surface to maintain temperature or even warm.

Summary of impacts

The direct and diffuse insolation terms in the weather file drive the broad band, solar (short wavelength) radiational load. The air temperature, relative humidity (or dew point temperature), sky exposure and cloud cover drive the broad band therm (long wavelength) radiational load. The solar and therm radiational loads are respectively weighted by the material’s solar absorption and thermal emissivity coefficients.

Important The sky exposure does not modify the direct or diffuse insolation. Hence, changing the sky exposure to indicate more clouds does not automatically reduce either the direct or diffuse insolation.
Clear Conditions

The direct insolation will be high, and the diffuse insolation will be moderate. The sky exposure will be 1 and the cloud type will be irrelevant.

Partly Sunny/Cloudy Conditions

The direct insolation will temporally oscillate between high and low values as clouds temporarily block the sun. The diffuse insolation may be slightly higher than clear sky conditions as the effective albedo of thin clouds can be higher than that of a clear sky. For thicker clouds, the diffuse insolation might be lower since the clouds might absorb more sun than scatter it. The sky exposure should be less than 1 and the appropriate cloud type should be specified.

Cloudy Conditions

The direct and diffuse insolation values will be generally lower than under clear conditions. The sky exposure should be significantly less than 1 and the appropriate cloud type should be specified.

Making WTH Files

Using Hourly Observations

A weather file can be created from hourly observation data provided by the National Weather Service (NWS) and other sources, provided that the user can perform the following tasks:

  • The user can interpolate the hourly data down to 15 minutes (0.25 hours).

  • The user can fill in the direct and diffuse insolation (irradiance) fields from another source (these values are normally not provided in a standard station observation).

Using Forecast Values

The user can run the Generate weather tool available in the Tools menu in the Atmosphere Editor to create a valid weather file using values available in most daily forecasts. This includes:

  • The air minimum temperature

  • The air maximum temperature

  • The average air pressure

  • The average wind speed

The user also supplies the tool with the date and location, which is used to estimate the direct and diffuse insolation fields.

Using the "makewth" tool

A simple Python tool is distributed with DIRSIG called makewth, which can take weather data from the National Solar Radiation Database (NSRDB) and convert it into a DIRSIG compatible weather file.

Demos

The WeatherPlugins1 demo gives an example of how to set up the ThermWeather plugin in a JSIM simulation and includes a sample THERM .wth weather file.