Skip to content

feat(language): a dimension lists its members - #1014

Draft
FabianHofmann wants to merge 13 commits into
feat/bound-atfrom
feat/tuple-dimensions
Draft

FabianHofmann wants to merge 13 commits into
feat/bound-atfrom
feat/tuple-dimensions

Conversation

@FabianHofmann

@FabianHofmann FabianHofmann commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Note

The following content was generated by AI.

A dimension lists its members under over:; its label is the tuple, and a member is read through the relation the entry implies.

Supersedes #999. Part of #1011. Stacked on #1013 (which is on #1012).

# before (main)
relations:
  connection: { key: [unit, port], values: [bus, role], missing: absent }
variables:
  flow: { dims: [unit, port, snapshot], where: connection, bounds: { lower: 0 } }
constraints:
  limit:   { dims: [unit, port, snapshot], expression: "flow <= capacity" }
  balance: { dims: [bus, snapshot], expression: "sum(flow, over=[unit, port], by=connection[bus]) == load" }

# after
dimensions:
  connection: { over: [unit, port] }              # labels are (unit, port); implies relation connection
  trade: { over: { from: region, to: region } }   # role form
relations:
  connection_bus: { key: connection, values: [bus, role] }   # extra facts: a relation keyed by it
variables:
  flow: { dims: [connection, snapshot], bounds: { lower: 0 } }
constraints:
  limit:   { dims: [connection, snapshot], expression: "flow <= at(capacity, by=connection[unit])" }
  balance: { dims: [bus, snapshot], expression: "sum(flow, over=connection, by=connection_bus[bus]) == load" }

# inner join of two tuple dimensions sharing a member (before: refused, "two dimensions cannot be compared")
dimensions:
  assignment: { over: [unit, period] }
constraints:
  k: { dims: [connection, assignment], where: "connection[unit] == assignment[unit]", expression: "x + y <= 1" }

Two relation columns now compare where dims: lists both keys (before: keys over the same dimensions), flat too:

# before: refused ("compares relations keyed over different dimensions")
# after: loads; with dims: [unit] refused: "Add 'line' to dims:, or compare against a relation keyed like 'bus_of'"
# a named condition has no dims:, so it is refused: "Write the comparison in the where: of an entry whose dims: lists the keys of 'bus_of' and 'line_end'"
variables:
  z: { dims: [unit, line], where: "bus_of[bus] == line_end[bus]" }

Legend: C ⊆ P × U (= under missing: refused); limit prints flow_{c,t} ≤ capacity_{connection.unit(c)}.

Method, gate output, open decision, not done

Triage (limits.md): not an operator, not a macro. A key on dimensions: that declares a relation; every read goes through at and sum as they are.

Rules of #1011 in this PR: 1, 2, 3, 4, 5, 7, 8, 10, 12, and the load half of 11 (a cross product loads; check advice later). Rule 9 needed no code: where: "at(active, by=connection[unit])" loads, test added.

How

  • DimensionSpec.over / .missing; Dimension.over / .missing on the program.
  • Implied relation is one line in Namespace.relations: key: connection, values: the members, missing: refused. Program.relations has it; its docstring and reading.md say a tool takes its rows from the dimension's struct column, no table of its own.
  • Collision exemption needs no code: the implied relation is not under relations:. A declared connection relation is still refused (tested).
  • Rule 10 "member operand meets the tuple": checked at the node (+ - * /, constraint and condition comparisons), against the entry's dims: passed down to the resolver.
  • The rule: an operand over member m (not T) meeting one over T (not m) is refused unless the frame lists both T and m; then it is their cross product (rule 11).
    • frame = the entry's dims:: constraint (body and where:), variable and parameter where:, named expression (body, case when:, value, otherwise:), piecewise links.
    • inside sum(...), frame = entry dims: minus what that sum adds up (over= names; all for a bare sum). A summed unit inside is not the frame's unit, so a cross product summed away is refused, as in rule 10; one the sum keeps loads.
    • no frame: objective, assumptions, piecewise where: (copied into the curve's assumptions; framing it made the assumption crash at load).
  • Frame-level checks in _dimensions.py: none duplicates the node check. Each catches an operand over a member that meets nothing (e.g. u <= 1 over [connection]); guard removal below.
  • merge: the existing "say different things about the dimension" refusal covers over: and missing:. rename: members renamed inside over:; a role is refused like a relation column.
  • never-an-axis advice skips the implied relation; an entry over the dimension reaches its members.
  • "member" now means only a dimension under over:; SOS docs and messages say "element".

Inner join (this revision; limit moved, limits.md join row)

  • Bug, rule 2: a side T[m] of a two-column comparison was read as dimension T, not its implied relation. Both sides now read as a relation where they name a column (_side_kind). connection[unit] == backup[spare] (same key) loads too.
  • Relaxed: two relation columns compare where both columns are over one dimension and the frame (dims:) carries both keys; RelationPairComparison.dims is the union. Each relation read at its own key; no row in either → false. No tuple special case.
  • Key outside the frame → refused: "…and dims: lacks 'z'. Add 'z' to dims:, or compare against a relation keyed like 'lk'".
  • No frame (objective, assumption, piecewise where:): today's rule, same-key only.
  • Case when:: exclusivity prover unchanged and sound. It models the pair as one boolean per cell plus both rows; keys do not enter. Tested: ==/!= proved apart; == vs a label refused with witness.
  • Typesetting: connection.unit(c) = assignment.unit(a), bus_of(u) = line_end(l) in md/tex/typst; no golden case added.
  • Docs: expressions.md row, relations.md tests, dimensions.md "Two dimensions that share a member" (cross product + filter = inner join; no left/outer join, rewrite over members), reading.md, limits.md.
  • Tests: test_tuple_dimensions.py 3 load cases + 2 case-exclusivity + 3 typeset; test_validation.py 4 load cases (variable/parameter/constraint where:, case), 3 refusal messages (key outside frame ×2, assumption).
  • Guard removal: right side read by kind → 7 fail; left side by kind → 8; no frame relaxation → 11; no-frame message dropped → 1; "keyed like" rewrite dropped → 2; pair dims only the left key → 2.

Refused at load, each with the rewrite (tests/test_tuple_dimensions.py, 41 parametrized cases)

  • member with members; undeclared member; dimension twice in list form; role named after another dimension; empty over:
  • ordered:, dtype:, one_of: beside over:; missing: without over:
  • shift, sum_back, position, piecewise:, sos: of type: 2 along one; within=connection[...] keeps the existing "no key column over 'snapshot'" refusal
  • operand with connection and a member, in a call through connection
  • over= naming a member → sum(..., over=connection, by=connection[port]); operand without connection → sum(at(u, by=connection[unit]), over=connection, by=connection[port])
  • operand over a member meeting connection where dims: lacks one of the two (flow <= capacity over [connection, snapshot], sum(flow * capacity) in the objective, sum(flow * capacity, over=unit) even over [connection, unit, snapshot], an assumption, a piecewise where:) → at(capacity, by=connection[unit]) or sum(flow, over=connection, by=connection[unit])
  • upper: capacity, where: capacity > 0, a body or case value over unit → at(capacity, by=connection[unit]); a named expression is named itself (at(e, …))
  • connection == 'a' → connection[port] == ...; bare where: connection → connection[port] == '...'

Loads: sos: of type: 1 along connection (no order used); an entry over [connection, unit] (both <= capacity); a meeting where dims: lists both: constraint flow <= capacity and named expression flow * capacity over [connection, unit, snapshot], sum(flow * capacity, over=snapshot) over [connection, unit], and the same in a variable, constraint or parameter where:, a case, a piecewise link (8 cases).

Guard removal (this revision): frame exemption deleted → 4 load cases fail; sum not shrinking the frame → 2 refusals fail (sum(..., over=unit) over a frame with unit, bare sum); frame dropped at each call site (constraint body, constraint where:, variable where:, parameter where:, named body, case when:/value/otherwise:, piecewise link) → 1–2 load cases each; framing the piecewise where: → assertion crash, 1 refusal fails. The constraint frame's at() rewrite failed no test once the node check took its case; a case now covers it (u <= 1 over [connection]).
Earlier revisions: 11 + 12 guards, 1–2 failing tests each.

Gates

  • pixi run ci passes on b5d7afd (after merging feat/bound-at ad19bec, which brings main's docs(examples): TIMES examples and a sparse-set example #1021): lint, 4315 tests (1 skipped), docs-build --strict, compile-tex (62 documents). examples/times/*.yaml and examples/sparse.yaml load.
  • regenerated and diff read: golden *.out (adds corridor_cap over corridor, so the golden model draws no advice), docs/reference/notation.md, tests/expand/*/after.yaml (SOS description "element"). Schema unchanged.

Open decision

  • "Operand has both connection and a member": refused for any call through connection (_dimensions.py join_dims), also where the member is not joined on. Narrower is possible.

Choices where #1011 is silent

  • dtype: and one_of: beside over: refused; a label comparison of the dimension refused. Rule 12 says the label is opaque.
  • missing: refused typesets as C = P × U.
  • List and mapping form with equal content ([unit] vs {unit: unit}) differ in merge, as relation columns do.
  • A patch (override) may not change missing: of a dimension; a relation's missing: it may.

Not done

  • Rule 6 (at unstack) and rule 11 (check advice): later PRs. at(x, by=connection[unit, port]) on an operand over connection keeps today's refusal.
  • No in:, no maps:, no linopy change. feat(language): a dimension may list combinations #999 untouched.
  • Commits have no Co-Authored-By, by the user's rule; AGENTS.md says otherwise.

Generated by Claude Code

A dimension takes `over:`, a list of plain dimensions or a mapping of
role to dimension, and `missing:`, absent or refused. Its label is the
tuple of its members, and it is one plain dimension in every operator.
The entry implies a relation of the same name, keyed by the dimension
with one value column per member, so `at` and `sum` read a member as
they read any relation column.

mathspec refuses at load, with the rewrite: a member that has members,
an order along the dimension, a role named after another dimension, a
dimension listed twice, an operand that carries the dimension and a
member in one call through it, and a label comparison. A sum over a
member and an operand over a member that meets the dimension get the
rewrite through the implied relation. All three typesetters print the
dimension as a subset of the product of its members.
A sum through a relation that names a member in `over=`, where the
operand is over the dimension that lists the member, is refused with
the sum over the dimension itself.
The dimensions page has the `over` and `missing` keys, the relation the
entry declares, what mathspec refuses and the data contract. The limits
page lists member access and an order along such a dimension as
constructs the language already has.
- An operand over a member meeting one over the dimension (+, -, *, /,
  comparison, condition comparison) is refused at the node, with the at()
  and sum() rewrites. sum(flow * capacity) and sum(flow * capacity, over=unit)
  no longer load as a cross product.
- A named-expression body, a case value and a where name the at() rewrite;
  a named expression is suggested by its own name.
- sum(u, over=unit, by=connection[port]) on an operand without connection
  suggests sum(at(u, by=connection[unit]), over=connection, by=...).
- sos of type 1 runs along a dimension with members; type 2 is refused as
  unordered. The dead within= guard is gone.
- never-an-axis ignores the implied relation; an entry over the dimension
  reaches its members.
- Bare where: connection suggests connection[port] == '...'.
- "member" means only a dimension under over:; an SOS has elements.
- Program.relations documents the implied relation and where its rows come
  from.
- An operand over a member meeting one over the dimension loads where the
  entry's dims: lists both, as their cross product (rule 11 of #1011).
  Elsewhere it stays refused with the at() and sum() rewrites.
- Inside a sum, a dim the sum adds up is not the entry's own, so
  sum(flow * capacity, over=unit) is refused even where dims: lists unit.
- The objective and an assumption have no dims:, so the meeting stays
  refused there, and in a piecewise where:, which its assumptions repeat.
- The frame is passed to constraints, variable and parameter where:, named
  expressions with their cases, and piecewise links.
- A constraint over a member its dims: lack keeps its at() rewrite, now
  tested.
@FBumann FBumann added the area: dimensions How dimensions are stated and used label Nov 16, 2026 — with Claude
A side named after a tuple dimension with a column reads its implied
relation, so connection[unit] == assignment[unit] is the inner join of
two tuple dimensions that share a member.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area: dimensions How dimensions are stated and used

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants