trnslator.idfclass.IDF¶

class trnslator.idfclass.IDF(*args, **kwargs)[source]¶

Wrapper over the geomeppy.IDF class and subsequently the eppy.modeleditor.IDF class

Parameters

*args –
**kwargs –

classmethod setiddname(iddname, testing=False)[source]¶

Set the path to the EnergyPlus IDD for the version of EnergyPlus which is to be used by eppy.

Parameters

iddname (str) – Path to the IDD file.
testing –

property area_conditioned¶: Returns the total conditioned area of a building (taking into account zone multipliers

property partition_ratio¶: The number of lineal meters of partitions (Floor to ceiling) present in average in the building floor plan by m2.

wwr(azimuth_threshold=10, round_to=None)[source]¶

Returns the Window-to-Wall Ratio by major orientation for the IDF model. Optionally round up the WWR value to nearest value (eg.: nearest 10).

Parameters

azimuth_threshold (int) – Defines the incremental major orientation azimuth angle. Due to possible rounding errors, some surface azimuth can be rounded to values different than the main directions (eg.: 89 degrees instead of 90 degrees). Defaults to increments of 10 degrees.
round_to (float) – Optionally round the WWR value to nearest value (eg.: nearest 10). If None, this is ignored and the float is returned.

Returns

A DataFrame with the total wall area, total window area and WWR for each main orientation of the building.

Return type

(pd.DataFrame)

space_heating_profile(units='kWh', energy_out_variable_name=None, name='Space Heating', EnergySeries_kwds={})[source]¶

Parameters

units (str) – Units to convert the energy profile to. Will detect the units of the EnergyPlus results.
energy_out_variable_name (list-like) – a list of EnergyPlus Variable names.
name (str) – Name given to the EnergySeries.
EnergySeries_kwds (dict, optional) – keywords passed to EnergySeries.from_sqlite()

Returns

EnergySeries

service_water_heating_profile(units='kWh', energy_out_variable_name=None, name='Space Heating', EnergySeries_kwds={})[source]¶

Parameters

units (str) – Units to convert the energy profile to. Will detect the units of the EnergyPlus results.
energy_out_variable_name (list-like) – a list of EnergyPlus Variable names.
name (str) – Name given to the EnergySeries.
EnergySeries_kwds (dict, optional) – keywords passed to EnergySeries.from_sqlite()

Returns

EnergySeries

space_cooling_profile(units='kWh', energy_out_variable_name=None, name='Space Cooling', EnergySeries_kwds={})[source]¶

Parameters

units (str) – Units to convert the energy profile to. Will detect the units of the EnergyPlus results.
energy_out_variable_name (list-like) – a list of EnergyPlus
name (str) – Name given to the EnergySeries.
EnergySeries_kwds (dict, optional) – keywords passed to EnergySeries.from_sqlite()

Returns

EnergySeries

custom_profile(energy_out_variable_name, name, units='kWh', prep_outputs=None, EnergySeries_kwds={})[source]¶

Parameters

energy_out_variable_name (list-like) – a list of EnergyPlus
name (str) – Name given to the EnergySeries.
units (str) – Units to convert the energy profile to. Will detect the units of the EnergyPlus results.
prep_outputs –
EnergySeries_kwds (dict, optional) – keywords passed to EnergySeries.from_sqlite()

Returns

EnergySeries

run_eplus(**kwargs)[source]¶

wrapper around the trnslator.idfclass.run_eplus() method.

If weather file is defined in the IDF object, then this field is optional. By default, will load the sql in self.sql.

Parameters: kwargs –
Returns: The output report or the sql file loaded as a dict of DataFrames.

add_object(ep_object, save=True, **kwargs)[source]¶

Add a new object to an idf file. The function will test if the object exists to prevent duplicates. By default, the idf with the new object is saved to disk (save=True)

Parameters

ep_object (str) – the object name to add, eg. ‘OUTPUT:METER’ (Must be in all_caps).
save (bool) – Save the IDF as a text file with the current idfname of the IDF.
**kwargs – keyword arguments to pass to other functions.

Returns

the object

Return type

EpBunch

get_schedule_type_limits_data_by_name(schedule_limit_name)[source]¶

Returns the data for a particular ‘ScheduleTypeLimits’ object

Parameters: schedule_limit_name –

get_schedule_epbunch(name, sch_type=None)[source]¶

Returns the epbunch of a particular schedule name. If the schedule type is know, retreives it quicker.

Parameters

name (str) – The name of the schedule to retreive in the IDF file.
sch_type (str) – The schedule type, e.g.: “SCHEDULE:YEAR”.

get_all_schedules(yearly_only=False)[source]¶

Returns all schedule ep_objects in a dict with their name as a key

Parameters

yearly_only (bool) – If True, return only yearly schedules

Returns

the schedules with their: name as a key

Return type

(dict of eppy.bunch_subclass.EpBunch)

get_used_schedules(yearly_only=False)[source]¶

Returns all used schedules

Parameters: yearly_only (bool) – If True, return only yearly schedules
Returns: the schedules names
Return type: (list)

property day_of_week_for_start_day¶: Get day of week for start day for the first found RUNPERIOD

building_name(use_idfname=False)[source]¶

Parameters: use_idfname –

rename(objkey, objname, newname)[source]¶

rename all the references to this objname

Function comes from eppy.modeleditor and was modify to compare the name to rename as a lower string (see idfobject[idfobject.objls[findex]].lower() == objname.lower())

Parameters

objkey (EpBunch) – EpBunch we want to rename and rename all the occurrences where this object is in the IDF file
objname (str) – The name of the EpBunch to rename
newname (str) – New name used to rename the EpBunch

Returns

The IDF objects renameds

Return type

theobject (EpBunch)

add_block(*args: Any, **kwargs: Any) → None [source]¶

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: Any, **kwargs: Any) → None [source]¶

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: geomeppy.builder.Zone) → None [source]¶

Add a zone to the IDF.

Parameters: zone – A Zone object holding details about the zone.

bounding_box() → geomeppy.geom.polygons.Polygon2D[source]¶

Calculate the site bounding box.

Returns: A polygon of the bounding box.

property centroid¶

Calculate the centroid of the site bounding box.

Returns: The centroid of the site bounding box.

copyidfobject(idfobject: geomeppy.patches.EpBunch) → geomeppy.patches.EpBunch¶

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)[source]¶

Get the index of the first extensible item.

Only for internal use. # TODO : hide this

Parameters

key (str) – The type of IDF object. This must be in ALL_CAPS.
name (str) – The name of the object to fetch.

Returns

Return type

int

getiddgroupdict()[source]¶

Return a idd group dictionary sample: {‘Plant-Condenser Loops’: [‘PlantLoop’, ‘CondenserLoop’],

‘Compliance Objects’: [‘Compliance:Building’], ‘Controllers’: [‘Controller:WaterCoil’,

‘Controller:OutdoorAir’, ‘Controller:MechanicalVentilation’, ‘AirLoopHVAC:ControllerList’],

…}

Returns
Return type: dict

classmethod getiddname()[source]¶

Get the name of the current IDD used by eppy.

Returns
Return type: str

getobject(key, name)[source]¶

Fetch an IDF object given key and name.

Parameters

key (str) – The type of IDF object. This must be in ALL_CAPS.
name (str) – The name of the object to fetch.

Returns

Return type

EpBunch object.

getshadingsurfaces(surface_type: str = '') → Union[List[eppy.bunch_subclass.EpBunch], eppy.idf_msequence.Idf_MSequence][source]¶

Return all subsurfaces in the IDF.

Parameters: surface_type – Type of surface to get. Defaults to all.
Returns: IDF surfaces.

getsubsurfaces(surface_type: str = '') → Union[List[eppy.bunch_subclass.EpBunch], eppy.idf_msequence.Idf_MSequence][source]¶

Return all subsurfaces in the IDF.

Parameters: surface_type – Type of surface to get. Defaults to all.
Returns: IDF surfaces.

getsurfaces(surface_type: str = '') → Union[List[eppy.bunch_subclass.EpBunch], eppy.idf_msequence.Idf_MSequence][source]¶

Return all surfaces in the IDF.

Parameters: surface_type – Type of surface to get. Defaults to all.
Returns: IDF surfaces.

idfstr()[source]¶

String representation of the IDF.

Returns
Return type: str

initnew(fname)[source]¶

Use the current IDD and create a new empty IDF. If the IDD has not yet been initialised then this is done first.

Parameters: fname (str, optional) – Path to an IDF. This does not need to be set at this point.

initread(idfname)[source]¶

Use the current IDD and read an IDF from file. If the IDD has not yet been initialised then this is done first.

Parameters: idf_name (str) – Path to an IDF file.

initreadtxt(idftxt)[source]¶

Use the current IDD and read an IDF from text data. If the IDD has not yet been initialised then this is done first.

Parameters: idftxt (str) – Text representing an IDF file.

intersect() → None [source]¶: Intersect all surfaces in the IDF.

intersect_match() → None [source]¶: Intersect all surfaces in the IDF, then set boundary conditions.

match() → None [source]¶: Set boundary conditions for all surfaces in the IDF.

new(fname=None)[source]¶

Create a blank new idf file. Filename is optional.

Parameters: fname (str, optional) – Path to an IDF. This does not need to be set at this point.

newidfobject(key: str, aname: str = '', **kwargs: Any) → geomeppy.patches.EpBunch¶

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)[source]¶

Pop an IDF object from the IDF.

Parameters

key (str) – The type of IDF object. This must be in ALL_CAPS.
index (int) – The index of the object to pop.

Returns

Return type

EpBunch object.

printidf()[source]¶: 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)[source]¶

Remove extensible items in the object of key and name.

Only for internal use. # TODO : hide this

Parameters

key (str) – The type of IDF object. This must be in ALL_CAPS.
name (str) – The name of the object to fetch.

Returns

Return type

EpBunch object

removeidfobject(idfobject)[source]¶

Remove an IDF object from the IDF.

Parameters: idfobject (EpBunch object) – The IDF object to remove.

rotate(angle: float, anchor: Optional[Union[geomeppy.geom.vectors.Vector2D, geomeppy.geom.vectors.Vector3D]] = None) → None [source]¶

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)[source]¶

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.

idfstr

Full or relative path to the IDF file to be run, or an IDF object.

weatherstr

Full or relative path to the weather file.

output_directorystr, optional

Full or relative path to an output directory (default: ‘run_outputs)

annualbool, optional

If True then force annual simulation (default: False)

design_daybool, optional

Force design-day-only simulation (default: False)

iddstr, optional

Input data dictionary (default: Energy+.idd in EnergyPlus directory)

epmacrostr, optional

Run EPMacro prior to simulation (default: False).

expandobjectsbool, optional

Run ExpandObjects prior to simulation (default: False)

readvarsbool, optional

Run ReadVarsESO after simulation (default: False)

output_prefixstr, optional

Prefix for output file names (default: eplus)

output_suffixstr, 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)

versionbool, 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')[source]¶

Save the IDF as a text file with the optional filename passed, or with the current idfname of the IDF.

Parameters

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')[source]¶

Save the IDF as a text file with the filename passed.

Parameters

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')[source]¶

Save a copy of the file with the filename passed.

Parameters

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: float, anchor: Optional[Union[geomeppy.geom.vectors.Vector2D, geomeppy.geom.vectors.Vector3D]] = None, axes: str = 'xy') → None [source]¶

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_wwr(wwr: Optional[float] = 0.2, construction: Optional[str] = None, force: Optional[bool] = False, wwr_map: Optional[dict] = {}, orientation: Optional[str] = None) → None [source]¶

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)[source]¶

Set the IDD to be used by eppy.

Parameters

iddinfo (list) – Comments and metadata about fields in the IDD.
block (list) – Field names in the IDD.

to_obj(fname: Optional[str] = None, mtllib: Optional[str] = None) → None [source]¶

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: geomeppy.geom.vectors.Vector2D) → None [source]¶

Move the IDF in the direction given by a vector.

Parameters: vector – A vector to translate by.

translate_to_origin() → None [source]¶: Move an IDF close to the origin so that it can be viewed in SketchUp.

view_model(test: Optional[bool] = False) → None [source]¶: Show a zoomable, rotatable representation of the IDF.