Learn the EnergyPlus Data Format (Part 1)

Most of the people in building energy modeling field know EnergyPlus, and a fair amount of people have already played around with EnergyPlus in some authoring tools such as OpenStudio, DesignBuilder, Autodesk Insight 360 orSefaira. These are great software that allows you to perform various tasks with EnergyPlus. However, these tools also set a fence on your imaginations sometimes. When this happens, a happy news is, these fences may not be there in EnergyPlus! And the bad news is, you have to deal with the most tedious user interface - text editor - to do your work.

I was in the SimBuild 2016 conference last year and listened to Michael O'Keefe's presentation about how to be a super productive energy modeler with a text editor. The techniques he mentioned in his presentations includes text manipulations, version controls, text template, and scripting. I highly recommend to check out his work in here. Using a text editor to do energy modeling could be, in some situations, more efficient than using EnergyPlus authoring tools. It supports a much faster data search function, and it sorts all the objects in order. It helps collaborations among multiple people, and you can even write scripts to automate some repeated work with your energy modeling style.

However, I found many people who don't use text editor are not because they don't like the interface, but because they don't understand the texts, in the raw .idf file. So I want to write down some of my understandings about these texts / EnergyPlus data format to help people start using text editors.

First, we should break down the texts in a raw .idf file into two components. 1. The data of an EnergyPlus object, and 2. the format that arranges the order of these data.

If you see a text block that starts with an EnergyPlus object name and ends with a semicolon ";", it represents an EnergyPlus object.

Take a look at the example above. It is a Site:Location object in EnergyPlus. The data we see here contains the location name (USA IL-CHICAGO-OHARE), the latitude (41.77 deg) and longitude (-87.75 deg) of this location, the time zone (-6.00 hr) that this particular location resides in and its elevation (190 m). Each piece of data is called the Field.

You will also find that this information is arranged in a key-value style. The words start with "!-" and in green font are the keys, and words in black font are the values. It is the format how EnergyPlus arranges its data. There are exceptions, for example, the sentence starts with "!" is a comment. Comments do not affect the data or simulation flow. However, it provides some explanations to the data. The other exception is the words in blue font. These words represent the object label ("Site:Location"). That's it! We just learned all the possible data format in an EnergyPlus input data file (.IDF).

However, sometimes, we don't see such a neat data format in an .IDF file. It may look like this:

Site:Location, USA IL-CHICAGO-OHARE, 41.77, -87.75, -6.00, 190;

No indentation and no keys in this example. The format may get worse by putting everything in one line. If we see this, we need to use some tools to sort the text file. Tools such as the IDFEditor (comes with the EnergyPlus installation package) and the BuildSimHub can help you sort the model data.

For IDFEditor, the sorting is usually automatically applied by saving the file with some changes have been done. One exception is when the data file starts with "!-Option OriginalOrderTop". It tells the IDFEditor do not sort the energy model. Furthermore, the model validation by the IDFEditor follows the Energy+.Idd file, which locates in the EnergyPlus folder. If any object contains more fields than it has in the .idd file specified, the IDFEditor will return severe errors such as the one below:

If there are too many of these errors, the IDFEditor will stop reading the .IDF file and exit. What's worse, if you ignore these warnings and successfully opened the IDF file, the IDFEditor may truncate the overflowed fields, which means your data will be lost in IDFEditor.

On the contrary, the BuildSimHub has no such limitations. Once you upload your .IDF file to the system, it validates the energy model against its flexible .idd and then sorts the IDF file in order.

Next part we will continue to discuss this topic. Let's look forward to it.