[FBumann]

Prompt: "This is the shape!" — after "Maybe a single relations key would be better?", "Is the lookup name always the first name in the by=?" and the rules written down in the session. Stacked on #493, which is the base branch. Supersedes #495, whose thread discusses the earlier over=a -> b form. A follow-up fixed the vocabulary: "its a direction, not a walk!" — the walk is the traversal, the direction is what the call writes.

A later follow-up, after reading #515 beside this one, shortened the read: "Yes, land that on #499" — that being one end on an at, so at(cap, by=ends(bus0)) loads and the key is not written out.

Note

The following content was generated by AI.

What this changes

by= is the only relational keyword. It names a relation, and the direction of the walk through it is written after the name, relation(a -> b). into=, within= and the direction form of over= are gone.

before	now
sum(p, by=zone_of, over=generator, into=zone)	sum(p, by=zone_of(generator -> zone))
sum(p, by=gen_bt, into=[bus, technology])	sum(p, by=gen_bt), or written out, by=gen_bt(generator -> [bus, technology])
sum(f, by=ends, over=line, into=bus1)	sum(f, by=ends(line -> bus1))
at(cap, by=ends, over=bus0)	at(cap, by=ends(bus0))
at(tech_cap, by=gen_bt, over=[bus, technology])	at(tech_cap, by=gen_bt)
shift(x, along=t, by=cal, within=week)	shift(x, along=t, by=cal(week))
position(g, by=gen_bt, within=[bus, technology])	position(g, by=gen_bt([bus, technology]))
sum(p, by=gen_bus), at(price, by=gen_bus), by=[gen_bus, gen_tech]	unchanged

The rules.

• A call writes what the declaration does not decide, and nothing more. A bare by= means the declaration decides the whole direction. A sum names both ends, since either can vary: sum(p, by=zone_of) with two key columns is refused toward by=zone_of(<dimension> -> zone). A read and a partition name one — the columns read, or the columns grouped by — because the other end is not theirs to choose. A read lands on the whole key, and a partition takes its other end from along=.
• The left end of a sum names a dimension, every other end names columns. A key has one column per dimension, so generator names the key column over it, and a renamed key column is written by its dimension. Value columns may share a dimension, so bus1 is named by column.
• over= and along= keep one meaning. over= is a reduction over a dimension, along= the axis a translation moves along. A sum with a by= takes no over=; the call shape refuses both together.
• Two defaults become rules. A bare sum lands on every value column (sum(p, by=gen_bt) onto bus × technology), and a bare read consumes every value column the operand carries (at(tech_cap, by=gen_bt)). Both were refused before. Each is the rule sum(x) already follows for dimensions, and each is refused where two value columns share a dimension, naming the column to write.
• The relation and both ends are nodes. A macro binds a formal at any of the three: sum(x, by=l(a -> b)) with l=, a= and b= at the call.

Nothing changes for a consumer: Walk, GroupSum, At and the partitions lower as before. A read's split into consumed, joined and produced is Walk.read_by, one rule the dim check and the lowering share. The typesetter's math did not move; the golden .out files are unchanged.

Why

Two keywords for one direction, with the table named in a third, made the relational calls hard to read, and over= meant a dimension in one call and a column in the next. Writing the direction after the relation puts the table first, shows the direction unmistakably, and leaves every keyword with one meaning. The probe rows on the operators page show each form beside the math it prints, which is where to judge it.

Why one end on a read, added after #515

The read was the one place this shape cost more than the keywords it replaced. at(cap, by=ends(bus0 -> line)) writes a landing that the declaration already fixes — a read lands on the whole key, always — so the arrow's right side could only ever be right or refused. #515's by=ends.bus0 is shorter for exactly that reason.

One end already meant something on a partition, by=cal(week): the columns the group is read from, with the other end coming from along=. Giving it the same meaning on a read makes the parenthesis one rule rather than two, and the read as short as #515's without leaving this PR's shape.

The math is the check that nothing was lost. The operator probe's cell is byte-identical before and after — at(cap, by=ends(bus0)) prints $f_l \le \mathrm{cap}_{\mathrm{ends.bus0}(l)}$, exactly as the long form did.

Refusals, each naming the rewrite

• sum(p, by=zone_of) with two key columns: 'zone_of' has 2 key columns (['generator', 'period']), and the call has to say the direction: by=zone_of(<dimension> -> zone).
• sum(p, by=lk(h)): by=lk(h) names one end, and a sum names both: what leaves and what arrives. Write by=lk(<dimension> -> h).
• sum(p, by=lk(g -> h), over=g): sum() takes at most one of by= or over= — a relation carries its own dimensions, and a direction names what leaves inside by=, so over= has nothing to add.
• sum(p, by=lk(h -> g)) where h is a value column's dimension: a sum consumes key columns, and 'lk' holds 'h' as a value column. To read it, write at(..., by=lk(h)).
• sum(p, by=lz) with h0, h1 over one dimension: by=lz lands on ['h0', 'h1'], two columns over ['h'] …
• at(r, by=lk(g)), naming a key column as the column read: by=lk(g) reads the key column(s) ['g'], and at reads value columns at the key. Read a value column, among ['h'], or walk the other way with sum.
• at(r, by=lk(h -> g)) with key [g, z]: lands on ['g'], and a read lands on the whole key, ['g', 'z']. Write by=lk(h), which names the columns read and lands on the key, or write that key out.
• at(cap, by=ends): 'ends' has two value columns over ['bus'] (['bus0', 'bus1']), so nothing says which one is read. Name it: by=ends(bus0).
• shift(..., by=lz(g -> h)): a partition walks the axis along= names, and the parenthesis names only the columns its group is read from. Write by=lz(h).
• sum(p, over=lk(h -> g)): names a direction through a relation, and a direction belongs in by=. Write sum(<expr>, by=lk(h -> g)).
• into=, within=: the closed call shape.
• by=l(a, b -> c) is a parse error, since a comma separates arguments; brackets for a list at an end.

Guards and their tests

Each guard deleted in turn, its test run, all failing without it. The two the read's change touches were re-checked in the session that shortened it; the rest were checked when they landed:

• one end written on a sum (_walk) → -k a-sum-with-one-end-written
• a read landing short of the key (_read) → -k a-read-landing-short-of-the-key
• a read naming a key column as the column read (_read) → -k a-read-naming-a-key-column
• a bare read through two value columns over one dimension (_read) → -k bare-read-through-two
• a left end on a partition (_partition_walk) → -k partition-with-a-left-end
• a direction in over= (_dim_ref) → -k a-direction-in-over
• a direction in arithmetic through a macro formal (_arith) → -k direction-bound-to-a-formal
• a left end not over a key column (_key_columns_over) → -k "key-is-not-over or walks-to-the-key"

Coverage moved when the read's one-end refusal went: a-read-with-one-end-written is deleted, since at(r, by=lk(h)) now loads, and a-read-naming-a-key-column-as-the-column-it-reads takes over the rule that the named column is a value column. Two rows were added to test_dim_inference, at(bz, by=gen_bz([bus, zone])) and at(load, by=pair(b0)); both failed on the tree before the change, with the refusal the change deletes.

Verified

pixi is not installable in this session (the installer is blocked by the proxy with a 403), so the gates ran from a uv venv on Python 3.13 with the pinned ruff==0.16.1 and pyrefly==1.2.0:

• pytest -q -n 4: 1317 passed, 1 skipped (the whole suite, test_docs.py included).
• ruff check, ruff format --check: clean. prettier --check on the changed pages: clean. reuse lint: compliant, 212/212. typos: clean.
• pyrefly check: 11 errors, 10 suppressed — the same count on the unmodified tree, and every one is a missing stub or pydantic import this venv lacks rather than a finding about the diff.
• Generated files regenerated with their tools: tests.typesetting.golden, tools.notation, tools.spec_math, tools.gallery, tools.home_math, tools.schema. The .out files, docs/reference/notation.md, docs/index.md and the README did not move at all, so the printed math is identical. docs/reference/language/operators.md and docs/examples/operators.md move only in the probe's label and its model.
• mkdocs build: no link or anchor warning. --strict aborts here on fetching docs.python.org/objects.inv through the proxy, which is the environment, not a page.

Not run: pixi run ci as one command, zizmor, taplo, compile-tex.

Deliberately not done: refusing the long at(cap, by=ends(bus0 -> line)) now that one end says the same thing. Two spellings for one read is a question worth deciding — the shorter is what the docs and the probe teach, and the longer shows the reader of a file what the result is over. Say the word and it becomes one spelling.

🤖 Generated with Claude Code

https://claude.ai/code/session_016enncWLMR8XjuSQ8JBKXGn

[read-the-docs-community]

Documentation build overview

📚 math-spec | 🛠️ Build #34692163 | 📁 Comparing 9311dfb against latest (5806435)

  🔍 Preview build  

10 files changed · ± 10 modified

± Modified

• CHANGELOG/index.html
• examples/operators/index.html
• reference/notation/index.html
• reference/language/dimensions/index.html
• reference/language/expressions/index.html
• reference/language/operators/index.html
• reference/math_spec/model/index.html
• reference/math_spec/operators/index.html
• reference/math_spec/program/index.html
• reference/math_spec/resolution/index.html

[FBumann]

Closed in favor of #540

Will revisit for syntax discussions

[FBumann]

Superseeded by #596