admin/goodwe-addon
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

TARIFF-17: a price component that varies by hour has somewhere to live
checks / unit (pull_request) Successful in 7m25s
Details

Browse Source 
`price.py` modelled the whole non-energy part of a Belgian bill as ONE flat
scalar. This adds `price_taxes_profile`, which carries the TAXES component as
a period table, and makes `assemble()` evaluate it at each point's own instant.

⚠️ THE FLAT SCALAR WAS NOT A WRONG NUMBER, AND THIS IS NOT A CORRECTION OF ONE.
The optimiser reads exactly two quantities off a series - the spread
`max - min` over the firm points, and which hour is cheapest - and an additive
constant identical in every hour cancels out of the first and leaves the second
where it was. It is provably inert. Measured, and printed by test_price.py 16b
on every run: with a flat taxes figure of 0.00, 0.0739, 0.1198, 0.1327 or 1.00
EUR/kWh the same 24-hour feed is cheapest at 13:00 in all five cases and its
spread is 0.1500 EUR/kWh in all five cases. What was missing is anywhere for an
HOUR-VARYING non-energy component to live. This is a missing capability, not a
bad constant.

Belgium has one. Fluvius distribution is a single rate - its tariff-card row
reads `Normaal | Uitsl. nacht`, where exclusive night is a separate physical
circuit and not a night register - so nothing changes for the reference site in
Flanders. The Walloon DSOs and Sibelga are on the same card with four columns,
`Enkelvoudig | Dag | Nacht | Uitsl. nacht`, and the gap is real money (c/kWh):
ORES 13,27 / 7,39; AIESH 15,17 / 8,21; Tecteo RESA 12,20 / 7,01; Sibelga
9,39 / 7,10; ORES IMPACT 2026 16,578 / 5,090.

⚠️ AND THE BANDS ARE ANTI-CORRELATED WITH WHAT THE BATTERY WANTS TO DO. The
cheap network hours are the cheap spot hours, so flattening them does not shift
the curve - it UNDERSTATES the spread and declines cycles that would have paid.
Same feed, same markup, the only difference being the taxes argument:

    flat 0.0000 / 0.0739 / 0.1198 / 0.1327 / 1.0000
                                       -> cheapest hour 13, spread 0.1500
    ORES dag 0.1327 / nacht 0.0739     -> cheapest hour 03, spread 0.1788

The regression check grades WHICH HOUR IS CHEAPEST, not the spread: an
implementation that reads the table once and adds one number to every point is
the LEVEL bucket wearing a period table - right magnitude, wrong shape - and a
spread assertion passes on it. Measured: hoisting the lookup out of
`assemble()`'s loop (+17 B) is red on six named checks in test_price.py and
GREEN in the other 28 files.

ONE GRAMMAR, NOT TWO. `static_tariff.py` already shipped the periods, the day
selectors, the tiling rule and the DST handling, so `parse_taxes_profile()` is
the same parser with the option name and the "what this number means" clause as
arguments. A second tiling rule would be a second set of 23- and 25-hour-day
bugs. test_static_tariff.py section 10 pins that two ways: by parsing every
module under `app/` and asserting the grammar is defined in exactly one of
them, and by deriving each of thirteen refusal sentences for the new option
from the old option's own sentence rather than transcribing them.

`Component.TAXES` semantics, `code_leaks()` and the double-counting guarantee
are untouched. The new key joins FRAMEWORK_KEYS, BANNED_IN_PLUGIN_CODE is
derived from that set, and a plugin that names it is refused at `register()`.
It reaches both plugins that take taxes - `custom_formula` ({ENERGY, MARKUP})
and `generic_dayahead` ({ENERGY}) - and not `manual_csv`, which is all-in: the
table is routed through `capabilities().adds`, exactly as the scalar is.

⚠️ A MALFORMED TABLE IS REFUSED AT STARTUP, NOT AT THE NEXT FETCH. It is read
on the ~30 s planning path, and a table that first fails at 03:00 is a site
that stops pricing at 03:00, which §11.4 turns into a quiet fallback
indistinguishable from a healthy fixed-tariff day. validate.py refuses three
things: a table that does not tile the day; a table set beside a NON-DEFAULT
`price_taxes_eur_kwh`, because the table wins and the scalar would then be a
number the operator typed that decides nothing; and a whole card typed in
CENTS, which is how these figures are printed. That last rung is not a
restatement of the parser's +-10 EUR/kWh bound - ORES's 13,27 trips the parser,
but Sibelga's entire card, 9,39 and 7,10, is under it and would otherwise have
started as a 9.39 EUR/kWh levy. Both rungs are graded by the REASON each gives,
and mutating them together (TEST-16) moves three rows.

NOTHING CHANGES FOR A SITE THAT DOES NOT SET IT. The option ships "", and the
scalar path is unchanged arithmetically rather than merely in intent:
test_price.py 16f reproduces the pre-TARIFF-17 expression and compares 12
capability/scalar combinations point for point with `==`.

13 mutations, every one red on a named check, ledger in test_price.py below
section 16k with byte deltas and the one equivalent mutant named. 29/29 green.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BwRLw7eKYj2byVdwB6kbjU
This commit is contained in:
glenn schrooyen
2026-09-13 15:31:15 +02:00
co-authored by Claude Opus 5
parent c518007caf
commit 2fac0aaf06
12 changed files with 1485 additions and 54 deletions
Download Patch File Download Diff File Expand all files Collapse all files
goodwe_controller/app/static_tariff.py
+117 -32
View File
@@ -222,6 +222,12 @@ _DAY_ALIASES = {
MINUTES_PER_DAY = 1440
# TARIFF-17. The option key whose value is a period table of the TAXES
# component. One spelling, here, because price.py, validate.py and config.yaml
# all name it and `provider_id()`'s note says what three spellings of one
# decision cost.
TAXES_PROFILE_OPTION = "price_taxes_profile"
# The mean that `cheap_now()` grades against is taken over this many local days.
# Seven, so each weekday appears exactly once - see the module docstring. It is
# a MODULE CONSTANT and not an option on purpose: CFG-03 already tracks three
@@ -320,13 +326,37 @@ def _days(value, field: str) -> frozenset:
return frozenset(out)
def _price(value, field: str) -> float:
"""The all-in EUR/kWh for a period, bounded exactly as price.py bounds a feed."""
# What a period's `eur_per_kwh` MEANS, per option. The grammar is one grammar
# (TARIFF-17); the quantity it carries is not, so the "you left this out"
# sentence is the one thing the two tables do not share.
_PERIOD_MEANS = {
"static_profile":
"an all-in eur_per_kwh (energy + supplier markup + taxes, §9.3) - the "
"same basis the dynamic providers are assembled onto, so the two are "
"comparable",
}
_TAXES_MEANS = (
"the TAXES component alone in eur_per_kwh - the non-energy part of the "
"bill for that band (distribution, levies, VAT), NOT an all-in price. The "
"framework adds it to what the feed publishes, exactly as the scalar "
"price_taxes_eur_kwh is added"
)
_PERIOD_MEANS[TAXES_PROFILE_OPTION] = _TAXES_MEANS
def _price(value, field: str, means: str = None) -> float:
"""One period's EUR/kWh, bounded exactly as price.py bounds a feed.
`means` names the quantity for the error sentence only. TARIFF-17: the same
grammar carries an ALL-IN price under `static_profile` and a TAXES-ONLY
component under `price_taxes_profile`, and an operator who confuses the two
is out by an energy price - so the refusal says which one is wanted.
"""
if means is None:
means = _PERIOD_MEANS["static_profile"]
if value is None:
raise ProfileInvalid(
f"{field} is missing. Every period needs an all-in eur_per_kwh "
f"(energy + supplier markup + taxes, §9.3) - the same basis the "
f"dynamic providers are assembled onto, so the two are comparable.")
f"{field} is missing. Every period needs {means}.")
if isinstance(value, bool) or not isinstance(value, (int, float, str)):
raise ProfileInvalid(f"{field} is {value!r}, which is not a number")
try:
@@ -383,14 +413,19 @@ class Period:
class StaticProfile:
"""A validated two-or-more-period tariff. Immutable, pure, I/O-free."""
def __init__(self, periods):
def __init__(self, periods, *, option: str = "static_profile"):
self.periods = tuple(periods)
# ⚠️ TARIFF-17: the OPTION NAME travels with the profile so that every
# refusal names the key the operator actually typed. It is a default
# argument on purpose - every pre-existing call site and every
# pre-existing sentence is byte-identical without it.
self.option = option
if not self.periods:
raise ProfileInvalid(
"static_profile has no periods. A profile with no periods is "
"not a fixed tariff, it is an absent one - leave the option "
"empty to say that on purpose (§11.4 then applies).")
_check_tiling(self.periods)
f"{option} has no periods. A profile with no periods is "
f"not a fixed tariff, it is an absent one - leave the option "
f"empty to say that on purpose (§11.4 then applies).")
_check_tiling(self.periods, option=option)
# -- what kind of tariff this is, DERIVED --------------------------------
@property
@@ -477,7 +512,7 @@ class StaticProfile:
u += timedelta(hours=1)
if not out:
raise ProfileInvalid(
f"static_profile.series({since.isoformat()}, "
f"{self.option}.series({since.isoformat()}, "
f"{until.isoformat()}) spans no whole hour. An empty series is "
f"not constructible downstream on purpose (price.py trap 3).")
return out
@@ -489,7 +524,7 @@ class StaticProfile:
return f"{kind}: " + "; ".join(p.words for p in self.periods)
def _check_tiling(periods) -> None:
def _check_tiling(periods, *, option: str = "static_profile") -> None:
"""Every day type must be covered by EXACTLY ONE period, every minute.
⚠️ REFUSES BOTH DIRECTIONS. A gap means an hour with no price, and the only
@@ -506,22 +541,22 @@ def _check_tiling(periods) -> None:
if n > 1 and over_from is None:
over_from = (minute, n)
if n != 0 and gap_from is not None:
_raise_gap(weekday, gap_from, minute)
_raise_gap(weekday, gap_from, minute, option)
if n <= 1 and over_from is not None:
_raise_overlap(weekday, over_from, minute, periods)
_raise_overlap(weekday, over_from, minute, periods, option)
if gap_from is not None:
_raise_gap(weekday, gap_from, MINUTES_PER_DAY)
_raise_gap(weekday, gap_from, MINUTES_PER_DAY, option)
if over_from is not None:
_raise_overlap(weekday, over_from, MINUTES_PER_DAY, periods)
_raise_overlap(weekday, over_from, MINUTES_PER_DAY, periods, option)
def _hhmm(m):
return f"{m // 60:02d}:{m % 60:02d}"
def _raise_gap(weekday, start, end):
def _raise_gap(weekday, start, end, option="static_profile"):
raise ProfileInvalid(
f"static_profile leaves {DAY_NAMES[weekday]} "
f"{option} leaves {DAY_NAMES[weekday]} "
f"{_hhmm(start)}-{_hhmm(end)} with no period, so those hours have no "
f"price. Refused rather than defaulted: an invented price is one an "
f"optimiser would trade on, and §11.4 already says what a missing price "
@@ -529,19 +564,28 @@ def _raise_gap(weekday, start, end):
f"\"22:00-07:00 mon-fri\" does NOT cover Saturday morning.")
def _raise_overlap(weekday, over, end, periods):
def _raise_overlap(weekday, over, end, periods, option="static_profile"):
start, n = over
names = [p.name for p in periods if p.covers(weekday, start)]
raise ProfileInvalid(
f"static_profile gives {DAY_NAMES[weekday]} {_hhmm(start)}-"
f"{option} gives {DAY_NAMES[weekday]} {_hhmm(start)}-"
f"{_hhmm(end)} {n} prices at once ({', '.join(names)}). Two prices for "
f"one hour means one of them silently wins on list order. Narrow one of "
f"the windows or split the day selector.")
def parse_static_profile(value):
def parse_static_profile(value, *, option: str = "static_profile",
means: str = None):
"""`static_profile` -> a `StaticProfile`, or None when unset.
⚠️ TARIFF-17 MADE `option`/`means` PARAMETERS RATHER THAN FORKING THIS
FUNCTION, and that is the whole of the reuse. A second period parser would
be a second tiling rule, a second day-type rule and a second set of DST
bugs, diverging first on the 23- and 25-hour days where nobody looks. The
two arguments move only the OPTION NAME and the "what this number is"
clause through the refusals; the grammar, the tiling check and the wrapping
rule are one implementation with one set of checks over it.
Accepts what the option can actually arrive as:
* `None` / `""` / `"null"` - unset. §14 ships `static_profile: null`.
* a JSON string - what config.yaml's flat `str?` option
@@ -555,6 +599,8 @@ def parse_static_profile(value):
"""
if value is None:
return None
if means is None:
means = _PERIOD_MEANS.get(option, _PERIOD_MEANS["static_profile"])
if isinstance(value, str):
text = value.strip()
if not text or text.lower() in ("null", "none", "off"):
@@ -563,7 +609,7 @@ def parse_static_profile(value):
value = json.loads(text)
except ValueError as e:
raise ProfileInvalid(
f"static_profile is not valid JSON ({e}). It is a JSON object "
f"{option} is not valid JSON ({e}). It is a JSON object "
f"with a \"periods\" list, on one line, e.g.\n"
f' {{"periods": [{{"name":"day","from":"07:00","to":"22:00",'
f'"days":"mon-fri","eur_per_kwh":0.34}}, ...]}}\n'
@@ -573,7 +619,7 @@ def parse_static_profile(value):
tz = str(value.get("timezone", "") or "").strip().lower()
if tz not in SUPPORTED_TZ:
raise ProfileInvalid(
f"static_profile.timezone is {value.get('timezone')!r}. Only "
f"{option}.timezone is {value.get('timezone')!r}. Only "
f"Europe/Brussels is supported: the shipped image carries no tz "
f"database (see app/price.py), so any other zone could not be "
f"honoured and would be silently treated as Brussels - which is "
@@ -581,24 +627,24 @@ def parse_static_profile(value):
rows = value.get("periods")
if rows is None:
raise ProfileInvalid(
"static_profile has no \"periods\" list. Even a fully-fixed "
"tariff is written as one period covering 00:00-24:00 all days "
"- one shape for both products, so nothing downstream branches "
"on which kind of site this is.")
f"{option} has no \"periods\" list. Even a fully-fixed "
f"tariff is written as one period covering 00:00-24:00 all days "
f"- one shape for both products, so nothing downstream branches "
f"on which kind of site this is.")
else:
rows = value
if not isinstance(rows, (list, tuple)):
raise ProfileInvalid(
f"static_profile.periods is {type(rows).__name__}, not a list")
f"{option}.periods is {type(rows).__name__}, not a list")
periods = []
for i, row in enumerate(rows, start=1):
if not isinstance(row, dict):
raise ProfileInvalid(
f"static_profile.periods[{i}] is {type(row).__name__}, not an "
f"{option}.periods[{i}] is {type(row).__name__}, not an "
f"object with from/to/days/eur_per_kwh")
where = f"static_profile.periods[{i}]"
where = f"{option}.periods[{i}]"
name = str(row.get("name", "") or f"period{i}").strip() or f"period{i}"
start = _minutes(row.get("from", row.get("start")), f"{where}.from")
end = _minutes(row.get("to", row.get("end")), f"{where}.to")
@@ -617,8 +663,47 @@ def parse_static_profile(value):
end_min=end,
days=_days(row.get("days"), f"{where}.days"),
eur_per_kwh=_price(row.get("eur_per_kwh"),
f"{where}.eur_per_kwh")))
return StaticProfile(periods)
f"{where}.eur_per_kwh",
means)))
return StaticProfile(periods, option=option)
def parse_taxes_profile(value):
"""`price_taxes_profile` -> a `StaticProfile` of TAX values, or None.
TARIFF-17. THE DEFECT THIS EXISTS TO CLOSE: `price.py` modelled the whole
non-energy part of a Belgian bill as ONE scalar. In Flanders that is
correct - Fluvius distribution is a single rate and its tariff card offers
only `Normaal | Uitsl. nacht`, where *exclusive night* is a separate
physical circuit rather than a night register. The Walloon and Brussels
DSOs are on the same card with four columns - `Enkelvoudig | Dag | Nacht |
Uitsl. nacht` - and the day/night gap is real money:
ORES dag 13,27 nacht 7,39 -> 5,88 c EUR/kWh
AIESH dag 15,17 nacht 8,21 -> 6,96
Tecteo RESA dag 12,20 nacht 7,01 -> 5,19
Sibelga (BXL) dag 9,39 nacht 7,10 -> 2,29
ORES IMPACT dag 16,578 nacht 5,090 -> 11,49 (2026)
⚠️ AND THE BANDS ARE ANTI-CORRELATED WITH WHAT THE BATTERY WANTS TO DO.
The cheap network hours are the cheap spot hours, so flattening them does
not merely shift the curve - it SYSTEMATICALLY UNDERSTATES the true spread
and makes the add-on decline cycles that are genuinely profitable. See
DOCS.md "The three buckets" for why the flat scalar could never have done
this: an additive constant, identical every hour, cancels exactly in
`max - min` and cannot move `min(firm, key=...)` either.
⚠️ THE VALUE IS THE TAXES COMPONENT, NOT AN ALL-IN PRICE. `static_profile`
uses the same grammar for an all-in figure; the two are one parser and two
meanings, and `_price()`'s refusal names which one it wanted.
⚠️ NOT PARSED ON THE FETCH PATH. validate.py refuses a malformed table at
STARTUP, by the rule `price.py` trap 3 states for `static_profile`: a table
that cannot be parsed at 03:00 is a site that stops pricing at 03:00, and
§11.4 makes that quiet.
"""
return parse_static_profile(value, option=TAXES_PROFILE_OPTION,
means=_TAXES_MEANS)
# --------------------------------------------------------------------------- #