Skip to content

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

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

FabianHofmann wants to merge 19 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, a member is read through the relation the entry implies, and a cross product that pairs tuples which disagree on a member is refused, in dims: or in an expression.

Part of #1011. Supersedes #999. Stack: #1029 (alias) → #1012 → #1013 → this → #1025.

# 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
  from_region: { alias: region }               # one dimension twice: an alias (#1029), no role form
  trade: { over: [from_region, region] }
relations:
  connection_bus: { key: connection, values: [bus, role] }
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" }

Refused at load:

dimensions:
  connection: { over: [unit, port] }
  assignment: { over: [unit, period] }
  link: { alias: connection }          # alias of a dimension with members → refused
variables:
  x: { dims: [connection, assignment] } # share unit → refused, whatever the where:
  y: { dims: [connection, unit] }       # beside its own member → refused
objective: "sum(sent * on)"             # sent over connection, on over assignment → refused
expressions:
  e: "sum(f, over=snapshot, by=snap_unit[unit])"  # f over [connection, snapshot] → refused
piecewise:
  curve: { dims: [assignment], along: period, ... } # along a member → refused at load, not at expand
# loads: supply_region: {alias: region}, demand_region: {alias: region},
#        supply: {over: [supply_region, plant]}, demand: {over: [demand_region, site]}
Messages, method, gates, not done

Refusals (verbatim)

  • Constraint 'exclusive' lists 'assignment' and 'connection' in dims:, which share 'unit'. A dimension with members is opaque, so the entry would pair every assignment with every connection, whatever their unit. Write the entry over the members, dims: [period, port, unit], with where: a relation keyed by [period, unit] and one keyed by [port, unit]. If every pair is meant, let connection list its own alias of the shared member: connection_unit: {alias: unit} and connection: {over: [connection_unit, port]}.
  • Variable 'x' lists 'assignment', 'c3' and 'connection' in dims:, which share 'unit'. … would pair every assignment with every c3 and every connection … If every pair is meant, let c3 and connection list their own alias of the shared member: c3_unit: {alias: unit}, c3: {over: [bus, c3_unit]}, connection_unit: {alias: unit} and connection: {over: [connection_unit, port]}. (one message per linked group)
  • Variable 'x' lists 'connection' and its member 'unit' in dims:, so the entry would pair every connection with every unit. Drop 'unit' from dims:, and read it at each connection as connection[unit], as in at(<operand>, by=connection[unit]).
  • The objective: sent * busy is over 'assignment' and 'connection', which share 'unit'. A dimension with members is opaque, so the expression would pair every assignment with every connection, whatever their unit. Declare the operands over the members, with where: a relation keyed by [period, unit] and one keyed by [port, unit]. If every pair is meant, let connection list its own alias of the shared member: connection_unit: {alias: unit} and connection: {over: [connection_unit, port]}.
  • Named expression 'e': sum(by=snap_unit[unit]) is over 'connection' and its member 'unit', so the expression would pair every connection with every unit. Sum 'connection' out of the operand first, or group by a column over another dimension.
  • piecewise 'curve': along: 'period' is a member of 'assignment' in dims:, so the curve would pair every assignment with every period. Step along an alias of it, curve_period: {alias: period}, and declare the breakpoints over 'curve_period'.
  • Dimension 'link': alias: 'connection' is a dimension with members. Declare 'link' with the same members instead: link: {over: [port, unit]}.
  • dimensions.pair.over: takes a list of dimensions, not a mapping. Name each member that repeats a dimension as an alias of it under dimensions:, src: {alias: region}, dst: {alias: region}, and list the names: over: [src, dst]. (alias target, even where src maps to an alias); with no repeat: … not a mapping. List the dimensions: over: [unit, port].
  • Dimension 'pair' lists 'from_region' twice under 'over:'. Declare an alias of it under dimensions:, from_from_region: {alias: region}, and list both: over: [from_from_region, from_region].

Design

  • One helper, _dimensions.overlaps(dims, spec): groups of dimensions linked by a shared member, plus a dimension beside its member. Run on each dims: frame, on the union where two operands meet (check_meeting), and on the dims a join leaves (join_dims). One message builder, shared_refusal.
  • Each suggested alias names the alias target (aliased), never an alias of an alias.
  • Mapping refusal moved from DimensionSpec to a Spec before-validator, so it sees every dimension.
  • within= through the relation of an alias loads again (regression from the alias merge); a dimension with members still refuses it.
  • Stack sits on feat(language): a dimension may alias another's labels #1029, merged bottom-up (no rebase, no force-push). Role form removed (D16); D15 overlap refusal; one implied-relation helper and one collision rule with feat(language): a dimension may alias another's labels #1029.

Tests

  • Failing first: 45d0707 (tests only) on 987f019 → 27 failed.
  • New: test_the_rewrite_an_overlap_refusal_suggests_loads feeds each suggested rewrite back to to_spec(...).expand() (14 cases).
  • Guard removal on the head: aliased undeclared guard → 1 fails; overlaps declared guard → 6 fail; piecewise declared guard → 1 fails; within= members guard → the alias within case fails.

Gates

  • pixi run ci passes on db56ec2: lint, 4375 tests (1 skipped), docs-build --strict, compile-tex (62 documents).
  • Schema and goldens regenerated: no diff.

Docs: dimensions.md (alias of a dimension with members, expression-level overlap, within= in the refused table, prose fixes); limits.md (same rows; lifting the refusal later breaks no spec).

Not done: rule 6 (at unstack) is #1025. No in:, maps:, linopy change.


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.
…imensions

# Conflicts:
#	docs/reference/language/dimensions.md
#	docs/reference/notation.md
#	src/mathspec/_advising.py
#	src/mathspec/_condition_resolver.py
#	src/mathspec/_lowering.py
#	src/mathspec/_resolution.py
#	src/mathspec/_validation.py
#	src/mathspec/program.py
#	src/mathspec/spec.py
#	tests/typesetting/golden/latex.out
#	tests/typesetting/golden/markdown.out
#	tests/typesetting/golden/typst.out
…: are refused

Refused whatever the where: dims: listing two dimensions that share a
member, or a dimension beside its own member. over: takes a list only; a
dimension twice is an alias beside it. The allocation of #1011 loads with
an alias per side. The frame exemption and the relaxed comparison of two
relations keyed apart lose their tests.
An entry whose dims: lists two dimensions that share a member, or a
dimension beside its own member, is refused at load, whatever its where:.
The message suggests the flat entry with a relation per set, or an alias
of the shared member where every pair is meant; beside a member, reading
it as connection[unit].

over: takes only a list of dimensions. A mapping is refused with the alias
rewrite, and the role checks, the rename guard for roles and the
role-shaped member pairs go. The frame exemption that let a member meet
its dimension where dims: listed both is deleted, and two relations keyed
apart compare only as on main.
…imensions

# Conflicts:
#	src/mathspec/_advising.py
#	src/mathspec/_condition_resolver.py
#	src/mathspec/_expression_resolver.py
#	src/mathspec/_resolution.py
#	src/mathspec/_validation.py
#	src/mathspec/errors.py
An expression whose operands meet over dimensions that share a member,
an alias of a dimension with members, a curve along a member of its
dimension, and within= through an alias's relation.
- An expression whose operands meet over dimensions that share a member,
  and a join that leaves an operand over a dimension beside its member or
  over two that share one, are refused like a dims: that lists them.
- A curve whose along: is a member of a dimension in its dims: is refused
  at load, not at expansion.
- An alias of a dimension with members is refused; the message suggests a
  second dimension with the same members.
- within= through the relation of an alias loads again.
- Dimensions that share a member are refused in one message per linked
  group, and each suggested alias names the dimension an alias member is
  an alias of. A mapping under over: that repeats no dimension suggests
  the list alone; the check moves to Spec, where it sees every dimension.
- _listed moves to errors.listed; _member_columns is inlined.

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