Add graduated Amber headroom target to reduce solar clipping on Amber days (#23)

Amber forecast days previously received no pre-period headroom export, leaving
the battery full when morning solar arrives. Now a configurable AMBER_HEADROOM_FRACTION
(default 0.25) drives a 6 kWh headroom target for Amber periods, sitting between
Red (none) and Green (50% / 12 kWh). All headroom checks in the decision engine,
period handlers, and mid-period safety exports are status-aware.

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: deadl0ck

README.md

@@ -104,6 +104,7 @@ see exactly what values were used and why each decision was made.
    | `CHEAP_RATE_END_HOUR` | `8` | Hour your cheap-rate electricity ends (local time) |
    | `ESTIMATED_HOME_LOAD_KW` | `0.8` | Your average household draw in kW when solar is low |
    | `HEADROOM_TARGET_KWH` | `BATTERY_KWH * 0.5` | Free battery space to maintain before a Green forecast. The alternative physics formula is `(SOLAR_PV_KW - INVERTER_KW) * 3`; use whichever fits your clipping risk tolerance |
+   | `AMBER_HEADROOM_FRACTION` | `0.25` | Fraction of battery capacity to keep free before an Amber forecast (e.g. `0.25` = 25%). Set to `0.0` to disable Amber headroom entirely |
 
    All solar trigger thresholds (`MID_PERIOD_SAFETY_SOLAR_TRIGGER_KW`, `LIVE_CLIPPING_RISK_SOLAR_TRIGGER_KW`) and discharge rate estimates (`PRE_CHEAP_RATE_NIGHT_EXPORT_ASSUMED_DISCHARGE_KW`, `EVENING_EXPORT_ASSUMED_DISCHARGE_KW`) are automatically derived from your hardware specs — you do not need to touch them.
 
@@ -286,6 +287,7 @@ These settings are **not** derived from hardware and need manual review:
 | `CHEAP_RATE_START_HOUR` / `CHEAP_RATE_END_HOUR` | Varies by energy provider and tariff plan |
 | `ESTIMATED_HOME_LOAD_KW` | Household draw varies; affects the evening battery-bridge rule |
 | `HEADROOM_TARGET_KWH` | Currently `BATTERY_KWH * 0.5`. The physics alternative is `(SOLAR_PV_KW - INVERTER_KW) * 3` (surplus kW × 3 h reserve). For systems with a large battery relative to array surplus, the physics formula is more appropriate |
+| `AMBER_HEADROOM_FRACTION` | Fraction of battery capacity to maintain as free headroom before an Amber period. Default `0.25` (25% of battery). Set to `0.0` to disable Amber pre-period exports entirely |
 | `PRE_SUNRISE_DISCHARGE_MONTHS` | Months where pre-sunrise discharge is useful — adjust for your latitude and climate |
 
 ### Scheduler and decision thresholds
@@ -305,6 +307,7 @@ FORECAST_SOLAR_POWER_MULTIPLIER = 1.53
 CHEAP_RATE_START_HOUR = 23
 CHEAP_RATE_END_HOUR = 8
 HEADROOM_TARGET_KWH = 10.2
+AMBER_HEADROOM_FRACTION = 0.25
 ENABLE_PRE_CHEAP_RATE_BATTERY_BRIDGE = True
 ESTIMATED_HOME_LOAD_KW = 0.8
 BRIDGE_BATTERY_RESERVE_KWH = 1.0
@@ -337,7 +340,8 @@ Meaning:
 - `QUARTZ_RED_CAPACITY_FRACTION`: lower Quartz status threshold as a fraction of configured array capacity
 - `QUARTZ_GREEN_CAPACITY_FRACTION`: upper Quartz status threshold as a fraction of configured array capacity
 - `FORECAST_SOLAR_POWER_MULTIPLIER`: scalar applied to Forecast.Solar watts before period status/value normalization; use this to correct persistent local bias (for example, historical under-forecasting)
-- `HEADROOM_TARGET_KWH`: fixed battery headroom target (10.2 kWh = surplus capacity × 3 hours)
+- `HEADROOM_TARGET_KWH`: fixed battery headroom target for Green periods (10.2 kWh = surplus capacity × 3 hours)
+- `AMBER_HEADROOM_FRACTION`: fraction of battery capacity to maintain as free headroom before Amber periods (default `0.25`); `AMBER_HEADROOM_TARGET_KWH` is derived as `BATTERY_KWH * AMBER_HEADROOM_FRACTION`. Set to `0.0` to disable Amber headroom
 - `ENABLE_PRE_CHEAP_RATE_BATTERY_BRIDGE`: when enabled, Evening decisions avoid charge-oriented behavior before cheap-rate starts if battery can bridge the expected load
 - `ESTIMATED_HOME_LOAD_KW`: average household load estimate used to calculate whether current battery energy can cover consumption until cheap-rate begins
 - `BRIDGE_BATTERY_RESERVE_KWH`: safety buffer to keep in battery when evaluating bridge sufficiency
@@ -650,19 +654,27 @@ $$
 
 The system exports to grid under these conditions.
 
-#### Rule 1: Insufficient headroom before a Green period
+#### Rule 1: Insufficient headroom before a Green or Amber period
 
-The target free headroom is derived from hardware surplus capacity multiplied by a 3-hour reserve window:
+The headroom target varies by forecast status:
+
+| Forecast | Target | Setting |
+|---|---|---|
+| Green | `BATTERY_KWH × 0.5` (e.g. 12 kWh) | `HEADROOM_TARGET_KWH` |
+| Amber | `BATTERY_KWH × 0.25` (e.g. 6 kWh) | `AMBER_HEADROOM_TARGET_KWH` (derived from `AMBER_HEADROOM_FRACTION`) |
+| Red | — (no headroom export) | — |
+
+The Green target is derived from hardware surplus capacity multiplied by a 3-hour reserve window:
 
 $$
-	ext{headroom target} = (\text{solar PV kW} - \text{inverter kW}) \times 3.0 = (8.9 - 5.5) \times 3.0 = 10.2 \text{ kWh}
+\text{headroom target (Green)} = (\text{solar PV kW} - \text{inverter kW}) \times 3.0 = (8.9 - 5.5) \times 3.0 = 10.2 \text{ kWh}
 $$
 
-This fixed target ensures the battery can absorb 3 hours of maximum surplus generation (3.4 kW) without clipping, independent of forecast quality or period.
+The Amber target is a reduced fraction of the battery, reflecting that Amber days carry real but moderate solar risk — enough to warrant partial headroom, but not the full Green reserve. Setting `AMBER_HEADROOM_FRACTION = 0.0` disables Amber headroom entirely.
 
 If:
 $$
-	ext{headroom} < \text{headroom target}
+\text{headroom} < \text{headroom target}
 $$
 
 then the system selects `GRID_EXPORT` to create battery space ahead of the solar period.

config/settings.py

@@ -193,6 +193,11 @@
 HEADROOM_TARGET_KWH = BATTERY_KWH * 0.5  # e.g. 24 × 0.5 = 12.0 kWh
 # Alternative physics-based formula: (SOLAR_PV_KW - INVERTER_KW) * 3 = surplus kW × 3 h reserve.
 # For this system that gives 10.2 kWh. BATTERY_KWH * 0.5 adds extra margin; adjust to taste.
+# Target free battery headroom before an Amber period: 25% of total battery capacity.
+# Amber days carry moderate solar risk — less than Green but enough to warrant partial headroom.
+# Set to 0.0 to disable Amber headroom entirely (reverts to pre-2026-05 behaviour).
+AMBER_HEADROOM_FRACTION = 0.25
+AMBER_HEADROOM_TARGET_KWH = BATTERY_KWH * AMBER_HEADROOM_FRACTION  # e.g. 24 × 0.25 = 6.0 kWh
 # Enable bridge-to-cheap-rate rule: before cheap-rate starts, prefer self-powered
 # if current battery energy is sufficient to cover expected household demand.
 ENABLE_PRE_CHEAP_RATE_BATTERY_BRIDGE = True
@@ -208,10 +213,9 @@
 PRE_CHEAP_RATE_NIGHT_EXPORT_MIN_SOC_PERCENT = 15.0
 # Conservative assumed net battery discharge power used to size the export window.
 PRE_CHEAP_RATE_NIGHT_EXPORT_ASSUMED_DISCHARGE_KW = round(INVERTER_KW * 0.36, 2)  # ~36% of inverter capacity
-# High-SOC protection: force GRID_EXPORT for Green periods when battery is very
-# full and headroom is below target, preventing wasted solar due to a full battery.
-# Amber is excluded: moderate solar is unlikely to cause significant clipping, and
-# exporting stored energy overnight on an Amber day wastes more than it saves.
+# High-SOC protection: force GRID_EXPORT for Green or Amber periods when battery is very
+# full and headroom is below the status-appropriate target, preventing wasted solar.
+# Green uses HEADROOM_TARGET_KWH (50%); Amber uses AMBER_HEADROOM_TARGET_KWH (25%).
 MORNING_HIGH_SOC_PROTECTION_ENABLED = True
 # SOC threshold for the mid-period high-SOC safety export check (combined with solar).
 # When SOC >= this AND solar >= MID_PERIOD_SAFETY_SOLAR_TRIGGER_KW, export is triggered.

logic/afternoon.py

@@ -12,6 +12,7 @@
 from datetime import timedelta
 
 from config.settings import (
+    AMBER_HEADROOM_TARGET_KWH,
     BATTERY_KWH,
     DAYTIME_TIMED_EXPORT_MIN_SOC_PERCENT,
     HEADROOM_TARGET_KWH,
@@ -137,7 +138,9 @@ async def handle_afternoon_period(ctx: PeriodHandlerContext) -> bool:
             and mid_period_solar_kw >= MID_PERIOD_SAFETY_SOLAR_TRIGGER_KW
         ):
             mid_period_headroom_kwh = calc_headroom_kwh(BATTERY_KWH, mid_period_soc)
-            mid_period_headroom_target_kwh = HEADROOM_TARGET_KWH
+            mid_period_headroom_target_kwh = (
+                AMBER_HEADROOM_TARGET_KWH if status.upper() == "AMBER" else HEADROOM_TARGET_KWH
+            )
             mid_period_headroom_deficit = max(0.0, mid_period_headroom_target_kwh - mid_period_headroom_kwh)
             if mid_period_headroom_deficit > 0:
                 mid_period_effective_battery_export_kw = get_effective_battery_export_kw(

logic/decision_logic.py

@@ -16,6 +16,7 @@
 
 from config.enums import ForecastStatus, Period
 from config.settings import (
+    AMBER_HEADROOM_TARGET_KWH,
     BATTERY_KWH,
     ENABLE_PRE_CHEAP_RATE_BATTERY_BRIDGE,
     FORECAST_TO_MODE,
@@ -128,7 +129,7 @@ def decide_operational_mode(ctx: DecisionContext) -> tuple[int, str]:
 
     if (
         ctx.soc is not None
-        and status_key == ForecastStatus.GREEN
+        and status_key in (ForecastStatus.GREEN, ForecastStatus.AMBER)
         and ctx.headroom_kwh is not None
         and ctx.headroom_kwh < ctx.headroom_target_kwh
     ):
@@ -141,18 +142,13 @@ def decide_operational_mode(ctx: DecisionContext) -> tuple[int, str]:
 
     if (
         MORNING_HIGH_SOC_PROTECTION_ENABLED
-        and status_key == ForecastStatus.GREEN
+        and status_key in (ForecastStatus.GREEN, ForecastStatus.AMBER)
         and ctx.soc is not None
         and ctx.soc >= MORNING_HIGH_SOC_THRESHOLD_PERCENT
         and ctx.headroom_kwh is not None
         and ctx.headroom_kwh < ctx.headroom_target_kwh
     ):
         mode = SIGEN_MODES["GRID_EXPORT"]
-        period_label = {
-            Period.MORN: "Morning",
-            Period.AFTN: "Afternoon",
-            Period.EVE: "Evening",
-        }.get(period_key, ctx.period)
         reason = (
             f"Battery is high ({ctx.soc:.1f}%) with only {ctx.headroom_kwh:.2f} kWh headroom "
             f"(needs {ctx.headroom_target_kwh:.2f} kWh) — exporting to make room for incoming solar."

logic/morning.py

@@ -12,6 +12,7 @@
 from datetime import timedelta
 
 from config.settings import (
+    AMBER_HEADROOM_TARGET_KWH,
     BATTERY_KWH,
     DAYTIME_TIMED_EXPORT_MIN_SOC_PERCENT,
     HEADROOM_TARGET_KWH,
@@ -137,7 +138,9 @@ async def handle_morning_period(ctx: PeriodHandlerContext) -> bool:
             and mid_period_solar_kw >= MID_PERIOD_SAFETY_SOLAR_TRIGGER_KW
         ):
             mid_period_headroom_kwh = calc_headroom_kwh(BATTERY_KWH, mid_period_soc)
-            mid_period_headroom_target_kwh = HEADROOM_TARGET_KWH
+            mid_period_headroom_target_kwh = (
+                AMBER_HEADROOM_TARGET_KWH if status.upper() == "AMBER" else HEADROOM_TARGET_KWH
+            )
             mid_period_headroom_deficit = max(0.0, mid_period_headroom_target_kwh - mid_period_headroom_kwh)
             if mid_period_headroom_deficit > 0:
                 mid_period_effective_battery_export_kw = get_effective_battery_export_kw(

logic/period_handler_shared.py

@@ -19,6 +19,7 @@
 from typing import Any
 
 from config.settings import (
+    AMBER_HEADROOM_TARGET_KWH,
     BATTERY_KWH,
     BRIDGE_BATTERY_RESERVE_KWH,
     ESTIMATED_HOME_LOAD_KW,
@@ -152,15 +153,19 @@ def _evaluate_period_mode_decision(
         period, status, soc, solar_avg_kw_3
     )
     headroom_kwh = calc_headroom_kwh(BATTERY_KWH, soc)
-    headroom_target_kwh = HEADROOM_TARGET_KWH
+    headroom_target_kwh = (
+        AMBER_HEADROOM_TARGET_KWH
+        if decision_status.upper() == "AMBER"
+        else HEADROOM_TARGET_KWH
+    )
     headroom_deficit_kwh = max(0.0, headroom_target_kwh - headroom_kwh)
     mode, reason = decide_operational_mode(
         DecisionContext(
             period=period,
             status=decision_status,
             soc=soc,
             headroom_kwh=headroom_kwh,
-            headroom_target_kwh=HEADROOM_TARGET_KWH,
+            headroom_target_kwh=headroom_target_kwh,
             live_solar_kw=solar_avg_kw_3,
             hours_until_cheap_rate=get_hours_until_cheap_rate(now_utc),
             estimated_home_load_kw=ESTIMATED_HOME_LOAD_KW,

tests/test_decision_logic.py

@@ -22,13 +22,15 @@ def test_cheap_rate_window_is_false_during_evening_shoulder_hours():
 
 
 def test_peak_tariff_overrides_default_forecast_mode_to_self_powered():
+    # headroom_target_kwh=6.0 reflects the Amber target; headroom=8.0 is sufficient
+    # so the headroom export rule does not fire and peak tariff override takes effect.
     mode, reason = decide_operational_mode(
         DecisionContext(
             period="Aftn",
             status="Amber",
             soc=45,
             headroom_kwh=8.0,
-            headroom_target_kwh=10.2,
+            headroom_target_kwh=6.0,
             live_solar_kw=None,
             hours_until_cheap_rate=None,
             estimated_home_load_kw=None,
@@ -101,16 +103,16 @@ def test_evening_red_falls_back_to_ai_when_bridge_energy_is_insufficient():
     assert "Forecast is Red" in reason
 
 
-def test_morning_high_soc_protection_does_not_export_for_amber_when_headroom_is_low():
-    # Amber forecast: high SOC should not trigger protective export — moderate solar
-    # is unlikely to cause significant clipping, and exporting stored energy wastes more.
+def test_amber_exports_when_headroom_below_amber_target():
+    # Amber forecast with high SOC: headroom (0.6 kWh) is below the Amber target
+    # (6.0 kWh), so protective export should trigger to make room for solar.
     mode, reason = decide_operational_mode(
         DecisionContext(
             period="Morn",
             status="Amber",
             soc=97.0,
             headroom_kwh=0.6,
-            headroom_target_kwh=10.2,
+            headroom_target_kwh=6.0,
             live_solar_kw=None,
             hours_until_cheap_rate=None,
             estimated_home_load_kw=None,
@@ -119,18 +121,20 @@ def test_morning_high_soc_protection_does_not_export_for_amber_when_headroom_is_
         )
     )
 
-    assert mode == SIGEN_MODES["SELF_POWERED"]
-    assert "Forecast is Amber" in reason
+    assert mode == SIGEN_MODES["GRID_EXPORT"]
+    assert "headroom" in reason.lower()
 
 
-def test_morning_high_soc_protection_does_not_trigger_below_threshold():
+def test_amber_does_not_export_when_headroom_meets_amber_target():
+    # Amber forecast: headroom (8.0 kWh) already exceeds the Amber target (6.0 kWh),
+    # so no export is needed regardless of SOC.
     mode, reason = decide_operational_mode(
         DecisionContext(
             period="Morn",
             status="Amber",
-            soc=45.0,
-            headroom_kwh=0.6,
-            headroom_target_kwh=10.2,
+            soc=75.0,
+            headroom_kwh=8.0,
+            headroom_target_kwh=6.0,
             live_solar_kw=None,
             hours_until_cheap_rate=None,
             estimated_home_load_kw=None,