geomeppy¶
This package contains the main API for geomeppy, the IDF class. This class is a drop-in substitute for the IDF class in eppy. The functions documented here are not only for geomeppy. All the existing functions of eppy.modeleditor.IDF are also still available.
Any functions in this class can be considered as stable. Changes in the future will only add functionality (or fix bugs, should any arise).
-
class
geomeppy.
IDF
(idfname=None, epw=None)¶ Bases:
geomeppy.patches.PatchedIDF
Geometry-enabled IDF class, usable in the same way as Eppy’s IDF.
This adds geometry functionality to Eppy’s IDF class.
-
add_block
(*args, **kwargs)¶ Add a block to the IDF.
Parameters: - name – A name for the block.
- coordinates – A list of (x, y) tuples representing the building outline.
- height – The height of the block roof above ground level.
- num_stories – The total number of stories including basement stories. Default : 1.
- below_ground_stories – The number of stories below ground. Default : 0.
- below_ground_storey_height – The height of each basement storey. Default : 2.5.
-
add_shading_block
(*args, **kwargs)¶ Add a shading block to the IDF.
Parameters: - name – A name for the block.
- coordinates – A list of (x, y) tuples representing the building outline.
- height – The height of the block roof above ground level.
- num_stories – The total number of stories including basement stories. Default : 1.
- below_ground_stories – The number of stories below ground. Default : 0.
- below_ground_storey_height – The height of each basement storey. Default : 2.5.
-
add_zone
(zone)¶ Add a zone to the IDF.
Parameters: zone – A Zone object holding details about the zone.
-
block
= None¶
-
bounding_box
()¶ Calculate the site bounding box.
Returns: A polygon of the bounding box.
-
centroid
¶ Calculate the centroid of the site bounding box.
Returns: The centroid of the site bounding box.
-
copyidfobject
(idfobject)¶ Add an IDF object to the IDF.
This has been monkey-patched to add the return value.
Parameters: idfobject – The IDF object to copy. Usually from another IDF, or it can be used to copy within this IDF. Returns: EpBunch object.
-
getextensibleindex
(key, name)¶ Get the index of the first extensible item.
Only for internal use. # TODO : hide this
- key : str
- The type of IDF object. This must be in ALL_CAPS.
- name : str
- The name of the object to fetch.
int
-
getiddgroupdict
()¶ Return a idd group dictionary sample: {‘Plant-Condenser Loops’: [‘PlantLoop’, ‘CondenserLoop’],
‘Compliance Objects’: [‘Compliance:Building’], ‘Controllers’: [‘Controller:WaterCoil’,
‘Controller:OutdoorAir’, ‘Controller:MechanicalVentilation’, ‘AirLoopHVAC:ControllerList’],…}
dict
-
getiddname
()¶ Get the name of the current IDD used by eppy.
str
-
getobject
(key, name)¶ Fetch an IDF object given key and name.
- key : str
- The type of IDF object. This must be in ALL_CAPS.
- name : str
- The name of the object to fetch.
EpBunch object.
-
getshadingsurfaces
(surface_type=None)¶ Return all subsurfaces in the IDF.
Returns: IDF surfaces.
-
getsubsurfaces
(surface_type=None)¶ Return all subsurfaces in the IDF.
Returns: IDF surfaces.
-
getsurfaces
(surface_type=None)¶ Return all surfaces in the IDF.
Parameters: surface – Type of surface to get. Defaults to all. Returns: IDF surfaces.
-
idd_info
= None¶
-
iddname
= None¶
-
idfstr
()¶ String representation of the IDF.
str
-
initnew
(fname)¶ Use the current IDD and create a new empty IDF. If the IDD has not yet been initialised then this is done first.
- fname : str, optional
- Path to an IDF. This does not need to be set at this point.
-
initread
(idfname)¶ Use the current IDD and read an IDF from file. If the IDD has not yet been initialised then this is done first.
- idf_name : str
- Path to an IDF file.
-
initreadtxt
(idftxt)¶ Use the current IDD and read an IDF from text data. If the IDD has not yet been initialised then this is done first.
- idftxt : str
- Text representing an IDF file.
-
intersect
()¶ Intersect all surfaces in the IDF.
-
intersect_match
()¶ Intersect all surfaces in the IDF, then set boundary conditions.
-
match
()¶ Set boundary conditions for all surfaces in the IDF.
-
new
(fname=None)¶ Create a blank new idf file. Filename is optional.
- fname : str, optional
- Path to an IDF. This does not need to be set at this point.
-
newidfobject
(key, aname='', **kwargs)¶ Add a new idfobject to the model.
If you don’t specify a value for a field, the default value will be set.
For example
newidfobject("CONSTRUCTION") newidfobject("CONSTRUCTION", Name='Interior Ceiling_class', Outside_Layer='LW Concrete', Layer_2='soundmat')
Parameters: - key – The type of IDF object. This must be in ALL_CAPS.
- aname – This parameter is not used. It is left there for backward compatibility.
- kwargs – Keyword arguments in the format field=value used to set fields in the EnergyPlus object.
Returns: EpBunch object.
-
popidfobject
(key, index)¶ Pop an IDF object from the IDF.
- key : str
- The type of IDF object. This must be in ALL_CAPS.
- index : int
- The index of the object to pop.
EpBunch object.
-
printidf
()¶ Print the IDF.
-
read
()¶ Read the IDF file and the IDD file.
If the IDD file had already been read, it will not be read again.
Populates the following data structures:
- idfobjects : list - model : list - idd_info : list - idd_index : dict
-
removeextensibles
(key, name)¶ Remove extensible items in the object of key and name.
Only for internal use. # TODO : hide this
- key : str
- The type of IDF object. This must be in ALL_CAPS.
- name : str
- The name of the object to fetch.
EpBunch object
-
removeidfobject
(idfobject)¶ Remove an IDF object from the IDF.
- idfobject : EpBunch object
- The IDF object to remove.
-
rotate
(angle, anchor=None)¶ Rotate the IDF counterclockwise by the angle given.
Parameters: - angle – Angle (in degrees) to rotate by.
- anchor – Point around which to rotate. Default is the centre of the the IDF’s bounding box.
-
run
(**kwargs)¶ This method wraps the following method:
- rruunn(idf=None, weather=None, output_directory=u’‘, annual=False, design_day=False, idd=None, epmacro=False, expandobjects=False, readvars=False, output_prefix=None, output_suffix=None, version=False, verbose=u’v’, ep_version=None)
Wrapper around the EnergyPlus command line interface.
- idf : str
- Full or relative path to the IDF file to be run, or an IDF object.
- weather : str
- Full or relative path to the weather file.
- output_directory : str, optional
- Full or relative path to an output directory (default: ‘run_outputs)
- annual : bool, optional
- If True then force annual simulation (default: False)
- design_day : bool, optional
- Force design-day-only simulation (default: False)
- idd : str, optional
- Input data dictionary (default: Energy+.idd in EnergyPlus directory)
- epmacro : str, optional
- Run EPMacro prior to simulation (default: False).
- expandobjects : bool, optional
- Run ExpandObjects prior to simulation (default: False)
- readvars : bool, optional
- Run ReadVarsESO after simulation (default: False)
- output_prefix : str, optional
- Prefix for output file names (default: eplus)
- output_suffix : str, optional
- Suffix style for output file names (default: L)
- L: Legacy (e.g., eplustbl.csv) C: Capital (e.g., eplusTable.csv) D: Dash (e.g., eplus-table.csv)
- version : bool, optional
- Display version information (default: False)
- verbose: str
- Set verbosity of runtime messages (default: v)
- v: verbose q: quiet
- ep_version: str
- EnergyPlus version, used to find install directory. Required if run() is called with an IDF file path rather than an IDF object.
str : status
CalledProcessError
- AttributeError
- If no ep_version parameter is passed when calling with an IDF file path rather than an IDF object.
-
save
(filename=None, lineendings=u'default', encoding=u'latin-1')¶ Save the IDF as a text file with the optional filename passed, or with the current idfname of the IDF.
- filename : str, optional
- Filepath to save the file. If None then use the IDF.idfname parameter. Also accepts a file handle.
- lineendings : str, optional
- Line endings to use in the saved file. Options are ‘default’, ‘windows’ and ‘unix’ the default is ‘default’ which uses the line endings for the current system.
- encoding : str, optional
- Encoding to use for the saved file. The default is ‘latin-1’ which is compatible with the EnergyPlus IDFEditor.
-
saveas
(filename, lineendings=u'default', encoding=u'latin-1')¶ Save the IDF as a text file with the filename passed.
- filename : str
- Filepath to to set the idfname attribute to and save the file as.
- lineendings : str, optional
- Line endings to use in the saved file. Options are ‘default’, ‘windows’ and ‘unix’ the default is ‘default’ which uses the line endings for the current system.
- encoding : str, optional
- Encoding to use for the saved file. The default is ‘latin-1’ which is compatible with the EnergyPlus IDFEditor.
-
savecopy
(filename, lineendings=u'default', encoding=u'latin-1')¶ Save a copy of the file with the filename passed.
- filename : str
- Filepath to save the file.
- lineendings : str, optional
- Line endings to use in the saved file. Options are ‘default’, ‘windows’ and ‘unix’ the default is ‘default’ which uses the line endings for the current system.
- encoding : str, optional
- Encoding to use for the saved file. The default is ‘latin-1’ which is compatible with the EnergyPlus IDFEditor.
-
scale
(factor, anchor=None)¶ Scale the IDF by a scaling factor.
Parameters: - factor – Factor to scale by.
- anchor – Point to scale around. Default is the centre of the the IDF’s bounding box.
-
set_default_constructions
()¶
-
set_wwr
(wwr=0.2, construction=None, force=False, wwr_map={})¶ Add strip windows to all external walls.
Different WWR can be applied to specific wall orientations using the wwr_map keyword arg. This map is a dict of wwr values, keyed by wall.azimuth, which overrides the default passed as wwr.
Parameters: - wwr – Window to wall ratio in the range 0.0 to 1.0.
- construction – Name of a window construction.
- force – True to remove all subsurfaces before setting the WWR.
- wwr_map – Mapping from wall orientation (azimuth) to WWR, e.g. {180: 0.25, 90: 0.2}.
-
setidd
(iddinfo, iddindex, block, idd_version)¶ Set the IDD to be used by eppy.
- iddinfo : list
- Comments and metadata about fields in the IDD.
- block : list
- Field names in the IDD.
-
setiddname
(iddname, testing=False)¶ Set the path to the EnergyPlus IDD for the version of EnergyPlus which is to be used by eppy.
- iddname : str
- Path to the IDD file.
- testing : bool
- Flag to use if running tests since we may want to ignore the IDDAlreadySetError.
IDDAlreadySetError
-
to_obj
(fname=None, mtllib=None)¶ Export an OBJ file representation of the IDF.
This can be used for viewing in tools which support the .obj format.
Parameters: - fname – A filename for the .obj file. If None we try to base it on IDF.idfname and change the filetype.
- mtllib – The name of a .mtl file to be referenced from the .obj file. If None, we use default.mtl.
-
translate
(vector)¶ Move the IDF in the direction given by a vector.
Parameters: vector – A vector to translate by.
-
translate_to_origin
()¶ Move an IDF close to the origin so that it can be viewed in SketchUp.
-
view_model
(test=False)¶ Show a zoomable, rotatable representation of the IDF.
-
geomeppy.recipes module¶
Recipes for making changes to EnergyPlus IDF files.
These are generally exposed and methods on the IDF object, e.g. set_default_constructions(idf)
can be called on an existing IDF object like myidf.set_default_constructions()
.
-
geomeppy.recipes.
rotate
(surfaces, angle)¶ Rotate all surfaces by an angle.
Parameters: - surfaces – A list of EpBunch objects or a mutable sequence.
- angle – An angle in degrees.
-
geomeppy.recipes.
rotate_coords
(coords, radians)¶ Rotate a set of coords by an angle in radians.
Parameters: - coords – A list of points.
- radians – The angle to rotate by.
Returns: List of Vector3D objects.
-
geomeppy.recipes.
scale
(surfaces, factor, axes='xy')¶ Scale all surfaces by a factor.
Parameters: - surfaces – A list of EpBunch objects.
- factor – Factor to scale the surfaces by.
- axes – Axes to scale on. Default ‘xy’.
-
geomeppy.recipes.
scale_coords
(coords, factor, axes)¶ Scale a set of coords by a factor.
Parameters: - coords – A list of points.
- factor – Factor to scale the surfaces by.
- axes – Axes to scale on.
Returns: A scaled polygon.
-
geomeppy.recipes.
set_default_construction
(surface)¶ Set default construction for a surface in the model.
Parameters: surface – A model surface.
-
geomeppy.recipes.
set_default_constructions
(idf)¶ Set default constructions for surfaces in the model.
Parameters: idf – The IDF object.
-
geomeppy.recipes.
set_wwr
(idf, wwr=0.2, construction=None, force=False, wwr_map={})¶ Set the window to wall ratio on all external walls.
Parameters: - idf – The IDF to edit.
- wwr – The window to wall ratio.
- construction – Name of a window construction.
- force – True to remove all subsurfaces before setting the WWR.
- wwr_map – Mapping from wall orientation (azimuth) to WWR, e.g. {180: 0.25, 90: 0.2}.
-
geomeppy.recipes.
translate
(surfaces, vector)¶ Translate all surfaces by a vector.
Parameters: - surfaces – A list of EpBunch objects.
- vector – Representation of a vector to translate by.
-
geomeppy.recipes.
translate_coords
(coords, vector)¶ Translate a set of coords by a direction vector.
Parameters: - coords – A list of points.
- vector – Representation of a vector to translate by.
Returns: List of translated vectors.
-
geomeppy.recipes.
translate_to_origin
(idf)¶ Move an IDF close to the origin so that it can be viewed in SketchUp.
Parameters: idf – The IDF to edit.
-
geomeppy.recipes.
window_vertices_given_wall
(wall, wwr)¶ Calculate window vertices given wall vertices and glazing ratio.
- :: For each axis:
- Translate the axis points so that they are centred around zero
- Either:
- Multiply the z dimension by the glazing ratio to shrink it vertically
- Multiply the x or y dimension by 0.995 to keep inside the surface
- Translate the axis points back to their original positions
Parameters: - wall – The wall to add a window on. We expect each wall to have four vertices.
- wwr – Window to wall ratio.
Returns: Window vertices bounding a vertical strip midway up the surface.
geomeppy.view_geometry module¶
Tool for visualising geometry.
-
geomeppy.view_geometry.
main
(fname=None, polygons=None)¶
-
geomeppy.view_geometry.
view_idf
(fname=None, idf_txt=None, test=False)¶ Display an IDF for inspection.
Parameters: - fname – Path to the IDF.
- idf_txt – The string representation of an IDF.
-
geomeppy.view_geometry.
view_polygons
(polygons)¶ Display a collection of polygons for inspection.
Parameters: polygons – A dict keyed by colour, containing Polygon3D objects to show in that colour.
geomeppy.builder module¶
Build IDF geometry from minimal inputs.
-
class
geomeppy.builder.
Block
(name, coordinates, height, num_stories=1, below_ground_stories=0, below_ground_storey_height=2.5)¶ Bases:
object
-
ceiling_heights
¶ Ceiling height for each storey in the block.
Returns: A list of ceiling heights.
-
ceilings
¶ Coordinates for each ceiling in the block.
Returns: Coordinates for all ceilings.
-
floor_heights
¶ Floor height for each storey in the block.
Returns: A list of floor heights.
-
floors
¶ Coordinates for each floor in the block.
Returns: Coordinates for all floors.
-
footprint
¶ Ground level outline of the block.
Returns: A 2D outline of the block.
-
lowest_floor_level
¶ Floor level of the lowest basement storey.
Returns: Lowest floor height.
-
roofs
¶ Coordinates for each roof of the block.
This returns a list with an entry for each floor for consistency with the other properties of the Block object, but should only have roof coordinates in the list in the final position.
Returns: Coordinates for all roofs.
-
storey_height
¶ Height of above ground stories.
Returns: Average storey height.
-
stories
¶ A list of dicts of the surfaces of each storey in the block.
Returns: list of dicts - Example dict format::
- {‘floors’: […],
- ‘ceilings’: […], ‘walls’: […], ‘roofs’: […], }
-
surfaces
¶ Coordinates for all the surfaces in the block.
Returns: Coordinates for all surfaces.
-
walls
¶ Coordinates for each wall in the block.
These are ordered as a list of lists, one for each storey.
Returns: Coordinates for all walls.
-
-
class
geomeppy.builder.
Zone
(name, surfaces)¶ Bases:
object
Represents a single zone for translation into an IDF.
geomeppy.extractor module¶
Module for extracting the geometry from an existing IDF.
There is the option to copy:
- thermal zone description and geometry
- surface construction elements
-
geomeppy.extractor.
copy_constructions
(source_idf, target_idf=None, fname=None)¶ Extract construction objects from a source IDF and add them to a target IDF or a new IDF.
Parameters: - source_idf – An IDF to source objects from.
- target_idf – An optional IDF to add objects to. If none is passed, a new IDF is returned.
- fname – A name for the new IDF created if no target IDF is passed in.
Returns: Either the target IDF or a new IDF containing the construction objects.
-
geomeppy.extractor.
copy_geometry
(source_idf, target_idf=None, fname=None)¶ Extract geometry objects from a source IDF and add them to a target IDF or a new IDF..
Parameters: - source_idf – An IDF to source objects from.
- target_idf – An optional IDF to add objects to. If none is passed, a new IDF is returned.
- fname – A name for the new IDF created if no target IDF is passed in.
Returns: Either the target IDF or a new IDF containing the geometry objects.
-
geomeppy.extractor.
copy_group
(source_idf, target_idf, group)¶ Extract a group of objects from a source IDF and add them to a target IDF.
Parameters: - source_idf – An IDF to source objects from.
- target_idf – An IDF to add objects to.
- group – The name of the group of objects to copy.
Returns: A new IDF containing the objects which belong to the group.
geomeppy.patches module¶
Monkey patches for changes to classes and functions in Eppy. These include fixes which have not yet made it to the released version of Eppy. These will be removed if/when they are added to Eppy.
-
class
geomeppy.patches.
EpBunch
(obj, objls, objidd, *args, **kwargs)¶ Bases:
eppy.bunch_subclass.EpBunch
Monkeypatched EpBunch to add the setcoords function.
-
setcoords
(poly, ggr=None)¶ Set the coordinates of a surface.
Parameters: - poly – Either a Polygon3D object of a list of (x,y,z) tuples.
- ggr – A GlobalGeometryRules IDF object. Defaults to None.
-
-
class
geomeppy.patches.
PatchedIDF
(idfname=None, epw=None)¶ Bases:
eppy.modeleditor.IDF
Monkey-patched IDF.
Patched to add read (to add additional functionality) and to fix copyidfobject and newidfobject.
-
copyidfobject
(idfobject)¶ Add an IDF object to the IDF.
This has been monkey-patched to add the return value.
Parameters: idfobject – The IDF object to copy. Usually from another IDF, or it can be used to copy within this IDF. Returns: EpBunch object.
-
newidfobject
(key, aname='', **kwargs)¶ Add a new idfobject to the model.
If you don’t specify a value for a field, the default value will be set.
For example
newidfobject("CONSTRUCTION") newidfobject("CONSTRUCTION", Name='Interior Ceiling_class', Outside_Layer='LW Concrete', Layer_2='soundmat')
Parameters: - key – The type of IDF object. This must be in ALL_CAPS.
- aname – This parameter is not used. It is left there for backward compatibility.
- kwargs – Keyword arguments in the format field=value used to set fields in the EnergyPlus object.
Returns: EpBunch object.
-
read
()¶ Read the IDF file and the IDD file.
If the IDD file had already been read, it will not be read again.
Populates the following data structures:
- idfobjects : list - model : list - idd_info : list - idd_index : dict
-
-
geomeppy.patches.
addthisbunch
(bunchdt, data, commdct, thisbunch, _idf)¶ Add an object to the IDF. Monkeypatched to return the object.
thisbunch usually comes from another idf file or it can be used to copy within the idf file.
Parameters: - bunchdt – Dict of lists of idf_MSequence objects in the IDF.
- data – Eplusdata object containing representions of IDF objects.
- commdct – Descriptions of IDF fields from the IDD.
- thisbunch – The object to add to the model.
- _idf – The IDF object. Not used either here or in Eppy but kept for consistency with Eppy.
Returns: The EpBunch object added.
-
geomeppy.patches.
idfreader1
(fname, iddfile, theidf, conv=True, commdct=None, block=None)¶ Read idf file and return bunches.
Parameters: - fname – Name of the IDF file to read.
- iddfile – Name of the IDD file to use to interpret the IDF.
- conv – If True, convert strings to floats and integers where marked in the IDD. Defaults to None.
- commdct – Descriptions of IDF fields from the IDD. Defaults to None.
- block – EnergyPlus field ID names of the IDF from the IDD. Defaults to None.
Returns: bunchdt Dict of lists of idf_MSequence objects in the IDF.
Returns: block EnergyPlus field ID names of the IDF from the IDD.
Returns data: Eplusdata object containing representions of IDF objects.
Returns: commdct List of names of IDF objects.
Returns: idd_index A pair of dicts used for fast lookups of names of groups of objects.
Returns: versiontuple Version of EnergyPlus from the IDD.
-
geomeppy.patches.
makeabunch
(commdct, obj, obj_i)¶ Make a bunch from the object.
Parameters: - commdct – Descriptions of IDF fields from the IDD.
- obj – List of field values in an object.
- obj_i – Index of the object in commdct.
Returns: EpBunch object.
-
geomeppy.patches.
makebunches
(data, commdct, theidf)¶ Make bunches with data.
Parameters: - data – Eplusdata object containing representions of IDF objects.
- commdct – Descriptions of IDF fields from the IDD.
- theidf – The IDF object.
Returns: Dict of lists of idf_MSequence objects in the IDF.
-
geomeppy.patches.
obj2bunch
(data, commdct, obj)¶ Make a new bunch object using the data object.
Parameters: - data – Eplusdata object containing representions of IDF objects.
- commdct – Descriptions of IDF fields from the IDD.
- obj – List of field values in an object.
Returns: EpBunch object.
-
geomeppy.patches.
readdatacommdct1
(idfname, iddfile='Energy+.idd', commdct=None, block=None)¶ Read the idf file.
This is patched so that the IDD index is not lost when reading a new IDF without reloading the modeleditor module.
Parameters: - idfname – Name of the IDF file to read.
- iddfile – Name of the IDD file to use to interpret the IDF.
- commdct – Descriptions of IDF fields from the IDD. Defaults to None.
- block – EnergyPlus field ID names of the IDF from the IDD. Defaults to None.
Returns: block EnergyPlus field ID names of the IDF from the IDD.
Returns data: Eplusdata object containing representions of IDF objects.
Returns: commdct List of names of IDF objects.
Returns: idd_index A pair of dicts used for fast lookups of names of groups of objects.
geomeppy.utilities module¶
Utilities for use in geomeppy.
-
geomeppy.utilities.
almostequal
(first, second, places=7)¶ Tests a range of types for near equality.