EpBunch

:Author: Santosh Philip.

EpBunch is at the heart of what makes eppy easy to use. Specifically Epbunch is what allows us to use the syntax building.Name and building.North_Axis. Some advanced coding had to be done to make this happen. Coding that would be easy for professional programmers, but not for us ordinary folk :-(

Most of us who are going to be coding eppy are not professional programmers. I was completely out of my depth when I did this coding. I had the code reviewed by programmers who do this for a living (at python meetups in the Bay Area). In their opinion, I was not doing anything fundamentally wrong.

Below is a fairly long explanation, to ease you into the code. Read through the whole thing without trying to understand every detail, just getting a birds eye veiw of the explanation. Then read it again, you will start to grok some of the details. All the code here is working code, so you can experiment with it.

Magic Methods (Dunders) of Python

To understand how EpBunch or Bunch is coded, one has to have an understanding of the magic methods of Python. (For a background on magic methods, take a look at http://www.rafekettler.com/magicmethods.html) Let us dive straight into this with some examples


In [1]:
adict = dict(a=10, b=20) # create a dictionary
print adict
print adict['a']
print adict['b']


{'a': 10, 'b': 20}
10
20

What happens when we say d['a'] ?

This is where the magic methods come in. Magic methods are methods that work behind the scenes and do some magic. So when we say d['a'], The dict is calling the method __getitem__('a').

Magic methods have a double underscore "__", called dunder methods for short

Let us override that method and see what happens.


In [1]:
class Funnydict(dict): # we are subclassing dict here
    def __getitem__(self, key):
        value = super(Funnydict, self).__getitem__(key)
        return "key = %s, value = %s" % (key, value)

funny = Funnydict(dict(a=10, b=20)) 
print funny


{'a': 10, 'b': 20}

The print worked as expected. Now let us try to print the values


In [3]:
print funny['a']
print funny['b']


key = a, value = 10
key = b, value = 20

Now that worked very differently from a dict

So it is true, funny['a'] does call __getitem__() that we just wrote

Let us go back to the variable adict


In [4]:
# to jog our memory
print adict


{'a': 10, 'b': 20}

In [5]:
# this should not work
print adict.a


---------------------------------------------------------------------------
AttributeError                            Traceback (most recent call last)
<ipython-input-5-8aa7211fcb66> in <module>()
      1 # this should not work
----> 2 print adict.a

AttributeError: 'dict' object has no attribute 'a'

What method gets called when we say adict.a ?

The magic method here is __getattr__() and __setattr__(). Shall we override them and see if we can get the dot notation to work ?


In [6]:
class Like_bunch(dict):
    def __getattr__(self, name):
        return self[name]
    def __setattr__(self, name, value):
        self[name] = value

lbunch = Like_bunch(dict(a=10, b=20))
print lbunch


{'a': 10, 'b': 20}

Works like a dict so far. How about lbunch.a ?


In [7]:
print lbunch.a
print lbunch.b


10
20

Yipeee !!! I works

How about lbunch.nota = 100


In [8]:
lbunch.anot = 100
print lbunch.anot


100

All good here. But don't trust the code above too much. It was simply done as a demonstration of dunder methods and is not fully tested.

Eppy uses the bunch library to do something similar. You can read more about the bunch library in the previous section.

Open an IDF file

Once again let us open a small idf file to test.


In [9]:
# you would normaly install eppy by doing
# python setup.py install
# or
# pip install eppy
# or
# easy_install eppy

# if you have not done so, uncomment the following three lines
import sys
# pathnameto_eppy = 'c:/eppy'
pathnameto_eppy = '../../../'
sys.path.append(pathnameto_eppy)

In [10]:
from eppy import modeleditor
from eppy.modeleditor import IDF
iddfile = "../../../eppy/resources/iddfiles/Energy+V7_2_0.idd"
fname1 = "../../../eppy/resources/idffiles/V_7_2/dev1.idf"

IDF.setiddname(iddfile)
idf1 = IDF(fname1)
idf1.printidf()


VERSION,                  
    7.3;                      !- Version Identifier

SIMULATIONCONTROL,        
    Yes,                      !- Do Zone Sizing Calculation
    Yes,                      !- Do System Sizing Calculation
    Yes,                      !- Do Plant Sizing Calculation
    No,                       !- Run Simulation for Sizing Periods
    Yes;                      !- Run Simulation for Weather File Run Periods

BUILDING,                 
    Empire State Building,    !- Name
    30.0,                     !- North Axis
    City,                     !- Terrain
    0.04,                     !- Loads Convergence Tolerance Value
    0.4,                      !- Temperature Convergence Tolerance Value
    FullExterior,             !- Solar Distribution
    25,                       !- Maximum Number of Warmup Days
    6;                        !- Minimum Number of Warmup Days

SITE:LOCATION,            
    CHICAGO_IL_USA TMY2-94846,    !- Name
    41.78,                    !- Latitude
    -87.75,                   !- Longitude
    -6.0,                     !- Time Zone
    190.0;                    !- Elevation

MATERIAL:AIRGAP,          
    F04 Wall air space resistance,    !- Name
    0.15;                     !- Thermal Resistance

MATERIAL:AIRGAP,          
    F05 Ceiling air space resistance,    !- Name
    0.18;                     !- Thermal Resistance


In [11]:
dtls = idf1.model.dtls
dt = idf1.model.dt
idd_info = idf1.idd_info

In [12]:
dt['MATERIAL:AIRGAP']


Out[12]:
[['MATERIAL:AIRGAP', 'F04 Wall air space resistance', 0.15],
 ['MATERIAL:AIRGAP', 'F05 Ceiling air space resistance', 0.18]]

In [13]:
obj_i = dtls.index('MATERIAL:AIRGAP')
obj_idd = idd_info[obj_i]
obj_idd


Out[13]:
[{'memo': ['Air Space in Opaque Construction'], 'min-fields': ['2']},
 {'field': ['Name'],
  'reference': ['MaterialName'],
  'required-field': [''],
  'type': ['alpha']},
 {'field': ['Thermal Resistance'],
  'minimum>': ['0'],
  'type': ['real'],
  'units': ['m2-K/W']}]

For the rest of this section let us look at only one airgap object


In [14]:
airgap = dt['MATERIAL:AIRGAP'][0]
airgap


Out[14]:
['MATERIAL:AIRGAP', 'F04 Wall air space resistance', 0.15]

Subclassing of Bunch

Let us review our knowledge of bunch


In [15]:
from bunch import Bunch
adict = {'a':1, 'b':2, 'c':3}
bunchdict = Bunch(adict)
print bunchdict
print bunchdict.a
print bunchdict.b
print bunchdict.c


Bunch(a=1, b=2, c=3)
1
2
3

Bunch lets us use dot notation on the keys of a dictionary. We need to find a way of making airgap.Name work. This is not straightforward because, airgap is list and Bunch works on dicts. It would be easy if airgap was in the form {'Name' : 'F04 Wall air space resistance', 'Thermal Resistance' : 0.15}.

The rest of this section is a simplified version of how EpBunch works.


In [16]:
class EpBunch(Bunch):
    def __init__(self, obj, objls, objidd, *args, **kwargs):
        super(EpBunch, self).__init__(*args, **kwargs)
        self.obj = obj
        self.objls = objls
        self.objidd = objidd

The above code shows how EpBunch is initialized. Three variables are passed to EpBunch to initialize it. They are obj, objls, objidd.


In [17]:
obj = airgap
objls = ['key', 'Name', 'Thermal_Resistance'] # a function extracts this from idf1.idd_info
objidd = obj_idd
#
print obj
print objls
# let us ignore objidd for now


['MATERIAL:AIRGAP', 'F04 Wall air space resistance', 0.15]
['key', 'Name', 'Thermal_Resistance']

Now we override __setattr__() and __getattr__() in the following way


In [18]:
class EpBunch(Bunch):
    def __init__(self, obj, objls, objidd, *args, **kwargs):
        super(EpBunch, self).__init__(*args, **kwargs)
        self.obj = obj
        self.objls = objls
        self.objidd = objidd
        
    def __getattr__(self, name):
        if name in ('obj', 'objls', 'objidd'):
            return super(EpBunch, self).__getattr__(name)
        i = self.objls.index(name)
        return self.obj[i]

    def __setattr__(self, name, value):
        if name in ('obj', 'objls', 'objidd'):
            super(EpBunch, self).__setattr__(name, value)
            return None
        i = self.objls.index(name)
        self.obj[i] = value

In [19]:
# Let us create a EpBunch object
bunch_airgap = EpBunch(obj, objls, objidd)
# Use this table to see how __setattr__ and __getattr__ work in EpBunch obj = ['MATERIAL:AIRGAP', 'F04 Wall air space resistance', 0.15 ] objls = ['key', 'Name', 'Thermal_Resistance'] i = 0 1 2

In [20]:
print bunch_airgap.Name
print bunch_airgap.Thermal_Resistance


F04 Wall air space resistance
0.15

In [21]:
print bunch_airgap.obj


['MATERIAL:AIRGAP', 'F04 Wall air space resistance', 0.15]

Let us change some values using the dot notation


In [22]:
bunch_airgap.Name = 'Argon in gap'

In [23]:
print bunch_airgap.Name


Argon in gap

In [24]:
print bunch_airgap.obj


['MATERIAL:AIRGAP', 'Argon in gap', 0.15]

Using the dot notation the value is changed in the list

Let us make sure it actually has done that.


In [25]:
idf1.model.dt['MATERIAL:AIRGAP'][0]


Out[25]:
['MATERIAL:AIRGAP', 'Argon in gap', 0.15]

EpBunch acts as a wrapper around idf1.model.dt['MATERIAL:AIRGAP'][0]

In other words EpBunch is just Syntactic Sugar for idf1.model.dt['MATERIAL:AIRGAP'][0]

Variables and Names in Python

At this point your reaction may, "I don't see how all those values in idf1.model.dt changed". If such question arises in your mind, you need to read the following:

This is especially important if you are experienced in other languages, and you expect the behavior to be a little different. Actually follow and read those links in any case.

Continuing with EpBunch

EpBunch_1

The code for EpBunch in the earlier section will work, but has been simplified for clarity. In file bunch_subclass.py take a look at the class EpBunch_1 . This class does the first override of __setattr__ and __getattr__. You will see that the code is a little more involved, dealing with edge conditions and catching exceptions.

EpBunch_1 also defines __repr__. This lets you print EpBunch in a human readable format. Further research indicates that __str__ should have been used to do this, not __repr__ :-(

EpBunch_2

EpBunch_2 is subclassed from EpBunch_1.

It overrides __setattr__ and __getattr__ to add a small functionality that has not been documented or used. The idea was to give the ability to shorten field names with alias. So building.Maximum_Number_of_Warmup_Days could be made into building.warmupdays.

I seemed like a good idea when I wrote it. Ignore it for now, although it may make a comeback :-)

EpBunch_3

EpBunch_3 is subclassed from EpBunch_2.

EpBunch_3 adds the ability to add functions to EpBunch objects. This would allow the object to make calculations using data within the object. So BuildingSurface:Detailed object has all the geometry data of the object. The function 'area' will let us calculate the are of the object even though area is not a field in BuildingSurface:Detailed.

So you can call idf1.idfobjects["BuildingSurface:Detailed"][0].area and get the area of the surface.

At the moment, the functions can use only data within the object for it's calculation. We need to extend this functionality so that calculations can be done using data outside the object. This would be useful in calculating the volume of a Zone. Such a calculation would need data from the surfaces that the aone refers to.

EpBunch_4

EpBunch_4 is subclassed from EpBunch_3.

EpBunch_4 overrides _setitem__ and __getitem__. Right now airgap.Name works. This update allows airgap["Name"] to work correctly too

EpBunch_5

EpBunch_5 is subclassed from EpBunch_4.

EpBunch_5 adds functions that allows you to call functions getrange and checkrange for a field

Finally EpBunch

EpBunch = EpBunch_5

Finally EpBunch_5 is named as EpBunch. So the rest of the code uses EpBunch and in effect it uses Epbunch_5