objectives

Objectives generate the output of evaluators.

For energyplus, outputs are calculated by reading the simulation output files, using either MeterReaders or VariableReaders.

The optimisation direction (minimize or maximize) and if the objectives are used to put constraints on a solution (such as electricity use being less than a certain amount) are both specified by arguments to the Problem containing the objectives.

If the model used does not generate the needed output, the objective will modify the model to add the corresponding output. For example, if a building does not include an Ouptut:Meter object for Electricity:Facility, one will be added if the corresponding MeterReader is used with that building.

class objectives.EPReader(class_name, frequency: str = None, func=<function sum_values>, name='')[source]
add_objective(building)[source]

Creates and adds the meter needed by this objective to the building.

Parameters:building – the building to modify
Returns:None
get_objective(building)[source]

Retrieves output object in the building corresponding to this Objective.

Parameters:building – The building to search for the object.
Returns:The part of the building’s data corresponding to this Objective. The return type varies between json and idf buildings
setup(building) → None[source]

Prepares an idf so that it’s output can be read by this meter.

Parameters:building – the idf to modify
Returns:None
class objectives.EPResults(name: str, frequency: str, units: str, data: pandas.core.frame.DataFrame)[source]

Represents the information about a Meter or Variable read from a .eso file.

class objectives.MeterReader(key_name: str, class_name: str = 'Output:Meter', frequency: str = None, func: Callable = <function sum_values>, name: str = '')[source]
Parameters:
  • key_name – What to measure (e.g. Electricity:Facility)
  • class_name – The kind of meter to use (e.g. Output:Meter)
  • frequency – the reporting frequency of the meter. (e.g. Timestep, Monthly)
  • func – a function used to aggregate the results read from the file.
  • name – the name of the output column corresponding to this objective
class objectives.VariableReader(key_value, variable_name='*', class_name='Output:Variable', frequency: str = None, func: Callable = <function sum_values>, name='')[source]

Reads the values of Variables from the .eso file Energyplus docs: https://bigladdersoftware.com/epx/docs/8-9/input-output-reference/input-for-output.html#outputvariable

Parameters:
  • key_value – The designation or location where to read the variable (e.g. Zone name, or Wall name, or * for all matches with variable_name available).
  • variable_name – The variable name you want to measure (e.g. “Site Outdoor Air Drybulb”).
  • frequency – The reporting frequency of the variable.
  • func – A function used to aggregate the results read from the file.
  • name – The name of the output column corresponding to this objective.
objectives.clear_outputs(building, outputs: Union[str, List[str]] = 'all') → None[source]

Disable certain types of output that appear in the .eso file.

Parameters:
  • building – the building to modify
  • outputs – Can be the class_name of the output to clear, a shortcut for different types of output, or a list that combines the above.
Returns:

None

objectives.get_eso_version(eso: Union[os.PathLike, str]) → packaging.version.Version[source]

Gets the version of energyplus used to generate an eso file.

Parameters:eso – the path to the eso file
Returns:the version of energyplus used to generate the eso file.
objectives.read_eso(out_dir: Union[os.PathLike, str] = None, file_name='eplusout.eso', version=None) → Dict[Tuple[str, str], objectives.EPResults][source]

Retrieve information from an Energy-Plus simulation, with outputs in out_dir

Parameters:
  • out_dir – the directory that contains the output files
  • file_name – the name of the output file to read from. Should be a .eso file.
  • version – Deprecated argument. Do not use.
Returns:

a dictionary with keys of the form {(MeterName, Reporting_Frequency or None):EPResults dataclass}

objectives.sum_values(results: objectives.EPResults) → float[source]

Returns the sum over the Value column from some results

Parameters:results – the results object to sum over
Returns:the sum of the first value for each entry in the collection.
objectives.time_series_values(results: objectives.EPResults)[source]

Returns the entire value column from the results.

Parameters:results – the results object
Returns:the values from the results object.