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.
  • zoning – The zoning pattern of the block. Default : by_storey
  • perim_depth – Depth of the perimeter zones if the core/perim zoning pattern is requested. Default : 3.0.
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

classmethod 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='')

Return all subsurfaces in the IDF.

Parameters:surface_type – Type of surface to get. Defaults to all.
Returns:IDF surfaces.
getsubsurfaces(surface_type='')

Return all subsurfaces in the IDF.

Parameters:surface_type – Type of surface to get. Defaults to all.
Returns:IDF surfaces.
getsurfaces(surface_type='')

Return all surfaces in the IDF.

Parameters:surface_type – 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=’‘, annual=False, design_day=False, idd=None, epmacro=False, expandobjects=False, readvars=False, output_prefix=None, output_suffix=None, version=False, verbose=’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='default', encoding='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='default', encoding='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='default', encoding='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, axes='xy')

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.
  • axes – Axes to scale on. Default ‘xy’.
set_default_constructions()
set_wwr(wwr=0.2, construction=None, force=False, wwr_map={}, orientation=None)

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.

They can also be applied to walls oriented to a compass point, e.g. north, which will apply to walls which have an azimuth within 45 degrees of due north.

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}.
  • orientation – One of “north”, “east”, “south”, “west”. Walls within 45 degrees will be affected.
classmethod 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.
classmethod 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)

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.
geomeppy.recipes.scale_coords(coords, factor, axes='xy')

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=None, orientation=None)

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}.
  • orientation – One of “north”, “east”, “south”, “west”. Walls within 45 degrees will be affected.
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:
  1. Translate the axis points so that they are centred around zero
  2. Either:
    1. Multiply the z dimension by the glazing ratio to shrink it vertically
    2. Multiply the x or y dimension by 0.995 to keep inside the surface
  3. 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, idf=None)

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, zoning='by_storey', perim_depth=3.0)

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='new.idf')

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. Default: “new.idf”.
Returns:

Either the target IDF or a new IDF containing the construction objects.

geomeppy.extractor.copy_geometry(source_idf, target_idf=None, fname='new.idf')

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. Default: “new.idf”.
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.