feat(fetch): warn when export_more_solar is enabled but has no effect

[chalfontchubby]

🤖 This PR was written by Claude.

Problem

export_more_solar works by enabling Freeze Export on otherwise-idle slots that have predicted solar generation, so optimise_solar() returns immediately unless export slots are being planned and Freeze Export is available:

# Freeze export slots only have an effect when export freeze is enabled
if not self.calculate_best_export or not self.set_export_freeze or not self.export_window_best:
    return best_metric, best_cost, best_keep, best_cycle, best_carbon, best_import

The switch is then on but does nothing whatsoever, and nothing anywhere says so. This turned up while investigating #4865 - a user had been running that combination for months, reasonably assuming the setting was doing something.

Change

Warn when export_more_solar is enabled but cannot have any effect, naming the cause:

• mode is not Control charge & discharge (calculate_best_export is off), so export slots are not planned
• the inverter does not support Freeze Export - fetch_inverter_data() forces set_export_freeze off whatever the switch says, so the user is told to turn export_more_solar off rather than to enable a switch that would change nothing
• set_export_freeze is off

The check is check_export_more_solar_effective(), run from update_pred() right after the first successful fetch_inverter_data(). It cannot live in fetch_config_options(): that runs before the inverter-capability override, so an unsupported inverter would never be caught.

Logged once per incident rather than every cycle, since the combination may well be deliberate. The last reason is tracked rather than a bool, so fixing one cause while another remains warns again instead of going quiet; it re-arms once export_more_solar is effective, so a later recurrence is reported.

docs/customisation.md already stated the dependency; it now also lists the three cases that warn.

Testing

test_export_more_solar_warning.py, five tests:

• optimise_solar() really is a no-op in each warned state - prediction is swapped for an object that raises on use, with a positive control for the effective case, so the guard itself is tested rather than whatever an earlier test left in the shared fixture
• each cause produces its own message, and an unsupported inverter is never told to enable set_export_freeze (including when the switch is also off)
• once per incident, quiet on later cycles, re-armed after becoming effective
• warns again when the reason changes
• export_more_solar off, or fully effective, never warns

Mutation-tested: reading the configured switch instead of the effective value, reverting to a bool flag, and removing the optimise_solar() guard each fail the suite.

• ./run_all --quick green
• ./run_pre_commit green

Note

This is only the discoverability half. The related finding from #4865 - that Freeze Export causes clipping on inverters without support_feedin_first (e.g. Sigenergy), so enabling it can be actively counterproductive there - would need its own warning and is not included here.

[Copilot]

Copilot review overview

🔵 Needs a closer look

The warning must also cover inverter configurations where Freeze Export support is unavailable.

Review effort: Lite
Findings: None

What changed in this PR

Adds a throttled warning when export_more_solar is enabled without effective Freeze Export support, with documentation and regression tests.

Changes:

• Adds once-per-incident warning state and logging.
• Documents the ineffective configuration.
• Adds tests for no-op behavior, throttling, reset, and valid combinations.

File	Summary
docs/​customisation.md	Documents the warning behavior.
apps/​predbat/​unit_test.py	Registers the new tests.
apps/​predbat/​tests/​test_export_more_solar_warning.py	Tests warning and reset behavior.
apps/​predbat/​predbat.py	Initializes warning state.
apps/​predbat/​fetch.py	Emits the configuration warning; currently misses cases where inverter discovery disables Freeze Export.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.