feat(data): a relation may be keyed by several columns, so a generator's zone can change by period

[FBumann]

Prompt: the engine work (widen refusal, then attaching/compiler/reindex/predicates for a multi-column key), using #1567 and #1575 as the reference and closing them

Note

The following content was generated by AI.

The single-valued map is now one value column per key, whatever the key names. sum(by=) groups per condition, at(by=) reads back per condition, and a where: tests the value at every key dimension. What #1567 asked for — a generator's zone that changes by period — is one relation now, not a relation per period.

The language already lowered it (math-spec#437's Walk carries joined roles); lanes.lowered refused it. Refused still: a relation with no key, a relation whose key determines two columns, and a partitioned shift/sum_back/position grouped by a conditioned map — the last of which the language admits, so its refusal says the limit is this package's group table and names the walked dimension in the rewrite. #1651 carries all three.

What moved

• relations.py — key_role/key_dim become key_roles/key_dims; refusal turns away only a keyless relation and one with several value columns, and gains the partition rule above, which needs a walk over the plan (_partitioning).
• sources.py — a relation arrives with one column per key column; the null, duplicate and stray-label checks are per key tuple and per key dimension.
• compiler.py — _mapping takes the node's walks and names every column by its dimension; _remap_fragment joins on the consumed dims and the joined ones. _empty_groups and the pullback's presences carry the condition too.
• predicates.py — a relation comparison joins on every key dimension.
• the eager lane — one array per relation over its key's product (loader.py), so dim_coords becomes a flat relations map; operator_grouped_sum groups by (value, condition) and masks the operand where a pair is unmapped rather than dropping a label; operator_at fills and masks back for the same reason.

Mutation table

Baseline for this environment: 10 failures, all gurobi/xpress not installed.

mutation	result
the partition-by-a-conditioned-map refusal (relations.py:47-50)	caught
the single-value walk guard (compiler.py:700-704)	caught
the relational join drops the condition (compiler.py:834)	caught — 13 failed, 3 beyond the baseline
the eager group keys drop the condition (operators.py:99)	caught — 12 failed, 2 beyond the baseline

The first two through python -m tools.mutate, which reported the tree clean afterwards; the last two by hand (a changed line, which the tool does not express), each with the same three precautions — committed tree, git checkout --, __pycache__ dropped on both sides.

Verified

ruff check · ruff format --check · pyrefly check · pytest -q -n 4 — the suite reaches the same 10 failures as main in this environment, all of them a solver that is not installed (gurobi, xpress). Run in a uv venv rather than pixi (no pixi here).

Not run: pixi run test-floors (the bare-install shape) and test-bench — no pixi environment here.

New coverage in tests/test_conditioned_relations.py: the grouping, an unmapped pair, the pullback, the where, both refusals, and three door checks — the first four differential, the first also against the LP file.

Coverage that moved: test_label_coords.py's a-key-of-two-columns-joins-on-one-the-walk-does-not-trade was a refusal case and is now the feature, so it is deleted and its shape is the new module's subject. test_sum_by_relations.test_a_hand_built_walk_onto_two_columns_is_refused now meets a named assertion rather than a zip crash.

What I did not do

• A relation with several value columns, and a bare relation, stay refused. Both are the rest of feat(data): a lookup is a relation, and one short of a key it declares total is refused at bind #1575 and are filed as a relation with several value columns, and one with no key, are still refused #1651 rather than bundled here.
• A partition by a conditioned map is refused, not built. The language admits it; this package's group table ranks inside one group per key column, and the eager lane's _grouped is one-dimensional. Building it is its own change, in a relation with several value columns, and one with no key, are still refused #1651.
• No new example or gallery page. The shape is exercised by the test module; an example is worth a docs: PR of its own.
• a self-map passes check and then crashes in the build with polars' own error #1652 is untouched here. A self-map — two columns over one dimension — crashes in the build on main and still does on this branch; the walk's output column needs a name of its own, which is a separate fix.

🤖 Generated with Claude Code

https://claude.ai/code/session_014pdMgEVkGBfh1f2AyiCSKA

[read-the-docs-community]

Documentation build overview

📚 lpspec | 🛠️ Build #34583566 | 📁 Comparing 827010a against latest (28cceaf)

  🔍 Preview build  

2 files changed

± about/architecture/index.html
± reference/data/index.html

[codspeed]

Merging this PR will not alter performance

✅ 24 untouched benchmarks
⏩ 58 skipped benchmarks¹

---

_{Comparing feat/relation-keyed-by-several-columns (827010a) with main (1fd8926)²}

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. ↩

2. No successful run was found on main (28cceaf) during the generation of this report, so 1fd8926 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

[FBumann]

Superseeded