Energym is an open source building simulation library designed for the control community to test climate control and energy mangement 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 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 incorporates models developed in Modelica and EnergyPlus as well as specific classes for simulating weather forecasts and appliances consumption figures.

Energym has to date 14 models integrated and 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 and new control capabilities are under development und will be added to the library in due course.

The library is compatible both for windows 10 and linux os and provides precompiled fmu files for both operating systems. Two docker files (one for running current models, one for compiling new models) that download dockerhub pre-built images are also at user disposal to speed up use and testing.

Features¶

Works directly on Windows and Linux (pre-compiled buildings .fmu files)
Works with E+ and Modelica
Works with Python 3.*

Available environments¶

Following environments are available. Click on the buildings hyperlink to get complete descriptions of the buildings, their inputs and outputs.

Technical systems/ Buildings	Thermostat	Heatpump	AHU	Battery	EV	PV	Prg
ApartmentsThermal-v0	con	con	abs	con	con	uncon	E+
ApartmentsGrid-v0	con	uncon	abs	con	con	uncon	E+
Apartments2Thermal-v0	con	con	abs	con	con	uncon	E+
Apartments2Grid-v0	con	uncon	abs	con	con	uncon	E+
OfficesThermostat-v0	con	abs	abs	abs	abs	uncon	E+
MixedUseFanFCU-v0	con	abs	con	abs	abs	abs	E+
SeminarcenterThermostat-v0	con	uncon	abs	abs	abs	uncon	E+
SeminarcenterFull-v0	con	con	abs	abs	abs	uncon	E+
SimpleHouseRad-v0	abs	con	abs	abs	abs	uncon	Mod
SimpleHouseRSla-v0	abs	con	abs	abs	abs	uncon	Mod
SwissHouseRSlaW2W-v0	abs	con	abs	abs	abs	uncon	Mod
SwissHouseRSlaA2W-v0	abs	con	abs	abs	abs	uncon	Mod
SwissHouseRSlaTank-v0	abs	con	abs	abs	abs	uncon	Mod
SwissHouseRSlaTankDhw-v0	abs	con	abs	abs	abs	uncon	Mod

con : present and controllable, uncon : present but uncontrollable, abs : absent.

Example¶

The usage of Energym is straight forward, as in this simplified code example, assuming the implementation of a get_input() function made by the user:

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()

For an introduction to Energym see Getting Started and for more in depth control examples see Examples.

Philosophy¶

Energym has been designed such that you are entirely free in your controller strategy and design.

In particular, if you use Model Predictive Control or Reinforcement Learning strategies, a set of weather files at different locations close to the real location is provided to carry out system identification/ RL training.

When a controller/model has been trained, it can be finally evaluated on the predefined period of time under the predefined meto condition and KPIs.

Furthermore, models can be launched in parallels, making Energym models also usable for flexibility control strategies at multi-building level.

Explanations¶

The first part of a video series on explanations and help around Energym can be found here:

Contribute¶

Users are encouraged to upload new environments that present an interest for building or energy system control.

To do so, follow the full installation steps described in Full Installation.

To create a new model, please follow the steps described in Contributing. Then contact the authors (see Support) if you want your model to be incorporated in Energym.

Cite¶

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

Support¶

If you are having issues, please let us know and open an issue on github. We are happy to let Energym grow and help you in a reasonable amount of time.

License¶

The project is licensed under the BSD license.

Thanks¶

Part of this work has been carried out under European Project Sabina. Research institutes and partners involved are CSEM, IREC, UNAV, NTUA and INSERO.

Indices and tables¶

Buildings