# Sinergym
<div align="center">
<img src="images/logo.png" width=40%><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>
**Welcome to Sinergym!**
<div align="center">
<img src="images/general_blueprint.png" width=80%><br><br>
</div>
The goal of this project is to create an environment following *Gymnasium* interface for wrapping
simulation engines (*EnergyPlus*) for building control using **deep reinforcement learning**
or any external control.
For more information about Sinergym, please visit our [documentation](https://ugr-sail.github.io/sinergym/compilation/main/index.html).
To report questions and issues, please use our [issue tracker](https://github.com/ugr-sail/sinergym/issues). We appreciate your feedback and contributions. Check out our [CONTRIBUTING.md](https://github.com/ugr-sail/sinergym/blob/main/CONTRIBUTING.md) for more details on how to contribute.
The main functionalities of *Sinergym* are the following:
- **Simulation Engine Compatibility**: Uses [EnergyPlus Python API](https://energyplus.readthedocs.io/en/latest/api.html) for Python-EnergyPlus communication. Future plans include more engines like [OpenModelica](https://openmodelica.org/).
- **Benchmark Environments**: Designs environments for benchmarking and testing deep RL algorithms or other external strategies, similar to *Atari* or *Mujoco*.
- **Customizable Environments**: Allows easy modification of experimental settings. Users can create their own environments or modify pre-configured ones in *Sinergym*.
- **Customizable Components**: Enables creation of new custom components for new environments, making *Sinergym* scalable, such as function rewards, wrappers, controllers, etc.
- **Automatic Building Model Adaptation**: *Sinergym* automates the process of adapting the building model to user changes in the environment definition.
- **Automatic Actuators Control**: Controls actuators through the Gymnasium interface based on user specification, only actuators names are required and *Sinergym* will do the rest.
- **Extensive Environment Information**: Provides comprehensive information about *Sinergym* background components from the environment interface.
- **Stable Baseline 3 Integration**: Customizes functionalities for easy testing of environments with SB3 algorithms, such as callbacks and customizable training real-time logging. However, *Sinergym* is agnostic to any DRL algorithm.
- **Google Cloud Integration**: Offers guidance on using *Sinergym* with Google Cloud infrastructure.
- **Weights & Biases Compatibility**: Automates and facilitates training, reproducibility, and comparison of agents in simulation-based building control problems. [WandB](https://wandb.ai/site) assists in managing and monitoring model lifecycle.
- **Notebook Examples**: Provides code in notebook format for user familiarity with the tool.
- **Extensive Documentation, Unit Tests, and GitHub Actions Workflows**: Ensures *Sinergym* is an efficient ecosystem for understanding and development.
- And much more!
_This is a project in active development. Stay tuned for upcoming releases._
<div align="center">
<img src="images/operation_diagram.png"><br><br>
</div>
## Project Structure
This repository is organized into the following directories:
- `sinergym/`: Contains the source code for *Sinergym*, including the environment, modeling, simulator, and tools such as wrappers and reward functions.
- `docs/`: Online documentation generated with Sphinx and using Restructured Text (RST).
- `examples/`: Jupyter notebooks illustrating use cases with Sinergym.
- `tests/`: Unit tests for Sinergym to ensure stability.
- `scripts/`: Scripts for various tasks such as agent training and performance checks, allowing configuration using JSON format.
## 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
Please visit [INSTALL.md](https://github.com/ugr-sail/sinergym/blob/main/INSTALL.md) for detailed installation instructions.
## Usage example
If you used our Dockerfile during installation, you should have the *try_env.py* file in your workspace as soon as you enter in. In case you have installed everything on your local machine directly, place it inside our cloned repository. In any case, we start from the point that you have at your disposal a terminal with the appropriate python version and *Sinergym* running correctly.
*Sinergym* uses the standard Gymnasium API. So a basic loop should look like:
```python
import gymnasium as gym
import sinergym
# Create the environment
env = gym.make('Eplus-datacenter-mixed-continuous-stochastic-v1')
# Initialize the episode
obs, info = env.reset()
truncated = terminated = False
R = 0.0
while not (terminated or truncated):
a = env.action_space.sample() # random action selection
obs, reward, terminated, truncated, info = env.step(a) # get new observation and reward
R += reward
print('Total reward for the episode: %.4f' % R)
env.close()
```
A folder will be created in the working directory after creating the environment. It will contain the Sinergym outputs produced during the simulation.
For more examples and details, please visit our [usage examples](https://ugr-sail.github.io/sinergym/compilation/main/pages/notebooks/basic_example.html#Basic-example) documentation section.
## Google Cloud Platform support
For more information about this functionality, please, visit our documentation [here](https://ugr-sail.github.io/sinergym/compilation/main/pages/gcloudAPI.html#sinergym-with-google-cloud).
## Projects using Sinergym
The following are some of the projects benefiting from the advantages of 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)
:pencil: If you want to appear in this list, do not hesitate to send us a PR 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>
## Repo 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
@inproceedings{2021sinergym,
title={Sinergym: A Building Simulation and Control Framework for Training Reinforcement Learning Agents},
author={Jiménez-Raboso, Javier and Campoy-Nieves, Alejandro and Manjavacas-Lucas, Antonio and Gómez-Romero, Juan and Molina-Solana, Miguel},
year={2021},
isbn = {9781450391146},
publisher = {Association for Computing Machinery},
address = {New York, NY, USA},
url = {https://doi.org/10.1145/3486611.3488729},
doi = {10.1145/3486611.3488729},
booktitle = {Proceedings of the 8th ACM International Conference on Systems for Energy-Efficient Buildings, Cities, and Transportation},
pages = {319–323},
numpages = {5},
}
```
For more detailed information, please visit our [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 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 always using the latest version of *Sinergym* that is supported by the container.
This approach helps you avoid the complexities of the installation process. 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.
In essence, 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, it can be used as follows:
```bash
$ docker build -t <tag_name> .
```
However, Sinergym has a set of optional dependencies that enhance the tool's usage. These
dependencies can be installed in the following way when building the image:
```bash
$ docker build -t <tag_name> --build-arg SINERGYM_EXTRAS=format,test,doc,DRL,gcloud .
```
These optional dependencies allow you to format code, run tests, generate documentation,
have pre-existing DRL algorithms available, etc. For more information, please refer to
the `pyproject.toml` file at the root of the repository. If you desire to install all optional
packages, you can use `dev` directly in the `SINERGYM_EXTRAS` argument.
> :memo: **Note:** Our 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,platforms .
$ 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 WandB account, remember to include the environment variable
in the container with the token.
It’s also possible to keep a session open in the image to copy and run your own scripts. For more
information, please refer to the Docker documentation. This can be useful when you want 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 on the *Reopen in container* pop-up button. This action will automatically install all dependencies and enable you to run *Sinergym* in an isolated environment. For more details on 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 have everything installed natively on your system, we’ll explain
how to do it.
First, make sure that you meet the compatibility matrix; otherwise, no support or guarantees of
functionality will be provided by the development team.
### Configure Python Environment
Start by installing the desired version of Python and pip. It is recommended to set up a working
environment for Python (multiple options are available). Finally, install the necessary
dependencies for Sinergym in that environment:
```sh
$ pip install sinergym
```
You can also install the optional packages from here, just like in the Docker container:
```sh
$ pip install sinergym[format,test,doc,DRL,gcloud]
```
If you want to install the cloned repository directly, you can do so by running the following
command in its root.
```sh
$ poetry install --with format,test,doc,DRL,gcloud
```
With this, you have the correct Python version and the necessary modules to run
*Sinergym*. Let's proceed with the installation of other required programs
outside of Python to run the simulations.
### Install EnergyPlus 24.1.0
You need to install *EnergyPlus*. We have tested and confirmed compatibility
with version `24.1.0`. The code might work with other versions, but we
have not tested them.
Follow the instructions [here](https://energyplus.net/downloads) to install
it for Linux (we only support **Ubuntu**). You can choose any location for the
installation. After installation, a folder named `Energyplus-24-1-0` should
appear in the chosen location.
### Include Energyplus Python API in Python Path
*Sinergym* uses the *Energyplus* Python API as its backend. The modules of this
API are located in the *Energyplus* folder that you installed in the previous
step. You must add this installation path to the `PYTHONPATH` environment
variable so that the interpreter can access these modules.
## Verify Installation
This project is automatically monitored using **tests** specifically developed for it.
To verify that *Sinergym* has been installed correctly, execute `pytest tests/ -vv`
in the **repository root**.
Furthermore, each time the *Sinergym* repository is updated, the tests are automatically executed in a remote container
built using the Dockerfile. This task is performed by [Github Action](https://docs.github.com/es/actions/)
(refer to the `Github Actions` section for more details).
## Cloud Computing
You also have the option to run your experiments in the Cloud. We utilize [Google Cloud](https://cloud.google.com/)
for this purpose. Our team is working on setting up an account to run our *Sinergym* container
with **remote storage** and **Weights&Biases tracking**.
For more information on installation and preparing the Google Cloud SDK to run your experiments,
please visit our `Preparing Google Cloud` section.
# 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) 2021 Javier Jiménez
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/ff/ef/0647e3220d4627da9e0be3f8bb4817b267da81de20d36b979ee0914394fa/sinergym-3.6.0.tar.gz",
"platform": null,
"description": "# Sinergym\n\n<div align=\"center\">\n <img src=\"images/logo.png\" width=40%><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**Welcome to Sinergym!**\n\n<div align=\"center\">\n <img src=\"images/general_blueprint.png\" width=80%><br><br>\n</div>\n\nThe goal of this project is to create an environment following *Gymnasium* interface for wrapping \nsimulation engines (*EnergyPlus*) for building control using **deep reinforcement learning** \nor any external control.\n\nFor more information about Sinergym, please visit our [documentation](https://ugr-sail.github.io/sinergym/compilation/main/index.html).\n\nTo report questions and issues, please use our [issue tracker](https://github.com/ugr-sail/sinergym/issues). We appreciate your feedback and contributions. Check out our [CONTRIBUTING.md](https://github.com/ugr-sail/sinergym/blob/main/CONTRIBUTING.md) for more details on how to contribute.\n\nThe main functionalities of *Sinergym* are the following:\n\n- **Simulation Engine Compatibility**: Uses [EnergyPlus Python API](https://energyplus.readthedocs.io/en/latest/api.html) for Python-EnergyPlus communication. Future plans include more engines like [OpenModelica](https://openmodelica.org/).\n\n- **Benchmark Environments**: Designs environments for benchmarking and testing deep RL algorithms or other external strategies, similar to *Atari* or *Mujoco*.\n\n- **Customizable Environments**: Allows easy modification of experimental settings. Users can create their own environments or modify pre-configured ones in *Sinergym*.\n\n- **Customizable Components**: Enables creation of new custom components for new environments, making *Sinergym* scalable, such as function rewards, wrappers, controllers, etc.\n\n- **Automatic Building Model Adaptation**: *Sinergym* automates the process of adapting the building model to user changes in the environment definition.\n\n- **Automatic Actuators Control**: Controls actuators through the Gymnasium interface based on user specification, only actuators names are required and *Sinergym* will do the rest.\n\n- **Extensive Environment Information**: Provides comprehensive information about *Sinergym* background components from the environment interface.\n\n- **Stable Baseline 3 Integration**: Customizes functionalities for easy testing of environments with SB3 algorithms, such as callbacks and customizable training real-time logging. However, *Sinergym* is agnostic to any DRL algorithm.\n\n- **Google Cloud Integration**: Offers guidance on using *Sinergym* with Google Cloud infrastructure.\n\n- **Weights & Biases Compatibility**: Automates and facilitates training, reproducibility, and comparison of agents in simulation-based building control problems. [WandB](https://wandb.ai/site) assists in managing and monitoring model lifecycle.\n\n- **Notebook Examples**: Provides code in notebook format for user familiarity with the tool.\n\n- **Extensive Documentation, Unit Tests, and GitHub Actions Workflows**: Ensures *Sinergym* is an efficient ecosystem for understanding and development.\n\n- And much more!\n\n_This is a project in active development. Stay tuned for upcoming releases._\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/`: Contains the source code for *Sinergym*, including the environment, modeling, simulator, and tools such as wrappers and reward functions.\n- `docs/`: Online documentation generated with Sphinx and using Restructured Text (RST).\n- `examples/`: Jupyter notebooks illustrating use cases with Sinergym.\n- `tests/`: Unit tests for Sinergym to ensure stability.\n- `scripts/`: Scripts for various tasks such as agent training and performance checks, allowing configuration using JSON format.\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\nPlease visit [INSTALL.md](https://github.com/ugr-sail/sinergym/blob/main/INSTALL.md) for detailed installation instructions.\n\n## Usage example\n\n\nIf you used our Dockerfile during installation, you should have the *try_env.py* file in your workspace as soon as you enter in. In case you have installed everything on your local machine directly, place it inside our cloned repository. In any case, we start from the point that you have at your disposal a terminal with the appropriate python version and *Sinergym* running correctly.\n\n*Sinergym* uses the standard Gymnasium API. So a basic loop should look like:\n\n```python\n\nimport gymnasium as gym\nimport sinergym\n# Create the environment\nenv = gym.make('Eplus-datacenter-mixed-continuous-stochastic-v1')\n# Initialize the episode\nobs, info = env.reset()\ntruncated = terminated = False\nR = 0.0\nwhile not (terminated or truncated):\n a = env.action_space.sample() # random action selection\n obs, reward, terminated, truncated, info = env.step(a) # get new observation and reward\n R += reward\nprint('Total reward for the episode: %.4f' % R)\nenv.close()\n```\n\nA folder will be created in the working directory after creating the environment. It will contain the Sinergym outputs produced during the simulation.\n\nFor more examples and details, please visit our [usage examples](https://ugr-sail.github.io/sinergym/compilation/main/pages/notebooks/basic_example.html#Basic-example) documentation section.\n\n\n## Google Cloud Platform support\n\nFor more information about this functionality, please, visit our documentation [here](https://ugr-sail.github.io/sinergym/compilation/main/pages/gcloudAPI.html#sinergym-with-google-cloud).\n\n## Projects using Sinergym\n\nThe following are some of the projects benefiting from the advantages of 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:pencil: If you want to appear in this list, do not hesitate to send us a PR 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## Repo 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@inproceedings{2021sinergym,\n title={Sinergym: A Building Simulation and Control Framework for Training Reinforcement Learning Agents}, \n author={Jim\u00e9nez-Raboso, Javier and Campoy-Nieves, Alejandro and Manjavacas-Lucas, Antonio and G\u00f3mez-Romero, Juan and Molina-Solana, Miguel},\n year={2021},\n isbn = {9781450391146},\n publisher = {Association for Computing Machinery},\n address = {New York, NY, USA},\n url = {https://doi.org/10.1145/3486611.3488729},\n doi = {10.1145/3486611.3488729},\n booktitle = {Proceedings of the 8th ACM International Conference on Systems for Energy-Efficient Buildings, Cities, and Transportation},\n pages = {319\u2013323},\n numpages = {5},\n}\n```\n\nFor more detailed information, please visit our [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. \nThe table below provides a summary of the 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 always using the latest version of *Sinergym* that is supported by the container. \nThis approach helps you avoid the complexities of the installation process. However, \nif you prefer to manually install *Sinergym* on your computer, we provide the necessary \ndocumentation in the subsequent sections.\n\n## Docker container\n\nWe provide a **Dockerfile** to install all dependencies and prepare the \nimage for running *Sinergym*. This is the **recommended** option, since it\nensures that all dependencies and versions are correctly installed and configured.\n\nIn essence, this Dockerfile installs the compatible operating system, EnergyPlus, \nPython, and **Sinergym**, along with the necessary dependencies for its proper functioning. \nIf you have cloned the repository, it can be used as follows:\n\n```bash\n$ docker build -t <tag_name> .\n```\n\nHowever, Sinergym has a set of optional dependencies that enhance the tool's usage. These \ndependencies can be installed in the following way when building the image:\n\n```bash\n$ docker build -t <tag_name> --build-arg SINERGYM_EXTRAS=format,test,doc,DRL,gcloud .\n```\n\nThese optional dependencies allow you to format code, run tests, generate documentation, \nhave pre-existing DRL algorithms available, etc. For more information, please refer to \nthe `pyproject.toml` file at the root of the repository. If you desire to install all optional\npackages, you can use `dev` directly in the `SINERGYM_EXTRAS` argument.\n\n> :memo: **Note:** Our 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,platforms .\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 WandB account, remember to include the environment variable \nin the container with the token.\n\nIt\u2019s also possible to keep a session open in the image to copy and run your own scripts. For more \ninformation, please refer to the Docker documentation. This can be useful when you want to run your \nown 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 on the *Reopen in container* pop-up button. This action will automatically install all dependencies and enable you to run *Sinergym* in an isolated environment. For more details on 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 have everything installed natively on your system, we\u2019ll explain \nhow to do it.\n\nFirst, make sure that you meet the compatibility matrix; otherwise, no support or guarantees of \nfunctionality will be provided by the development team.\n\n### Configure Python Environment\n\nStart by installing the desired version of Python and pip. It is recommended to set up a working \nenvironment for Python (multiple options are available). Finally, install the necessary \ndependencies for Sinergym in that environment:\n\n```sh\n$ pip install sinergym\n```\n\nYou can also install the optional packages from here, just like in the Docker container:\n\n```sh\n$ pip install sinergym[format,test,doc,DRL,gcloud]\n```\n\nIf you want to install the cloned repository directly, you can do so by running the following \ncommand in its root.\n\n```sh\n$ poetry install --with format,test,doc,DRL,gcloud\n```\n\nWith this, you have the correct Python version and the necessary modules to run \n*Sinergym*. Let's proceed with the installation of other required programs \noutside of Python to run the simulations.\n\n### Install EnergyPlus 24.1.0\n\nYou need to install *EnergyPlus*. We have tested and confirmed compatibility \nwith version `24.1.0`. The code might work with other versions, but we \nhave not tested them.\n\nFollow the instructions [here](https://energyplus.net/downloads) to install \nit for Linux (we only support **Ubuntu**). You can choose any location for the \ninstallation. After installation, a folder named `Energyplus-24-1-0` should \nappear in the chosen location.\n\n### Include Energyplus Python API in Python Path\n\n*Sinergym* uses the *Energyplus* Python API as its backend. The modules of this \nAPI are located in the *Energyplus* folder that you installed in the previous \nstep. You must add this installation path to the `PYTHONPATH` environment \nvariable so that the interpreter can access these modules.\n\n\n## Verify Installation\n\nThis project is automatically monitored using **tests** specifically developed for it. \nTo verify that *Sinergym* has been installed correctly, execute `pytest tests/ -vv` \nin the **repository root**.\n\nFurthermore, each time the *Sinergym* repository is updated, the tests are automatically executed in a remote container \nbuilt using the Dockerfile. This task is performed by [Github Action](https://docs.github.com/es/actions/) \n(refer to the `Github Actions` section for more details).\n\n## Cloud Computing\n\nYou also have the option to run your experiments in the Cloud. We utilize [Google Cloud](https://cloud.google.com/) \nfor this purpose. Our team is working on setting up an account to run our *Sinergym* container \nwith **remote storage** and **Weights&Biases tracking**.\nFor more information on installation and preparing the Google Cloud SDK to run your experiments, \nplease visit our `Preparing Google Cloud` section.\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) 2021 Javier Jim\u00e9nez\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": "The goal of sinergym is to create an environment following OpenAI Gym interface for wrapping simulation engines for building control using deep reinforcement learning.",
"version": "3.6.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": "bbdf7fabc8ea7342d5b3e48a7cea6f2bfc6aa4559e997a133960e945a035df24",
"md5": "35ba4354bac0f689a99b43a41b909c60",
"sha256": "1f92f5ec3f20a946782fa6b1865eedadaae3ad488993952028b656fbfbe48160"
},
"downloads": -1,
"filename": "sinergym-3.6.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "35ba4354bac0f689a99b43a41b909c60",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.12",
"size": 3380398,
"upload_time": "2024-09-26T14:42:14",
"upload_time_iso_8601": "2024-09-26T14:42:14.864314Z",
"url": "https://files.pythonhosted.org/packages/bb/df/7fabc8ea7342d5b3e48a7cea6f2bfc6aa4559e997a133960e945a035df24/sinergym-3.6.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ffef0647e3220d4627da9e0be3f8bb4817b267da81de20d36b979ee0914394fa",
"md5": "ae07d1f1f215b6512fbe9a6c81788621",
"sha256": "b00c6d08978843d4ea1631145809eaf4c27cbc40fc2bf275936875f0d449c9bf"
},
"downloads": -1,
"filename": "sinergym-3.6.0.tar.gz",
"has_sig": false,
"md5_digest": "ae07d1f1f215b6512fbe9a6c81788621",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.12",
"size": 3219927,
"upload_time": "2024-09-26T14:42:17",
"upload_time_iso_8601": "2024-09-26T14:42:17.032969Z",
"url": "https://files.pythonhosted.org/packages/ff/ef/0647e3220d4627da9e0be3f8bb4817b267da81de20d36b979ee0914394fa/sinergym-3.6.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-26 14:42:17",
"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
