sinergym

Gym environment for building simulation and control using reinforcement learning

Science Score: 67.0%

This score indicates how likely this project is to be science-related based on various indicators:

✓
CITATION.cff file
Found CITATION.cff file
✓
codemeta.json file
Found codemeta.json file
✓
.zenodo.json file
Found .zenodo.json file
✓
DOI references
Found 1 DOI reference(s) in README
✓
Academic publication links
Links to: sciencedirect.com
○
Committers with academic emails
○
Institutional organization owner
○
JOSS paper metadata
○
Scientific vocabulary similarity
Low similarity (12.6%) to scientific vocabulary

Keywords

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

Last synced: 4 months ago · JSON representation ·

Repository

Gym environment for building simulation and control using reinforcement learning

Basic Info

Host: GitHub
Owner: ugr-sail
License: mit
Language: Python
Default Branch: main
Homepage: https://ugr-sail.github.io/sinergym/
Size: 476 MB

Statistics

Stars: 185
Watchers: 6
Forks: 51
Open Issues: 8
Releases: 62

Topics

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

Created almost 5 years ago · Last pushed 5 months ago

Metadata Files

Readme Contributing License Code of conduct Citation

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:

```python 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:

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

Owner

Name: UGR-SAIL
Login: ugr-sail
Kind: organization
Location: Spain

Website: http://sail.ugr.es
Repositories: 2
Profile: https://github.com/ugr-sail

Research group at the University of Granada focused on developing AI tools for climate-neutral buildings and networks

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

GitHub Events

Total

Create event: 33
Release event: 6
Issues event: 11
Watch event: 47
Delete event: 31
Issue comment event: 14
Push event: 179
Pull request review event: 1
Pull request event: 51
Fork event: 17

Last Year

Create event: 33
Release event: 6
Issues event: 11
Watch event: 47
Delete event: 31
Issue comment event: 14
Push event: 179
Pull request review event: 1
Pull request event: 51
Fork event: 17

Committers

Last synced: 4 months ago

All Time

Total Commits: 831
Total Committers: 11
Avg Commits per committer: 75.545
Development Distribution Score (DDS): 0.158

Past Year

Commits: 156
Committers: 3
Avg Commits per committer: 52.0
Development Distribution Score (DDS): 0.026

Top Committers

Name	Email	Commits
AlejandroCN7	a**9@g**m	700
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 (Top 20 + Academic)

accenture.com: 1 github.com: 1

Issues and Pull Requests

Last synced: 4 months ago

All Time

Total issues: 125
Total pull requests: 194
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.57
Average comments per pull request: 0.03
Merged pull requests: 178
Bot issues: 0
Bot pull requests: 2

Past Year

Issues: 9
Pull requests: 84
Average time to close issues: 1 day
Average time to close pull requests: about 15 hours
Issue authors: 6
Pull request authors: 4
Average comments per issue: 0.78
Average comments per pull request: 0.01
Merged pull requests: 74
Bot issues: 0
Bot pull requests: 0

View more stats

Top Authors

Issue Authors

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

Pull Request Authors

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

Top Labels

Issue Labels

question (44) bug (30) enhancement (28) Feature request (17) Env (15) documentation (15) wrapper (13) building (12) BackEnd (7) DRL (6) log (6) workflow (3) container (3) reward (2) Testing (2) callback (2) dependencies (1) PyPi (1) warning (1) Controller (1) good first issue (1) help wanted (1)

Pull Request Labels

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

Packages

Total packages: 2
Total downloads:
- pypi 639 last-month
Total docker downloads: 35

Total dependent packages: 0
(may contain duplicates)
Total dependent repositories: 1
(may contain duplicates)
Total versions: 118
Total maintainers: 2

proxy.golang.org: github.com/ugr-sail/sinergym

Documentation: https://pkg.go.dev/github.com/ugr-sail/sinergym#section-documentation
License: mit
Latest release: v3.9.0+incompatible
published 6 months ago

Versions: 65
Dependent Packages: 0
Dependent Repositories: 0

Rankings

Dependent packages count: 5.4%

Average: 5.6%

Dependent repos count: 5.8%

Last synced: 4 months ago

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
License: MIT
Latest release: 3.9.0
published 6 months ago

Versions: 53
Dependent Packages: 0
Dependent Repositories: 1
Downloads: 639 Last month
Docker Downloads: 35

Rankings

Docker downloads count: 2.9%

Dependent packages count: 7.3%

Stargazers count: 7.6%

Forks count: 8.3%

Average: 10.9%

Downloads: 17.3%

Dependent repos count: 22.1%

Maintainers (2)

alejandrocn7 sail-ugr

Last synced: 4 months ago

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

sinergym

Science Score: 67.0%

Keywords

Repository

Basic Info

Statistics

Topics

Metadata Files

README.md

About Sinergym

Main features

Project structure

Available environments

Installation

Usage example

Create environment

Initialization

Run episode

Contributing

Projects using Sinergym

Repository activity

Citing Sinergym

Owner

Citation (CITATION.bib)

GitHub Events

Total

Last Year

Committers

All Time

Past Year

Top Committers

Committer Domains (Top 20 + Academic)

Issues and Pull Requests

All Time

Past Year

Top Authors

Issue Authors

Pull Request Authors

Top Labels

Issue Labels

Pull Request Labels

Packages

proxy.golang.org: github.com/ugr-sail/sinergym

Rankings

pypi.org: sinergym

Rankings

Maintainers (2)

Dependencies