BasicEdit

class epquery.BasicEdit(idf_path, idd_path)

Bases: object

BasicEdit is used to query and manipulate EnergyPlus model stored in IDF file. It contains only basic manipulation methods in its API (object type-agnostic). Look into the Editor class for more specialized methods.

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)

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

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)

match_fields(obj_type, fields)

Tries to match field names in fields with actual field names in IDD. In some cases the user cannot use exact field names as arguments to methods, because of special characters. This method returns a dictionary mapping user field names to IDD field names (user names: IDD names). If a field name couldn’t be matched, it’s mapped to None.

Note

All strings are converted to upper case, both in user field names and IDD field names.

Parameters:

• obj_type (str) – Object type, e.g. ‘Zone’
• fields (list(str)) – List of field names

Returns:

dict(str: 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.

Note

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).

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

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, avoid dashes), 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