Skip to content

feat(language): at spreads a tuple over its members - #1025

Draft
FabianHofmann wants to merge 9 commits into
feat/tuple-dimensionsfrom
feat/tuple-unstack
Draft

FabianHofmann wants to merge 9 commits into
feat/tuple-dimensionsfrom
feat/tuple-unstack

Conversation

@FabianHofmann

@FabianHofmann FabianHofmann commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Note

The following content was generated by AI.

at by every member of a dimension moves an operand over that dimension to its members, absent where no tuple exists.

Part of #1011 (rule 6). Stacked on #1014.

dimensions:
  connection: { over: [unit, port] }
  assignment: { over: [unit, period] }
variables:
  flow: { dims: [connection] }
  metered: { dims: [unit, port] }
  sent: { dims: [connection, period] }
  busy: { dims: [assignment] }
  level: { dims: [assignment] }

# before: refused
#   at(by=connection[port, unit]) joins on ['port', 'unit'], which the expression does not carry ...

# after
constraints:
  meter:              # absent at a unit and port that are no connection
    dims: [unit, port]
    expression: metered == at(flow, by=connection[unit, port])
  only_when_busy:     # no row where the unit has no assignment: the inner join
    dims: [connection, period]
    expression: sent <= at(at(busy, by=assignment[unit, period]), by=connection[unit])
  idle_sends_nothing: # every connection and period: the left join, 0 where nothing matches
    dims: [connection, period]
    expression: sent <= at(sum(busy, over=assignment, by=assignment[unit, period]), by=connection[unit])
  carry:              # a shift along an ordered member, read back at each tuple
    dims: [assignment]
    expression: level >= at(shift(at(level, by=assignment[unit, period]), along=period, offset=1), by=assignment[unit, period])

Prints metered_{p,u} = flow_{(p,u)}, sent_{c,p} ≤ busy_{(p, connection.unit(c))}, level_a ≥ level_{(assignment.period(a) − 1, assignment.unit(a))}.

Engines: program.footprint.spreads names each dimension a row or bound spreads ({'connection'} above).

Method, gate output, choices, not done

Triage (limits.md): no new operator. at on an operand over the dimension, where it was refused. On an operand over the members it gathers onto the dimension, as before.

Rule

Why JoinColumns.spreads, and why the sum by every member still loads

  • sum(y, over=assignment, by=assignment[unit, period]) has the same joined/grouped as the spread, and groups of at most one row. relations.md refuses other one-row-per-group sums; this one loads because it is a different program: 0 where no tuple, the spread absent.
  • e.g. at(shift(sum(y, …), along=period, offset=1), by=…) reads 0 in a unit's first active period; the spread form drops that row. Same for idle_sends_nothing vs only_when_busy above.
  • so the flag tells the two apart; it is documented in relations.md and relations-as-linear-maps.md.
  • footprint: a spread is a Join in kinds, like a lookup, so an engine gating on kinds could not see it. New field Footprint.spreads: frozenset[str], empty when unused, like the other fields. Covers rows and bounds, not where: (as kinds).

Program

  • No new node. Join with JoinColumns(joined=(connection,), grouped=(port, unit), spreads=True); JoinedCondition likewise.
  • Engines: docstrings of Join, JoinColumns, JoinedCondition, Footprint; reading.md.

Loads (tests): constraint (left join, sum after, shift along another dimension, shift along a member), named expression (body and as operand), one case + otherwise, bound, where: (bare and comparison), piecewise link with at by every or one member.

Refused, each with the rewrite

  • case when: with a spread, two or more cases, written inline or through a named conditions: entry → undecidable (SchemaError). The spread's "has a row" is a different fact from the relation's. Not handled, so refused.
  • piecewise by: naming members of a dimension in dims: → DimensionError, advises at(<expression>, by=<same columns>) in the link. On feat(language): a dimension lists its members #1014 a clean DimensionError from a later check; the new spread in lookup would crash here, so it is refused first.
  • stray connection in an entry over its members (constraint, named body, bound, where:) suggests the spread; a meeting suggests it only where dims: holds every member.

Typesetting: a gather inside a spread printed capacity_{connection.unit((o, u))}; now capacity_u, all three formats. Golden unchanged (regenerated, no diff).

Guard removal (each deleted, full suite run)

  • operand-with-a-member falls to feat(language): a dimension lists its members #1014's refusal → 1 fails
  • partial list → 2 fail; as SchemaError → 2 fail
  • two members over one dimension → 1 fails; as SchemaError → 1 fails
  • undecidable case → 1 fails
  • piecewise by: → 2 fail; as SchemaError → 2 fail
  • spreads() needs value columns (key column keeps its own refusal) → 1 fails (test added after 0 failed)
  • spread advice needs every member in dims:, one guard (_spread_roles) for the stray-dimension rewrite and the meeting → 5 fail; the meeting calling it with its own members instead of dims: → 2 fail
  • member read inside a spread → 4 fail
  • footprint.spreads → 2 fail

Gates

  • pixi run ci passes on the pushed head: lint, 4361 tests (1 skipped), docs-build --strict, compile-tex (62 documents).
  • regenerated, diff read: golden *.out (no change from this revision), docs/reference/notation.md. Schema unchanged.
  • figure operators-at-members.svg: looked at in light and dark (headless Chrome). Data invented: three connections.
  • dimensions.md math for idle_sends_nothing is the typesetter's output, copied.

limits.md moves: "an order along a dimension with members" → shift and sum_back along an ordered member now have a spelling. dimensions.md: the left join moves from "no left join" to an example (the sum by every member); outer join stays refused.

Where #1011 is silent or off

  • rule 6, role form: chosen as above.
  • rule 9 and the first risk: carry above loads. position, piecewise:, sos: still need the bare relation.
  • conditions and bounds: spread allowed in both; false, and no bound, where no tuple.

Not done

  • rule 11 (check advice). shift along the tuple dimension itself stays refused. No in:, maps:, linopy.
  • exclusivity of a spread in when: (refused, see above).
  • the meeting's "read the operand at each tuple" clause is feat(language): a dimension lists its members #1014's and not checked against dims: either.
  • footprint still does not read where:.

Generated by Claude Code

@read-the-docs-community

read-the-docs-community Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

- the meeting advises a spread only where dims: holds every member
- a partial list and two members over one dimension raise DimensionError
- a piecewise by: naming members of a dimension in dims: is refused as a
  DimensionError, and advises at() by the same columns in the link
- a member read inside a spread prints as the member's index
- footprint.spreads names each dimension a row or bound spreads
@FabianHofmann
FabianHofmann removed this pull request from stack #1022 November 19, 2026 08:29

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

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants