Mirrors/EOS
1
0
Fork 0
mirror of https://github.com/Akkudoktor-EOS/EOS.git synced 2026-08-31 12:46:38 +00:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

feat: electricity fee provider framework and generic providers (#1235)

Browse Source 
Add new provider class for electricity fees providers.

Add the generic providers:
- ElecFeeFixed
- ElecFeeImport

The providers provide predictions for:

- elecfee_consumption_amt_wh:
  Total fixed fee for consumed energy per Wh [amount/Wh]. This is the accumulation of all
  fixed per-Wh fees payable on "consumed energy - such as network charge, concession fee,
  and electricity charge - into a single amount.
- elecfee_consumption_percent_amt:
  Total fixed surcharge on consumed energy, given as a percentage of the monetary amount
  already charged for that energy [%]. This is the accumulation of all percentage-based
  surcharges payable on top of the consumed-energy fee - such as VAT - into a single
  percentage. This is a percentage of the fee amount, not a per-Wh rate.
- elecfee_feedin_amt_wh:
  Total fixed deduction from feed-in energy per Wh [amount/Wh]. This is the accumulation of
  all fixed per-Wh charges deducted from feed-in energy - such as metering fees or
  grid-operator handling "charges - into a single amount. Applied after the percentage-based
  deduction, i.e. it reduces the price by a flat amount per Wh rather than by a share of the
  raw price.
- elecfee_feedin_percent_amt:
  Total percentage deducted from the raw feed-in price (spot price) [%]. This is the
  accumulation of all percentage-based deductions payable on the feed-in tariff - such as a
  marketing or balancing fee retained by the aggregator - into a single percentage. It is
  applied as `raw_price * (100 - percent) / 100`, i.e. it scales down the raw price rather
  than adding a surcharge to it.

A new _apply_fee() method is added to the base class for ElecPrice and FeedInTariff to be used to
add the fees in a consistent way. Fees are taken from the active ElecFee provider and applied
to the raw prices given to the _apply_fee() method.

The optional application of fees is added to:

- ElecPriceAkkudoktor
- ElecPriceFixed
- ElecPriceEnergyCharts
- ElecPriceSMARD
- FeedInTariffEnergyCharts
- FeedInTariffFixed
- FeedInTariffSMARD

The import providers ElecPriceImport and FeedInTariffImport do not apply fees by intentention.

The following providers currently do not handle fees defined by ElecFee:

- ElecPriceTibber
- FeedInTariffAkkudoktor
- FeedInTariffDvhubOnline
- FeedInTariffTibber

The tests for this feature are either added or existing tests are extended.

The documentation was extended for the electricity fee provider settings.

Besides this feature further improvements are added:

* feat: add SMARD quarter-hour electricty price and feed-in tariff provider

* feat: to_series method for TimeWindows and ValueTimeWindows

  Additional to to_array the time window sequence can now also produce a pandas series.
  Test have been extended to cover the series generation.

* feat: use time windows in fixed feedin tariff provider

  Feedin tariff can now be configured by time windows - not a single value.

* feat: EOSdash select for PVLib inverters and modules

  Provide PVLib inverter and module names in config selection.

* feat: EOSdash lazy select for big option sets

  Add a new form for lazy selection of big option sets. Filtering and
  generation of the option set is done server-side.

* fix: use raw data for ETS/ median prediction

  Use to raw time series data for ETS/ median prediction to avoid interference
  by e.g. dynamic grid charges.

* fix: EOSdash config drops by type only on details resolve

  Drop configuration by type and path. Prevents dropping of configuration items
  with same type and level but different path.

* fix: EOSdash configuration section closes on update

  Open section if searching or if last update touched this category — including
  updates on deeply nested sub-fields.

* chore: make elecfeefixed, elecpricefixed and feedintarifffixed warn about no windows and default to 0

  Missining configuration creates default 0 value and a warning instead of an exception.

* fix: test setup for providers

  Reset db state on each test run.

* chore: improve config option naming for elecpricefixed.

* chore: adapt elecpricefixed test to changed time_windows naming

* chore: factorized common price provider helpers to priceabc.py

  Factorized common price provider helpers to priceabc.py. Add tests for these helpers.
  Reduce/ change testing of elecpriceabc.py and feedintariffabc.py to cover
  only specifics. Rest of testing is already covered by test_priceabc.py.

* chore: update version

Signed-off-by: Bobby Noelte <b0661n0e17e@gmail.com>
This commit is contained in:
Bobby Noelte
2026-08-23 02:26:16 +02:00
committed by GitHub
parent 6849b731b0
commit ba76087db9
71 changed files with 6584 additions and 1191 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/_generated/config.md
+1
View File
@@ -6,6 +6,7 @@
../_generated/configcache.md
../_generated/configdatabase.md
../_generated/configdevices.md
../_generated/configelecfee.md
../_generated/configelecprice.md
../_generated/configems.md
../_generated/configfeedintariff.md
docs/_generated/configelecfee.md
+296
View File
@@ -0,0 +1,296 @@
## Electricity Price Prediction Configuration
<!-- pyml disable line-length -->
:::{table} elecfee
:widths: 10 20 10 5 5 30
:align: left
| Name | Environment Variable | Type | Read-Only | Default | Description |
| ---- | -------------------- | ---- | --------- | ------- | ----------- |
| elecfeefixed | `EOS_ELECFEE__ELECFEEFIXED` | `ElecFeeFixedCommonSettings` | `rw` | `required` | Fixed electricity fees provider settings. |
| elecfeeimport | `EOS_ELECFEE__ELECFEEIMPORT` | `ElecFeeImportCommonSettings` | `rw` | `required` | Electricity fees import provider settings. |
| provider | `EOS_ELECFEE__PROVIDER` | `str | None` | `rw` | `None` | Electricity fee provider id of provider to be used. |
| providers | | `list[str]` | `ro` | `N/A` | Available electricity fee provider ids. |
:::
<!-- pyml enable line-length -->
<!-- pyml disable no-emphasis-as-heading -->
**Example Input**
<!-- pyml enable no-emphasis-as-heading -->
<!-- pyml disable line-length -->
```json
{
"elecfee": {
"provider": "ElecFeeFixed",
"elecfeefixed": {
"consumption_amt_kwh": {
"windows": []
},
"consumption_percent_amt": {
"windows": []
},
"feedin_amt_kwh": {
"windows": []
},
"feedin_percent_amt": {
"windows": []
}
},
"elecfeeimport": {
"import_file_path": null,
"import_json": null
}
}
}
```
<!-- pyml enable line-length -->
<!-- pyml disable no-emphasis-as-heading -->
**Example Output**
<!-- pyml enable no-emphasis-as-heading -->
<!-- pyml disable line-length -->
```json
{
"elecfee": {
"provider": "ElecFeeFixed",
"elecfeefixed": {
"consumption_amt_kwh": {
"windows": []
},
"consumption_percent_amt": {
"windows": []
},
"feedin_amt_kwh": {
"windows": []
},
"feedin_percent_amt": {
"windows": []
}
},
"elecfeeimport": {
"import_file_path": null,
"import_json": null
},
"providers": [
"ElecFeeFixed",
"ElecFeeImport"
]
}
}
```
<!-- pyml enable line-length -->
### Common settings for elecfee data import from file or JSON String
<!-- pyml disable line-length -->
:::{table} elecfee::elecfeeimport
:widths: 10 10 5 5 30
:align: left
| Name | Type | Read-Only | Default | Description |
| ---- | ---- | --------- | ------- | ----------- |
| import_file_path | `str | pathlib.Path | None` | `rw` | `None` | Path to the file to import elecfee data from. |
| import_json | `str | None` | `rw` | `None` | JSON string, dictionary of electricity fee forecast value lists. |
:::
<!-- pyml enable line-length -->
<!-- pyml disable no-emphasis-as-heading -->
**Example Input/Output**
<!-- pyml enable no-emphasis-as-heading -->
<!-- pyml disable line-length -->
```json
{
"elecfee": {
"elecfeeimport": {
"import_file_path": null,
"import_json": "{\"elecfee_consumption_amt_wh\": [0.0003384, 0.0003318, 0.0003284]}"
}
}
}
```
<!-- pyml enable line-length -->
### Value applicable during a specific time window
This model extends `TimeWindow` by associating a value with the defined time interval.
<!-- pyml disable line-length -->
:::{table} elecfee::elecfeefixed::consumption_amt_kwh::windows::list
:widths: 10 10 5 5 30
:align: left
| Name | Type | Read-Only | Default | Description |
| ---- | ---- | --------- | ------- | ----------- |
| date | `pydantic_extra_types.pendulum_dt.Date | None` | `rw` | `None` | Optional specific calendar date for the time window. Naive — matched against the local date of the datetime passed to contains(). Overrides `day_of_week` if set. |
| day_of_week | `int | str | None` | `rw` | `None` | Optional day of the week restriction. Can be specified as integer (0=Monday to 6=Sunday) or localized weekday name. If None, applies every day unless `date` is set. |
| duration | `Duration` | `rw` | `required` | Duration of the time window starting from `start_time`. |
| locale | `str | None` | `rw` | `None` | Locale used to parse weekday names in `day_of_week` when given as string. If not set, Pendulum's default locale is used. Examples: 'en', 'de', 'fr', etc. |
| start_time | `Time` | `rw` | `required` | Naive start time of the time window (time of day, no timezone). Interpreted in the timezone of the datetime passed to contains() or earliest_start_time(). |
| value | `float | None` | `rw` | `None` | Value applicable during this time window. |
:::
<!-- pyml enable line-length -->
<!-- pyml disable no-emphasis-as-heading -->
**Example Input/Output**
<!-- pyml enable no-emphasis-as-heading -->
<!-- pyml disable line-length -->
```json
{
"elecfee": {
"elecfeefixed": {
"consumption_amt_kwh": {
"windows": [
{
"start_time": "00:00:00.000000",
"duration": "2 hours",
"day_of_week": null,
"date": null,
"locale": null,
"value": 0.288
}
]
}
}
}
}
```
<!-- pyml enable line-length -->
### Sequence of value time windows
This model specializes `TimeWindowSequence` to ensure that all
contained windows are instances of `ValueTimeWindow`.
It provides the full set of sequence operations (containment checks,
availability, start time calculations) for value windows.
<!-- pyml disable line-length -->
:::{table} elecfee::elecfeefixed::consumption_amt_kwh
:widths: 10 10 5 5 30
:align: left
| Name | Type | Read-Only | Default | Description |
| ---- | ---- | --------- | ------- | ----------- |
| windows | `list[akkudoktoreos.config.configabc.ValueTimeWindow]` | `rw` | `required` | Ordered list of value time windows. Each window defines a time interval and an associated value. |
:::
<!-- pyml enable line-length -->
<!-- pyml disable no-emphasis-as-heading -->
**Example Input/Output**
<!-- pyml enable no-emphasis-as-heading -->
<!-- pyml disable line-length -->
```json
{
"elecfee": {
"elecfeefixed": {
"consumption_amt_kwh": {
"windows": []
}
}
}
}
```
<!-- pyml enable line-length -->
### Common settings for fixed electricity fees
This model defines a fixed electricity fee schedule using a sequence
of time windows. Each window specifies a time interval and the electricity
fee applicable during that interval.
<!-- pyml disable line-length -->
:::{table} elecfee::elecfeefixed
:widths: 10 10 5 5 30
:align: left
| Name | Type | Read-Only | Default | Description |
| ---- | ---- | --------- | ------- | ----------- |
| consumption_amt_kwh | `ValueTimeWindowSequence` | `rw` | `required` | Sequence of time windows defining the total fixed per-kWh electricty fee charged for consumed energy, accumulating all applicable fixed per-kWh charges (e.g. network charge, metering fee, concession fee) into a single amount [amount/kWh]. If not provided, no fixed per-kWh consumption fee is applied. |
| consumption_percent_amt | `ValueTimeWindowSequence` | `rw` | `required` | Sequence of time windows defining the total fixed electricity surcharge applied as a percentage of the monetary amount already charged for consumed energy, accumulating all applicable percentage-based surcharges (e.g. VAT, electricity tax) into a single percentage [%]. This is a percentage of the fee amount, not a per-kWh rate. If not provided, no percentage-based consumption surcharge is applied. |
| feedin_amt_kwh | `ValueTimeWindowSequence` | `rw` | `required` | Sequence of time windows defining the total deduction from feed-in energy per Wh [amount/Wh]. This is the accumulation of all fixed per-Wh charges deducted from feed-in energy - such as metering fees or grid-operator handling charges - into a single amount. Applied after the percentage-based deduction, i.e. it reduces the price by a flat amount per Wh rather than by a share of the raw price. If not provided, no fixed per-kWh feed-in fee is applied. |
| feedin_percent_amt | `ValueTimeWindowSequence` | `rw` | `required` | Sequence of time windows defining the total percentage deducted from the raw feed-in price (spot price) [%]. This is the accumulation of all percentage-based deductions payable on the feed-in tariff - such as a marketing or balancing fee retained by the aggregator - into a single percentage. It is applied as `raw_price * (100 - percent) / 100`, i.e. it scales down the raw price rather than adding a surcharge to it. If not provided, no percentage-based feed-in deduction is applied. |
:::
<!-- pyml enable line-length -->
<!-- pyml disable no-emphasis-as-heading -->
**Example Input/Output**
<!-- pyml enable no-emphasis-as-heading -->
<!-- pyml disable line-length -->
```json
{
"elecfee": {
"elecfeefixed": {
"consumption_amt_kwh": {
"windows": [
{
"start_time": "00:00:00.000000",
"duration": "8 hours",
"day_of_week": null,
"date": null,
"locale": null,
"value": 0.00288
},
{
"start_time": "08:00:00.000000",
"duration": "16 hours",
"day_of_week": null,
"date": null,
"locale": null,
"value": 0.0034
}
]
},
"consumption_percent_amt": {
"windows": [
{
"start_time": "00:00:00.000000",
"duration": "1 day",
"day_of_week": null,
"date": null,
"locale": null,
"value": 19.0
}
]
},
"feedin_amt_kwh": {
"windows": [
{
"start_time": "00:00:00.000000",
"duration": "8 hours",
"day_of_week": null,
"date": null,
"locale": null,
"value": 0.00288
},
{
"start_time": "08:00:00.000000",
"duration": "16 hours",
"day_of_week": null,
"date": null,
"locale": null,
"value": 0.0034
}
]
},
"feedin_percent_amt": {
"windows": [
{
"start_time": "00:00:00.000000",
"duration": "1 day",
"day_of_week": null,
"date": null,
"locale": null,
"value": 19.0
}
]
}
}
}
}
```
<!-- pyml enable line-length -->
docs/_generated/configelecprice.md
+74 -93
View File
@@ -7,14 +7,14 @@
| Name | Environment Variable | Type | Read-Only | Default | Description |
| ---- | -------------------- | ---- | --------- | ------- | ----------- |
| charges_kwh | `EOS_ELECPRICE__CHARGES_KWH` | `float | None` | `rw` | `None` | Electricity price charges [amount/kWh]. Will be added to variable market price. |
| akkudoktor | `EOS_ELECPRICE__AKKUDOKTOR` | `ElecPriceAkkudoktorCommonSettings` | `rw` | `required` | Akkudoktor electricity price provider settings. |
| elecpricefixed | `EOS_ELECPRICE__ELECPRICEFIXED` | `ElecPriceFixedCommonSettings` | `rw` | `required` | Fixed electricity price provider settings. |
| elecpriceimport | `EOS_ELECPRICE__ELECPRICEIMPORT` | `ElecPriceImportCommonSettings` | `rw` | `required` | Electricity price import provider settings. |
| energycharts | `EOS_ELECPRICE__ENERGYCHARTS` | `ElecPriceEnergyChartsCommonSettings` | `rw` | `required` | Energy Charts provider settings. |
| provider | `EOS_ELECPRICE__PROVIDER` | `str | None` | `rw` | `None` | Electricity price provider id of provider to be used. |
| providers | | `list[str]` | `ro` | `N/A` | Available electricity price provider ids. |
| smard | `EOS_ELECPRICE__SMARD` | `ElecPriceSMARDCommonSettings` | `rw` | `required` | SMARD electricity price provider settings. |
| tibber | `EOS_ELECPRICE__TIBBER` | `ElecPriceTibberCommonSettings` | `rw` | `required` | Tibber electricity price provider settings. |
| vat_rate | `EOS_ELECPRICE__VAT_RATE` | `float | None` | `rw` | `1.19` | VAT rate factor applied to electricity price when charges are used. |
:::
<!-- pyml enable line-length -->
@@ -27,10 +27,9 @@
{
"elecprice": {
"provider": "ElecPriceAkkudoktor",
"charges_kwh": 0.21,
"vat_rate": 1.19,
"akkudoktor": {},
"elecpricefixed": {
"time_windows": {
"elecprice_marketprice_amt_kwh": {
"windows": []
}
},
@@ -41,6 +40,10 @@
"energycharts": {
"bidding_zone": "DE-LU"
},
"smard": {
"filter_id": 4169,
"region": "DE"
},
"tibber": {
"access_token": null,
"home_id": null
@@ -59,10 +62,9 @@
{
"elecprice": {
"provider": "ElecPriceAkkudoktor",
"charges_kwh": 0.21,
"vat_rate": 1.19,
"akkudoktor": {},
"elecpricefixed": {
"time_windows": {
"elecprice_marketprice_amt_kwh": {
"windows": []
}
},
@@ -73,6 +75,10 @@
"energycharts": {
"bidding_zone": "DE-LU"
},
"smard": {
"filter_id": 4169,
"region": "DE"
},
"tibber": {
"access_token": null,
"home_id": null
@@ -82,6 +88,7 @@
"ElecPriceEnergyCharts",
"ElecPriceFixed",
"ElecPriceImport",
"ElecPriceSMARD",
"ElecPriceTibber"
]
}
@@ -120,6 +127,37 @@
```
<!-- pyml enable line-length -->
### Common settings for the direct SMARD electricity-price provider
<!-- pyml disable line-length -->
:::{table} elecprice::smard
:widths: 10 10 5 5 30
:align: left
| Name | Type | Read-Only | Default | Description |
| ---- | ---- | --------- | ------- | ----------- |
| filter_id | `int` | `rw` | `4169` | SMARD filter id for the German/Luxembourg day-ahead price. |
| region | `str` | `rw` | `DE` | SMARD market region used in the chart-data endpoint. |
:::
<!-- pyml enable line-length -->
<!-- pyml disable no-emphasis-as-heading -->
**Example Input/Output**
<!-- pyml enable no-emphasis-as-heading -->
<!-- pyml disable line-length -->
```json
{
"elecprice": {
"smard": {
"filter_id": 4169,
"region": "DE"
}
}
}
```
<!-- pyml enable line-length -->
### Common settings for Energy Charts electricity price provider
<!-- pyml disable line-length -->
@@ -180,89 +218,6 @@
```
<!-- pyml enable line-length -->
### Value applicable during a specific time window
This model extends `TimeWindow` by associating a value with the defined time interval.
<!-- pyml disable line-length -->
:::{table} elecprice::elecpricefixed::time_windows::windows::list
:widths: 10 10 5 5 30
:align: left
| Name | Type | Read-Only | Default | Description |
| ---- | ---- | --------- | ------- | ----------- |
| date | `pydantic_extra_types.pendulum_dt.Date | None` | `rw` | `None` | Optional specific calendar date for the time window. Naive — matched against the local date of the datetime passed to contains(). Overrides `day_of_week` if set. |
| day_of_week | `int | str | None` | `rw` | `None` | Optional day of the week restriction. Can be specified as integer (0=Monday to 6=Sunday) or localized weekday name. If None, applies every day unless `date` is set. |
| duration | `Duration` | `rw` | `required` | Duration of the time window starting from `start_time`. |
| locale | `str | None` | `rw` | `None` | Locale used to parse weekday names in `day_of_week` when given as string. If not set, Pendulum's default locale is used. Examples: 'en', 'de', 'fr', etc. |
| start_time | `Time` | `rw` | `required` | Naive start time of the time window (time of day, no timezone). Interpreted in the timezone of the datetime passed to contains() or earliest_start_time(). |
| value | `float | None` | `rw` | `None` | Value applicable during this time window. |
:::
<!-- pyml enable line-length -->
<!-- pyml disable no-emphasis-as-heading -->
**Example Input/Output**
<!-- pyml enable no-emphasis-as-heading -->
<!-- pyml disable line-length -->
```json
{
"elecprice": {
"elecpricefixed": {
"time_windows": {
"windows": [
{
"start_time": "00:00:00.000000",
"duration": "2 hours",
"day_of_week": null,
"date": null,
"locale": null,
"value": 0.288
}
]
}
}
}
}
```
<!-- pyml enable line-length -->
### Sequence of value time windows
This model specializes `TimeWindowSequence` to ensure that all
contained windows are instances of `ValueTimeWindow`.
It provides the full set of sequence operations (containment checks,
availability, start time calculations) for value windows.
<!-- pyml disable line-length -->
:::{table} elecprice::elecpricefixed::time_windows
:widths: 10 10 5 5 30
:align: left
| Name | Type | Read-Only | Default | Description |
| ---- | ---- | --------- | ------- | ----------- |
| windows | `list[akkudoktoreos.config.configabc.ValueTimeWindow]` | `rw` | `required` | Ordered list of value time windows. Each window defines a time interval and an associated value. |
:::
<!-- pyml enable line-length -->
<!-- pyml disable no-emphasis-as-heading -->
**Example Input/Output**
<!-- pyml enable no-emphasis-as-heading -->
<!-- pyml disable line-length -->
```json
{
"elecprice": {
"elecpricefixed": {
"time_windows": {
"windows": []
}
}
}
}
```
<!-- pyml enable line-length -->
### Common configuration settings for fixed electricity pricing
This model defines a fixed electricity price schedule using a sequence
@@ -276,7 +231,7 @@ price applicable during that interval.
| Name | Type | Read-Only | Default | Description |
| ---- | ---- | --------- | ------- | ----------- |
| time_windows | `ValueTimeWindowSequence` | `rw` | `required` | Sequence of time windows defining the fixed price schedule. If not provided, no fixed pricing is applied. |
| elecprice_marketprice_amt_kwh | `ValueTimeWindowSequence` | `rw` | `required` | Sequence of time windows defining the fixed price schedule. If not provided, no fixed pricing is applied. |
:::
<!-- pyml enable line-length -->
@@ -289,7 +244,7 @@ price applicable during that interval.
{
"elecprice": {
"elecpricefixed": {
"time_windows": {
"elecprice_marketprice_amt_kwh": {
"windows": [
{
"start_time": "00:00:00.000000",
@@ -314,3 +269,29 @@ price applicable during that interval.
}
```
<!-- pyml enable line-length -->
### Common configuration settings for Akkodoktor electricity pricing
<!-- pyml disable line-length -->
:::{table} elecprice::akkudoktor
:widths: 10 10 5 5 30
:align: left
| Name | Type | Read-Only | Default | Description |
| ---- | ---- | --------- | ------- | ----------- |
:::
<!-- pyml enable line-length -->
<!-- pyml disable no-emphasis-as-heading -->
**Example Input/Output**
<!-- pyml enable no-emphasis-as-heading -->
<!-- pyml disable line-length -->
```json
{
"elecprice": {
"akkudoktor": {}
}
}
```
<!-- pyml enable line-length -->
docs/_generated/configexample.md
+32 -5
View File
@@ -95,12 +95,32 @@
"home_appliances": [],
"max_home_appliances": 1
},
"elecfee": {
"provider": "ElecFeeFixed",
"elecfeefixed": {
"consumption_amt_kwh": {
"windows": []
},
"consumption_percent_amt": {
"windows": []
},
"feedin_amt_kwh": {
"windows": []
},
"feedin_percent_amt": {
"windows": []
}
},
"elecfeeimport": {
"import_file_path": null,
"import_json": null
}
},
"elecprice": {
"provider": "ElecPriceAkkudoktor",
"charges_kwh": 0.21,
"vat_rate": 1.19,
"akkudoktor": {},
"elecpricefixed": {
"time_windows": {
"elecprice_marketprice_amt_kwh": {
"windows": []
}
},
@@ -111,6 +131,10 @@
"energycharts": {
"bidding_zone": "DE-LU"
},
"smard": {
"filter_id": 4169,
"region": "DE"
},
"tibber": {
"access_token": null,
"home_id": null
@@ -124,7 +148,9 @@
"feedintariff": {
"provider": "FeedInTariffFixed",
"feedintarifffixed": {
"feed_in_tariff_kwh": null
"feed_in_tariff_amt_kwh": {
"windows": []
}
},
"feedintariffimport": {
"import_file_path": null,
@@ -136,7 +162,8 @@
},
"energycharts": {
"bidding_zone": "DE-LU"
}
},
"smard": {}
},
"general": {
"config_save_mode": "AUTOMATIC",
docs/_generated/configfeedintariff.md
+58 -5
View File
@@ -13,6 +13,7 @@
| feedintariffimport | `EOS_FEEDINTARIFF__FEEDINTARIFFIMPORT` | `FeedInTariffImportCommonSettings` | `rw` | `required` | Feed in tarif import provider settings. |
| provider | `EOS_FEEDINTARIFF__PROVIDER` | `str | None` | `rw` | `None` | Feed in tariff provider id of provider to be used. |
| providers | | `list[str]` | `ro` | `N/A` | Available feed in tariff provider ids. |
| smard | `EOS_FEEDINTARIFF__SMARD` | `FeedInTariffSMARDCommonSettings` | `rw` | `required` | SMARD feed in tariff provider settings. |
:::
<!-- pyml enable line-length -->
@@ -26,7 +27,9 @@
"feedintariff": {
"provider": "FeedInTariffFixed",
"feedintarifffixed": {
"feed_in_tariff_kwh": null
"feed_in_tariff_amt_kwh": {
"windows": []
}
},
"feedintariffimport": {
"import_file_path": null,
@@ -38,7 +41,8 @@
},
"energycharts": {
"bidding_zone": "DE-LU"
}
},
"smard": {}
}
}
```
@@ -54,7 +58,9 @@
"feedintariff": {
"provider": "FeedInTariffFixed",
"feedintarifffixed": {
"feed_in_tariff_kwh": null
"feed_in_tariff_amt_kwh": {
"windows": []
}
},
"feedintariffimport": {
"import_file_path": null,
@@ -67,12 +73,14 @@
"energycharts": {
"bidding_zone": "DE-LU"
},
"smard": {},
"providers": [
"FeedInTariffAkkudoktor",
"FeedInTariffDvhubOnline",
"FeedInTariffEnergyCharts",
"FeedInTariffFixed",
"FeedInTariffImport",
"FeedInTariffSMARD",
"FeedInTariffTibber"
]
}
@@ -80,6 +88,32 @@
```
<!-- pyml enable line-length -->
### Settings for SMARD feed-in prices shared with ``elecprice.smard``
<!-- pyml disable line-length -->
:::{table} feedintariff::smard
:widths: 10 10 5 5 30
:align: left
| Name | Type | Read-Only | Default | Description |
| ---- | ---- | --------- | ------- | ----------- |
:::
<!-- pyml enable line-length -->
<!-- pyml disable no-emphasis-as-heading -->
**Example Input/Output**
<!-- pyml enable no-emphasis-as-heading -->
<!-- pyml disable line-length -->
```json
{
"feedintariff": {
"smard": {}
}
}
```
<!-- pyml enable line-length -->
### Common settings for feed in tariff data import from file or JSON string
<!-- pyml disable line-length -->
@@ -120,7 +154,7 @@
| Name | Type | Read-Only | Default | Description |
| ---- | ---- | --------- | ------- | ----------- |
| feed_in_tariff_kwh | `float | None` | `rw` | `None` | Electricity price feed in tariff [amount/kWh]. |
| feed_in_tariff_amt_kwh | `ValueTimeWindowSequence` | `rw` | `required` | Sequence of time windows defining the electricity feed in tariff [amount/kWh]. If not provided, no fixed feed in tariff is applied. |
:::
<!-- pyml enable line-length -->
@@ -133,7 +167,26 @@
{
"feedintariff": {
"feedintarifffixed": {
"feed_in_tariff_kwh": 0.078
"feed_in_tariff_amt_kwh": {
"windows": [
{
"start_time": "00:00:00.000000",
"duration": "8 hours",
"day_of_week": null,
"date": null,
"locale": null,
"value": 0.028
},
{
"start_time": "08:00:00.000000",
"duration": "16 hours",
"day_of_week": null,
"date": null,
"locale": null,
"value": 0.034
}
]
}
}
}
}
docs/_generated/openapi.md
+1 -1
View File
@@ -1,6 +1,6 @@
# Akkudoktor-EOS
**Version**: `v0.3.0.dev2608160647074704`
**Version**: `v0.3.0.dev2608221553448643`
<!-- pyml disable line-length -->
**Description**: This project provides a comprehensive solution for simulating and optimizing an energy system based on renewable energy sources. With a focus on photovoltaic (PV) systems, battery storage (batteries), load management (consumer requirements), heat pumps, electric vehicles, and consideration of electricity price data, this system enables forecasting and optimization of energy flow and costs over a specified period.
docs/akkudoktoreos/prediction.md
+212 -25
View File
@@ -121,12 +121,107 @@ If no keys are displayed, or if the ones you need are missing, it indicates that
lacks the necessary prediction provider settings. You can configure prediction providers by using
the **PUT** `/v1/config` endpoint. You may save your configuration to the EOS configuration file.
## Electricity Fee Prediction
Prediction keys:
- `elecfee_consumption_amt_wh`: Total fixed fee for consumed energy per Wh (amount/Wh),
accumulating all fixed per-Wh fees payable on consumed energy - such as network charge,
concession fee, and electricity charge - into a single amount.
- `elecfee_consumption_amt_kwh`: Total fixed fee for consumed energy per kWh (amount/kWh),
calculated from `elecfee_consumption_amt_wh`.
- `elecfee_consumption_percent_amt`: Total fixed surcharge on consumed energy, given as a
percentage of the monetary amount already charged for that energy (%), accumulating all
percentage-based surcharges - such as VAT - into a single percentage. Applied after
`elecfee_consumption_amt_wh`, i.e. it is calculated on the raw price plus the per-Wh fee.
- `elecfee_feedin_amt_wh`: Total fixed fee for feed-in energy per Wh (amount/Wh), accumulating
all fixed per-Wh fees payable on feed-in energy - such as network charge and concession fee -
into a single amount. Applied after `elecfee_feedin_percent_amt`, i.e. it is deducted from
the price as a flat per-Wh amount once the percentage deduction has already been applied.
- `elecfee_feedin_amt_kwh`: Total fixed fee for feed-in energy per kWh (amount/kWh),
calculated from `elecfee_feedin_amt_wh`.
- `elecfee_feedin_percent_amt`: Total fixed deduction on feed-in energy, given as a percentage
of the raw feed-in price (spot price) for that energy (%), accumulating all percentage-based
deductions - such as a marketing or balancing fee retained by the aggregator - into a single
percentage. Applied to the raw price before `elecfee_feedin_amt_wh` is subtracted.
Configuration options:
- `elecfee`: Electricity fee configuration.
- `provider`: Electricity fee provider id of provider to be used.
- `ElecFeeFixed`: Caluclates from configured time window fees.
- `ElecFeeImport`: Imports from a file or JSON string or by endpoint data provision.
- `elecfeefixed.consumption_amt_kwh.windows`: Time windows defining the total fixed per-kWh
fee for consumed energy, accumulating fees such as network charge, metering fee, and
concession fee into a single amount (amount/kWh).
- `elecfeefixed.consumption_percent_amt.windows`: Time windows defining the total fixed
surcharge on consumed energy, given as a percentage of the amount already charged,
accumulating surcharges such as VAT into a single percentage (%).
- `elecfeefixed.feedin_amt_kwh.windows`: Time windows defining the total fixed per-kWh fee
or credit for feed-in energy, accumulating fees such as network charge and metering fee
into a single amount (amount/kWh).
- `elecfeefixed.feedin_percent_amt.windows`: Time windows defining the total fixed
deduction on feed-in energy, given as a percentage of the raw feed-in price (spot price),
accumulating deductions such as a service charge into a single percentage (%).
- `elecfeeimport.import_file_path`: Path to the file to import electricity fee forecast data from.
- `elecfeeimport.import_json`: JSON string, dictionary of electricity fee forecast value lists.
### ElecFeeFixed Provider
The `ElecFeeFixed` provider calculates the electricity fees from the configuration
of electricity fee time windows set up by the user.
### ElecFeeImport Provider
The `ElecFeeImport` provider is designed to import electricity prices from:
- A file or a JSON string (primarily for initialization). The data source can be given in the
`import_file_path` or `import_json` configuration option.
- The **PUT** `/v1/prediction/import/ElecFeeImport` endpoint (recommended for dynamic updates).
The prediction keys for the electricity fee forecast data are:
- `elecfee_consumption_amt_wh`: Total fixed fee for consumed energy per Wh (amount/Wh),
accumulating all fixed per-Wh fees payable on consumed energy - such as network charge,
concession fee, and electricity charge - into a single amount.
- `elecfee_consumption_percent_amt`: Total fixed surcharge on consumed energy, given as a
percentage of the monetary amount already charged for that energy (%), accumulating all
percentage-based surcharges - such as VAT - into a single percentage.
- `elecfee_feedin_amt_wh`: Total fixed fee for feed-in energy per Wh (amount/Wh), accumulating
all fixed per-Wh fees payable on feed-in energy - such as network charge and concession fee -
into a single amount.
- `elecfee_feedin_percent_amt`: Total fixed deduction on feed-in energy, given as a percentage
of the raw feed-in price (spot price) for that energy (%), accumulating all percentage-based
deductions into a single percentage.
The electricity fee forecast data must be provided in one of the formats described in
<project:#prediction-import-providers>.
An external entity may update the file or JSON string whenever new prediction data becomes
available. However, for production use or regular updates, you should prefer the **PUT** endpoint
over file or JSON string based imports.
:::{admonition} Warning
:class: warning
Be aware that providing dynamic values via a file and/or JSON string **alongside other value
sources** can lead to unintended data overwrites. Moreover, after a restart, even outdated values
from the configuration may be reloaded. To avoid these issues, use the **PUT** endpoint for live
data and rely on file/JSON imports only for initial setup.
:::
## Electricity Price Prediction
Prediction keys:
- `elecprice_marketprice_wh`: Electricity market price per Wh (€/Wh).
- `elecprice_marketprice_kwh`: Electricity market price per kWh (€/kWh).
- `elecprice_marketprice_raw_wh`: Raw electricity market price per Wh, always excluding fees
(amount/Wh).
- `elecprice_marketprice_wh`: Electricity market price per Wh, including fees if configured
(amount/Wh).
- `elecprice_marketprice_kwh`: Electricity market price per kWh (amount/kWh), calculated from
`elecprice_marketprice_wh`.
Configuration options:
@@ -139,20 +234,29 @@ Configuration options:
- `ElecPriceFixed`: Caluclates from configured time window prices.
- `ElecPriceImport`: Imports from a file or JSON string or by endpoint data provision.
- `charges_kwh`: Electricity price charges (€/kWh).
- `vat_rate`: VAT rate factor applied to electricity price when charges are used (default: 1.19).
- `elecpricefixed.time_windows.windows`: The time windows with associated electricity prices.
- `elecpricefixed.elecprice_marketprice_amt_kwh.windows`: The time windows with associated
electricity prices.
- `elecpriceimport.import_file_path`: Path to the file to import electricity price forecast data from.
- `elecpriceimport.import_json`: JSON string, dictionary of electricity price forecast value lists.
- `energycharts.bidding_zone`: Bidding zone Energy Charts shall provide price data for.
Fees:
- If `fees` are given by the ElecFee prediction, the electricity fees are added to the raw market
price and stored in `elecprice_marketprice_wh`.
- The resulting price is calculated as:
`(raw market price + elecfee_consumption_amt_wh) * (100 + elecfee_consumption_percent_amt) / 100`
where `elecfee_consumption_amt_wh` and `elecfee_consumption_percent_amt` are given by the
ElecFee prediction.
### ElecPriceAkkudoktor Provider
The `ElecPriceAkkudoktor` provider retrieves electricity prices directly from **Akkudoktor.net**,
which supplies price data for the next 24 hours. For periods beyond 24 hours, the provider generates
prices by extrapolating historical price data combined with the most recent actual prices obtained
from Akkudoktor.net. Electricity price charges given in the `charges_kwh` configuration
option are added.
from Akkudoktor.net.
Fees are applied if given by the `ElecFee` prediction.
### ElecPriceEnergyCharts Provider
@@ -164,19 +268,20 @@ forecasting by combining real-time market data with historical price trends.
- For periods beyond 24 hours, prices are estimated using extrapolation based on historical data
and the latest available market values.
Charges and VAT
Fees are applied if given by the `ElecFee` prediction.
- If `charges_kwh` configuration option is greater than 0, the electricity price is calculated as:
`(market price + charges_kwh) * vat_rate` where `vat_rate` is configurable (default: 1.19 for 19% VAT).
- If `charges_kwh` is set to 0, the electricity price is simply: `market_price` (no VAT applied).
**Note:** For the most accurate forecasts, it is recommended to set the `historic_hours` parameter to 840.
:::{admonition} Note
:class: note
For the most accurate forecasts, it is recommended to set the `historic_hours` parameter to 840.
:::
### ElecPriceFixed Provider
The `ElecPriceFixed` provider calculates the day-ahead electricity market prices from the configuration
of electricity price time windows set up by the user.
Fees are applied if given by the `ElecFee` prediction.
### ElecPriceImport Provider
The `ElecPriceImport` provider is designed to import electricity prices from:
@@ -185,9 +290,11 @@ The `ElecPriceImport` provider is designed to import electricity prices from:
`import_file_path` or `import_json` configuration option.
- The **PUT** `/v1/prediction/import/ElecPriceImport` endpoint (recommended for dynamic updates).
The prediction key for the electricity price forecast data is:
The prediction keys for the electricity price forecast data are:
- `elecprice_marketprice_wh`: Electricity market price per Wh (€/Wh).
- `elecprice_marketprice_raw_wh`: Raw electricity market price per Wh, always excluding fees
(amount/Wh).
- `elecprice_marketprice_wh`: Electricity market price per Wh, including fees if wished (amount/Wh).
The electricity price forecast data must be provided in one of the formats described in
<project:#prediction-import-providers>.
@@ -204,12 +311,38 @@ from the configuration may be reloaded. To avoid these issues, use the **PUT** e
data and rely on file/JSON imports only for initial setup.
:::
:::{admonition} Note
:class: note
No fees are applied, even if given by the `ElecFee` prediction.
:::
### ElecPriceSMARD Provider
The `ElecPriceSMARD` provider retrieves quarter-hourly German/Luxembourg day-ahead prices directly
from the public SMARD chart-data endpoint. It requests the required weekly chunks only and caches
the combined response for one hour. Missing quarter-hour slots beyond the published day-ahead
horizon are generated with the same daily or weekly seasonal ETS forecast as the Energy-Charts
provider.
Fees are applied if given by the ElecFee prediction.
The same raw SMARD series is also available as `FeedInTariffSMARD` for direct-marketing feed-in
revenue.
### ElecPriceTibber Provider
:::{admonition} Warning
:class: warning
`elecprice_marketprice_raw_wh` is currently not filled by the `ElecPriceTibber` prediction.
:::
## Feed In Tariff Prediction
Prediction keys:
- `feed_in_tariff_wh`: Feed in tarif per Wh (€/Wh).
- `feed_in_tariff_kwh`: Feed in tarif per kWh (€/kWh)
- `feed_in_tariff_raw_wh`: Feed in tarif per Wh, always excluding fees (€/Wh).
- `feed_in_tariff_wh`: Feed in tarif per Wh, including fees if configured (€/Wh).
- `feed_in_tariff_kwh`: Feed in tarif per kWh (€/kWh), calculated from `feed_in_tariff_wh`.
Configuration options:
@@ -226,16 +359,26 @@ Configuration options:
- `FeedInTariffTibber`: Retrieves Tibber's native quarter-hour energy-price component.
- `energycharts.bidding_zone`: Bidding zone Energy Charts shall provide feed-in tariff for.
- `feedintarifffixed.feed_in_tariff_kwh`: Fixed feed in tariff (€/kWh).
- `feedintarifffixed.feed_in_tariff_amt_kwh.windows`: The time windows with associated
fixed feed-in tariff (Amount/kWh).
- `feedintariffimport.import_file_path`: Path to the file to import feed in tariff forecast data from.
- `feedintariffimport.import_json`: JSON string, dictionary of feed in tariff value lists.
Fees:
- If `fees` are given by the ElecFee prediction, the electricity fees are subtracted from the
raw feed-in tariff and stored in `feed_in_tariff_wh`.
- The resulting tariff is calculated as:
`raw feed in tariff * (100 - elecfee_feedin_percent_amt) / 100 - elecfee_feedin_amt_wh`
where `elecfee_feedin_amt_wh` and `elecfee_feedin_percent_amt` are given by the
ElecFee prediction.
### FeedInTariffAkkudoktor Provider
The `FeedInTariffAkkudoktor` provider uses raw day-ahead market prices from
`https://api.akkudoktor.net/prices` as `feed_in_tariff_wh`. It does not add electricity import
charges or VAT. Published prices are extended to the configured prediction horizon with the same
seasonal ETS or median fallback used by the Akkudoktor electricity-price provider.
`https://api.akkudoktor.net/prices` as `feed_in_tariff_wh`. Published prices are extended to
the configured prediction horizon with the same seasonal ETS or median fallback used by the
Akkudoktor electricity-price provider.
The Akkudoktor endpoint currently forwards hourly market prices from aWATTar. With a 15-minute
optimization interval, EOS holds each hourly price constant for its four quarter-hour slots. This
@@ -249,11 +392,25 @@ keeps the slot grid consistent but does not create genuine quarter-hour market p
}
```
:::{admonition} Warning
:class: warning
`feed_in_tariff_raw_wh` is currently not filled by the `FeedInTariffAkkudoktor` prediction.
:::
:::{admonition} Note
:class: note
No fees are applied, even if given by the `ElecFee` prediction.
:::
### FeedInTariffDvhubOnline Provider
TBD
### FeedInTariffEnergyCharts Provider
The `FeedInTariffEnergyCharts` provider uses the raw Energy-Charts day-ahead market price as the
feed-in tariff. It stores prices in `feed_in_tariff_wh` without adding electricity import charges
or VAT. The data is loaded from the Energy-Charts `/price` endpoint for the configured bidding
feed-in tariff. It stores raw prices in `feed_in_tariff_raw_wh` without adding electricity fees.
The data is loaded from the Energy-Charts `/price` endpoint for the configured bidding
zone. The native Energy-Charts resolution, including quarter-hour data, is retained.
Energy-Charts usually supplies prices only for the published day-ahead period. If that data does
@@ -269,6 +426,8 @@ four values per hour. Values already supplied by Energy-Charts are kept unchange
future slots after the last published price are forecast. Consequently, a 15-minute optimization
uses four forecast values per hour without converting them to hourly averages.
Fees are applied if given by the `ElecFee` prediction.
Example configuration:
```json
@@ -282,6 +441,13 @@ Example configuration:
}
```
### FeedInTariffFixed Provider
The `FeedInTariffFixed` provider calculates the day-ahead feed-in tariffs from the configuration
of feed-in tariff time windows set up by the user.
Fees are applied if given by the `ElecFee` prediction.
### FeedInTariffImport Provider
The `FeedInTariffImport` provider is designed to import feed in tariff prices from:
@@ -290,9 +456,10 @@ The `FeedInTariffImport` provider is designed to import feed in tariff prices fr
`import_file_path` or `import_json` configuration option.
- The **PUT** `/v1/prediction/import/FeedInTariffImport` endpoint (recommended for dynamic updates).
The prediction key for the feed in tariff price forecast data is:
The prediction keys for the feed in tariff price forecast data are:
- `feed_in_tariff_wh`: Feed in tariff price per Wh (€/Wh).
- `feed_in_tariff_raw_wh`: Feed in tarif per Wh, always excluding fees (€/Wh).
- `feed_in_tariff_wh`: Feed in tarif per Wh, including fees if wished (€/Wh).
The feed in tariff price forecast data must be provided in one of the formats described in
<project:#prediction-import-providers>.
@@ -309,6 +476,21 @@ from the configuration may be reloaded. To avoid these issues, use the **PUT** e
data and rely on file/JSON imports only for initial setup.
:::
:::{admonition} Note
:class: note
No fees are applied, even if given by the `ElecFee` prediction.
:::
### FeedInTariffSMARD Provider
he `FeedInTariffSMARD` provider retrieves quarter-hourly German/Luxembourg day-ahead prices directly
from the public SMARD chart-data endpoint. It requests the required weekly chunks only and caches
the combined response for one hour. Missing quarter-hour slots beyond the published day-ahead
horizon are generated with the same daily or weekly seasonal ETS forecast as the Energy-Charts
provider.
Fees are applied if given by the `ElecFee` prediction.
### FeedInTariffTibber Provider
The `FeedInTariffTibber` provider requests `priceInfo` and `priceInfoRange` with
@@ -328,6 +510,11 @@ are needed.
}
```
:::{admonition} Warning
:class: warning
`feed_in_tariff_raw_wh` is currently not filled by the `FeedInTariffTibber` prediction.
:::
## Load Prediction
Prediction keys: