Package: besos
BESOS: Building and Energy Systems Optimization and Surrogate-modellingBESOS is a collection of modules for the simulation and optimization of buildings and urban energy systems. BESOS is designed to help researchers and practitioners to design more sustainable, district-integrated buildings. It integratesEnergyPlusandEnergyHubsimulation software with optimization and machine learning functionality. this includes lots of help with 'surrogate modelling', where machine learning models are fitted to data generated by parametric runs of detailed simulation models. BESOS facilitates running large-scale parametric analyses of EnergyPlus or EnergyHub models with output in a pandas DataFrame and using this to train machine learning surrogate models with scikit-learn or TensorFlow. We provide access to commonly used optimization algorithms via existing optimization toolboxes.Installing BESOSEnsure that you have Python 3.7+ and the corresponding version of pip.pip install besos[complete](If you do not want to run the example notebooks, you can usepip install besos, which will
install with less dependencies.)Install DependenciesWe use third party software to run building models (EnergyPlus), to solve EnergyHub models (a MILP solver), and make use of Rbfopt (viaBonmin). To use this functionality you need to install the software for the corresponding the task. GLPK and Bonmin are optional, it is possible to use Besos without them.Install EnergyplusDownload EnergyPlushere. (BESOSis currently supporting versions from 8.8-9.3+).For windows: After downloading the installation file, double click the setup file to start installing.
After setup is complete, navigate to yourSystem Propertiesand in theAdvancedtab, selectEnvironment Variables.
In either yourUser VariablesorSystem Variables(Depending on your permissions), double click onPathand add the location of yourEnergyPlusfolder to the end of it. Ensure the path is C:\EnergyPlusV{version} for proper integration with Besos.For linux: Run the downloaded script, and accept the prompt to add symlinks. Ensure the path is /usr/local/EnergyPlus-{version} for proper integration with Besos.TensorFlow (only required to use TensorFlow)TensorFlow is a machine learning library of which we have provided some examples. This package is quite large 300 mb therefore we have not added this to the requirements.To install TensorFlow use pip install.pip install tensorflowMILP solver (only required to use EnergyHub)EnergyHubmodelling requires a linear programming solver that is supported byPuLP, such asGLPK,CPlex, orGurobi. To learn about how to setup a custom solver please review the readthedocs page onCustomizing EnergyHub Solver.GLPKis free and open source. It can be foundhere.
If you are using a Debian based operating system, you can install GLPK withsudo apt install glpk-utilsOptional: Bonmin (only required to use RBFopt)Bonminis required to use theRBFoptoptimizer.
How to installBonmincan be foundhere.Running Example NotebooksExamples of Besos' functionality are provided through example notebooks. The notebooks can be viewed as Python scripts or through a Jupyter notebook.You can run notebooks from theBesos platform, which has the besos library and all dependencies pre-installed, or you can install Jupyter locally.To run the notebooks you needJuptyerinstalled. Jupyter can be installed using:pip install juptyerand launched from the current directory withjupyter notebook.Contributing and SupportWhen creating gitlab issues, please search the existinggitlab issuesto see if someone else has already made the same request.Feature RequestsTo request a feature open a new issue with your feature request.Bug reports/QuestionsIf you have found a bug, please open a gitlab issue describing the bug.
Make sure to include steps to reproduce the bug. Ideally, include a small
bit of code that causes the bug. If the bug causes an error, please include
the traceback. If the bug causes the wrong behaviour, please mention what
besos should do in this situation.Code contributionsIf you are interested in contributing to the code please review the readthedocs page oncontributing to the code.Example notebooksA good way to start is using the example notebooks.
They are described in theexamples overview