EnergyPlus
Weather File (EPW) Data Dictionary[LINK]
The “data dictionary” for EnergyPlus Weather Data is shown
below. Note that semi-colons do NOT terminate lines in the
EnergyPlus Weather Data. It helps if you have familiarity with
the IDD conventions please view them in the Input Output
Reference document. Briefly, we have similar “\” conventions
that are important for reading the following tables:
\minimum, \minimum> - values for this field must be
either > = or > than the following number
\maximum, \maximum< - values for this field must be
either < = or < than the following number
\missing - if values in this field are > = the following
number, it is considered “missing” and missing data rules will
apply
\default - blank fields will receive the following as
“default” values
\units - expected units for the field. Standard EnergyPlus
units are shown in the Input Output Reference Document.
Note that in the header records where “date” is used, the
interpretation is shown in the following table.
Weather File Date Field Interpretation
| Field Contents |
Interpretation |
Header Applicability |
| < number > |
Julian Day of Year |
All date fields |
| < number > / < number
> |
Month / Day |
All date fields |
| < number > / < number
> / < number > |
Month / Day / Year |
DataPeriod only - special
multiple year file - ref: RunPeriod:CustomRange object in IDF
/ Input Output Reference document |
| < number > Month |
Day and Month |
All date fields |
| Month < number > |
Day and Month |
All date fields |
| < number > Weekday in
Month |
Numbered weekday of month |
Holiday,
DaylightSavingPeriod |
| Last Weekday In Month |
Last weekday of month |
Holiday,
DaylightSavingPeriod |
In the table, Month can be one of (January, February,
March, April, May, June, July, August, September, October,
November, December). Abbreviations of the first three
characters are also valid.
In the table, Weekday can be one of (Sunday, Monday,
Tuesday, Wednesday, Thursday, Friday, Saturday). Abbreviations
of the first three characters are also valid.
!ESP(r)/EnergyPlus Weather Format
!April 2002
\memo Dates in the EPW file can be several formats:
\memo <number>/<number> (month/day)
\memo <number> Month
\memo Month <number>
\memo <number> (taken to be Julian day of year)
\memo Months are January, February, March, April, May,
\memo June, July, August, September, October, November, December
\memo Months can be the first 3 letters of the month
LOCATION,
A1, \field city
\type alpha
A2, \field State Province Region
\type alpha
A3, \field Country
\type alpha
A4, \field Source
\type alpha
N1, \field WMO
\note usually a 6 digit field. Used as alpha in EnergyPlus
\type alpha
N2 , \field Latitude
\units deg
\minimum -90.0
\maximum +90.0
\default 0.0
\note + is North, - is South, degree minutes represented in decimal (i.e. 30 minutes is .5)
\type real
N3 , \field Longitude
\units deg
\minimum -180.0
\maximum +180.0
\default 0.0
\note - is West, + is East, degree minutes represented in decimal (i.e. 30 minutes is .5)
\type real
N4 , \field TimeZone
\units hr - not on standard units list???
\minimum -12.0
\maximum +12.0
\default 0.0
\note Time relative to GMT.
\type real
N5 ; \field Elevation
\units m
\minimum -1000.0
\maximum< +9999.9
\default 0.0
\type real
The Location header record duplicates the information
required for the Location Object. When only a Run Period
object is used (i.e. a weather file), then the Location Object
Is not needed. When a Run Period and Design Day objects are
entered, then the Location on the weather file (as described
previously) is used and overrides any Location Object
entry.
DESIGN CONDITIONS,
N1, \field Number of Design Conditions
A1, \field Design Condition Source
\note current sources are ASHRAE HOF 2009 US Design Conditions, Canadian Design Conditions
\note and World Design Conditions
A2, \field Design Condition Type (HEATING)
\note fields here will be dependent on the source, they are shown in a header/data format
\note in both the .rpt and .csv files that are produced by the WeatherConverter program
...
An, \field Design Condition Type (COOLING)
\note same as note on Heating Design Conditions
The Design Conditions header record encapsulates matching
(using WMO# – World Meteorological Organization Station
Number) design conditions for a weather file location.
Currently only those design conditions contained in the ASHRAE
Handbook of Fundamentals 2009 are contained in the weather
files. These conditions can be used as desired. In addition,
Design Day definition files have been created of all World,
Canada, and United States Design Conditions. These files are
available in the DataSet folder of the EnergyPlus
installation.
TYPICAL/EXTREME PERIODS,
N1, \field Number of Typical/Extreme Periods
A1, \field Typical/Extreme Period 1 Name
A2, \field Typical/Extreme Period 1 Type
A3, \field Period 1 Start Day
A4, \field Period 1 End Day
\note repeat (A1-A3) until number of typical periods
-- etc to # of periods entered
Using a heuristic method, the weather converter can
determine typical and extreme weather periods for full year
weather files. These will then be shown on the Typical/Extreme
Periods header record. These are also reported in the
statistical report output from the Weather Converter.
GROUND TEMPERATURES,
N1, Number of Ground Temperature Depths
N2, \field Ground Temperature Depth 1
\units m
N3, \field Depth 1 Soil Conductivity
\units W/m-K,
N4, \field Depth 1 Soil Density
\units kg/m3
N5, \field Depth 1 Soil Specific Heat
\units J/kg-K,
N6, \field Depth 1 January Average Ground Temperature
\units C
N7, \field Depth 1 February Average Ground Temperature
\units C
N8, \field Depth 1 March Average Ground Temperature
\units C
N9, \field Depth 1 April Average Ground Temperature
\units C
N10, \field Depth 1 May Average Ground Temperature
\units C
N11, \field Depth 1 June Average Ground Temperature
\units C
N12, \field Depth 1 July Average Ground Temperature
\units C
N13, \field Depth 1 August Average Ground Temperature
\units C
N14, \field Depth 1 September Average Ground Temperature
\units C
N15, \field Depth 1 October Average Ground Temperature
\units C
N16, \field Depth 1 November Average Ground Temperature
\units C
N17, \field Depth 1 December Average Ground Temperature
\units C
\note repeat above (N2-N17) to number of ground temp depths indicated
-- etc to # of depths entered
The weather converter program can use a full year weather
data file to calculate “undisturbed” ground temperatures based
on temperatures. Since an important part of soil heat transfer
includes soil properties such as conductivity, density and
specific heat AND these cannot be calculated from simple
weather observations, this header record is provided
primarilyfor user information. However, with the FC
construction option, these are automatically selected (.5
depth) for use if the user does not include values in the
Site:GroundTemperature:FcfactorMethod object.
As noted in the statistics report, the “undisturbed” ground
temperatures calculated by the weather converter should not be
used in building losses but are appropriate to be used in the
GroundTemperatures:Surface and GroundTemperatures:Deep
objects. The reasoning (for building losses) is that these
values are too extreme for the soil under a conditioned
building. For best results, use the Slab or Basement program
described in this document to calculate custom monthly average
ground temperatures (see the Ground Heat Transfer section).
This is especially important for residential applications and
very small buildings. If one of these ground temperature
preprocessors is not used, for typical commercial buildings in
the USA, a reasonable default value is 2C less than the
average indoor space temperature.
HOLIDAYS/DAYLIGHT SAVING,
A1, \field LeapYear Observed
\type choice
\key Yes
\key No
\note Yes if Leap Year will be observed for this file
\note No if Leap Year days (29 Feb) should be ignored in this file
A2, \field Daylight Saving Start Day
A3, \field Daylight Saving End Day
N1, \field Number of Holidays (essentially unlimited)
A4, \field Holiday 1 Name
A5, \field Holiday 1 Day
\note repeat above two fields until Number of Holidays is reached
-- etc to # of Holidays entered
The Holidays / Daylight Saving header record details the
start and end dates of Daylight Saving Time and other special
days such as might be recorded for the weather file. These can
be used by keying “Yes” for appropriate fields in the Run
Period Object.
Note: EnergyPlus processed weather files available on the
EnergyPlus web site: have neither special days specified nor
daylight saving period.
For example, using a RunPeriod:
RunPeriod,
1, !- Begin Month
1, !- Begin Day Of Month
12, !- End Month
31, !- End Day Of Month
Wednesday, !- Day Of Week For Start Day
Yes, !- Use WeatherFile Holidays/Special Days
No, !- Use WeatherFile DaylightSavingPeriod
Yes, !- Apply Weekend Holiday Rule
Yes, !- Use WeatherFile Rain Indicators
Yes; !- Use WeatherFile Snow Indicators
Will use any holidays specified in the Holidays / Daylight
Saving header record of the weather file but will not use the
Daylight Saving Period that is specified there (if any). In
addition, the user can specify Special Day Periods via the
Special Day Period object and/or Daylight Saving Period via
the Daylight Saving Period object to additionally specify
these items.
COMMENTS 1, A1 \field Comments_1
COMMENTS 2, A1 \field Comments_2
The Comment header records may provide additional
information about the weather data source or other information
which may not fit in other header record formats.
DATA PERIODS,
N1, \field Number of Data Periods
N2, \field Number of Records per hour
A1, \field Data Period 1 Name/Description
A2, \field Data Period 1 Start Day of Week
\type choice
\key Sunday
\key Monday
\key Tuesday
\key Wednesday
\key Thursday
\key Friday
\key Saturday
A3, \field Data Period 1 Start Day
A4, \field Data Period 1 End Day
\note repeat above to number of data periods
-- etc to # of periods entered
A weather file may contain several “data periods” though
this is not required (and, in fact, may be detrimental). In
addition, a weather file may contain multiple records per hour
BUT these must match the Number of Time Steps In Hour for the
simulation. Multiple interval data files can be valued when
you want to be sure of the weather values for each time step
(rather than relying on “interpolated” weather data). A
weather file may also contain several consecutive years of
weather data. EnergyPlus will automatically process the extra
years when the Number of Years field is used in the RunPeriod
object. Sorry - there is no way to jump into a year in the
middle of the EPW file.
Note that a Run Period object may not cross Data Period
boundary lines.
For those interested in creating their own weather data in
the CSV or EPW formats or reading the .csv and .epw files that
are produced by the Weather Converter program, the fields are
shown in the following “IDD” description. Items shown in bold
are used directly in the EnergyPlus program.
! Actual data does not have a descriptor
N1, \field Year
N2, \field Month
N3, \field Day
N4, \field Hour
N5, \field Minute
A1, \field Data Source and Uncertainty Flags
\note Initial day of weather file is checked by EnergyPlus for validity (as shown below)
\note Each field is checked for "missing" as shown below. Reasonable values, calculated
\note values or the last "good" value is substituted.
N6, \field Dry Bulb Temperature
\units C
\minimum> -70
\maximum< 70
\missing 99.9
N7, \field Dew Point Temperature
\units C
\minimum> -70
\maximum< 70
\missing 99.9
N8, \field Relative Humidity
\missing 999.
\minimum 0
\maximum 110
N9, \field Atmospheric Station Pressure
\units Pa
\missing 999999.
\minimum> 31000
\maximum< 120000
N10, \field Extraterrestrial Horizontal Radiation
\units Wh/m2
\missing 9999.
\minimum 0
N11, \field Extraterrestrial Direct Normal Radiation
\units Wh/m2
\missing 9999.
\minimum 0
N12, \field Horizontal Infrared Radiation Intensity
\units Wh/m2
\missing 9999.
\minimum 0
N13, \field Global Horizontal Radiation
\units Wh/m2
\missing 9999.
\minimum 0
N14, \field Direct Normal Radiation
\units Wh/m2
\missing 9999.
\minimum 0
N15, \field Diffuse Horizontal Radiation
\units Wh/m2
\missing 9999.
\minimum 0
N16, \field Global Horizontal Illuminance
\units lux
\missing 999999.
\note will be missing if > = 999900
\minimum 0
N17, \field Direct Normal Illuminance
\units lux
\missing 999999.
\note will be missing if > = 999900
\minimum 0
N18, \field Diffuse Horizontal Illuminance
\units lux
\missing 999999.
\note will be missing if > = 999900
\minimum 0
N19, \field Zenith Luminance
\units Cd/m2
\missing 9999.
\note will be missing if > = 9999
\minimum 0
N20, \field Wind Direction
\units degrees
\missing 999.
\minimum 0
\maximum 360
N21, \field Wind Speed
\units m/s
\missing 999.
\minimum 0
\maximum 40
N22, \field Total Sky Cover
\missing 99
\minimum 0
\maximum 10
N23, \field Opaque Sky Cover (used if Horizontal IR Intensity missing)
\missing 99
\minimum 0
\maximum 10
N24, \field Visibility
\units km
\missing 9999
N25, \field Ceiling Height
\units m
\missing 99999
N26, \field Present Weather Observation
N27, \field Present Weather Codes
N28, \field Precipitable Water
\units mm
\missing 999
N29, \field Aerosol Optical Depth
\units thousandths
\missing .999
N30, \field Snow Depth
\units cm
\missing 999
N31, \field Days Since Last Snowfall
\missing 99
N32, \field Albedo
\missing 999
N33, \field Liquid Precipitation Depth
\units mm
\missing 999
N34; \field Liquid Precipitation Quantity
\units hr
\missing 99
Data Field Descriptions[LINK]
Descriptions of the fields are taken from the IWEC manual -
as descriptive of what should be contained in the data
fields.
This is the Year of the data. Not really used in
EnergyPlus. Used in the Weather Converter program for display
in audit file.
This is the month (1-12) for the data. Cannot be
missing.
This is the day (dependent on month) for the data. Cannot
be missing.
This is the hour of the data. (1 - 24). Hour 1 is 00:01 to
01:00. Cannot be missing.
Field: Minute[LINK]
This is the minute field. (1..60)
Field: Data
Source and Uncertainty Flags[LINK]
The data source and uncertainty flags from various formats
(usually shown with each field) are consolidated in the E/E+
EPW format. More is shown about Data Source and Uncertainty in
Data Sources/Uncertainty section later in this document.
Field: Dry Bulb
Temperature[LINK]
This is the dry bulb temperature in C at the time
indicated. Note that this is a full numeric field (i.e. 23.6)
and not an integer representation with tenths. Valid values
range from -70°C to 70°C. Missing value for this field is
99.9.
Field: Dew Point
Temperature[LINK]
This is the dew point temperature in C at the time
indicated. Note that this is a full numeric field (i.e. 23.6)
and not an integer representation with tenths. Valid values
range from -70°C to 70°C. Missing value for this field is
99.9.
Field: Relative Humidity[LINK]
This is the Relative Humidity in percent at the time
indicated. Valid values range from 0% to 110%. Missing value
for this field is 999.
Field: Atmospheric
Station Pressure[LINK]
This is the station pressure in Pa at the time indicated.
Valid values range from 31,000 to 120,000. (These values were
chosen from the standard barometric pressure for all
elevations of the World). Missing value for this field is
999999.
This is the Extraterrestrial Horizontal Radiation in Wh/m2.
It is not currently used in EnergyPlus calculations. It should
have a minimum value of 0; missing value for this field is
9999.
This is the Extraterrestrial Direct Normal Radiation in
Wh/m2. (Amount of solar radiation in Wh/m2 received on a
surface normal to the rays of the sun at the top of the
atmosphere during the number of minutes preceding the time
indicated). It is not currently used in EnergyPlus
calculations. It should have a minimum value of 0; missing
value for this field is 9999.
Field:
Horizontal Infrared Radiation Intensity[LINK]
This is the Horizontal Infrared Radiation Intensity in
Wh/m2. If it is missing, it is calculated from the Opaque Sky
Cover field as shown in the following explanation. It should
have a minimum value of 0; missing value for this field is
9999.
\[Horizontal_{IR} =
\epsilon\sigma T^4_{drybulb}\]
where
\(Horizontal_{IR}\) is
the horizontal IR intensity {W/m\(^{2}\)}
\(\epsilon\) is the
sky emissivity
\(\sigma\) is the
Stefan-Boltzmann constant = 5.6697e-8 W/m\(^{2}\)-K\(^{4}\)
\(T_{drybulb}\) is the
drybulb temperature {K}
The sky emissivity is given by
\[\epsilon = \left( 0.787 +0.764
\ln\left(\frac{T_{dewpoint}}{273}\right)\right)\left( 1 +
0.0224N + 0.0035N^2 + 0.00028N^3 \right)\]
where
Example: Clear sky (\(N =
0\) ), \(T_{drybulb} = 273+20
= 293 K\) , \(T_{dewpoint} =
273+10 = 283 K\) :
\(\epsilon = 0.787 + 0.764*0.036
= 0.815\)
\(Horizontal_{IR} =
0.815*5.6697e-8*(293^4) = 340.6 W/m^2\)
References (Walton, 1983) (Clark, Allen, 1978) for these
calculations are contained in the references section at the
end of this list of fields.
Field: Global
Horizontal Radiation[LINK]
This is the Global Horizontal Radiation in Wh/m2. (Total
amount of direct and diffuse solar radiation in Wh/m2 received
on a horizontal surface during the number of minutes preceding
the time indicated.) It is not currently used in EnergyPlus
calculations. It should have a minimum value of 0; missing
value for this field is 9999.
Field: Direct Normal
Radiation[LINK]
This is the Direct Normal Radiation in Wh/m2. (Amount of
solar radiation in Wh/m2 received directly from the solar disk
on a surface perpendicular to the sun’s rays, during the
number of minutes preceding the time indicated.) If the field
is missing (\(\ge 9999\) ) or
invalid (\(<0\) ), it is
set to 0. Counts of such missing values are totaled and
presented at the end of the runperiod.
Field: Diffuse
Horizontal Radiation[LINK]
This is the Diffuse Horizontal Radiation in Wh/m2. (Amount
of solar radiation in Wh/m2 received from the sky (excluding
the solar disk) on a horizontal surface during the number of
minutes preceding the time indicated.) If the field is missing
(\(\ge 9999\) ) or invalid
(\(<0\) ), it is set to 0.
Counts of such missing values are totaled and presented at the
end of the runperiod.
Field: Global
Horizontal Illuminance[LINK]
This is the Global Horizontal Illuminance in lux. (Average
total amount of direct and diffuse illuminance in hundreds of
lux received on a horizontal surface during the number of
minutes preceding the time indicated.) It is not currently
used in EnergyPlus calculations. It should have a minimum
value of 0; missing value for this field is 999999 and will be
considered missing if greater than or equal to 999900.
Field: Direct Normal
Illuminance[LINK]
This is the Direct Normal Illuminance in lux. (Average
amount of illuminance in hundreds of lux received directly
from the solar disk on a surface perpendicular to the sun’s
rays, during the number of minutes preceding the time
indicated.) It is not currently used in EnergyPlus
calculations. It should have a minimum value of 0; missing
value for this field is 999999 and will be considered missing
if greater than or equal to 999900.
Field: Diffuse
Horizontal Illuminance[LINK]
This is the Diffuse Horizontal Illuminance in lux. (Average
amount of illuminance in hundreds of lux received from the sky
(excluding the solar disk) on a horizontal surface during the
number of minutes preceding the time indicated.) It is not
currently used in EnergyPlus calculations. It should have a
minimum value of 0; missing value for this field is 999999 and
will be considered missing if greater than or equal to
999900.
Field: Zenith Luminance[LINK]
This is the Zenith Illuminance in Cd/m2. (Average amount of
luminance at the sky’s zenith in tens of Cd/m2 during the
number of minutes preceding the time indicated.) It is not
currently used in EnergyPlus calculations. It should have a
minimum value of 0; missing value for this field is 9999.
Field: Wind Direction[LINK]
This is the Wind Direction in degrees where the convention
is that North = 0.0, East = 90.0, South = 180.0, West = 270.0.
(Wind direction in degrees at the time indicated. If calm,
direction equals zero.) Values can range from 0 to 360.
Missing value is 999.
Field: Wind Speed[LINK]
This is the wind speed in m/sec. (Wind speed at time
indicated.) Values can range from 0 to 40. Missing value is
999.
Field: Total Sky Cover[LINK]
This is the value for total sky cover (tenths of coverage).
(i.e. 1 is 1/10 covered. 10 is total coverage). (Amount of sky
dome in tenths covered by clouds or obscuring phenomena at the
hour indicated at the time indicated.) Minimum value is 0;
maximum value is 10; missing value is 99.
Field: Opaque Sky Cover[LINK]
This is the value for opaque sky cover (tenths of
coverage). (i.e. 1 is 1/10 covered. 10 is total coverage).
(Amount of sky dome in tenths covered by clouds or obscuring
phenomena that prevent observing the sky or higher cloud
layers at the time indicated.) This is not used unless the
field for Horizontal Infrared Radiation Intensity is missing
and then it is used to calculate Horizontal Infrared Radiation
Intensity. Minimum value is 0; maximum value is 10; missing
value is 99.
Field: Visibility[LINK]
This is the value for visibility in km. (Horizontal
visibility at the time indicated.) It is not currently used in
EnergyPlus calculations. Missing value is 9999.
Field: Ceiling Height[LINK]
This is the value for ceiling height in m. (77777 is
unlimited ceiling height. 88888 is cirroform ceiling.) It is
not currently used in EnergyPlus calculations. Missing value
is 99999.
Field: Present
Weather Observation[LINK]
If the value of the field is 0, then the observed weather
codes are taken from the following field. If the value of the
field is 9, then “missing” weather is assumed. Since the
primary use of these fields (Present Weather Observation and
Present Weather Codes) is for rain/wet surfaces, a missing
observation field or a missing weather code implies no
rain.
Present Weather Observation Values
| Element |
Values |
Definition |
| Observation Indicator |
0 or 9 |
0 = Weather observation made; 9
= Weather observation not made, or missing |
Field: Present Weather
Codes[LINK]
The present weather codes field is assumed to follow the
TMY2 conventions for this field. Note that though this field
may be represented as numeric (e.g. in the CSV format), it is
really a text field of 9 single digits. This convention along
with values for each “column” (left to right) is presented in
Table.
Note that some formats (e.g. TMY) does not follow this
convention - as much as possible, the present weather codes
are converted to this convention during WeatherConverter
processing. Also note that the most important fields are those
representing liquid precipitation - where the surfaces of the
building would be wet. EnergyPlus uses “Snow Depth” to
determine if snow is on the ground.
Weather Codes Field Interpretation
| Column - Poisition in Field |
Element Description |
Possible Values |
Definition |
| 1 |
Occurrence
ofThunderstorm,Tornado, orSquall |
0 - 2, 4, 6- 9 |
0 = Thunderstorm-lightning and
thunder. Wind gusts less than 25.7 m/s, and hail, if any, less
than 1.9 cm diameter 1 = Heavy or severe thunderstorm-frequent
intense lightning and thunder. Wind gusts greater than 25.7
m/s and hail, if any, 1.9 cm or greater diameter 2 = Report of
tornado or waterspout 4 = Moderate squall-sudden increase of
windspeed by at least 8.2 m/s, reaching 11.3 m/s or more and
lasting for at least 1 minute 6 = Water spout (beginning
January 1984) 7 = Funnel cloud (beginning January 1984) 8 =
Tornado (beginning January 1984) 9 = None if Observation
Indicator element equals 0, or else unknown or missing if
Observation Indicator element equals 9 |
| 2 |
Occurrence ofRain, RainShowers,
orFreezing Rain |
0 - 9 |
0 = Light rain 1 = Moderate rain
2 = Heavy rain 3 = Light rain showers 4 = Moderate rain
showers 5 = Heavy rain showers 6 = Light freezing rain 7 =
Moderate freezing rain 8 = Heavy freezing rain 9 = None if
Observation Indicator element equals 0, or else unknown or
missing if Observation Indicator element equals 9 Notes: Light
= up to 0.25 cm per hour Moderate = 0.28to 0.76 cm per hour
Heavy = greater than 0.76cm per hour |
| 3 |
Occurrence ofRain
Squalls,Drizzle, orFreezing Drizzle |
0, 1, 3-9 |
0 = Light rain squalls 1 =
Moderate rain squalls 3 = Light drizzle 4 = Moderate drizzle 5
= Heavy drizzle 6 = Light freezing drizzle 7 = Moderate
freezing drizzle 8 = Heavy freezing drizzle 9 = None if
Observation Indicator element equals 0, or else unknown or
missing if Observation Indicator element equals 9 Notes: When
drizzle or freezing drizzle occurswith other weather
phenomena: Light = up to0.025 cm per hour Moderate = 0.025 to
0.051cm per hour Heavy = greater than 0.051 cmper hour When
drizzle or freezing drizzle occurs alone: Light = visibility 1
km or greater Moderate = visibility between 0.5 and 1 km Heavy
= visibility 0.5 km or less |
| 4 |
Occurrence ofSnow, SnowPellets,
or IceCrystals |
0 - 9 |
0 = Light snow 1 = Moderate snow
2 = Heavy snow 3 = Light snow pellets 4 = Moderate snow
pellets 5 = Heavy snow pellets 6 = Light ice crystals 7 =
Moderate ice crystals 8 = Heavy ice crystals 9 = None if
Observation Indicator element equals 0, or else unknown or
missing if Observation Indicator element equals 9
Notes:Beginning in April 1963, any occurrence of icecrystals
is recorded as a 7. |
| 5 |
Occurrence ofSnow Showers,Snow
Squalls, orSnow Grains |
0 - 7, 9 |
0 = Light snow 1 = Moderate snow
showers 2 = Heavy snow showers 3 = Light snow squall 4 =
Moderate snow squall 5 = Heavy snow squall 6 = Light snow
grains 7 = Moderate snow grains 9 = None if Observation
Indicator element equals 0, or else unknown or missing if
Observation Indicator element equals 9 |
| 6 |
Occurrence ofSleet,
SleetShowers, or Hail |
0 - 2, 4, 9 |
0 = Light ice pellet showers 1 =
Moderate ice pellet showers 2 = Heavy ice pellet showers 4 =
Hail 9 = None if Observation Indicator element equals 0, or
else unknown or missing if Observation Indicator element
equals 9 Notes: Prior to April 1970, ice pellets werecoded as
sleet. Beginning in April 1970, sleetand small hail were
redefined as ice pellets andare coded as 0, 1, or 2. |
| 7 |
Occurrence ofFog, BlowingDust,
or Blowing Sand |
0 - 9 |
0 = Fog 1 = Ice fog 2 = Ground
fog 3 = Blowing dust 4 = Blowing sand 5 = Heavy fog 6 = Glaze
(beginning 1984) 7 = Heavy ice fog (beginning 1984) 8 = Heavy
ground fog (beginning 1984) 9 = None if Observation Indicator
element equals 0, or else unknown or missing if Observation
Indicator element equals 9 Notes:These values recorded only
when visibility isless than 11 km. |
| 8 |
Occurrence ofSmoke, Haze,Smoke
andHaze, BlowingSnow, BlowingSpray, or Dust |
0 - 7, 9 |
0 = Smoke 1 = Haze 2 = Smoke and
haze 3 = Dust 4 = Blowing snow 5 = Blowing spray 6 = Dust
storm (beginning 1984) 7 = Volcanic ash 9 = None if
Observation Indicator element equals 0, or else unknown or
missing if Observation Indicator element equals 9 Notes: These
values recorded only when visibility is less than 11 km. |
| 9 |
Occurrence ofIce Pellets |
0 - 2, 9 |
0 = Light ice pellets 1 =
Moderate ice pellets 2 = Heavy ice pellets 9 = None if
Observation Indicator element equals 0, or else unknown or
missing if Observation Indicator element equals 9 |
For example, a Present Weather Observation (previous field)
of 0 and a Present Weather Codes field of 929999999 notes that
there is heavy rain for this data period (usually hourly but
depends on the number of intervals per hour field in the “Data
Periods” record).
Field: Precipitable
Water[LINK]
This is the value for Precipitable Water in mm. (This is
not rain - rain is inferred from the PresWeathObs field but a
better result is from the Liquid Precipitation Depth field)).
It is not currently used in EnergyPlus calculations (primarily
due to the unreliability of the reporting of this value).
Missing value is 999.
Field: Aerosol Optical
Depth[LINK]
This is the value for Aerosol Optical Depth in thousandths.
It is not currently used in EnergyPlus calculations. Missing
value is .999.
Field: Snow Depth[LINK]
This is the value for Snow Depth in cm. This field is used
to tell when snow is on the ground and, thus, the ground
reflectance may change. Missing value is 999.
Field: Days Since Last
Snowfall[LINK]
This is the value for Days Since Last Snowfall. It is not
currently used in EnergyPlus calculations. Missing value is
99.
Field: Albedo[LINK]
The ratio (unitless) of reflected solar irradiance to
global horizontal irradiance. It is not currently used in
EnergyPlus.
Field: Liquid
Precipitation Depth[LINK]
The amount of liquid precipitation (mm) observed at the
indicated time for the period indicated in the liquid
precipitation quantity field. If this value is not missing,
then it is used and overrides the “precipitation” flag as
rainfall. Conversely, if the precipitation flag shows rain and
this field is missing or zero, it is set to 1.5 (mm).
Field: Liquid
Precipitation Quantity[LINK]
The period of accumulation (hr) for the liquid
precipitation depth field. It is not currently used in
EnergyPlus.
Walton, G. N. 1983. Thermal Analysis Research Program
Reference Manual. NBSSIR 83-2655. National Bureau of
Standards, p. 21.
Clark, G. and C. Allen, “The Estimation of Atmospheric
Radiation for Clear and Cloudy Skies,” Proceedings 2nd
National Passive Solar Conference (AS/ISES), 1978,
pp. 675-678.
EnergyPlus Weather File (EPW) Data Dictionary[LINK]
The “data dictionary” for EnergyPlus Weather Data is shown below. Note that semi-colons do NOT terminate lines in the EnergyPlus Weather Data. It helps if you have familiarity with the IDD conventions please view them in the Input Output Reference document. Briefly, we have similar “\” conventions that are important for reading the following tables:
\minimum, \minimum> - values for this field must be either > = or > than the following number
\maximum, \maximum< - values for this field must be either < = or < than the following number
\missing - if values in this field are > = the following number, it is considered “missing” and missing data rules will apply
\default - blank fields will receive the following as “default” values
\units - expected units for the field. Standard EnergyPlus units are shown in the Input Output Reference Document.
Note that in the header records where “date” is used, the interpretation is shown in the following table.
In the table, Month can be one of (January, February, March, April, May, June, July, August, September, October, November, December). Abbreviations of the first three characters are also valid.
In the table, Weekday can be one of (Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday). Abbreviations of the first three characters are also valid.
The Location header record duplicates the information required for the Location Object. When only a Run Period object is used (i.e. a weather file), then the Location Object Is not needed. When a Run Period and Design Day objects are entered, then the Location on the weather file (as described previously) is used and overrides any Location Object entry.
The Design Conditions header record encapsulates matching (using WMO# – World Meteorological Organization Station Number) design conditions for a weather file location. Currently only those design conditions contained in the ASHRAE Handbook of Fundamentals 2009 are contained in the weather files. These conditions can be used as desired. In addition, Design Day definition files have been created of all World, Canada, and United States Design Conditions. These files are available in the DataSet folder of the EnergyPlus installation.
Using a heuristic method, the weather converter can determine typical and extreme weather periods for full year weather files. These will then be shown on the Typical/Extreme Periods header record. These are also reported in the statistical report output from the Weather Converter.
The weather converter program can use a full year weather data file to calculate “undisturbed” ground temperatures based on temperatures. Since an important part of soil heat transfer includes soil properties such as conductivity, density and specific heat AND these cannot be calculated from simple weather observations, this header record is provided primarilyfor user information. However, with the FC construction option, these are automatically selected (.5 depth) for use if the user does not include values in the Site:GroundTemperature:FcfactorMethod object.
As noted in the statistics report, the “undisturbed” ground temperatures calculated by the weather converter should not be used in building losses but are appropriate to be used in the GroundTemperatures:Surface and GroundTemperatures:Deep objects. The reasoning (for building losses) is that these values are too extreme for the soil under a conditioned building. For best results, use the Slab or Basement program described in this document to calculate custom monthly average ground temperatures (see the Ground Heat Transfer section). This is especially important for residential applications and very small buildings. If one of these ground temperature preprocessors is not used, for typical commercial buildings in the USA, a reasonable default value is 2C less than the average indoor space temperature.
The Holidays / Daylight Saving header record details the start and end dates of Daylight Saving Time and other special days such as might be recorded for the weather file. These can be used by keying “Yes” for appropriate fields in the Run Period Object.
Note: EnergyPlus processed weather files available on the EnergyPlus web site: have neither special days specified nor daylight saving period.
For example, using a RunPeriod:
Will use any holidays specified in the Holidays / Daylight Saving header record of the weather file but will not use the Daylight Saving Period that is specified there (if any). In addition, the user can specify Special Day Periods via the Special Day Period object and/or Daylight Saving Period via the Daylight Saving Period object to additionally specify these items.
The Comment header records may provide additional information about the weather data source or other information which may not fit in other header record formats.
A weather file may contain several “data periods” though this is not required (and, in fact, may be detrimental). In addition, a weather file may contain multiple records per hour BUT these must match the Number of Time Steps In Hour for the simulation. Multiple interval data files can be valued when you want to be sure of the weather values for each time step (rather than relying on “interpolated” weather data). A weather file may also contain several consecutive years of weather data. EnergyPlus will automatically process the extra years when the Number of Years field is used in the RunPeriod object. Sorry - there is no way to jump into a year in the middle of the EPW file.
Note that a Run Period object may not cross Data Period boundary lines.
For those interested in creating their own weather data in the CSV or EPW formats or reading the .csv and .epw files that are produced by the Weather Converter program, the fields are shown in the following “IDD” description. Items shown in bold are used directly in the EnergyPlus program.
Data Field Descriptions[LINK]
Descriptions of the fields are taken from the IWEC manual - as descriptive of what should be contained in the data fields.
Field: Year[LINK]
This is the Year of the data. Not really used in EnergyPlus. Used in the Weather Converter program for display in audit file.
Field: Month[LINK]
This is the month (1-12) for the data. Cannot be missing.
Field: Day[LINK]
This is the day (dependent on month) for the data. Cannot be missing.
Field: Hour[LINK]
This is the hour of the data. (1 - 24). Hour 1 is 00:01 to 01:00. Cannot be missing.
Field: Minute[LINK]
This is the minute field. (1..60)
Field: Data Source and Uncertainty Flags[LINK]
The data source and uncertainty flags from various formats (usually shown with each field) are consolidated in the E/E+ EPW format. More is shown about Data Source and Uncertainty in Data Sources/Uncertainty section later in this document.
Field: Dry Bulb Temperature[LINK]
This is the dry bulb temperature in C at the time indicated. Note that this is a full numeric field (i.e. 23.6) and not an integer representation with tenths. Valid values range from -70°C to 70°C. Missing value for this field is 99.9.
Field: Dew Point Temperature[LINK]
This is the dew point temperature in C at the time indicated. Note that this is a full numeric field (i.e. 23.6) and not an integer representation with tenths. Valid values range from -70°C to 70°C. Missing value for this field is 99.9.
Field: Relative Humidity[LINK]
This is the Relative Humidity in percent at the time indicated. Valid values range from 0% to 110%. Missing value for this field is 999.
Field: Atmospheric Station Pressure[LINK]
This is the station pressure in Pa at the time indicated. Valid values range from 31,000 to 120,000. (These values were chosen from the standard barometric pressure for all elevations of the World). Missing value for this field is 999999.
Field: Extraterrestrial Horizontal Radiation[LINK]
This is the Extraterrestrial Horizontal Radiation in Wh/m2. It is not currently used in EnergyPlus calculations. It should have a minimum value of 0; missing value for this field is 9999.
Field: Extraterrestrial Direct Normal Radiation[LINK]
This is the Extraterrestrial Direct Normal Radiation in Wh/m2. (Amount of solar radiation in Wh/m2 received on a surface normal to the rays of the sun at the top of the atmosphere during the number of minutes preceding the time indicated). It is not currently used in EnergyPlus calculations. It should have a minimum value of 0; missing value for this field is 9999.
Field: Horizontal Infrared Radiation Intensity[LINK]
This is the Horizontal Infrared Radiation Intensity in Wh/m2. If it is missing, it is calculated from the Opaque Sky Cover field as shown in the following explanation. It should have a minimum value of 0; missing value for this field is 9999.
\[Horizontal_{IR} = \epsilon\sigma T^4_{drybulb}\]
where
\(Horizontal_{IR}\) is the horizontal IR intensity {W/m\(^{2}\)}
\(\epsilon\) is the sky emissivity
\(\sigma\) is the Stefan-Boltzmann constant = 5.6697e-8 W/m\(^{2}\)-K\(^{4}\)
\(T_{drybulb}\) is the drybulb temperature {K}
The sky emissivity is given by
\[\epsilon = \left( 0.787 +0.764 \ln\left(\frac{T_{dewpoint}}{273}\right)\right)\left( 1 + 0.0224N + 0.0035N^2 + 0.00028N^3 \right)\]
where
\(T_{dewpoint}\) is the dewpoint temperature {K}
\(N\) is the opaque sky cover {tenths}
Example: Clear sky (\(N = 0\) ), \(T_{drybulb} = 273+20 = 293 K\) , \(T_{dewpoint} = 273+10 = 283 K\) :
\(\epsilon = 0.787 + 0.764*0.036 = 0.815\)
\(Horizontal_{IR} = 0.815*5.6697e-8*(293^4) = 340.6 W/m^2\)
References (Walton, 1983) (Clark, Allen, 1978) for these calculations are contained in the references section at the end of this list of fields.
Field: Global Horizontal Radiation[LINK]
This is the Global Horizontal Radiation in Wh/m2. (Total amount of direct and diffuse solar radiation in Wh/m2 received on a horizontal surface during the number of minutes preceding the time indicated.) It is not currently used in EnergyPlus calculations. It should have a minimum value of 0; missing value for this field is 9999.
Field: Direct Normal Radiation[LINK]
This is the Direct Normal Radiation in Wh/m2. (Amount of solar radiation in Wh/m2 received directly from the solar disk on a surface perpendicular to the sun’s rays, during the number of minutes preceding the time indicated.) If the field is missing (\(\ge 9999\) ) or invalid (\(<0\) ), it is set to 0. Counts of such missing values are totaled and presented at the end of the runperiod.
Field: Diffuse Horizontal Radiation[LINK]
This is the Diffuse Horizontal Radiation in Wh/m2. (Amount of solar radiation in Wh/m2 received from the sky (excluding the solar disk) on a horizontal surface during the number of minutes preceding the time indicated.) If the field is missing (\(\ge 9999\) ) or invalid (\(<0\) ), it is set to 0. Counts of such missing values are totaled and presented at the end of the runperiod.
Field: Global Horizontal Illuminance[LINK]
This is the Global Horizontal Illuminance in lux. (Average total amount of direct and diffuse illuminance in hundreds of lux received on a horizontal surface during the number of minutes preceding the time indicated.) It is not currently used in EnergyPlus calculations. It should have a minimum value of 0; missing value for this field is 999999 and will be considered missing if greater than or equal to 999900.
Field: Direct Normal Illuminance[LINK]
This is the Direct Normal Illuminance in lux. (Average amount of illuminance in hundreds of lux received directly from the solar disk on a surface perpendicular to the sun’s rays, during the number of minutes preceding the time indicated.) It is not currently used in EnergyPlus calculations. It should have a minimum value of 0; missing value for this field is 999999 and will be considered missing if greater than or equal to 999900.
Field: Diffuse Horizontal Illuminance[LINK]
This is the Diffuse Horizontal Illuminance in lux. (Average amount of illuminance in hundreds of lux received from the sky (excluding the solar disk) on a horizontal surface during the number of minutes preceding the time indicated.) It is not currently used in EnergyPlus calculations. It should have a minimum value of 0; missing value for this field is 999999 and will be considered missing if greater than or equal to 999900.
Field: Zenith Luminance[LINK]
This is the Zenith Illuminance in Cd/m2. (Average amount of luminance at the sky’s zenith in tens of Cd/m2 during the number of minutes preceding the time indicated.) It is not currently used in EnergyPlus calculations. It should have a minimum value of 0; missing value for this field is 9999.
Field: Wind Direction[LINK]
This is the Wind Direction in degrees where the convention is that North = 0.0, East = 90.0, South = 180.0, West = 270.0. (Wind direction in degrees at the time indicated. If calm, direction equals zero.) Values can range from 0 to 360. Missing value is 999.
Field: Wind Speed[LINK]
This is the wind speed in m/sec. (Wind speed at time indicated.) Values can range from 0 to 40. Missing value is 999.
Field: Total Sky Cover[LINK]
This is the value for total sky cover (tenths of coverage). (i.e. 1 is 1/10 covered. 10 is total coverage). (Amount of sky dome in tenths covered by clouds or obscuring phenomena at the hour indicated at the time indicated.) Minimum value is 0; maximum value is 10; missing value is 99.
Field: Opaque Sky Cover[LINK]
This is the value for opaque sky cover (tenths of coverage). (i.e. 1 is 1/10 covered. 10 is total coverage). (Amount of sky dome in tenths covered by clouds or obscuring phenomena that prevent observing the sky or higher cloud layers at the time indicated.) This is not used unless the field for Horizontal Infrared Radiation Intensity is missing and then it is used to calculate Horizontal Infrared Radiation Intensity. Minimum value is 0; maximum value is 10; missing value is 99.
Field: Visibility[LINK]
This is the value for visibility in km. (Horizontal visibility at the time indicated.) It is not currently used in EnergyPlus calculations. Missing value is 9999.
Field: Ceiling Height[LINK]
This is the value for ceiling height in m. (77777 is unlimited ceiling height. 88888 is cirroform ceiling.) It is not currently used in EnergyPlus calculations. Missing value is 99999.
Field: Present Weather Observation[LINK]
If the value of the field is 0, then the observed weather codes are taken from the following field. If the value of the field is 9, then “missing” weather is assumed. Since the primary use of these fields (Present Weather Observation and Present Weather Codes) is for rain/wet surfaces, a missing observation field or a missing weather code implies no rain.
Field: Present Weather Codes[LINK]
The present weather codes field is assumed to follow the TMY2 conventions for this field. Note that though this field may be represented as numeric (e.g. in the CSV format), it is really a text field of 9 single digits. This convention along with values for each “column” (left to right) is presented in Table. Note that some formats (e.g. TMY) does not follow this convention - as much as possible, the present weather codes are converted to this convention during WeatherConverter processing. Also note that the most important fields are those representing liquid precipitation - where the surfaces of the building would be wet. EnergyPlus uses “Snow Depth” to determine if snow is on the ground.
For example, a Present Weather Observation (previous field) of 0 and a Present Weather Codes field of 929999999 notes that there is heavy rain for this data period (usually hourly but depends on the number of intervals per hour field in the “Data Periods” record).
Field: Precipitable Water[LINK]
This is the value for Precipitable Water in mm. (This is not rain - rain is inferred from the PresWeathObs field but a better result is from the Liquid Precipitation Depth field)). It is not currently used in EnergyPlus calculations (primarily due to the unreliability of the reporting of this value). Missing value is 999.
Field: Aerosol Optical Depth[LINK]
This is the value for Aerosol Optical Depth in thousandths. It is not currently used in EnergyPlus calculations. Missing value is .999.
Field: Snow Depth[LINK]
This is the value for Snow Depth in cm. This field is used to tell when snow is on the ground and, thus, the ground reflectance may change. Missing value is 999.
Field: Days Since Last Snowfall[LINK]
This is the value for Days Since Last Snowfall. It is not currently used in EnergyPlus calculations. Missing value is 99.
Field: Albedo[LINK]
The ratio (unitless) of reflected solar irradiance to global horizontal irradiance. It is not currently used in EnergyPlus.
Field: Liquid Precipitation Depth[LINK]
The amount of liquid precipitation (mm) observed at the indicated time for the period indicated in the liquid precipitation quantity field. If this value is not missing, then it is used and overrides the “precipitation” flag as rainfall. Conversely, if the precipitation flag shows rain and this field is missing or zero, it is set to 1.5 (mm).
Field: Liquid Precipitation Quantity[LINK]
The period of accumulation (hr) for the liquid precipitation depth field. It is not currently used in EnergyPlus.
References[LINK]
Walton, G. N. 1983. Thermal Analysis Research Program Reference Manual. NBSSIR 83-2655. National Bureau of Standards, p. 21.
Clark, G. and C. Allen, “The Estimation of Atmospheric Radiation for Clear and Cloudy Skies,” Proceedings 2nd National Passive Solar Conference (AS/ISES), 1978, pp. 675-678.
Documentation content copyright © 1996-2026 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. EnergyPlus is a trademark of the US Department of Energy.
This documentation is made available under the EnergyPlus Open Source License v1.0.