docs(pypsa): the pypsa spec is also 24 topic files that merge back to it, each component adding its share of a sum by name

[FBumann]

Prompt: "Now, let's try to port the large pypsa docs pr over / In a separate branch / To test the design". Later: "Can we improve/simplify the pypsa proof? Does it read well? Can it be looked at nivcely in the docs?", and "should we then combine 736 and 740 into one PR?" — "Yes".

Note

The following content was generated by AI.

examples/pypsa.yaml is also 24 topic files that merge back to it in one canonical form. One fragment declares each of the nine sums as empty: true, and each component adds its share by name. Each fragment has a page.

This PR now carries #740, which is closed. It also merges #620 and #717, so the diff carries both. Based on main at b82076c (#742, #759).

What a fragment says, the check, the pages, gates, what was not done

What a fragment says

# network.yaml owns the sum
expressions:
  Bus_injection:
    dims: [scenario, snapshot, bus]
    empty: true
    description: …
constraints:
  Bus_nodal_balance: { dims: [scenario, snapshot, bus], expression: Bus_injection == 0 }

# load.yaml adds its share
given:
  expressions:
    Bus_injection: { dims: [scenario, snapshot, bus], term: Load_injection }
expressions:
  Load_injection: sum(Load_demand, by=Load_bus, over=load, into=bus)

• Owners. network owns Bus_injection, and power_flow owns Cycle_angle_sum. settings owns the seven totals whose readers (cost, carrier, global_constraints) a model may leave out. The file that was core.yaml is now settings.yaml.
• The one file names its terms. In pypsa.yaml, each of the nine sums is its terms by name over a declared frame, 40 terms in all. So the merged fragments and the one file have one canonical form.
• A missing owner is refused. Leaving out an owner while a contributor stays in is refused as "no fragment declares it". Leaving out a component leaves a whole model.

The check

python -m tools.pypsa_split check examples/pypsa loads each fragment alone, merges them, and compares the canonical form with the one file. The tool is 419 lines, down from 578, because it reads the sums and terms off the file. split is the bridge until you decide which side is the source.

Pages

docs/examples/pypsa/index.md has two generated tables: each sum with its owner and its terms, and each fragment with what it declares, reads and adds to. Each of the 24 fragments has a generated page. The three owner pages print each sum as symbol = ⋯. The pages sit under "Proofs of concept" as "PyPSA in 24 files", and tests/test_docs.py keeps them current.

How #740 was merged in

• The language, the typesetter and their tests keep main's side: feat(language): a sum other files add terms to is declared as an expression with empty: true #742 with empty: true, and fix(typeset): a substituted term that opens with a minus prints as a subtraction #759. src/, schema/ and the language tests equal main.
• The PyPSA files take fix(typeset): a substituted term prints its leading minus as a subtraction, and the PyPSA split has a page per fragment #740's side. The splitter writes empty: true on each owner block.
• The fragments and pages were regenerated from pypsa.yaml. They keep docs(pypsa): an efficiency, a rate or a phase shift may change from snapshot to snapshot #717's per-snapshot coefficients: the Link_efficiency and Process_rate lines are identical to this branch before the merge. docs(pypsa): an efficiency, a rate or a phase shift may change from snapshot to snapshot #717's rung 60 prose on docs/examples/pypsa.md is kept, and the generated blocks were regenerated.

Gates

Pixi cannot be installed in this container. In a Python 3.12 venv, on d69d0d8:

pytest -n auto                                   2560 passed
ruff check . / ruff format --check .             clean
pyrefly check                                    0 errors
typos, prettier --check                          clean
python -m tools.pypsa_split check examples/pypsa 24/24 load alone, one canonical form
python -m tools.gallery --check                  34 page(s) current
zensical build --strict                          one warning: the docs.python.org inventory, blocked by the proxy (main has the same)

Not run: compile-tex, the PyPSA reference solves, reuse lint, zizmor, taplo.

Not done

• It is still open which is the source, the one file or the fragments. The generator stays until that is decided.
• The terms have no descriptions, and each fragment page has one sentence of prose.
• chore: examples/pypsa/ cuts pypsa.yaml into 24 topic fragments that merge back to its rows #723 stays open until you decide. This PR supersedes it.

🤖 Generated with Claude Code

https://claude.ai/code/session_01CQxVP5uX2V4rpvJNPhbyR2