fix(typeset): a substituted term prints its leading minus as a subtraction, and the PyPSA split has a page per fragment

[FBumann]

Prompt: "Can we improve/simplify the pypsa proof? Does it read well? Can it be looked at nivcely in the docs?" — then "Do it as another stacked PR", and, on the empty sum: "I thought only one of the files will hold the empty sum at the end? The others either contribute or just read" — "Do it".

Note

The following content was generated by AI.

examples/pypsa.yaml writes each of its nine hubs as a sum of named terms with a declared frame, so check is one canonical comparison and the splitter loses its row algebra. In the split, one fragment declares each sum as an expression with a frame and no body, the others contribute or read. The split gets an index and a page per fragment under "PyPSA in 24 files". core.yaml is settings.yaml.

Stacked on #736. It carries #742 by merge commit until #742 lands in feat/composition and #736 takes the base; the empty sum is #742's rule.

What this changes

• The one file names its terms, and frames its sums. Bus_nodal_balance reads Bus_injection == 0, Bus_injection is Generator_injection + … + Transformer_injection over [scenario, snapshot, bus], and each term is a named expression, forty in all, for the nine hubs. The canonical form of the file is unchanged apart from the nine frames, which feat(language): a named expression may declare the frame it is read over #741 admits and which are what the terms are held to.
• One owner per sum. network declares Bus_injection, power_flow declares Cycle_angle_sum, and settings declares the seven totals, each with its frame and description and no body. Every other fragment either adds a term through its given: entry or reads the name under given:. Leaving an owner out while a contributor is in is refused with "no fragment declares it".
• The tool is 415 lines, from 578. Model reads the hubs and their terms off the file instead of computing them; the rewrite machinery, same_rows, _inlined, _row, _written and _share are gone. check loads each fragment, merges them, and compares canonical forms with the one file. split is the bridge until you decide which side is authored.
• settings.yaml, not core.yaml: the weightings, the risk preference, the flags every topic reads, and the seven totals whose own readers a model may leave out.
• Pages. docs/examples/pypsa/index.md says what the split is and carries two generated tables: each sum with its frame, the fragment that declares it and the terms by the fragment that adds each; and each fragment with what it declares, reads and adds to. One generated page per fragment shows the file and its math in the one file's symbols; the three owner pages print each sum they declare as symbol = ⋯ under Definitions, as feat(language): a sum other files add terms to is declared as an expression with empty: true #742 renders an empty sum. All 25 sit under "Proofs of concept" as "PyPSA in 24 files", and tools/gallery.py renders them like the library pages, so tests/test_docs.py holds them current.
• The one-file page keeps its balance rows. A row that reads a hub, hub == 0 over a sum of named expressions, prints with the sum substituted in, as the file wrote it before each term had a name. The terms and the hubs then print once each as definitions.
• The typesetter fix. Substituting a named term that opens with a minus printed a + -b, and one that is itself a sum printed a + -b + c. Walk._substituted unwraps a plain named expression before the sign folding, and a right-hand sum is re-associated to the left, so both print as written out: a - b and a - b + c. This is what makes the balance rows read as before. The golden model gains net, a plain expression whose body is -spill + slack, and netted, which adds it on the right of a plus, so the line-coverage guard reaches both new lines; the notation page shows them under "Named expressions".

Why

The proof kept two sources of truth in lockstep with a generator and a row comparison, because the one file wrote each balance inline while the fragments wrote it as named terms. Naming the terms in the one file removes the difference, and gives every component's contribution a name there too. With #742, the sum's regular block lives in a fragment somebody wrote, which is what makes the split readable: every given: entry in it points at a block in one other file. Nothing showed the split in the docs; the library pages already had the shape to copy.

Method, gates, what was not done

The rewrite. A one-off script took the old tool's Model.data, which already held every hub as a sum and every term's body, and edited pypsa.yaml in place: the two rows' expressions, the seven hub expressions with their terms inserted before them, and the two balance hubs with their terms at the end of expressions:. canonical_yaml(to_spec(new file)) == canonical_yaml(to_spec(Model.data)) held before the tool was touched. Terms that fit on a line are written as name: body. The frames were added to the nine hub blocks in a second pass, so the composed sums, which keep their owner's frame, and the one file have one canonical form.

Guards. test_a_substituted_term_that_opens_with_a_minus_prints_as_a_subtraction fails without either half of the typesetter fix, and test_the_golden_model_reaches_every_line_of_the_walk failed on CI until the golden model carried the case (it skips where coverage is not installed, which is why it did not fail here first). test_the_fragments_merge_to_the_one_file is the check; test_every_sum_is_declared_empty_with_its_description_in_one_fragment pins one owner per sum; test_leaving_out_the_owner_of_a_sum_no_model_goes_without_is_refused pins the refusal. test_the_one_file_with_its_hubs_as_sums_states_the_rows_of_pypsa_yaml is gone with the row comparison it tested.

Gates. Pixi cannot be installed in this container. In a Python 3.12 uv virtualenv with the runtime pins of pixi.toml plus coverage, on the head that carries #742's ellipsis rendering:

pytest tests -n 8                         2501 passed, 45 skipped
ruff check . / ruff format --check .      clean
pyrefly check                             0 errors (9 suppressed)
prettier --check docs CHANGELOG.md examples mkdocs.yml   clean
python -m tools.gallery --check           34 page(s) current
python -m tools.notation --check          current
python -m tools.schema                    no diff
python -m tools.pypsa_split check examples/pypsa   24/24 load alone, one canonical form

Not run: docs-build, compile-tex, the PyPSA reference solves, typos, reuse lint, zizmor, taplo. The skips beyond #736's count are the docs-feature tests, which the bare environment skips.

Not done.

• The terms carry no descriptions. Their names say what they are; prose would be forty sentences to write by hand, and the split copies whatever the one file says.
• The per-fragment pages carry one sentence of prose each. The library pages have more, and these can grow the same way.
• Which of the one file and the fragments is authored is still open. The generator stays until it is decided.

🤖 Generated with Claude Code

https://claude.ai/code/session_01H1F2gprjeiGPnvDaWjZwBB

[read-the-docs-community]

Documentation build overview

📚 mathspec | 🛠️ Build #34773177 | 📁 Comparing 695febe against latest (0efbf59)

  🔍 Preview build  

52 files changed · + 32 added · ± 16 modified · - 4 deleted

+ 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
• examples/pypsa/carrier/index.html
• examples/pypsa/cost/index.html
• and 22 more...

± Modified

• changelog/index.html
• examples/index.html
• about/limits/index.html
• examples/pypsa/index.html
• examples/pypsa_linearized_uc/index.html
• reference/api/index.html
• reference/glossary/index.html
• reference/language/index.html
• reference/notation/index.html
• reference/program/index.html
• and 6 more...

- Deleted

• examples/pypsa_losses/index.html
• examples/pypsa_multi_period/index.html
• examples/pypsa_quadratic/index.html
• examples/pypsa_stochastic/index.html

[FBumann]

Prompt: should we then combine 736 and 740 into one PR? — "Yes"

Note

The following content was generated by AI.

This PR is closed. Its PyPSA work is merged into #736 as 1cbdeec, with the owner blocks written empty: true. Its typesetter fix landed separately as #759.

---

Generated by Claude Code