Feature: Automated Solar Clipping Mitigation (using native clear-sky models)

[rholligan]

Introduction:

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

This implementation integrates with the existing cloud model. It extends SolarAPI to compute and store new pv_clearsky arrays (supporting multiple native upstream sources like ha_solcast_clearsky, solcast_api, and openmeteo). Clear-sky arrays are used alongside a lightweight auto-tuner to safely estimate peak generation and align it with hardware limits.

Resolves issue #1206, supersedes PR #4036.

Key Features:

• Dynamic Buffer Calculation: Calculates exactly how much spare capacity the battery needs to safely absorb any solar generation that exceeds the inverter limits.
• Cost-Optimized Headroom Creation: Integrates directly into Predbat's financial solver by adding a cost penalty whenever the battery doesn't have enough headroom. This naturally forces Predbat to prioritize exporting or deferring charge just before a solar peak hits, guaranteeing the necessary spare capacity.
• Clear-Sky Cloud Modelling: Introduces ha_solcast_clearsky integration alongside a robust clipping_auto_tune mechanism. This explicitly accounts for those short "break in the clouds" spikes, ensuring the buffer is safely sized even when the standard hourly forecast is smoothed out.
• Defensive HA Polling: Hardened solcast.py with safe float(val or 0.0) casting to gracefully handle missing HA clear-sky sensor history without crashing.

Configuration Parameters:

• clipping_buffer_enable: Master toggle for the clipping buffer feature.
• clipping_clearsky_source: Selection of clear-sky forecast source (recommends ha_solcast_clearsky). This setting is fully exposed in the Home Assistant configuration panel.
• clipping_use_clearsky_peaks: Toggle to use Clear-Sky generation arrays rather than standard PV forecast arrays to size the buffer.
• clipping_auto_tune: Automatically learns the scale difference between standard forecasts and hardware limits based on past clipping behavior.
• clipping_amplification: Manual multiplier for the standard solar forecast (used if Auto-Tune is disabled).
• clipping_cost_weight: Multiplier to add a harsher financial penalty for clipping, forcing the optimizer to prioritize creating headroom.
• clipping_limit_override: Manual configuration of the inverter AC ceiling in Watts.
• clipping_buffer_max_kwh / start_time / end_time: Manual settings to force a fixed static buffer size and time window instead of using the dynamic calculation.

Developed with Gemini ✦

[giddie]

I'm very excited about this. I think this is the correct approach. The cloud model that mixes with the 90% solar scenario isn't sufficient to model the sporadic full-intensity bursts from clear skies between clouds. And Solcast's "peak power" is nowhere near the actually-observed peak power. So I think using this "clear skies" model instead (or in addition) is exactly what's needed.

[jkpe]

@rholligan thanks for this!

I’m experiencing regular clipping at the moment so I’ll give this a spin later today and let you know if there are any issues.

[rholligan]

@rholligan thanks for this!

I’m experiencing regular clipping at the moment so I’ll give this a spin later today and let you know if there are any issues.

Hey @jkpe,

Glad you’re giving the clipping buffer a spin!

It's been working really well on my setup (6.4 kWp array / 5 kW inverter) over the last weeks, the battery gets just enough head room before peaks to prevent clipping, and the clipping_auto_tune setting has nicely tracked the seasonal generation peaks, rising initially and now tapering after the solstice.

Please let us know how it behaves on your system and if you have any unique configuration we should accommodate.

@springfall2008 – any update on the review status? Let me know if there’s anything we can do to move this into main.

[jkpe]

@rholligan

Apart from installing https://github.com/autoSteve/ha-solcast-clearsky do I need to make any changes to my Solcast configuration or integration? I’ve got a 5kW inverter so I’ve got that set as my AC limit on Solcast’s website, or should I remove this so that we’re getting unclipped data? I think Solcast clips it for you if you set an AC limit.

[rholligan]

@rholligan

Apart from installing https://github.com/autoSteve/ha-solcast-clearsky do I need to make any changes to my Solcast configuration or integration? I’ve got a 5kW inverter so I’ve got that set as my AC limit on Solcast’s website, or should I remove this so that we’re getting unclipped data? I think Solcast clips it for you if you set an AC limit.

As you say, set Solcast to your actual array capacity, and let Predbat handle the clipping calculation (so in my case I set both Capacity DC (modules) in kW and Capacity AC in kW in Solcast to 6.4 kW).