Runtime API

class runtime.Runtime(api: <ctypes.LibraryLoader object at 0x7ff42ee621d0>)[source]

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(state: c_void_p, f: function) None[source]

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

Parameters:
  • state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().

  • f – A python function which takes one argument, the current state instance, and returns nothing

Returns:

Nothing

callback_after_new_environment_warmup_complete(state: c_void_p, f: function) None[source]

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

Parameters:
  • state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().

  • f – A python function which takes one argument, the current state instance, and returns nothing

Returns:

Nothing

callback_after_predictor_after_hvac_managers(state: c_void_p, f: function) None[source]

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:
  • state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().

  • f – A python function which takes one argument, the current state instance, and returns nothing

Returns:

Nothing

callback_after_predictor_before_hvac_managers(state: c_void_p, f: function) None[source]

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:
  • state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().

  • f – A python function which takes one argument, the current state instance, and returns nothing

Returns:

Nothing

callback_begin_new_environment(state: c_void_p, f: function) None[source]

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

Parameters:
  • state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().

  • f – A python function which takes one argument, the current state instance, and returns nothing

Returns:

Nothing

callback_begin_system_timestep_before_predictor(state: c_void_p, f: function) None[source]

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

Parameters:
  • state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().

  • f – A python function which takes one argument, the current state instance, and returns nothing

Returns:

Nothing

callback_begin_zone_timestep_after_init_heat_balance(state: c_void_p, f: function) None[source]

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:
  • state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().

  • f – A python function which takes one argument, the current state instance, and returns nothing

Returns:

Nothing

callback_begin_zone_timestep_before_init_heat_balance(state: c_void_p, f: function) None[source]

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:
  • state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().

  • f – A python function which takes one argument, the current state instance, and returns nothing

Returns:

Nothing

callback_begin_zone_timestep_before_set_current_weather(state: c_void_p, f: function) None[source]

This function allows a client to register a function to be called back by EnergyPlus at the beginning of zone time step, before weather is updated.

Parameters:
  • state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().

  • f – A python function which takes one argument, the current state instance, and returns nothing

Returns:

Nothing

callback_end_system_sizing(state: c_void_p, f: function) None[source]

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

Parameters:
  • state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().

  • f – A python function which takes one argument, the current state instance, and returns nothing

Returns:

Nothing

callback_end_system_timestep_after_hvac_reporting(state: c_void_p, f: function) None[source]

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:
  • state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().

  • f – A python function which takes one argument, the current state instance, and returns nothing

Returns:

Nothing

callback_end_system_timestep_before_hvac_reporting(state: c_void_p, f: function) None[source]

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:
  • state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().

  • f – A python function which takes one argument, the current state instance, and returns nothing

Returns:

Nothing

callback_end_zone_sizing(state: c_void_p, f: function) None[source]

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

Parameters:
  • state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().

  • f – A python function which takes one argument, the current state instance, and returns nothing

Returns:

Nothing

callback_end_zone_timestep_after_zone_reporting(state: c_void_p, f: function) None[source]

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:
  • state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().

  • f – A python function which takes one argument, the current state instance, and returns nothing

Returns:

Nothing

callback_end_zone_timestep_before_zone_reporting(state: c_void_p, f: function) None[source]

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:
  • state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().

  • f – A python function which takes one argument, the current state instance, and returns nothing

Returns:

Nothing

callback_inside_system_iteration_loop(state: c_void_p, f: function) None[source]

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

Parameters:
  • state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().

  • f – A python function which takes one argument, the current state instance, and returns nothing

Returns:

Nothing

callback_message(state: c_void_p, f: function) None[source]

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:
  • state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().

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

Returns:

Nothing

callback_progress(state: c_void_p, f: function) None[source]

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:
  • state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().

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

Returns:

Nothing

callback_register_external_hvac_manager(state: c_void_p, f: function) None[source]

This function allows a client to register an external HVAC manager function to be called back in EnergyPlus. By registering this function, EnergyPlus will bypass all HVAC calculations and expect that this function will manage all HVAC through sensors and actuators. Right now this function is not well-supported, and this callback should be considered purely as a placeholder until a future release refines the use case.

Parameters:
  • state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().

  • f – A python function which takes one argument, the current state instance, and returns nothing

Returns:

Nothing

callback_unitary_system_sizing(state: c_void_p, f: function) None[source]

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

Parameters:
  • state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().

  • f – A python function which takes one argument, the current state instance, and returns nothing

Returns:

Nothing

callback_user_defined_component_model(state: c_void_p, f: function, program_name: str) None[source]

This function allows a client to register a function to be called by a specific user-defined equipment object inside EnergyPlus. This registration function takes a string for the program “name” which should match the name given in the IDF.

Parameters:
  • state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().

  • f – A python function which takes one argument, the current state instance, and returns nothing.

  • program_name – The program name which is listed in the IDF on the user-defined object, either as an initialization program name or a simulation program name.

Returns:

Nothing

static clear_callbacks() None[source]

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(state: c_void_p, message: str | bytes) None[source]

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:
  • state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().

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

Returns:

Nothing

issue_text(state: c_void_p, message: str | bytes) None[source]

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:
  • state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().

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

Returns:

Nothing

issue_warning(state: c_void_p, message: str | bytes) None[source]

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:
  • state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().

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

Returns:

Nothing

run_energyplus(state: c_void_p, command_line_args: List[str | bytes]) int[source]

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: state = api.state_manager.new_state() run_energyplus(state, [‘-d’, ‘/path/to/output/directory’, ‘-w’, ‘/path/to/weather.epw’, ‘/path/to/input.idf’])

Parameters:
  • state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().

  • 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

set_console_output_status(state, print_output: bool) None[source]

Allows disabling (and enabling) of console output (stdout and stderr) when calling EnergyPlus as a library. :param state: An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state(). :param print_output: A boolean flag for whether we should mute console output :return: Nothing

stop_simulation(state: c_void_p) None[source]