chore(engine): a relation's table is read through one module, as the join and the grouping a walk names

[FBumann]

Prompt: "Please review everything about relations in lpspec. Do a stacked pr refactoring the code to make it more readable and have better seams and types" — and, on the first cut: "I fell like this lpspec pr adds a lot of new names which are things we already have conceptually", which took Ends and keyed back out; "Axis is a separability concept I think", which took the word out; and "Do Order", which named the type by the language's word.

Note

The following content was generated by AI.

Stacked on #1659. No consumer can tell the difference: the same queries, read through one module and two types instead of a dozen loose functions, in the language's own words — a walk's consumed, joined and produced dimensions, and the order a shift counts along.

What the review found. After #1659, the relational lane spelled the same three facts several times over:

• a Walk's roles became columns in four places — compiler._walked, compiler.partitioned, predicates.join_relation and reindex._group_columns;
• the walk join was written twice — _remap_fragment and _pulled_back_presences.pulled both keyed on consumed, joined and carried-produced dims and landed the rest under their names;
• a partition's group key was recomputed in three places, and reindex._edge rebuilt the ranked table a second time per shift; reindex._Walk had come to hold a program.Walk as a field, under the same name.

What moved

• relational/engines/polars/relations.py (new) holds the role-to-column translation once:
  • mapping and walk_join — the table a group or a pullback joins against, and the one join that trades the consumed dims for the produced ones (keyed on consumed, joined, and a produced dim the operand already carries) in a single select, which is what a self-map needs. _remap_fragment is two lines and the pullback's presence step one.
  • Grouping — the walked dimension ranked inside its groups, with key, keys, placed() and column_of(); replaces compiler.partitioned, reindex._grouped and reindex._group_columns.
  • joined_dims — the one property a node lacks until feat(program): a grouped sum and a pullback say which dimensions their walks join on energy-models/mathspec#488 releases; the pin bump deletes it. consumed_dims, produced_dims and landing are gone from the compiler.
  • GROUP_RANK, GROUP_SIZE, group_column and landing live here, out of fragments.py and compiler.py.
• reindex.py: _Walk is _Order — one dimension's own order, or each group's own, as an operator counts along it: the positions and the two keyed sides of the remap — built once per operator and holding its Grouping; the acyclic edge is _Edge, one type with keys, coordinates(), filled() and vacated_of(), in place of _edge, _filled_edge, _vacated, edge_keys and offset_dims, and the named offset's table is read once. The prose says dimension where it said axis.
• predicates.py reads a grouped position through Grouping; the relation read keeps its body.
• compiler.py keeps the expression walk only.

Verified

ruff check · ruff format --check · pyrefly check · pytest -q -n 4 on the head: 3772 passed, the same 10 failures as the base (gurobi, xpress not installed here). No new guard, so no mutation table.

Departed from one default: the pass is not fewer lines. Six files, +417 −332 against the base, and the surplus is the docstrings on the two types; what it ends with is fewer concepts and one home per fact.

🤖 Generated with Claude Code

https://claude.ai/code/session_01DT1r52zPp9BdnrzFdp1xoY

[read-the-docs-community]

Documentation build overview

📚 lpspec | 🛠️ Build #34584662 | 📁 Comparing 8c0e2cc against latest (3e825f0)

  🔍 Preview build  

11 files changed · ± 11 modified

± Modified

• about/architecture/index.html
• about/linopy/index.html
• reference/data/index.html
• examples/pypsa_ladder/rung_01_transport/index.html
• examples/pypsa_ladder/rung_02_storage/index.html
• examples/pypsa_ladder/rung_06_kvl/index.html
• examples/pypsa_ladder/rung_10_quadratic_costs/index.html
• examples/pypsa_ladder/rung_12_linearized_uc/index.html
• examples/pypsa_ladder/rung_13_losses/index.html
• examples/pypsa_ladder/rung_14_stochastic/index.html
• and 1 more...

[codspeed]

Merging this PR will not alter performance

✅ 24 untouched benchmarks
⏩ 58 skipped benchmarks¹

---

_{Comparing chore/relation-seams (8c0e2cc) with claude/mathspec-relations-issues-tsf1fa (8c64e8c)}

Footnotes

1. 58 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩