fix(plan): gate Freeze Export on a new inverter_can_freeze_export flag (#4207/#4538)

springfall2008 pointed out on #4538 that gating on
inverter_can_charge_during_export was wrong: that flag is specifically
about PV exceeding the inverter/export limit during *active* Force Export
(see its own docstring), not about whether Freeze Export can hold the
battery flat at all - two genuinely different questions this PR had
conflated.

Add inverter_can_freeze_export as its own setting (apps.yaml only, defaults
to true) and gate optimise_export()/optimise_solar()'s freeze offering on
it instead. Reusing inverter_can_charge_during_export's default of true
would have been wrong here too - most inverters genuinely can freeze, so
"assume it works, let affected users opt out" is the right default for
this flag as well, it just needed to be a different flag with a different
meaning, not a shared one.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: chalfontchubby

apps/predbat/fetch.py

@@ -2396,6 +2396,7 @@ def fetch_config_options(self):
         self.inverter_clock_skew_discharge_start = self.get_arg("inverter_clock_skew_discharge_start", 0)
         self.inverter_clock_skew_discharge_end = self.get_arg("inverter_clock_skew_discharge_end", 0)
         self.inverter_can_charge_during_export = self.get_arg("inverter_can_charge_during_export", True)
+        self.inverter_can_freeze_export = self.get_arg("inverter_can_freeze_export", True)
 
         # Log clock skew
         if self.inverter_clock_skew_start != 0 or self.inverter_clock_skew_end != 0:

apps/predbat/plan.py

@@ -2126,11 +2126,15 @@ def optimise_export(self, window_n, record_charge_windows, try_charge_limit, cha
         export_step = 5
         export_step_large = 15
 
-        if not self.set_export_freeze or self.inverter_can_charge_during_export:
-            # An inverter that charges the battery from surplus PV regardless of what it's been told
-            # (inverter_can_charge_during_export) can't actually achieve a frozen SoC - it behaves
-            # identically to idle in that case, so offering freeze as a distinct option is pointless
-            # and would mislabel the plan (#4207/#4425).
+        if not self.set_export_freeze or not self.inverter_can_freeze_export:
+            # inverter_can_freeze_export is a different question to inverter_can_charge_during_export
+            # (that one is specifically about PV exceeding the export/inverter limit during *active*
+            # force export - see its own docstring). Some inverters simply cannot be commanded into a
+            # state where battery charging is disabled at all - they charge from any available surplus
+            # PV regardless of mode, so Freeze Export never achieves anything distinct from idle on
+            # them. Offering it as a distinct plan option there is pointless and mislabels the plan
+            # (#4207/#4538 - originally gated on inverter_can_charge_during_export, corrected after
+            # springfall2008 pointed out that conflated two genuinely different things).
             allow_freeze = False
 
         # loop on each export option
@@ -3054,8 +3058,8 @@ def optimise_solar(self, best_metric, best_cost, best_keep, best_cycle, best_car
 
         # Freeze export slots only have an effect when export freeze is enabled, and only mean anything
         # distinct from idle when the inverter can actually hold SoC flat - see optimise_export()'s
-        # matching gate (#4207/#4425) for why inverter_can_charge_during_export rules it out too.
-        if not self.calculate_best_export or not self.set_export_freeze or not self.export_window_best or self.inverter_can_charge_during_export:
+        # matching gate (#4207/#4538) for why inverter_can_freeze_export rules it out too.
+        if not self.calculate_best_export or not self.set_export_freeze or not self.export_window_best or not self.inverter_can_freeze_export:
             return best_metric, best_cost, best_keep, best_cycle, best_carbon, best_import
 
         pv_forecast_minute_step = self.prediction.pv_forecast_minute_step

apps/predbat/predbat.py

@@ -604,6 +604,7 @@ def reset(self):
         self.set_export_low_power = False
         self.config_root = "./"
         self.inverter_can_charge_during_export = True
+        self.inverter_can_freeze_export = True
         self.octopus_last_joined_try = None
         self.calculate_savings_max_charge_slots = 1
         self.inverter_data_last_fetch = None

apps/predbat/tests/test_optimise_solar.py

@@ -32,7 +32,7 @@ def run_optimise_solar(
     expect_export_start=None,
     car_charging_slots=None,
     car_charging_from_battery=False,
-    inverter_can_charge_during_export=False,
+    inverter_can_freeze_export=True,
 ):
     print("Starting optimise solar test {}".format(name))
     failed = False
@@ -42,7 +42,7 @@ def run_optimise_solar(
     my_predbat.calculate_best_export = calculate_best_export
     my_predbat.set_export_freeze = set_export_freeze
     my_predbat.set_charge_freeze = True
-    my_predbat.inverter_can_charge_during_export = inverter_can_charge_during_export
+    my_predbat.inverter_can_freeze_export = inverter_can_freeze_export
     my_predbat.export_more_solar_threshold = threshold
     my_predbat.soc_max = battery_size
     my_predbat.soc_kw = battery_soc
@@ -163,18 +163,19 @@ def run_optimise_solar_tests(my_predbat):
         set_export_freeze=False,
     )
 
-    # An inverter that charges the battery from surplus PV regardless of command can't actually hold
-    # SoC flat, so freeze is no different from idle for it (#4207/#4425) - feature is a no-op here too,
-    # same outcome as freeze_disabled above but via the capability gate instead of the switch
+    # An inverter that can't be commanded into a state where battery charging is disabled at all
+    # can't actually hold SoC flat, so freeze is no different from idle for it (#4207/#4538) - feature
+    # is a no-op here too, same outcome as freeze_disabled above but via the capability gate instead
+    # of the switch
     failed |= run_optimise_solar(
-        "freeze_pointless_when_inverter_always_charges",
+        "freeze_pointless_when_inverter_cannot_freeze",
         my_predbat,
         export_window_best=export_window_best,
         export_limits_best=[100.0, 100.0, 100.0],
         expect_export_limit=[100.0, 100.0, 100.0],
         pv_amount=3.0,
         threshold=100.0,
-        inverter_can_charge_during_export=True,
+        inverter_can_freeze_export=False,
     )
 
     # An already active export window (limit 0) is left untouched, only idle ones are converted

docs/apps-yaml.md

@@ -1149,6 +1149,19 @@ During a force export period if the generated solar exceeds the inverter limit o
 If this setting is `true` then the inverter is able to charge the battery from excess PV while still in Force Export mode.
 If this setting is `false` then the inverter will not charge the battery and the excess PV will be lost.
 
+This is a different question to **inverter_can_freeze_export** below - it's specifically about PV exceeding the inverter/export limit during *active* Force Export, not about whether Freeze Export can hold the battery flat at all.
+
+### **inverter_can_freeze_export**
+
+Global setting, defaults to `true`.
+
+Controls the way Predbat models your inverter, this does not change the way it is controlled.
+
+Freeze Export is meant to disable battery charging entirely so all solar is exported. Some inverters (e.g. certain "Feed-in First" work modes) cannot be commanded into a state where charging is disabled at all - they keep charging the battery from any available surplus PV regardless of the mode requested.
+
+If this setting is `true` (the default) Predbat assumes Freeze Export genuinely holds the battery flat, and will offer it as a distinct option in the plan.
+If this setting is `false`, Predbat assumes your inverter can't actually achieve that - Freeze Export would behave identically to Idle - so it stops offering Freeze Export in the plan at all, rather than showing a `FrzExp` slot that wouldn't achieve anything different from doing nothing.
+
 ## Controlling the Inverter
 
 There are a few different ways to control your inverter: