Add night surplus forecast to battery state publishing

[MaStr]

Summary

Adds computation and MQTT publishing of the expected battery surplus at the start of the next solar production window (morning). This metric helps identify when the battery will retain usable charge after overnight discharge, enabling flexible load scheduling before dawn.

Changes

• New method _compute_night_surplus() in core.py: Calculates expected battery energy remaining after the overnight discharge period between end of today's solar production and start of tomorrow's production. Returns 0 if no solar production window exists in forecast.

  • Projects battery level at end of first production window, accounting for stored energy and free capacity constraints
  • Identifies the night period (gap between first and second production windows)
  • Subtracts night consumption from projected battery level, clamped to non-negative

• Integration in run() loop: Calls _compute_night_surplus() with current production/consumption forecast and battery state, publishes result via MQTT

• MQTT API enhancements:

  • New publish_night_surplus() method to publish /night_surplus_wh topic
  • Added MQTT discovery message for Home Assistant integration
  • Updated module docstring to document the new metric

• Comprehensive test suite (test_night_surplus.py): 13 test cases covering:

  • No production scenarios
  • Solar active (current day production) with various battery states
  • Solar inactive (bridge night, production tomorrow) scenarios
  • Edge cases: battery depletion, free capacity limits, different time resolutions (15-min, 60-min)
  • Ensures surplus never goes negative

Implementation Details

• Uses numpy array slicing to efficiently compute net consumption/production deltas
• Handles variable forecast lengths (may end before next production window)
• Respects battery constraints: stored energy floor and free capacity ceiling
• Logs debug information for troubleshooting (battery projection, night consumption, slot count)

https://claude.ai/code/session_01AbZuZ73iEQMiwTkwy3Mt1h

[Copilot]

Pull request overview

Adds a new forecast-derived metric (“night surplus”) to estimate remaining usable battery energy after an overnight discharge period, and publishes it via MQTT (including Home Assistant discovery), with a dedicated pytest module.

Changes:

• Added Batcontrol._compute_night_surplus() and integrated it into the run() loop to compute and publish the metric.
• Extended MqttApi with /night_surplus_wh publishing and Home Assistant MQTT discovery configuration.
• Added tests/batcontrol/test_night_surplus.py to validate the new computation across multiple forecast scenarios.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
src/batcontrol/core.py	Adds computation for night surplus and publishes it during the main control loop.
src/batcontrol/mqtt_api.py	Introduces MQTT publish method + HA discovery entry for /night_surplus_wh.
tests/batcontrol/test_night_surplus.py	New tests covering the night surplus calculation behavior.