Energym is an open source building simulation library designed to test climate control and energy management strategies on buildings in a systematic and reproducible way. Energym includes a number of building models that are calibrated on site data and defines standard metrics, quantifying the objective to be reached and allowing a standardized comparison between different controllers and publications.
The library offers an intuitive interface to a variety of building models, similar to the one popularized by the Gym library used in the robotic control community. Energym relies on the functional mockup interface (FMI) standard in order to support models generated in multiple modelling languages easily. It currently includes 14 models developed in Modelica and EnergyPlus as well as specific classes for simulating weather forecasts and appliances consumption figures.
With the models already incorporated, Energym offers the possibility to benchmark controllers on buildings models that are representative of real-world HVAC systems. They cover different buildings typologies (institutional building, office building, etc.) and configuration of the HVAC where control can be performed at different levels (control of energy generation, control of final demand through setpoints, etc.).
New models are under development and will be integrated in due date.
The full documentation (with installation instructions, usage examples, buildings characteristics) is available at Energym
Energym is a toolkit for developing and comparing control algorithms for buildings. It makes no assumptions about the structure of the control algorithms, whose implementation is left up to the user.
The Energym library includes a collection of test problems — environments — that can be used to benchmark algorithms. An environement typically contains one building and all its equipment (heat pumps, chillers, batteries, Photovoltaic installation, etc), and defines the boundary conditions that affect the building, for example the weather patterns. The environments have a shared interface, allowing you to write general algorithms.
Energym allows to apply control inputs to the buildings subsystems, for example temperature setpoints, and to receive information about the current state of the building, including for example zone temperatures, power consumption, etc. The observation can be then used by the controller to adapt the control inputs.
Precompiled FMU files are made available to the user, for both Windows 10 and Linux platforms. The linux files have been tested on Ubuntu 18.04, 20.04 and CentOS 7.
The library runs with EnergyPlus and Modelica. To ensure that FMU models compiled from EnergyPlus models work, please install the following version of EnergyPlus:
- EnergyPlus 9.5 link
Communication between the Python code and the FMU's relies on the package FMPy, which is installed with the default installation.
Firstly git clone the present repository and move inside with cd energym. Then run python setup.py install.
For users willing to use containers, a dockerfile, called Dockerfile, is made available. It creates an Ubuntu 20.04 container, with EnergyPlus 9.5 and Python 3.8. This docker file is not made to compile .idf or .mo files and works with the precompiled FMU's. For this latter particular task, another dockerfile is provided, that downloads a pre-built docker image on dockerhub.
Following environments are available:
| Environment | Thermostat | Heat Pump | Battery | AHU | EV | PV | Software |
|---|---|---|---|---|---|---|---|
Apartments2Thermal-v0 |
✔️ | ✔️ | ✔️ | ❌ | ✔️ | 🔶 | E+ |
Apartments2Grid-v0 |
✔️ | 🔶 | ✔️ | ❌ | ✔️ | 🔶 | E+ |
ApartmentsThermal-v0 |
✔️ | ✔️ | ✔️ | ❌ | ✔️ | 🔶 | E+ |
ApartmentsGrid-v0 |
✔️ | 🔶 | ✔️ | ❌ | ✔️ | 🔶 | E+ |
OfficesThermostat-v0 |
✔️ | ❌ | ❌ | ❌ | ❌ | 🔶 | E+ |
MixedUseFanFCU-v0 |
✔️ | ❌ | ❌ | ✔️ | ❌ | ❌ | E+ |
SeminarcenterThermostat-v0 |
✔️ | 🔶 | ❌ | ❌ | ❌ | 🔶 | E+ |
SeminarcenterFull-v0 |
✔️ | ✔️ | ❌ | ❌ | ❌ | 🔶 | E+ |
SimpleHouseRad-v0 |
❌ | ✔️ | ❌ | ❌ | ❌ | 🔶 | Mod |
SimpleHouseRSla-v0 |
❌ | ✔️ | ❌ | ❌ | ❌ | 🔶 | Mod |
SwissHouseRSlaW2W-v0 |
❌ | ✔️ | ❌ | ❌ | ❌ | 🔶 | Mod |
SwissHouseRSlaA2W-v0 |
❌ | ✔️ | ❌ | ❌ | ❌ | 🔶 | Mod |
SwissHouseRSlaTank-v0 |
❌ | ✔️ | ❌ | ❌ | ❌ | 🔶 | Mod |
SwissHouseRSlaTankDhw-v0 |
❌ | ✔️ | ❌ | ❌ | ❌ | 🔶 | Mod |
✔️ : present and controllable, 🔶 : present but not controllable, ❌ : absent.
Control variables are outlined in yaml files for all environments in the simulation folder. Environment simulations are packed into FMU's for windows and debian distributions.
An examplatory usage of Energym (assuming a function get_input() for computing the controls) looks as follows
import energym
envName = "Apartments2Grid-v0"
nsteps = 10
env = energym.make(envName, simulation_days=100)
obs = env.get_output()
for _ in range(nsteps):
inputs = get_input(obs)
obs = env.step(inputs)
env.close()Examples of using the models can be found here
Every FMU generated by an E+ model specifies certain inputs and outputs. Their format is defined as
zone_type(_device(_sp(_out)))
The different parts of the naming convention refer to:
zone: Specifies the measured location, e.g. building zones (Z01, ...,Z99), the whole buildingBdor the exteriorExt.type: Specifies the measured unit, e.g. the temperatureT, the relative humidityRH, the power demandPw, the energy consumption or productionEor the flow rateFl.device(optional): Specifies the measured object, e.g. a thermostatThermostat, a heat pumpHP, a HVAC unitHVAC, a solar panelPVor the combination of all energy consuming devicesAll.sp(optional): Specifies that the given value is used as a setpoint.out(optional): Specifies that a given setpoint is output.
Solar panels are the only devices in these buildings that produce energy.
Examples:
Z01_Pw_HVACExt_TZ99_T_Thermostat_sp_out
For every environment, a list of inputs, outputs and weather files used is specified in the energym/envs folder for every building project.
Users are encouraged to upload new environments that present an interest for building control.
Please, download the latest version of EnergyPlus as well as a C/C++ compiler (for e.g., microsoft visual studio build tools). On windows, change the default compiler address in the .bat files in EnergyPlusToFMU/Scripts/win to your current C compiler address.
To create a new model, please create a new folder in simulation/energyplus or simulation/modelica. The folder must have following structure:
fmus: where FMU's will be storedsrc: with.idfor.mofiles: reference files to build the FMU's on any platformwf: weather files to be used for training and benchmarking evaluation
The energym/envs folder contains the specifics of the model: inputs, outputs as well as weather files for benchmarking and benchmarking metrics KPI's on the output
Once those steps have been carried out, run the script script/create_eplus_env.py to build EnergyPlus FMU's or scripts/create_mo_env_jmod.py to build Modelica FMU's (ensure before that you have JModelica installed and running under Python 2.7).
Two docker pre-built images are stored on dockerhub, one for model launching and interaction, and one heavier for model compilation.
If you use our library for your work, please cite our paper:
Scharnhorst, P.; Schubnel, B.; Fernández Bandera, C.; Salom, J.; Taddeo, P.; Boegli, M.; Gorecki, T.; Stauffer, Y.; Peppas, A.; Politi, C. Energym: A Building Model Library for Controller Benchmarking. Appl. Sci. 2021, 11, 3518. https://doi.org/10.3390/app11083518
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent