feat: Add pv_ac_limit for AC coupled inverter PV clipping

Adds a new pv_ac_limit config setting that allows users with AC-coupled
inverters (non-hybrid) to model clipping from their PV system (e.g.,
microinverters with an AC output limit).

- config.py: Add pv_ac_limit to APPS_SCHEMA as a float
- fetch.py: Read pv_ac_limit (in Watts) and store as kWh/min on self
- predbat.py: Initialize self.pv_ac_limit = 0
- prediction.py: Pass pv_ac_limit through and apply AC clipping in
  the non-hybrid (else) branch after inverter_limit handling
- tests/test_infra.py: Add pv_ac_limit parameter to simple_scenario
  and reset_inverter
- tests/test_model.py: Add four new test scenarios for pv_ac_limit
- docs/apps-yaml.md: Document the new pv_ac_limit setting

Agent-Logs-Url: https://github.com/springfall2008/batpred/sessions/c2b66364-9d11-4c05-8b9f-88095c31c6dd

Co-authored-by: springfall2008 <48591903+springfall2008@users.noreply.github.com>

Author: Copilot

apps/predbat/config.py

@@ -2082,6 +2082,7 @@
     "pause_start_time": {"type": "sensor_list", "sensor_type": "none|string", "modify": True, "entries": "num_inverters"},
     "pause_end_time": {"type": "sensor_list", "sensor_type": "none|string", "modify": True, "entries": "num_inverters"},
     "inverter_limit": {"type": "sensor_list", "sensor_type": "float", "modify": False, "zero": False, "entries": "num_inverters"},
+    "pv_ac_limit": {"type": "float", "zero": True},
     "inverter_limit_charge": {"type": "sensor_list", "sensor_type": "integer", "modify": False, "zero": False, "entries": "num_inverters"},
     "inverter_limit_charge_dc": {"type": "sensor_list", "sensor_type": "integer", "modify": False, "zero": False, "entries": "num_inverters"},
     "inverter_limit_discharge": {"type": "sensor_list", "sensor_type": "integer", "modify": False, "zero": False, "entries": "num_inverters"},

apps/predbat/fetch.py

@@ -2156,6 +2156,7 @@ def fetch_config_options(self):
         self.battery_loss_discharge = 1.0 - self.get_arg("battery_loss_discharge")
         self.inverter_loss = 1.0 - self.get_arg("inverter_loss")
         self.inverter_hybrid = self.get_arg("inverter_hybrid")
+        self.pv_ac_limit = self.get_arg("pv_ac_limit", 0) / MINUTE_WATT
         self.base_load = self.get_arg("base_load", 0) / 1000.0
 
         # Charge curve

apps/predbat/predbat.py

@@ -529,6 +529,7 @@ def reset(self):
         self.battery_loss_discharge = 1.0
         self.inverter_loss = 1.0
         self.inverter_hybrid = True
+        self.pv_ac_limit = 0
         self.inverter_soc_reset = False
         self.inverter_set_charge_before = True
         self.best_soc_min = 0

apps/predbat/prediction.py

@@ -157,6 +157,7 @@ def __init__(self, base=None, pv_forecast_minute_step=None, pv_forecast_minute10
             self.inverter_hybrid = base.inverter_hybrid
             self.inverter_limit = base.inverter_limit
             self.export_limit = base.export_limit
+            self.pv_ac_limit = base.pv_ac_limit
             self.battery_rate_min = base.battery_rate_min
             self.battery_rate_max_charge = base.battery_rate_max_charge
             self.battery_rate_max_charge_dc = base.battery_rate_max_charge_dc
@@ -511,6 +512,7 @@ def run_prediction(self, charge_limit, charge_window, export_window, export_limi
         car_energy_reported_load = self.car_energy_reported_load
         inverter_limit = self.inverter_limit * step
         export_limit = self.export_limit * step
+        pv_ac_limit = self.pv_ac_limit * step
         set_charge_low_power = self.set_charge_window and self.set_charge_low_power and (save in ["best", "best10", "test"])
         carbon_enable = self.carbon_enable
         reserve = self.reserve
@@ -1007,6 +1009,12 @@ def run_prediction(self, charge_limit, charge_window, export_window, export_limi
                     else:
                         battery_draw = min(battery_draw + over_limit * inverter_loss, 0)
 
+                # Clip PV AC for non-hybrid (AC coupled) inverters with a PV AC limit (e.g. microinverters)
+                if pv_ac_limit > 0 and pv_ac > pv_ac_limit:
+                    pv_ac_before = pv_ac
+                    pv_ac = pv_ac_limit
+                    clipped_today += pv_ac_before - pv_ac
+
             # Export limit, clip PV output
             diff = get_diff(battery_draw, pv_dc, pv_ac, load_yesterday, inverter_loss, inverter_loss_recp)
             if diff < 0 and abs(diff) > export_limit:

apps/predbat/tests/test_infra.py

@@ -448,6 +448,7 @@ def reset_inverter(my_predbat):
     my_predbat.inverter_limit = 1 / 60.0
     my_predbat.num_inverters = 1
     my_predbat.export_limit = 10 / 60.0
+    my_predbat.pv_ac_limit = 0
     my_predbat.inverters = [TestInverter()]
     my_predbat.charge_window = []
     my_predbat.export_window = []
@@ -598,6 +599,7 @@ def simple_scenario(
     set_charge_freeze=True,
     calculate_export_on_pv=True,
     assert_clipped=0,
+    pv_ac_limit=0,
 ):
     """
     No PV, No Load
@@ -656,6 +658,7 @@ def simple_scenario(
     my_predbat.inverter_hybrid = hybrid
     my_predbat.export_limit = export_limit / 60.0
     my_predbat.inverter_limit = inverter_limit / 60.0
+    my_predbat.pv_ac_limit = pv_ac_limit / 60.0
     my_predbat.reserve = reserve
     my_predbat.inverter_loss = inverter_loss
     my_predbat.battery_rate_max_charge = battery_rate_max_charge / 60.0

apps/predbat/tests/test_model.py

@@ -1870,6 +1870,30 @@ def run_model_tests(my_predbat):
         assert_iboost_running_solar=True,
     )
 
+    # PV AC limit tests (AC-coupled / non-hybrid inverters only)
+    reset_rates(my_predbat, import_rate, export_rate)
+    reset_inverter(my_predbat)
+    # No clipping when pv_ac_limit is above the actual PV output
+    failed |= simple_scenario("pv_ac_limit_no_clip", my_predbat, 0, 1.0, assert_final_metric=-export_rate * 24, assert_final_soc=0, with_battery=False, pv_ac_limit=2.0)
+    # Clipping when pv_ac_limit is below the actual PV output (non-hybrid AC-coupled)
+    failed |= simple_scenario("pv_ac_limit_ac_clip", my_predbat, 0, 2.0, assert_final_metric=-export_rate * 24 * 1.5, assert_final_soc=0, with_battery=False, pv_ac_limit=1.5, assert_clipped=24 * 0.5)
+    # With a load, clipping still applies; load is met from grid when pv is capped
+    failed |= simple_scenario(
+        "pv_ac_limit_ac_clip_with_load",
+        my_predbat,
+        0.5,
+        2.0,
+        assert_final_metric=-export_rate * 24 * 1.0,
+        assert_final_soc=0,
+        with_battery=False,
+        pv_ac_limit=1.5,
+        assert_clipped=24 * 0.5,
+    )
+    # pv_ac_limit must NOT apply to hybrid inverters (PV is DC-coupled, clipping handled by inverter_limit)
+    failed |= simple_scenario("pv_ac_limit_hybrid_ignored", my_predbat, 0, 2.0, assert_final_metric=-export_rate * 24, assert_final_soc=24, with_battery=True, hybrid=True, pv_ac_limit=1.5)
+    if failed:
+        return failed
+
     if failed:
         print("**** ERROR: Some Model tests failed ****")
     return failed

docs/apps-yaml.md

@@ -913,6 +913,28 @@ If you have multiple inverters then set the value of each one in a list format.
 
 NB: inverter_limit is ONLY used by Predbat to improve the quality of the plan, any solar clipping is done by the inverter and is not controlled by Predbat.
 
+### **pv_ac_limit**
+
+Optional, applies to **non-hybrid (AC coupled) inverters only**.
+
+Controls the way Predbat models the maximum AC output of your PV system.
+This does not change the way the inverter is controlled.
+
+When set, defines the maximum AC output power in watts for your PV system (e.g. microinverters).
+This is used by Predbat to model clipping that occurs when your PV generation exceeds the AC output limit,
+for example if you have microinverters with a rated maximum AC output.
+
+This setting is ignored for hybrid inverters (`inverter_hybrid: true`) because in a hybrid system the PV
+connects directly to the DC bus and clipping is already modelled via `inverter_limit`.
+
+Example:
+
+```yaml
+  pv_ac_limit: 3600
+```
+
+NB: pv_ac_limit is ONLY used by Predbat to improve the quality of the plan, any solar clipping is done by the inverter and is not controlled by Predbat.
+
 ### **export_limit**
 
 One per inverter (optional).