strategy: fill batteries early via an orthogonal battery_first option

[andig]

A levelled day used to sit on an empty battery. On reduce_grid_feedin-2.json (192 steps, attenuate_demand_peaks, flat 32.5 ct) the battery held its initial charge for 27 hours and first charged at step 17 — the none answer.

Reintroduces #125, which fixed the export side but was merged into perf/two-stage-solve rather than main, so it never applied here. This PR ports it, adds the import side, and then separates the two questions that were tangled in one enum.

Why it happened

prc_p_peak and prc_p_ramp bound how high the grid profile may go and how fast it may move. They say nothing about when the batteries fill, and on a flat tariff no price decides it either, so every schedule inside that envelope scores the same and the solver returns whichever it reaches first.

charging_strategy was answering two questions at once

• what to shape about the grid profile — the three attenuate_* values
• when to fill the batteries — charge_before_export

Sharing one enum meant the two could never be asked together: 5 of 8 combinations were reachable, and the peak strategies had to smuggle earliness in implicitly.

battery_first is now its own boolean, orthogonal to charging_strategy, and charge_before_export is removed — it was exactly no profile shaping plus that option, so it is spelled that way:

"strategy": {
  "charging_strategy": "attenuate_feedin_peaks",  // what to shape
  "battery_first": true,                          // when to fill
  "discharging_strategy": "discharge_before_import"
}

⚠️ Breaking. charge_before_export is gone from the enum; senders migrate to charging_strategy: "none" + battery_first: true. The 14 stored cases that used it are converted, and client.gen.go is regenerated.

Precedence: attenuation outranks battery_first

Filling sooner is not free on either side — a battery full by the first hour has no room left for the midday solar peak, and one filled at full power draws a taller import peak than one trickled. So where the two disagree, the profile the request asked to level is the one that survives:

early_unprotected = self.min_import_price * 2e-5 * self.T * len(self.batteries)
early_protected = self.penalty_base * 1e-7
self.prc_e_early = early_protected if 'exp' in self.peak_sides else early_unprotected
self.prc_n_early = early_protected if 'imp' in self.peak_sides else early_unprotected

charging_strategy	levels	feed-in peak	fills (with battery_first)
none	—	spent	full rate
attenuate_demand_peaks	import	spent	full rate
attenuate_feedin_peaks	feed-in	protected	at levelling's rate
attenuate_grid_peaks	both	protected	at levelling's rate

Verification

The refactor is provably exact. With the import-side term disabled, all 19 stored cases reproduce origin/main's charge_before_export schedules to 0.00 W. Getting there required preserving two artifacts of the old term, both now documented at the weight:

• its (T - t) coefficient, un-normalised
• its accidental multiplication by the battery count — the term sat inside for i, bat in enumerate(self.batteries) but never referenced i or bat, so a two-battery request weighted it twice. Preserved to keep this a pure refactor; it is a latent bug worth removing on its own, which will move those schedules.

Head to head (origin/main + charge_before_export vs this branch + none/battery_first), 6 of 19 cases move by up to 689 W — entirely from the import-side earliness added earlier in this series — with real money identical to 8 decimals.

Note on method: the stored responses for cases 009–023 are stale, and origin/main reproduces the same 7 deviations against them. Only 024–027 are strict; for the rest just status and objective_value are contractual, and objective_value strips preference terms, so it cannot see a tie-break shift. Comparisons here are head-to-head against main, not against the stored files.

Solve time does not regress — the risk was that combining earliness with levelling, previously unreachable, would compound the known tie-break cost:

charging_strategy	battery_first: false	true
none	0.25 s	0.18 s
attenuate_demand_peaks	0.23 s	0.21 s
attenuate_feedin_peaks	2.52 s	2.92 s
attenuate_grid_peaks	4.06 s	1.93 s

(reduce_grid_feedin-2, 192 steps; 020 at 154 steps is faster with the flag in all four rows.) The earliness gradient gives CBC something to prune instead of a flat plateau.

The default, and what it costs

battery_first defaults to false, so a request must now ask for the early charge:

reduce_grid_feedin-2	first charge	half charged
battery_first: false	step 17	27.5 h
battery_first: true	step 0	1.5 h

This means the reported symptom is only fixed once evcc sends the flag. Defaulting to true would fix it for everyone but also switch it on for charging_strategy: none, which does not fill early today. It is one constant either way — say which you want.

Separately, attenuate_feedin_peaks deliberately does not fill fast even with the flag: it keeps a 2936 W feed-in peak and reaches half charge at 3.1 h. Buying 1.1 h instead costs 22% of the peak the strategy exists to protect (3597 W), money unchanged. That is the precedence working as asked.

Tests

tests/test_early_charge.py, 13 tests — four steps of surplus for the export side, eight grid-only steps for the import side, eight mixed steps where the sides pull against each other, flat prices throughout.

• none + battery_first fills in the first two steps and exports the rest — what charge_before_export meant
• attenuate_feedin_peaks still flattens export to half the surplus; levelling keeps the last word
• grid-only attenuate_feedin_peaks fills immediately (fails with prc_n_early zeroed, verified)
• grid-only attenuate_demand_peaks keeps its flat import profile
• mixed: solar absorbed at once, the grid energy following it stays flat
• without the option, a peak strategy sits on the empty battery again — guards against it being implied
• the option combines with all four charging_strategy values
• the weight rule itself, parametrized over all three attenuation strategies
• both tie breaks cost neutral, via s0-insensitive economics

110 pass, 024–027 strict goldens unchanged, ruff check clean, go build ./client/... ./cmd/... clean.

Companion change: #125 reverted on perf/two-stage-solve (bff2e84) so the fix is not carried twice once that branch merges.

Side note, not fixed here

get_clean_objective_value() values the horizon as s[T-1] - s[0], but s[0] is the state after the first step, so energy charged in step 0 is dropped from the reported objective_value. Moving a charge into step 0 lowers the reported number while real money is unchanged — 6.2525 → 6.2126 on reduce_grid_feedin-2, against identical real money. The baseline should be s_initial.

🤖 Generated with Claude Code

[iseeberg79]

Like that approach. It's a missed detail. On same costs it's preferred to have the energy stored.

Imho it pairs perfectly with #62, not only as alternative. The battery operates between min/max SoC if cost neutral, buffering unplanned household consumption.