Skip to content

feat(language)!: a dimension lists its members, strictly - #9

Draft
FBumann wants to merge 17 commits into
feat/dimension-aliasfrom
compare/tuple-strict
Draft

FBumann wants to merge 17 commits into
feat/dimension-aliasfrom
compare/tuple-strict

Conversation

@FBumann

@FBumann FBumann commented Nov 17, 2026 •

Copy link
Copy Markdown

Prompt: We should do a PR like that on mathspec fluxopt

Prompt (follow-ups, relayed from the parent session): We can remove relations right away in both · Lets do it like that! · (confirmed: relations go from the language, not only the examples) Yes · It should get cascaded into the fork PRs!!

Note

The following content was generated by AI.

The strict tuple dimension of energy-models#1011: opaque, at() required, every rule a refusal. Loosening it later only removes refusals; no spec that loads changes meaning.

  • The file has no relations: section. A set of combinations of labels is a dimension with over:. The closed schema refuses relations: as an unknown key.
  • maps: is mappings:, from the base (energy-models/mathspec feat/dimension-alias at 06e52956), applied to this PR's own code too.

A relation becomes a tuple dimension:

# before (feat/dimension-alias)
relations:
  connection: { dims: [unit, port], missing: absent }
  ts_map: { dims: { region: region, s: timeslice, ts: timeslice }, missing: absent }

# after (this PR)
dimensions:
  connection: { over: [unit, port] }
  upper_timeslice: { alias: timeslice }
  ts_map: { over: [region, upper_timeslice, timeslice] }

examples/sparse.yaml, before (feat/dimension-alias):

relations:
  connection: { dims: [unit, port], missing: absent }
  active: { dims: [unit, period], missing: absent }
mappings:
  connection:
    bus: { dim: bus }
parameters:
  efficiency: { dims: [unit, port, period], where: connection, missing: 1 }
variables:
  output: { dims: [unit, period], where: active }
  flow: { dims: [unit, port, period], where: connection }
constraints:
  port_limit: { dims: [unit, port, period], expression: flow <= capacity }
  split: { dims: [unit, period], expression: "sum(flow, over=port) == output" }
  balance: { dims: [bus, period], expression: "sum(efficiency * flow, over=[unit, port], by=connection[bus]) >= load" }

After (this PR, loads with to_spec):

dimensions:
  connection: { over: [unit, port] }
  active: { over: [unit, period] }
mappings:
  connection:
    bus: { dim: bus }
parameters:
  efficiency: { dims: [connection, period], missing: 1 }
variables:
  output: { dims: [unit, period], where: active }
  flow: { dims: [connection, period] }
constraints:
  port_limit: { dims: [connection, period], expression: "flow <= at(capacity, by=connection[unit])" }
  split: { dims: [unit, period], expression: "sum(flow, over=connection, by=connection[unit]) == output" }
  balance: { dims: [bus, period], expression: "sum(efficiency * flow, over=connection, by=connection[bus]) >= load" }

TIMES (examples/times/):

act:     { dims: [region, vintage, period, process, timeslice], where: "prc_ts AND rtp_vintyr" }
ire_flo: { dims: [top_ire] }

(before: act with where: rtp_vintyr AND prc_ts over two relations; ire_flo over the five dims with where: top_ire.)

Draft, for comparison, not for merge. Siblings: #7 (Confine), #8 (multi-dims as members).

The border

A tuple used whole is allowed. Reaching inside it without at() is refused, and each message names the spelled-out form.

  • Allowed: a tuple in dims:; over=<tuple>; its bare name as a condition on an entry over every member; mappings keyed by it, read as connection[bus].
  • The only way inside: at(…, by=connection[member]).
Refused in #9 Spelled out in #9 (the message names it) What #8 writes
a member operand meets the tuple flow <= at(capacity, by=connection[unit]) flow <= capacity
over=<member> on an operand over the tuple sum(flow, over=connection, by=connection[unit]) sum(flow, over=port)
two tuples share a member in one dims: dims: [connection, bus], where: "at(site, by=connection[unit])", or an alias dims: [connection, site], joined on unit
shift, sum_back, position along a member of an entry over the tuple dims: [period, unit], where: active, then shift(output, along=period, offset=1) dims: [active] with the same shift

Rules of energy-models#1011 → refusal or meaning

# Rule Here When loosened
1 over: makes the label a tuple; one dimension in every operator meaning kept: the flat reading is the same set of tuples
2 each member is a mapping dim[member], missing: refused meaning kept: at(x, by=connection[unit]) is what alignment by name would compute
3 a declared mapping named after a member refusal —
4 an operand over a member meets the tuple (flow <= capacity) refusal could mean at(capacity, by=connection[unit])
5 sum(flow, over=unit) on an operand over the tuple refusal could mean sum(…, over=connection, by=connection[port])
6 a dimension twice in over: refusal (alias) —
7 a member with members of its own refusal could flatten
8 ordered, dtype, one_of beside over: refusal —
9 an order along the tuple, or along a member of an entry over it refusal; the rewrite is an entry over the members with where: <tuple> could step along the member
10 the tuple compared with a label refusal —
11 a member shared in one dims: (two tuples, or a tuple and its member) was a meaning (cross product), now a refusal could mean a join on the member
12 a call through a member on an operand over the tuple and that member refusal (now unreachable, see below) —
— the bare name in a condition was a refusal, now a meaning on an entry over every member; refusal elsewhere kept: a membership test, no alignment
— missing: absent / refused meaning kept
— the order of the members changes nothing meaning kept
— sos type 1 along the tuple meaning kept: it reads no order
Method, gate output, what was not done

Method

  • Branch = upstream feat/maps-tuple-dimensions (16f558c) + merge of the fork's feat/dimension-alias (96c1002). Conflicts in the TIMES trade example and its page: took the base's process member, kept top_ire a dimension, rewrote the prose, regenerated.
  • Shared members: _validation._shared_members, on every frame and on piecewise: dims:. Test first: test_a_member_shared_by_two_dimensions_of_one_frame_is_refused failed on the merged tree; test_the_rewrite_of_a_shared_member_loads holds the message to a rewrite that loads.
  • Bare name: resolved to RelationDefined(<tuple>, <member dims>); the frame check refuses it where a member is missing. Tests first, watched failing. Typesetting printed (a) ∈ active; test_a_membership_test_prints_the_member_indices failed in all three formats and passes now.
  • Border check: shift, sum_back and position along a member of an entry over the tuple were refused without the flat form. test_a_step_along_a_member_of_an_entry_over_the_tuple_names_the_flat_entry failed for all three, and passes with _dimensions._step_member.
  • Removing relations:. RelationSpec, Spec.relations, the relation validators, the 'relation' name kind and its branches, and the relation sections of merge, override, rename and the PyPSA splitter are gone. Program.relations stays as the internal table of each subject with mappings or members. test_a_relations_section_is_refused_by_the_schema is the one test of the refusal. check counted a tuple named only in a where: as never used; test_a_member_does_not_count_as_a_use[a-where-tests-the-dimension] failed first, and passes now.
  • Where the relation tests went. 4340 → 4266 tests.
    • The tests of a relation's join on its key columns (test_dimensions.py, test_validation.py, test_piecewise.py walks into a relation) are deleted with the construct. The tuple's reads through its members and the refusals with their at() rewrites are in tests/test_tuple_dimensions.py.
    • The relation's schema, name and missing: rules are deleted. A tuple's missing: is in test_missing_says_whether_the_full_product_is_required, and fragments disagreeing on it in test_two_fragments_that_say_different_things_about_one_entry_are_refused.
    • Converted to tuples: the golden model, the typesetting UNREAD fixture, the fluxopt investment curve (INVESTED), the lowering of a join (test_a_tuple_lowers_with_the_join_each_call_names), the renaming class, the composition WIRED fixture, the spec-mutation probes, the parameter-mask fixtures.
  • The mappings: merge. feat/dimension-alias at 06e52956, fetched from upstream because the fork's branch was still at 96c1002. 56 files conflicted. In each conflict this branch's side was taken, and the hunks git merged cleanly kept the base's rename. Then the rename was applied to every line that differs from the base: MappingSpec, Spec.mappings, mappings:, subject[mapping], and "mapping" in messages, docstrings, tests and pages. The verb, Python's Mapping, the maths map(t) and "linear maps" stay. The page maps.md is mappings.md.
  • Examples: sparse, connection, both operators/sum_by_*, times/capacity, pypsa and its split fragments; no example has relations:.
  • Docs: the relations page is now mappings.md (Mappings), with every link re-pointed. The pages updated: dimensions.md, expressions.md, parameters-variables-constraints.md, absence.md, file.md, operators.md, composition.md, reading.md, glossary.md, the how-to, limits.md (a row for the removed section), sql-and-dataframes.md, the PyPSA reference README, and "Mappings as linear maps". Figures with the old spelling are updated, and generated files regenerated.

Gate (no pixi here; uv venv with the pinned tools, on b8a42448)

  • lint pieces: ruff check, ruff format --check, pyrefly check (0 errors), prettier --check, typos, reuse lint, git diff --check. All pass. Not run: taplo, zizmor, lefthook itself.
  • pytest -q -n auto: 4266 passed, 3 skipped.
  • python -m zensical build --strict: no issues.
  • python -m tools.render_tex: 62 specs rendered.
  • compile-tex: not run. tectonic is not installed here.

Not done

  • The fork's base branch feat/dimension-alias is still at 96c1002. Until it is fast-forwarded to 06e52956, this diff also shows the base's rename.
  • The frame exception in check_meeting and the guard of rule 12 can no longer be reached. Left in place.
  • A sum over a tuple grouped by all of its members loads, though each group is one tuple; the relation's "groups are the whole key" refusal has no tuple counterpart yet.
  • The restack of feat(language): a dimension's members are read by name #8 onto this branch is not done here: it changes compare/multi-dims, which this session's brief kept out of reach.
  • Multi-dimensions as explicit tuple indexes energy-models/mathspec#1011's body could not be read from this session. Rule numbers 9 and 11 come from the commits and tests that cite them.
  • Nothing posted on energy-models/mathspec.

🤖 Generated with Claude Code

https://claude.ai/code/session_018B3nA494URRSeWy6wmELGP

claude and others added 9 commits November 16, 2026 16:32
Ports energy-models#1014 alone onto energy-models#1015's maps, without energy-models#1012 or energy-models#1013. A dimension
takes `over:` and `missing:`; each member is an implied map of the
dimension, read as `connection[unit]`, beside the maps the file declares
under `maps: connection:`. A declared map named after a member is
refused. A bound over a member suggests a constraint through `at`, since
a bound does not read through a map here.

Co-Authored-By: Fabian Hofmann <fab.hof@gmx.de>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018B3nA1xxh6NMJN6mrYY34Q
With the alias underneath, a dimension's members are a list of
dimensions, each once. The role form (`over: {from: region, to:
region}`) is gone: a tuple that holds one dimension twice lists an alias
of it as a member, and `over: [region, region]` is refused with the alias
as the rewrite. The two branches that only roles reached are removed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018B3nA1xxh6NMJN6mrYY34Q
The TIMES trade example in this PR's spelling: top_ire is a dimension
over the two aliases and the two plain dimensions, and ire_flo,
trade_cost and export are over it. capacity.yaml keeps its relations:
rtp_vintyr has an ordered member, which a tuple dimension cannot step
along.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018B3nA1xxh6NMJN6mrYY34Q
sparse.yaml in this PR's spelling: connection is a dimension over unit
and port, capacity is read through at(), the sum per unit groups by the
member, and active stays a relation because ramp_up steps along its
ordered member.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018B3nA1xxh6NMJN6mrYY34Q
The TIMES trade example in this spelling: top_ire is a dimension over
the two aliases, the two plain dimensions and process, and ire_flo,
trade_cost and export are over it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018B3nA494URRSeWy6wmELGP
…used

A dims: list reaches each member once. Two dimensions that share a
member, or a dimension beside one of its own members, are refused at
load, in place of the cross product they meant. The message names the
shared member and the rewrite: one of the two with a where: through a
relation, or an alias. The same holds for a piecewise entry's dims:.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018B3nA494URRSeWy6wmELGP
@coderabbitai

coderabbitai Bot commented Nov 17, 2026

Copy link
Copy Markdown

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

  • Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018B3nA494URRSeWy6wmELGP
On an entry over every member, as plain dimensions, the bare name of a
dimension with members keeps the coordinates whose member tuple it
lists. It aligns nothing by name. An entry missing a member is refused
with the frame rewrite. It prints as the tuple of the member indices.
The shared-member and order refusals name the bare name as their
rewrite.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018B3nA494URRSeWy6wmELGP
No example has relations: any more. Each relation becomes a dimension
over its members, with an alias where it held one dimension twice
(ts_map, the PyPSA maintenance covers). Sums and lookups read through
the members with at(); act is confined with where: "prc_ts AND
rtp_vintyr".

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018B3nA494URRSeWy6wmELGP
shift, sum_back and position along a member of an entry over the tuple
were refused without a rewrite, or with an at() that does not apply.
The message now names the entry over the members, confined with
where: <tuple>. The data contract leaves the storage of a tuple to the
tool.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018B3nA494URRSeWy6wmELGP
`maps:` is renamed to `mappings:`, `MapSpec` to `MappingSpec` and
`Spec.maps` to `Spec.mappings`. Messages, docstrings, the reference, the
examples and the figures say "mapping", and a read is written
`subject[mapping]`. The math symbol of a group stays `map(t)`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018B3nA4HppT8Z4pzepcHkj9
The alias's own code follows the rename: an alias has the mapping
`<alias>[<target>]`, the refusal of that mapping declared again reads
`mappings:`, and the notation rows say "mapping".

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018B3nA4HppT8Z4pzepcHkj9
A set of combinations of labels is a dimension with over:. The schema
refuses relations: as an unknown key, and the program keeps one table
per subject with maps or members. The maps page replaces the relations
page; the reference, limits.md and the explanation pages say the same.
A tuple named only in a where: counts as a use for check.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018B3nA494URRSeWy6wmELGP
@FBumann FBumann changed the title feat(language): a dimension lists its members, strictly feat(language)!: a dimension lists its members, strictly Nov 17, 2026
The base renames maps: to mappings:. The merge takes this branch's side
in every conflict, then applies the rename to this branch's own lines:
MapSpec, Spec.mappings, mappings:, subject[mapping], and "mapping" in
messages, docstrings, tests and pages. The page maps.md is mappings.md.
The verb, Python's Mapping, the maths map(t) and linear maps stay.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018B3nA494URRSeWy6wmELGP
FBumann pushed a commit that referenced this pull request Nov 17, 2026
Four refusals of #9 become the spelling each one stood for:

- an operand over a member meets the dimension: read at each tuple, as
  at(x, by=dimension[member]) reads it;
- sum(x, over=member) on an operand over the dimension: the sum through
  the dimension, grouped by the members over= leaves;
- two dimensions in one dims: that share a member: the entry over the
  members, where: the dimensions;
- a step along a member: the entry it steps in, and the entry it steps,
  over the members, where: the dimension.

Every spec #9 loads builds the same program. A parameter over the
members carries the tuples as its domain, where a tool refuses a stray
row; that is the one change no #9 spelling states.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018B3nA494URRSeWy6wmELGP
FBumann pushed a commit that referenced this pull request Nov 17, 2026
…strict

The tree is the restack's: #8's design as the four lifts over #9. The
second parent keeps #8's earlier history, so the push fast-forwards.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018B3nA494URRSeWy6wmELGP
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants