diff --git a/.env b/.env index b368282f..253c441c 100644 --- a/.env +++ b/.env @@ -11,7 +11,7 @@ DOCKER_COMPOSE_DATA_DIR=${HOME}/.local/share/net.akkudoktor.eos # ----------------------------------------------------------------------------- # Image / build # ----------------------------------------------------------------------------- -VERSION=0.3.0.dev2610301534325811 +VERSION=0.3.0.dev2611091577972738 PYTHON_VERSION=3.13.15 # ----------------------------------------------------------------------------- diff --git a/config.yaml b/config.yaml index 36d00987..5eae6b16 100644 --- a/config.yaml +++ b/config.yaml @@ -6,7 +6,7 @@ # the root directory (no add-on folder as usual). name: "Akkudoktor-EOS" -version: "0.3.0.dev2610301534325811" +version: "0.3.0.dev2611091577972738" slug: "eos" description: "Akkudoktor-EOS add-on" url: "https://github.com/Akkudoktor-EOS/EOS" diff --git a/docs/_generated/configexample.md b/docs/_generated/configexample.md index 10fe555f..d74c44aa 100644 --- a/docs/_generated/configexample.md +++ b/docs/_generated/configexample.md @@ -372,6 +372,15 @@ "calibration_prior_kwh": 5.0, "calibration_min_factor": 0.5, "calibration_max_factor": 1.5, + "snow_enabled": false, + "snow_lookback_days": 7, + "snow_threshold_snowfall_cm_per_hour": 0.5, + "snow_threshold_depth_cm": 1.0, + "snow_feedback_enabled": true, + "snow_feedback_gain": 0.8, + "snow_feedback_min_fraction": 0.05, + "snow_feedback_memory_hours": 12.0, + "snow_detection_ratio": 0.5, "regional_weather_model": "icon_d2", "regional_horizon_hours": 6, "learning_days": 21, diff --git a/docs/_generated/configpvforecast.md b/docs/_generated/configpvforecast.md index 88df38a8..75864bbe 100644 --- a/docs/_generated/configpvforecast.md +++ b/docs/_generated/configpvforecast.md @@ -96,6 +96,15 @@ "calibration_prior_kwh": 5.0, "calibration_min_factor": 0.5, "calibration_max_factor": 1.5, + "snow_enabled": false, + "snow_lookback_days": 7, + "snow_threshold_snowfall_cm_per_hour": 0.5, + "snow_threshold_depth_cm": 1.0, + "snow_feedback_enabled": true, + "snow_feedback_gain": 0.8, + "snow_feedback_min_fraction": 0.05, + "snow_feedback_memory_hours": 12.0, + "snow_detection_ratio": 0.5, "regional_weather_model": "icon_d2", "regional_horizon_hours": 6, "learning_days": 21, @@ -291,6 +300,15 @@ "calibration_prior_kwh": 5.0, "calibration_min_factor": 0.5, "calibration_max_factor": 1.5, + "snow_enabled": false, + "snow_lookback_days": 7, + "snow_threshold_snowfall_cm_per_hour": 0.5, + "snow_threshold_depth_cm": 1.0, + "snow_feedback_enabled": true, + "snow_feedback_gain": 0.8, + "snow_feedback_min_fraction": 0.05, + "snow_feedback_memory_hours": 12.0, + "snow_detection_ratio": 0.5, "regional_weather_model": "icon_d2", "regional_horizon_hours": 6, "learning_days": 21, @@ -893,6 +911,15 @@ | regional_weather_model | `Optional[str]` | `rw` | `icon_d2` | None | | resolution_minutes | `int` | `rw` | `15` | Forecast resolution in minutes. 15 requests Open-Meteo's `minutely_15` block (natively resolved over Central Europe and North America, interpolated from hourly elsewhere); 60 requests the `hourly` block. | | shift_to_interval_start | `bool` | `rw` | `True` | Open-Meteo stamps an interval mean with the interval END. EOS labels an interval by its START, so records are shifted back by one interval. Disable only to compare like-for-like against a provider that does not. | +| snow_detection_ratio | `float` | `rw` | `0.5` | Measured/clear-model production ratio below which an interval counts as evidence of snow the weather model missed. | +| snow_enabled | `bool` | `rw` | `False` | Model snow lying on the modules. Requests snowfall and snow depth from Open-Meteo and runs the NREL snow coverage model (pvlib.snow) per plane, which covers the modules on heavy snowfall and lets the snow slide off with warmth and sunshine. Without this, the forecast after a snowfall assumes clean modules. | +| snow_feedback_enabled | `bool` | `rw` | `True` | Correct the modelled snow coverage with measured PV production from `measurement.pv_production_emr_keys`. Production well above the snow model clears the coverage at once; production far below the clear-module model raises it, but only while snow is plausible (snow on the ground or already modelled on the modules). Needs cumulative meter readings. | +| snow_feedback_gain | `float` | `rw` | `0.8` | How far one measured interval pulls the coverage towards the observed value (1.0 = adopt the observation). | +| snow_feedback_memory_hours | `float` | `rw` | `12.0` | When measured production shows more snow than modelled, the snow is assumed to slide off slower than the NREL model says. This damping fades back to the model's rate with this time constant after the last measurement. | +| snow_feedback_min_fraction | `float` | `rw` | `0.05` | A measured interval is only used when the clear-module model expects at least this fraction of the installed AC capacity. Dawn, dusk and dark overcast carry no usable evidence about snow. | +| snow_lookback_days | `int` | `rw` | `7` | Days of past weather (and PV measurements) replayed on every update to rebuild the current snow coverage. No state is stored between runs, so this must reach back before the last relevant snowfall. | +| snow_threshold_depth_cm | `float` | `rw` | `1.0` | Ground snow depth below which the modules are assumed clear (pvlib `threshold_depth`). | +| snow_threshold_snowfall_cm_per_hour | `float` | `rw` | `0.5` | Snowfall rate that fully covers the modules (pvlib `threshold_snowfall`). pvlib's default of 1.0 cm/h was tuned on US station data; Open-Meteo's hourly model snowfall is smoother, so a lower rate fits better. | | solar_response_enabled | `bool` | `rw` | `True` | Learn empirical angular response relative to separate, eligible reference arrays; activate only after issued-candidate validation. | | temperature_coefficient | `float` | `rw` | `-0.36` | Module power temperature coefficient in %/degC (negative). Matches the `cellCoEff` the akkudoktor.net forecast uses. | | total_curtailment_key | `Optional[str]` | `rw` | `None` | None | @@ -943,6 +970,15 @@ "calibration_prior_kwh": 5.0, "calibration_min_factor": 0.5, "calibration_max_factor": 1.5, + "snow_enabled": false, + "snow_lookback_days": 7, + "snow_threshold_snowfall_cm_per_hour": 0.5, + "snow_threshold_depth_cm": 1.0, + "snow_feedback_enabled": true, + "snow_feedback_gain": 0.8, + "snow_feedback_min_fraction": 0.05, + "snow_feedback_memory_hours": 12.0, + "snow_detection_ratio": 0.5, "regional_weather_model": "icon_d2", "regional_horizon_hours": 6.0, "learning_days": 21, diff --git a/docs/_generated/openapi.md b/docs/_generated/openapi.md index 24986ea6..5ddd2a5e 100644 --- a/docs/_generated/openapi.md +++ b/docs/_generated/openapi.md @@ -1,6 +1,6 @@ # Akkudoktor-EOS -**Version**: `v0.3.0.dev2611011668106370` +**Version**: `v0.3.0.dev2611091577972738` **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. diff --git a/openapi.json b/openapi.json index b1e8e97f..ba05462f 100644 --- a/openapi.json +++ b/openapi.json @@ -8,7 +8,7 @@ "name": "Apache 2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0.html" }, - "version": "v0.3.0.dev2611011668106370" + "version": "v0.3.0.dev2611091577972738" }, "paths": { "/v1/measurement/battery-capacity/{battery_id}": { @@ -14722,6 +14722,105 @@ 1.5 ] }, + "snow_enabled": { + "type": "boolean", + "title": "Snow Enabled", + "description": "Model snow lying on the modules. Requests snowfall and snow depth from Open-Meteo and runs the NREL snow coverage model (pvlib.snow) per plane, which covers the modules on heavy snowfall and lets the snow slide off with warmth and sunshine. Without this, the forecast after a snowfall assumes clean modules.", + "default": false, + "examples": [ + false, + true + ] + }, + "snow_lookback_days": { + "type": "integer", + "maximum": 92.0, + "minimum": 1.0, + "title": "Snow Lookback Days", + "description": "Days of past weather (and PV measurements) replayed on every update to rebuild the current snow coverage. No state is stored between runs, so this must reach back before the last relevant snowfall.", + "default": 7, + "examples": [ + 7, + 14 + ] + }, + "snow_threshold_snowfall_cm_per_hour": { + "type": "number", + "exclusiveMinimum": 0.0, + "title": "Snow Threshold Snowfall Cm Per Hour", + "description": "Snowfall rate that fully covers the modules (pvlib `threshold_snowfall`). pvlib's default of 1.0 cm/h was tuned on US station data; Open-Meteo's hourly model snowfall is smoother, so a lower rate fits better.", + "default": 0.5, + "examples": [ + 0.5, + 1.0 + ] + }, + "snow_threshold_depth_cm": { + "type": "number", + "minimum": 0.0, + "title": "Snow Threshold Depth Cm", + "description": "Ground snow depth below which the modules are assumed clear (pvlib `threshold_depth`).", + "default": 1.0, + "examples": [ + 1.0 + ] + }, + "snow_feedback_enabled": { + "type": "boolean", + "title": "Snow Feedback Enabled", + "description": "Correct the modelled snow coverage with measured PV production from `measurement.pv_production_emr_keys`. Production well above the snow model clears the coverage at once; production far below the clear-module model raises it, but only while snow is plausible (snow on the ground or already modelled on the modules). Needs cumulative meter readings.", + "default": true, + "examples": [ + true + ] + }, + "snow_feedback_gain": { + "type": "number", + "maximum": 1.0, + "exclusiveMinimum": 0.0, + "title": "Snow Feedback Gain", + "description": "How far one measured interval pulls the coverage towards the observed value (1.0 = adopt the observation).", + "default": 0.8, + "examples": [ + 0.8, + 1.0 + ] + }, + "snow_feedback_min_fraction": { + "type": "number", + "exclusiveMaximum": 1.0, + "exclusiveMinimum": 0.0, + "title": "Snow Feedback Min Fraction", + "description": "A measured interval is only used when the clear-module model expects at least this fraction of the installed AC capacity. Dawn, dusk and dark overcast carry no usable evidence about snow.", + "default": 0.05, + "examples": [ + 0.05, + 0.1 + ] + }, + "snow_feedback_memory_hours": { + "type": "number", + "exclusiveMinimum": 0.0, + "title": "Snow Feedback Memory Hours", + "description": "When measured production shows more snow than modelled, the snow is assumed to slide off slower than the NREL model says. This damping fades back to the model's rate with this time constant after the last measurement.", + "default": 12.0, + "examples": [ + 12.0, + 24.0 + ] + }, + "snow_detection_ratio": { + "type": "number", + "exclusiveMaximum": 1.0, + "exclusiveMinimum": 0.0, + "title": "Snow Detection Ratio", + "description": "Measured/clear-model production ratio below which an interval counts as evidence of snow the weather model missed.", + "default": 0.5, + "examples": [ + 0.5, + 0.3 + ] + }, "regional_weather_model": { "anyOf": [ {