Sinergym

Gym environment for building simulation and control using reinforcement learning.
https://github.com/ugr-sail/sinergym

Category: Consumption
Sub Category: Buildings and Heating

Keywords

building-control building-energy buildings energyplus framework python reinforcement-learning reinforcement-learning-environments simulation

Keywords from Contributors

routing

Last synced: about 13 hours ago
JSON representation

Repository metadata

Gym environment for building simulation and control using reinforcement learning

Host: GitHub
URL: https://github.com/ugr-sail/sinergym
Owner: ugr-sail
License: mit
Created: 2021-01-23T18:45:17.000Z (over 4 years ago)
Default Branch: main
Last Pushed: 2025-04-11T09:00:43.000Z (16 days ago)
Last Synced: 2025-04-20T10:41:23.188Z (7 days ago)
Topics: building-control, building-energy, buildings, energyplus, framework, python, reinforcement-learning, reinforcement-learning-environments, simulation
Language: Python
Homepage: https://ugr-sail.github.io/sinergym/
Size: 442 MB
Stars: 159
Watchers: 6
Forks: 44
Open Issues: 8
Releases: 60
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Citation: CITATION.bib

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/: auxiliar and help 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.

Projects using Sinergym

The following are some of the projects using Sinergym:

📝 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

Alt

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},
}

Citation (CITATION.bib)

@article{campoy2024sinergym,
  title     = {Sinergym--A virtual testbed for building energy optimization with Reinforcement Learning},
  author    = {Campoy-Nieves, Alejandro and Manjavacas, Antonio and Jim{\'e}nez-Raboso, Javier and Molina-Solana, Miguel and G{\'o}mez-Romero, Juan},
  journal   = {Energy and Buildings},
  pages     = {115075},
  year      = {2024},
  publisher = {Elsevier}
}

Owner metadata

Name: UGR-SAIL
Login: ugr-sail
Email:
Kind: organization
Description: Research group at the University of Granada focused on developing AI tools for climate-neutral buildings and networks
Website: http://sail.ugr.es
Location: Spain
Twitter:
Company:
Icon url: https://avatars.githubusercontent.com/u/100535102?v=4
Repositories: 2
Last ynced at: 2023-03-05T01:18:39.087Z
Profile URL: https://github.com/ugr-sail

GitHub Events

Total

Create event: 29
Release event: 5
Issues event: 6
Watch event: 34
Delete event: 24
Issue comment event: 6
Push event: 145
Pull request review event: 1
Pull request event: 46
Fork event: 14

Last Year

Create event: 29
Release event: 5
Issues event: 6
Watch event: 34
Delete event: 24
Issue comment event: 6
Push event: 145
Pull request review event: 1
Pull request event: 46
Fork event: 14

Committers metadata

Last synced: 4 days ago

Total Commits: 826
Total Committers: 11
Avg Commits per committer: 75.091
Development Distribution Score (DDS): 0.159

Commits in past year: 166
Committers in past year: 3
Avg Commits per committer in past year: 55.333
Development Distribution Score (DDS) in past year: 0.024

Name	Email	Commits
AlejandroCN7	a**9@g**m	695
jajimer	j**1@g**m	70
Antonio	a**s@g**m	30
GitHub Action	a**n@g**m	11
Maria Moreno de Castro	m**o@o**m	5
Jiménez	j**z@a**m	4
Ahmed Brek Prieto	7****P	3
Francisco Pertíñez Perea	7****p	3
Pablo Torres Anaya	h**s@g**m	2
Miguel Molina-Solana	m**s@g**m	2
Marco Biemann	3****n	1

Committer domains:

accenture.com: 1
github.com: 1

Issue and Pull Request metadata

Last synced: 1 day ago

Total issues: 126
Total pull requests: 131
Average time to close issues: about 2 months
Average time to close pull requests: 2 days
Total issue authors: 31
Total pull request authors: 9
Average comments per issue: 1.71
Average comments per pull request: 0.03
Merged pull request: 124
Bot issues: 0
Bot pull requests: 1

Past year issues: 23
Past year pull requests: 58
Past year average time to close issues: 8 days
Past year average time to close pull requests: about 14 hours
Past year issue authors: 12
Past year pull request authors: 4
Past year average comments per issue: 1.61
Past year average comments per pull request: 0.02
Past year merged pull request: 54
Past year bot issues: 0
Past year bot pull requests: 0

More stats: https://issues.ecosyste.ms/repositories/lookup?url=https://github.com/ugr-sail/sinergym

Top Issue Authors

AlejandroCN7 (60)
MichielKempkens (19)
kad99kev (8)
jajimer (3)
HYDesmondLiu (3)
Lorenzo69420 (2)
Ahmed2BP (2)
mrks-g (2)
MMdeCastro (2)
chencjiajy (2)
Miguel-jp (2)
manjavacas (2)
Theophile11 (1)
glolichen (1)
cainiaodidi (1)

Top Pull Request Authors

AlejandroCN7 (116)
fpertinezp (3)
Ahmed2BP (3)
manjavacas (3)
MMdeCastro (2)
kad99kev (1)
multi-stager (1)
dependabot[bot] (1)
jajimer (1)

Top Issue Labels

question (42)
enhancement (30)
bug (29)
Feature request (19)
documentation (16)
Env (15)
wrapper (14)
building (12)
log (8)
BackEnd (7)
DRL (6)
workflow (3)
container (3)
reward (2)
Testing (2)
callback (2)
help wanted (1)
good first issue (1)
Controller (1)
PyPi (1)
dependencies (1)
warning (1)

Top Pull Request Labels

enhancement (14)
bug (9)
documentation (9)
building (9)
Env (8)
wrapper (7)
BackEnd (4)
log (3)
reward (2)
Feature request (2)
container (2)
callback (1)
dependencies (1)

Package metadata

Total packages: 1
Total downloads:
- pypi: 1,310 last-month
Total docker downloads: 35
Total dependent packages: 0
Total dependent repositories: 1
Total versions: 52
Total maintainers: 2

pypi.org: sinergym

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

Homepage: https://github.com/ugr-sail/sinergym
Documentation: https://ugr-sail.github.io/sinergym
Licenses: MIT
Latest release: 3.8.4 (published 5 days ago)
Last Synced: 2025-04-25T13:05:23.896Z (1 day ago)
Versions: 52
Dependent Packages: 0
Dependent Repositories: 1
Downloads: 1,310 Last month
Docker Downloads: 35
Rankings:
- Docker downloads count: 2.92%
- Dependent packages count: 7.31%
- Stargazers count: 7.592%
- Forks count: 8.272%
- Average: 10.908%
- Downloads: 17.267%
- Dependent repos count: 22.088%
Maintainers (2)
- alejandrocn7
- sail-ugr

Dependencies

.github/workflows/create_pr.yml actions

actions/checkout v2 composite
actions/setup-python v2 composite
dorny/paths-filter v2 composite
isort/isort-action master composite
peter-evans/autopep8 v1 composite

.github/workflows/create_release.yml actions

abatilo/release-info-action v1.3.0 composite
actions/checkout master composite
actions/checkout v2 composite
pypa/gh-action-pypi-publish release/v1 composite

.github/workflows/merge_pr.yml actions

actions/checkout v2 composite
actions/setup-python v2 composite
dorny/paths-filter v2 composite
isort/isort-action master composite
peter-evans/autopep8 v1 composite
stefanzweifel/git-auto-commit-action v4 composite
tj-actions/verify-changed-files v7.2 composite

.github/workflows/protection.yml actions

actions/checkout v2 composite
dorny/paths-filter v2 composite

.devcontainer/Dockerfile docker

sailugr/sinergym latest build

Dockerfile docker

ubuntu ${UBUNTU_VERSION} build

docs/requirements.txt pypi

nbsphinx *
sphinx-rtd-theme *

poetry.lock pypi

167 dependencies

pyproject.toml pypi

IPython ^8.27.0 doc
nbsphinx ^0.9.5 doc
nbsphinx_link ^1.3.1 doc
pyenchant ^3.2.2 doc
sphinx ^7.4.7 doc
sphinx-multitoc-numbering ^0.1.3 doc
sphinx-multiversion ^0.2.4 doc
sphinx-rtd-theme ^2.0.0 doc
sphinxcontrib-jquery ^4.1 doc
sphinxcontrib-spelling ^8.0.0 doc
stable-baselines3 ^2.3.2 drl
autopep8 ^2.3.1 format
isort ^5.13.2 format
pipdeptree ^2.23.4 format
google-api-python-client ^2.58.0 gcloud
google-cloud-storage ^2.5.0 gcloud
oauth2client ^4.1.3 gcloud
IPython ^8.27.0 ipython
wandb ^0.18.1 platforms
IPython ^8.27.0
coverage ^7.6.1
eppy ^0.5.63
epw ^1.2.dev2
google-api-python-client ^2.58.0
google-cloud-storage ^2.5.0
gymnasium ^0.29.1
numpy ^2.1.1
oauth2client ^4.1.3
pandas ^2.2.2
pytest ^8.3.3
pytest-cov ^5.0.0
pytest-xdist ^3.6.1
python ^3.12
stable-baselines3 ^2.3.2
tqdm ^4.66.5
wandb ^0.18.1
xlsxwriter ^3.2.0
coverage ^7.6.1 test
pytest ^8.3.3 test
pytest-cov ^5.0.0 test
pytest-xdist ^3.6.1 test
wandb ^0.18.1 test
pytype ^2024.9.13 typing
urllib3 ^2.2.3 typing

Score: 14.723007941422882

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Open Sustainable Technology