Tutorial - What you can do¶
Author(s): Santosh Philip
We am using this tutorial/documentation as a way of identifying alformed API and gaps in the software. When eppy was developed, writing the user documentation forced us to rewrite the software. This documentation is written with the same intent. It is a little easier in the case of eppy3000, since we are trying to mimic eppy using it as a starting point.
Any places where the word TODO occurs is where we find some recoding has to be done. An issue has to be opened and then resolved.
Quick Start¶
Here is a short EPJ file that I’ll be using as an example to start us off
{
"Version": {
"Version 1": {
"version_identifier": "9.3",
"idf_order": 1
}
},
"SimulationControl": {
"SimulationControl 1": {
"do_zone_sizing_calculation": "Yes",
"do_system_sizing_calculation": "Yes",
"do_plant_sizing_calculation": "Yes",
"run_simulation_for_sizing_periods": "No",
"run_simulation_for_weather_file_run_periods": "Yes",
"idf_order": 2
}
},
"Building": {
"Empire State Building": {
"north_axis": 30,
"terrain": "City",
"loads_convergence_tolerance_value": 0.04,
"temperature_convergence_tolerance_value": 0.4,
"solar_distribution": "FullExterior",
"maximum_number_of_warmup_days": 25,
"minimum_number_of_warmup_days": 6,
"idf_order": 3
}
},
"Site:Location": {
"CHICAGO_IL_USA TMY2-94846": {
"latitude": 41.78,
"longitude": -87.75,
"time_zone": -6,
"elevation": 190,
"idf_order": 4
}
}
}
To use eppy3000 to look at this model, we have to run a little code first:
[1]:
# you would normaly install eppy3000 by doing
# python setup.py install
# or
# pip install eppy3000
# or
# easy_install eppy3000
# if you have not done so, uncomment the following three lines
import sys
# pathnameto_eppy = 'c:/eppy3000'
pathnameto_eppy3000 = '../'
sys.path.append(pathnameto_eppy3000)
from eppy3000.modelmaker import EPJ
schema_file = "../eppy3000/resources/schema/V9_3/Energy+.schema.epJSON"
ep_file = "../eppy3000/resources/epJSON/V9_3/smallfile.epJSON"
[2]:
epj = EPJ(epjname=ep_file, epschemaname=schema_file)
[3]:
print(epj)
Version !- EP_KEY # use .eppykey
Version 1 !- EPJOBJECT_NAME # use .eppyname
9.3 !- version_identifier
1 !- idf_order
SimulationControl !- EP_KEY # use .eppykey
SimulationControl 1 !- EPJOBJECT_NAME # use .eppyname
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
2 !- idf_order
Building !- EP_KEY # use .eppykey
Empire State Building !- EPJOBJECT_NAME # use .eppyname
30 !- 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
3 !- idf_order
Site:Location !- EP_KEY # use .eppykey
CHICAGO_IL_USA TMY2-94846 !- EPJOBJECT_NAME # use .eppyname
41.78 !- latitude
-87.75 !- longitude
-6 !- time_zone
190 !- elevation
4 !- idf_order
Looks like the same file as before, except that it is written in the idf format
As you can see, this file has four objects:
Version
SimulationControl
Building
Site:Location
You may notice some weird fields like EP_KEY and EPJOBJECT_NAME
Let us look at the Version object and tease out what is going on
The EPjson for version object looks like this:
{
"Version": {
"Version 1": {
"version_identifier": "9.3",
"idf_order": 1
}
},
... <snip> ...
More objects below
}
But eppy3000 prints it like this
Version !- EP_KEY # use .eppykey
Version 1 !- EPJOBJECT_NAME # use .eppyname
9.3 !- version_identifier
1 !- idf_order
E+ and eppy3000 see the E+ objects slightly differently.
Eppy3000 sees each object as having fields
E+ and EPjson see each object as key-value pairs
If you stare at the above representation in EPjson and eppy3000 you will see how they are different and how they work.
Let us play with the eppy3000 version
[4]:
versions = epj.epobjects["Version"]
version = versions[0]
print(version)
Version !- EP_KEY # use .eppykey
Version 1 !- EPJOBJECT_NAME # use .eppyname
9.3 !- version_identifier
1 !- idf_order
[23]:
print(version.eppykey)
Version
[25]:
print(version.eppyname)
Version 1
[27]:
print(version.version_identifier)
9.3
[28]:
print(version.idf_order)
1
TODO: test what happens when user changes eppykey and eppyname
Let us do the same with the EPjson object. Let us treat it as a pure json object
[37]:
import json
jsonstr = """ {
"Version": {
"Version 1": {
"version_identifier": "9.3",
"idf_order": 1
}
}
}"""
print(jsonstr)
{
"Version": {
"Version 1": {
"version_identifier": "9.3",
"idf_order": 1
}
}
}
[38]:
epjson = json.loads(jsonstr)
print(epjson)
{'Version': {'Version 1': {'version_identifier': '9.3', 'idf_order': 1}}}
[39]:
ep_versions = epjson["Version"]
print(ep_versions)
{'Version 1': {'version_identifier': '9.3', 'idf_order': 1}}
[40]:
ep_version = ep_versions["Version 1"]
print(ep_version)
{'version_identifier': '9.3', 'idf_order': 1}
[41]:
print(ep_version["version_identifier"])
9.3
[42]:
print(ep_version["idf_order"])
1
Do you notice how much easier it is to operate with the eppy3000 than direclty with the json structure of EPjson
So, let us look take a closer look at the BUILDING object. We can do this using this command:
print(epjfile.epobjects[‘OBJECTNAME’])
[4]:
print(epj.epobjects['Building']) # put the name of the object you'd like to look at in brackets
[
Building !- EP_KEY # use .eppykey
Empire State Building !- EPJOBJECT_NAME # use .eppyname
30 !- 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
3 !- idf_order]
We can also zoom in on the object and look just at its individual parts.
For example, let us look at the name of the building.
[5]:
building = epj.epobjects['Building'][0]
Now we can do this:
[6]:
building.eppyname
[6]:
'Empire State Building'
Now that we’ve isolated the building name, we can change it.
[7]:
building.eppyname = "Taj Mahal"
Did this actually change the name in the model ? Let us print the entire model and see.
[8]:
print(epj)
Version !- EP_KEY # use .eppykey
Version 1 !- EPJOBJECT_NAME # use .eppyname
9.3 !- version_identifier
1 !- idf_order
SimulationControl !- EP_KEY # use .eppykey
SimulationControl 1 !- EPJOBJECT_NAME # use .eppyname
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
2 !- idf_order
Building !- EP_KEY # use .eppykey
Taj Mahal !- EPJOBJECT_NAME # use .eppyname
30 !- 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
3 !- idf_order
Site:Location !- EP_KEY # use .eppykey
CHICAGO_IL_USA TMY2-94846 !- EPJOBJECT_NAME # use .eppyname
41.78 !- latitude
-87.75 !- longitude
-6 !- time_zone
190 !- elevation
4 !- idf_order
Yes! It did. So now you have a taste of what eppy can do. Let’s get started!
Modifying EPJ Fields¶
That was just a quick example – we were showing off. Let’s look a little closer.
As you might have guessed, changing an EPJ field follows this structure:
object.fieldname = "New Field Name"
Plugging the object name (building), the field name (Name) and our new field name (“Empire State Building”) into this command gave us this:
object.fieldname = "New Field Name"
But how did we know that “Name” is one of the fields in the object “building”?
Are there other fields?
What are they called?
[9]:
# TODO: need to implement the function fieldnames()
Python lesson 1: lists¶
do this later ?
How many items in the list¶
Do this later
Saving an epj file¶
This is easy:
epj.save()
# OR
epj.saveas("newname.epJSON")
Working with E+ objects¶
Let us open a small epj file that has only “CONSTRUCTION” and “MATERIAL” objects in it. You can go into “../eppy3000/resources/epJSON/V9_3/constructions.epJSON” 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 -
[10]:
from eppy3000 import modelmaker
from eppy3000.modelmaker import EPJ
fname = "../eppy3000/resources/epJSON/V9_3/constructions.epJSON"
epschemaname ="../eppy3000/resources/schema/V9_0/Energy+.schema.epJSON"
epj = EPJ(fname, epschemaname)
Let us print all the “MATERIAL” objects in this model.
[11]:
materials = epj.epobjects["Material"]
print(materials)
[
Material !- EP_KEY # use .eppykey
F08 Metal surface !- EPJOBJECT_NAME # use .eppyname
Smooth !- roughness
0.0008 !- thickness
45.28 !- conductivity
7824 !- density
500 !- specific_heat
2 !- idf_order,
Material !- EP_KEY # use .eppykey
I01 25mm insulation board !- EPJOBJECT_NAME # use .eppyname
MediumRough !- roughness
0.0254 !- thickness
0.03 !- conductivity
43 !- density
1210 !- specific_heat
3 !- idf_order,
Material !- EP_KEY # use .eppykey
I02 50mm insulation board !- EPJOBJECT_NAME # use .eppyname
MediumRough !- roughness
0.0508 !- thickness
0.03 !- conductivity
43 !- density
1210 !- specific_heat
4 !- idf_order,
Material !- EP_KEY # use .eppykey
G01a 19mm gypsum board !- EPJOBJECT_NAME # use .eppyname
MediumSmooth !- roughness
0.019 !- thickness
0.16 !- conductivity
800 !- density
1090 !- specific_heat
5 !- idf_order,
Material !- EP_KEY # use .eppykey
M11 100mm lightweight concrete !- EPJOBJECT_NAME # use .eppyname
MediumRough !- roughness
0.1016 !- thickness
0.53 !- conductivity
1280 !- density
840 !- specific_heat
6 !- idf_order,
Material !- EP_KEY # use .eppykey
F16 Acoustic tile !- EPJOBJECT_NAME # use .eppyname
MediumSmooth !- roughness
0.0191 !- thickness
0.06 !- conductivity
368 !- density
590 !- specific_heat
7 !- idf_order,
Material !- EP_KEY # use .eppykey
M01 100mm brick !- EPJOBJECT_NAME # use .eppyname
MediumRough !- roughness
0.1016 !- thickness
0.89 !- conductivity
1920 !- density
790 !- specific_heat
8 !- idf_order,
Material !- EP_KEY # use .eppykey
M15 200mm heavyweight concrete !- EPJOBJECT_NAME # use .eppyname
MediumRough !- roughness
0.2032 !- thickness
1.95 !- conductivity
2240 !- density
900 !- specific_heat
9 !- idf_order,
Material !- EP_KEY # use .eppykey
M05 200mm concrete block !- EPJOBJECT_NAME # use .eppyname
MediumRough !- roughness
0.2032 !- thickness
1.11 !- conductivity
800 !- density
920 !- specific_heat
10 !- idf_order,
Material !- EP_KEY # use .eppykey
G05 25mm wood !- EPJOBJECT_NAME # use .eppyname
MediumSmooth !- roughness
0.0254 !- thickness
0.15 !- conductivity
608 !- density
1630 !- specific_heat
11 !- idf_order]
As you can see, there are many material objects in this epj 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.
[12]:
firstmaterial = materials[0]
secondmaterial = materials[1]
[13]:
print(firstmaterial)
Material !- EP_KEY # use .eppykey
F08 Metal surface !- EPJOBJECT_NAME # use .eppyname
Smooth !- roughness
0.0008 !- thickness
45.28 !- conductivity
7824 !- density
500 !- specific_heat
2 !- idf_order
Let us print secondmaterial
[18]:
print(secondmaterial)
Material !- EP_KEY
I01 25mm insulation board !- EPJOBJECT_NAME
MediumRough !- roughness
0.0254 !- thickness
0.03 !- conductivity
43 !- density
1210 !- specific_heat
3 !- idf_order
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 lists.
Python lesson 2: more about lists¶
More ways to access items in a list¶
Do this later
Continuing to work with E+ objects¶
Let us get those “MATERIAL” objects again
[21]:
materials = epj.epobjects["Material"]
With our newfound knowledge of lists, we can do a lot of things.
Let us get the last material:
[22]:
print(materials[-1])
Material !- EP_KEY
G05 25mm wood !- EPJOBJECT_NAME
MediumSmooth !- roughness
0.0254 !- thickness
0.15 !- conductivity
608 !- density
1630 !- specific_heat
11 !- idf_order
How about the last two?
[23]:
print(materials[-2:])
[
Material !- EP_KEY
M05 200mm concrete block !- EPJOBJECT_NAME
MediumRough !- roughness
0.2032 !- thickness
1.11 !- conductivity
800 !- density
920 !- specific_heat
10 !- idf_order,
Material !- EP_KEY
G05 25mm wood !- EPJOBJECT_NAME
MediumSmooth !- roughness
0.0254 !- thickness
0.15 !- conductivity
608 !- density
1630 !- specific_heat
11 !- idf_order]
More stuff to do later
Python lesson 3: indentation and looping through lists¶
Do later
Looping through E+ objects¶
If you have read the python explanation of loops, you are now masters of using loops.
Let us use the loops with E+ objects.
We’ll continue to work with the materials list.
[25]:
for material in materials:
print(material.eppyname)
F08 Metal surface
I01 25mm insulation board
I02 50mm insulation board
G01a 19mm gypsum board
M11 100mm lightweight concrete
F16 Acoustic tile
M01 100mm brick
M15 200mm heavyweight concrete
M05 200mm concrete block
G05 25mm wood
[26]:
[material.eppyname for material in materials]
[26]:
['F08 Metal surface',
'I01 25mm insulation board',
'I02 50mm insulation board',
'G01a 19mm gypsum board',
'M11 100mm lightweight concrete',
'F16 Acoustic tile',
'M01 100mm brick',
'M15 200mm heavyweight concrete',
'M05 200mm concrete block',
'G05 25mm wood']
[28]:
[material.roughness for material in materials]
[28]:
['Smooth',
'MediumRough',
'MediumRough',
'MediumSmooth',
'MediumRough',
'MediumSmooth',
'MediumRough',
'MediumRough',
'MediumRough',
'MediumSmooth']
[31]:
[material.thickness for material in materials if material.thickness > 0.1]
[31]:
[0.1016, 0.1016, 0.2032, 0.2032]
[32]:
[material.eppyname for material in materials if material.thickness > 0.1]
[32]:
['M11 100mm lightweight concrete',
'M01 100mm brick',
'M15 200mm heavyweight concrete',
'M05 200mm concrete block']
[33]:
thick_materials = [material for material in materials if material.thickness > 0.1]
[34]:
thick_materials
[34]:
[
Material !- EP_KEY
M11 100mm lightweight concrete !- EPJOBJECT_NAME
MediumRough !- roughness
0.1016 !- thickness
0.53 !- conductivity
1280 !- density
840 !- specific_heat
6 !- idf_order,
Material !- EP_KEY
M01 100mm brick !- EPJOBJECT_NAME
MediumRough !- roughness
0.1016 !- thickness
0.89 !- conductivity
1920 !- density
790 !- specific_heat
8 !- idf_order,
Material !- EP_KEY
M15 200mm heavyweight concrete !- EPJOBJECT_NAME
MediumRough !- roughness
0.2032 !- thickness
1.95 !- conductivity
2240 !- density
900 !- specific_heat
9 !- idf_order,
Material !- EP_KEY
M05 200mm concrete block !- EPJOBJECT_NAME
MediumRough !- roughness
0.2032 !- thickness
1.11 !- conductivity
800 !- density
920 !- specific_heat
10 !- idf_order]
[35]:
# change the names of the thick materials
for material in thick_materials:
material.eppyname = "THICK " + material.eppyname
[36]:
thick_materials
[36]:
[
Material !- EP_KEY
THICK M11 100mm lightweight concrete !- EPJOBJECT_NAME
MediumRough !- roughness
0.1016 !- thickness
0.53 !- conductivity
1280 !- density
840 !- specific_heat
6 !- idf_order,
Material !- EP_KEY
THICK M01 100mm brick !- EPJOBJECT_NAME
MediumRough !- roughness
0.1016 !- thickness
0.89 !- conductivity
1920 !- density
790 !- specific_heat
8 !- idf_order,
Material !- EP_KEY
THICK M15 200mm heavyweight concrete !- EPJOBJECT_NAME
MediumRough !- roughness
0.2032 !- thickness
1.95 !- conductivity
2240 !- density
900 !- specific_heat
9 !- idf_order,
Material !- EP_KEY
THICK M05 200mm concrete block !- EPJOBJECT_NAME
MediumRough !- roughness
0.2032 !- thickness
1.11 !- conductivity
800 !- density
920 !- specific_heat
10 !- idf_order]
Do the rest later
Geometry functions in eppy3000¶
No geometry functions yet in eppy3000
TODO: Add geometry functions