# Dark Grey Box
[](https://www.gnu.org/licenses/gpl-3.0)
[](https://circleci.com/gh/czagoni/darkgreybox)
[](https://badge.fury.io/py/darkgreybox)
## DarkGreyBox: An open-source data-driven python building thermal model inspired by Genetic Algorithms and Machine Learning
### Read the medium article here: https://medium.com/analytics-vidhya/data-driven-thermal-models-for-buildings-15385f744fc5
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](docs/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`:
```bash
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:
```bash
pip install darkgreybox[dev]
```
### User installation from source repository
You can check the latest sources with the command::
```bash
git clone https://github.com/czagoni/darkgreybox.git
```
You can install the dev dependencies (from the root of the repository):
```bash
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:
* [Demo Notebook 01 - Ti Model Direct Fit](docs/tutorials/darkgrey_poc_demo_01.ipynb): This notebook demonstrates the direct usage of the DarkGreyBox models via a simple fitting example for a Ti model.
* [Demo Notebook 02 - TiTe Model Direct Fit FAIL](docs/tutorials/darkgrey_poc_demo_02.ipynb): This notebook demonstrates the direct usage of the DarkGreyBox models via a simple fitting example for a TiTe model. In this case a local minimum is found during the fitting process and the model heavily oscillates making it unusable.
* [Demo Notebook 03 - TiTe Model Wrapper Fit PASS](docs/tutorials/darkgrey_poc_demo_03.ipynb): This notebook demonstrates the usage of the DarkGreyBox models via fitting them with a wrapper function for a TiTe model.
* [Demo Notebook 04 - DarkGreyFit](docs/tutorials/darkgrey_poc_demo_04.ipynb): This notebook demonstrates the usage of the DarkGreyBox models via fitting them with DarkGreyFit, setting up and evaluating multiple pipelines at once.
Launch a new jupyter notebook from the root of the repository:
```bash
jupyter notebook
```
## Development
We welcome new contributors of all experience levels.
### Source code
You can check the latest sources with the command::
```bash
git clone https://github.com/czagoni/darkgreybox.git
```
You can install the dev and test dependencies (from the root of the repository):
```bash
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):
```bash
pytest
```
You can check linting from the repo root directory (you will need to have `flake8` installed):
```bash
flake8
```
Raw data
{
"_id": null,
"home_page": "https://github.com/czagoni/darkgreybox",
"name": "darkgreybox",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "python model thermal machine-learning genetic-algorithm data-science",
"author": "csaba zagoni",
"author_email": "czagoni@greenpeace.org",
"download_url": "https://files.pythonhosted.org/packages/66/51/ebb04104141bb9b254a0f68606b7b348886a2472136cc3913e27bdef1246/darkgreybox-0.3.2.tar.gz",
"platform": null,
"description": "# Dark Grey Box\n\n[](https://www.gnu.org/licenses/gpl-3.0)\n[](https://circleci.com/gh/czagoni/darkgreybox)\n[](https://badge.fury.io/py/darkgreybox)\n\n## DarkGreyBox: An open-source data-driven python building thermal model inspired by Genetic Algorithms and Machine Learning\n\n### Read the medium article here: https://medium.com/analytics-vidhya/data-driven-thermal-models-for-buildings-15385f744fc5\n\nConstructing 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. \n\nA 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.\n\nThe 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. \n\nThe easiest way to get familiar with DarkGreyBox is to look at the [tutorials](docs/tutorials/).\n\n## Installation\n\n### Dependencies\n\nDarkGreyBox requires:\n\n- Python (>= 3.6)\n- lmfit \n- pandas \n- joblib \n\nNote: 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.\n\n### User installation from PyPi package (latest release)\n\nInstall DarkGreyBox via `pip`:\n```bash\npip install darkgreybox\n```\n\n#### Optional Dependencies\n\nThis gives you a headstart for using DarkGreyBox in anger.\n\n- scikit-learn \n- numdifftools \n- statsmodels \n- matplotlib \n- jupyter \n- notebook \n\nYou can install these additional dependencies via pip:\n```bash\npip install darkgreybox[dev]\n```\n\n### User installation from source repository\n\nYou can check the latest sources with the command::\n```bash\ngit clone https://github.com/czagoni/darkgreybox.git\n```\n\nYou can install the dev dependencies (from the root of the repository):\n```bash\npip install -e .'[dev]'\n```\n\n## Documentation\n\nTo access the tutorials you need to have cloned DarkGreyBox from the source repository (see above).\n\n### Tutorials\n\nThe easiest way to get into the details of how DarkGreyBox works is through following the tutorials:\n\n* [Demo Notebook 01 - Ti Model Direct Fit](docs/tutorials/darkgrey_poc_demo_01.ipynb): This notebook demonstrates the direct usage of the DarkGreyBox models via a simple fitting example for a Ti model.\n* [Demo Notebook 02 - TiTe Model Direct Fit FAIL](docs/tutorials/darkgrey_poc_demo_02.ipynb): This notebook demonstrates the direct usage of the DarkGreyBox models via a simple fitting example for a TiTe model. In this case a local minimum is found during the fitting process and the model heavily oscillates making it unusable.\n* [Demo Notebook 03 - TiTe Model Wrapper Fit PASS](docs/tutorials/darkgrey_poc_demo_03.ipynb): This notebook demonstrates the usage of the DarkGreyBox models via fitting them with a wrapper function for a TiTe model.\n* [Demo Notebook 04 - DarkGreyFit](docs/tutorials/darkgrey_poc_demo_04.ipynb): This notebook demonstrates the usage of the DarkGreyBox models via fitting them with DarkGreyFit, setting up and evaluating multiple pipelines at once.\n\nLaunch a new jupyter notebook from the root of the repository:\n```bash\njupyter notebook\n```\n\n## Development\n\nWe welcome new contributors of all experience levels. \n\n### Source code\n\nYou can check the latest sources with the command::\n```bash\ngit clone https://github.com/czagoni/darkgreybox.git\n```\n\nYou can install the dev and test dependencies (from the root of the repository):\n```bash\npip install -e .'[dev,test]'\n```\n\n### Testing\n\nAfter installation, you can launch the test suite from the repo root\ndirectory (you will need to have `pytest` installed):\n```bash\npytest\n```\n\nYou can check linting from the repo root directory (you will need to have `flake8` installed):\n```bash\nflake8\n```\n\n\n\n\n",
"bugtrack_url": null,
"license": "",
"summary": "DarkGreyBox: An Open-Source Data-Driven Python Building Thermal Model Inspired By Genetic Algorithms and Machine Learning",
"version": "0.3.2",
"project_urls": {
"Download": "https://github.com/czagoni/darkgreybox/archive/refs/tags/0.3.1.tar.gz",
"Homepage": "https://github.com/czagoni/darkgreybox"
},
"split_keywords": [
"python",
"model",
"thermal",
"machine-learning",
"genetic-algorithm",
"data-science"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b7814f814ee6f4da83a8cd290574a703f225247a5d722937e7ea6d32915ee877",
"md5": "b16c41e1591f0609829e9e0414318d3d",
"sha256": "75f3a31a60019c33fc7f901bde6f89d6a0ce9ef47ebc1c8c670a7e344de00bf7"
},
"downloads": -1,
"filename": "darkgreybox-0.3.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b16c41e1591f0609829e9e0414318d3d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 14438,
"upload_time": "2024-03-01T13:16:59",
"upload_time_iso_8601": "2024-03-01T13:16:59.049023Z",
"url": "https://files.pythonhosted.org/packages/b7/81/4f814ee6f4da83a8cd290574a703f225247a5d722937e7ea6d32915ee877/darkgreybox-0.3.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6651ebb04104141bb9b254a0f68606b7b348886a2472136cc3913e27bdef1246",
"md5": "5ff68883cb4b6533c33825d1ad238ff4",
"sha256": "8db01e2dc51cda462d456dcc9f8fca2ec060bad43d50491a11086990fe51fe70"
},
"downloads": -1,
"filename": "darkgreybox-0.3.2.tar.gz",
"has_sig": false,
"md5_digest": "5ff68883cb4b6533c33825d1ad238ff4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 878683,
"upload_time": "2024-03-01T13:17:02",
"upload_time_iso_8601": "2024-03-01T13:17:02.409983Z",
"url": "https://files.pythonhosted.org/packages/66/51/ebb04104141bb9b254a0f68606b7b348886a2472136cc3913e27bdef1246/darkgreybox-0.3.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-01 13:17:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "czagoni",
"github_project": "darkgreybox",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"circle": true,
"lcname": "darkgreybox"
}
JSON
