feat: add EnergyCharts feed-in tariff provider (#1165)

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
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
not cover the complete configured prediction horizon, the provider extends it as follows:

- With more than 800 hours of history, an ETS (Holt-Winters exponential smoothing) forecast with
  weekly seasonality is used.
- With more than 168 hours of history, an ETS forecast with daily seasonality is used.
- With less history, the median of the available values is used as a constant fallback.

The seasonal periods are adjusted to the source resolution. For example, quarter-hour data uses
four values per hour. Values already supplied by Energy-Charts are kept unchanged; only missing
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.

Signed-off-by: Andreas Schmitz <akkudoktor.net>
Signed-off-by: Bobby Noelte <b0661n0e17e@gmail.com>

docs/_generated/configexample.md

@@ -129,6 +129,9 @@
            "feedintariffimport": {
                "import_file_path": null,
                "import_json": null
+           },
+           "energycharts": {
+               "bidding_zone": "DE-LU"
            }
        },
        "general": {

docs/_generated/configfeedintariff.md

@@ -7,6 +7,7 @@
 
 | Name | Environment Variable | Type | Read-Only | Default | Description |
 | ---- | -------------------- | ---- | --------- | ------- | ----------- |
+| energycharts | `EOS_FEEDINTARIFF__ENERGYCHARTS` | `FeedInTariffEnergyChartsCommonSettings` | `rw` | `required` | EnergyCharts feed in tariff provider settings. |
 | feedintarifffixed | `EOS_FEEDINTARIFF__FEEDINTARIFFFIXED` | `FeedInTariffFixedCommonSettings` | `rw` | `required` | Fixed feed in tariff provider settings. |
 | feedintariffimport | `EOS_FEEDINTARIFF__FEEDINTARIFFIMPORT` | `FeedInTariffImportCommonSettings` | `rw` | `required` | Feed in tarif import provider settings. |
 | provider | `EOS_FEEDINTARIFF__PROVIDER` | `Optional[str]` | `rw` | `None` | Feed in tariff provider id of provider to be used. |
@@ -29,6 +30,9 @@
            "feedintariffimport": {
                "import_file_path": null,
                "import_json": null
+           },
+           "energycharts": {
+               "bidding_zone": "DE-LU"
            }
        }
    }
@@ -51,7 +55,11 @@
                "import_file_path": null,
                "import_json": null
            },
+           "energycharts": {
+               "bidding_zone": "DE-LU"
+           },
            "providers": [
+               "FeedInTariffEnergyCharts",
                "FeedInTariffFixed",
                "FeedInTariffImport"
            ]
@@ -119,3 +127,32 @@
    }
 ```
 <!-- pyml enable line-length -->
+
+### Common settings for Energy-Charts feed-in tariff provider
+
+<!-- pyml disable line-length -->
+:::{table} feedintariff::energycharts
+:widths: 10 10 5 5 30
+:align: left
+
+| Name | Type | Read-Only | Default | Description |
+| ---- | ---- | --------- | ------- | ----------- |
+| bidding_zone | `<enum 'EnergyChartsBiddingZones'>` | `rw` | `DE-LU` | Bidding Zone: 'AT', 'BE', 'CH', 'CZ', 'DE-LU', 'DE-AT-LU', 'DK1', 'DK2', 'FR', 'HU', 'IT-NORTH', 'NL', 'NO2', 'PL', 'SE4' or 'SI' |
+:::
+<!-- 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": {
+           "energycharts": {
+               "bidding_zone": "DE-LU"
+           }
+       }
+   }
+```
+<!-- pyml enable line-length -->

docs/_generated/openapi.md

@@ -1,6 +1,6 @@
 # Akkudoktor-EOS
 
-**Version**: `v0.3.0.dev2607231185985809`
+**Version**: `v0.3.0.dev2607231331447302`
 
 <!-- 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

@@ -217,13 +217,49 @@ Configuration options:
 
   - `provider`: Feed in tariff provider id of provider to be used.
 
+    - `FeedInTariffEnergyCharts`: Retrieves Energy-Charts day-ahead market prices and extends
+      them to the configured prediction horizon when necessary.
     - `FeedInTariffFixed`: Provides fixed feed in tariff values.
     - `FeedInTariffImport`: Imports from a file or JSON string or by endpoint data provision.
 
+  - `energycharts.bidding_zone`: Bidding zone Energy Charts shall provide feed-in tariff for.
   - `feedintarifffixed.feed_in_tariff_kwh`: Fixed feed in tariff (€/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.
 
+### 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
+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
+not cover the complete configured prediction horizon, the provider extends it as follows:
+
+- With more than 800 hours of history, an ETS (Holt-Winters exponential smoothing) forecast with
+  weekly seasonality is used.
+- With more than 168 hours of history, an ETS forecast with daily seasonality is used.
+- With less history, the median of the available values is used as a constant fallback.
+
+The seasonal periods are adjusted to the source resolution. For example, quarter-hour data uses
+four values per hour. Values already supplied by Energy-Charts are kept unchanged; only missing
+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.
+
+Example configuration:
+
+```json
+{
+  "feedintariff": {
+    "provider": "FeedInTariffEnergyCharts",
+    "energycharts": {
+      "bidding_zone": "DE-LU"
+    }
+  }
+}
+```
+
 ### FeedInTariffImport Provider
 
 The `FeedInTariffImport` provider is designed to import feed in tariff prices from: