Description of the Eppy

Authors: Santosh Philip, Leora Tanjuatco

Eppy is a scripting language for E+ idf files, and E+ output files. Eppy is written in the programming language Python. As a result it takes full advantage of the rich data structure and idioms that are available in python. You can programmatically navigate, search, and modify E+ idf files using eppy. The power of using a scripting language allows you to do the following:

• Make a large number of changes in an idf file with a few lines of eppy code.
• Use conditions and filters when making changes to an idf file
• Make changes to multiple idf files.
• Read data from the output files of a E+ simulation run.
• Based to the results of a E+ simulation run, generate the input file for the next simulation run.

So what does this matter? Here are some of the things you can do with eppy:

• Change construction for all north facing walls.
• Change the glass type for all windows larger than 2 square meters.
• Change the number of people in all the interior zones.
• Change the lighting power in all south facing zones.
• Change the efficiency and fan power of all rooftop units.
• Find the energy use of all the models in a folder (or of models that were run after a certain date)
• If a model is using more energy than expected, keep increasing the R-value of the roof until you get to the expected energy use.

Here is a short IDF file that I'll be using as an example to start us off:

To use eppy to look at this model, we first load the eppy library

Use IDF load your idf file and save as idf1. Now idf1 holds all the data to your in you idf file.

Now that the behind-the-scenes work is done, you can print this file using

idf1.printidf()

Looks like the same file as before, except that all the comments are slightly different.

As you can see, this file has four objects:

• VERSION
• SIMULATIONCONTROL
• BUILDING
• SITE:LOCATION

So, let us look take a closer look at the BUILDING object. You can do this using the command like using pandas: put the name of the object you'd like to look at in brackets.

You can also isolate the building name, and change it.

Did this actually change the name in the model ? Let us print the entire model and see.

Yes! It did. So now you have a taste of what eppy can do. Let's get started!

As previous step shows, in the IDF Editor, the building object is selected.

We can see all the fields of the object "BUILDING".

They are:

• Name
• North Axis
• Terrain
• Loads Convergence Tolerance Value
• Temperature Convergence Tolerance Value
• Solar Distribution
• Maximum Number of Warmup Days
• Minimum Number of Warmup Days

Let us try to access the other fields.

Where else can we find the field names?

The IDF Editor saves the idf file with the field name commented next to field.

Eppy also does this.

Let us take a look at the "BUILDING" object in the text file that the IDF Editor saves :

This a good place to find the field names too. It is easy to copy and paste from here. You can't do that from the IDF Editor.

We know that in an E+ model, there will be only ONE "BUILDING" object. This will be the first and only item in the list "buildings".

But E+ models are made up of objects such as "BUILDING", "SITE:LOCATION", "ZONE", "PEOPLE", "LIGHTS". There can be a number of "ZONE" objects, a number of "PEOPLE" objects and a number of "LIGHTS" objects.

So how do you know if you're looking at the first "ZONE" object or the second one? Or the tenth one? To answer this, we need to learn about how lists work in python.

Let us open a small idf file that has only "CONSTRUCTION" and "MATERIAL" objects in it. You can go into "../data/constructions.idf" and take a look at the file. We are not printing it here because it is too big.

So let us open it using the idfreader - IDF

After printing out all the "MATERIAL" objects in this model, you can see that there are many material objects in this idf file. The variable "materials" now contains a list of "MATERIAL" objects. You already know a little about lists, so let us take a look at the items in this list.

First material:

materials[0]

Let us print second material:

materials[1]

This is awesome!! Why?

To understand what you can do with your objects organized as lists, you'll have to learn a little more about the list.

Let us get those "MATERIAL" objects again.

Let us get the last material:

materials[-1]

How about the last two?

materials[-2:]

Pretty good.

Counting all the materials (or counting all objects)

How many materials are in this model?

len(materials)

Removing a material

Let us remove the last material in the list

was_last_material = materials.pop(-1)

Now the last material in the list is

Adding a material to the list

materials.append(was_last_material)

Once again, we have 10 materials and the last material in the list is

Adding a new material to the model

So far we have been working only with materials that were already in the list.

What if we want to make new material?

Obviously we would use the function 'newidfobject'.

materials.newidfobject("MATERIAL")

Now we have 11 items in the materials list.

Let us take a look at the last material in the list, where this fancy new material was added.

Looks a little different from the other materials. It does have the name we gave it.

Why do some fields have values and others are blank ?

"addobject" puts in all the default values, and leaves the others blank. It is up to us to put values in the the new fields.

Try to add these two materials by yourself:

Copy an existing material

idf1.copyidfobject(materials[-1])

Try to use loops with the material list:

for material in materials:
    print(material.Name)

or

[material.Name for material in materials]

or

[material.Thickness for material in materials if material.Thickness > 0.1]

or

thick_materials = [material for material in materials if material.Thickness > 0.1]

thick_materials:

...

You can also change the names of the thick materials

for material in thick_materials:
    material.Name = "THICK " + material.Name 

thick_materials:

...

So now we're working with two different lists: materials and thick_materials. But even though the items can be separated into two lists, we're still working with the same items.

Here's a helpful illustration:

Sometimes, we want information about the E+ object that is not in the fields. For example, it would be useful to know the areas and orientations of the surfaces. These attributes of the surfaces are not in the fields of surfaces, but surface objects do have fields that have the coordinates of the surface. The areas and orientations can be calculated from these coordinates.

Pyeplus has some functions that will do the calculations.

In the present version, pyeplus will calculate:

• surface azimuth
• surface tilt
• surface area

Let us explore these functions.

First, select "BUILDINGSURFACE" object and save as surfaces.

Take a look at the first surface:

Last 5 surface names and azimuths, surface names and tilt, surface names and areas:

Let us try to isolate the exterior north facing walls and change their constructions.

Select items based on following order:

• vertical walls

vertical_walls = [sf for sf in surfaces if sf.tilt == 90.0]

• north facing walls

north_walls = [sf for sf in vertical_walls if sf.azimuth == 0.0]

• north facing exterior walls

exterior_nwall = [sf for sf in north_walls if sf.Outside_Boundary_Condition == "Outdoors"]

More details of the north facing exterior walls:

Change the construction in the exterior north walls. The result should be like this:

Eppy Tutorial

https://pythonhosted.org/eppy/Main_Tutorial.html