Editor

class epquery.Editor(idf_path, idd_path)

Bases: epquery.edit.geometry.Geometry, epquery.edit.extinterface.ExtInterface, epquery.edit.schedule.Schedule

Public API of EPQuery. This class inherits all methods defined in BasicEdit as well as in the Specialized classes.

Examples:

1) Select all zones having words first and floor in their names and then read get a list with full names of these zones:

>>> from epquery import Editor
>>> ed = Editor(path_to_idf, path_to_idd)
>>> mask = ed.mask('Zone', method='words', Name='first floor')
>>> names = ed.get_field(mask, 'Name')
>>> print(names)
['Living room first floor', 'Hall first floor', 'Bedroom first floor']
add_external_interface()

Adds external interface object IN PLACE. The object is added at the end of the current IDF. Returns the copy of this object.

Returns:A copy of external interface object
Return type:list(str)
add_object(obj, index=None)

Adds a single EnergyPlus object to the IDF. If index is None, the object is appended to the end of IDF. Otherwise it’s inserted at index (using list.insert()).

Parameters:obj (list(str)) – EnergyPlus object representation
Return type:None
add_objects(objects)

Appends IDF IN PLACE with EnergyPlus objects stored in objects. Unlike in add_object, index cannot be defined by the user. All objects are simply added to the end of IDF.

Parameters:objects (list(list(str))) – Objects to be added
Return type:None
apply(func, mask, inplace=True, args=[])

Applies function func to the passed mask.

If inplace is True, modifications are applied IN PLACE to objects selected in the mask as True. In addition the modified objects are returned by this function. If inplace is False, then no in place modifications are performed and the modified objects are just returned.

Parameters:
  • func (function) – Function to be applied
  • mask (list(bool)) – List of booleans, result of query_mask
  • inplace (bool) – Flag for in-place modification
  • args (list) – Any other parameters to be passed to func
Return type:

list(list(str))
comment(mask)

Puts ‘!=’ in the begining of each line of the selected objects. Edits IN PLACE and returns the commented objects.

Note

Currently, commented objects cannot be uncommented! It is because they cannot be located by query(), which searches for objects compliant with IDD. Also, all comment in IDF files are deleted during parsing.

Parameters:mask (list(bool)) – Objects to be commented out
Returns:Commented objects
Return type:list(list(str))
create_object(obj_type, inplace=False, **kwargs)

Creates and returns a new object of type obj_type with fields defined by kwargs. Fields not provided in kwargs are assumed to have no value. Spaces in the field names have to be replaced with underscores. Field names with special characters have to be provided without them, trying to match the name as close as possible, e.g. instead of ‘Output:Variable Index Key Name’ write ‘OutputVariable_Index_Key_Name’ (no semicolon, spaces to underscores).

Warning

The method may not work with expandable objects with unnamed fields.

Parameters:
  • obj_type (str) – Object type, e.g. ‘Schedule:File’
  • kwargs – Field names and values
  • inplace (bool) – If True, the object is appended to the IDF
Returns:

New object
Return type:

list(str)
definition_to_schedule_file(mask, file_name, column_number, inplace=True)

Creates Schedule:File objects for all objects selected in mask. Adds the schedules to the IDF if inplace is True. Returns the created schedule objects.

Compatible definition objects: Lights, People, ElectricEquipment, ZoneInfiltration:DesignFlowRate

Parameters:
  • mask (list(bool)) – Selected definition objects
  • file_name (str) – Schedule file name
  • column_number (int) – Column number
Returns:

A copy of the schedule objects
Return type:

list(list(str))
filter(mask, ignore_index=True)

Returns objects for which mask elements are True. Does not change the self-stored IDF.

Index can be ignored. By doing so the resulting list includes only matching objects (those where mask is True). Otherwise None is put where mask is False. It can be useful if the original object positions are to be preserved.

Parameters:
  • mask (list(bool)) – Mask
  • ignore_index (bool) – If False, not matching objects are stored as None
Returns:

List of objects
Return type:

list(list(str))
get_field(obj, field, flatten=True)

Generic function for retrieving field values from one or more objects defined by obj.

obj can be an index to an object, a list of indexes, a mask (list of bools), an actual object (list of str), or a list of objects (list of list of str). The returned field can be a single value or a list of values, depending on how many objects are in obj and on flatten. The parameter flatten contols the return type in case a single object is passed in obj. If it’s False, the return value is a single-element list (with a string). Otherwise it’s just a string.

field must exist in all objects passed/selected in obj.

Parameters:
  • obj (int or list(int) or list(bool) or list(str) or list(list(str))) – Object(s)
  • field (str) – Field name
Return type:

str or list(str)
get_index(obj_type, method=’exact’, flatten=True, **kwargs)

Returns index of the object. If more than one object is found, returns a list of indices. If flatten is False, then returns a list even if only one object is found (single-element list). Returns None if no object matches the criteria.

Parameters:
  • obj_type (str) – Object type
  • method (str) – Search method used in the query (‘exact’, ‘words’, ‘substring’)
  • kwargs – Field names and values
Return type:

int or list(int) or None
get_object_info(obj_type)

Returns object information based on the IDD file.

Parameters:obj_type (str) – Object type, e.g. ‘Zone’
Return type:str
get_surface_area(surface_name, surface_type=’BuildingSurface:Detailed’)

Returns the surface area.

Parameters:
  • surface_name (str) – Surface name
  • surface_type (str) – Surface type, default: BuildingSurface:Detailed
Returns:

List of vertices (list of tuples with x, y, z)
Return type:

list(tuple(float, float, float))
get_surface_centroid(surface_name, surface_type=’BuildingSurface:Detailed’, relative=False)

Returns the surface center point (centroid). The centroid can be in absolute or relative coordinates (relative to the first vertex).

Parameters:
  • surface_name (str) – Surface name
  • surface_type (str) – Surface type, default: BuildingSurface:Detailed
  • relative (bool) – If True the centroid is given in relative coordinates
Return type:

numpy.ndarray with 3 elements
get_surface_vertices(surface_name, surface_type=’BuildingSurface:Detailed’)

Returns a list of vertices defining the surface.

Parameters:
  • surface_name (str) – Surface name
  • surface_type (str) – Surface type, default: BuildingSurface:Detailed
Returns:

List of vertices (list of tuples with x, y, z)
Return type:

list(tuple(float, float, float))
mask(keyword, method=’exact’, inverse=False, **kwargs)

Same as query(), but returns a mask (list of bools). The mask represents a list of object matches. It can be then applied on IDF objects using apply_mask().

This method is useful if you need to:

  • select some objects and get their indexes
  • select some objects and print IDF without them (*inverse*=False)
Parameters:
  • keyword (str) – Unique keyword defining object type, e.g. ‘Zone’
  • method (str) – Search method (‘exact’, ‘substring’ or ‘words’)
  • inverse (bool) – If True, the mask is inversed
  • kwargs – Field types and required values
Return type:

list(bool)
output_to_interface(mask, key_values, inplace=True)

Returns external interface objects for Output:Variable.

Warning

Currently, the method only supports Output:Variable objects defined in IDF with key value = *. The argument key_values is used to expand the interface to all needed objects.

Parameters:
  • mask (list(bool)) – Mask with selected outputs
  • key_values (list(str)) – Key values from Output:Variable after expanding *
  • inplace (bool) – If True, original schedules are commented and new are added in place
Returns:

Schedules interface objects
Return type:

list(list(str))
query(keyword, method=’exact’, **kwargs)

Returns objects based on given criteria. Supports exact matches (*method*=’exact’), substring matches (*method*=’substring’), word matches (*method*=’words’).

All methods convert the letters to uppercase before comparing strings, so ‘woRd’==’WorD’ is True.

kwargs represents field descriptors from IDD (\field). If a descriptor contains space, replace it with underscore.

Warning

Currently field names with special characters (e.g. {}/) are not supported.

Parameters:
  • keyword (str) – Unique keyword defining object type, e.g. ‘Zone’
  • method (str) – Search method (‘exact’, ‘substring’ or ‘words’)
  • kwargs – Field types and required values
Return type:

list(list(str))

Example:

>>> ep = BasicEdit('path_to_IDF', 'path_to_IDD')
>>> objects = ep.query('Zone', method='words', Name='Zone1', Floor_Area=33.5)
remove(mask)

Removes selected objects IN PLACE. Returns removed objects.

Parameters:mask (list(bool)) – Selected objects
Returns:A copy of the deleted objects
Return type:list(list(str))
schedule_to_interface(mask, init_val=0, inplace=True)

Returns external interface objects for schedules. Adds the objects to the IDF if inplace is True.

Warning

The method does not check if the objects selected in the mask are valid schedules. It’s the user responsibility.

Parameters:
  • mask (list(bool)) – Mask with selected schedules
  • init_val (float) – Initial value of the schedule
  • inplace (bool) – If True, original schedules are commented and new are added in place
Returns:

Schedules interface objects
Return type:

list(list(str))
set_field(mask, **kwargs)

Sets a new value(s) to the field(s) of the selected objects IN PLACE. In addition returns the modified objects.

Warning

Does not work with expandable objects with unnamed fields.

Warning

Currently field names with special characters (e.g. {}/) are not supported.

Parameters:
  • mask (list(bool)) – Selected objects
  • kwargs – Field names and new values
Returns:

A copy of the modified objects
Return type:

list(list(str))
to_fmu(script, epw, name=None, directory=None)

Saves the model to IDF and exports to an FMU using EnergyPlusToFMU tool.

If name and directory are not given, the output files are saved in the current working directory with the following names: out.idf, out.fmu.

Parameters:
  • script (str) – Path to EnergyPlusToFMU.py
  • epw (str) – Path to EPW weather file
  • name (str) – IDF/FMU file name (without extension), optional
  • directory (str) – Output directory if other than CWD, optional
Returns:

Path to the generated FMU
Return type:

str
to_idf(path)

Prints IDF object to a file.

All fields are described with comments. Comments start with ‘!=’ to distinguish comments added by EPQuery from standard EnergyPlus comments (‘!’) or OpenStudio comments (‘!-‘).

Parameters:path (str) – Path to the output file
Return type:None