sinergym 3.10.0

Sinergym provides a Gymnasium-based interface to interact with building simulations. This allows control in simulation time through custom controllers, including reinforcement learning agents

About Sinergym

Sinergym provides a Gymnasium-based interface to interact with simulation engines such as EnergyPlus. This allows control in simulation time through custom controllers, including reinforcement learning agents.

For more information about Sinergym, refer to its documentation.

Main features

⚙️ Simulation engines compatibility. Sinergym is currently compatible with the EnergyPlus Python API for controller-building communication.

📊 Benchmark environments. Similar to Atari or Mujoco, Sinergym allows the use of benchmarking environments to test and compare RL algorithms or custom control strategies.

🛠️ Custom experimentation. Sinergym enables effortless customization of experimental settings. Users can create their own environments or customize pre-configured ones within Sinergym. Select your preferred reward functions, wrappers, controllers, and more!

🏠 Automatic building model adaptation. Automatic adaptation of building models to align with user-defined settings.

🪛 Automatic actuator control. Seamless management of building actuators via the Gymnasium interface. Users only need to specify actuator names, and Sinergym will do the rest.

🤖 Stable Baselines 3 integration. Sinergym is highly integrated with Stable Baselines 3 algorithms, wrappers and callbacks.

✅ Controller-agnostic. Any controller compatible with the Gymnasium interface can be integrated with Sinergym.

☁️ Google Cloud execution. Sinergym provides several features to execute experiments in Google Cloud.

📈 Weights & Biases logging. Automate the logging of training and evaluation data, and record your models in the cloud. Sinergym facilitates reproducibility and cloud data storage through Weights and Biases integration.

📒 Notebook examples. Learn how to get the most out of Sinergym through our notebooks examples.

📚 Extensive documentation, unit tests, and GitHub actions workflows. Sinergym follows proper development practices facilitating community contributions.

Project structure

This repository is organized into the following directories:

• sinergym/: the source code of Sinergym.
• docs/: Sinergym's documentation sources.
• examples/: notebooks with several examples illustrating how to use Sinergym.
• tests/: Sinergym tests code.
• scripts/: auxiliary and helper scripts.

Available environments

For a complete and up-to-date list of available environments, please refer to our documentation.

Installation

Read INSTALL.md for detailed installation instructions.

Usage example

This is a simple script using Sinergym:

import gymnasium as gym
import sinergym

# Create environment
env = gym.make('Eplus-datacenter-mixed-continuous-stochastic-v1')

# Initialization
obs, info = env.reset()
truncated = terminated = False

# Run episode
while not (terminated or truncated):
    action = env.action_space.sample() # random action selection
    obs, reward, terminated, truncated, info = env.step(action)

env.close()

Several usage examples can be consulted here.

Contributing

To report questions and issues, open an issue following the provided templates. We appreciate your feedback!

Check out CONTRIBUTING.md for specific details on how to contribute.

To better adhere to the required standards of this repository, we recommend running the following command:

chmod +x hooks/*
git config core.hooksPath hooks

This will add git hooks that execute before using typical commands (add, commit, push, etc.) to verify that the methodology is correct before proceeding with the process.

Projects using Sinergym

The following are some of the projects using Sinergym:

• Demosthen/ActiveRL
• VectorInstitute/HV-Ai-C
• rdnfn/beobench

📝 If you want to appear in this list, feel free to open a pull request and include the following badge in your repository:

Repository activity

Citing Sinergym

If you use Sinergym in your work, please cite our paper:

@article{Campoy2025sinergym,
  title = {Sinergym – A virtual testbed for building energy optimization with Reinforcement Learning},
  author = {Alejandro Campoy-Nieves and Antonio Manjavacas and Javier Jiménez-Raboso and Miguel Molina-Solana and Juan Gómez-Romero},
  journal   = {Energy and Buildings},
  volume = {327},
  articleno = {115075},
  year = {2025},
  issn = {0378-7788},
  doi = {10.1016/j.enbuild.2024.115075},
  url = {https://www.sciencedirect.com/science/article/pii/S0378778824011915},
}