![E.ON EBC RWTH Aachen University](./docs/EBC_Logo.png)
[![DOI](https://joss.theoj.org/papers/10.21105/joss.03861/status.svg)](https://doi.org/10.21105/joss.03861)
[![pylint](https://rwth-ebc.github.io/ebcpy/master/pylint/pylint.svg )](https://rwth-ebc.github.io/ebcpy/master/pylint/pylint.html)
[![documentation](https://rwth-ebc.github.io/ebcpy/master/docs/doc.svg)](https://rwth-ebc.github.io/ebcpy/master/docs/index.html)
[![coverage](https://rwth-ebc.github.io/ebcpy/master/coverage/badge.svg)](https://rwth-ebc.github.io/ebcpy/master/coverage)
[![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
[![build](https://rwth-ebc.github.io/ebcpy/master/build/build.svg)](https://rwth-ebc.github.io/ebcpy/master/build/build.svg)
# ebcpy
This **PY**thon package provides generic functions and classes commonly
used for the analysis and optimization of **e**nergy systems, **b**uildings and indoor **c**limate (**EBC**).
Key features are:
* `TimeSeriesData`
* `SimulationAPI`'s
* Optimization wrapper
* Pre-/Postprocessing
* Modelica utilities
It was developed together with `AixCaliBuHA`, a framework for an automated calibration of dynamic building and HVAC models. During this development, we found several interfaces relevant to further reserach. We thus decoupled these interfaces into `ebcpy` and used the framework, for instance in the design optimization of heat pump systems ([link](https://www.sciencedirect.com/science/article/abs/pii/S0196890421010645?via%3Dihub)).
# Installation
To install, simply run
```
pip install ebcpy
```
In order to use all optional dependencies (e.g. `pymoo` optimization), install via:
```
pip install ebcpy[full]
```
If you encounter an error with the installation of `scikit-learn`, first install `scikit-learn` separatly and then install `ebcpy`:
```
pip install scikit-learn
pip install ebcpy
```
If this still does not work, we refer to the troubleshooting section of `scikit-learn`: https://scikit-learn.org/stable/install.html#troubleshooting. Also check [issue 23](https://github.com/RWTH-EBC/ebcpy/issues/23) for updates.
In order to help development, install it as an egg:
```
git clone https://github.com/RWTH-EBC/ebcpy
pip install -e ebcpy
```
# How to get started?
We recommend running our jupyter-notebook to be guided through a **helpful tutorial**.
For this, run the following code:
```
# If jupyter is not already installed:
pip install jupyter
# Go into your ebcpy-folder (cd \path_to_\ebcpy) or change the path to tutorial.ipynb and run:
jupyter notebook tutorial\tutorial.ipynb
```
Or, clone this repo and look at the examples\README.md file.
Here you will find several examples to execute.
# How to cite ebcpy
Please use the following metadata to cite `ebcpy` in your research:
```
@article{Wuellhorst2022,
doi = {10.21105/joss.03861},
url = {https://doi.org/10.21105/joss.03861},
year = {2022},
publisher = {The Open Journal},
volume = {7},
number = {72},
pages = {3861},
author = {Fabian Wüllhorst and Thomas Storek and Philipp Mehrfeld and Dirk Müller},
title = {AixCaliBuHA: Automated calibration of building and HVAC systems},
journal = {Journal of Open Source Software}
}
```
# TimeSeriesData
Note that we use our own `TimeSeriesData` object which inherits from `pd.DataFrame`. The aim is to make tasks like loading different filetypes or applying multiple tags to one variable more convenient, while conserving the powerful tools of the DataFrame.
Just a quick intro here:
## Variables and tags
```
>>> from ebcpy.data_types import TimeSeriesData
>>> tsd = TimeSeriesData(r"path_to_a_supported_file")
>>> print(tsd)
Variables T_heater T_heater_1
Tags meas sim meas sim
Time
0.0 313.165863 313.165863 293.173126 293.173126
1.0 312.090271 310.787750 293.233002 293.352448
2.0 312.090027 310.796753 293.385925 293.719055
3.0 312.109436 310.870331 293.589233 294.141754
```
As you can see, our first column level is always a variable, and the second one a tag.
This is especially handy when dealing with calibration or processing tasks, where you will have multiple
versions (tags) for one variable. The default tag is `raw` to indicate the unmodified data.
To access a variable, you have to call `.loc`. To access multiple variables that all hold one tag use `xs`:
```python
# All tags:
tsd.loc[:, "variable_name"]
# One specific tag:
tsd.loc[:, ("variable_name", "tag_name")]
# One tag, all variables:
tsd.xs("tag_name", axis=1, level=1)
```
## FloatIndex and DateTimeIndex
Measured data typically holds a datetime stamps (`DateTimeIndex`) while simulation result files hold absolute seconds (`FloatIndex`).
You can easily convert back and forth using:
```python
# From Datetime to float
tsd.to_float_index()
# From float to datetime
tsd.to_datetime_index()
# To clean your data and create a common frequency:
tsd.clean_and_space_equally(desired_freq="1s")
```
# Documentation
Visit our official [Documentation](https://rwth-ebc.github.io/ebcpy/master/docs/index.html).
# Problems?
Please [raise an issue here](https://github.com/RWTH-EBC/ebcpy/issues/new).
Raw data
{
"_id": null,
"home_page": "https://github.com/RWTH-EBC/ebcpy",
"name": "ebcpy",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "simulation,building,energy,time-series-data,comfort,black-box optimization",
"author": "RWTH Aachen University, E.ON Energy Research Center, Institute of Energy Efficient Buildings and Indoor Climate",
"author_email": "fabian.wuellhorst@eonerc.rwth-aachen.de",
"download_url": "https://files.pythonhosted.org/packages/05/f5/0d257afd6149d6578ebdf7657bb999790e4b70017b6c9252596d7854b5c9/ebcpy-0.3.14.tar.gz",
"platform": null,
"description": "![E.ON EBC RWTH Aachen University](./docs/EBC_Logo.png)\n\n[![DOI](https://joss.theoj.org/papers/10.21105/joss.03861/status.svg)](https://doi.org/10.21105/joss.03861)\n[![pylint](https://rwth-ebc.github.io/ebcpy/master/pylint/pylint.svg )](https://rwth-ebc.github.io/ebcpy/master/pylint/pylint.html)\n[![documentation](https://rwth-ebc.github.io/ebcpy/master/docs/doc.svg)](https://rwth-ebc.github.io/ebcpy/master/docs/index.html)\n[![coverage](https://rwth-ebc.github.io/ebcpy/master/coverage/badge.svg)](https://rwth-ebc.github.io/ebcpy/master/coverage)\n[![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)\n[![build](https://rwth-ebc.github.io/ebcpy/master/build/build.svg)](https://rwth-ebc.github.io/ebcpy/master/build/build.svg)\n\n\n# ebcpy\n\nThis **PY**thon package provides generic functions and classes commonly\nused for the analysis and optimization of **e**nergy systems, **b**uildings and indoor **c**limate (**EBC**).\n\nKey features are:\n\n* `TimeSeriesData`\n* `SimulationAPI`'s\n* Optimization wrapper\n* Pre-/Postprocessing\n* Modelica utilities\n\nIt was developed together with `AixCaliBuHA`, a framework for an automated calibration of dynamic building and HVAC models. During this development, we found several interfaces relevant to further reserach. We thus decoupled these interfaces into `ebcpy` and used the framework, for instance in the design optimization of heat pump systems ([link](https://www.sciencedirect.com/science/article/abs/pii/S0196890421010645?via%3Dihub)).\n\n# Installation\n\nTo install, simply run\n```\npip install ebcpy\n```\n\nIn order to use all optional dependencies (e.g. `pymoo` optimization), install via:\n\n```\npip install ebcpy[full]\n```\n\nIf you encounter an error with the installation of `scikit-learn`, first install `scikit-learn` separatly and then install `ebcpy`:\n\n```\npip install scikit-learn\npip install ebcpy\n```\n\nIf this still does not work, we refer to the troubleshooting section of `scikit-learn`: https://scikit-learn.org/stable/install.html#troubleshooting. Also check [issue 23](https://github.com/RWTH-EBC/ebcpy/issues/23) for updates.\n\nIn order to help development, install it as an egg:\n\n```\ngit clone https://github.com/RWTH-EBC/ebcpy\npip install -e ebcpy\n```\n\n# How to get started?\n\nWe recommend running our jupyter-notebook to be guided through a **helpful tutorial**. \nFor this, run the following code:\n```\n# If jupyter is not already installed:\npip install jupyter\n# Go into your ebcpy-folder (cd \\path_to_\\ebcpy) or change the path to tutorial.ipynb and run:\njupyter notebook tutorial\\tutorial.ipynb\n```\n\nOr, clone this repo and look at the examples\\README.md file.\nHere you will find several examples to execute.\n\n# How to cite ebcpy\n\nPlease use the following metadata to cite `ebcpy` in your research:\n\n```\n@article{Wuellhorst2022,\n doi = {10.21105/joss.03861},\n url = {https://doi.org/10.21105/joss.03861},\n year = {2022},\n publisher = {The Open Journal},\n volume = {7},\n number = {72},\n pages = {3861},\n author = {Fabian W\u00fcllhorst and Thomas Storek and Philipp Mehrfeld and Dirk M\u00fcller},\n title = {AixCaliBuHA: Automated calibration of building and HVAC systems},\n journal = {Journal of Open Source Software}\n}\n```\n\n# TimeSeriesData\nNote that we use our own `TimeSeriesData` object which inherits from `pd.DataFrame`. The aim is to make tasks like loading different filetypes or applying multiple tags to one variable more convenient, while conserving the powerful tools of the DataFrame.\nJust a quick intro here:\n\n## Variables and tags\n```\n>>> from ebcpy.data_types import TimeSeriesData\n>>> tsd = TimeSeriesData(r\"path_to_a_supported_file\")\n>>> print(tsd)\nVariables T_heater T_heater_1 \nTags meas sim meas sim\nTime \n0.0 313.165863 313.165863 293.173126 293.173126\n1.0 312.090271 310.787750 293.233002 293.352448\n2.0 312.090027 310.796753 293.385925 293.719055\n3.0 312.109436 310.870331 293.589233 294.141754\n```\n\nAs you can see, our first column level is always a variable, and the second one a tag.\nThis is especially handy when dealing with calibration or processing tasks, where you will have multiple\nversions (tags) for one variable. The default tag is `raw` to indicate the unmodified data.\nTo access a variable, you have to call `.loc`. To access multiple variables that all hold one tag use `xs`:\n```python\n# All tags:\ntsd.loc[:, \"variable_name\"]\n# One specific tag:\ntsd.loc[:, (\"variable_name\", \"tag_name\")]\n# One tag, all variables:\ntsd.xs(\"tag_name\", axis=1, level=1)\n```\n## FloatIndex and DateTimeIndex\nMeasured data typically holds a datetime stamps (`DateTimeIndex`) while simulation result files hold absolute seconds (`FloatIndex`). \nYou can easily convert back and forth using:\n```python\n# From Datetime to float\ntsd.to_float_index()\n# From float to datetime\ntsd.to_datetime_index()\n# To clean your data and create a common frequency:\ntsd.clean_and_space_equally(desired_freq=\"1s\")\n```\n\n# Documentation\nVisit our official [Documentation](https://rwth-ebc.github.io/ebcpy/master/docs/index.html).\n\n# Problems?\nPlease [raise an issue here](https://github.com/RWTH-EBC/ebcpy/issues/new).\n",
"bugtrack_url": null,
"license": "BSD 3-Clause",
"summary": "Python Library used for different python modules for the analysis and optimization of energy systems, buildings and indoor climate",
"version": "0.3.14",
"project_urls": {
"Download": "https://github.com/RWTH-EBC/ebcpy/archive/refs/tags/0.3.14.tar.gz",
"Homepage": "https://github.com/RWTH-EBC/ebcpy"
},
"split_keywords": [
"simulation",
"building",
"energy",
"time-series-data",
"comfort",
"black-box optimization"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6ca0b72aac6df07aa5f846905e4a4b9546bf88485c9a4f13f7d4d1fce0fd6c88",
"md5": "8cfdea16e7b08a6f9928a925849f2da6",
"sha256": "9a1f15a2f9c34b050309502d840d1e244cae042a247afd43398e681c86950b5e"
},
"downloads": -1,
"filename": "ebcpy-0.3.14-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8cfdea16e7b08a6f9928a925849f2da6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 69407,
"upload_time": "2024-02-16T13:24:38",
"upload_time_iso_8601": "2024-02-16T13:24:38.266320Z",
"url": "https://files.pythonhosted.org/packages/6c/a0/b72aac6df07aa5f846905e4a4b9546bf88485c9a4f13f7d4d1fce0fd6c88/ebcpy-0.3.14-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "05f50d257afd6149d6578ebdf7657bb999790e4b70017b6c9252596d7854b5c9",
"md5": "28f0f2e165779c89d1600800420479fd",
"sha256": "0383a1414ba9b90a8db9b8c419d4558f9f0e9daed502de0b7f0a7251d748af68"
},
"downloads": -1,
"filename": "ebcpy-0.3.14.tar.gz",
"has_sig": false,
"md5_digest": "28f0f2e165779c89d1600800420479fd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 77204,
"upload_time": "2024-02-16T13:24:40",
"upload_time_iso_8601": "2024-02-16T13:24:40.535376Z",
"url": "https://files.pythonhosted.org/packages/05/f5/0d257afd6149d6578ebdf7657bb999790e4b70017b6c9252596d7854b5c9/ebcpy-0.3.14.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-16 13:24:40",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "RWTH-EBC",
"github_project": "ebcpy",
"travis_ci": false,
"coveralls": true,
"github_actions": false,
"requirements": [],
"lcname": "ebcpy"
}