From 004ebcc9d0806334a00ce14464eb9c68f39baf41 Mon Sep 17 00:00:00 2001 From: FBumann <117816358+FBumann@users.noreply.github.com> Date: Mon, 20 Jul 2026 11:09:11 +0200 Subject: [PATCH] =?UTF-8?q?docs(v1):=20fix=20=C2=A711=20MultiIndex-level?= =?UTF-8?q?=20projection=20example;=20note=201.0=20doc=20graduation?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The §11 example used `expr.indexes["snapshot"].get_level_values("period")`, which cannot run under v1: v1 rejects a first-class `pd.MultiIndex` dimension at construction, so `snapshot` is a flat dim with `period`/`timestep` as aux coords and `.indexes["snapshot"]` is a flat index, not a MultiIndex. Replace it with the working aux-coord mapping (verified on the branch) and add a one-line note on the flat representation. Also record in open-items.md that convention.md graduates into the rendered Sphinx docs at the 1.0 reframe (add myst-parser, toctree, internal cross-refs); until then it stays a design-record linked by URL — the rules are permanent but the transitional framing would only be re-done, so rendering now is wasted. Co-Authored-By: Claude Opus 4.8 (1M context) --- arithmetics-design/convention.md | 15 +++++++++++---- arithmetics-design/open-items.md | 7 ++++++- 2 files changed, 17 insertions(+), 5 deletions(-) diff --git a/arithmetics-design/convention.md b/arithmetics-design/convention.md index 9d30dfa9c..3f4e84760 100644 --- a/arithmetics-design/convention.md +++ b/arithmetics-design/convention.md @@ -210,10 +210,17 @@ position). An operand whose *dimension* names one of those levels — a per-`period` weighting meeting a `snapshot`-indexed expression — is a same-name conflict between a dimension and an auxiliary coordinate, and it raises like any other conflict of this section. There is no implicit -projection; write it explicitly by selecting with the dimension's level -values: - - weights.sel(period=expr.indexes["snapshot"].get_level_values("period")) +projection. `snapshot` is a flat dimension carrying `period` and `timestep` +as auxiliary coordinates (v1 rejects a first-class `pd.MultiIndex` dimension, +so `expr.indexes["snapshot"]` is a flat index, not a `MultiIndex`). Map the +per-`period` input onto `snapshot` through that coordinate — a plain array +of one weight per position — then use it in the operation: + + # weights: pd.Series indexed by `period`; expr: indexed by `snapshot` + w = xr.DataArray( + weights.loc[expr.coords["period"].values].to_numpy(), dims="snapshot" + ) + weighted = expr * w # one constraint/term per snapshot, weighted by period An input that reconstructs the *entire* MultiIndex (all levels, every combination) is not a conflict — it is the same coordinate spelled diff --git a/arithmetics-design/open-items.md b/arithmetics-design/open-items.md index b3eb735bd..82b2dd1c9 100644 --- a/arithmetics-design/open-items.md +++ b/arithmetics-design/open-items.md @@ -61,7 +61,12 @@ here ([`goals.md`] step 1: *warn on legacy, raise on v1*). `grep "LEGACY: remove at 1.0"` marker. Dependency-ordered checklist in [`legacy-removal.md`]. - [ ] Reframe [`convention.md`] / [`goals.md`] — drop the "v1"/legacy framing - once there is only one convention. + once there is only one convention. At this point [`convention.md`] also + **graduates into the rendered Sphinx docs** (add `myst-parser`, into the + toctree, internal `:doc:` cross-refs replacing the GitHub blob links in + `doc/migrating-to-v1.rst` and `doc/release_notes.rst`). Until then it stays a + design-record linked by URL — the rules are permanent but the transitional + framing would only be re-done, so rendering now is wasted effort. ## Not blocking (follow-ups)