sinergym.simulators.eplus.EnergyPlus

class sinergym.simulators.eplus.EnergyPlus(name: str, obs_queue: Queue, info_queue: Queue, act_queue: Queue, context_queue: Queue, time_variables: List[str] = [], variables: Dict[str, Tuple[str, str]] = {}, meters: Dict[str, str] = {}, actuators: Dict[str, Tuple[str, str, str]] = {}, context: Dict[str, Tuple[str, str, str]] = {})
__init__(name: str, obs_queue: Queue, info_queue: Queue, act_queue: Queue, context_queue: Queue, time_variables: List[str] = [], variables: Dict[str, Tuple[str, str]] = {}, meters: Dict[str, str] = {}, actuators: Dict[str, Tuple[str, str, str]] = {}, context: Dict[str, Tuple[str, str, str]] = {})

EnergyPlus runner class. This class run an episode in a thread when start() is called.

Parameters:

  • name (str) – Name of the environment which is using the simulator.

  • obs_queue (Queue) – Observation queue for Gymnasium environment communication.

  • info_queue (Queue) – Extra information dict queue for Gymnasium environment communication.

  • act_queue (Queue) – Action queue for Gymnasium environment communication.

  • context_queue (Queue) – Context queue for Gymnasium environment communication, modifying internal states.

  • time_variables (List[str]) – EnergyPlus time variables we want to observe. The name of the variable must match with the name of the E+ Data Transfer API method name. Defaults to empty list

  • variables (Dict[str, Tuple[str, str]]) – Specification for EnergyPlus Output:Variable. The key name is custom, then tuple must be the original variable name and the output variable key. Defaults to empty dict.

  • meters (Dict[str, str]) – Specification for EnergyPlus Output:Meter. The key name is custom, then value is the original EnergyPlus Meters name.

  • actuators (Dict[str, Tuple[str, str, str]]) – Specification for EnergyPlus Input Actuators. The key name is custom, then value is a tuple with actuator type, value type and original actuator name. Defaults to empty dict.

  • context (Dict[str, Tuple[str, str, str]]) – Specification for EnergyPlus Context Actuators. The key name is custom, then value is a tuple with actuator type, value type and original actuator name. These values are processed as real-time building configuration instead of real-time control. Defaults to empty dict.

Methods

__init__(name, obs_queue, info_queue, ...[, ...])

EnergyPlus runner class.

clear_simulator_callbacks()

Clear tracked user callbacks (see Custom callbacks).

failed()

Method to determine if simulation has failed.

make_eplus_args()

Transform attributes defined in class instance into energyplus bash command

register_simulator_callback(callback_name, ...)

Validate and queue a user callback for EnergyPlus (applied when the run starts).

start(building_path, weather_path, ...)

Initializes all callbacks and handlers using EnergyPlus API, prepare the simulation system

stop()

It forces the simulation ends, cleans all communication queues, thread is deleted (joined) and simulator attributes are reset (except handlers, to not initialize again if there is a next thread execution).

Attributes

is_running

logger

registered_callbacks

{callback_point: [callable __name__, ...]} for user callbacks.
clear_simulator_callbacks() → None

Clear tracked user callbacks (see Custom callbacks).

Does not remove internal Sinergym communication callbacks. EnergyPlus runtime hooks are torn down with the simulation lifecycle (e.g. when stop() runs).

failed() → bool

Method to determine if simulation has failed.

Returns:

Flag to describe this state

Return type:

bool

property is_running: bool
logger = <Logger SIMULATOR (INFO)>
make_eplus_args() → List[str]

Transform attributes defined in class instance into energyplus bash command

Returns:

List of the argument components for energyplus bash command

Return type:

List[str]

register_simulator_callback(callback_name: str, callback_func: Callable, component_program_name: str | None = None) → None

Validate and queue a user callback for EnergyPlus (applied when the run starts).

Callables are stored until the simulation registers them at run start. User-facing documentation, the full list of callback_name values, and examples are in Custom callbacks section.

Raises:

ValueError – Invalid callback_name or invalid component_program_name usage.

property registered_callbacks: Dict[str, List[str]]

{callback_point: [callable __name__, ...]} for user callbacks.

See Custom callbacks. The environment exposes the same data via its callbacks property.

start(building_path: str, weather_path: str, output_path: str, episode: int) → None
Initializes all callbacks and handlers using EnergyPlus API, prepare the simulation system

and start running the simulation in a Python thread.

Parameters:

  • building_path (str) – EnergyPlus input description file path.

  • weather_path (str) – EnergyPlus weather path.

  • output_path (str) – Path where EnergyPlus process is going to allocate its output files.

  • episode (int) – Number of the episode to run (useful to show in progress bar).

stop() → None

It forces the simulation ends, cleans all communication queues, thread is deleted (joined) and simulator attributes are reset (except handlers, to not initialize again if there is a next thread execution).