Skip to content

DarkGreyBox: An open-source data-driven python building thermal model inspired by Genetic Algorithms and Machine Learning

License

Notifications You must be signed in to change notification settings

czagoni/darkgreybox

Repository files navigation

Dark Grey Box

License: GPL v3 CircleCI PyPI version

DarkGreyBox: An open-source data-driven python building thermal model inspired by Genetic Algorithms and Machine Learning

Constructing simple, accurate and easy-to-interpret thermal models for existing buildings is essential in reducing the environmental impact of our built environment. DarkGreyBox provides a data-driven approach to constructing and fitting RC-equivalent grey box thermal models for buildings, within the classic Machine Learning (ML) framework for straightforward model performance evaluation.

A large number of competing models can be set up in easy-to-configure pipelines and the best performing models are selected based on principles inspired by Genetic Algorithms (GA). This approach also addresses the main disadvanatages of classical grey-box thermal modelling techniques by not requiring initial condition values for the thermal parameters to be pre-calculated and also not requiring an excitation signal to be injected into the building for successful model convergence and evaluation.

The massive advantages of using a DarkGreyBoxModel over a black-box (i.e. Machine Learning) model - e.g. a deep sequence-to-sequence model - are that it is easily interpreted by humans and that it slots easily into other modelling frameworks. E.g. to model the behaviour of a building with its connected heating system, simply construct a heat source model in a MILP framework and the grey-box building thermal model just slots in as a set of linear differential equations with a handful of parameters. Doing this with a deep ML model would be quite tricky.

The easiest way to get familiar with DarkGreyBox is to look at the tutorials.

Installation

Dependencies

DarkGreyBox requires:

  • Python (>= 3.6)
  • lmfit
  • pandas
  • joblib

Note: these are only the core dependencies and you will most likely want to install either the optional dependencies or your preferred custom alternatives to them.

User installation from PyPi package (latest release)

Install DarkGreyBox via pip:

pip install darkgreybox

Optional Dependencies

This gives you a headstart for using DarkGreyBox in anger.

  • scikit-learn
  • numdifftools
  • statsmodels
  • matplotlib
  • jupyter
  • notebook

You can install these additional dependencies via pip:

pip install darkgreybox[dev]

User installation from source repository

You can check the latest sources with the command::

git clone https://github.com/czagoni/darkgreybox.git

You can install the dev dependencies (from the root of the repository):

pip install -e .'[dev]'

Documentation

To access the tutorials you need to have cloned DarkGreyBox from the source repository (see above).

Tutorials

The easiest way to get into the details of how DarkGreyBox works is through following the tutorials:

Launch a new jupyter notebook from the root of the repository:

jupyter notebook

Development

We welcome new contributors of all experience levels.

Source code

You can check the latest sources with the command::

git clone https://github.com/czagoni/darkgreybox.git

You can install the dev and test dependencies (from the root of the repository):

pip install -e .'[dev,test]'

Testing

After installation, you can launch the test suite from the repo root directory (you will need to have pytest installed):

pytest

You can check linting from the repo root directory (you will need to have flake8 installed):

flake8

About

DarkGreyBox: An open-source data-driven python building thermal model inspired by Genetic Algorithms and Machine Learning

Topics

Resources

License

Stars

Watchers

Forks

Languages