honeybee_doe2.util module¶
Various utilities used throughout the package.
- honeybee_doe2.util.calculate_value_with_global_parameter(global_parameters, input_expr)[source]¶
Evaluate an INP Global Parameter expression with #PA(”…”).
Note that this method will only return a float value if the expression is strictly an inline math expression.
- Parameters:
global_parameters – A dict with parameter names as keys and floats as values.
input_expr – A string of an expression to be evaluated. See an example below.
- Returns:
Evaluated float result or None is not an inline math expression.
'{0.66 * #PA("...")}' or '{0.66 * #PA("...") + #PA("...")}
- honeybee_doe2.util.child_objects_from_parent(cmd_dict, parent_name, parent_command, child_command)[source]¶
Return all child_command objects between a parent’s line and its next sibling.
This requires the full dict of parsed INP blocks and one parent instance.
- Parameters:
cmd_dict – Command dictionary containing all DOE2 objects.
parent_name – Name of the parent from the object dict.
parent_command – The command name of the parent.
child_command – The command of the child objects to return.
- Returns:
A dictionary with u_name strings for keys and dictionaries for values. This maps each child’s u_name to its data dict whose __line__ is between the two parent lines.
- honeybee_doe2.util.clean_inp_file_contents(inp_file_contents)[source]¶
Clean an INP file’s text.
This includes removing comment lines and resolving inline #PA() parameter expressions.
- Parameters:
inp_file_contents – Complete text of an INP file.
- Returns:
The cleaned text, ready for further parsing.
- honeybee_doe2.util.doe2_object_blocks(inp_file_contents)[source]¶
Get the object blocks of a DOE-2 INP file.
- Parameters:
inp_file_contents – A string of the INP file to parse.
- Returns:
A list of strings, where each string is a complete block of the INP file.
- honeybee_doe2.util.find_user_lib_file()[source]¶
Find the user’s eQUEST library file (eQ_Lib.dat).
This searches common eQuest installation paths in the users Documents folder, including OneDrive documents.
TODO: Consider this an optional input for Model Editor? :returns: Path to eQ_Lib.dat if found, None otherwise.
- honeybee_doe2.util.generate_inp_string(u_name, command, keywords, values)[source]¶
Get an INP string representation of a DOE-2 object.
This method is written in a generic way so that it can describe practically any element of the INP Building Description Language (BDL).
- Parameters:
u_name – Text for the unique, user-specified name of the object being created. This must be 32 characters or less and not contain special or non-ASCII characters. The clean_doe2_string method may be used to convert strings to a format that is acceptable here. For example, a U-Name of a space might be “Floor2W ClosedOffice5”.
command – Text indicating the type of instruction that the DOE-2 object executes. Commands are typically in capital letters and examples include POLYGON, FLOOR, SPACE, EXTERIOR-WALL, WINDOW, CONSTRUCTION, etc.
keywords – A list of text with the same length as the values that denote the attributes of the DOE-2 object.
values – A list of values with the same length as the keywords that describe the values of the attributes for the object.
- Returns:
inp_str – A DOE-2 INP string representing a single object.
- honeybee_doe2.util.generate_inp_string_list_format(u_name, command, keywords, values)[source]¶
Get an INP string of a DOE-2 object with nicer formatting for list values.
This method will process any values that are a list or tuple and format them such that they are indented and more readable. This method is written in a generic way so that it can describe practically any element of the INP Building Description Language (BDL).
- Parameters:
u_name – Text for the unique, user-specified name of the object being created. This must be 32 characters or less and not contain special or non-ASCII characters. The clean_doe2_string method may be used to convert strings to a format that is acceptable here. For example, a U-Name of a space might be “Floor2W ClosedOffice5”.
command – Text indicating the type of instruction that the DOE-2 object executes. Commands are typically in capital letters and examples include POLYGON, FLOOR, SPACE, EXTERIOR-WALL, WINDOW, CONSTRUCTION, etc.
keywords – A list of text with the same length as the values that denote the attributes of the DOE-2 object.
values – A list of values with the same length as the keywords that describe the values of the attributes for the object. The items in this list can be list themselves, in which case they will be translated with nice indented formatting.
- Returns:
inp_str – A DOE-2 INP string representing a single object.
- honeybee_doe2.util.header_comment_major(header_text)[source]¶
Create a header given header_text, which can help organize the INP file contents.
- honeybee_doe2.util.header_comment_minor(header_text)[source]¶
Create a header given header_text, which can help organize the INP file contents.
- honeybee_doe2.util.inp_path_from_folder(folder_path=None, filename=None)[source]¶
Get the path to an INP file from a specified folder or the current directory.
- Parameters:
folder_path – Path to the folder containing the INP file. If None, the current directory will be used.
filename – Name of the INP file. If None, the first file found in the folder with an .inp extension will be returned
- Returns:
Path to the INP file.
- Raises:
FileNotFoundError – If no INP file is found.
- honeybee_doe2.util.parse_inp_string(inp_string)[source]¶
Parse an INP string of a single DOE-2 object into a list of values.
Note that this method is only equipped to parse DOE-2 test strings that originate from eQuest or from this package. It has not yet been generalized to parse all formats of text formats that can appear in a DOE-2 file.
- Parameters:
inp_string – An INP string for a single DOE-2 object.
- Returns:
A tuple with four elements.
u_name: Text for the unique name of the object. Will be None if the object is a Parameter. DOE-2 object defaults will return a tuple (command, command_type). For example, ZONE default u_name would be: (‘ZONE’, ‘CONDITIONED’)
- command: Text for the type of instruction that the DOE-2 object
executes.
- keywords: A list of text with the same length as the values that
denote the attributes of the DOE-2 object.
- values: A list of values with the same length as the keywords that
describe the values of the attributes for the object.
- honeybee_doe2.util.parse_lib_string(lib_string, command_type)[source]¶
Parse a library entry string from eQ_Lib.dat into a tuple of values.
Library entries have a different format than standard INP strings: - First line: $LIBRARY-ENTRY <u_name> <COMMAND> <category> - Comment lines starting with $ - Keyword-value pairs with indentation - Ends with ..
- Parameters:
lib_string – A string for a single library entry block.
command_type – The DOE-2 command type (ie ‘SCHEDULE-PD’, ‘WEEK-SCHEDULE-PD’, ‘DAY-SCHEDULE-PD’).
- Returns:
A tuple with three elements.
u_name: Unique name of the library entry.
keywords: A list of text with the same length as the values that denote the attributes of the object.
values: A list of values with the same length as the keywords that describe the values of the attributes for the object.
- honeybee_doe2.util.resolve_defaults(obj_attrs, defaults, keys)[source]¶
Resolve attribute values for a DOE-2 command by merging its own attributes with SET-DEFAULT fallback values.
The goal is for this to be generic and works for any command type (SPACE, ZONE, SYSTEM, etc.).
- Parameters:
obj_attrs – The parsed attribute dict for the specific object instance (ie one SPACE or one ZONE from command_dict_from_inp)
defaults – The merged DEFAULTS dict for this command type. For switch- based defaults, values will be resolved using the object’s C-ACTIVITY-DESC attribute. Pass an empty dict if no defaults exist.
keys – An iterable of INP keyword strings to resolve (e.g. SPACE_KEYS or ZONE_KEYS).
- Returns:
A dict mapping each key to its resolved value (string or float). Keys that cannot be resolved from either source are ignored
- honeybee_doe2.util.resolve_switch_value(switch_text, case_key)[source]¶
Resolve a DOE-2 switch statement to the value for a given case key.
- Parameters:
switch_text – The full switch block string
example – {switch(#L(“C-ACTIVITY-DESC”)) case “npln”: 215.198 case “m5m2”: 1075.99 default: no_default endswitch}
case_key – The case label to match
above (example in) – ‘npln’
- Returns:
The resolved value as a string, or None if no matching case is found. For
#SI(...)or#SIT(...)schedule references, the schedule name is extracted.