dragonfly_energy.measure module

Mange OpenStudio measures that can be mapped to different buildings in a model.

class dragonfly_energy.measure.MapperMeasure(folder)

Bases: Measure

An OpenStudio measure that can be mapped to different buildings in a model.

Parameters:

folder – Path to the folder in which the measure exists. This folder must contain a measure.rb and a measure.xml file. Other files are optional.

Properties:

• folder

• metadata_file

• program_file

• resources_folder

• identifier

• display_name

• description

• type

• arguments

ToString()

classmethod from_dict(data, folder='.')

Initialize a MapperMeasure from a dictionary.

Parameters:

• data – A dictionary in the format below.

• folder – Path to a destination folder to save the measure files. (Default ‘.’)

{
"type": "MapperMeasure",
"identifier": string,  # Measure identifier
"xml_data": string,  # XML file data as string
"rb_data": string,  # Ruby file data as string
"resource_data": {},  # Dictionary of strings for any resource ruby files
"argument_values": [],  # List of values for each of the measure arguments
}

static sort_measures(measures)

Sort measures according to the order they will be executed by OpenStudio CLI.

ModelMeasures will be first, followed by EnergyPlusMeasures, followed by ReportingMeasures.

to_dict()

Convert MapperMeasure to a dictionary.

to_osw_dict(full_path=False)

Get a Python dictionary that can be written to an OSW JSON.

Specifically, this dictionary can be appended to the “steps” key of the OpenStudio Workflow (.osw) JSON dictionary in order to include the measure in the workflow.

Note that this method does not perform any checks to validate that the Measure has all required values and only arguments with values will be included in the dictionary. Validation should be done separately with the validate method.

Parameters:

full_path – Boolean to note whether the full path to the measure should be written under the ‘measure_dir_name’ key or just the measure base name. (Default: False)

validate(raise_exception=True)

Check if all required arguments have values needed for simulation.

Parameters:

raise_exception – If True, an exception will be raised if there’s a required argument and there is no value. Otherwise, False will be returned for this case and True will be returned if all is correct.

property arguments

Get a tuple of MeasureArgument objects for the measure input arguments.

The value property of these objects can be set in order to specify input arguments for the measure.

property description

Get text for describing what the measure does.

property display_name

Get text for the human-readable display name of the measure.

This is called the “display_name” in the measure.xml file.

property folder

Get the path to the folder in which the measure exists.

property identifier

Get text for the identifier of the measure.

This is also called the “name” in the measure.xml file.

property metadata_file

Get the path to the measure.xml file within the measure folder.

This file contains metadata about the measure and this is where many of the properties on this object originate from.

property program_file

Get the path to the measure.rb file within the measure folder.

This file contains the Ruby code that is executed whenever the measure is run by the OpenStudio CLI.

property resources_folder

Get the path to the folder for resource Ruby file if it exists.

This folder contains Ruby file dependencies that are used in the program_file.

property type

Get text for the type of measure this is. This is always one of 3 values.

• ModelMeasure - for measures that operate on the .osm model.

• EnergyPlusMeasure - for measures that operate on the .idf file.

• ReportingMeasure - for measures that run after the simulation is finished.

class dragonfly_energy.measure.MapperMeasureArgument(xml_element)

Bases: MeasureArgument

Object representing a single mapper measure argument.

Parameters:

xml_element – A Python XML Element object taken from the <arguments> section of the measure.xml file.

Properties:

• identifier

• display_name

• value

• default_value

• type

• type_text

• required

• description

• model_dependent

• valid_choices

ToString()

validate(raise_exception=True)

If this argument is required, check that it has a value.

If this argument is not required, this method will always return True.

Parameters:

raise_exception – If True, an exception will be raised if this argument is required and there is no value. Otherwise, False will be returned for this case and True will be returned if all is correct.

PYTHON_TYPES = {'Boolean': <class 'bool'>, 'Choice': <class 'str'>, 'Double': <class 'float'>, 'Integer': <class 'int'>, 'String': <class 'str'>}

property default_value

Get the default value for the argument.

This may be None if no default value has been included.

property description

Get text for describing what the measure does if it exists.

property display_name

Get text for the human-readable display name of the argument.

This is called the “display_name” in the measure.xml file.

property identifier

Get text for the identifier of the argument.

This is also called the “name” in the measure.xml file.

property model_dependent

Get a boolean for whether this argument is dependent on the model.

property required

Get a boolean for whether this argument is required to run the measure.

property type

Get the Python type of argument this is (eg. float, str, int).

property type_text

Get a text string for the argument type as it appears in the measure.xml.

(eg. ‘Double’, ‘String’, ‘Boolean’).

property valid_choices

Get a list of text for valid inputs for choice arguments.

This will be None if the argument type is not Choice.

property value

Get or set the value or list of values for the argument.

When using a list, the length of it must match the number of buildings in the dragonfly Model and each value corresponds to a building under the Model.buildings property.

If not set, this will be equal to the default_value and, if no default value is included for this argument, it will be None.