Rebuild: the battery account in code

@dataclass
class BatteryAccount:
    """Bookkeeping for the energy in a battery, in kWh and in euros."""

    energy_kwh: float = 0.0
    """Stock: energy booked into the battery right now (goes up and down)."""

    cost_eur: float = 0.0
    """Stock: what that energy cost (goes up and down with it)."""

    solar_in_kwh: float = 0.0
    """Counter: everything ever charged from the sun (never goes down)."""

    grid_in_kwh: float = 0.0
    """Counter: everything ever charged from the grid (never goes down)."""

    def charge(self, kwh: float, price_eur_kwh: float) -> None:
        """Book kwh at price_eur_kwh. Every kilowatt hour brings its price."""
        if kwh <= 0:
            return
        self.energy_kwh += kwh
        self.cost_eur += kwh * price_eur_kwh

    def charge_solar(self, kwh: float, price_eur_kwh: float = 0.0) -> None:
        """Charge from the sun. The panels are paid for: price 0 by default."""
        if kwh <= 0:
            return
        self.charge(kwh, price_eur_kwh)
        self.solar_in_kwh += kwh

    def charge_grid(self, kwh: float, price_eur_kwh: float) -> None:
        """Charge from the grid at the price that applied when it came in."""
        if kwh <= 0:
            return
        self.charge(kwh, price_eur_kwh)
        self.grid_in_kwh += kwh

    def discharge(self, kwh: float) -> float:
        """Take kwh out at the average price; returns the kWh actually booked.

        The price stays exactly where it was: only the amount changes.
        An empty account books nothing (there is no price to take out at).
        """
        price = self.price()
        if kwh <= 0 or price is None:
            return 0.0
        taken = min(kwh, self.energy_kwh)
        self.energy_kwh -= taken
        self.cost_eur = self.energy_kwh * price
        return taken

    def price(self) -> float | None:
        """Price per kWh in EUR, or None if the account is empty."""
        if self.energy_kwh <= EMPTY_KWH:
            return None
        return self.cost_eur / self.energy_kwh

def book_interval(self, *, hours: float, battery_w: float | None,
                  solar_w: float | None, grid_import_w: float | None,
                  grid_price_eur_kwh: float | None) -> Booking:
    """Book one interval of length hours. Returns what was booked."""
    if hours <= 0:
        return Booking("idle", 0.0, reason="no time has passed")
    if battery_w is None:
        return Booking("skipped", 0.0, reason="battery power unknown")

    kwh = self._smooth(battery_w) * hours / 1000.0

    if kwh < 0:
        taken = self.account.discharge(-kwh)
        return Booking("discharge", -taken,
                       reason="price unchanged" if taken else "account empty")
    if kwh == 0:
        return Booking("idle", 0.0, reason="battery at rest")

    # Charging: where does this energy come from?
    if solar_w is None or grid_import_w is None:
        return Booking("skipped", 0.0,
                       reason="source unknown, nothing booked")
    solar = max(solar_w, 0.0)
    grid = max(grid_import_w, 0.0)
    total = solar + grid
    # Split in proportion to solar power and grid import right now.
    # Nothing measured on either side: counted as grid (the expensive,
    # careful choice).
    solar_share = solar / total if total > 0 else 0.0
    solar_kwh = kwh * solar_share
    grid_kwh = kwh - solar_kwh

    price = None
    if grid_kwh > 0:
        if grid_price_eur_kwh is None:
            return Booking("skipped", 0.0, reason="grid price unknown")
        price = min(grid_price_eur_kwh, self.settings.max_grid_price_eur_kwh)
        self.account.charge_grid(grid_kwh, price)
    if solar_kwh > 0:
        self.account.charge_solar(solar_kwh, self.settings.solar_price_eur_kwh)
    return Booking("charge", kwh, solar_kwh, grid_kwh, price,
                   reason="booked by source")

def source_price(*, surplus_w: float | None, soc_pct: float | None,
                 battery_may_discharge: bool, account_price_eur_kwh: float | None,
                 grid_price_eur_kwh: float,
                 settings: SourceSettings | None = None) -> SourcePrice:
    """Where would the next kWh come from, and what does it cost?"""
    s = settings if settings is not None else SourceSettings()

    if surplus_w is not None and surplus_w >= s.min_surplus_w:
        return SourcePrice(0.0, SOLAR, "solar surplus, would otherwise be exported")

    soc_ok = soc_pct is not None and soc_pct > s.battery_floor_pct
    if soc_ok and battery_may_discharge and account_price_eur_kwh is not None:
        return SourcePrice(account_price_eur_kwh, BATTERY,
                           "battery above its floor delivers the kWh")

    if soc_pct is None:
        why = "battery level unknown"
    elif not battery_may_discharge:
        why = "battery may not discharge"
    elif not soc_ok:
        why = "battery at or below its floor"
    else:
        # An unknown account price is not a price of zero: count as grid.
        why = "account price unknown"
    return SourcePrice(grid_price_eur_kwh, GRID, f"{why}: the kWh comes from the grid")

def decide_heat_source(*, source: SourcePrice, cop: float | None,
                       gas_heat_eur_kwh: float | None,
                       fallback_blocked: bool = False) -> HeatDecision:
    """Block the heat pump only if its heat costs more than gas heat."""
    if source.source == SOLAR:
        return HeatDecision(False, source, 0.0, gas_heat_eur_kwh, True,
                            "solar surplus never blocks the heat pump")

    hp_heat = source.eur_kwh / cop if cop is not None and cop > 0 else None
    if hp_heat is None or gas_heat_eur_kwh is None:
        missing = "COP" if hp_heat is None else "gas heat price"
        return HeatDecision(fallback_blocked, source, hp_heat, gas_heat_eur_kwh, False,
                            f"{missing} missing: fallback decides")

    blocked = (hp_heat - gas_heat_eur_kwh) > TIE_TOLERANCE_EUR_KWH
    verdict = "gas is cheaper" if blocked else "heat pump is cheaper or equal"
    return HeatDecision(blocked, source, hp_heat, gas_heat_eur_kwh, True,
                        f"{verdict} ({source.source})")

python examples/episode1_walkthrough.py     # episode 1, step by step
python examples/meter_day.py            # a made-up day, booked from power readings
python -m pip install pytest            # only needed for the tests
python -m pytest                        # ends with: 49 passed

Start: empty battery                     0.0 kWh   0.00 EUR  -> no price per kWh
Sun puts in 10 kWh (0 ct)               10.0 kWh   0.00 EUR  -> 0.00 ct per kWh
Grid adds 5 kWh at 30 ct                15.0 kWh   1.50 EUR  -> 10.00 ct per kWh
House takes out 10 kWh                   5.0 kWh   0.50 EUR  -> 10.00 ct per kWh
Grid adds 5 kWh at 30 ct again          10.0 kWh   2.00 EUR  -> 20.00 ct per kWh

Winter, COP 3, gas heat 10.00 ct per kWh of heat
  Battery at 10 ct                     heat 3.33 ct vs gas 10.00 ct -> heat pump
  Battery refilled from grid at 42 ct  heat 14.00 ct vs gas 10.00 ct -> gas

Tipping point winter (COP 3.0): electricity above 30.00 ct makes gas cheaper
Tipping point mild weather (COP 5.9): electricity above 59.00 ct makes gas cheaper

def test_episode1_sun_and_grid_give_ten_cents():
    acc = BatteryAccount()
    acc.charge_solar(10)            # sun: 10 kWh for nothing
    acc.charge_grid(5, 0.30)        # grid: 5 kWh at 30 ct = 1.50 EUR
    assert acc.energy_kwh == pytest.approx(15)
    assert acc.cost_eur == pytest.approx(1.50)
    assert acc.price() == pytest.approx(0.10)