Grid charging: when and how much

def simulate(start_pct: float, hours: list[Hour], charged_pp: list[float] | None = None,
             floor_pct: float = 20.0, top_pct: float = 100.0) -> Run:
    """Battery level for every hour, with the grid charging in charged_pp (points per hour)."""
    if not floor_pct <= start_pct <= top_pct:
        start_pct = min(max(start_pct, floor_pct), top_pct)
    if charged_pp is not None and len(charged_pp) != len(hours):
        raise ValueError("charged_pp needs one value per hour")
    run = Run(start_pct=start_pct)
    level = raw = start_pct
    for h, hour in enumerate(hours):
        change = hour.net_pp() + (charged_pp[h] if charged_pp else 0.0)
        new = level + change
        spilled = max(0.0, new - top_pct)
        new = min(new, top_pct)
        at_floor = max(0.0, floor_pct - new)
        level = max(new, floor_pct)
        raw = min(raw + change, top_pct)        # no floor here, only the top
        run.levels.append(level)
        run.raw.append(raw)
        run.at_floor_pp.append(at_floor)
        run.spilled_pp.append(spilled)
    return run

def mark_pct(hour: int, settings: MarkSettings = MarkSettings(), last_priced_hour: int = -1) -> float:
    """The mark for hour h (0 = the hour starting now).

    last_priced_hour: the last hour with a known price. Up to there, the plain
    mark applies (floor + buffer), whatever the hour.
    """
    mark = settings.floor_pct + settings.buffer_pts
    if hour >= settings.step_from_hour and hour > last_priced_hour:
        days = 1 + (hour - settings.step_from_hour) // 24
        mark += days * settings.step_pts_per_day
    return mark


def first_gap(levels: list[float], marks: list[float], first: int = 0, last: int | None = None,
              tolerance_pp: float = 0.02) -> int | None:
    """First hour (index) whose end level is below its mark, or None."""
    last = len(levels) - 1 if last is None else min(last, len(levels) - 1)
    for h in range(first, last + 1):
        if levels[h] < marks[h] - tolerance_pp:
            return h
    return None


def gap_pp(raw: list[float], marks: list[float], last: int) -> float:
    """How many points are missing up to hour `last`: the deepest dip below the mark,
    measured without the floor (so a stretch at the floor still counts)."""
    if last < 0:
        return 0.0
    return max(0.0, max(marks[h] - raw[h] for h in range(min(last, len(raw) - 1) + 1)))

def make_plan(start_pct: float, hours: list[Hour], prices_ct: list[float | None],
              settings: PlanSettings = PlanSettings(), clock: Clock = Clock()) -> Plan:
    """The charging plan for the coming hours.

    start_pct  battery level now, from a trusted reading (no fresh reading: no plan)
    hours      forecast per hour, usually 168 (seven days)
    prices_ct  price per quarter hour from now, None where not known yet
    clock      start of hour 0 (weekday, clock hour): for the full hour and for labels
    """
    n = len(hours)
    if n == 0:
        raise ValueError("no hours")
    if len(prices_ct) > 4 * n:
        raise ValueError("more prices than quarter hours")
    s = settings
    floor = s.mark.floor_pct
    prices = list(prices_ct) + [None] * (4 * n - len(prices_ct))
    priced = [q for q, p in enumerate(prices) if p is not None]
    last_priced = priced[-1] // 4 if priced else -1
    known_mean = sum(prices[q] for q in priced) / len(priced) if priced else None
    marks = [mark_pct(h, s.mark, last_priced) for h in range(n)]
    charge = [0.0] * (4 * n)
    purchases: list[Purchase] = []
    rejected: set[int] = set()

    def simulate_now() -> Run:
        per_hour = [sum(charge[4 * h:4 * h + 4]) for h in range(n)]
        return simulate(start_pct, hours, per_hour, floor, s.top_pct)

    def allowed(q: int) -> bool:
        hour = hours[q // 4]
        if prices[q] is None or charge[q] > 0 or q in rejected:
            return False
        if hour.solar_pp is None:                                   # no solar forecast: never buy
            return False
        if s.full_hour is not None and (clock.hour + q // 4) % 24 == s.full_hour:
            return False                                            # the daily full hour is for the sun
        if hour.solar_pp >= hour.demand_pp:                         # the sun already covers the house
            return False
        use_per_quarter = (hour.demand_pp + hour.losses_pp - hour.solar_pp) / 4
        if s.charge_pp_per_quarter <= use_per_quarter:              # would not raise the level
            return False
        return True

    def within_cap(run: Run, new_q: int) -> bool:
        """No grid charge may end above max_target_pct (zero-price charges excepted)."""
        qs = [p.quarter for p in purchases if p.kind != ZERO] + [new_q]
        return all(quarter_level(run, hours, charge, q) <= s.max_target_pct + 1e-9 for q in qs)

    def buy_best(until_hour: int, price_ok, missing) -> tuple[int, Run] | None:
        """Cheapest allowed quarter hour up to and including until_hour that really helps.
        On equal prices the earlier one wins."""
        before = missing(simulate_now())
        candidates = sorted((prices[q], q) for q in range(4 * (until_hour + 1))
                            if allowed(q) and price_ok(prices[q]))
        for _, q in candidates:
            charge[q] = s.charge_pp_per_quarter
            trial = simulate_now()
            if within_cap(trial, q) and before - missing(trial) >= s.min_effect * s.charge_pp_per_quarter:
                return q, trial
            charge[q] = 0.0
            rejected.add(q)                                         # never effective, never again
        return None

    without = simulate_now()
    run = without
    # 1  zero price: always charge, up to 100 %, without the other rules
    for q in priced:
        if prices[q] <= 0 and quarter_level(run, hours, charge, q) < s.top_pct - s.tolerance_pp:
            charge[q] = s.charge_pp_per_quarter
            purchases.append(Purchase(q, prices[q], ZERO, len(purchases) + 1, None))
            run = simulate_now()
    first = first_gap(without.levels, marks, 0, None, s.tolerance_pp)
    gap = gap_pp(without.raw, marks, last_priced)

    # 2  need: gaps inside the known prices, any price
    def missing_inside(r: Run) -> float:
        return gap_pp(r.raw, marks, last_priced)

    while True:
        e = first_gap(run.levels, marks, 0, last_priced, s.tolerance_pp)
        if e is None:
            break
        found = buy_best(e, lambda price: True, missing_inside)
        if found is None:
            break
        q, run = found
        purchases.append(Purchase(q, prices[q], NEED, len(purchases) + 1, e))

    # 3  reserve: gaps behind the known prices, within reserve_days, clearly cheap only
    def clearly_cheap(price: float) -> bool:
        if price > s.reserve_max_ct or known_mean is None or price > known_mean:
            return False
        return s.reserve_percentile_ct is None or price <= s.reserve_percentile_ct

    reserve_last = min(n - 1, 24 * s.reserve_days - 1)

    def missing_reserve(r: Run) -> float:
        return gap_pp(r.raw, marks, reserve_last)

    if first_gap(run.levels, marks, 0, last_priced, s.tolerance_pp) is None:
        while True:
            e = first_gap(run.levels, marks, last_priced + 1, reserve_last, s.tolerance_pp)
            if e is None:
                break
            found = buy_best(min(e, last_priced), clearly_cheap, missing_reserve)
            if found is None:
                break
            q, run = found
            purchases.append(Purchase(q, prices[q], RESERVE, len(purchases) + 1, e))

    # 4  rest
    r = first_gap(run.levels, marks, 0, None, s.tolerance_pp)
    rest = NOTHING_MISSING if r is None else (NOT_COVERABLE if r <= last_priced else WAITS_FOR_PRICES)
    return Plan(purchases=purchases, without=without, with_plan=run, marks=marks, last_priced_hour=last_priced,
                first_gap_hour=first, gap_pp=gap, rest=rest, rest_hour=r, known_mean_ct=known_mean,
                charge_pp=charge)

python examples/example_week.py      # the example week, step by step
python -m pip install pytest         # only needed for the tests
python -m pytest                     # ends with: 31 passed

Start Tue 15:00: battery 52.0 %, prices known until Thu 00:00
Known prices average 31.8 ct

Step 1 - the line without buying
  first below the mark: Wed 07:00 (29.13 %)
  on the floor from:    Wed 17:00

Step 2 - the gap up to the last known price
  22.49 points

Step 3 - the cheapest quarter hours within reach, one at a time
   1. Wed 01:00  21.5 ct  need    for the gap at Wed 07:00
   2. Wed 03:00  21.5 ct  need    for the gap at Wed 08:00
   3. Wed 02:30  21.7 ct  need    for the gap at Wed 08:00
  ...
  17. Wed 05:00  25.0 ct  need    for the gap at Wed 20:00
  18. Wed 05:45  25.3 ct  need    for the gap at Wed 21:00
  19. Wed 00:30  25.7 ct  need    for the gap at Wed 21:00
  20. Wed 05:15  25.7 ct  need    for the gap at Wed 22:00
  21. Wed 22:30  21.2 ct  need    for the gap at Wed 23:00
  22. Wed 22:00  21.5 ct  need    for the gap at Wed 23:00
  23. Wed 23:00  21.0 ct  need    for the gap at Thu 00:00
  24. Wed 23:45  21.3 ct  reserve for the gap at Thu 01:00
  25. Wed 23:15  21.7 ct  reserve for the gap at Thu 02:00
  26. Wed 22:15  21.9 ct  reserve for the gap at Thu 03:00
  27. Wed 22:45  22.2 ct  reserve for the gap at Thu 04:00
  28. Wed 23:30  22.4 ct  reserve for the gap at Thu 04:00

Result
  need     23 quarter hours, 23.0 points, average 22.60 ct
  reserve   5 quarter hours,  5.0 points, average 21.90 ct
  all      28 quarter hours, 28.0 points, average 22.47 ct
  with the plan: low 30.17 %, high 50.37 % (inside the known prices)
  rest: waits_for_prices from Thu 05:00

Charging blocks (charge up to ..., stop at ...)
  Wed 00:30 - 00:45: charge up to 37.1 %
  Wed 01:00 - 05:30: charge up to 49.9 %
  Wed 05:45 - 06:00: charge up to 50.4 %
  Wed 22:00 - 00:00: charge up to 35.5 %

def test_twenty_three_plus_five_quarter_hours(week):
    _, plan = week
    assert len(plan.chosen(NEED)) == 23
    assert len(plan.chosen(RESERVE)) == 5
    assert plan.bought_pp() == pytest.approx(28.0)