docs: a link's delivery lags its flow, wrapping or losing what is in transit at the horizon's edge

[FBumann]

Prompt: Lets fix that! Do a PR implementing it, adjusting the docs etc. And closing the issue

Note

The following content was generated by AI.

Link delay is now stated on the ladder. A port's delivery is shift(…, offset=Link_output_delay, edge=…), and a cases: block on Link_output_cyclic_delay picks edge='wrap' (cyclic) or edge=0 (lost). Closes #75; the weighted case is #299.

Why #75 closes rather than ships

#75 asked for edge=<parameter> — a per-link number. But wrap is a quoted keyword, never a value, so a parameter could never have carried the wrap/lose choice. That choice is a branch, and the shipped cases: (#168) carries it. So #75 is superseded, not implemented.

The uniform-weighting boundary (a decision to flag)

PyPSA measures delay as a duration in snapshot_weightings.generators units and resolves it through cumulative time. A positional shift(offset=n) reproduces that only when that column is uniform — which is why rung 16 is the one rung with a uniform generators column (objective/stores stay non-uniform, so no cost or storage factor passes as identity). Under a non-uniform column PyPSA resamples per snapshot — a shift that varies along the axis it translates, which the language refuses. That residual is filed as #299, and the rung prose says so plainly.

Verification

• pixi run ci — 904 passed, mkdocs build --strict, compile-tex compiled all 27 documents (the new \overrightarrow{f} arrival renders and compiles in LaTeX).
• reference.py --check — every rung solves to its record; only rung_16 added (objective 5262.5, 52 rows), no existing rung's numbers moved.
• The rung network was built and solved with PyPSA 1.3.0 via uv; the delay=2 cyclic pipe serves all load from the cheap source, the delay=1 non-cyclic pipe drops the first snapshot to expensive backup — both cases: arms exercised, and the two links differ in both delay (the offset parameter) and cyclic_delay (the branch).
• The delay↔shift mapping was read from _Multiport._delay_positions in pypsa 1.3.0 and checked position-for-position under uniform and non-uniform weightings.

Deliberately not done / departed defaults

• Delay is its own standalone rung (16), not folded into rung 9. Rung 9 is spine-based, and the spine's generators weighting is non-uniform by design — it cannot host a positional delay. Rung 9 is narrowed to "multi-link"; its delay row moves to rung 16.
• A follow-up issue (duration-weighted link delay is a per-snapshot resample, above shift's positional reach #299) was opened for the weighted-duration case rather than forcing it into scope here.
• Named expression Link_output_arrival is symbolized (\overrightarrow{f}) and not expanded on the page, exactly as StorageUnit_charge_carried_in is — its cases: body lives in examples/pypsa.yaml.

[read-the-docs-community]

Documentation build overview

📚 math-spec | 🛠️ Build #34316661 | 📁 Comparing dee5a9a against latest (2d2f140)

  🔍 Preview build  

1 file changed

± examples/pypsa/index.html