Feature: Native Solar Clipping Buffer (Resolves #1206)

[rholligan]

Resolves #1206. This PR introduces a native clipping buffer to Predbat. It prevents solar energy loss on high-generation days by reserving a dynamic buffer in the battery SoC, specifically targeting periods where PV generation is forecast to exceed inverter AC capacity or DNO export limits.

Key Features:

• Dynamic Buffer Calculation: Computes the required buffer (sensor.predbat_clipping_buffer_kwh) based on the solar forecast area exceeding the "Effective
  Clipping Limit" (choosing the most restrictive hardware or DNO constraint).
• Grid-Charge Capping: Restricts overnight grid charging to ensure headroom for the calculated buffer.
• Proactive Risk Management: Includes a two-stage safety system. It uses a risk_threshold (trigger) and a configurable clipping_buffer_safety_margin
  (default 5% of window solar) to protect against un-forecasted cloud-edge spikes.
• Dynamic Buffer Decay: Reserved space shrinks as the solar peak passes, releasing capacity for evening use.
• Web UI Integration: Adds a "Clipping Analysis" chart to the Predbat Web UI, displaying PV curves, clipping ceilings, and the decaying buffer.
• Improved Peak Reporting: Refined the clipping status text to report the actual high-risk generation period (minutes exceeding the limit) rather than the broad protection window, providing clearer information for the user.

Configuration Parameters:

• clipping_buffer_enable: Master toggle.
• clipping_buffer_forecast: Selection of forecast model (recommends pv_clearsky).
• clipping_buffer_safety_margin: Percentage of window solar to reserve as a safety factor (default 0.05).
• clipping_buffer_risk_threshold: Sensitivity factor to trigger the safety margin logic (default 0.80).
• clipping_buffer_can_discharge: Discharge behavior (None, Cost Optimal, or Always).
• clipping_buffer_min_kwh / max_kwh: Manual size constraints.
• clipping_buffer_limit_override: Manual power threshold override (Watts).

Testing & Documentation:

• Verified on live 5kW hardware; effectively mitigated 6.28kW solar spikes by holding battery headroom.
• Includes unit tests in apps/predbat/tests/test_clipping.py.
• Full feature documentation available in docs/clipping.md.

Developed with Gemini ✦

[tieskuh]

Cross-referencing #4023 (Model curtailment on a negative export price) — our PRs look complementary and touch some of the same files, so flagging for coordination.

	#4023	This PR (#4036)
Trigger	export price is negative (rate-conditional)	PV exceeds a power limit (inverter AC / DNO export)
Goal	avoid a phantom export cost + keep PV calibration clean	avoid solar lost to clipping
Approach	modelling-only (models the curtailment)	active control (reserves battery SoC headroom)
Related issue	#3986	#1206 (+ #3442 / #3481 / #3828)

Yours handles clipping against a power limit with active SoC buffering; mine models price-driven curtailment and keeps PV calibration clean (modelling-only). We overlap in prediction.py / solcast.py / output.py / config.py and the tests, so whichever merges second will need a rebase. Happy to rebase mine on top if yours lands first.

[springfall2008]

This looks very smart, I guess the question I have at the higher level is why does PredBat not handle the clipping correctly already, could it do so natively without having to work around it?

[rholligan]

Thanks @springfall2008!

IMO the need for a solution like the clipping buffer stems from the combination of hardware limits and forecast resolution:

1. On free tier, Solcast provides smoothed average generation over 30-minute blocks. A block forecasting a 3kW average might mask local variability / maximums (e.g. 10 minutes of 6kW peak sun, followed by 20 minutes of cloud).
2. On systems with high DC-to-AC ratios (e.g. a 5kW hybrid inverter with 7kWp panels), that 6kW spike can only be captured if the battery has empty capacity to absorb the DC excess.
3. Because Predbat plans against the 30-minute average (3kW), it assumes generation will stay below the 5kW inverter limit. Consequently, the plan might optimise for e.g. cheap import rates and charges the battery to 100%.
4. When the 6kW spike actually occurs, the inverter is maxed out at 5kW, the battery is at 100%, and the 1kW DC excess is clipped and lost. The optimiser can't natively prevent this because the spike is hidden in the forecast average.

This feature introduces a proactive safety margin to ensure there is always a buffer of empty battery space ready to absorb those local above average spikes.

[rholligan]

Thanks @tieskuh for flagging - more than happy to handle the rebase depending what first! Great work on #4023.

[springfall2008]

On free tier, Solcast provides smoothed average generation over 30-minute blocks. A block forecasting a 3kW average might mask local variability / maximums (e.g. 10 minutes of 6kW peak sun, followed by 20 minutes of cloud).

Inside PredBat solar there is a cloud model which creates a wave formation on the solar in 5 minute intervals throughout the 30 minute period basic on the variation between 10% and 90% forecasts.

I'm wondering why it isn't working for you and if we can debug that?

[daviessm]

I'm wondering why it isn't working for you and if we can debug that?

I think there are probably a few things affecting it. This happens for me as well, and it seems to be at least partially because Predbat assumes that in freeze export mode the battery won't be charged whereas for FoxESS at least, it is, when the generation is above the export limit + house load. This causes Predbat to think that battery will fill slower than it actually does. See #3555 for a bit of a discussion on that.

[rholligan]

Hey @springfall2008, taking your suggestion, I've had a stab at integrating the manual clipping overrides directly into the cloud model.

I'm still testing on my setup to evaluate real life results, but if you have a sec I'd appreciate you your eyes on the approach to see if it better aligns with your expectations.

You can check out the branch here: https://github.com/rholligan/batpred/tree/clipping-cloud-model