feat(prediction): add configurable battery loss during Freeze Export

[PlainSeer]

Summary

Adds an optional prediction-only model for battery-side energy loss while Freeze Export is active.

This issue has been directly observed and measured on an AlphaESS SMILE-G3 system: while PredBat Freeze Export successfully prevents normal battery discharge, the AlphaESS system continues to draw a small amount of energy internally from the battery. Controlled Home Assistant recorder testing measured approximately 231 W average battery-side discharge during a clean Freeze Export period.

PredBat currently has no separate model for this type of internal consumption, so during extended Freeze Export periods the predicted battery SoC can remain higher than the actual SoC.

Other inverter/battery systems may exhibit similar behaviour, so rather than hard-coding an AlphaESS-specific value, this PR adds a generic configurable setting:

inverter_freeze_export_loss: 240

The value is specified in watts and defaults to 0, preserving existing behaviour for all installations unless explicitly configured.

Behaviour

While a genuine Freeze Export window is active, the configured loss is deducted directly from predicted battery SoC. It is intentionally not added to house load or grid export because it represents internal battery/inverter consumption rather than useful energy delivered to the house or grid.

The implementation defaults to 0 W, clamps negative configured values to zero, applies only during Freeze Export, is directional battery discharge only, respects the expected battery reserve, includes the internal discharge in battery-cycle accounting, changes prediction only, and is implemented in both the Python predictor and C++ prediction kernel.

Why a separate setting?

This loss should not be represented using the inverter/battery minimum-rate model. Testing that approach affected the prediction in the wrong direction because the minimum-rate setting participates in the normal charge/discharge energy-flow model.

Freeze Export loss is different: it is battery-side consumption occurring while the normal external battery flow is intentionally frozen. A separate directional prediction term therefore models the observed behaviour without fabricating house load or grid energy.

Real-world validation

Controlled testing was carried out on 18 August 2026 on an AlphaESS SMILE-G3 installation with 13.68 kWh usable battery capacity.

During a clean Freeze Export period from approximately 11:00:29 to 11:25:58, Home Assistant recorder data showed repeated battery-side discharge measurements of approximately:

208 W
238 W
239 W
209 W
239 W
209 W
239 W
269 W
239 W

Time-weighting those recorder measurements gives an average battery-side discharge of approximately 231 W.

This independently supports a practical site calibration value of:

inverter_freeze_export_loss: 240

The battery SoC trace also declined during the period. SoC on this installation is reported in relatively coarse steps, so the direct battery-power recorder data provides the cleaner short-duration calibration signal.

For the 13.68 kWh usable battery, 240 W is 0.240 kWh/hour, or about 1.75 percentage points of SoC per hour. Over the roughly 25.5-minute controlled period that corresponds to about 0.74 percentage points, consistent with the observed stepped SoC behaviour.

240 W is not intended to be a universal AlphaESS default. Internal consumption may vary by inverter model, battery, firmware, configuration and operating mode, which is why the setting is configurable rather than inverter-specific.

Tests

Regression coverage has been added using a generic 10 kWh test battery. It verifies that 0 W preserves existing behaviour, 240 W for one hour produces the expected 0.24 kWh battery-energy reduction during Freeze Export, the loss does not apply outside Freeze Export, the reserve floor is respected, and the loss is included in battery-cycle accounting.

The same model cases run through both the Python and C++ prediction engines, and the seeded kernel-parity scenarios exercise the new field without altering their existing random sequence.

The existing PredBat pre-commit checks, quick unit-test suite, prediction-kernel build, checked-in x86_64 kernel verification and cross-platform kernel builds all pass on the proposed commit.

Scope

This is a prediction-only change. It does not modify inverter commands, charge control, export control, the decision to enter Freeze Export, or Home Assistant control behaviour. Systems that do not configure inverter_freeze_export_loss continue to use the existing behaviour.

[springfall2008]

Seems like a good idea, but 'loss' implies a factor and not a value.

Is it really losing this 240w or is it just discharging at 240w rate?

[PlainSeer]

Yes, that’s a better description.

The AlphaESS is not showing a percentage/factor loss; the battery is continuing to discharge at roughly 230–240 W while Freeze Export is active.

I used “loss” to distinguish it from normal house/grid discharge, but inverter_freeze_export_discharge_rate would be clearer and better reflects the measured behaviour.