docs(pypsa): the outage factors of a security-constrained run come from each investment period's own branches

[FabianHofmann]

Prompt: "1" (start Wave 1 of the #783 plan: the linearized-UC patch file, outage factors per period, and drafts of the unfiled PyPSA bugs)

Note

The following content was generated by AI.

Line_BODF and Transformer_BODF now span period: each period's outage factors come from its own active branches. Rung 68 records PyPSA/PyPSA#1971: intended 13000.0, PyPSA 8050.0. Part of #783.

Method, gate output, what is not done

What changed

• examples/pypsa.yaml: Line_BODF and Transformer_BODF span [period, …, outage]. A row exists only where the branch and the outage are active in the period and share a sub-network of that period. The eight security blocks read the factor with at(…, by=snapshot_period, over=period, into=snapshot), in the where and in the expression, as Line_angle_sum reads the cycle weights since docs(pypsa): the cycle rows read each investment period's own cycle basis #814. No language work was needed. examples/pypsa/security.yaml and the pages are regenerated.
• Rung 68 (rung_68_outage_factors_per_period.py), ISSUE = 1971. Buses a, b; lines ab68 (both periods) and ab_old68 (build_year=2000, lifetime=25, so 2020 only), both rated 60; outage ab_old68. In 2020 its factor on ab68 is +1, so the import is at most 60. PyPSA builds no security row and raises no error, imports up to 120, and solves to 8050.0. The network has no build to decide, so each period solves on its own. The oracle is the same network once per period (network([2020]), network([2030])): in a network of one period, the last period is that period, so PyPSA's factors are correct there. Oracle objectives 7600.0 + 5400.0 = 13000.0. reference.py is unchanged.
• docs/examples/pypsa.md: rung 30 says the factors span period; its row "a branch not active in a period" now says the file builds no copy there; a new row "outage factors of a period other than the last" (diverges, rung 68). Rung 66's text and row: the file no longer builds the 2020 copies of ca66. It builds 6 of PyPSA's 12 rows per bound, not 10; PyPSA's other 2020 copies repeat a plain limit or are empty, so the feasible set is the same. New rung 68 section. New data-prep step: outage factors come from each period's active branches.

PyPSA cites (02bdcbba)

abstract.py:443-460 (one BODF per sub-network after create_model, applied to all snapshots), constraints.py:1641 (last topology call is the last period's cycle loop), networks.py:1278-1281 (an inactive branch loses its sub_network).

Gates

• pixi run python -m tools.pypsa_split split examples/pypsa, check: 24/24 fragments load alone, one canonical form.
• pixi run python -m tools.gallery: regenerated docs/examples/pypsa.md, docs/examples/pypsa/security.md.
• uv run --script examples/references/pypsa/reference.py: only rung_68_outage_factors_per_period is new in references.json; every other record is unchanged. --check: "every rung solves to its record".
• pixi run lint: pass. pixi run ci: exit 0, 2659 passed, docs-build and compile-tex done.

Not run, not done

• No engine solves the file on rung 68's data; the intended objective comes from the PyPSA oracle only. Data prep is described, not implemented in this repo.
• Rung 68 tests only the missing outage. The second effect of #1971, wrong factors in an earlier period for a branch that stands in both, has no rung. The MRE in #1971 shows it.
• No PyPSA parity with master: open points, new master changes and the PyPSA bugs found #783 box ticked, and the issue body is not edited.
• No PyPSA issue filed or commented.

[read-the-docs-community]

Documentation build overview

📚 mathspec | 🛠️ Build #34896666 | 📁 Comparing d8e8561 against latest (8f1c7b3)

  🔍 Preview build  

2 files changed

± changelog/index.html
± examples/pypsa/security/index.html