BESOS documentation

besos: Building and Energy Systems Optimization and Surrogate-modelling

besos library and BESOS platform have been created by the Energy In Cities Group and University of Victoria. The Platform is a Jupyter Hub that is able to run the besos code base, and has all the dependencies installed. The platform is freely accessible for academics in the building energy modelling space.

_images/besos.png

Besos library connects modelling and optimization tools to allow for parameterizing running and optimizing models, sampling from their design spaces, and generating data for use in machine learning models. This supports designing building and district energy modelling experiments.

https://gitlab.com/energyincities/besos/badges/master/pipeline.svg https://gitlab.com/energyincities/besos/badges/master/coverage.svg https://img.shields.io/badge/code%20style-black-000000.svg https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white

Examples of applications of Besos to building and district energy modelling are available on our examples overview page or take a look at the example workflow.

EnergyPlus is a commonly used physics-based building energy modelling software. EnergyHub is a linear programming framework with constraints specificially designed to size energy convertors and schedule energy carriers for an energy system with the intend to minimize cost, emissions or a custom objective funcation. Both these simulation tools are commenly used by civil engineering researchers to build energy related simulation experiments. besos adds substantial functionality to these tools integrating them with python and several different libraries to optimize the model, or use the results from the models for and machine learning.

besos also facilitates running large-scale parametric analyses of EnergyPlus or EnergyHub models with output in a pandas DataFrame and uses this to train machine learning surrogate models with scikit-learn or TensorFlow. We provide access to commonly used optimization algorithms via existing optimization toolboxes.

besos library and associated BESOS Platform

The BESOS Platform is a Jupyter Hub that is able to run the besos code base, and has all the dependencies installed. An overview of the platform using a C4 diagram is presented here. The platform is freely accesible for academics in the building energy modelling space. If you want to get started on the BESOS platform, check out how to get started here!

The besos library connects modelling and optimization tools to allow for parameterizing running and optimizing models, sampling from their design spaces, and generating data for use in machine learning models. This supports designing building and district energy modelling experiments.

Installation

If you want to run besos on your own personal computer, please review the Installation page on the gitlab. If you are an scholar associated with an academic institution you can request access to the BESOS platform through our online request form. This platform comes with all the software dependies installed and has significant computational resources avilable.

A high level overview of the besos modules.

The besos library software is written to include all the features required to setup a building or district design energy modelling experiments using EnergyPlus as building energy model and EnergyHub as distric energy model. We have created distinct software objects that will help the designer create this experiment.

The following concepts: Parameters, Objectives, Problem, Evaluators, Sampling and Optimizers have been created to build these experiments. First is the creation of the optimization problem which is composed of a model, parameters and an objective. The model could be an EnergyPlus model or a PyEHub model. Parameters are created is a separate class where each parameter is composed of a selector and a descriptor. The selectors point to the definitions in the model that will be changed and the descriptors provide the range or list of values that are of interest. The objectives point to model results that are of interest to the optimizer. Once a problem has been defined we can make use of the Evaluators to run the model to find a sampled dataset or allow a optimizer to find the best solution given the problem definition. The sampling dataset can be used to train a surrogate model. To get a better understanding how all the concepts work together, we have constructed an example-notebooks/building_to_surrogate_tf that explains these basic concepts.

Examples

The example workflow only gives a high level overview of what is possible. We have prepared more detailed examples of all the various modules and case studies of the besos library. The examples can be found on our examples overview page

Indices and tables

Acknowledgement

besos library and BESOS platform have been created by the Energy In Cities Group and University of Victoria.