<div align="center">
<img src="images/logo.png" width=50%><br><br>
</div>
</p>
<p align="center">
<a href="https://github.com/ugr-sail/sinergym/releases">
<img alt="Github latest release" src="https://img.shields.io/github/release-date/ugr-sail/sinergym" />
</a>
<a href="https://github.com/ugr-sail/sinergym/commits/main">
<img alt="Github last commit" src="https://img.shields.io/github/last-commit/ugr-sail/sinergym" />
</a>
<a href="https://pypi.org/project/sinergym/">
<img alt="pypi version" src="https://img.shields.io/pypi/v/sinergym" />
</a>
<a href="https://github.com/ugr-sail/sinergym/stargazers">
<img alt="pypi downloads" src="https://img.shields.io/pypi/dm/sinergym" />
</a>
<a href="https://codecov.io/gh/ugr-sail/sinergym">
<img src="https://codecov.io/gh/ugr-sail/sinergym/branch/main/graph/badge.svg" />
</a>
<a href="https://github.com/ugr-sail/sinergym/graphs/contributors">
<img alt="GitHub Contributors" src="https://img.shields.io/github/contributors/ugr-sail/sinergym" />
</a>
<a href="https://github.com/ugr-sail/sinergym/issues">
<img alt="Github issues" src="https://img.shields.io/github/issues/ugr-sail/sinergym?color=0088ff" />
</a>
<a href="https://github.com/ugr-sail/sinergym/pulls">
<img alt="GitHub pull requests" src="https://img.shields.io/github/issues-pr/ugr-sail/sinergym?color=0088ff" />
</a>
<a href="https://github.com/ugr-sail/sinergym/blob/main/LICENSE">
<img alt="Github license" src="https://img.shields.io/github/license/ugr-sail/sinergym" />
</a>
<a href="https://www.python.org/downloads/release/python-3120/">
<img alt="pypi Python version" src="https://img.shields.io/pypi/pyversions/sinergym" />
</a>
<a href="https://hub.docker.com/r/sailugr/sinergym/tags">
<img alt="DockerHub last version" src="https://img.shields.io/docker/v/sailugr/sinergym?color=blue&label=Docker%20Image%20Version&logo=docker" />
</a>
<br />
<br />
<a href="https://code.visualstudio.com/">
<img src="https://img.shields.io/badge/Supported%20by-VSCode%20Power%20User%20%E2%86%92-gray.svg?colorA=655BE1&colorB=4F44D6&style=for-the-badge"/>
</a>
</p>
<div align="center">
<img src="images/general_blueprint.png" width=80%><br><br>
</div>
## About Sinergym
*Sinergym* provides a [Gymnasium](https://gymnasium.farama.org/)-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](https://ugr-sail.github.io/sinergym/compilation/main/index.html).
## Main features
⚙️ **Simulation engines compatibility**. *Sinergym* is currently compatible with the [EnergyPlus Python API](https://energyplus.readthedocs.io/en/latest/api.html) 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](https://github.com/DLR-RM/stable-baselines3) 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](https://cloud.google.com/).
📈 **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](https://wandb.ai/site) integration.
📒 **Notebook examples**. Learn how to get the most out of *Sinergym* through our [notebooks examples](https://github.com/ugr-sail/sinergym/tree/main/examples).
📚 **Extensive documentation, unit tests, and GitHub actions workflows**. *Sinergym* follows proper development practices facilitating community contributions.
<div align="center">
<img src="images/operation_diagram.png"><br><br>
</div>
## 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](https://ugr-sail.github.io/sinergym/compilation/main/pages/environments.html#).
## Installation
Read [INSTALL.md](https://github.com/ugr-sail/sinergym/blob/main/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](https://ugr-sail.github.io/sinergym/compilation/main/pages/notebooks/basic_example.html#Basic-example).
## Contributing
To report questions and issues, [open an issue](https://github.com/ugr-sail/sinergym/issues) following the provided templates. We appreciate your feedback!
Check out [CONTRIBUTING.md](https://github.com/ugr-sail/sinergym/blob/main/CONTRIBUTING.md) for specific details on how to contribute.
## Projects using Sinergym
The following are some of the projects using *Sinergym*:
- [Demosthen/ActiveRL](https://github.com/Demosthen/ActiveRL)
- [VectorInstitute/HV-Ai-C](https://github.com/VectorInstitute/HV-Ai-C)
- [rdnfn/beobench](https://github.com/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:
<p align="center">
<a href="https://github.com/ugr-sail/sinergym">
<img src="https://img.shields.io/badge/Powered%20by-Sinergym%20%E2%86%92-gray.svg?colorA=00BABF&colorB=4BF2F7&style=for-the-badge"/>
</a>
</p>
## Repository activity
## Citing Sinergym
If you use *Sinergym* in your work, please cite our [paper](https://dl.acm.org/doi/abs/10.1145/3486611.3488729):
```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},
}
```
For detailed information, please refer to the [documentation](https://ugr-sail.github.io/sinergym/compilation/main/index.html).
# Installation
*Sinergym* relies on several dependencies, the specifics of which vary by version.
The table below provides a summary of the dependencies versions supported by *Sinergym* across its releases:
| **Sinergym version** | **Ubuntu version** | **Python version** | **EnergyPlus version** | **Building model file** |
| -------------------- | ------------------ | ------------------ | ---------------------- | ----------------------- |
| **0.0** | 18.04 LTS | 3.6 | 8.3.0 | IDF |
| **1.1.0** | 18.04 LTS | 3.6 | **9.5.0** | IDF |
| **1.7.0** | 18.04 LTS | **3.9** | 9.5.0 | IDF |
| **1.9.5** | **22.04 LTS** | **3.10.6** | 9.5.0 | IDF |
| **2.4.0** | 22.04 LTS | 3.10.6 | 9.5.0 | **epJSON** |
| **2.5.0** | 22.04 LTS | 3.10.6 | **23.1.0** | epJSON |
| **3.3.6** | **24.04 LTS** | **3.12.3** | 23.1.0 | epJSON |
| **3.5.8** | 24.04 LTS | 3.12.3 | **24.1.0** | epJSON |
We recommend to always use the latest version of *Sinergym* that is supported by the container. This will help you to avoid the complexities of manual installation.
However, if you prefer to manually install *Sinergym* on your computer, we provide the necessary documentation in the subsequent sections.
## Docker container
We provide a **Dockerfile** to install all dependencies and prepare the image for running *Sinergym*. This is the **recommended** option, since it
ensures that all dependencies and versions are correctly installed and configured.
This Dockerfile installs the compatible operating system, EnergyPlus, Python, and *Sinergym*, along with the necessary dependencies for its proper functioning.
If you have cloned the repository, run the following command:
```bash
$ docker build -t <tag_name> .
```
*Sinergym* has a set of optional dependencies that enhance its usage. These dependencies can be installed in the following way when building the image:
```bash
$ docker build -t <tag_name> --build-arg SINERGYM_EXTRAS="drl notebooks gcloud" .
```
These optional dependencies allow you to use `stable-baselines3`, `wandb`, `notebooks` and `gcloud`. For more information, please refer to the `pyproject.toml` file at the root of the repository (``[tool.poetry.extras]`` section).
If you want to install all optional packages, use `extras` in the `SINERGYM_EXTRAS` argument.
> :memo: **Note:** the container can also be directly installed from the [Docker Hub repository](https://hub.docker.com/repository/docker/sailugr/sinergym). It contains all the project's releases with secondary dependencies or lite versions.
Once the container image is ready, you can execute any command as follows:
```bash
$ docker run -it --rm <tag_name> <command>
```
By default, the command executed is `python scripts/try_env.py`, which is a minimal working example.
If you want to run a DRL experiment, for example, you can do it like this:
```bash
$ docker build -t example/sinergym:latest --build-arg SINERGYM_EXTRAS="drl" .
$ docker run -e WANDB_API_KEY=$WANDB_API_KEY -it --rm example/sinergym:latest python scripts/train/train_agent.py -conf scripts/train/train_agent_PPO.json
```
If the script you want to use requires a Weights and Biases account, remember to include the corresponding API token in a container environment variable.
It is also possible to keep an open session in the image. For more information, please refer to the official Docker documentation. This may help to run your own scripts in the container.
```bash
$ docker run -it <tag_name> /bin/bash
```
> :memo: **Note:** For [Visual Studio Code](https://code.visualstudio.com/) users, simply open the root directory and click the *Reopen in container* pop-up button. This will automatically install all dependencies and enable you to run *Sinergym* in an isolated environment. For more details about this feature, refer to the [VSCode Containers extension documentation](https://code.visualstudio.com/docs/remote/containers).
## Manual installation
If you prefer not to use containers and install it natively on your system, we provide some guidance on how to do it.
First, ensure that your system meets the previously specified software compatibility requirements. Without this, we cannot provide support or guarantees of functionality.
### Configure Python Environment
Start by installing the desired version of Python and *pip*. It is recommended to set up a working environment for Python. Finally, install the necessary dependencies of *Sinergym* in that environment:
```sh
$ pip install sinergym
```
You can also install the optional packages by running:
```sh
$ pip install sinergym[extras]
```
To directly install *Sinergym* from the cloned repository, run:
```sh
$ poetry install --no-interaction --only main --extras <optional_extras>
# or
$ pip install .[<optional_extras>]
```
Now the correct Python version and the necessary modules to run *Sinergym* will be installed.
Let's now proceed with the installation of external software.
### Install EnergyPlus
We have tested and confirmed compatibility with **EnergyPlus** version `24.1.0`. *Sinergym* might not work with other non-tested versions.
Follow the instructions detailed [here](https://energyplus.net/downloads) to install it in Linux (we only guarantee proper testing and support for **Ubuntu**).
After installation, the folder `Energyplus-24-1-0` should appear in the selected location.
### Include EnergyPlus Python API in Python path
*Sinergym* relies on the *Energyplus* Python API. The modules of this API are located in the *EnergyPlus* folder that was created in the previous step. You must add this installation path to the `PYTHONPATH` environment variable so that the interpreter can access these modules.
## Develop in Sinergym
Whether you have chosen to use Docker or a manual installation, we offer facilities for developing and contributing to *Sinergym*.
- If you have used a container, Visual Studio Code will set up a development environment with all the necessary packages automatically configured, including documentation, tests, etc.
- If you have decided to use a container without Visual Studio Code, you can use the Dockerfile available in the `.devcontainer` folder instead of the one in the root of the repository. If you create your own Dockerfile, make sure to perform the following installation so that all development modules are available:
```dockerfile
RUN poetry install --no-interaction
```
The default installation includes all development packages. To avoid this, you should specify `--only main` or `--without <develop_groups>`. The development groups can also be found
in `pyproject.toml`.
If you have manually installed the project, you can install the development packages from **poetry** in the same way. Once the repository is cloned, run:
```sh
$ poetry install --no-interaction
```
The command is similar to the one shown in the manual installation section, but without specifying groups or extras, so that all development packages are installed. In this case,
it is not possible to use *pip* because it does not include information about development dependencies (except those listed in *extras*).
> :memo: For more information about how poetry dependencies work, visit its [official documentation](https://python-poetry.org/docs/dependency-specification/).
## Verify Installation
This project is automatically monitored using **tests**. To verify that *Sinergym* has been installed correctly, execute `pytest tests/ -vv` from the repository root directory. Tests dependencies should have been previously installed.
Each time the *Sinergym* repository is updated, the tests are automatically executed in a remote container built using the Dockerfile. This task is performed via [Github actions](https://docs.github.com/es/actions/) (refer to the `Github actions` documentation section for additional details).
## Cloud Computing
We provide some features to execute experiments in [Google Cloud](https://cloud.google.com/). For more information visit the `Google Cloud integration` section of the documentation.
# Contributor Covenant Code of Conduct
## Our Pledge
We as members, contributors, and leaders pledge to make participation in our
community a harassment-free experience for everyone, regardless of age, body
size, visible or invisible disability, ethnicity, sex characteristics, gender
identity and expression, level of experience, education, socio-economic status,
nationality, personal appearance, race, religion, or sexual identity
and orientation.
We pledge to act and interact in ways that contribute to an open, welcoming,
diverse, inclusive, and healthy community.
## Our Standards
Examples of behavior that contributes to a positive environment for our
community include:
* Demonstrating empathy and kindness toward other people
* Being respectful of differing opinions, viewpoints, and experiences
* Giving and gracefully accepting constructive feedback
* Accepting responsibility and apologizing to those affected by our mistakes,
and learning from the experience
* Focusing on what is best not just for us as individuals, but for the
overall community
Examples of unacceptable behavior include:
* The use of sexualized language or imagery, and sexual attention or
advances of any kind
* Trolling, insulting or derogatory comments, and personal or political attacks
* Public or private harassment
* Publishing others' private information, such as a physical or email
address, without their explicit permission
* Other conduct which could reasonably be considered inappropriate in a
professional setting
## Enforcement Responsibilities
Community leaders are responsible for clarifying and enforcing our standards of
acceptable behavior and will take appropriate and fair corrective action in
response to any behavior that they deem inappropriate, threatening, offensive,
or harmful.
Community leaders have the right and responsibility to remove, edit, or reject
comments, commits, code, wiki edits, issues, and other contributions that are
not aligned to this Code of Conduct, and will communicate reasons for moderation
decisions when appropriate.
## Scope
This Code of Conduct applies within all community spaces, and also applies when
an individual is officially representing the community in public spaces.
Examples of representing our community include using an official e-mail address,
posting via an official social media account, or acting as an appointed
representative at an online or offline event.
## Enforcement
Instances of abusive, harassing, or otherwise unacceptable behavior may be
reported to the community leaders responsible for enforcement at
[INSERT CONTACT METHOD].
All complaints will be reviewed and investigated promptly and fairly.
All community leaders are obligated to respect the privacy and security of the
reporter of any incident.
## Enforcement Guidelines
Community leaders will follow these Community Impact Guidelines in determining
the consequences for any action they deem in violation of this Code of Conduct:
### 1. Correction
**Community Impact**: Use of inappropriate language or other behavior deemed
unprofessional or unwelcome in the community.
**Consequence**: A private, written warning from community leaders, providing
clarity around the nature of the violation and an explanation of why the
behavior was inappropriate. A public apology may be requested.
### 2. Warning
**Community Impact**: A violation through a single incident or series
of actions.
**Consequence**: A warning with consequences for continued behavior. No
interaction with the people involved, including unsolicited interaction with
those enforcing the Code of Conduct, for a specified period of time. This
includes avoiding interactions in community spaces as well as external channels
like social media. Violating these terms may lead to a temporary or
permanent ban.
### 3. Temporary Ban
**Community Impact**: A serious violation of community standards, including
sustained inappropriate behavior.
**Consequence**: A temporary ban from any sort of interaction or public
communication with the community for a specified period of time. No public or
private interaction with the people involved, including unsolicited interaction
with those enforcing the Code of Conduct, is allowed during this period.
Violating these terms may lead to a permanent ban.
### 4. Permanent Ban
**Community Impact**: Demonstrating a pattern of violation of community
standards, including sustained inappropriate behavior, harassment of an
individual, or aggression toward or disparagement of classes of individuals.
**Consequence**: A permanent ban from any sort of public interaction within
the community.
## Attribution
This Code of Conduct is adapted from the [Contributor Covenant][homepage],
version 2.0, available at
[https://www.contributor-covenant.org/version/2/0/code_of_conduct.html][v2.0].
Community Impact Guidelines were inspired by
[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
For answers to common questions about this code of conduct, see the FAQ at
[https://www.contributor-covenant.org/faq][FAQ]. Translations are available
at [https://www.contributor-covenant.org/translations][translations].
[homepage]: https://www.contributor-covenant.org
[v2.0]: https://www.contributor-covenant.org/version/2/0/code_of_conduct.html
[Mozilla CoC]: https://github.com/mozilla/diversity
[FAQ]: https://www.contributor-covenant.org/faq
[translations]: https://www.contributor-covenant.org/translations
MIT License
Copyright (c) 2024, A. Campoy, A. Manjavacas, J. Jiménez, M. Molina, J. Gómez
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
Raw data
{
"_id": null,
"home_page": "https://github.com/ugr-sail/sinergym",
"name": "sinergym",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.12",
"maintainer_email": null,
"keywords": "reinforcement-learning, buildings, simulation, control, reinforcement-learning-environments",
"author": "Alejandro Campoy Nieves",
"author_email": "alejandroac79@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/f0/93/e5c73586a138f1e10b8594ac686e63d17dfee0fbd3d1b790e167307fffbe/sinergym-3.7.0.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n <img src=\"images/logo.png\" width=50%><br><br>\n</div>\n\n</p>\n <p align=\"center\">\n <a href=\"https://github.com/ugr-sail/sinergym/releases\">\n <img alt=\"Github latest release\" src=\"https://img.shields.io/github/release-date/ugr-sail/sinergym\" />\n </a>\n <a href=\"https://github.com/ugr-sail/sinergym/commits/main\">\n <img alt=\"Github last commit\" src=\"https://img.shields.io/github/last-commit/ugr-sail/sinergym\" />\n </a>\n <a href=\"https://pypi.org/project/sinergym/\">\n <img alt=\"pypi version\" src=\"https://img.shields.io/pypi/v/sinergym\" />\n </a>\n <a href=\"https://github.com/ugr-sail/sinergym/stargazers\">\n <img alt=\"pypi downloads\" src=\"https://img.shields.io/pypi/dm/sinergym\" />\n </a>\n <a href=\"https://codecov.io/gh/ugr-sail/sinergym\">\n <img src=\"https://codecov.io/gh/ugr-sail/sinergym/branch/main/graph/badge.svg\" />\n </a>\n <a href=\"https://github.com/ugr-sail/sinergym/graphs/contributors\">\n <img alt=\"GitHub Contributors\" src=\"https://img.shields.io/github/contributors/ugr-sail/sinergym\" />\n </a>\n <a href=\"https://github.com/ugr-sail/sinergym/issues\">\n <img alt=\"Github issues\" src=\"https://img.shields.io/github/issues/ugr-sail/sinergym?color=0088ff\" />\n </a>\n <a href=\"https://github.com/ugr-sail/sinergym/pulls\">\n <img alt=\"GitHub pull requests\" src=\"https://img.shields.io/github/issues-pr/ugr-sail/sinergym?color=0088ff\" />\n </a>\n <a href=\"https://github.com/ugr-sail/sinergym/blob/main/LICENSE\">\n <img alt=\"Github license\" src=\"https://img.shields.io/github/license/ugr-sail/sinergym\" />\n </a>\n <a href=\"https://www.python.org/downloads/release/python-3120/\">\n <img alt=\"pypi Python version\" src=\"https://img.shields.io/pypi/pyversions/sinergym\" />\n </a>\n <a href=\"https://hub.docker.com/r/sailugr/sinergym/tags\">\n <img alt=\"DockerHub last version\" src=\"https://img.shields.io/docker/v/sailugr/sinergym?color=blue&label=Docker%20Image%20Version&logo=docker\" />\n </a>\n <br />\n <br />\n <a href=\"https://code.visualstudio.com/\">\n <img src=\"https://img.shields.io/badge/Supported%20by-VSCode%20Power%20User%20%E2%86%92-gray.svg?colorA=655BE1&colorB=4F44D6&style=for-the-badge\"/>\n </a>\n </p>\n\n<div align=\"center\">\n <img src=\"images/general_blueprint.png\" width=80%><br><br>\n</div>\n\n## About Sinergym\n\n*Sinergym* provides a [Gymnasium](https://gymnasium.farama.org/)-based interface to interact with simulation engines such as *EnergyPlus*. This allows control in simulation time through custom controllers, including **reinforcement learning** agents.\n\nFor more information about *Sinergym*, refer to its [documentation](https://ugr-sail.github.io/sinergym/compilation/main/index.html).\n\n## Main features\n\n\u2699\ufe0f **Simulation engines compatibility**. *Sinergym* is currently compatible with the [EnergyPlus Python API](https://energyplus.readthedocs.io/en/latest/api.html) for controller-building communication.\n\n\ud83d\udcca **Benchmark environments**. Similar to *Atari* or *Mujoco*, *Sinergym* allows the use of benchmarking environments to test and compare RL algorithms or custom control strategies.\n\n\ud83d\udee0\ufe0f **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!\n\n\ud83c\udfe0 **Automatic building model adaptation**. Automatic adaptation of building models to align with user-defined settings.\n\n\ud83e\ude9b **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.\n\n\ud83e\udd16 **Stable Baselines 3 integration**. *Sinergym* is highly integrated with [Stable Baselines 3](https://github.com/DLR-RM/stable-baselines3) algorithms, wrappers and callbacks.\n\n\u2705 **Controller-agnostic**. Any controller compatible with the Gymnasium interface can be integrated with *Sinergym*.\n\n\u2601\ufe0f **Google Cloud execution**. *Sinergym* provides several features to execute experiments in [Google Cloud](https://cloud.google.com/).\n\n\ud83d\udcc8 **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](https://wandb.ai/site) integration.\n\n\ud83d\udcd2 **Notebook examples**. Learn how to get the most out of *Sinergym* through our [notebooks examples](https://github.com/ugr-sail/sinergym/tree/main/examples).\n\n\ud83d\udcda **Extensive documentation, unit tests, and GitHub actions workflows**. *Sinergym* follows proper development practices facilitating community contributions.\n\n\n<div align=\"center\">\n <img src=\"images/operation_diagram.png\"><br><br>\n</div>\n\n## Project structure\n\nThis repository is organized into the following directories:\n\n- `sinergym/`: the source code of *Sinergym*.\n- `docs/`: *Sinergym*'s documentation sources.\n- `examples/`: notebooks with several examples illustrating how to use *Sinergym*.\n- `tests/`: *Sinergym* tests code.\n- `scripts/`: auxiliar and help scripts.\n\n## Available environments\n\nFor a complete and up-to-date list of available environments, please refer to [our documentation](https://ugr-sail.github.io/sinergym/compilation/main/pages/environments.html#).\n\n## Installation\n\nRead [INSTALL.md](https://github.com/ugr-sail/sinergym/blob/main/INSTALL.md) for detailed installation instructions.\n\n## Usage example\n\nThis is a simple script using *Sinergym*:\n\n```python\nimport gymnasium as gym\nimport sinergym\n\n# Create environment\nenv = gym.make('Eplus-datacenter-mixed-continuous-stochastic-v1')\n\n# Initialization\nobs, info = env.reset()\ntruncated = terminated = False\n\n# Run episode\nwhile not (terminated or truncated):\n action = env.action_space.sample() # random action selection\n obs, reward, terminated, truncated, info = env.step(action)\n\nenv.close()\n```\n\nSeveral usage examples can be consulted [here](https://ugr-sail.github.io/sinergym/compilation/main/pages/notebooks/basic_example.html#Basic-example).\n\n## Contributing\n\nTo report questions and issues, [open an issue](https://github.com/ugr-sail/sinergym/issues) following the provided templates. We appreciate your feedback!\n\nCheck out [CONTRIBUTING.md](https://github.com/ugr-sail/sinergym/blob/main/CONTRIBUTING.md) for specific details on how to contribute.\n\n## Projects using Sinergym\n\nThe following are some of the projects using *Sinergym*:\n\n- [Demosthen/ActiveRL](https://github.com/Demosthen/ActiveRL)\n- [VectorInstitute/HV-Ai-C](https://github.com/VectorInstitute/HV-Ai-C)\n- [rdnfn/beobench](https://github.com/rdnfn/beobench)\n\n\ud83d\udcdd If you want to appear in this list, feel free to open a pull request and include the following badge in your repository:\n\n<p align=\"center\">\n <a href=\"https://github.com/ugr-sail/sinergym\">\n <img src=\"https://img.shields.io/badge/Powered%20by-Sinergym%20%E2%86%92-gray.svg?colorA=00BABF&colorB=4BF2F7&style=for-the-badge\"/>\n </a>\n</p>\n\n## Repository activity\n\n![Alt](https://repobeats.axiom.co/api/embed/d8dc96d423d6996351e728a2412dba2551f99cca.svg \"Repobeats analytics image\")\n\n## Citing Sinergym\n\nIf you use *Sinergym* in your work, please cite our [paper](https://dl.acm.org/doi/abs/10.1145/3486611.3488729):\n\n```bibtex\n@article{Campoy2025sinergym,\n title = {Sinergym \u2013 A virtual testbed for building energy optimization with Reinforcement Learning},\n author = {Alejandro Campoy-Nieves and Antonio Manjavacas and Javier Jim\u00e9nez-Raboso and Miguel Molina-Solana and Juan G\u00f3mez-Romero},\n journal = {Energy and Buildings},\n volume = {327},\n articleno = {115075},\n year = {2025},\n issn = {0378-7788},\n doi = {10.1016/j.enbuild.2024.115075},\n url = {https://www.sciencedirect.com/science/article/pii/S0378778824011915},\n}\n```\n\nFor detailed information, please refer to the [documentation](https://ugr-sail.github.io/sinergym/compilation/main/index.html).\n\n# Installation\n\n*Sinergym* relies on several dependencies, the specifics of which vary by version.\n\nThe table below provides a summary of the dependencies versions supported by *Sinergym* across its releases:\n\n| **Sinergym version** | **Ubuntu version** | **Python version** | **EnergyPlus version** | **Building model file** |\n| -------------------- | ------------------ | ------------------ | ---------------------- | ----------------------- |\n| **0.0** | 18.04 LTS | 3.6 | 8.3.0 | IDF |\n| **1.1.0** | 18.04 LTS | 3.6 | **9.5.0** | IDF |\n| **1.7.0** | 18.04 LTS | **3.9** | 9.5.0 | IDF |\n| **1.9.5** | **22.04 LTS** | **3.10.6** | 9.5.0 | IDF |\n| **2.4.0** | 22.04 LTS | 3.10.6 | 9.5.0 | **epJSON** |\n| **2.5.0** | 22.04 LTS | 3.10.6 | **23.1.0** | epJSON |\n| **3.3.6** | **24.04 LTS** | **3.12.3** | 23.1.0 | epJSON |\n| **3.5.8** | 24.04 LTS | 3.12.3 | **24.1.0** | epJSON |\n\n\nWe recommend to always use the latest version of *Sinergym* that is supported by the container. This will help you to avoid the complexities of manual installation.\nHowever, if you prefer to manually install *Sinergym* on your computer, we provide the necessary documentation in the subsequent sections.\n\n## Docker container\n\nWe provide a **Dockerfile** to install all dependencies and prepare the image for running *Sinergym*. This is the **recommended** option, since it\nensures that all dependencies and versions are correctly installed and configured.\n\nThis Dockerfile installs the compatible operating system, EnergyPlus, Python, and *Sinergym*, along with the necessary dependencies for its proper functioning. \n\nIf you have cloned the repository, run the following command:\n\n```bash\n$ docker build -t <tag_name> .\n```\n\n*Sinergym* has a set of optional dependencies that enhance its usage. These dependencies can be installed in the following way when building the image:\n\n```bash\n$ docker build -t <tag_name> --build-arg SINERGYM_EXTRAS=\"drl notebooks gcloud\" .\n```\n\nThese optional dependencies allow you to use `stable-baselines3`, `wandb`, `notebooks` and `gcloud`. For more information, please refer to the `pyproject.toml` file at the root of the repository (``[tool.poetry.extras]`` section). \n\nIf you want to install all optional packages, use `extras` in the `SINERGYM_EXTRAS` argument.\n\n> :memo: **Note:** the container can also be directly installed from the [Docker Hub repository](https://hub.docker.com/repository/docker/sailugr/sinergym). It contains all the project's releases with secondary dependencies or lite versions.\n\nOnce the container image is ready, you can execute any command as follows:\n\n```bash\n$ docker run -it --rm <tag_name> <command>\n```\n\nBy default, the command executed is `python scripts/try_env.py`, which is a minimal working example.\n\nIf you want to run a DRL experiment, for example, you can do it like this:\n\n```bash\n$ docker build -t example/sinergym:latest --build-arg SINERGYM_EXTRAS=\"drl\" .\n$ docker run -e WANDB_API_KEY=$WANDB_API_KEY -it --rm example/sinergym:latest python scripts/train/train_agent.py -conf scripts/train/train_agent_PPO.json\n```\n\nIf the script you want to use requires a Weights and Biases account, remember to include the corresponding API token in a container environment variable.\n\nIt is also possible to keep an open session in the image. For more information, please refer to the official Docker documentation. This may help to run your own scripts in the container.\n\n```bash\n$ docker run -it <tag_name> /bin/bash\n```\n\n> :memo: **Note:** For [Visual Studio Code](https://code.visualstudio.com/) users, simply open the root directory and click the *Reopen in container* pop-up button. This will automatically install all dependencies and enable you to run *Sinergym* in an isolated environment. For more details about this feature, refer to the [VSCode Containers extension documentation](https://code.visualstudio.com/docs/remote/containers).\n\n## Manual installation\n\nIf you prefer not to use containers and install it natively on your system, we provide some guidance on how to do it.\n\nFirst, ensure that your system meets the previously specified software compatibility requirements. Without this, we cannot provide support or guarantees of functionality.\n\n### Configure Python Environment\n\nStart by installing the desired version of Python and *pip*. It is recommended to set up a working environment for Python. Finally, install the necessary dependencies of *Sinergym* in that environment:\n\n```sh\n$ pip install sinergym\n```\n\nYou can also install the optional packages by running:\n\n```sh\n$ pip install sinergym[extras]\n```\n\nTo directly install *Sinergym* from the cloned repository, run:\n\n```sh\n$ poetry install --no-interaction --only main --extras <optional_extras>\n# or\n$ pip install .[<optional_extras>]\n```\n\nNow the correct Python version and the necessary modules to run *Sinergym* will be installed.\n\nLet's now proceed with the installation of external software.\n\n### Install EnergyPlus\n\nWe have tested and confirmed compatibility with **EnergyPlus** version `24.1.0`. *Sinergym* might not work with other non-tested versions.\n\nFollow the instructions detailed [here](https://energyplus.net/downloads) to install it in Linux (we only guarantee proper testing and support for **Ubuntu**). \n\nAfter installation, the folder `Energyplus-24-1-0` should appear in the selected location.\n\n### Include EnergyPlus Python API in Python path\n\n*Sinergym* relies on the *Energyplus* Python API. The modules of this API are located in the *EnergyPlus* folder that was created in the previous step. You must add this installation path to the `PYTHONPATH` environment variable so that the interpreter can access these modules.\n\n## Develop in Sinergym\n\nWhether you have chosen to use Docker or a manual installation, we offer facilities for developing and contributing to *Sinergym*.\n\n- If you have used a container, Visual Studio Code will set up a development environment with all the necessary packages automatically configured, including documentation, tests, etc.\n\n- If you have decided to use a container without Visual Studio Code, you can use the Dockerfile available in the `.devcontainer` folder instead of the one in the root of the repository. If you create your own Dockerfile, make sure to perform the following installation so that all development modules are available:\n\n```dockerfile\nRUN poetry install --no-interaction\n```\n\nThe default installation includes all development packages. To avoid this, you should specify `--only main` or `--without <develop_groups>`. The development groups can also be found \nin `pyproject.toml`.\n\nIf you have manually installed the project, you can install the development packages from **poetry** in the same way. Once the repository is cloned, run:\n\n```sh\n$ poetry install --no-interaction\n```\n\nThe command is similar to the one shown in the manual installation section, but without specifying groups or extras, so that all development packages are installed. In this case,\nit is not possible to use *pip* because it does not include information about development dependencies (except those listed in *extras*).\n\n> :memo: For more information about how poetry dependencies work, visit its [official documentation](https://python-poetry.org/docs/dependency-specification/).\n\n\n## Verify Installation\n\nThis project is automatically monitored using **tests**. To verify that *Sinergym* has been installed correctly, execute `pytest tests/ -vv` from the repository root directory. Tests dependencies should have been previously installed.\n\nEach time the *Sinergym* repository is updated, the tests are automatically executed in a remote container built using the Dockerfile. This task is performed via [Github actions](https://docs.github.com/es/actions/) (refer to the `Github actions` documentation section for additional details).\n\n## Cloud Computing\n\nWe provide some features to execute experiments in [Google Cloud](https://cloud.google.com/). For more information visit the `Google Cloud integration` section of the documentation.\n# Contributor Covenant Code of Conduct\n\n## Our Pledge\n\nWe as members, contributors, and leaders pledge to make participation in our\ncommunity a harassment-free experience for everyone, regardless of age, body\nsize, visible or invisible disability, ethnicity, sex characteristics, gender\nidentity and expression, level of experience, education, socio-economic status,\nnationality, personal appearance, race, religion, or sexual identity\nand orientation.\n\nWe pledge to act and interact in ways that contribute to an open, welcoming,\ndiverse, inclusive, and healthy community.\n\n## Our Standards\n\nExamples of behavior that contributes to a positive environment for our\ncommunity include:\n\n* Demonstrating empathy and kindness toward other people\n* Being respectful of differing opinions, viewpoints, and experiences\n* Giving and gracefully accepting constructive feedback\n* Accepting responsibility and apologizing to those affected by our mistakes,\n and learning from the experience\n* Focusing on what is best not just for us as individuals, but for the\n overall community\n\nExamples of unacceptable behavior include:\n\n* The use of sexualized language or imagery, and sexual attention or\n advances of any kind\n* Trolling, insulting or derogatory comments, and personal or political attacks\n* Public or private harassment\n* Publishing others' private information, such as a physical or email\n address, without their explicit permission\n* Other conduct which could reasonably be considered inappropriate in a\n professional setting\n\n## Enforcement Responsibilities\n\nCommunity leaders are responsible for clarifying and enforcing our standards of\nacceptable behavior and will take appropriate and fair corrective action in\nresponse to any behavior that they deem inappropriate, threatening, offensive,\nor harmful.\n\nCommunity leaders have the right and responsibility to remove, edit, or reject\ncomments, commits, code, wiki edits, issues, and other contributions that are\nnot aligned to this Code of Conduct, and will communicate reasons for moderation\ndecisions when appropriate.\n\n## Scope\n\nThis Code of Conduct applies within all community spaces, and also applies when\nan individual is officially representing the community in public spaces.\nExamples of representing our community include using an official e-mail address,\nposting via an official social media account, or acting as an appointed\nrepresentative at an online or offline event.\n\n## Enforcement\n\nInstances of abusive, harassing, or otherwise unacceptable behavior may be\nreported to the community leaders responsible for enforcement at\n[INSERT CONTACT METHOD].\nAll complaints will be reviewed and investigated promptly and fairly.\n\nAll community leaders are obligated to respect the privacy and security of the\nreporter of any incident.\n\n## Enforcement Guidelines\n\nCommunity leaders will follow these Community Impact Guidelines in determining\nthe consequences for any action they deem in violation of this Code of Conduct:\n\n### 1. Correction\n\n**Community Impact**: Use of inappropriate language or other behavior deemed\nunprofessional or unwelcome in the community.\n\n**Consequence**: A private, written warning from community leaders, providing\nclarity around the nature of the violation and an explanation of why the\nbehavior was inappropriate. A public apology may be requested.\n\n### 2. Warning\n\n**Community Impact**: A violation through a single incident or series\nof actions.\n\n**Consequence**: A warning with consequences for continued behavior. No\ninteraction with the people involved, including unsolicited interaction with\nthose enforcing the Code of Conduct, for a specified period of time. This\nincludes avoiding interactions in community spaces as well as external channels\nlike social media. Violating these terms may lead to a temporary or\npermanent ban.\n\n### 3. Temporary Ban\n\n**Community Impact**: A serious violation of community standards, including\nsustained inappropriate behavior.\n\n**Consequence**: A temporary ban from any sort of interaction or public\ncommunication with the community for a specified period of time. No public or\nprivate interaction with the people involved, including unsolicited interaction\nwith those enforcing the Code of Conduct, is allowed during this period.\nViolating these terms may lead to a permanent ban.\n\n### 4. Permanent Ban\n\n**Community Impact**: Demonstrating a pattern of violation of community\nstandards, including sustained inappropriate behavior, harassment of an\nindividual, or aggression toward or disparagement of classes of individuals.\n\n**Consequence**: A permanent ban from any sort of public interaction within\nthe community.\n\n## Attribution\n\nThis Code of Conduct is adapted from the [Contributor Covenant][homepage],\nversion 2.0, available at\n[https://www.contributor-covenant.org/version/2/0/code_of_conduct.html][v2.0].\n\nCommunity Impact Guidelines were inspired by \n[Mozilla's code of conduct enforcement ladder][Mozilla CoC].\n\nFor answers to common questions about this code of conduct, see the FAQ at\n[https://www.contributor-covenant.org/faq][FAQ]. Translations are available \nat [https://www.contributor-covenant.org/translations][translations].\n\n[homepage]: https://www.contributor-covenant.org\n[v2.0]: https://www.contributor-covenant.org/version/2/0/code_of_conduct.html\n[Mozilla CoC]: https://github.com/mozilla/diversity\n[FAQ]: https://www.contributor-covenant.org/faq\n[translations]: https://www.contributor-covenant.org/translations\nMIT License\n\nCopyright (c) 2024, A. Campoy, A. Manjavacas, J. Jim\u00e9nez, M. Molina, J. G\u00f3mez\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Sinergym provides a Gymnasium-based interface to interact with building simulations. This allows control in simulation time through custom controllers, including reinforcement learning agents",
"version": "3.7.0",
"project_urls": {
"Documentation": "https://ugr-sail.github.io/sinergym",
"Homepage": "https://github.com/ugr-sail/sinergym",
"Repository": "https://github.com/ugr-sail/sinergym"
},
"split_keywords": [
"reinforcement-learning",
" buildings",
" simulation",
" control",
" reinforcement-learning-environments"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3dced4bbd77b3aac6681508619c0762bc4af917ddba3959be628541b83721193",
"md5": "fcd3b56d0b7ca8a14307cfac0119e207",
"sha256": "166f3c7ae768cc67f9776dcfc3e33311caea7357639f10abb7830d60d22c151e"
},
"downloads": -1,
"filename": "sinergym-3.7.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fcd3b56d0b7ca8a14307cfac0119e207",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.12",
"size": 3441451,
"upload_time": "2024-12-11T11:58:07",
"upload_time_iso_8601": "2024-12-11T11:58:07.087758Z",
"url": "https://files.pythonhosted.org/packages/3d/ce/d4bbd77b3aac6681508619c0762bc4af917ddba3959be628541b83721193/sinergym-3.7.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f093e5c73586a138f1e10b8594ac686e63d17dfee0fbd3d1b790e167307fffbe",
"md5": "a2ab4c75d64d25cafbfdb41883304ff8",
"sha256": "5c672833786b32b7cf9eb66de62efcb169b83aeef464ad91ddcd0e0867e57cc3"
},
"downloads": -1,
"filename": "sinergym-3.7.0.tar.gz",
"has_sig": false,
"md5_digest": "a2ab4c75d64d25cafbfdb41883304ff8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.12",
"size": 3279307,
"upload_time": "2024-12-11T11:58:09",
"upload_time_iso_8601": "2024-12-11T11:58:09.444478Z",
"url": "https://files.pythonhosted.org/packages/f0/93/e5c73586a138f1e10b8594ac686e63d17dfee0fbd3d1b790e167307fffbe/sinergym-3.7.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-11 11:58:09",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ugr-sail",
"github_project": "sinergym",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "sinergym"
}
JSON
