# Peak Shaving Analyzer
This repository contains tools and utilities for analyzing and optimizing energy consumption with peak shaving strategies. The project includes data fetching, analysis, and visualization components, as well as Docker configurations for deployment.
## Table of Contents
- [Overview](#overview)
- [Features](#features)
- [Installation](#installation)
- [Usage](#usage)
- [Examples](#examples)
- [License](#license)
## Overview
Peak shaving is a strategy to reduce energy costs by minimizing peak demand utilizing energy storage systems. This project provides tools to optimize a given consumption time series with peak-shaving reducing capacity costs and visualizing results using Grafana.
## Features
- Peak shaving optimization using [FINE by FZJ](https://github.com/FZJ-IEK3-VSA/FINE)
- Easy configuration of many parameters
- Support for dynamic prices
- Inclusion of PV system integration with automatic retrieving of generation timeseries depending on location (with detection for leap years)
- Dockerized deployment with Grafana dashboards
- Example configurations for various scenarios
## Installation
You can install peakshaving-analyzer using pip. Choose the appropriate installation method based on your needs:
### Using pip
To install the core package:
```bash
pip install peakshaving-analyzer
```
### Timescale Database and Grafana Dashboards
If you want to benefit from a supported database and integrated Grafana dashboards for scenario analysis, you can use the provided Docker Compose file.
Follow these steps:
1. Clone the repository and navigate to its directory:
```bash
git clone https://github.com/NOWUM/peakshaving-analyzer.git
cd peakshaving-analyzer
```
2. Start the database and Grafana using the following command:
```bash
docker compose up -d
```
This will launch a container for TimescaleDB and Grafana with preconfigured dashboards for analysis. You can access the Grafana dashboards at `http://localhost:3000`.
## Usage
You can use Peak Shaving Analyzer flexibly – either with a YAML configuration file, directly from Python code or use the [OpenEnergyDataServer](https://github.com/open-energy-data-server/open-energy-data-server). Results can be saved locally as files or in a database.
### Using the CLI
Use `psa -h` to see the usage of the CLI tool and it's options.
### Loading the Configuration
**1. Load from YAML configuration file:**
```python
from peakshaving_analyzer import PeakShavingAnalyzer, load_yaml_config
config = load_yaml_config("/path/to/your/config.yml")
```
**2. Load from OEDS:**
```python
from peakshaving_analyzer import PeakShavingAnalyzer, load_oeds_config
config = load_oeds_config(load_oeds_config(con="your/database/uri", profile_id=id_to_analyze))
```
**3. Load from a Python dictionary:**
Please note that a lot of configuration is done by the loaders, so it's best to use one of the provided loaders.
```python
from peakshaving_analyzer import PeakShavingAnalyzer, Config
config_dict = {
"name": "MyScenario",
"consumption_timeseries": [...],
# further parameters
}
config = Config(config_dict)
```
### Initialize the Peakshaving Analyzer and run it:
Running the `optimize()` method will return a `Results` object.
```python
psa = PeakShavingAnalyzer(config=config)
results = psa.optimize(solver="your_prefered_solver")
```
### Saving Results
Results objects can be printed to std-out, written to file (.csv, .yaml, .json) or converted to python objects.
**1. Save as file (e.g. CSV, YAML, ...):**
```python
results = psa.optimize()
results.to_csv("results.csv")
results.to_json("results.json")
results.to_yaml("results.yaml")
```
For saving the timeseries, please use the following functions:
```python
results = psa.optimize()
results.timeseries_to_csv("timeseries.csv")
results.timeseries_to_json("timeseries.json")
```
**2. Save to database (TimescaleDB):**
If you use the Docker environment, results are automatically written to TimescaleDB. You can also trigger saving explicitly:
```python
results = psa.optimize()
results.to_sql(connection="your/database/uri")
```
**3. Use as Python object:**
After optimization, results are available as a Python object for further processing:
```python
results = psa.optimize()
# Access individual values
print(results.total_yearly_costs_eur)
# print everything
results.print()
# convert to dict or dataframe
results_dict = results.to_dict()
results_dataframe = results.to_dataframe()
```
**4. Plot the resulting timeseries:**
The resulting timeseries (storage charging / discharging, state of charge, solar generation, grid usage, ...) can be easily plotted:
```python
results = psa.optimize()
results.plot_timeseries()
results.plot_consumption_timeseries()
results.plot_storage_timeseries()
```
For more details on configuration, see the example files in the `examples` directory.
## Examples
In the `examples` directory are four examples:
* A scenario examining only a storage system using hourly values with a fixed, non-dynamic price for the used energy.
* A scenario examining only a storage system using quarterhouly values with a fixed, non-dynamic price for the used energy.
* A scenario examining only a storage system using quarterhourly values with a dynamic, time-depended price for the used energy.
* A scenario examining a storage system as well as a photovoltaic system using hourly values with a dynamic, time-depended price for the used energy.
You can run these examples with `python3 ./examples/example/main.py` from the base directory.
## License
This project is licensed under the terms of the LICENSE file.
Raw data
{
"_id": null,
"home_page": null,
"name": "peakshaving-analyzer",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "peak shaving, energy framework, energy optimization, optimization",
"author": null,
"author_email": "Christoph Komanns <c.komanns@gmail.com>, Florian Maurer <fmaurer@disroot.org>",
"download_url": "https://files.pythonhosted.org/packages/ec/c7/3c0a85dd5088925c8057e5f93d39cf0f048b75a72e92068d4d60d65f44f1/peakshaving_analyzer-0.1.7.tar.gz",
"platform": null,
"description": "# Peak Shaving Analyzer\n\nThis repository contains tools and utilities for analyzing and optimizing energy consumption with peak shaving strategies. The project includes data fetching, analysis, and visualization components, as well as Docker configurations for deployment.\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Features](#features)\n- [Installation](#installation)\n- [Usage](#usage)\n- [Examples](#examples)\n- [License](#license)\n\n## Overview\n\nPeak shaving is a strategy to reduce energy costs by minimizing peak demand utilizing energy storage systems. This project provides tools to optimize a given consumption time series with peak-shaving reducing capacity costs and visualizing results using Grafana.\n\n## Features\n\n- Peak shaving optimization using [FINE by FZJ](https://github.com/FZJ-IEK3-VSA/FINE)\n- Easy configuration of many parameters\n- Support for dynamic prices\n- Inclusion of PV system integration with automatic retrieving of generation timeseries depending on location (with detection for leap years)\n- Dockerized deployment with Grafana dashboards\n- Example configurations for various scenarios\n\n## Installation\n\nYou can install peakshaving-analyzer using pip. Choose the appropriate installation method based on your needs:\n\n### Using pip\n\nTo install the core package:\n\n```bash\npip install peakshaving-analyzer\n```\n\n### Timescale Database and Grafana Dashboards\n\nIf you want to benefit from a supported database and integrated Grafana dashboards for scenario analysis, you can use the provided Docker Compose file.\n\nFollow these steps:\n\n1. Clone the repository and navigate to its directory:\n\n```bash\ngit clone https://github.com/NOWUM/peakshaving-analyzer.git\ncd peakshaving-analyzer\n```\n\n2. Start the database and Grafana using the following command:\n\n```bash\ndocker compose up -d\n```\n\nThis will launch a container for TimescaleDB and Grafana with preconfigured dashboards for analysis. You can access the Grafana dashboards at `http://localhost:3000`.\n\n## Usage\n\nYou can use Peak Shaving Analyzer flexibly \u2013 either with a YAML configuration file, directly from Python code or use the [OpenEnergyDataServer](https://github.com/open-energy-data-server/open-energy-data-server). Results can be saved locally as files or in a database.\n\n### Using the CLI\n\nUse `psa -h` to see the usage of the CLI tool and it's options.\n\n### Loading the Configuration\n\n**1. Load from YAML configuration file:**\n```python\nfrom peakshaving_analyzer import PeakShavingAnalyzer, load_yaml_config\n\nconfig = load_yaml_config(\"/path/to/your/config.yml\")\n```\n\n**2. Load from OEDS:**\n```python\nfrom peakshaving_analyzer import PeakShavingAnalyzer, load_oeds_config\n\nconfig = load_oeds_config(load_oeds_config(con=\"your/database/uri\", profile_id=id_to_analyze))\n```\n\n**3. Load from a Python dictionary:**\n\nPlease note that a lot of configuration is done by the loaders, so it's best to use one of the provided loaders.\n```python\nfrom peakshaving_analyzer import PeakShavingAnalyzer, Config\n\nconfig_dict = {\n \"name\": \"MyScenario\",\n \"consumption_timeseries\": [...],\n # further parameters\n}\nconfig = Config(config_dict)\n```\n\n### Initialize the Peakshaving Analyzer and run it:\n\nRunning the `optimize()` method will return a `Results` object.\n```python\npsa = PeakShavingAnalyzer(config=config)\nresults = psa.optimize(solver=\"your_prefered_solver\")\n```\n\n### Saving Results\n\nResults objects can be printed to std-out, written to file (.csv, .yaml, .json) or converted to python objects.\n\n**1. Save as file (e.g. CSV, YAML, ...):**\n```python\nresults = psa.optimize()\nresults.to_csv(\"results.csv\")\nresults.to_json(\"results.json\")\nresults.to_yaml(\"results.yaml\")\n```\n\nFor saving the timeseries, please use the following functions:\n```python\nresults = psa.optimize()\nresults.timeseries_to_csv(\"timeseries.csv\")\nresults.timeseries_to_json(\"timeseries.json\")\n```\n\n\n**2. Save to database (TimescaleDB):**\nIf you use the Docker environment, results are automatically written to TimescaleDB. You can also trigger saving explicitly:\n```python\nresults = psa.optimize()\nresults.to_sql(connection=\"your/database/uri\")\n```\n\n**3. Use as Python object:**\n\nAfter optimization, results are available as a Python object for further processing:\n```python\nresults = psa.optimize()\n# Access individual values\nprint(results.total_yearly_costs_eur)\n\n# print everything\nresults.print()\n\n# convert to dict or dataframe\nresults_dict = results.to_dict()\nresults_dataframe = results.to_dataframe()\n```\n\n**4. Plot the resulting timeseries:**\n\nThe resulting timeseries (storage charging / discharging, state of charge, solar generation, grid usage, ...) can be easily plotted:\n\n```python\nresults = psa.optimize()\nresults.plot_timeseries()\nresults.plot_consumption_timeseries()\nresults.plot_storage_timeseries()\n```\n\nFor more details on configuration, see the example files in the `examples` directory.\n\n## Examples\n\nIn the `examples` directory are four examples:\n* A scenario examining only a storage system using hourly values with a fixed, non-dynamic price for the used energy.\n* A scenario examining only a storage system using quarterhouly values with a fixed, non-dynamic price for the used energy.\n* A scenario examining only a storage system using quarterhourly values with a dynamic, time-depended price for the used energy.\n* A scenario examining a storage system as well as a photovoltaic system using hourly values with a dynamic, time-depended price for the used energy.\n\nYou can run these examples with `python3 ./examples/example/main.py` from the base directory.\n\n## License\n\nThis project is licensed under the terms of the LICENSE file.\n",
"bugtrack_url": null,
"license": null,
"summary": "Peak shaving analysis for industrial load profiles",
"version": "0.1.7",
"project_urls": {
"Issues": "https://github.com/assume-framework/assume/issues",
"Repository": "https://github.com/NOWUM/peakshaving-analyzer"
},
"split_keywords": [
"peak shaving",
" energy framework",
" energy optimization",
" optimization"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e2af6487a91b48bfb91db1af83895763a45cb8762d187656b1d5f08b2c417bc1",
"md5": "2f7686403abcb750b983172d02e7de0f",
"sha256": "108a698174f48c1cfc15894781e24500a10a431d402937c25589b4f3f084bf48"
},
"downloads": -1,
"filename": "peakshaving_analyzer-0.1.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2f7686403abcb750b983172d02e7de0f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 16484,
"upload_time": "2025-09-05T11:51:16",
"upload_time_iso_8601": "2025-09-05T11:51:16.312403Z",
"url": "https://files.pythonhosted.org/packages/e2/af/6487a91b48bfb91db1af83895763a45cb8762d187656b1d5f08b2c417bc1/peakshaving_analyzer-0.1.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ecc73c0a85dd5088925c8057e5f93d39cf0f048b75a72e92068d4d60d65f44f1",
"md5": "6e2af4100f5aa71938f9718c6138ba68",
"sha256": "fcacfe1cfcdeeb7d9f65243fbe37291a9df3ed31dc68eea2d36f4098117ad380"
},
"downloads": -1,
"filename": "peakshaving_analyzer-0.1.7.tar.gz",
"has_sig": false,
"md5_digest": "6e2af4100f5aa71938f9718c6138ba68",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 17059,
"upload_time": "2025-09-05T11:51:17",
"upload_time_iso_8601": "2025-09-05T11:51:17.817454Z",
"url": "https://files.pythonhosted.org/packages/ec/c7/3c0a85dd5088925c8057e5f93d39cf0f048b75a72e92068d4d60d65f44f1/peakshaving_analyzer-0.1.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-05 11:51:17",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "assume-framework",
"github_project": "assume",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "peakshaving-analyzer"
}
JSON
