docs(pypsa): a line or transformer limits its voltage angle difference, as in pypsa master

[FabianHofmann]

Prompt: "2" (run steps 1 to 3 of the PyPSA-parity plan as one workflow)

Note

The following content was generated by AI.

pypsa.yaml states PyPSA master's six voltage angle rows (PyPSA#1910) over new v_ang_max, x_pu_eff and fixed-shift parameters. Rung 61 binds a line cap, a fixed-shift and a decided-shift transformer cap.

Part of #783 (step 3a, "Voltage angle limits"). Stacks on #787 and #786; base docs/pypsa-fixed-modular.

Method, gate output, alternatives

PyPSA read. constraints.py:1680-1782 on 02bdcbba, called at optimize.py:882.

• Assets: finite v_ang_max, in c.active_assets, rows masked by per-snapshot active. Lines only where carrier == "AC"; transformers have no carrier filter.
• cap = deg2rad(v_ang_max) / x_pu_eff. Line: s >= -cap, s <= cap.
• Transformer, fixed (phase_shift_min >= phase_shift_max): offset = deg2rad(phase_shift) / x_pu_eff, with phase_shift per snapshot; s >= -cap - offset, s <= cap - offset.
• Transformer, decided: s + Transformer-phase_shift * deg2rad / x_pu_eff in [-cap, cap]; the variable is in degrees.
• v_ang_min finite: DeprecationWarning, ignored.

Triage against docs/about/limits.md: no new construct. The rows are linear in existing operators; deg2rad is the literal 3.141592653589793 / 180. limits.md does not move.

File. Line_v_ang_max, Line_x_pu_eff [scenario, line]; Transformer_v_ang_max, Transformer_x_pu_eff [scenario, transformer], as s_nom. Transformer_phase_shift_fixed [snapshot, transformer], without scenario, as the other shift parameters; the Transformer_phase_shift_varying description now says the angle rows read them too. The variable Transformer_phase_shift holds the name, so the fixed shift is _fixed. Rows Line_v_ang_lower/upper (with Line_carrier == 'AC' in the where), Transformer_v_ang_lower/upper, Transformer_v_ang_var_lower/upper, in PyPSA's divided form, placed after the *_s_set rows. Symbols in examples/symbols/pypsa.yaml. Fragments and gallery pages regenerated.

Rung 61. Spine plus a radial line beside the link (cap 1°), a triangle with a fixed 2° shift (transformer cap 2.5°) and a triangle with a decided shift (cap 5°). In one cycle the angle caps couple, so each triangle carries one cap. PyPSA solves to 121834.62; with each cap removed: line 121161.89, fixed-shift transformer 35214.37, decided-shift transformer 111382.98, all three 24090.0. Duals on Line-v_ang-upper, Transformer-v_ang-lower and Transformer-v_ang-var-lower are nonzero.

Scenarios. With scenarios PyPSA builds no angle row and raises nothing (the #783 note, comment on PyPSA#1951). The rung has no scenario on purpose. The file states the rows per scenario; the docs table marks that case diverges, with no rung recording it.

Failing first. With the rung recorded and the file unchanged, tests/test_pypsa_references.py::test_pypsa_builds_no_row_the_files_do_not_declare failed: pypsa builds these and the files declare nothing that stands for them: ['Line-v_ang-lower', 'Line-v_ang-upper', 'Transformer-v_ang-lower', 'Transformer-v_ang-upper', 'Transformer-v_ang-var-lower', 'Transformer-v_ang-var-upper']. It passes after.

Cite. The KeyError of a transformer cycle with scenarios is raised at constraints.py:1660 (tr.static.loc[...]) on 02bdcbba, not at :1654 (the if "Transformer" in test), so the merge of main cites :1660 in Transformer_phase_shift_varying and in rung 55's prose.

Gates. pixi run lint passed. pixi run ci passed (2626 tests). uv run --script examples/references/pypsa/reference.py --check: every rung solves to its record. Re-recording changed only the rung_61 entry.

Not done. No engine solves the file against rung 61 here. No rung records the scenario divergence. v_ang_min has no parameter. No new data-prep note for x_pu_eff beyond the parameter descriptions. Nothing ticked in #783.

Departure. Commits carry no Co-Authored-By, per the user's global instruction.

[read-the-docs-community]

Documentation build overview

📚 mathspec | 🛠️ Build #34895214 | 📁 Comparing f8834e5 against latest (1b88c89)

  🔍 Preview build  

22 files changed · ± 22 modified

± Modified

• changelog/index.html
• examples/pypsa/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/generator_ramping/index.html
• examples/pypsa/line/index.html
• examples/pypsa/link/index.html
• examples/pypsa/link_commitment/index.html
• and 12 more...