0% found this document useful (0 votes)

548 views

AuxiliaryPrograms PDF

EnergyPlus 1 Auxiliary Programs Introduction 2 Weather Converter Program 2. Using the Weather Converter 2.4. File Menu 2.4. Converting Data 2. Definitions File and Custom File Processing 2.5. Reports / Files Produced by the Weather Converter 2.5.

Uploaded by

tiramisu_man3190

Available Formats

Download as PDF, TXT or read online on Scribd

0% found this document useful (0 votes)

548 views

AuxiliaryPrograms PDF

Uploaded by

tiramisu_man3190

Available Formats

Download as PDF, TXT or read online on Scribd

You are on page 1/ 165

Table of Contents

EnergyPlusTM Documentation, v8.4.0

Auxiliary EnergyPlus Programs

8
8

Extra programs for EnergyPlus

1 Auxiliary Programs Introduction

2 Weather Converter Program

10
10

2.1 Background

2.2 Weather Format for Simulation Programs

2.3 Weather Data Availability

2.4 Using the Weather Converter

2.4.1 File Menu

2.4.2 Converting Data

2.4.3 Help

2.5 Definitions File & Custom File Processing

2.5.1 Description of "Def" input file

2.5.2 Expected Formats for &location

2.5.3 Expected Formats for &miscdata

2.5.4 Expected Formats for &wthdata

2.5.5 Custom Files - Auxiliary Data

2.5.6 Expected Formats for &datacontrol

2.5.7 Def File Examples

2.5.8 Custom File Processing

2.5.9 Custom File Processing - Solar Radiation Value Calculation

2.6 Reports/Files Produced by the Weather Converter

2.6.1 Audit / Log File

2.6.2 Statistical Report File

2.6.3 Design Day Calculations Output

2.7 Kppen Climate Classification

2.7.1 Tropical Moist Climates (A)

2.7.2 Dry Climates (B)

2.7.3 Moist Subtropical Mid-Latitude Climates (C)

2.7.4 Moist Continental Mid-latitude Climates (D)

2.7.5 Polar Climates (E)

2.7.6 Highlands Areas (H)

2.8 ASHRAE Climate Classification

2.9 EnergyPlus Weather File (EPW) Data Dictionary

2.9.1 Data Field Descriptions

2.9.2 References

2.10 EPW CSV Format (In/Out)

2.10.1 Location Header/Data (CSV)

2.10.2 Design Conditions Header/Data (CSV)

2.10.3 Typical/Extreme Periods Header/Data (CSV)

2.10.4 Ground Temperatures Header/Data (CSV)

2.10.5 Holiday/Daylight Saving Header/Data (CSV)

2.10.6 Comment 1 Header/Data (CSV)

2.10.7 Comment 2 Header/Data (CSV)

2.10.8 Data Period Header/Data (CSV)

2.10.9 Data Records (CSV)

2.11 Missing Weather File Data

2.12 Source Weather Data Formats

2.12.1 Data Set vs. Data Format

2.12.2 SAMSON Data Set/Format

2.12.3 TMY2 Data Set/Format

2.12.4 Solar and Wind Energy Resource Assessment (SWERA) Format

2.12.5 WYEC2 Data Set/Format

2.12.6 Canadian Weather for Energy Calculations (CWEC)

2.12.7 International Weather for Energy Calculations (IWEC)

2.12.8 Typical Meteorological Year (TMY)

2.12.9 California Climate Zones 2 (CTZ2)

2.12.10 Solar and Wind Energy Resource Assessment (SWERA)

2.12.11 Spanish Weather for Energy Calculations (SWEC)

2.12.12 Italian Climatic data collection "Gianni De Giorgio" (IGDG)

2.12.13 Chinese Typical Year Weather (CTYW)

2.12.14 INETI Synthetic data for Portugal

2.12.15 ISHRAE India Weather Data Files (ISHRAE)

2.12.16 City University of Hong Kong (CUHK) Data Set

2.12.17 Chinese Standard Weather Data (CSWD)

2.12.18 Kuwait Weather Data from Kuwait Institute for Scientific Research (KISR)

2.12.19 Egyptian Weather for Energy Calculations (EWEC)

2.12.20 Israel weather data (MSI)

2.12.21 Representative Meteorological Year (RMY) Australia Climatic Data

2.12.22 Iranian Typical Meteorological Year (ITMY)

2.12.23 New Zealand National Institute of Water & Atmospheric Research Ltd (NIWA)

2.12.24 Chartered Institution of Building Services Engineers (CIBSE)

2.12.25 Meteonorm Data

2.12.26 Other Formats

2.12.27 Custom Format

2.12.28 Solar Data

2.13 Data Sources/Uncertainty

2.14 Advanced use - accessing weather conversion capabilities

2.14.1 Interface to the EPlusWth.dll

2.14.2 Files used by EPlusWth.dll

2.14.3 Public calls to EPlusWth.dll

2.15 References

2.16 Web Resources

69
2

3 Ground Heat Transfer in EnergyPlus

3.1 Caution

3.2 Introduction

3.3 Use of the Ground Temperatures with Slabs

3.4 Slab configuration Drawing

3.5 Running the Slab Program

3.6 Technical Details on Files for Ground Heat Transfer with Slabs

3.7 Slab Program Output Files

3.7.1 EnergyPlus idf Objects from Slab Program

3.8 Description of the Objects in the E+SlabGHT.IDD

3.8.1 Materials or GroundHeatTransfer:Slab:Materials Object

3.8.2 MatlProps or GroundHeatTransfer:Slab:MatlProps Object

3.8.3 BoundConds or GroundHeatTransfer:Slab:BoundConds Object

3.8.4 BldgProps or GroundHeatTransfer:Slab:BldgProps Object

3.8.5 Insulation or GroundHeatTransfer:Slab:Insulation Object

3.8.6 EquivalentSlab or GroundHeatTransfer:Slab:EquivalentSlab Object

3.8.7 EquivSlab Object - Obsolete

3.8.8 EquivAutoGrid Object - Obsolete

3.8.9 Additional Objects

3.8.10 Sample IDF File - Slab Program

3.9 Using Ground Temperatures with Basements

3.10 Running the Basement Program

3.11 Technical Details on Files for Ground Heat Transfer with Basements

3.12 Basement Program Output Files

3.13 The Basement idd

3.14 Description of the Objects in the BasementGHT.idd

3.14.1 SimParameters or GroundHeatTransfer:Basement:SimParameters Object

3.14.2 MatlProps or GroundHeatTransfer:Basement:MatlProps Object

3.14.3 Insulation or GroundHeatTransfer:Basement:Insulation Object

3.14.4 SurfaceProps or GroundHeatTransfer:Basement:SurfaceProps Object

3.14.5 BldgData or GroundHeatTransfer:Basement:BldgData Object

3.14.6 Interior or GroundHeatTransfer:Basement:Interior Object

3.14.7 ComBldg or GroundHeatTransfer:Basement:ComBldg Object

3.14.8 EquivSlab or GroundHeatTransfer:Basement:EquivSlab Object

3.14.9 EquivAutoGrid or GroundHeatTransfer:Basement:EquivAutoGrid Object

3.14.10 Sample idf File - Basement

3.14.11 Additional Objects

3.15 Using the Interface Surface Temperature Results in EnergyPlus

3.15.1 Multiple Ground Temperatures

93
94

3.16 References

4 View Factor Calculation Program

4.1 Associated Files

95
3

4.2 Using the View Factor Interface program

4.3 Additional Information

5 Using Older Version Input Files - Transition

5.1 IDF Version Updater

5.2 Transition Console Program Details

5.3 IDF Version Converter / Transition File Lists

100

5.4 Converting imf files

100

6 EPDrawGUI

101

6.1 Main Tab

101

6.2 Option Tab

101

7 Input Macros

102

7.1 Introduction

102

7.2 Running the EP-Macro program

102

7.3 Incorporating External Files

103

7.4 Selectively Accepting or Skipping Lines of Input

104

7.5 Defining Blocks of Input

105

7.5.1 Arithmetic Operations

107

7.6 Macro Debugging and Listing Control

108

7.7 Listing Format

110

8 HVAC Diagram

110

8.1 Introduction

110

9 CoeffConv/CoeffCheck

114

9.1 CoeffConv

114

9.2 CoeffCheck

114

9.3 Running the CoeffConv or CoeffCheck programs

115

10 ExpandObjects

115

10.1 Introduction

115

10.2 HVAC Template Objects Processed

115

10.3 Ground Heat Transfer Objects Processed

116

10.4 Building Surface Objects Processed

117

11 CSVproc
12 convertESOMTR
13 CalcSoilSurfTemp Program

117
118
119

13.1 Running the Program

119

13.2 Program Inputs

119

13.3 Program Outputs

120
4

14 HVAC Performance Curve Fit Tool

122

14.1 Introduction

122

14.2 Inputs

123

14.3 Rated Data

123

14.4 Performance Data

123

14.5 Outputs

123

14.6 Error Message

124

14.7 Notes

124

14.8 References

125

15 Parametric Spreadsheets

125

15.1 Water-to-Water Heat Pump Parameter / Coefficient Generator (Cooling and Heating Mode)
15.1.1 Step 1: Catalog Data Input
125125
15.1.2 Parameter Estimation Procedure

126

15.1.3 End Parameter Estimation Procedure

127

15.1.4 Curve Fit Model Procedure

127

15.1.5 End Curve Fit Model Procedure

127

15.2 Water-to-Air Heat Pump Parameter / Coefficient Generator (Cooling)

127

15.2.1 Step 1: Catalog Data Input

127

15.2.2 Parameter Estimation Procedure

128

15.2.3 End Parameter Estimation Procedure

129

15.2.4 Curve Fit Model Procedure

129

15.2.5 End Curve Fit Model Procedure

129

15.3 Water-to-Air Heat Pump Parameter / Coefficient Generator (Heating Mode)

129

15.3.1 Step 1: Catalog Data Input

130

15.3.2 Parameter Estimation Procedure

130

15.3.3 End Parameter Estimation Procedure

131

15.3.4 Curve Fit Model Procedure

131

15.3.5 End Curve Fit Model Procedure

132

15.4 G-Function Spreadsheet

132

16 ParametricPreprocessor
17 AppGPostProcess - Appendix G PostProcessing program
18 BLASTTranslator
19 DOE2Translator
20 Running Console Applications
20.1 Modifying the batch file

132
133
133
134
135
135

21 Technical Details of Running EnergyPlus

21.1 EP-Launch Program

136
136

21.1.1 Start EP-Launch

137

21.1.2 Selecting Input and Weather Files

137

21.1.3 Running a Single Input File

137

21.1.4 Looking at the Results

137

21.1.5 Viewing the Drawing File without Running a Simulation

140

21.1.6 Editing the Input Files

140

21.1.7 File Menu

140

21.1.8 Edit Menu

140

21.1.9 View Menu

140

21.1.10 Help Menu

143

21.1.11 Recently Used Files

143

21.1.12 Running Groups of Input Files

143

21.1.13 History of Simulations Performed

146

21.1.14 Utilities Tab

146

21.1.15 Caveats

147

21.1.16 When things go wrong

147

21.1.17 Bugs

148

21.2 EP-Launch Lite

148

21.3 EnergyPlus File Extensions

148

21.3.1 Input Files

148

21.3.2 Output Files

149

21.3.3 Postprocessing Program/Files

150

21.4 RunEPlus batch file

150

21.5 Running EnergyPlus by Hand

150

21.6 RunEPlus details

151

21.7 RunDirMulti Batch File

152

21.8 EnergyPlus Files

152

21.8.1 Input Files

152

21.8.2 Output Files

153

21.8.3 Postprocessing Program/Files

154

22 Creating Input Files

154

22.1 IDD Conventions

155

22.2 IDFEditor

159

22.2.1 Start IDF Editor

159

22.2.2 Creating or Selecting an Input Data File

159

22.2.3 Class List and Objects

159

22.2.4 Changing Values

160

22.2.5 Edit or Select Node Names Dialog

160

22.2.6 Working with Objects

161

22.2.7 File Menu

161

22.2.8 Edit Menu

162

22.2.9 View Menu

163

22.2.10 Help Menu

164

22.2.11 Caveats

164

22.2.12 Bugs

164

23 Manipulating Output Files

164

23.1 EP-Compare

164
6

EnergyPlusTM Documentation, v8.4.0

Auxiliary EnergyPlus Programs

Extra programs for EnergyPlus

(Extra! Extra! Read all about it!)

COPYRIGHT (c) 1996-2015 THE BOARD OF TRUSTEES OF THE UNIVERSITY OF ILLINOIS AND THE REGENTS OF THE UNIVERSITY OF CALIFORNIA THROUGH THE ERNEST ORLANDO
LAWRENCE BERKELEY NATIONAL LABORATORY. ALL RIGHTS RESERVED. NO PART OF THIS MATERIAL MAY BE REPRODUCED OR TRANSMITTED IN ANY FORM OR BY ANY MEANS
WITHOUT THE PRIOR WRITTEN PERMISSION OF THE UNIVERSITY OF ILLINOIS OR THE ERNEST ORLANDO LAWRENCE BERKELEY NATIONAL LABORATORY. ENERGYPLUS IS A
TRADEMARK OF THE US DEPARTMENT OF ENERGY.

1 Auxiliary Programs Introduction

This document will describe several of the "auxiliary programs" of the EnergyPlus system in more detail. Some of these programs are only available or only
distributed for certain platforms. Typically, the programs are available on the Windows platform. Within the descriptions, other platforms will be noted as
applicable. These programs include:
Weather Converter Program (aka "Weather")
Ground Heat Transfer in EnergyPlus - Procedure for Ground Temperature creation
View Factor Calculation Program - Auxiliary program used to calculate View Factors which can be used with EnergyPlus
Using Older Version Input Files - Transition - to convert input files from one version to another upon release of a new version
EPDraw - Create DXF files from your input files
Input Macros - Use a macro language to increase efficiency in creating EnergyPlus input files. Unfortunately, IDF files containing macros cannot be read in the
IDF Editor.
HVAC Diagram - Use a post processing program to diagram your HVAC inputs.
CoeffConv/CoeffCheck - Convert DOE-2 temperature dependent curves (Fahrenheit) to EnergyPlus temperature curves (Centigrade/Celsius)
ExpandObjects - Some technical details of the Expand Objects program which preprocessed HVACTemplate:* and GroundHeatTransfer:* objects for use inside
EnergyPlus.
CSVproc - Get simple statistics from CSV output files.
convertESOMTR - convert your outputs to Inch-Pound (default) or other custom unit conversions.
CalcSoilSurfTemp Program - calculate soil surface parameters used in the Earth Tube simulation
HVAC Performance Curve Fit Tool- generates HVAC performance curves in EnergyPlus IDF format
Parametric Spreadsheets - Parametric spreadsheets are available to help illustrate or calculate some parameters/coefficients.
ParametricPreprocessor - Special objects can be inserted in IDF files and generate a series of IDF files from a single source IDF file that contains parametric
objects and expressions. Unlike using the macro language, these input files are capable of being read in the IDF Editor.
AppGPostProcess - Appendix G PostProcessing program - The ASHRAE 90.1 Appendix G postprocessing program takes simulation outputs and processes
them to help meet Appendix G requirements..
BLASTTranslator - The BLAST translator can take BLAST (Building Loads Analysis and System Thermodynamics) input files and make them ready for running
in EnergyPlus.
DOE2Translator - The DOE-2 translator can take DOE-2 program input files and make them ready for running in EnergyPlus.
Running Console Applications - this section describes how to run console applications that are part of EnergyPlus and how you might modify these to your
specific needs. Instructions for running individual programs are included in their descriptions.
Technical Details of Running EnergyPlus - this section gives full instructions on both EP-Launch and the IDF-Editor as well as some more details on running
EnergyPlus manually.
EP-Compare - A utility to graphically compare tabular results from multiple simulation files.

2 Weather Converter Program

The Weather Converter program is stored in the EnergyPlus folder area under "PreProcess" and subsequently in the "WeatherConverter" folder.
To perform annual/run period simulations in EnergyPlus, one needs weather data. Most weather data is still issued in an hour by hour (hourly) format though as
you will see, EnergyPlus and its weather converter can accept data that has a finer resolution on the data (such as every 10 or 15 minutes).
The special weather format (EPW) used in EnergyPlus is a simple, ascii format as is common in the rest of the inputs for EnergyPlus.

2.1 Background
All building simulation programs employ some means of representing local climatic conditions relative to the building models. For example, Radiance (Ward
1996) needs a description of sky conditions and illuminance values to calculate solar distribution through a window and within a space. Three of the widely used
energy simulation programs in the UK and US, ESP-r (ESRU 1999), BLAST (UI 1998), and DOE-2 (Winkelmann et al. 1993) also use weather conditions to
simulate the response of a building. But even after 30 years of significant development advances in simulation capabilities, these programs use the same climate

representations as in the past-a simple set of hourly temperature, humidity, wind speed and direction, and atmospheric pressure and solar radiation or cloud
cover data. These data are often 'typical' data derived from hourly observations at a specific location by the national weather service or meteorological office.
Examples of these typical data include TMY2 (NREL 1995) and WYEC2 (ASHRAE 1997) in the United States and Canada and TRY (CEC 1985) in Europe. The
TMY2 and WYEC2 typical weather years contain more solar radiation and illumination data than older formats such as TMY (NCDC 1983), WYEC (ASHRAE
1985), and TRY (NCDC 1981) in the U.S. Crawley (1998) demonstrated that the methods used to select data for the US TMY2 and European TRY data sets
better fits the long-term climate patterns.
Radiation and illumination data are becoming increasingly necessary in simulation programs. Anyone who has ever attempted to measure daylight factors will be
familiar with the fluctuations in lighting levels under partly cloudy conditions. The expansion and contraction of lightweight building components also shares
sensitivity to rapid fluctuations in solar radiation. Single-sided ventilation is dependant on wind pressure fluctuations and pedestrians in many cities are
acquainted with the disarming tendency of the wind to guest and change direction. It is increasingly the case that design questions touch on such issues.
In a research context, the advent of tools such as LabVIEW (National Instruments Corporation 1999) have made it possible for increasing numbers of researchers
to acquire and process test-cell data. The increasing use of building energy management systems (BEMS) has also provided high frequency information from
which simulation could be used as a predictive tool for future control strategies. Other issues of control, particularly of advanced daylighting control require subhourly illumination data to ensure that possible control regimes are tested under realistic conditions. Janak (1997) observed that the differences between 5
minute and hourly illumination data could result in prediction variations approaching 40%.
Thus far, projects that mix empirical and simulation-based work have had to store and access such data via temporal database facilities (ESRU 1999). As the
number of high quality datasets increases so does the need to encapsulate such information in a form that can be broadly distributed. The simulation community
must also consider the uncertainty in high frequency performance predictions that are based on boundary conditions that have been sampled at one or two
magnitudes less temporal resolution.
The simulation community must also consider practitioner demands and issues of quality assurance. Someone who is not a native of Copenhagen may not know
that there are three or four recognizable patterns of winter weather that should be included in detailed assessments. A data set that lacks documentation or is
dependent on separately held lists of assumptions can be effectively useless.
In the absence of data within the weather data format, the simulation programs must calculate these data often with older calculation methods. As the simulation
programs have become more capable, data at hourly resolution is no longer enough-interpolating between hourly observations does not accurately represent
weather conditions that change much more frequently such as illumination.
We have developed a generalized weather data format for use by energy simulation programs has been developed and adopted by both ESP-r (in the UK) and
EnergyPlus (in the US). Anticipating the need for data at time steps less than one hour, the format includes a minute field to facilitate the use of sub hourly data.
The data include basic location identifiers such as location name, data source, latitude, longitude, time zone, elevation, peak design conditions, holidays,
daylight saving period, typical and extreme periods, ground temperatures, period(s) covered by the data and space for descriptive comments. The time step data
include dry bulb and dew point temperature, relative humidity, station pressure, solar radiation (global, extraterrestrial, horizontal infrared, direct, and diffuse),
illuminance, wind direction and speed, sky cover, and current weather.

2.2 Weather Format for Simulation Programs

For these reasons, we developed a generalized weather data format for use with two major simulation programs-ESP-r and EnergyPlus (Crawley et al. 1999). All
the data are in SI units. The format is simple, text-based with comma-separated data. It is based on the data available within the TMY2 weather format but has
been rearranged to facilitate visual inspection of the data. The TMY2 data are a strict, position-specific format-filling missing data with nines and zero values with
zeroes. The new weather data format contains commas to facilitate data reading and analysis with spreadsheet programs. By eliminating redundant 'fill' values,
the size of each file is only slightly larger than the original TMY2 format. Details about the TMY2 format can be found in the TMY2 User's manual (see references
at the end of this section).
The traditional distribution of data source and uncertainty flags within the raw data fields carries with it not only the need for many field separators, it obfuscates
the relationships between non-numerical data. In a set of minute data, which could easily require hundreds of thousands of records, the space penalty is
considerable. In the E/E file format, all data source and uncertainty fields have been clumped together as a single field immediately following the day and time
stamp. For applications where uncertainty is not an issue such data can be easily ignored. When it is important, a single text field is conceptually and
computationally easy to parse.
Another difference between the EnergyPlus/ESP-r (E/E) format and TMY2 is the addition of two new data fields-minute and infrared sky. The minute field
facilitates use of data observed at intervals of less than one hour such as measured data from a research study of energy efficiency for a particular building. This
will allow easier and more accurate calibration of a simulation model to measured data than possible in the past. The infrared sky field allows the programs to
calculate the effective sky temperature for re-radiation during nighttime.
The last difference is that a full year of data (such as 8760 hours) is not required-subsets of years are acceptable. Which periods are covered by the data is
described in the files. Periods of typical weather patterns based on analysis of the data are also included within the format. A side-by-side comparison of data
included in the E/E weather format with data previously used by ESP-r, DOE-2, and BLAST is shown in Table 1. A deficiency noted within ESP-r for example is
the lack of correcting air volumes for elevation change-many of the users of ESP-r are in relatively low elevations. For DOE-2 and BLAST, neither program used
illumination data in daylighting calculations or infrared sky temperatures-it was always recalculated at time of use.
By including the uncertainty and data source information found in TMY2, users now can evaluate the potential impact of weather variability on the performance of
the building.

McDonald and Strachan (1998) are introducing uncertainty analysis into ESP-r.
We use the EnergyPlus data dictionary format to describe the E/E weather data set. (See the end of this document). Each line in the format is preceded by a
keyword such as LOCATION, DESIGN CONDITIONS, followed by a list of variables beginning either with A or N and a number. A stands for alphanumeric; N for
numeric. The number following A/N is the sequence of that number in the keyword list. Commas separate data. (Refer to the IDD Conventions document in
"Input Output Reference" for further explanation of the format). The header information consists of eight lines (keywords): LOCATION, DESIGN CONDITIONS,
TYPICAL/EXTREME PERIODS, GROUND TEMPERATURES, HOLIDAYS/DAYLIGHT SAVINGS, COMMENTS 1, COMMENTS 2, and DATA PERIODS. This is
followed by the time step data.
The first eight lines or header within each E/E weather file define basic location information such as longitude, latitude, time zone, elevation, annual design
conditions, monthly average ground temperatures, typical and extreme periods, holidays/daylight saving periods, and data periods included. There is also space
for users to document any special features or information about the file such as sources of data.

2.3 Weather Data Availability

Typically, acquisition of weather data has been a user's burden. Though this will remain the case in many instances for EnergyPlus users, the EnergyPlus team
has been successful in making a wealth of US, Canadian and International data available to our users. To summarize, the weather data for 2092 locations is
available at the EnergyPlus web site: www.energyplus.gov
The details are shown in Table 18. Summary of Downloadable Weather Data by Type. This data has been selected with the energy simulation user in mind. All
the data (as well as the statistical reports - described later in this document) are downloadable for individual locations.
Table 1. Comparison of E/E with ESP-r/DOE-2/BLAST Weather Data Formats
Data Element
Location (name, latitude, longitude, elevation, time
zone)

DOE-2 BLAST ESP-r E/E

Data source

X
X

Commentary

Design conditions

X
X

Typical/extreme periods

Data periods

X
X

Holiday/Daylight Saving

Solar Angles/Equation of Time Hours

Degree Days

Year

Month

Day

Hour

Minute

Data source and uncertainty flags

Dry bulb temperature

Wet bulb temperature

Dew point temperature

Atmospheric station pressure

Humidity ratio

Density

Wind Speed

Wind Direction

Infrared Sky Temperature

Solar Radiation (global, normal, diffuse)
Illuminance (global, normal, diffuse)
Sky cover (cloud amount)

X
X

Relative humidity
Enthalpy

X
X

Opaque sky cover

Visibility

Ceiling height
Clearness (monthly)

X
X

"Undisturbed" Ground temperatures (monthly)

Present weather observation and codes (rain, snow)

X
X

Precipitable water

Aerosol optical depth

Snow depth

Days since last snowfall

Albedo

Liquid Precipitation Depth

Liquid Precipitation Quantity

2.4 Using the Weather Converter

We developed a utility for the E/E format to read standard weather service file types such as SAMSON and newer 'typical year' weather files such as TMY2,
WYEC2, and IWEC. The utility also reads ESP-r (CLM format), DOE-2 (fmt format), BLAST (Ascii format) files and other files.
The utility translates and extends typical weather data into the E/E format. The processor makes the calculations necessary for supplying data (when data is
missing) and calculates the Horizontal Infrared Radiation Intensity values-not typically currently an observed value reported by the meteorological offices through
the world. The utility also prepares an statistical summary of the weather data set as part of the processing. An additional "output format" from the utility is a
comma-delimited file that can easily be imported into a spreadsheet program such as Excel for further user perusal, charting and/or editing.
The utility consists of two parts: a user interface that executes on standard Wintel systems and a DLL that does the work of the processing. The DLL interface is
described in a later section for those developers who might wish to access it directly.
The user front end is a simple to use program with standard graphical user interface menus. It is executed from the Start Menu programs using the specific folder
where the EnergyPlus program was installed. (e.g., Start Menu -> EnergyPlus <version> -> WeatherConverter). For convenience, it automatically opens with the
"convert" option.
EP-Launch can also be used to run the weather utility program. Weather is one of the options on the Utilities tab in EP-Launch. See the section on EP-Launch in
this document for more information on how to use EP-Launch with the weather utility program.

Figure 1. Main menu screen of the Weather Converter Utility

2.4.1 File Menu

The file menu has four options:
2.4.1.1 Fix Out of Range Data
This is a toggle option that once selected is saved in the registry with other options (for example, screen size) for the program. As shown in the IDD type
description of the Weather Data, there are minimum and maximum values for several of the fields. The weather converter program can ignore these (and just
report them) or it can try to fix them with appropriate values. If the option is "checked", then the processor will try to fix the data; if it is blank, the processor will not
fix the data though it will report any out of range data that it finds.
2.4.1.2 Select Delta DB Trigger
Depending on the quality control and accuracy of the weather data collection, time period (usually hour to hour) changes in some data values may make the
data suspect for that time period. This selection brings up the screen shown below and will allow the user some control over the actual value reporting. Note that
this data is not "fixed", merely reported by the program in the audit output file.

Figure 2. Delta DB Trigger Selection

Though only one "trigger" value is selected from this screen, consecutive values of dry-bulb temperature, dew-point temperature and wind speed are reported
using appropriate calculated values. Both dew-point and wind speed use a calculated value based on mean of their values over the entire data period and
standard deviation from that mean, heuristically derived.
An excerpt from the audit file is illustrative:
Average Delta DB Change= 0.78C ; Std Dev= 0.83C
Average Delta DP Change= 0.68C ; Std Dev= 0.78C
Average Delta Relative Humidity Change= 4.02% ; Std Dev= 4.22%
Average Delta Wind Speed Change= 0.91m/s ; Std Dev= 0.88m/s
Hourly Dry Bulb temperature change trigger = minimum of 12.13C and 10.C
12.13C = calculated trigger based on mean change in dry-bulb temperature and standard deviation shown above
10.C = trigger set by user
Here the calculated DB trigger would be 12.13C, but the user chosen trigger is 10C. Changes >= 10C will be reported.
Delta DB/DP Range Triggered for Apr 30
Change in DB= 11.60C, Hour=14
Such detail allows the user to hand edit the incoming data, if desired.
2.4.1.3 Delete File
You may use this menu option to browse your computer and delete files.
2.4.1.4 Input Folder => Output Folder
Choosing this option (a check will show and will carry over from one use to the next) sets the output folder for saving files to be the same as the input folder
where the original files are located.
2.4.1.5 Exit
This choice exits the program.

2.4.2 Converting Data

This screen is automatically shown when you start the program - it will allow you to select raw data for processing, change the default type (based on file
extension), select the kind of conversion you want, select where and what name to store for the processed data, and process the data. An "almost" completed
screen shows:

Figure 3. Convert Data Screen selections

The screen is navigated by choosing the following buttons on the left portion of the screen. Interpretation from the program is shown in the status boxes on the
right portion of the screen.
2.4.2.1 Select File to Convert
Selecting this command button brings up a common dialog interface that allows you to select a file for conversion from a specific set of default file extensions.
These are shown in the following table. Note that you can (mostly) override the default file extension by the use of a simple DEF file and change the input file
type.
Table 2. Input File Extensions with implied Data types
File
Extension
LST

Implicit Data File Type

Processing List of Files

<any> or CST Custom - must have "def" file as specified below

EPW
CSV

EnergyPlus E/E
Comma Delimited File (EPW Format) Note: special EnergyPlus CSV format. For other CSV files use the DEF file and describe the
format.

TM2

TMY2

TMY

IWC

IWEC

WY2

WYEC2

DAT

SAMSON

FMT

DOE-2 Formatted File

CLM

ESP-r Climate Formatted File

ASC

BLAST ASCII

SWE

SWERA

WEA

Ecotect WEA file

Of course, the "all files" (*.*) may be used as well. If the file selected is not one of the above types, you will be cautioned to use the "override default type" button
to select the correct type before proceeding. Most of the data file types are described in other publications and won't be described in detail here.
Note on the input CSV format: It is the EPW CSV format. The CSV format must mirror the output CSV format very closely. The processor expects a Location
header record and the headers for the data fields as a minimum (as well as the data that supports those header fields). If you have a differently formatted file,
possible comma delimited, investigate the "custom" format option.
The LST data type allows you to specify a list of files to be "batch processed". The format of this file is very simple (however, the default extensions from the
preceding table must be used or you must include a "def" file - see below for details).
Each line of the LST file can have a columnar structure as shown in the following table or can have the input file separated from the output file with a TAB
character.
Table 3. LST File Structure
Columns

Contents

1-45

Name of Input File to be Processed

46-105 (or follow the first name with a

Output File with: EPW - same as output type "EPW" CSV - same as output type "CSV" Both - same as output type

{TAB})

"both" Rpt - same as output type "rpt"

106-end (or follow the second name

with a {TAB})

URL for KML output

2.4.2.2 Definitions File

An auxiliary file, the Definitions File (extension .def) can be used to specify additional or replacement characteristics for the incoming data. This file is fully
described in the section "Definitions File & Custom File Processing" later in this document.
2.4.2.3 Override Default Type
This button is used as described above to select the correct data type for a file that might have one of the standard "default" extensions but may, in fact, be a
data file of an entirely different type. For example, the BLAST ASCII files as they exist on the BLAST CD have extensions of .dat - our default type for the
SAMSON data. You must select the proper data type for your data or the processor probably won't work anywhere near what you expect.
2.4.2.4 Select Output Format
You may select from four options of output format:
EPW Format -- both an epw file and a statistical report file are produced
CSV Format - both a csv file and a statistical report file are produced
Both EPW and CSV - epw, csv, and statistical report files are produced
Rpt only - only a statistical report file is produced (output extension is "stat")
Note that the CSV file is very similar to the EPW format file but is ready to be imported into a spreadsheet program such as Excel and has some additional
"header" records in front of each EPW style header record
2.4.2.5 Save File As
This button allows you to select the location to save your file set from the output format selection. The utility automatically places a "data type" extension on the
file name to show its original data file type.
Note on Save As Since you select the "save as" file name from a dialog, the processor DOES NOT warn you of overwriting previous files of the same name. In
addition, if you have previously saved several types (e.g. EPW and CSV) but this time only save the RPT - it DOES NOT create new of the others nor does it
delete the previous ones.
2.4.2.6 Convert File
Pressing this button causes the processing of the data to proceed. If you choose a ".lst" input format, you will see messages as each once is completed and/or
has errors. If you choose a single data file, you will see a similar message box once the processing is done (or has terminated due to errors).

2.4.3 Help
No online help is available. This brings up an "about" box for the program.

2.5 Definitions File & Custom File Processing

2.5.1 Description of "Def" input file
Some of the data formats have inherent omissions (e.g. TMY does not have location data, BLAST ASCII does not have elevations). In order to overcome this
limitation and to provide further flexibility, a definitions file (extension must be .def) is implemented. By naming this with the same "file name" as your input file (in
the same folder), the weather converter will read the format and use that data, as appropriate, in the file conversions. The .def file uses Fortran "Namelist" input
fields as shown in the example below. For flexibility, you can also define a "presets.def" file (such as when you have a list of files to process and the format or
some portion is all the same between the group of files. The two def files (one named the same as the file name for the raw data and one named presets.def) will
both be processed. Conflicts between the two will be shown in the .audit file. The set of namelist groups is:
&location - Location data
&miscdata - Comments to be applied to "COMMENT2" in the EPW file and "Source Data"
&wthdata - weather data specifications including file type, custom formats
&datacontrol - user specified control over "missing" data (Custom format only)
Note that the "Def" formats are entirely different from the usual IDF formats of EnergyPlus. No commas separate fields. No semicolon terminates the
entry.
&location

City='Hong Kong'
StateProv=' '
Country='CHN'
InLat=22.75
InLong=115
InTime=8
InElev=0
InWMO=450040
/
&miscdata
Comments1='This file was given to us by....'
SourceData='Original xyz data'
/
The "slash" (/) character terminating each block is very important - omissions results in incorrect reading of data.
Definitions File Details are shown in the following table. You may leave out a field if you wish - the program will use whatever default is applicable (or usable)
from the data format. All data formats accept this additional file. Only Custom format currently uses the &datacontrol element. And only Custom format input type
uses the Data Elements, Format and Conversion factors from the &wthdata element.
Note that strings in the "def" should be enclosed in single quotes if there is more than one word in the string - if only one word, quotes do not need to be used.
Table 4. Definitions File &location description
&location Field
Description

Field Name

Type

Name of City

City

String

State or Province

StateProv

String

Country Code

Country

String (3 characters)

Latitude (N+/S-)

InLat

Numeric

Longitude (W-/E+)

InLong

Numeric

Time Zone (GMT +/-)

InTime

Numeric

Elevation (meters)

InElev

Numeric

WMO #

InWMO

Numeric or String (6
characters)

2.5.2 Expected Formats for &location

2.5.2.1 Fields: City, StateProv, Country
These fields are string variables. If Country isnot included, an attempt to use the State/Prov entry may be used to determine country. Otherwise, these fields are
not validated and are used to create part of the "location" header record in the EPW file. City can be up to 30 characters in length; StateProv up to 15 characters;
Country up to 10 characters (standard 3 character abbreviation preferred).
2.5.2.2 Fields: InLat, InLong
These fields are decimal equivalent for Latitude and Longitude. The convention is North Latitude is positive; South is negative. Likewise, East Longitude is
positive; West Longitude is negative. That is, if your latitude is N 30 15' (North 30 degrees, 15 minutes) then your input is +30.25.
2.5.2.3 Field: InTime
This field is the decimal equivalent for the Time Zone value. The convention is GMT +/-. That is, if your time zone is "behind" GMT time by 6 hours, your input
would be -6.
2.5.2.4 Field: InElev
This field is the location elevation in meters. Range can be from -300 to 6096. (These are the values from EnergyPlus - there is no validation of these in the
weather converter.)
2.5.2.5 Field: InWMO
This field is the WMO (World Meterological Organization) number for the location. Though not validated per se, if found in the "design conditions" auxiliary files,
the Design Day information can be generated.
Table 5. Definitions File - &miscdata description
&mischata Field Description

Field Name Type

String for Comments 1 header

Comments1 String

String for Comments 2 header

Comments2 String

String for Source Data in Location

header
URL for output

SourceData String
OutputURL String

2.5.3 Expected Formats for &miscdata

2.5.3.1 Fields: Comments1, Comments2
These are strings. After concatenation, they become part of the comment header lines in the EPW headers. Up to 150 characters each is allowed.
2.5.3.2 Field: SourceData
This string is applied to the "Source Data" field in the Location Header. Up to 60 characters is allowed.
2.5.3.3 Field: OutputURL
When a list of files is being processed, one of the outputs that results from the processing is a KML (Keyhole Markup Language) file that can be used with
Google Earth to pinpoint the locations of the weather site. This field can be used to set this URL for later output. The list file format also includes a URL as its
third (optional) parameter. If included, this input would overwrite other URL designations.
Table 6. Definitions file - &wthdata description
&wthdata Field Description

Field Name

Type

Input File Type

InputFileType

String

Number of records per hour

NumInHour

Integer

Data Element Names

DataElements

Strings

Data Units

DataUnits

Strings

Multiplicative Conversion Factors for

Data

DataConversionFactors Numeric

Special Missing Values

DataMissingValues

Numeric

Format for input

InFormat

Format String or
"delimited"

Delimiter Character

DelimiterChar

Decimal Delimiter Character

DecimalSymbolChar

String

Date Separator

DateSeparator

String (single character)

2.5.4 Expected Formats for &wthdata

2.5.4.1 Field: InputFileType
You can always use this field and def file to "override" the default input format type that depends on the extension of your file (see Table 2. Input File Extensions
with implied Data types). A complete set of valid values for Input File types is shown in the following table. Data Files are described more fully in the section
Source Weather Data Formats that occurs later in this document.
Table 7. Input File Type Values
Value

File Type Description

Tmy or ,tm2

TMY2 Data File

Iwec or iwc

IWEC Data File

Samson or dat SAMSON Data File

wyec2 or wy2

WYEC2 Data File

Fmt or txt

DOE-2 FMT File

Clm or esp-r

ESP-r Formatted (CLM) data

file

Blast or asc

BLAST ASCII Data File

Tmy

TMY Data File

Epw

EPW Data File

Csv

EPW - CSV Data File

Wea

Ecotect wea Data File

Swera or swe
Custom or
User

SWERA Data File

Custom Data File

2.5.4.2 Field: NumInHour

This field can be used to specify multi-interval (per hour) files. Without this field, the only formats that can have multiple intervals per hour are the EPW and CSV
file formats - using the header record DataPeriods value for that field.
2.5.4.3 Fields below only used in "Custom" format processing
2.5.4.4 Field: DataElements
For custom files, you will need to indicate which data elements are in which positions of the raw data file. The fields must come from a standardized list of names
see following tables that include internal names (short and long - as shown in Table 8) as well as the EnergyPlus CSV format names (short and long - shown in
Table 9) plus some further elements that can be specified when the standard data elements are not part of the raw data (as shown in Table 10). "Ignore" is used
to skip a raw data field that is not applicable to the weather converter formats. Note that variables listed in the following table (in italics) are allowed for flexibility i.e. wetbulb temperature can be used to determine relative humidity and/or dewpoint temperature. The following three tables illustrate the names for data
elements.
Table 8. Internal Data Element Names (directly applicable to EPW)
Short Name

Default EPW
Units

Long Name

Used by EnergyPlus

year

Year

month

Month

day

Day

hour

minute

datasource

drybulb

dry_bulb_temperature

dewpoint

dew_point_temperature

relhum

relative_humidity

atmos_pressure

atmospheric_pressure

exthorrad

extraterrestrial_horizontal_radiation

Wh/m2

extdirrad

extraterrestrial_direct_normal_radiation

Wh/m2

horirsky

horizontal_infrared_radiation_intensity_from_sky Wh/m2

glohorrad

global_horizontal_radiation

Wh/m2

dirnorrad

direct_normal_radiation

Wh/m2

difhorrad

diffuse_horizontal_radiation

Wh/m2

glohorillum

global_horizontal_illuminance

lux

dirnorillum

direct_normal_illuminance

lux

difhorillum

diffuse_horizontal_illuminance

lux

zenlum

zenith_luminance

lux

winddir

wind_direction

degrees

windspd

wind_speed

m/2

totskycvr

total_sky_cover

tenths

opaqskycvr

opaque_sky_cover

tenths

visibility

ceiling_hgt

ceiling_height

presweathobs

present_weather_observation

presweathcodes

present_weather_codes

precip_wtr

precipitable_water

aerosol_opt_depth aerosol_optical_depth

thousandths

snowdepth

snow_depth

days_last_snow

days_since_last_snow

Albedo

albedo

liq_precip_depth

liquid_precip_depth

liq_precip_rate

liquid_precip_rate

Hour

The following table illustrates that the EnergyPlus CSV header names can be used for data elements in DEF files, if desired.
Table 9. Names from the EnergyPlus CSV files
Short Name

Default EPW
Units

Long Name

Used by EnergyPlus

Date

Date (used to derive Month/Day)

hh:mm

HH:MM (used to derive hour/minute)

datasource

Drybulb

dry bulb temperature

dewpoint

dew point temperature

Relhum

relative humidity

atmos pressure atmospheric pressure

exthorzrad

extraterrestrial horizontal radiation

Wh/m2

extdirrad

extraterrestrial direct normal radiation

Wh/m2

horizontal infrared radiation intensity from

horzirsky

sky

glohorzrad

global horizontal radiation

Wh/m2

dirnorzrad

direct normal radiation

Wh/m2

difhorzrad

diffuse horizontal radiation

Wh/m2

glohorzillum

global horizontal illuminance

lux

dirnorzillum

direct normal illuminance

lux

difhorzillum

diffuse horizontal illuminance

lux

Zenlum

zenith luminance

lux

winddir

wind direction

degrees

windspd

wind speed

m/2

totskycvr

total sky cover

tenths

opaqskycvr

opaque sky cover

tenths

visibility

ceiling hgt

ceiling height

presweathobs

present weather observation

presweathcodes present weather codes

precip wtr

precipitable water

aerosol optical depth

thousandths

snowdepth

snow depth

days last snow

days since last snow

Albedo

albedo

rain

liquid precipitation depth

rain quantity

liquid precipitation rate

Hour

aerosol opt
depth

2.5.5 Custom Files - Auxiliary Data

Often raw data files will not have the preceding elements but similar elements that can be used to derive the values used in the EPW files and in EnergyPlus.
(For example, dew point temperature and relative humidity are needed and can be derived from dry builb temperature and a humidity indicating element such as
wet bulb temperature or humidity ratio). The following table contains the data element names that can be used in the Weather Converter program to derive other
data which will then be placed into the EPW data fields.
Table 10. Auxiliary Data for Custom Files
Short Name

Long Name

Units

Useh by EnergyPlus

wetbulb

wet_bulb_temperature

humratio

humidity_ratio

g/kg

dirhorrad

direct_horizontal_radiation Wh/m2

interval

Interval

unit

hour_yr

hour_of_year

hour

time

Time

hh:mm

hh:mm
Date

HH:MM
Date

hh:mm
mm/dd/yyyy N
N

Explanation of these data elements follows:

2.5.5.1 Wetbulb (Wet Bulb Temperature)
If you have the wet bulb temperature, this data element can be used to derive the dew point temperature and relative humidity.
2.5.5.2 HumRatio (Humidity Ratio)
If you have the humidity ratio, this data element can be used to derive the dew point temperature and relative humidity.
2.5.5.3 Dirhorrad (Direct Horizontal Radiation)
If you have direct horizontal radiation (and at least one other solar element from global horizontal radiation or diffuse horizontal radaition), this data element will
be used to derive the direct normal radiation.
2.5.5.4 Interval
If your "number of records per hour" is >1, then you can designate each interval of that hour with this field.
2.5.5.5 Hour_Of_Year
If you wish, you can just put in the hour of the year for each record. Note that if no date element is entered, then the default is that the data is in hour of the year
(including possible number of records per hour).
2.5.5.6 Time (or HH:MM)
Time can be entered (rather than hour) and the units must be hh:mm; this is then decoded on each record to the appropriate hour.
2.5.5.7 Date
Dates can be entered as month, day, and year. The units field must be entered and should designate the format for the date decoding. Date separator characters
for this field are entered in the DateSeparator item. Default date separator is "/" and that is what is used in the table that shows the allowable units:
Table 11. Allowable hate formats for Custom Data entries.
Units Format
mm/dd/yyyy mm/dd/yy
m/d/y
yyyy/mm/dd yy/mm/dd
y/m/d

Interpretation

Example

Month, day, year 12/13/2009

Year, month, day 2009/12/13

dd/mm/yyyy dd/mm/yy

Day, month,

d/m/y

year

13/12/2009

2.5.5.8 Field: DataUnits

There should be as many DataUnits entries as DataElement entries. These are not generally used but may be used in the future for automatic conversions. The
exception to this is "temperature" fields. Use "f" for Fahrenheit, "k" for Kelvin temperatures. Note that the DataConversionFactor for this field will be applied prior
to conversion. (Many formats use integer numbers to represent values that are in tenths, for example.)
2.5.5.9 Field: DataConversionFactors
There should be as many DataConversionFactors entries as DataElement entries. These factors are multiplicative factors (i.e. the input value is multiplied by this
factor) and can be used to process input data into the values used in the EPW weather files.
2.5.5.10 Field: DataMissingValues
There should be as many entries (though some can be blank) as DataElement entries. The values entered will override the default "missing" values (from the
EPW data dictionary) and, whereas the defaults may be interpreted as a >= missing value (i.e. >= 999), these values will be exact (i.e. = -999.)
2.5.5.11 Field: InFormat
The value in this field should be "delimited" if you are using a free format data file or specify a "Fortran style" format statement.
2.5.5.12 Field: DelimiterChar

If you use a "delimited" format file, you need to specify a delimiter character. Only a single character may be specified.
2.5.5.13 Field: DecimalSymbolChar
A single character can be used to specify the decimal "point" character. Default is the US Standard ".". With use of DelimiterChar and this field, one can
essentially use the fields to specify European Standard Excel export formats.
2.5.5.14 Field: DateSeparator
If you are entering the aforementiond "date" Data Element and your date separator is a character other than slash ("/"), then you need to enter a single character
so the program can interpret your date entries.
Table 12. Definitions file - &datacontrol description
&datacontrol Field Description

Field Name

Type

Records to Skip

NumRecordsToSkip

Integer

Records to Read

MaxNumRecordsToRead

Integer

Missing Data Action

MissingDataAction

Missing Wind Direction Action

MissingWindDirAction

Missing Wind Direction Value

MissingWindDirValue

Real

Missing Opaque Sky Cover Action MissingOpaqueSkyCoverAction

Real (Value 0.0 to 10.0) - tenths of sky

Missing Opaque Sky Cover Value

MissingOpaqueSkyCoverValue

Maximum Wind Speed

MaxWindSpeed

Real

Maximum Direct Solar

MaxDirectSolar

Real

Maximum Diffuse Solar

MaxDiffuseSolar

Real

Maximum Illuminance Value

MaxIlluminanceValue

Real

Generate Solar Radiation

Warnings

GenerateSolarRadiationWarnings

Generate Illuminance Warnings

GenerateIlluminanceWarnings

cover

2.5.6 Expected Formats for &datacontrol

Most of the items in this element are particularly applicable to custom format input files. Currently, they are only used in custom files, but may be more generally
applicable in future releases.
2.5.6.1 Field: NumRecordsToSkip
This is an integer number of records to skip during processing. You might use this if your input file has some information at the top of the file.
2.5.6.2 Field: MaxNumRecordsToRead
This is an integer number of records to read (typically 8760 for a full year). You might use this if your input file has some information after the data records.
2.5.6.3 Fields: MissingDataAction, MissingWindDirAction, MissingOpaqueSkyCoverAction
These fields tell the converter program what to do with "missing" data. Missing data can be found in two forms: totally not included in the DataElements or a
missing value (as defined in the EPW format). Valid values for these fields are:
DEFAULT - use the default processing that the weather converter already uses - starts off with a specific value and updates if data is found.
CONSTANT - use a constant value to replace all missing data
RANDOM - use a random number to generate the missing data
An additional value for MissingOpaqueSkyCoverAction is:
TOTALSKY - use the value for Total Sky Cover
2.5.6.4 Fields: MissingWindDirValue, MissingOpaqueSkyCoverValue
The values specified in this field are used with the action fields previously mentioned.
2.5.6.5 Field: MaxWindSpeed
The default maximum wind speed (40m/s) may not be enough for some locations - this allows the override capability.

2.5.6.6 Field: MaxDirectSolar, MaxDiffuseSolar, MaxIlluminanceValue

Default maximum solar values may not be enough for some locations - this allows the override capability.
2.5.6.7 Field: GenerateSolarRadiationWarnings, GenerateIlluminanceWarnings
If you don't want to see extra warnings when input values are greater than max values (default or as specified in previous fields), use NO as the keyword. Use
YES to make sure you see the warnings. Default is YES.

2.5.7 Def File Examples

In the following examples, every attempt has been made to make sure that these work with the Weather Converter program. However, we cannot foresee all
possible combinations. Caveat emptor - user beware.
Here's an example where the delimiter between fields is a semi-colon (;) and the decimal symbol character is a comma (,) - typical of some non-USA regional
settings:
&location
City=<cityname>
StateProv=<state/province>
Country=<country>
InWMO=<wmo>
InLat=<latitude>
InLong=<longitude>
InElev=<elevation>
InTime=<timezone>
/

&wthdata
NumInHour=1
InputFileType='CUSTOM'
InFormat='DELIMITED'
DataElements=Date,HH:MM,Datasource,Dry Bulb Temperature,Dew Point Temperature,Relative Humidity,Atmospheric Pressure,Extraterr
DataUnits='mm.dd.yyyy','hh:mm','x','x','x','x','C','C','%','Pa','Wh/m2','Wh/m2','Wh/m2','Wh/m2','Wh/m2','Wh/m2','lux','lux','l
DataConversionFactors=1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1
DelimiterChar=';'
DateSeparator='.'
DecimalSymbolChar=','
/
&datacontrol
NumRecordsToSkip=19
MaxNumRecordsToRead=8784
MissingWindDirAction=RANDOM
/
Figure 4. DEF file for with non-standard field delimiter and decimal symbol
Here's an example of a file used to "enhance" a DOE-2 FMT file:
&location
City='Kelburn'
StateProv='Wellington'
Country='NZL'
InWMO=934360
InLat=-42.3333
InLong=174.8
InElev=8
InTime=1
/
&wthdata
NumInHour=1
InputFileType='FMT'
/

&miscdata
Comments1='Standard Data Files for Computer Thermal Simulation of Solar Low Energy Non-residential Buildings; ven der Werff, A
Comments2='Full Actual year of dataSource data is TRY format converted to DOE-2 format;'
/
Figure 5. DEF file for DOE-2 FMT file
Here's an example of a fixed format used for custom file processing. Note that random sky cover is used, to facilitate calculating Horizontal IR from Sky that is
used in EnergyPlus. Also, random wind direction is used because the data set does not contain wind direction.
&location

City='Torino-Caselle'
StateProv=' '
Country='ITA'
InWMO=160590
InLat=45.18333
InLong=7.65
InElev=282
InTime=1
/
&wthdata
NumInHour=1
InputFileType='CUSTOM'
InFormat='(I2, I2, I2, F7.2, F7.2, F5.1, F5.1, F5.1)'
DataElements=Month,Day,Hour,DirNorRad,DifHorRad,DryBulb,Wind\_Speed,Relative\_Humidity
DataUnits=,,,'kJ/M2','kJ/M2','C','m/s','%'
DataConversionFactors=1,1,1,.2777778,.2777778,1,1,1
/
&miscdata
Comments1='Italian Climate Data Set Gianni de Giorgio'
Comments2='Period of record 1951-1970'
SourceData='IGDG Data Set'
/
&datacontrol
MissingOpaqueSkyCoverAction=RANDOM
MissingWindDirAction=RANDOM
/
Figure 6. DEF file for formatted custom file.
An example of a free format custom file. Here, there were several lines of text after the numeric data at the end of the file - thus we used the number of records
to read parameter rather than hand editing each input file.
&location
City='Beijing'
StateProv='Beijing'
Country='CHN'
InWMO='545110'
InLat=39.92
InLong=116.27
InElev=55
InTime=8
/
&miscdata
Comments1='China Data Set - Zhang/Huang'
/

&wthdata
NumInHour=1
InputFileType='CUSTOM'
InFormat='DELIMITED'
DataElements=Ignore,Year,Month,Day,Hour,Ignore,DryBulb,DewPoint,Ignore,Relative\_Humidity,Ignore,DirNorRad,DifHorRad,WindDir,W
DataUnits=x,x,x,x,x,x,'k','k',x,'%',x,'wh/m2','wh/m2','deg','m/s',x,'Pa'
DataConversionFactors=1,1,1,1,1,1,.1,.1,1,1,1,1,1,1,.1,.1,10
DelimiterChar=' '
/
&datacontrol
NumRecordsToSkip=0
MaxNumRecordsToRead=8760
/
Figure 7. DEF File for delimited custom file.
Suppose you have a file that is "almost" TMY2 format. You can easily specify a Def file to treat it as a custom file rather than a TMY2 file (which, by standards, will
have the data filled).
&location
City=<cityname>
StateProv=<state/province>
Country=<country>
InWMO=<wmo>
InLat=<latitude>
InLong=<longitude>
InElev=<elevation>
InTime=<timezone>

&wthdata
NumInHour=1
InputFileType='CUSTOM'
InFormat='(1X,I2,I2,I2,I2,I4,I4,I4,A2,I4,A2,I4,A2,I4,A2,I4,A2,I4,A2,I4,A2,I2,A2,I2,A2,I4,A2,I4,A2,I3,A2,I4,A2,I3,A2,I3,A2,I4,A
DataElements=ignore,year,month,day,hour,ExtHorzRad,ExtDirNormRad,GloHorzRad,ignore,DirNormRad,ignore,DifHorzRad,ignore,GloHorz
DataUnits='x','x','x','x','x','x','Wh/m2','Wh/m2','Wh/m2','x','Wh/m2','x','Wh/m2','x','lux','x','lux','x','lux','x','Cd/m2','x
DataConversionFactors=1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,0.1,1,0.1,1,1,1,100,1,1,1,0.1,1,1,1,1,1,1,1,1,1,1,1,1,
/
&miscdata
Comments1='Custom DEF format for TMY2 formatted files.'
SourceData='TMY2'
/
&datacontrol
NumRecordsToSkip=1
MaxNumRecordsToRead=8784
MissingWindDirAction=RANDOM
MissingDataAction=DEFAULT
MissingOpaqueSkyCoverAction=RANDOM
/
Figure 8. DEF File for almost TMY2 files.
Finally, an example of using an EPW file as a custom file with a DEF format. Note that the specially formatted CSV files from EnergyPlus can be automatically
read in and this format is provided as an extra bonus.
&location
City=<cityname>
StateProv=<state/province>
Country=<country>
InWMO=<wmo>
InLat=<latitude>
InLong=<longitude>
InElev=<elevation>
InTime=<timezone>
/

&wthdata
NumInHour=1
InputFileType='CUSTOM'
InFormat='DELIMITED'
DataElements=year,month,day,hour,minute,datasource,Dry\_Bulb\_Temperature,Dew\_Point\_Temperature,Relative\_Humidity,Atmospher
DataUnits='x','x','x','x','x','x','C','C','%','Pa','Wh/m2','Wh/m2','Wh/m2','Wh/m2','Wh/m2','Wh/m2','lux','lux','lux','Cd/m2','
DataConversionFactors=1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1
DelimiterChar=','
/
&miscdata
Comments1='Standard EPW Custom def format for reading EPW files in EnergyPlus Weather Converter'
SourceData='EPW'
/
&datacontrol
NumRecordsToSkip=8
MaxNumRecordsToRead=8784
MissingWindDirAction=RANDOM
/
Figure 9. DEF File for EPW files.

2.5.8 Custom File Processing

In "normal" file processing, conversion from the input data elements to the EPW data elements is automatic. In "custom" file processing, there is limited flexibility
in this regard. For example, the user may use "wet bulb" temperature in their inputs - this will allow the weather converter to calculate appropriate values for dew
point temperature (if it is missing) and/or relative humidity. Again, limited calculations/derivations are done - should one input wet bulb temperature along with
dew point temperature and relative humidity. Likewise, if only values for global horizontal radiation and diffuse horizontal radiation are given, the program will
calculate a value for direct normal radiation using commonly recognized relationships between these values.

2.5.9 Custom File Processing - Solar Radiation Value Calculation

EnergyPlus only uses the solar radiation data for Direct Normal and Diffuse Horizontal radation in its calculations. But many data sources have only Global
Horizontal (sometimes called Total) or none of the solar radiation elements.
With any two of the solar components, it is reasonable to use the simple relationship of Global, Diffuse and Direct, such as:

Globalhorizontalradiation = Directhorizontalradiation + Diffusehorizontalradiation

(1)

Using known solar position (calculated internally by the Weather converter from latitude, longitude, date and hour), one has:

Directnormalradiation =

Directhorizontalradiation
sin(Solarheight

(2)

Thus, having two of the solar radiation components makes it relatively simple to derive the third.
However, many data sources may not have any solar radiation components. A study was undertaken to find an appropriate solar model to fill in missing solar
data for weather files. The goal was to determine one or more possible solar models to use in the weather conversion/creation process. One model seemed
better overall with the usual given data from the sources than others. The model, termed Zhang-Huang, has been used in a variety of locations and data
creations, including the upcoming IWEC2 data. The model uses a simplistic approach of recent drybulb temperatures, sky cover, global solar constant and solar
position. This model is only used when all solar values are missing from the incoming data. When global radiation is available, then a different model (Perez split)
is used to split the global into direct normal and diffuse horizontal values.
Results, of course, can vary depending on locations.
For example, in Brisbane AUS, comparing the solar creation with the original IWEC data looks very good:

Figure 10. Solar radiation comparison - IWEC vs Weather Solar Model (Brisbane AUS)
Of course, there are other locations that don't compare quite as well:

Figure 11. Comparison of IWEC vs Weather program Solar Model (Singapore)

2.6 Reports/Files Produced by the Weather Converter

Minimally, two outputs are produced for every weather converter run: an audit / log file and a statistical report file. The audit / log file shows details of the
processing (including any errors) as well as the statistical report. The statistical report produced from the weather conversion process is a short, but complete,
picture of the weather data on the file. A single file (.stat extension) is produced of the "statistics" about the data file. A feature of the weather converter is to look
in several design condition files for possible design conditions for the location from the stored design condition files (source: ASHRAE Handbook of
Fundamentals, 2001). If found (WMO (World Meteorological Organization) id is used for matching), these will be shown in the report as well as included in the
output data files (EPW and CSV, as applicable). In addition, the Kppen classification scheme is used to characterize the climate based on the data file's
contents. Other statistics are given as well to help you visualize the data.
In the "reporting" section of the file, each line contains "tab-delimited" elements. This will allow you to easily place the data into a spreadsheet program for further
refinement but the tabs are not as intrusive for "normal viewing" as commas.

2.6.1 Audit / Log File

As an example, the initial portion of an audit file is shown (illustrating the error reporting):
-Input File Type=WY2, with FileName=D:\DevTests\Release\WeatherData\04772.wy2
-Out of Range Data items will NOT be corrected.
Warning ** Dew Point=
5.00°C > Dry Bulb=
4.90°C on date= 5/ 1 at hour= 4
Warning ** Dew Point=
4.80°C > Dry Bulb=
4.40°C on date= 5/ 1 at hour= 5
Warning ** Dew Point=
4.70°C > Dry Bulb=
3.80°C on date= 5/ 1 at hour= 6
Warning ** Suspected missing data line after processing
365 days
Month=
0 Day=
0 Hour=
0
Processing continues but may be in error
Warning ** Suspected Blank line after processing
365 days
** Remaining records, if any, will be ignored
Warning ** Missing Data Found on Source Weather Data File
** Missing (and corrected) Aerosol Optical Depth, Number of items= 8760
Warning ** Out of Range Data Found on Weather Data File
** Out of Range Dew Point Temperatures > Dry Bulb Temperatures, Number of items=
3
- Start Date/End Date for Weather Source
Start Date=Jan 1; End Date=Dec 31
- Actual Data Years for Monthly Data**
Jan
Feb
Mar
Apr
May
Jun
Jul
Aug
1966 1980 1964 1964 1968 1970 1977 1981 1979
- ** Not all weather data sources represent contiguous years.
- ** Monthly data values may come from different years.

Sep
1969

Oct
Nov
1974 1960

Dec

- Data Sources should be checked for relevancy to these statistics.

Average Delta DB Change= 0.76°C ; Std Dev= 0.73°C
Average Delta DP Change= 0.62°C ; Std Dev= 0.69°C
Average Delta Relative Humidity Change= 3.50% ; Std Dev= 3.63%
Average Delta Wind Speed Change= 0.93m/s ; Std Dev= 0.88m/s
Hourly Dry Bulb temperature change trigger = minimum of 11.07°C and 10.°C
11.07°C = calculated trigger based on mean change in dry-bulb temperature and standard deviation shown above
10.°C = trigger set by user
-Output File Type=epw, with FileName=D:\DevTests\Release\WeatherData\Out\CAN\_Ottawa-International\_Airport\_CWEC.epw
-Output File Type=csv, with FileName=D:\DevTests\Release\WeatherData\Out\CAN\_Ottawa-International\_Airport\_CWEC.csv

2.6.2 Statistical Report File

As will be seen in comparison with a "statistical" report shown following, the audit file may contain some details about the data that the statistical report does not
(such as the data years for the weather data). Some basic statistics are shown first:
Statistics for USA_CA_San.Francisco.Intl.AP.724940_TMY3
Location -- San Francisco Intl Ap CA USA
{N 37° 37'} {W 122° 24'} {GMT -8.0 Hours}
Elevation -2m above sea level
Standard Pressure at Elevation -- 101301Pa
Data Source -- TMY3
WMO Station 724940
- Displaying Design Conditions from "Climate Design Data 2009 ASHRAE Handbook"
- ASHRAE design conditions are carefully generated from a period of record
- (typically 30 years) to be representative of that location and to be suitable
- for use in heating/cooling load calculations.
Design Stat
Units {}
Heating

ColdestMonth DB996
{°C}
{°C}
1
3.8
4.9

DB990 DP996 HR_DP996

DB_DP996
{°C}
{}
{°C}
{°C}
-3.7
2.8
10.7
-1.2
3.4
11.2

Design Stat
Units {}
Cooling

HottestMonth DBR
{°C}
{°C}
8
8.5
28.3

DB004 WB_DB004
DB010 WB_DB010
DB020 WB_DB020
WB004 DB_WB004
{°C}
{°C}
{°C}
{°C}
{°C}
{°C}
{°C}
{°C
17.2
25.7
16.7
23.6
16.2
18.6
25.7
17.8
23.9
17
22.4
5.9

Design Stat
Units {m/s}
Extremes

WS010
{m/s}
12.8

WS025
{m/s}
11.5

DP990 HR_DP990
DB_DP990
WS004c
{}
{°C}
{m/s} {°C}
{m/s} {
12.9
12.1
11.6
12.2
2.2
150

WS050 WBmax DBmin_mean

DBmax_mean
DBmin_stddev DBmax_stddev
DBmin05years DBm
{°C}
{°C}
{°C}
{°C}
{°C}
{°C}
{°C}
{°C}
{&de
10.6
22.3
1.8
34.6
1.5
2.3
0.8
36.2
-0.1
37.5
-0.9
38.8
-1.9

- Displaying Monthly Design Conditions "Climate Design Data

- Monthly Optical Sky Depth Beam (taub) and Diffuse (taud)
Jan
Feb
Mar
Apr
taub (beam)
0.316 0.326 0.334 0.362
taud (diffuse)
2.608 2.528 2.525 2.345
taub
taud

2009 ASHRAE Handbook"

May
0.368
2.360

Jun
0.353
2.496

Sep
0.352
2.518

Oct
0.335
2.545

903
118

904
112

901
99

887
90

866
78

846
80

Wetbulb Temperatures°C
Feb
Mar
Apr
May
Jun
21.1 23.3 26.9 28.3 31.5 29.4
13.9 14.4 16.2 17.3 17.7 18.4
17.9 19.8 22.5 23.7 25.6 25.3
12.7 13.4 14.4 15.8 16.7 17.3
16.2 17.6 19.5 21.1 22.3 22.7
12.6 13.0 13.6 15.1 15.8 16.5
15.0 16.2 17.5 19.1 20.6 21.2
12.1 12.5 12.9 14.1 15.1 15.9

Jul
29.2
18.2
25.0
17.5
22.9
16.8
21.5
16.2

Aug
31.1
18.0
27.1
17.1
23.9
16.6
21.8
16.1

Sep
29.5
16.5
25.5
15.6
22.6
15.2
20.5
14.9

Oct
22.7
14.0
20.0
13.5
18.2
13.4
16.8
13.3

Nov
17.5
12.9
16.2
13.0
15.2
12.5
14.2
11.7

= 0.4% Monthly Design Drybulb Temperature

= 0.4% Monthly Mean Coincident Wetbulb Temperature
= 2.0% Monthly Design Drybulb Temperature
= 2.0% Monthly Mean Coincident Wetbulb Temperature
= 5.0% Monthly Design Drybulb Temperature
= 5.0% Monthly Mean Coincident Wetbulb Temperature
= 10.% Monthly Design Drybulb Temperature
= 10.% Monthly Mean Coincident Wetbulb Temperature

Or, if the weather converter must calculate the design stats:

-EnergyPlus Weather Converter V7.1.0.010
Statistics for FaroCST
Location -- Faro - PRT
{N 37° 2'} {E
7° 55'} {GMT +0.0 Hours}
Elevation -100m above sea level
Standard Pressure at Elevation -- 100129Pa
Data Source -- Custom-085790
WMO Station 085790
- Displaying Design Conditions calculated from this weather file.
- The following design temperature statistics are calculated based on THIS weather file ONLY
- and may not be representative of a long-term period of record normally used for
- design temperatures. Also, note that dew point temperatures are listed where
- wet-bulb temperatures are normally presented.
Design Stat
Units
Heating

Coldest Month HDB 99.6%

{}
{C}
3
5.6
6.0

Design Stat
Units
Cooling

Hottest Month CDB .4%

{}
{C}
8
33.3 32.5 31.8

Design Stat
Jan
Units
{m/s}
Max WS 0.0
0.0

Feb
{m/s}
0.0

Nov
Dec
0.320 0.318
2.611 2.538

= Clear Sky Noon Beam Normal Irradiance on 21st Day

= Clear Sky Noon Diffuse Horizontal Irradiance on 21st Day

- Monthly Drybulb and Mean Coincident

Jan
Drybulb 0.4%
17.8
Coincident Wetbulb 0.4%
12.1
Drybulb 2.0%
15.8
Coincident Wetbulb 2.0%
12.1
Drybulb 5.0%
14.6
Coincident Wetbulb 5.0%
11.8
Drybulb 10.%
13.5
Coincident Wetbulb 10.%
11.2
Drybulb 0.4%
Coincident Wetbulb 0.4%
Drybulb 2.0%
Coincident Wetbulb 2.0%
Drybulb 5.0%
Coincident Wetbulb 5.0%
Drybulb 10.%
Coincident Wetbulb 10.%

Aug
0.365
2.435

= Clear Sky Optical Depth for Beam Irradiance

= Clear Sky Optical Depth for Diffuse Irradiance

- Monthly Solar Irradiance Wh/m2 (noon on 21st of month)

ib (beam)
879
910
933
918
912
923
id (diffuse)
79
93
100
124
123
108
ib
id

Jul
0.371
2.395

HDB 99%
{C}
CDB 1% CDB 2% CDP .4%
{C}
{C}
{C}
22.6 22.0 21.7

Mar
Apr
May
Jun
Jul
{m/s} {m/s} {m/s} {m/s} {m/s}
0.0
0.0
0.0
0.0
0.0
0.0

{C}

Aug
{m/s}
0.0

CDP 1% CDP 2%
{C}
Sep
Oct
{m/s} {m/s}
0.0
0.0

Nov
{m/s}

- Heating/Cooling Degree Days/Hours calculated from this weather file are later in this report.
These are followed by groupings of Monthly temperature data.
- Monthly Statistics for Dry Bulb temperatures°C
Jan
Feb
Mar
Apr
May
Jun
Jul
Maximum
16.7 22.2 23.9 28.3 29.4 32.8 26.7 29.4

Aug
30.0

Sep
26.7

Oct
Nov
20.6 16.1

Dec

Dec
{m/s}

Dec

Day:Hour

19:13

14:13

Minimum
Day:Hour

2.2
24:06

5.0
4.4
8.3
8.9
9.4 11.1 11.1 11.1
26:07 23:05 19:05 4:02 22:03 1:04 28:05

Daily Avg

9.6

11.3

12:15

12.7

2:15

13.7

- Maximum Dry Bulb temperature of

- Minimum Dry Bulb temperature of