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

.prettierignore

@@ -19,15 +19,12 @@ docs/examples/dispatch.md
 docs/examples/commitment.md
 docs/examples/operators.md
 docs/examples/pypsa.md
-docs/examples/pypsa_quadratic.md
 docs/examples/pypsa_linearized_uc.md
-docs/examples/pypsa_losses.md
-docs/examples/pypsa_stochastic.md
-docs/examples/pypsa_multi_period.md
 docs/examples/library/surface.md
 docs/examples/library/generator.md
 docs/examples/library/load.md
 docs/examples/library/composed.md
+docs/examples/pypsa/*.md
 
 # The PyPSA reference scripts write this file; prettier would reformat what
 # they stamp, and the two would fight over it exactly as above.

CHANGELOG.md

@@ -12,6 +12,8 @@ it releases that version ([RELEASING.md](https://github.com/energy-models/mathsp
 
 ## Upcoming version
 
+- docs(pypsa): a single spec covers every pypsa model class and component ([#620](https://github.com/energy-models/mathspec/pull/620))
+- 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 ([#736](https://github.com/energy-models/mathspec/pull/736))
 - fix(typeset): a substituted term that opens with a minus prints as a subtraction ([#759](https://github.com/energy-models/mathspec/pull/759))
 - docs: a file restates a shared dimension as its dtype alone, and `merge` carries the one description written for it ([#743](https://github.com/energy-models/mathspec/pull/743))
 - feat(language): a sum other files add terms to is declared as an expression with `empty: true` ([#742](https://github.com/energy-models/mathspec/pull/742))
@@ -23,6 +25,7 @@ it releases that version ([RELEASING.md](https://github.com/energy-models/mathsp
 - refactor(language): a term prints as the definition it is, and one rule folds every reading ([#738](https://github.com/energy-models/mathspec/pull/738))
 - feat(language): two files that state the same spec write one text, and `canonical --check` fails a file that is not in it ([#731](https://github.com/energy-models/mathspec/pull/731))
 - fix(language): a merged spec's descriptions do not depend on the order the fragments are passed in, and a reader's fills one its owner left out ([#739](https://github.com/energy-models/mathspec/pull/739))
+- docs(pypsa): an efficiency, a rate or a phase shift may change from snapshot to snapshot ([#717](https://github.com/energy-models/mathspec/pull/717))
 
 ## 0.2.0 (2026-09-25)
 

docs/examples/index.md

@@ -19,6 +19,7 @@ Every spec is a file under `examples/` in the repository.
   composed page shows what `merge` returns.
 
 The PyPSA parity pages, from [PyPSA in one file](pypsa.md) on, are a proof of
-concept. They sit in the Development section.
+concept. They sit in the Development section, and
+[PyPSA in 24 files](pypsa/index.md) is the same spec composed from fragments.
 
 [Typeset the math](../reference/typeset.md) prints your own.

docs/examples/pypsa/carrier.md

@@ -0,0 +1,107 @@
+<!--
+SPDX-FileCopyrightText: mathspec contributors
+SPDX-License-Identifier: CC-BY-4.0
+-->
+
+# Carriers
+
+One of the [24 fragments](index.md) of `examples/pypsa.yaml`: the growth limits per carrier, which read `Carrier_additions`. It reads `Carrier_additions` under [`given`](../../reference/language/declarations.md#given).
+
+<!-- gallery:begin -->
+```yaml
+dimensions:
+  period:
+    description: investment periods — PyPSA's `investment_periods`
+    dtype: int
+  carrier:
+    description: energy carriers, what a growth limit is set per
+
+parameters:
+  Carrier_max_growth:
+    description: >-
+      most capacity of a carrier that may be added in a period; no value means
+      no limit. The least over the scenarios, as PyPSA takes it
+      (`global_constraints.py:226-230`), data prep. PyPSA reads it only under
+      `multi_investment_periods` (`global_constraints.py:219-220`), so data
+      prep feeds no value otherwise
+    dims: [carrier]
+  Carrier_max_relative_growth:
+    description: >-
+      share of the previous period's additions that may be added on top — the
+      least over the scenarios, as PyPSA takes it, data prep
+    dims: [carrier]
+
+given:
+  expressions:
+    Carrier_additions: { dims: [period, carrier] }
+
+expressions:
+  Carrier_relative_growth:
+    description: >-
+      the share of the previous period's additions a carrier's growth limit
+      reads — PyPSA's `max_relative_growth` clipped at zero, so a negative
+      share adds nothing and never tightens the limit
+    dims: [carrier]
+    cases:
+      positive: { when: Carrier_max_relative_growth > 0, expression: Carrier_max_relative_growth }
+    otherwise: 0
+
+constraints:
+  Carrier_growth_limit:
+    description: >-
+      `Carrier-growth_limit` — what a carrier adds across its extendable components in a period,
+      counting each build in the first period it stands in, is at most its allowance plus a share of
+      what it added the period before; the first period has no predecessor, so `edge=0` leaves it the
+      bare allowance
+    dims: [carrier, period]
+    where: Carrier_max_growth
+    expression: >-
+      Carrier_additions
+      - shift(Carrier_additions, along=period, offset=1, edge=0) * Carrier_relative_growth
+      <= Carrier_max_growth
+```
+
+#### Sets
+
+| Symbol | Meaning |
+|---|---|
+| $`\mathcal{Y}`$ | index $`y`$ — `period` — investment periods — PyPSA's `investment_periods` |
+| $`\mathcal{I}`$ | index $`i`$ — `carrier` — energy carriers, what a growth limit is set per |
+
+#### Parameters
+
+| Symbol | Meaning |
+|---|---|
+| $`\overline{\Delta}`$ | `Carrier_max_growth` over $`\mathcal{I}`$ — most capacity of a carrier that may be added in a period; no value means no limit. The least over the scenarios, as PyPSA takes it (`global_constraints.py:226-230`), data prep. PyPSA reads it only under `multi_investment_periods` (`global_constraints.py:219-220`), so data prep feeds no value otherwise |
+| $`\mathrm{r}`$ | `Carrier_max_relative_growth` over $`\mathcal{I}`$ — share of the previous period's additions that may be added on top — the least over the scenarios, as PyPSA takes it, data prep |
+
+#### Given
+
+| Symbol | Meaning |
+|---|---|
+| $`\mathit{Carrier\_additions}`$ | `Carrier_additions` over $`\mathcal{Y} \times \mathcal{I}`$, an expression another file defines |
+
+#### Definitions
+
+| Symbol | Meaning |
+|---|---|
+| $`\mathrm{r}^{+}`$ | `Carrier_relative_growth` over $`\mathcal{I}`$ — the share of the previous period's additions a carrier's growth limit reads — PyPSA's `max_relative_growth` clipped at zero, so a negative share adds nothing and never tightens the limit |
+
+$`t \boxminus_{v} k`$ denotes translation with $`v`$ standing where index $`t-k`$ leaves the dimension (`shift(edge=v)`), so the row at that boundary is built and carries $`v`$ rather than being dropped.
+
+#### Subject to
+
+**`Carrier_growth_limit`**
+
+```math
+\mathit{Carrier\_additions}_{y,i} - \mathit{Carrier\_additions}_{y \boxminus_{0} 1,i} \cdot \mathrm{r}^{+}_{i} \le \overline{\Delta}_{i} \qquad \forall\, i \in \mathcal{I},\ y \in \mathcal{Y} \,:\, \overline{\Delta}_{i} \text{ is defined}
+```
+
+#### Definitions
+
+**`Carrier_relative_growth`**
+
+```math
+\mathrm{r}^{+}_{i} = \begin{cases} \mathrm{r}_{i} & \text{if } \mathrm{r}_{i} > 0 \\ 0 & \text{otherwise} \end{cases} \qquad \forall\, i \in \mathcal{I}
+```
+<!-- gallery:end -->

docs/examples/pypsa/cost.md

@@ -0,0 +1,129 @@
+<!--
+SPDX-FileCopyrightText: mathspec contributors
+SPDX-License-Identifier: CC-BY-4.0
+-->
+
+# The cost
+
+One of the [24 fragments](index.md) of `examples/pypsa.yaml`: the objective: the expected operating cost and its tail, weighted by scenario. It reads `CVaR_omega`, `scenario_opex`, `scenario_weight` under [`given`](../../reference/language/declarations.md#given).
+
+<!-- gallery:begin -->
+```yaml
+dimensions:
+  scenario:
+    description: the futures dispatch is chosen in, each with a weight
+
+parameters:
+  CVaR_inv_tail:
+    description: PyPSA's `1 / (1 - alpha)` — the tail's own probability, inverted in data prep because a divisor is one factor
+    dims: []
+
+variables:
+  CVaR_a:
+    description: "`CVaR-a` — how far a scenario's operating cost exceeds the tail's start; nothing where it does not"
+    dims: [scenario]
+    bounds:
+      lower: 0
+  CVaR_theta:
+    description: "`CVaR-theta` — where the tail starts, the value at risk"
+    dims: []
+  CVaR:
+    description: "`CVaR` — the tail's average cost, what the objective prices at `omega`"
+    dims: []
+
+given:
+  parameters:
+    scenario_weight: { dims: [scenario] }
+    CVaR_omega: { dims: [] }
+  expressions:
+    scenario_opex: { dims: [scenario] }
+
+constraints:
+  CVaR_excess:
+    description: "`CVaR-excess-{s}` — a scenario's operating cost beyond the tail's start is its excess; PyPSA names one row per scenario"
+    dims: [scenario]
+    where: CVaR_omega > 0
+    expression: CVaR_a - scenario_opex + CVaR_theta >= 0
+  CVaR_def:
+    description: "`CVaR-def` — the tail's average is at least where it starts plus the expected excess over the tail's probability"
+    dims: []
+    where: CVaR_omega > 0
+    expression: CVaR_theta + CVaR_inv_tail * sum(scenario_weight * CVaR_a, over=scenario) <= CVaR
+
+objective:
+  sense: minimize
+  description: >-
+    capacity once per active period at its expected cost over the scenarios, operation in expectation over the scenarios, and a share of it at the tail
+  expression: >-
+    (1 - CVaR_omega) * sum(scenario_weight * scenario_opex, over=scenario)
+    + CVaR_omega * CVaR
+```
+
+#### Sets
+
+| Symbol | Meaning |
+|---|---|
+| $`\Xi`$ | index $`\xi`$ — `scenario` — the futures dispatch is chosen in, each with a weight |
+
+#### Parameters
+
+| Symbol | Meaning |
+|---|---|
+| $`\mathrm{v}`$ | `CVaR_inv_tail` (scalar) — PyPSA's `1 / (1 - alpha)` — the tail's own probability, inverted in data prep because a divisor is one factor |
+
+#### Variables
+
+| Symbol | Meaning |
+|---|---|
+| $`a`$ | `CVaR_a` over $`\Xi`$ — `CVaR-a` — how far a scenario's operating cost exceeds the tail's start; nothing where it does not |
+| $`\theta`$ | `CVaR_theta` (scalar) — `CVaR-theta` — where the tail starts, the value at risk |
+| $`CVaR`$ | `CVaR` (scalar) — `CVaR` — the tail's average cost, what the objective prices at `omega` |
+
+#### Given
+
+| Symbol | Meaning |
+|---|---|
+| $`\pi`$ | `scenario_weight` over $`\Xi`$, data another file declares |
+| $`\omega`$ | `CVaR_omega` (scalar), data another file declares |
+| $`\mathit{scenario\_opex}`$ | `scenario_opex` over $`\Xi`$, an expression another file defines |
+
+#### Objective
+
+```math
+\min \left( 1 - \omega \right) \cdot \left( \sum_{\xi \in \Xi} \pi_{\xi} \cdot \mathit{scenario\_opex}_{\xi} \right) + \omega \cdot CVaR
+```
+
+#### Subject to
+
+**`CVaR_excess`**
+
+```math
+a_{\xi} - \mathit{scenario\_opex}_{\xi} + \theta \ge 0 \qquad \forall\, \xi \in \Xi \,:\, \omega > 0
+```
+
+**`CVaR_def`**
+
+```math
+\theta + \mathrm{v} \cdot \left( \sum_{\xi \in \Xi} \pi_{\xi} \cdot a_{\xi} \right) \le CVaR \qquad \text{where } \omega > 0
+```
+
+#### Variable domains
+
+**`CVaR_a`**
+
+```math
+a_{\xi} \ge 0 \qquad \forall\, \xi \in \Xi
+```
+
+**`CVaR_theta`**
+
+```math
+\theta \in \mathbb{R}
+```
+
+**`CVaR`**
+
+```math
+CVaR \in \mathbb{R}
+```
+<!-- gallery:end -->