Fix DHW transition volatility and add generic offset volatility tracker

DHW Transition Fix:
- Unify DHW active tracking: is_hot_water OR temp_lux (was separate)
- Trigger weather layer cooldown when DHW stops (30 min)
- Prevents offset flip when flow temp still elevated after DHW

Generic Offset Volatility Tracker:
- Add OffsetVolatilityTracker class in volatile_helpers.py
- Blocks large offset reversals (>2°C) within 45 min window
- Applied at coordinator level for ALL layer decisions
- Prevents rapid back-and-forth that heat pump can't follow

Consolidate Volatile Duration Constants (DRY):
- VOLATILE_MIN_DURATION_MINUTES = 45 (single source of truth)
- VOLATILE_MIN_DURATION_QUARTERS = 3 (derived for price logic)
- MINUTES_PER_QUARTER = 15 (replaces hardcoded * 15)
- Remove PRICE_FORECAST_MIN_DURATION (redundant)
- Rename COMPRESSOR_MIN_CYCLE_MINUTES → VOLATILE_MIN_DURATION_MINUTES

Tests: 1093 passed (17 new for OffsetVolatilityTracker)

Author: enoch85

custom_components/effektguard/const.py

@@ -627,9 +627,18 @@ class OptimizationModeConfig:
 # Based on typical NIBE F-series compressor behavior
 COMPRESSOR_RAMP_UP_MINUTES: Final = 30  # Minutes to reach full speed from idle
 COMPRESSOR_COOL_DOWN_MINUTES: Final = 15  # Minutes for thermal stabilization after reduction
-COMPRESSOR_MIN_CYCLE_MINUTES: Final = (
+
+# Minimum duration for volatility detection (Jan 4, 2026)
+# Used by both price volatility (short price runs) and offset volatility (rapid reversals)
+# Based on compressor dynamics: 30 min ramp-up + 15 min cool-down = 45 min
+# Single source of truth - use MINUTES for offset tracking, QUARTERS for price logic
+MINUTES_PER_QUARTER: Final = 15  # 15-minute price quarters
+VOLATILE_MIN_DURATION_MINUTES: Final = (
     COMPRESSOR_RAMP_UP_MINUTES + COMPRESSOR_COOL_DOWN_MINUTES
 )  # 45min total
+VOLATILE_MIN_DURATION_QUARTERS: Final = (
+    VOLATILE_MIN_DURATION_MINUTES // MINUTES_PER_QUARTER
+)  # 3 quarters (45min / 15min)
 
 # Price forecast lookahead (Nov 27, 2025)
 # Forward-looking price optimization: reduce heating when cheaper period coming soon
@@ -646,9 +655,6 @@ class OptimizationModeConfig:
 PRICE_FORECAST_EXPENSIVE_THRESHOLD: Final = (
     1.5  # Price ratio - upcoming > 150% of current = "much more expensive"
 )
-PRICE_FORECAST_MIN_DURATION: Final = (
-    COMPRESSOR_MIN_CYCLE_MINUTES // 15
-)  # quarters - derived from compressor dynamics (45min / 15min = 3)
 PRICE_FORECAST_REDUCTION_OFFSET: Final = (
     -1.5
 )  # °C - reduce heating when cheap period coming (Dec 5, 2025: strengthened from -1.0)

custom_components/effektguard/coordinator.py

@@ -35,6 +35,7 @@
     DHW_MIN_AMOUNT_DEFAULT,
     DHW_READY_THRESHOLD,
     DHW_SAFETY_MIN,
+    DHW_WEATHER_COOLDOWN_MINUTES,
     DM_THRESHOLD_START,
     DOMAIN,
     MIN_DHW_TARGET_TEMP,
@@ -62,6 +63,7 @@
 from .optimization.weather_learning import WeatherPatternLearner
 from .utils.compressor_monitor import CompressorHealthMonitor
 from .utils.time_utils import get_current_quarter
+from .utils.volatile_helpers import OffsetVolatilityTracker
 
 _LOGGER = logging.getLogger(__name__)
 
@@ -267,18 +269,22 @@ def __init__(
             minutes=UPDATE_INTERVAL_MINUTES
         )  # Throttle to coordinator update interval
 
+        # Offset volatility tracking (prevents rapid back-and-forth offset changes)
+        # Uses same min duration as price volatility (45 min) for consistency
+        self._offset_volatility_tracker = OffsetVolatilityTracker()
+
         # Peak tracking metadata (for sensor attributes)
         self.peak_today_time: datetime | None = None  # When today's peak occurred
         self.peak_today_source: str = "unknown"  # external_meter, nibe_currents, estimate
         self.peak_today_quarter: int | None = None  # 15-min quarter (0-95) for effect tariff
         self.yesterday_peak: float = 0.0  # Yesterday's peak for comparison
 
-        # DHW tracking
+        # DHW tracking (unified: is_hot_water OR temp_lux active)
         self.last_dhw_heated = None  # Last time DHW was in heating mode
         self.last_dhw_temp = None  # Last BT7 temperature for trend analysis
         self.dhw_heating_start = None  # When current/last DHW cycle started
         self.dhw_heating_end = None  # When last DHW cycle ended
-        self.dhw_was_heating = False  # Track state changes
+        self.dhw_was_active = False  # Track DHW state (is_hot_water OR temp_lux)
 
         # Spot price savings tracking (per-cycle accumulation)
         self._daily_spot_savings: float = 0.0  # Accumulates during day, recorded at midnight
@@ -819,21 +825,45 @@ async def _async_update_data(self) -> dict[str, Any]:
                 else:
                     current_power_for_decision = self.peak_today
 
-                # Check if DHW temporary lux is active
+                # Check if DHW is active (EITHER is_hot_water sensor OR temp_lux switch)
                 # When NIBE heats DHW, flow temp reads charging temp (45-60°C), not space heating
+                is_hot_water = (
+                    nibe_data.is_hot_water if hasattr(nibe_data, "is_hot_water") else False
+                )
                 temp_lux_active = False
                 if self.temp_lux_entity:
                     lux_state = self.hass.states.get(self.temp_lux_entity)
                     temp_lux_active = lux_state is not None and lux_state.state == STATE_ON
 
+                # Unified DHW active state: either source means DHW is heating
+                dhw_is_active = is_hot_water or temp_lux_active
+
+                # Track DHW transition: active → inactive triggers weather layer cooldown
+                # When DHW stops, flow temp remains elevated - needs cooldown period
+                # Uses DHW_WEATHER_COOLDOWN_MINUTES (30 min) before weather comp re-enables
+                if self.dhw_was_active and not dhw_is_active:
+                    self.dhw_heating_end = dt_util.now()
+                    _LOGGER.info(
+                        "DHW heating stopped - triggering weather layer cooldown (%d min)",
+                        DHW_WEATHER_COOLDOWN_MINUTES,
+                    )
+                elif not self.dhw_was_active and dhw_is_active:
+                    self.dhw_heating_start = dt_util.now()
+                    _LOGGER.info(
+                        "DHW heating started (is_hot_water=%s, temp_lux=%s)",
+                        is_hot_water,
+                        temp_lux_active,
+                    )
+                self.dhw_was_active = dhw_is_active
+
                 decision = await self.hass.async_add_executor_job(
                     self.engine.calculate_decision,
                     nibe_data,
                     price_data,
                     weather_data,
                     self.peak_this_month,  # Monthly peak threshold to protect
                     current_power_for_decision,  # Current whole-house power consumption
-                    temp_lux_active,  # DHW heating active - skip weather comp
+                    dhw_is_active,  # DHW heating active - skip weather comp
                     self.dhw_heating_end,  # When DHW last stopped - for cooldown
                 )
 
@@ -878,6 +908,24 @@ async def _async_update_data(self) -> dict[str, Any]:
                 # Fall back to safe operation (no offset)
                 decision = get_safe_default_decision()
 
+        # Check for volatile offset reversal before applying
+        # Prevents rapid back-and-forth that the heat pump can't follow (same logic as price volatility)
+        if self._offset_volatility_tracker.is_reversal_volatile(decision.offset):
+            volatile_reason = self._offset_volatility_tracker.get_volatile_reason(decision.offset)
+            _LOGGER.info(
+                "Offset change blocked: %s (keeping %.1f°C)",
+                volatile_reason,
+                self._offset_volatility_tracker.last_offset,
+            )
+            # Keep the previous offset
+            decision = OptimizationDecision(
+                offset=self._offset_volatility_tracker.last_offset,
+                reasoning=f"[{volatile_reason}] {decision.reasoning}",
+            )
+        else:
+            # Record the new offset for volatility tracking
+            self._offset_volatility_tracker.record_change(decision.offset, decision.reasoning)
+
         # Update current state
         self.current_offset = decision.offset
         self.last_decision_time = dt_util.utcnow()
@@ -1046,29 +1094,9 @@ async def _async_update_data(self) -> dict[str, Any]:
         if nibe_data and hasattr(nibe_data, "dhw_top_temp") and nibe_data.dhw_top_temp is not None:
             current_dhw_temp = nibe_data.dhw_top_temp
 
-            # Check if DHW is actively heating (from NIBE MyUplink sensor)
-            # This is more accurate than temperature thresholds alone
-            is_actively_heating = (
-                nibe_data.is_hot_water if hasattr(nibe_data, "is_hot_water") else False
-            )
-
-            # Track DHW heating cycle transitions (start/stop)
-            if is_actively_heating and not self.dhw_was_heating:
-                # DHW heating just started
-                self.dhw_heating_start = now_time
-                _LOGGER.info("DHW heating started at %s", now_time.strftime("%H:%M:%S"))
-            elif not is_actively_heating and self.dhw_was_heating:
-                # DHW heating just stopped
-                self.dhw_heating_end = now_time
-                if self.dhw_heating_start:
-                    duration = (now_time - self.dhw_heating_start).total_seconds() / 60
-                    _LOGGER.info(
-                        "DHW heating stopped at %s (duration: %.1f minutes)",
-                        now_time.strftime("%H:%M:%S"),
-                        duration,
-                    )
-
-            self.dhw_was_heating = is_actively_heating
+            # Use unified DHW active state (tracked earlier in update cycle)
+            # dhw_was_active combines is_hot_water sensor + temp_lux switch
+            is_actively_heating = self.dhw_was_active
 
             # Determine status using actual heating status + temperature
             if is_actively_heating:

custom_components/effektguard/optimization/price_layer.py

@@ -15,14 +15,14 @@
 
 from ..const import (
     BENEFICIAL_CLASSIFICATIONS,
-    OptimizationModeConfig,
     LAYER_WEIGHT_PRICE,
+    MINUTES_PER_QUARTER,
+    OptimizationModeConfig,
     PRICE_DAYTIME_MULTIPLIER,
     PRICE_FORECAST_BASE_HORIZON,
     PRICE_FORECAST_CHEAP_THRESHOLD,
     PRICE_FORECAST_DM_DEBT_OFFSET,
     PRICE_FORECAST_EXPENSIVE_THRESHOLD,
-    PRICE_FORECAST_MIN_DURATION,
     PRICE_FORECAST_PREHEAT_OFFSET,
     PRICE_FORECAST_REDUCTION_OFFSET,
     PRICE_OFFSET_CHEAP,
@@ -40,6 +40,8 @@
     PRICE_TOLERANCE_MAX,
     PRICE_TOLERANCE_MIN,
     QuarterClassification,
+    VOLATILE_MIN_DURATION_MINUTES,
+    VOLATILE_MIN_DURATION_QUARTERS,
     VOLATILE_WEIGHT_REDUCTION,
     WEATHER_COMP_DEFER_DM_CRITICAL,
 )
@@ -131,7 +133,7 @@ def get_fallback_prices() -> PriceData:
 
     for quarter in range(96):  # 96 quarters per day (15-min intervals)
         hour = quarter // 4
-        minute = (quarter % 4) * 15
+        minute = (quarter % 4) * MINUTES_PER_QUARTER
         start_time = base_date.replace(hour=hour, minute=minute)
         fallback_periods.append(QuarterPeriod(start_time=start_time, price=1.0))
 
@@ -824,8 +826,8 @@ def evaluate_layer(
             if (
                 expensive_quarters_away is not None
                 and expensive_ratio > PRICE_FORECAST_EXPENSIVE_THRESHOLD
-                and expensive_duration >= PRICE_FORECAST_MIN_DURATION
-                and expensive_quarters_away >= PRICE_FORECAST_MIN_DURATION
+                and expensive_duration >= VOLATILE_MIN_DURATION_QUARTERS
+                and expensive_quarters_away >= VOLATILE_MIN_DURATION_QUARTERS
             ):
                 increase_percent = int((expensive_ratio - 1) * 100)
                 forecast_adjustment = PRICE_FORECAST_PREHEAT_OFFSET
@@ -838,21 +840,21 @@ def evaluate_layer(
                 # Period meets price threshold but fails duration/lead-time requirements.
                 # Common cause: lookahead window boundary cuts off part of the period
                 # (e.g., we see 15min of a 45min peak because the rest is beyond horizon).
-                if expensive_duration < PRICE_FORECAST_MIN_DURATION:
+                if expensive_duration < VOLATILE_MIN_DURATION_QUARTERS:
                     _LOGGER.debug(
                         "Forecast: Expensive period too brief "
                         "(%dmin < %dmin) - may extend beyond lookahead",
-                        expensive_duration * 15,
-                        PRICE_FORECAST_MIN_DURATION * 15,
+                        expensive_duration * MINUTES_PER_QUARTER,
+                        VOLATILE_MIN_DURATION_MINUTES,
                     )
                 elif (
                     expensive_quarters_away is not None
-                    and expensive_quarters_away < PRICE_FORECAST_MIN_DURATION
+                    and expensive_quarters_away < VOLATILE_MIN_DURATION_QUARTERS
                 ):
                     _LOGGER.debug(
                         "Forecast: Expensive period too soon " "(%dmin < %dmin lookahead)",
-                        expensive_quarters_away * 15,
-                        PRICE_FORECAST_MIN_DURATION * 15,
+                        expensive_quarters_away * MINUTES_PER_QUARTER,
+                        VOLATILE_MIN_DURATION_MINUTES,
                     )
 
         elif classification in [
@@ -863,8 +865,8 @@ def evaluate_layer(
             if (
                 cheap_quarters_away is not None
                 and cheap_ratio < PRICE_FORECAST_CHEAP_THRESHOLD
-                and cheap_duration >= PRICE_FORECAST_MIN_DURATION
-                and cheap_quarters_away >= PRICE_FORECAST_MIN_DURATION
+                and cheap_duration >= VOLATILE_MIN_DURATION_QUARTERS
+                and cheap_quarters_away >= VOLATILE_MIN_DURATION_QUARTERS
             ):
                 savings_percent = int((1 - cheap_ratio) * 100)
                 forecast_adjustment = PRICE_FORECAST_REDUCTION_OFFSET
@@ -877,35 +879,35 @@ def evaluate_layer(
                 # Period meets price threshold but fails duration/lead-time requirements.
                 # Common cause: lookahead window boundary cuts off part of the period
                 # (e.g., we see 15min of a 45min cheap period beyond horizon).
-                if cheap_duration < PRICE_FORECAST_MIN_DURATION:
+                if cheap_duration < VOLATILE_MIN_DURATION_QUARTERS:
                     _LOGGER.debug(
                         "Forecast: Cheap period too brief "
                         "(%dmin < %dmin) - may extend beyond lookahead",
-                        cheap_duration * 15,
-                        PRICE_FORECAST_MIN_DURATION * 15,
+                        cheap_duration * MINUTES_PER_QUARTER,
+                        VOLATILE_MIN_DURATION_MINUTES,
                     )
                 elif (
                     cheap_quarters_away is not None
-                    and cheap_quarters_away < PRICE_FORECAST_MIN_DURATION
+                    and cheap_quarters_away < VOLATILE_MIN_DURATION_QUARTERS
                 ):
                     _LOGGER.debug(
                         "Forecast: Cheap period too soon " "(%dmin < %dmin lookahead)",
-                        cheap_quarters_away * 15,
-                        PRICE_FORECAST_MIN_DURATION * 15,
+                        cheap_quarters_away * MINUTES_PER_QUARTER,
+                        VOLATILE_MIN_DURATION_MINUTES,
                     )
 
         else:  # NORMAL - check both directions, take most significant sustained change
             expensive_valid = (
                 expensive_quarters_away is not None
                 and expensive_ratio > PRICE_FORECAST_EXPENSIVE_THRESHOLD
-                and expensive_duration >= PRICE_FORECAST_MIN_DURATION
-                and expensive_quarters_away >= PRICE_FORECAST_MIN_DURATION
+                and expensive_duration >= VOLATILE_MIN_DURATION_QUARTERS
+                and expensive_quarters_away >= VOLATILE_MIN_DURATION_QUARTERS
             )
             cheap_valid = (
                 cheap_quarters_away is not None
                 and cheap_ratio < PRICE_FORECAST_CHEAP_THRESHOLD
-                and cheap_duration >= PRICE_FORECAST_MIN_DURATION
-                and cheap_quarters_away >= PRICE_FORECAST_MIN_DURATION
+                and cheap_duration >= VOLATILE_MIN_DURATION_QUARTERS
+                and cheap_quarters_away >= VOLATILE_MIN_DURATION_QUARTERS
             )
 
             if expensive_valid and cheap_valid:
@@ -944,39 +946,39 @@ def evaluate_layer(
                 # Common cause: lookahead window boundary cuts off part of the period
                 # (e.g., we see 15min of a 45min peak beyond horizon). Expected behavior.
                 if expensive_ratio > PRICE_FORECAST_EXPENSIVE_THRESHOLD:
-                    if expensive_duration < PRICE_FORECAST_MIN_DURATION:
+                    if expensive_duration < VOLATILE_MIN_DURATION_QUARTERS:
                         _LOGGER.debug(
                             "Forecast NORMAL: Expensive period too brief "
                             "(%dmin < %dmin) - may extend beyond lookahead",
-                            expensive_duration * 15,
-                            PRICE_FORECAST_MIN_DURATION * 15,
+                            expensive_duration * MINUTES_PER_QUARTER,
+                            VOLATILE_MIN_DURATION_MINUTES,
                         )
                     elif (
                         expensive_quarters_away is not None
-                        and expensive_quarters_away < PRICE_FORECAST_MIN_DURATION
+                        and expensive_quarters_away < VOLATILE_MIN_DURATION_QUARTERS
                     ):
                         _LOGGER.debug(
                             "Forecast NORMAL: Expensive period too soon "
                             "(%dmin < %dmin lookahead)",
-                            expensive_quarters_away * 15,
-                            PRICE_FORECAST_MIN_DURATION * 15,
+                            expensive_quarters_away * MINUTES_PER_QUARTER,
+                            VOLATILE_MIN_DURATION_MINUTES,
                         )
                 if cheap_ratio < PRICE_FORECAST_CHEAP_THRESHOLD:
-                    if cheap_duration < PRICE_FORECAST_MIN_DURATION:
+                    if cheap_duration < VOLATILE_MIN_DURATION_QUARTERS:
                         _LOGGER.debug(
                             "Forecast NORMAL: Cheap period too brief "
                             "(%dmin < %dmin) - may extend beyond lookahead",
-                            cheap_duration * 15,
-                            PRICE_FORECAST_MIN_DURATION * 15,
+                            cheap_duration * MINUTES_PER_QUARTER,
+                            VOLATILE_MIN_DURATION_MINUTES,
                         )
                     elif (
                         cheap_quarters_away is not None
-                        and cheap_quarters_away < PRICE_FORECAST_MIN_DURATION
+                        and cheap_quarters_away < VOLATILE_MIN_DURATION_QUARTERS
                     ):
                         _LOGGER.debug(
                             "Forecast NORMAL: Cheap period too soon " "(%dmin < %dmin lookahead)",
-                            cheap_quarters_away * 15,
-                            PRICE_FORECAST_MIN_DURATION * 15,
+                            cheap_quarters_away * MINUTES_PER_QUARTER,
+                            VOLATILE_MIN_DURATION_MINUTES,
                         )
 
         # DM debt gate: Don't suppress heating when thermal debt exists (Dec 13, 2025)