{"id":30957264,"url":"https://github.com/tobirohrer/building-energy-storage-simulation","last_synced_at":"2025-09-11T13:45:07.204Z","repository":{"id":65083109,"uuid":"564235838","full_name":"tobirohrer/building-energy-storage-simulation","owner":"tobirohrer","description":"An open source playground energy storage environment to explore reinforcement learning and model predictive control.","archived":false,"fork":false,"pushed_at":"2024-01-15T19:24:16.000Z","size":1627,"stargazers_count":54,"open_issues_count":6,"forks_count":11,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-09-07T21:59:25.655Z","etag":null,"topics":["energy-storage","energy-storage-systems","gym","gymnasium","model-predictive-control","optimal-control","reinforcement-learning","solar-energy"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tobirohrer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2022-11-10T09:36:08.000Z","updated_at":"2025-07-31T16:44:49.000Z","dependencies_parsed_at":"2023-02-15T22:45:47.185Z","dependency_job_id":"797cce98-6388-4c52-bd87-bb123b895049","html_url":"https://github.com/tobirohrer/building-energy-storage-simulation","commit_stats":{"total_commits":59,"total_committers":1,"mean_commits":59.0,"dds":0.0,"last_synced_commit":"05b9197c8d6f600bed2a5b092db6de6f07bf3c65"},"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/tobirohrer/building-energy-storage-simulation","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tobirohrer%2Fbuilding-energy-storage-simulation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tobirohrer%2Fbuilding-energy-storage-simulation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tobirohrer%2Fbuilding-energy-storage-simulation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tobirohrer%2Fbuilding-energy-storage-simulation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tobirohrer","download_url":"https://codeload.github.com/tobirohrer/building-energy-storage-simulation/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tobirohrer%2Fbuilding-energy-storage-simulation/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274648319,"owners_count":25324299,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-11T02:00:13.660Z","response_time":74,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["energy-storage","energy-storage-systems","gym","gymnasium","model-predictive-control","optimal-control","reinforcement-learning","solar-energy"],"created_at":"2025-09-11T13:45:06.120Z","updated_at":"2025-09-11T13:45:07.189Z","avatar_url":"https://github.com/tobirohrer.png","language":"Python","funding_links":[],"categories":["Reinforcement Learning (RL) and Deep Reinforcement Learning (DRL)"],"sub_categories":["RL/DRL Environments"],"readme":"# Building Energy Storage Simulation\n\n\u003cimg src=\"docs/imgs/overview.drawio.png\" alt=\"isolated\" width=\"600\"/\u003e\n\nThe Building Energy Storage Simulation serves as an OpenAI gym (now [gymnasium](https://github.com/Farama-Foundation/Gymnasium)) environment \nfor Reinforcement Learning. The environment represents a building with an energy storage (in the form of a battery) and a \nsolar energy system. The building is connected to a power grid with time-varying electricity prices. The task is to \ncontrol the energy storage so that the total cost of electricity is minimized.\n\nThe inspiration for this project and the data profiles come from the [CityLearn](https://github.com/intelligent-environments-lab/CityLearn) environment. Anyhow, this project focuses on the ease of usage and the simplicity of its implementation. Therefore, this project serves as a playground for those who want to get started with reinforcement learning for energy management system control.\n\n## Installation\n\nBy using pip just: \n\n```\npip install building-energy-storage-simulation\n```\n\nor if you want to continue developing the package:\n\n```\ngit clone https://github.com/tobirohrer/building-energy-storage-simulation.git \u0026\u0026 cd building-energy-storage-simulation\npip install -e .[dev]\n```\n\n## Usage\n\n```python\nfrom building_energy_storage_simulation import Environment, BuildingSimulation\n\nsimulation = BuildingSimulation()\nenv = Environment(building_simulation=simulation)\n\nenv.reset()\nenv.step(1)\n...\n```\n\n**Important note:** This environment is implemented by using [gymnasium](https://github.com/Farama-Foundation/Gymnasium) (the proceeder of OpenAI gym). Meaning, if you are using a reinforcement learning library like [Stable Baselines3](https://github.com/DLR-RM/stable-baselines3) make sure it supports [gymnasium](https://github.com/Farama-Foundation/Gymnasium) environments. \n\n## Task Description\n\nThe simulation contains a building with an energy load profile attached to it. The load is always automatically covered by\n\n- primarily using electricity generated by the solar energy system,\n- and secondary by using the remaining required electricity \"from the grid\"\n\nWhen energy is taken from the grid, costs are incurred that can vary depending on the time (if a price profile is passed\nas `electricity_price` to `BuildingSimulation`). The simulated building contains a battery that be controlled by \n**charging** and **discharging** energy. The goal is to find control strategies to optimize the use of energy storage\nby e.g. charging whenever electricity prices are high or whenever there is a surplus of solar generation. It is important \nto note that no energy can be fed into the grid. This means any surplus of solar energy which is not used to charge the\nbattery is considered lost.\n\n### Reward\n\n$$r_t = -1 * electricity\\\\_consumed_t * electricity\\\\_price_t $$ \n\nNote, that the term `electricity_consumed` cannot be negative. This means excess energy from the solar \nenergy system which is not consumed by the electricity load or by charging the battery is considered lost \n(`electricity_consumed` is 0 in this case). \n \n### Action Space\n\n| Action   | Min      | Max    |\n|----------|----------|--------|\n| Charge   | -1       | 1      |\n\nThe actions lie in the interval of [-1;1]. The action represents a fraction of the maximum energy that can be retrieved from the battery (or used to charge the battery) per time step.\n\n- 1 means maximum charging the battery. The maximum charge per time step is defined by the parameter `max_battery_charge_per_timestep`.\n- -1 means maximum discharging the battery, meaning \"gaining\" electricity out of the battery\n- 0 means don't charge or discharge\n\n### Observation Space\n\n| Index       | Observation                           | Min                       | Max                          |\n|-------------|---------------------------------------|---------------------------|------------------------------|\n| 0           | State of Charge (in kWh)              | 0                         | `battery_capacity`           |\n| [1; n]      | Forecast Electric Load (in kWh)       | Min of Load Profile       | Max of Load Profile          |\n| [n+1; 2*n]  | Forecast Solar Generation (in kWh)    | Min of Generation Profile | Max of Generation Profile    |\n| [2n+1; 3*n] | Electricity Price (in € cent per kWh) | Min of Price Profile      | Max of Price Profile         |\n\n\nThe length of the observation depends on the length of the forecast ($n$) used. By default, the simulation uses a forecast length of 4. \nThis means 4 time steps of an electric load forecast, 4 time steps of a solar generation forecast, and 4 time steps of the \nelectric price profiles are included in the observation. \nIn addition to that, the information about the current state of charge of the battery is contained in the observation.\n\nThe length of the forecast can be defined by setting the parameter `num_forecasting_steps` of the `Environment()`.\n\n\n### Episode Ends\n\nThe episode ends if the `max_timesteps` of the `Environment()` are reached.\n\n## Example Solutions\n\nThe folder [example_solutions](example_solutions) contains three different example solutions to solve the problem \ndescribed.\n\n1. By applying deep reinforcement learning using the framework [stable-baselines3](https://github.com/DLR-RM/stable-baselines3).\n2. By formulating the problem as an optimal control problem (OCP) using [pyomo](http://www.pyomo.org/). In this case, it \n   is assumed that the forecast for the price, load, and generation data for the whole period is available. \n3. By model predictive control, which solves the optimal control problem formulation from 2. in each time step in a closed loop manner.\n   In contrast to 2. only a forecast of a fixed length is given in each iteration. \n\nNote that the execution of the example solutions requires additional dependencies which are not specified inside `setup.py`. \nTherefore, make sure to install the required Python packages defined in `requirements.txt`. Additionally, an installation \nof the `ipopt` solver is required to solve the optimal control problem \n(by using conda, simply run `conda install -c conda-forge ipopt`). \n\n## Code Documentation\n\nThe documentation is available at [https://building-energy-storage-simulation.readthedocs.io/](https://building-energy-storage-simulation.readthedocs.io/en/master/)\n\n## Contribute \u0026 Contact\n\nAs I just started with this project, I am very happy for any kind of\ncontribution! In case you want to contribute, or if you have any\nquestions, contact me via\n[discord](https://discord.com/users/tobirohrer#8654).\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftobirohrer%2Fbuilding-energy-storage-simulation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftobirohrer%2Fbuilding-energy-storage-simulation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftobirohrer%2Fbuilding-energy-storage-simulation/lists"}