Runtime API

class runtime.Runtime(api: <ctypes.LibraryLoader object at 0x7fdff3d3bb70>)

Bases: object

This API class enables a client to hook into EnergyPlus at runtime and sense/actuate data in a running simulation. The pattern is quite simple: create a callback function in Python, and register it with one of the registration methods on this class to allow the callback to be called at a specific point in the simulation. Inside the callback function, the client can get sensor values and set actuator values using the DataTransfer API methods, and also look up values and perform calculations using EnergyPlus internal methods via the Functional API methods.

callback_after_component_get_input(f: function) → None

This function allows a client to register a function to be called back by EnergyPlus at the end of component get input processes.

Parameters

f – A python function which takes no arguments and returns nothing

Returns

Nothing

callback_after_new_environment_warmup_complete(f: function) → None

This function allows a client to register a function to be called back by EnergyPlus at the warmup of each environment.

Parameters

f – A python function which takes no arguments and returns nothing

Returns

Nothing

callback_after_predictor_after_hvac_managers(f: function) → None

This function allows a client to register a function to be called back by EnergyPlus at the end of the predictor step after HVAC managers.

Parameters

f – A python function which takes no arguments and returns nothing

Returns

Nothing

callback_after_predictor_before_hvac_managers(f: function) → None

This function allows a client to register a function to be called back by EnergyPlus at the end of the predictor step but before HVAC managers.

Parameters

f – A python function which takes no arguments and returns nothing

Returns

Nothing

callback_begin_new_environment(f: function) → None

This function allows a client to register a function to be called back by EnergyPlus at the beginning of each environment.

Parameters

f – A python function which takes no arguments and returns nothing

Returns

Nothing

callback_begin_system_timestep_before_predictor(f: function) → None

This function allows a client to register a function to be called back by EnergyPlus at the beginning of system time step .

Parameters

f – A python function which takes no arguments and returns nothing

Returns

Nothing

callback_begin_zone_timestep_after_init_heat_balance(f: function) → None

This function allows a client to register a function to be called back by EnergyPlus at the beginning of the zone time step after init heat balance.

Parameters

f – A python function which takes no arguments and returns nothing

Returns

Nothing

callback_begin_zone_timestep_before_init_heat_balance(f: function) → None

This function allows a client to register a function to be called back by EnergyPlus at the beginning of the zone time step before init heat balance.

Parameters

f – A python function which takes no arguments and returns nothing

Returns

Nothing

callback_end_system_sizing(f: function) → None

This function allows a client to register a function to be called back by EnergyPlus at the end of the system sizing process.

Parameters

f – A python function which takes no arguments and returns nothing

Returns

Nothing

callback_end_system_timestep_after_hvac_reporting(f: function) → None

This function allows a client to register a function to be called back by EnergyPlus at the end of a system time step and after HVAC reporting.

Parameters

f – A python function which takes no arguments and returns nothing

Returns

Nothing

callback_end_system_timestep_before_hvac_reporting(f: function) → None

This function allows a client to register a function to be called back by EnergyPlus at the end of a system time step, but before HVAC reporting.

Parameters

f – A python function which takes no arguments and returns nothing

Returns

Nothing

callback_end_zone_sizing(f: function) → None

This function allows a client to register a function to be called back by EnergyPlus at the end of the zone sizing process.

Parameters

f – A python function which takes no arguments and returns nothing

Returns

Nothing

callback_end_zone_timestep_after_zone_reporting(f: function) → None

This function allows a client to register a function to be called back by EnergyPlus at the end of a zone time step and after zone reporting.

Parameters

f – A python function which takes no arguments and returns nothing

Returns

Nothing

callback_end_zone_timestep_before_zone_reporting(f: function) → None

This function allows a client to register a function to be called back by EnergyPlus at the end of a zone time step but before zone reporting has been completed.

Parameters

f – A python function which takes no arguments and returns nothing

Returns

Nothing

callback_inside_system_iteration_loop(f: function) → None

This function allows a client to register a function to be called back by EnergyPlus inside the system iteration loop.

Parameters

f – A python function which takes no arguments and returns nothing

Returns

Nothing

callback_message(f: function) → None

This function allows a client to register a function to be called back by EnergyPlus when printing anything to standard output. This can allow a GUI to easily show the output of EnergyPlus streaming by. When used in conjunction with the progress callback, a progress bar and status text label can provide a nice EnergyPlus experience on a GUI.

Parameters

f – A python function which takes a string (bytes) argument and returns nothing

Returns

Nothing

callback_progress(f: function) → None

This function allows a client to register a function to be called back by EnergyPlus at the end of each day with a progress (percentage) indicator

Parameters

f – A python function which takes an integer argument and returns nothing

Returns

Nothing

callback_unitary_system_sizing(f: function) → None

This function allows a client to register a function to be called back by EnergyPlus in unitary system sizing.

Parameters

f – A python function which takes no arguments and returns nothing

Returns

Nothing

static clear_callbacks() → None

This function is used if you are running this script continually making multiple calls into the E+ library in one thread. EnergyPlus should be cleaned up between runs.

Note this will clean all registered callbacks, so functions must be registered again prior to the next run.

Returns

Nothing

issue_severe(message: Union[str, bytes]) → None

This function allows a script to issue an error through normal EnergyPlus methods. The message will be listed in the standard EnergyPlus error file once the simulation is complete. This function has limited usefulness when calling EnergyPlus as a library, as errors can be handled by the calling client, however, in a PythonPlugin workflow, this can be an important tool to alert the user of issues once EnergyPlus(.exe) has finished running.

Note the severe errors tend to lead to EnergyPlus terminating with a Fatal Error. This can be accomplished in PythonPlugin workflows by issuing a severe error, followed by returning 1 from the plugin function. EnergyPlus will interpret this return value as a signal to terminate with a fatal error.

Note that the argument passed in here can be either a string or a bytes object, as this wrapper handles conversion as needed.

Parameters

message – The error message to be listed in the error file.

Returns

Nothing

issue_text(message: Union[str, bytes]) → None

This function allows a script to issue a message through normal EnergyPlus methods. The message will be listed in the standard EnergyPlus error file once the simulation is complete. This function can be used alongside the warning and error issuance functions to provide further context to the situation. This function has limited usefulness when calling EnergyPlus as a library, as errors can be handled by the calling client, however, in a PythonPlugin workflow, this can be an important tool to alert the user of issues once EnergyPlus(.exe) has finished running.

Note that the argument passed in here can be either a string or a bytes object, as this wrapper handles conversion as needed.

Parameters

message – The message to be listed in the error file.

Returns

Nothing

issue_warning(message: Union[str, bytes]) → None

This function allows a script to issue a warning through normal EnergyPlus methods. The message will be listed in the standard EnergyPlus error file once the simulation is complete. This function has limited usefulness when calling EnergyPlus as a library, as errors can be handled by the calling client, however, in a PythonPlugin workflow, this can be an important tool to alert the user of issues once EnergyPlus(.exe) has finished running.

Note that the argument passed in here can be either a string or a bytes object, as this wrapper handles conversion as needed.

Parameters

message – The warning message to be listed in the error file.

Returns

Nothing

run_energyplus(command_line_args: List[Union[str, bytes]]) → int

This function calls EnergyPlus to run a simulation. The C API expects to find arguments matching the command line string when executing EnergyPlus. When calling the C API directly, the client must create a list of char arguments starting with the program name, followed by all the command line options. For this Python API, the program name is not passed in as an argument, rather only the command line options.

An example call: run_energyplus([‘-d’, ‘/path/to/output/directory’, ‘-w’, ‘/path/to/weather.epw’, ‘/path/to/input.idf’])

Parameters

command_line_args – The command line arguments that would be passed into EnergyPlus if executing directly from the EnergyPlus executable.

Returns

An integer exit code from the simulation, zero is success, non-zero is failure