docs: every spec in the docs and examples opens with its given block

CHANGELOG.md

@@ -12,6 +12,7 @@ it releases that version ([RELEASING.md](https://github.com/energy-models/mathsp
 
 ## Upcoming version
 
+- docs: every spec in the docs and examples opens with its given block ([#813](https://github.com/energy-models/mathspec/pull/813))
 - feat(spec)!: a spec written back out puts its given block first ([#818](https://github.com/energy-models/mathspec/pull/818))
 - feat(language)!: `missing:` says what a missing row means, a table short of a row is refused unless the file says otherwise, and a variable's `absence:` is now `missing:` ([#810](https://github.com/energy-models/mathspec/pull/810))
 - docs(pypsa): a risk preference with weight zero builds the CVaR variables and refuses quadratic costs, as in PyPSA ([#849](https://github.com/energy-models/mathspec/pull/849))

docs/examples/library/generator.md

@@ -32,19 +32,19 @@ description: >-
   PyPSA's `Generator`, wired to a port rather than straight to a bus, and cut
   to what a dispatch spec needs: a fixed build, no availability profile, no
   ramp limits.
-dimensions:
-  snapshot: { dtype: datetime, description: dispatch periods }
-  port: { dtype: str, description: "the connections components make, one label per connection" }
-  generator: { dtype: str, description: "generating units, each on one port" }
-relations:
-  Generator_port: { key: generator, values: port }
 given:
   variables:
     Port_p:
       dims: [snapshot, port]
       description: the surface introduces this flow, and this file pins it at its own ports
   expressions:
     total_cost: { dims: [] }
+dimensions:
+  snapshot: { dtype: datetime, description: dispatch periods }
+  port: { dtype: str, description: "the connections components make, one label per connection" }
+  generator: { dtype: str, description: "generating units, each on one port" }
+relations:
+  Generator_port: { key: generator, values: port }
 parameters:
   Generator_p_nom: { dims: [generator], description: nominal power }
   Generator_marginal_cost: { dims: [generator], description: cost of one unit of output }

docs/examples/library/load.md

@@ -15,17 +15,17 @@ withdrawal is a negative injection.
 <!-- gallery:begin -->
 ```yaml
 description: PyPSA's `Load`, wired to a port rather than straight to a bus. What it takes is data, so it decides nothing.
+given:
+  variables:
+    Port_p:
+      dims: [snapshot, port]
+      description: the surface introduces this flow, and this file pins it at its own ports
 dimensions:
   snapshot: { dtype: datetime, description: dispatch periods }
   port: { dtype: str, description: "the connections components make, one label per connection" }
   load: { dtype: str, description: "demands, each on one port" }
 relations:
   Load_port: { key: load, values: port }
-given:
-  variables:
-    Port_p:
-      dims: [snapshot, port]
-      description: the surface introduces this flow, and this file pins it at its own ports
 parameters:
   Load_p_set: { dims: [snapshot, load], description: "`Load-p_set` — what a load takes in a snapshot" }
 constraints:

docs/examples/library/surface.md

@@ -30,6 +30,9 @@ description: >-
   wired to a port, the port to a bus, and the balance names no component class.
   A flow is positive where the port injects into its bus. A component that
   costs something adds its cost to `total_cost`.
+given:
+  expressions:
+    total_cost: { dims: [], description: what running the system costs }
 dimensions:
   snapshot: { dtype: datetime, description: dispatch periods }
   bus: { dtype: str, description: network nodes }
@@ -45,9 +48,6 @@ constraints:
     description: "`Bus-nodal_balance` — what the ports on a bus put in nets to nothing"
     dims: [snapshot, bus]
     expression: sum(Port_p, over=port, by=Port_bus[bus]) == 0
-given:
-  expressions:
-    total_cost: { dims: [], description: what running the system costs }
 objective:
   sense: minimize
   expression: total_cost

docs/examples/pypsa/carrier.md

@@ -9,6 +9,10 @@ One of the [24 fragments](index.md) of `examples/pypsa.yaml`: the growth limits
 
 <!-- gallery:begin -->
 ```yaml
+given:
+  expressions:
+    Carrier_additions: { dims: [period, carrier] }
+
 dimensions:
   period:
     description: investment periods — PyPSA's `investment_periods`
@@ -33,10 +37,6 @@ parameters:
       least over the scenarios, as PyPSA takes it, data prep
     dims: [carrier]
 
-given:
-  expressions:
-    Carrier_additions: { dims: [period, carrier] }
-
 expressions:
   Carrier_relative_growth:
     description: >-

docs/examples/pypsa/cost.md

@@ -9,6 +9,14 @@ One of the [24 fragments](index.md) of `examples/pypsa.yaml`: the expected opera
 
 <!-- gallery:begin -->
 ```yaml
+given:
+  parameters:
+    scenario_weight: { dims: [scenario] }
+    CVaR_omega: { dims: [] }
+  expressions:
+    scenario_opex: { dims: [scenario] }
+    total_cost: { dims: [] }
+
 dimensions:
   scenario:
     description: the futures dispatch is chosen in, each with a weight
@@ -38,14 +46,6 @@ variables:
     where: CVaR_omega
     missing: neutral
 
-given:
-  parameters:
-    scenario_weight: { dims: [scenario] }
-    CVaR_omega: { dims: [] }
-  expressions:
-    scenario_opex: { dims: [scenario] }
-    total_cost: { dims: [] }
-
 expressions:
   risk_weighted_opex:
     expression: (1 - CVaR_omega) * sum(scenario_weight * scenario_opex, over=scenario) + CVaR_omega * CVaR

docs/examples/pypsa/generator.md

@@ -9,6 +9,28 @@ One of the [24 fragments](index.md) of `examples/pypsa.yaml`: PyPSA's `Generator
 
 <!-- gallery:begin -->
 ```yaml
+given:
+  parameters:
+    snapshot_weightings_objective: { dims: [snapshot] }
+    Generator_committable: { dims: [generator], dtype: bool }
+    Generator_maintenance_pu: { dims: [scenario, generator] }
+    scenario_weight: { dims: [scenario] }
+    CVaR_omega: { dims: [] }
+    period_weight_objective: { dims: [period] }
+    snapshot_weightings_generators: { dims: [snapshot] }
+  variables:
+    Generator_maintenance: { dims: [scenario, snapshot, generator] }
+    Generator_maintenance_capacity: { dims: [scenario, snapshot, generator] }
+  expressions:
+    GlobalConstraint_energy_weight: { dims: [scenario, global_constraint, snapshot] }
+    primary_energy: { dims: [scenario, global_constraint] }
+    operational_limit: { dims: [scenario, global_constraint] }
+    tech_capacity_expansion: { dims: [global_constraint] }
+    scenario_opex: { dims: [scenario] }
+    total_cost: { dims: [] }
+    Carrier_additions: { dims: [period, carrier] }
+    Bus_injection: { dims: [scenario, snapshot, bus] }
+
 dimensions:
   scenario:
     description: the futures dispatch is chosen in, each with a weight
@@ -164,28 +186,6 @@ variables:
     dims: [generator]
     where: Generator_p_nom_extendable
 
-given:
-  parameters:
-    snapshot_weightings_objective: { dims: [snapshot] }
-    Generator_committable: { dims: [generator], dtype: bool }
-    Generator_maintenance_pu: { dims: [scenario, generator] }
-    scenario_weight: { dims: [scenario] }
-    CVaR_omega: { dims: [] }
-    period_weight_objective: { dims: [period] }
-    snapshot_weightings_generators: { dims: [snapshot] }
-  variables:
-    Generator_maintenance: { dims: [scenario, snapshot, generator] }
-    Generator_maintenance_capacity: { dims: [scenario, snapshot, generator] }
-  expressions:
-    GlobalConstraint_energy_weight: { dims: [scenario, global_constraint, snapshot] }
-    primary_energy: { dims: [scenario, global_constraint] }
-    operational_limit: { dims: [scenario, global_constraint] }
-    tech_capacity_expansion: { dims: [global_constraint] }
-    scenario_opex: { dims: [scenario] }
-    total_cost: { dims: [] }
-    Carrier_additions: { dims: [period, carrier] }
-    Bus_injection: { dims: [scenario, snapshot, bus] }
-
 expressions:
   Generator_p_nom_effective:
     description: the build a generator's limits are taken against — the chosen one where it is extendable, the given one otherwise

docs/examples/pypsa/generator_commitment.md

@@ -9,6 +9,30 @@ One of the [24 fragments](index.md) of `examples/pypsa.yaml`: PyPSA's `Generator
 
 <!-- gallery:begin -->
 ```yaml
+given:
+  parameters:
+    snapshot_weightings_objective: { dims: [snapshot] }
+    Generator_p_nom: { dims: [scenario, generator] }
+    Generator_p_nom_extendable: { dims: [generator], dtype: bool }
+    Generator_p_min_pu: { dims: [scenario, snapshot, generator] }
+    Generator_p_max_pu: { dims: [scenario, snapshot, generator] }
+    Generator_p_nom_mod: { dims: [generator] }
+    Generator_modules_installed: { dims: [scenario, generator] }
+    Generator_p_min_pu_nonneg: { dims: [generator], dtype: bool }
+    Generator_maintenance_pu: { dims: [scenario, generator] }
+    period_weight_objective: { dims: [period] }
+    Generator_active: { dims: [snapshot, generator], dtype: bool }
+  variables:
+    Generator_p: { dims: [scenario, snapshot, generator] }
+    Generator_n_mod: { dims: [generator], domain: integer }
+    Generator_maintenance_capacity: { dims: [scenario, snapshot, generator] }
+    Generator_maintenance_status: { dims: [scenario, snapshot, generator] }
+    Generator_p_nom_ext: { dims: [generator] }
+  expressions:
+    scenario_opex: { dims: [scenario] }
+  masks:
+    Generator_committed: { dims: [snapshot, generator] }
+
 dimensions:
   scenario:
     description: the futures dispatch is chosen in, each with a weight
@@ -108,30 +132,6 @@ variables:
     bounds:
       lower: 0
 
-given:
-  parameters:
-    snapshot_weightings_objective: { dims: [snapshot] }
-    Generator_p_nom: { dims: [scenario, generator] }
-    Generator_p_nom_extendable: { dims: [generator], dtype: bool }
-    Generator_p_min_pu: { dims: [scenario, snapshot, generator] }
-    Generator_p_max_pu: { dims: [scenario, snapshot, generator] }
-    Generator_p_nom_mod: { dims: [generator] }
-    Generator_modules_installed: { dims: [scenario, generator] }
-    Generator_p_min_pu_nonneg: { dims: [generator], dtype: bool }
-    Generator_maintenance_pu: { dims: [scenario, generator] }
-    period_weight_objective: { dims: [period] }
-    Generator_active: { dims: [snapshot, generator], dtype: bool }
-  variables:
-    Generator_p: { dims: [scenario, snapshot, generator] }
-    Generator_n_mod: { dims: [generator], domain: integer }
-    Generator_maintenance_capacity: { dims: [scenario, snapshot, generator] }
-    Generator_maintenance_status: { dims: [scenario, snapshot, generator] }
-    Generator_p_nom_ext: { dims: [generator] }
-  expressions:
-    scenario_opex: { dims: [scenario] }
-  masks:
-    Generator_committed: { dims: [snapshot, generator] }
-
 expressions:
   Generator_previous_status:
     description: >-

docs/examples/pypsa/generator_maintenance.md

@@ -9,6 +9,21 @@ One of the [24 fragments](index.md) of `examples/pypsa.yaml`: PyPSA's `Generator
 
 <!-- gallery:begin -->
 ```yaml
+given:
+  parameters:
+    Generator_p_nom_extendable: { dims: [generator], dtype: bool }
+    Generator_committable: { dims: [generator], dtype: bool }
+    Generator_p_nom_mod: { dims: [generator] }
+    Generator_active: { dims: [snapshot, generator], dtype: bool }
+    snapshot_weightings_generators: { dims: [snapshot] }
+    Generator_p_nom_min: { dims: [scenario, generator] }
+    Generator_p_nom_max: { dims: [scenario, generator] }
+  variables:
+    Generator_status: { dims: [scenario, snapshot, generator], domain: integer }
+    Generator_p_nom_ext: { dims: [generator] }
+  masks:
+    Generator_committed: { dims: [snapshot, generator] }
+
 dimensions:
   scenario:
     description: the futures dispatch is chosen in, each with a weight
@@ -101,21 +116,6 @@ variables:
     bounds:
       lower: 0
 
-given:
-  parameters:
-    Generator_p_nom_extendable: { dims: [generator], dtype: bool }
-    Generator_committable: { dims: [generator], dtype: bool }
-    Generator_p_nom_mod: { dims: [generator] }
-    Generator_active: { dims: [snapshot, generator], dtype: bool }
-    snapshot_weightings_generators: { dims: [snapshot] }
-    Generator_p_nom_min: { dims: [scenario, generator] }
-    Generator_p_nom_max: { dims: [scenario, generator] }
-  variables:
-    Generator_status: { dims: [scenario, snapshot, generator], domain: integer }
-    Generator_p_nom_ext: { dims: [generator] }
-  masks:
-    Generator_committed: { dims: [snapshot, generator] }
-
 masks:
   Generator_maint_ext:
     description: >-

docs/examples/pypsa/generator_ramping.md

@@ -9,6 +9,27 @@ One of the [24 fragments](index.md) of `examples/pypsa.yaml`: PyPSA's `Generator
 
 <!-- gallery:begin -->
 ```yaml
+given:
+  parameters:
+    Generator_p_nom_extendable: { dims: [generator], dtype: bool }
+    Generator_committable: { dims: [generator], dtype: bool }
+    Generator_status_initial: { dims: [scenario, generator], dtype: int }
+    Generator_p_nom_mod: { dims: [generator] }
+    Generator_big_m: { dims: [scenario, generator] }
+    Generator_active: { dims: [snapshot, generator], dtype: bool }
+  variables:
+    Generator_p: { dims: [scenario, snapshot, generator] }
+    Generator_status: { dims: [scenario, snapshot, generator], domain: integer }
+    Generator_start_up: { dims: [scenario, snapshot, generator], domain: integer }
+    Generator_shut_down: { dims: [scenario, snapshot, generator], domain: integer }
+    Generator_p_nom_ext: { dims: [generator] }
+  expressions:
+    Generator_previous_status: { dims: [scenario, snapshot, generator] }
+    Generator_p_nom_effective: { dims: [scenario, generator] }
+    Generator_p_nom_committed: { dims: [scenario, generator] }
+  masks:
+    Generator_com_ext: { dims: [snapshot, generator] }
+
 dimensions:
   scenario:
     description: the futures dispatch is chosen in, each with a weight
@@ -54,27 +75,6 @@ parameters:
     dims: [scenario, generator]
     missing: neutral
 
-given:
-  parameters:
-    Generator_p_nom_extendable: { dims: [generator], dtype: bool }
-    Generator_committable: { dims: [generator], dtype: bool }
-    Generator_status_initial: { dims: [scenario, generator], dtype: int }
-    Generator_p_nom_mod: { dims: [generator] }
-    Generator_big_m: { dims: [scenario, generator] }
-    Generator_active: { dims: [snapshot, generator], dtype: bool }
-  variables:
-    Generator_p: { dims: [scenario, snapshot, generator] }
-    Generator_status: { dims: [scenario, snapshot, generator], domain: integer }
-    Generator_start_up: { dims: [scenario, snapshot, generator], domain: integer }
-    Generator_shut_down: { dims: [scenario, snapshot, generator], domain: integer }
-    Generator_p_nom_ext: { dims: [generator] }
-  expressions:
-    Generator_previous_status: { dims: [scenario, snapshot, generator] }
-    Generator_p_nom_effective: { dims: [scenario, generator] }
-    Generator_p_nom_committed: { dims: [scenario, generator] }
-  masks:
-    Generator_com_ext: { dims: [snapshot, generator] }
-
 expressions:
   Generator_previous_p:
     description: >-

docs/examples/pypsa/global_constraints.md

@@ -9,6 +9,16 @@ One of the [24 fragments](index.md) of `examples/pypsa.yaml`: the five system to
 
 <!-- gallery:begin -->
 ```yaml
+given:
+  parameters:
+    scenario_weight: { dims: [scenario] }
+  expressions:
+    primary_energy: { dims: [scenario, global_constraint] }
+    operational_limit: { dims: [scenario, global_constraint] }
+    transmission_volume_expansion: { dims: [scenario, global_constraint] }
+    transmission_expansion_cost: { dims: [scenario, global_constraint] }
+    tech_capacity_expansion: { dims: [global_constraint] }
+
 dimensions:
   scenario:
     description: the futures dispatch is chosen in, each with a weight
@@ -40,16 +50,6 @@ parameters:
       (`global_constraints.py:552`, `:750`, `:829`)
     dims: [scenario, global_constraint]
 
-given:
-  parameters:
-    scenario_weight: { dims: [scenario] }
-  expressions:
-    primary_energy: { dims: [scenario, global_constraint] }
-    operational_limit: { dims: [scenario, global_constraint] }
-    transmission_volume_expansion: { dims: [scenario, global_constraint] }
-    transmission_expansion_cost: { dims: [scenario, global_constraint] }
-    tech_capacity_expansion: { dims: [global_constraint] }
-
 constraints:
   GlobalConstraint_primary_energy_ub:
     description: "`primary_energy` — its total, at most its constant"