feat(language): a sum or a read walks a relation with consume= and produce= rather than over= and into=

[FBumann]

Prompt: "There are a lot of proposals for relation operations. I want to add one more: going back to consume and produce." · "And should we add rows for the common case without relations too? THats where this PR shines, right? It uses consume, not over in sum()?" · "also shift, at etc!?"

A sixth proposal for #516, and the only one that is a naming change alone: main's shape with the two walk keywords back to the pair #437 used and #477 renamed. It writes all fourteen cases of #516 and prints the same math. It is also the only one that reaches a model with no relation in it — one keyword out of six.

Note

The following content was generated by AI.

What this changes

over= is consume= and into= is produce=, on sum and on at. by=, along=, within= and window= are unchanged. piecewise: over: and sos: over: are unchanged, because they name a declaration's breakpoint axis and not a call keyword — so over stops being one word for two things.

sum(p, consume=generator) # the plain sum: no relation in sight
sum(p, by=zone_of, consume=generator, produce=zone)
at(price, by=zone_of, consume=zone, produce=generator)
shift(p, along=snapshot, offset=1, edge=0, by=cal, within=week) # untouched

The first line is the point, and the cost. sum(x, over=d) with no by= is the most common call in any model, and the four relational proposals (#502, #499, #515, #509) all leave it exactly as main has it. This is the one proposal that touches it. In this tree that is 164 of the 221 keyword occurrences under examples/ and docs/ — three quarters of the diff is models that declare no relation at all.

The rename goes no further than that one keyword. I ran every relation-free call on all six branches. sum(p), shift(x, along=t, offset=1, edge=0), sum_back(x, along=t, window=4) and position(t) are the same call and the same math on all six. shift(…, over=t, …) and sum_back(…, over=t, …) are refused on all six, main included — the over= → along= half of #477 is settled and this PR does not reopen it. at has no relation-free form anywhere: a read needs a table to read through.

What the rename buys, in three lines that over= did not give:

• Walk.consumed and Walk.produced already carry these words. feat(language): relations replace lookups, walked with over= and into= rather than consume= and produce= #477 kept them on purpose. The call and the program now say one word per concept.
• over= meant two directions. On sum it names the column removed; on at the same keyword names the column the read starts from. Both are Walk.consumed, and consume= says so.
• Gap F of Relations: the five syntax proposals on fourteen cases, with the math each prints #516 asks whoever wins to state in one sentence what over= takes. consume= takes the thing consumed: a dimension without a by=, a key column with one.

The rename is whole — the operator signatures, every error message, the reference pages, every example, the generated schema and the golden model. GroupSum.over, At.over and Sum.over keep their names: they were over/into before #477 too, and on At they flip with the adjoint, so they are not the keyword under another spelling.

The cases of #516, in this spelling

The calls with no relation in them, which are where this proposal differs from the other four:

#	the call	against the other four
0a	sum(p)	same
0b	sum(p, consume=generator)	the one cell where this PR stands alone
0c	shift(x, along=t, offset=1, edge=0)	same
0d	sum_back(x, along=t, window=4)	same
0e	position(t)	same
0f	a read with no by=	refused on all six

The fourteen relational cases:

#	the call
1	sum(p, by=gen_bus)
2	sum(p, by=zone_of, consume=generator, produce=zone)
3	sum(p, by=slot_of, consume=generator, produce=bus)
4	sum(p, by=slot_of, consume=generator, produce=[bus, technology])
5	sum(p, by=slot_of, consume=[generator, period], produce=bus)
6	sum(p, by=slot_of, consume=[generator, period], produce=[bus, technology])
7	sum(f, by=ends, consume=line, produce=bus1)
8	at(price, by=gen_bus)
9	at(cap, by=ends, consume=bus0)
10	shift(x, along=t, offset=1, by=cal, within=week)
11	position(t, by=cal)
12	position(t, by=cal, within=week)
13	sum(p, by=connection, consume=generator, produce=bus)
14	sum(y, by=l, consume=a, produce=b) — binds l, a, b

All of them load, cases 3 and 4 included, and each prints the math #516 records for it.

Verified

pixi is unreachable from this session, so every gate ran in a uv venv on Python 3.13 with the pinned ruff 0.16.1, pyrefly 1.2.0, typos, reuse and prettier 3.9.3.

• pytest -q: 1290 passed, 6 skipped.
• ruff check, ruff format --check, prettier --check, typos, reuse lint: clean.
• pyrefly check: the same 11 errors as the base branch in this environment, all missing stubs for pydantic and yaml.
• mkdocs build --strict: passes with the docs.python.org inventory dropped for the run, since the proxy answers 403 on it. The committed mkdocs.yml is unchanged.
• Regenerated and read the diff: schema/math-spec.schema.json, the three golden outputs, the gallery pages, notation.md, operators.md, README.md, docs/index.md.
• The cross-branch runs used fresh exports of each proposal's own commit: origin/main @ bc1d9d4, feat(language): a sum and a read name their direction in direction=, as a -> b #502 @ 21cd2a9, feat(language): a relation's direction is written inside by=, as relation(a -> b) #499 @ 9311dfb, feat(language): over=rel.k and by=rel.v name a relation's columns after its name #515 @ b55dc42, feat(language): a relation is summed with over=/by= and indexed with x[rel] #509 @ 4b4796e.

The strongest evidence is the golden output. tests/typesetting/golden/model.yaml moved 18 lines and latex.out, markdown.out and typst.out are byte for byte what they were. A keyword rename cannot touch the math, and the committed files say so.

Not run: compile-tex (no tectonic here) and taplo (no .toml changed).

Two test ids named the old keywords and follow it: by-and-over-compose is by-and-consume-compose, into-without-by is produce-without-by. No assertion changed.

Not done, on purpose

• along= stays. feat(language): a relation between dimensions, walked in the direction each call names #437 spelled the ordered axis over= as well. That half of feat(language): relations replace lookups, walked with over= and into= rather than consume= and produce= #477 is a separate decision and this PR does not reopen it; 0c and 0d above are the check that it is settled on all six branches.
• The macro formal named over stays, in tests/test_expansion.py and the weighted_sum example on the expressions page. kwargs: [over] with template: sum(array * weights, consume=over) is what the tree carried before feat(language): relations replace lookups, walked with over= and into= rather than consume= and produce= #477, and it still shows that a formal may be named after a word the language no longer reserves.
• GroupSum.over, At.over, Sum.over and RelationNode.into stay, for the reason above.
• One sentence in dimensions.md is cut rather than renamed. "over= names the column consumed and into= the column produced" is a restatement once the keyword is the word, so the paragraph keeps only the rule: name a column only where the relation offers two.

Why

#516 compares five syntaxes for the same walk and finds that every one of them prints the same math. What is left to choose on is the spelling, and this is the spelling that names the two ends of the walk in the words the program already uses for them. It writes the two cases #509 cannot, without the arrow of #499 and #502 and without #499's whole-or-nothing rule on case 6.

Bryn's objection on #437 was that consume and produce are energy-system words. The counter-argument this PR makes is that they are also the two words this codebase uses for the walk, and that over was carrying the declaration axis, the English "sum over", and one of two directions at the same time. The counter-cost is case 0b: this is the only proposal that rewrites a model with no relation in it.

🤖 Generated with Claude Code

https://claude.ai/code/session_017ZhdyUr2JZZYcBzTuJrRKx

[read-the-docs-community]

Documentation build overview

📚 math-spec | 🛠️ Build #34614493 | 📁 Comparing f4166ec against latest (bc1d9d4)

  🔍 Preview build  

24 files changed · ± 24 modified

± Modified

• index.html
• about/limits/index.html
• about/what-counts-as-language/index.html
• examples/commitment/index.html
• examples/dispatch/index.html
• examples/operators/index.html
• examples/pypsa/index.html
• examples/pypsa_losses/index.html
• examples/pypsa_stochastic/index.html
• reference/language/index.html
• and 14 more...

[FBumann]

Closed in favor of #534

Will revisit for syntax discussions