feat(language): a sum other files add terms to is declared as an expression with empty: true

[FBumann]

Prompt: "So every given: block finds its counterpart somewhere? I think thats important to keep the feature understandable!" — then "Why not simply allow expression: 0?", "Is that rule to narrow?", "Go", and on the printing: "I think the ellipsis might be the most clear one…", "Fold it into 742". Later: "I think an empty expression should be marked explicitly", and "I think we should have an explicit flag".

Note

The following content was generated by AI.

An expressions: entry written empty: true over a dims: is an empty sum: the file declares the name, and other files add the terms. A term lands only on a declared expressions: block, empty or bodied. Alone, the sum prints as injection = ⋯.

Based on main, which carries #741, #731 and #732. The empty sum is #741's rule 1 with no body. #743 is merged into this branch. #758 wrote the same feature with expression: null. It is closed, and its explicit spelling is here as a flag.

The rule

A given: entry always assumes one upstream, and the upstream is always a regular block. For a parameter, a column or a row family, that was already so. For an expression it now is too. The owner declares the name under expressions:. It writes a body if it has one of its own, and empty: true if the components supply all of it. A reading with no term still folds into that block. A term lands on that block and nowhere else, so a mistyped target is refused as "no fragment declares it".

# network.yaml owns the sum, and adds nothing to it
expressions:
  injection:
    dims: [snapshot, bus]
    empty: true
    description: what the components put into a bus

# generators.yaml, unchanged
expressions:
  generation: sum(dispatch, by=gen_bus, over=generator, into=bus)
given:
  expressions:
    injection: { dims: [snapshot, bus], term: generation }

The owner writes	Alone, the name is	Composed, the body is
injection: { dims: [snapshot, bus], empty: true }	a column over the frame	the terms
injection: shed - load	its body	(shed - load) + terms
injection: { dims: [snapshot, bus] }	refused: neither expression: nor cases:, and the message names empty: true	—

empty defaults to false, and a spec writes it only where it is true. It is refused beside expression:, cases: or otherwise:, and it needs a dims:. The composed block has a body and keeps the owner's frame, so a later merge adds to it like any bodied expression. The composed load holds every term to the frame by #741's rule 2.

What this changes

• Schema. ExpressionBlock gains empty: bool = False. An entry with empty: true and a dims: has no body. An entry with no body and no empty: true is refused as having neither form, and the refusal names the flag. The flag is serialised only where it is true.
• Load. An empty sum resolves as a column over its frame, through the same path a given expression takes. Namespace.bodies is the set of names that resolve to a body, and the expression and where resolvers read it instead of schema.expressions. lowering puts the empty sum under program.given.expressions with empty set, since a host or merge must provide it. It does not go under program.expressions, which holds bodies. ExpressionDeclaration is untouched.
• Advice. One note says the file declares a sum other files fill.
• Typesetting. The owner declares the name, so the sum prints under Definitions and not under Given. Its line is symbol = ⋯ over its frame, last among the definitions, under either inline_expressions setting, and its legend row sits with the definitions. typeset_declaration prints that line. Where the name is read, it prints as a column, as before. Each format spells the ellipsis (\cdots, dots.c) the way it spells the dash: as a format spelling, not an operator. So the operator census of the golden model is untouched. A contributor's page is as refactor(language): a term prints as the definition it is, and one rule folds every reading #738 left it: the term prints as its own definition, and the Given line names what it adds to.
• Merge. _landed accepts a declared name and nothing else. The "reads or uses" anchors are gone, and so are the Variable and walk imports. _summed writes the terms alone onto an empty block, and body + terms onto a bodied one. It keeps the owner's dims, and it does not carry empty. _definer_frame is the owner's declared frame where there is one.
• Override. A patch empties a bodied definition with {expression: null, empty: true, dims: [...]}. The null drops the body and the flag marks the sum, so neither spelling means two things.
• Docs. The tutorial's network.yaml declares the sum empty: true. Its check prints the new note, and "Leave the network out" prints the new refusal. The reference section "A term a file adds" shows the owner as an empty sum, and states the landing rule and how the sum prints. The named-expressions page defines the empty sum and its flag beside feat(language): a named expression may declare the frame it is read over #741's frame. The typeset page lists it among the definitions. reading.md names empty, and the how-to table's row follows. From docs: a file restates a shared dimension as its dtype alone, and merge carries the one description written for it #743, the tutorial's files after the first restate a shared dimension as a dtype alone.

Why

The sum was the one name whose regular block existed only in the composed spec, written by merge from a reading. That was the confusing part of the design. expression: 0 cannot be that block: alone, it is a row with no variable, and its frame is not one the body carries. Both are refused for good reasons.

A frame with no body was the first spelling here. It made a forgotten body load silently as an empty sum. expression: null (#758) was explicit, but a null means absent everywhere else: output drops it, and an override patch uses it to remove a field. empty: true is explicit, and it leaves the null with one meaning. The program flag has the same name as the file's key.

A Given row said another file provides the name. That is true for a consumer and false for the file, which declares the name. A definition with an open body says what the file states and no more, and leaves Given to names another file defines.

Method, guards, the retarget, gates, what was not done

Guards, each with the test that fails without it (tests/test_terms.py).

• At load: test_an_empty_sum_loads_alone_and_reads_as_a_column, test_an_empty_sum_round_trips and test_empty_false_is_the_default_and_is_not_written. test_an_empty_sum_is_written_as_empty_true_over_a_frame has five cases: no frame, a frame and no body, empty: false and no body, beside a body, and beside cases.
• At merge: test_a_reading_is_no_place_for_a_term_to_land, where neither a reader nor a contributor's own use anchors a term. test_terms_that_land_on_no_name_are_refused checks the new message. test_the_composed_sum_keeps_the_owner_s_frame checks that the composed load refuses a term wider than the owner's frame. test_a_patch_empties_a_definition checks the override.
• Printing: test_the_owner_s_sum_prints_as_a_definition_with_no_body pins the ellipsis line, the Definitions legend row and the absence of a Given section. The advice note and the no-line refusals for a reader and a contributor are pinned too.

Mutation table for the flag commit 98ad950: each guard was removed by hand, then restored with git checkout --, __pycache__ was dropped, and the tree was clean after.

Guard removed	Result
empty: true refused beside a body	caught: [beside-a-body], [beside-cases]
empty: true needs dims:	caught: [no-frame]
a frame with no body is refused	caught: 3 failed, including test_composition.py::…[short-of-what-it-says]
empty: true written back	caught: test_an_empty_sum_round_trips

The golden model declares no empty sum. check accepts the fixture without output, and an empty sum draws advice until its terms arrive. So the one walk line that renders the ellipsis is listed in UNREACHABLE with that reason, and test_terms.py reaches it. The golden output is unchanged.

Fixtures. tests/fixtures.py gains NETWORK, the owner of the empty sum. BALANCE, the reader, stays for the tests of readings. In test_terms.py, every merge that anchored on the reader now anchors on the owner. The file that defines injection as its slack is SLACKED.

test_composition.py is back as it is on main. A frame with no body is partial again, so {'expressions': {'spend': {'dims': ['snapshot']}}} is refused as short of what it says.

The retarget. #732 landed on main as the squash 74c36d6. Its tree is identical to feat/composition at fc464a7 (git diff is empty). This took three merge commits and no force-push:

1. 5190229 merges fc464a7, the one feat(language): a spec is composed from files that each state part of it, and patched with files that each change part of it #732 commit this branch lacked. Its one conflict was in Namespace.__init__.
2. 88e8ccc merges main at 74c36d6 with -s ours. All 19 conflicts from the squash are resolved to this branch's side, since step 1 already brought in main's content.
3. 63e4b8c merges main at 8e4765a, which brings docs(notation): the notation page shows a named expression whose declared frame is wider than its body #756. The one conflict was the changelog, which keeps both lines.

Then 98ad950 changes the spelling to the flag, as a fast-forward.

Gates. Pixi cannot be installed in this container. I ran each gate in a Python 3.12 uv virtualenv with pytest, pytest-xdist, coverage, typst, pyrefly==1.2.0 and ruff==0.16.1, on 98ad950:

pytest -n auto                              2114 passed
ruff check . / ruff format --check .        clean
pyrefly check                               0 errors
typos                                       clean
prettier --check docs CHANGELOG.md examples mkdocs.yml   clean
tools.schema / tests.typesetting.golden / tools.notation / tools.gallery   regenerated; only the schema changed
zensical build --strict                     one warning: the docs.python.org inventory, which the proxy blocks (main has the same warning)

Not run: compile-tex, reuse lint, zizmor, taplo.

Not done.

• The PyPSA split takes this rule in fix(typeset): a substituted term prints its leading minus as a subtraction, and the PyPSA split has a page per fragment #740: network, power_flow and settings declare the nine sums. Those nine entries now need empty: true, and fix(typeset): a substituted term prints its leading minus as a subtraction, and the PyPSA split has a page per fragment #740 fails to load until it merges this head and adds the flag.
• The owner cannot add its own term through a given: entry, because the collision rule refuses it. It writes its own contribution as its body, which is the second row of the table above.

🤖 Generated with Claude Code

https://claude.ai/code/session_01CQxVP5uX2V4rpvJNPhbyR2

[read-the-docs-community]

Documentation build overview

📚 mathspec | 🛠️ Build #34806719 | 📁 Comparing 98ad950 against latest (0efbf59)

  🔍 Preview build  

22 files changed · + 8 added · ± 14 modified

+ Added

• several-files/index.html
• examples/library/index.html
• howto/compare/index.html
• howto/compose/index.html
• examples/library/composed/index.html
• examples/library/generator/index.html
• examples/library/load/index.html
• examples/library/surface/index.html

± Modified

• changelog/index.html
• examples/index.html
• about/limits/index.html
• reference/api/index.html
• reference/glossary/index.html
• reference/language/index.html
• reference/notation/index.html
• reference/program/index.html
• reference/reading/index.html
• reference/typeset/index.html
• and 4 more...