[](https://doi.org/10.21105/joss.03861)
[](https://rwth-ebc.github.io/ebcpy/master/pylint/pylint.html)
[](https://rwth-ebc.github.io/ebcpy/master/docs/index.html)
[](https://rwth-ebc.github.io/ebcpy/master/coverage)
[](https://opensource.org/licenses/BSD-3-Clause)
[](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 research. 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 or questions?
Please [raise an issue here](https://github.com/RWTH-EBC/ebcpy/issues/new).
For other inquires, please contact [ebc-tools@eonerc.rwth-aachen.de](mailto:ebc-tools@eonerc.rwth-aachen.de).
Raw data
{
"_id": null,
"home_page": "https://github.com/RWTH-EBC/ebcpy",
"name": "ebcpy",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"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/7b/6e/153f8ac4d3632e7d8267427ce58e4c4dfd2500424b99ccefc0e7e48803f0/ebcpy-0.5.5.tar.gz",
"platform": null,
"description": "\n\n[](https://doi.org/10.21105/joss.03861)\n[](https://rwth-ebc.github.io/ebcpy/master/pylint/pylint.html)\n[](https://rwth-ebc.github.io/ebcpy/master/docs/index.html)\n[](https://rwth-ebc.github.io/ebcpy/master/coverage)\n[](https://opensource.org/licenses/BSD-3-Clause)\n[](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 research. 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 or questions?\nPlease [raise an issue here](https://github.com/RWTH-EBC/ebcpy/issues/new).\n\nFor other inquires, please contact [ebc-tools@eonerc.rwth-aachen.de](mailto:ebc-tools@eonerc.rwth-aachen.de).\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.5.5",
"project_urls": {
"Download": "https://github.com/RWTH-EBC/ebcpy/archive/refs/tags/0.5.5.tar.gz",
"Homepage": "https://github.com/RWTH-EBC/ebcpy"
},
"split_keywords": [
"simulation",
" building",
" energy",
" time-series-data",
" comfort",
" black-box optimization"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "9ab0d28d045ec0bfb0c52cae6d77d8e52238713c68047b53883d47bb459e494c",
"md5": "ee8d85afc5ffae916dcb223fe7eac247",
"sha256": "d1981fbffa6cb8a6240ea23f41e4a313ffed4fdc93f419371e798dc4499e1aa3"
},
"downloads": -1,
"filename": "ebcpy-0.5.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ee8d85afc5ffae916dcb223fe7eac247",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 73878,
"upload_time": "2025-07-09T10:47:29",
"upload_time_iso_8601": "2025-07-09T10:47:29.083870Z",
"url": "https://files.pythonhosted.org/packages/9a/b0/d28d045ec0bfb0c52cae6d77d8e52238713c68047b53883d47bb459e494c/ebcpy-0.5.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "7b6e153f8ac4d3632e7d8267427ce58e4c4dfd2500424b99ccefc0e7e48803f0",
"md5": "e697a00e2cd52c12f6d7b8908db60f37",
"sha256": "cb88686edd0a7faae611a0a6e82ff522adcb9fab29344669bbe1dcd11e69c84e"
},
"downloads": -1,
"filename": "ebcpy-0.5.5.tar.gz",
"has_sig": false,
"md5_digest": "e697a00e2cd52c12f6d7b8908db60f37",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 83346,
"upload_time": "2025-07-09T10:47:30",
"upload_time_iso_8601": "2025-07-09T10:47:30.394023Z",
"url": "https://files.pythonhosted.org/packages/7b/6e/153f8ac4d3632e7d8267427ce58e4c4dfd2500424b99ccefc0e7e48803f0/ebcpy-0.5.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-09 10:47:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "RWTH-EBC",
"github_project": "ebcpy",
"travis_ci": false,
"coveralls": true,
"github_actions": false,
"requirements": [
{
"name": "numpy",
"specs": [
[
"<",
"2.0"
],
[
">=",
"1.19.5"
]
]
},
{
"name": "matplotlib",
"specs": [
[
">=",
"3.3.4"
]
]
},
{
"name": "scipy",
"specs": [
[
">=",
"1.5.4"
]
]
},
{
"name": "pandas",
"specs": [
[
">=",
"1.1.5"
]
]
},
{
"name": "tables",
"specs": [
[
">=",
"3.6.1"
]
]
},
{
"name": "scikit-learn",
"specs": [
[
">=",
"0.24.2"
]
]
},
{
"name": "fmpy",
"specs": [
[
"<",
"0.3.17"
],
[
">=",
"0.2.27"
]
]
},
{
"name": "openpyxl",
"specs": [
[
">=",
"3.0.5"
]
]
},
{
"name": "xlrd",
"specs": [
[
">=",
"2.0.1"
]
]
},
{
"name": "pymoo",
"specs": [
[
"==",
"0.5.0"
]
]
},
{
"name": "bayesian-optimization",
"specs": [
[
"==",
"1.4.3"
]
]
},
{
"name": "pydantic",
"specs": [
[
">=",
"2.0"
]
]
},
{
"name": "h5py",
"specs": [
[
">=",
"3.1.0"
]
]
},
{
"name": "GitPython",
"specs": [
[
">=",
"3.1.30"
]
]
},
{
"name": "fastparquet",
"specs": [
[
">=",
"2023.1.0"
]
]
},
{
"name": "pyarrow",
"specs": [
[
">=",
"11.0.0"
]
]
}
],
"lcname": "ebcpy"
}
JSON
