docs(pypsa): the cycle rows read each investment period's own cycle basis

[FabianHofmann]

Prompt: Continue PyPSA parity for energy-models/mathspec: implement step 4 of the plan in tracking issue #783. Step 4 covers the parity items the language can already state. Run it as an ultracode workflow with at most 4 agents, one PR per group.

Note

The following content was generated by AI.

Kirchhoff_Voltage_Law now reads the cycle basis of each snapshot's investment period, as PyPSA does. Rung 66 records a line that closes a mesh in 2030, and the empty security copies linopy counts. Part of #783; stacks on #787 and #786.

Method, gate output, PyPSA cites, what is not done

What changed

• examples/pypsa.yaml: Line_cycle_weight, Transformer_cycle_weight and Transformer_phase_shift_cycle_weight span [period, …, cycle]. Line_angle_sum and Transformer_angle_sum read them with at(…, by=snapshot_period, over=period, into=snapshot). The cycle dimension and Kirchhoff_Voltage_Law say that a label is a position in its period's basis. A cycle label that a period's basis does not reach has no weight there, so the row has no variable and is not built. No language work was needed.
• tests/test_pypsa_collapses.py: a standard parameter may gain a leading period as well as a leading scenario. With one period the frame collapses to the standard one. The docstring no longer calls period "mask-only".
• Rung 66 (rung_66_cycles_per_period.py): optimize_security_constrained(multi_investment_periods=True), outage ca66. Lines ab66, bc66 form a path in 2020. ca66 comes in with 2030 and closes a triangle. PyPSA builds 2 Kirchhoff-Voltage-Law rows (2030 only) and solves to 16000.0.
• docs/examples/pypsa.md: a rung 66 section; rows in the rung 6 and rung 15 tables; the rung 30 row "a branch not active in a period" now points at rung 66 and has the status split.

PyPSA cites (02bdcbba)

• Cycles per period: constraints.py:1640-1652. window.iter_periods() yields one (None, all snapshots) pair without multi_investment_periods (window.py:173-175). cycle_matrix(investment_period=…) drops the branches that are not active in that period (networks.py:1278-1281).
• Empty security rows: abstract.py:472-489. In rung 66 each of Line-fix-s-lower-security-… and -upper-… has 12 rows. 2 of them, 2020 × monitored ca66 × outage ca66, read +0 ≥ -40. The file builds the other 10 of each. The feasible set is the same.

Measured (this PR)

• A single basis over all branches would hold the 2020 snapshots to the triangle's row with ca66 absent. That forces zero flow on ab66 and bc66. PyPSA on the same network without those lines in 2020 solves to 43900.0, against 16000.0. The page cites this PR for the number.

Gates

• pixi run python -m tools.pypsa_split split examples/pypsa && pixi run python -m tools.gallery: regenerated examples/pypsa/{line,transformer,power_flow}.yaml and their pages.
• uv run --script examples/references/pypsa/reference.py: only rung_66_cycles_per_period is new in references.json. Every other record is unchanged.
• uv run --script examples/references/pypsa/reference.py --check: "every rung solves to its record".
• pixi run lint: pass. pixi run ci: exit 0, 2626 passed, docs-build and compile-tex done.

Not done, and found on the way

• PyPSA bug candidate, not filed and not in the file. optimize_security_constrained reads n.c.sub_networks after create_model (abstract.py:443-449). With periods, the last determine_network_topology call is the cycle loop of the last period (constraints.py:1641), which sets sub_network to NaN for branches that are not active then (networks.py:1278-1281). So the BODF comes from the last period's topology in every period, and an outage of a branch that is not active in the last period builds no row, without an error. Probe: the rung 66 network plus ab_old66 (a–b, build_year=2000, lifetime=25) with branch_outages=['ab_old66', 'ca66'] builds copies for ca66 only. The file's Line_BODF and Transformer_BODF span no period, so the file cannot state per-period factors yet. Rung 66 avoids the case: its only outage stands in the last period.
• The constraints.py:1654 vs :1660 question from docs(pypsa): the pypsa line references point at pypsa master #806 and docs(pypsa): a line or transformer limits its voltage angle difference, as in pypsa master #808: on 02bdcbba rung 55's KeyError is raised at constraints.py:1660 (tr.static.loc[…]). Line 1654 is the if "Transformer" in … test. The cite in Transformer_phase_shift_varying still says :1654. This PR does not change it; docs(pypsa): the pypsa line references point at pypsa master #806 owns line cites.
• Line_cycle_weight still cites networks.py:1354-1361 for the first scenario. On 02bdcbba the xs(self.scenarios[0]) calls are at networks.py:1334-1335 and :1351-1352. Left to docs(pypsa): the pypsa line references point at pypsa master #806.
• tests/fixtures/pypsa_standard_shape.yaml is unchanged. It freezes the standard frames, and the test now allows a leading period.
• No PyPSA parity with master: open points, new master changes and the PyPSA bugs found #783 box is ticked.

[read-the-docs-community]

Documentation build overview

📚 mathspec | 🛠️ Build #34894886 | 📁 Comparing 35e6259 against latest (34c68fd)

  🔍 Preview build  

16 files changed · ± 16 modified

± Modified

• changelog/index.html
• examples/pypsa_linearized_uc/index.html
• examples/pypsa/generator/index.html
• examples/pypsa/generator_commitment/index.html
• examples/pypsa/generator_maintenance/index.html
• examples/pypsa/line/index.html
• examples/pypsa/link/index.html
• examples/pypsa/link_commitment/index.html
• examples/pypsa/link_maintenance/index.html
• examples/pypsa/power_flow/index.html
• and 6 more...