Storage units#

dimensions:
  scenario:
    description: the futures dispatch is chosen in, each with a weight
  snapshot:
    description: dispatch periods
    dtype: datetime
  bus:
    description: network nodes
  storage_unit:
    description: storage units, dispatch and store behind one bus connection
  global_constraint:
    description: PyPSA's `GlobalConstraint` rows, one label per declared limit
  period:
    description: investment periods — PyPSA's `investment_periods`
    dtype: int
  carrier:
    description: energy carriers, what a growth limit is set per

relations:
  snapshot_period:
    description: the investment period a snapshot falls in
    key: snapshot
    values: period
  StorageUnit_carrier:
    description: the carrier a storage unit converts from
    key: storage_unit
    values: carrier
  StorageUnit_bus:
    description: the bus a storage unit sits on
    key: storage_unit
    values: bus

parameters:
  StorageUnit_active:
    description: whether a storage unit stands in a snapshot's period — PyPSA's `active`, data prep
    dims: [snapshot, storage_unit]
    dtype: bool
  StorageUnit_capital_weight:
    description: the sum of period weights a storage unit stands in — PyPSA's `active * period_weighting`, summed, data prep
    dims: [storage_unit]
  StorageUnit_first_active:
    description: >-
      one in the first period a storage unit stands in, zero elsewhere, data prep.
      PyPSA `1.3.0` takes `active.cumsum() == 1`, which also counts a storage unit
      that has retired in every later period (`global_constraints.py:276`,
      PyPSA/PyPSA#1938)
    dims: [period, storage_unit]
  StorageUnit_p_nom_min:
    description: least nominal power an extendable storage unit may be built at
    dims: [scenario, storage_unit]
  StorageUnit_p_nom_max:
    description: most nominal power an extendable storage unit may be built at
    dims: [scenario, storage_unit]
  StorageUnit_capital_cost:
    description: cost of one unit of nominal power — PyPSA's `capital_cost`, periodized as an annuity in data prep
    dims: [scenario, storage_unit]
  StorageUnit_p_nom_set:
    description: a given nominal power for an extendable storage unit; one without a value has no row here
    dims: [scenario, storage_unit]
  StorageUnit_p_nom:
    description: nominal power
    dims: [scenario, storage_unit]
  StorageUnit_p_nom_extendable:
    description: whether the nominal power is a decision
    dims: [storage_unit]
    dtype: bool
  StorageUnit_p_min_pu:
    description: most storing, per unit of nominal power and negated
    dims: [scenario, snapshot, storage_unit]
  StorageUnit_p_max_pu:
    description: most dispatch, per unit of nominal power
    dims: [scenario, snapshot, storage_unit]
  StorageUnit_max_hours:
    description: energy capacity, as hours of dispatch at nominal power
    dims: [scenario, storage_unit]
  StorageUnit_efficiency_store:
    description: share of the power drawn from the bus that becomes charge
    dims: [scenario, snapshot, storage_unit]
  StorageUnit_efficiency_dispatch:
    description: share of the charge drawn down that reaches the bus
    dims: [scenario, snapshot, storage_unit]
  StorageUnit_sign:
    description: >-
      the sign net dispatch enters its bus's balance with — PyPSA's `sign`,
      `1` unless given. PyPSA refuses one that differs by scenario
      (`consistency.py:1187`)
    dims: [storage_unit]
  StorageUnit_retention:
    description: share of charge kept over a snapshot — PyPSA's `(1 - standing_loss) ** elapsed hours`, data prep
    dims: [scenario, snapshot, storage_unit]
  StorageUnit_inflow:
    description: energy arriving per hour, a river into a reservoir
    dims: [scenario, snapshot, storage_unit]
  StorageUnit_state_of_charge_initial:
    description: charge held before the first snapshot
    dims: [scenario, storage_unit]
  StorageUnit_cyclic_state_of_charge:
    description: whether the horizon closes on itself instead of opening on the initial charge
    dims: [scenario, storage_unit]
    dtype: bool
  StorageUnit_cyclic_state_of_charge_per_period:
    description: >-
      whether each investment period closes on itself instead of carrying its
      charge on to the next; it overrides `cyclic_state_of_charge` and
      `state_of_charge_initial_per_period`. PyPSA reads it only under
      `multi_investment_periods`, so data prep feeds false otherwise
    dims: [scenario, storage_unit]
    dtype: bool
  StorageUnit_state_of_charge_initial_per_period:
    description: >-
      whether each investment period opens on the initial charge instead of
      carrying the previous period's; PyPSA reads it only under
      `multi_investment_periods`, so data prep feeds false otherwise
    dims: [scenario, storage_unit]
    dtype: bool
  StorageUnit_opens_late:
    description: >-
      whether a snapshot is the first a storage unit stands in, where that is
      not the first of the horizon — PyPSA's `active.cumsum() == 1` over the
      snapshots it stands in, past the first snapshot, data prep; false in a
      run where every unit stands throughout
    dims: [snapshot, storage_unit]
    dtype: bool
  StorageUnit_inactive_snapshots:
    description: >-
      how many snapshots a storage unit does not stand in — PyPSA's
      `(~active).sum()`, data prep. A cyclic unit reaches back this many
      snapshots further, so it closes on the last snapshot it stands in
    dims: [storage_unit]
    dtype: int
  StorageUnit_marginal_cost:
    description: cost of one unit of dispatch
    dims: [scenario, snapshot, storage_unit]
  StorageUnit_marginal_cost_quadratic:
    description: cost of the square of one unit of dispatch; storing is not charged
    dims: [scenario, snapshot, storage_unit]
  StorageUnit_marginal_cost_storage:
    description: cost of one unit of charge held over one snapshot
    dims: [scenario, snapshot, storage_unit]
  StorageUnit_spill_cost:
    description: cost of one unit of inflow passed on unused
    dims: [scenario, snapshot, storage_unit]
  StorageUnit_p_set:
    description: a given net dispatch schedule; a unit without one has no row here
    dims: [scenario, snapshot, storage_unit]
  StorageUnit_p_dispatch_set:
    description: a given dispatch schedule; a unit without one has no row here
    dims: [scenario, snapshot, storage_unit]
  StorageUnit_p_store_set:
    description: a given charging schedule; a unit without one has no row here
    dims: [scenario, snapshot, storage_unit]
  StorageUnit_state_of_charge_set:
    description: a given charge schedule; a unit without one has no row here
    dims: [scenario, snapshot, storage_unit]
  StorageUnit_primary_energy_weight:
    description: the constrained attribute per unit of charge depleted — data prep; an unweighted unit has no row
    dims: [scenario, global_constraint, storage_unit]
  StorageUnit_operational_limit_weight:
    description: one where the storage unit is in the row's set — data prep; one outside it has no row
    dims: [scenario, global_constraint, storage_unit]
  StorageUnit_tech_capacity_weight:
    description: >-
      one where the storage unit is in the row's carrier-and-bus set — data prep; one
      outside it, or one that does not stand in the row's `investment_period`,
      has no row
    dims: [global_constraint, storage_unit]

variables:
  StorageUnit_p_dispatch:
    description: "`StorageUnit-p_dispatch` — power delivered to the bus"
    dims: [scenario, snapshot, storage_unit]
    where: StorageUnit_active
  StorageUnit_p_store:
    description: "`StorageUnit-p_store` — power drawn from the bus into charge"
    dims: [scenario, snapshot, storage_unit]
    where: StorageUnit_active
  StorageUnit_state_of_charge:
    description: "`StorageUnit-state_of_charge` — energy held at the end of a snapshot"
    dims: [scenario, snapshot, storage_unit]
    where: StorageUnit_active
  StorageUnit_spill:
    description: >-
      `StorageUnit-spill` — inflow passed on unused. Zero where there is no
      inflow, so the balance keeps its row there; the bounds are PyPSA's, on
      the variable rather than as rows
    dims: [scenario, snapshot, storage_unit]
    where: "StorageUnit_inflow > 0 AND StorageUnit_active"
    absence: zero
    bounds:
      lower: 0
      upper: StorageUnit_inflow
  StorageUnit_p_nom_ext:
    description: >-
      `StorageUnit-p_nom` — nominal power where it is a decision; the
      parameter of the same PyPSA name carries the fixed regime
    dims: [storage_unit]
    where: StorageUnit_p_nom_extendable

given:
  parameters:
    snapshot_weightings_objective: { dims: [snapshot] }
    scenario_weight: { dims: [scenario] }
    CVaR_omega: { dims: [] }
    period_weight_objective: { dims: [period] }
    period_weight_years: { dims: [period] }
    snapshot_weightings_stores: { dims: [snapshot] }
    GlobalConstraint_counts_snapshot: { dims: [scenario, global_constraint, snapshot], dtype: bool }
  expressions:
    GlobalConstraint_snapshot_closes: { dims: [scenario, global_constraint, snapshot] }
    primary_energy: { dims: [scenario, global_constraint], term: StorageUnit_primary_energy }
    operational_limit: { dims: [scenario, global_constraint], term: StorageUnit_operational_limit }
    tech_capacity_expansion: { dims: [global_constraint], term: StorageUnit_tech_capacity_expansion }
    scenario_opex: { dims: [scenario], term: StorageUnit_opex }
    Carrier_additions: { dims: [period, carrier], term: StorageUnit_additions }
    Bus_injection: { dims: [scenario, snapshot, bus], term: StorageUnit_injection }

expressions:
  StorageUnit_charge_carried_in:
    description: >-
      the charge a unit opens a snapshot with — at the first snapshot it
      stands in, its last such snapshot's less standing loss where it is
      cyclic and the given initial charge, which no standing loss has touched
      yet, where it is not; the previous snapshot's less standing loss
      otherwise. A unit built in a later period opens in that period, and a
      cyclic one that retires closes on its own last snapshot. Per period, the
      same holds with each investment period as the horizon
    dims: [scenario, snapshot, storage_unit]
    cases:
      cyclic:
        when: >-
          StorageUnit_cyclic_state_of_charge AND NOT StorageUnit_cyclic_state_of_charge_per_period
          AND NOT StorageUnit_state_of_charge_initial_per_period
          AND (position(snapshot) == 0 OR StorageUnit_opens_late)
        expression: >-
          StorageUnit_retention
          * shift(shift(StorageUnit_state_of_charge, along=snapshot, offset=1, edge='wrap'), along=snapshot, offset=StorageUnit_inactive_snapshots, edge='wrap')
      opening:
        when: >-
          NOT StorageUnit_cyclic_state_of_charge AND NOT StorageUnit_cyclic_state_of_charge_per_period
          AND NOT StorageUnit_state_of_charge_initial_per_period
          AND (position(snapshot) == 0 OR StorageUnit_opens_late)
        expression: StorageUnit_state_of_charge_initial
      period_cyclic:
        when: StorageUnit_cyclic_state_of_charge_per_period
        expression: >-
          StorageUnit_retention
          * shift(StorageUnit_state_of_charge, along=snapshot, offset=1, edge='wrap', by=snapshot_period, within=period)
      period_opening:
        when: >-
          StorageUnit_state_of_charge_initial_per_period AND NOT StorageUnit_cyclic_state_of_charge_per_period
          AND position(snapshot, by=snapshot_period, within=period) == 0
        expression: StorageUnit_state_of_charge_initial
    otherwise: StorageUnit_retention * shift(StorageUnit_state_of_charge, along=snapshot, offset=1)
  StorageUnit_closing_weight:
    description: >-
      what the charge a unit holds at a snapshot counts for in a row as its
      closing level — the years of the period at the last snapshot of each
      counted period where the unit reopens per period, one at the last
      counted snapshot where it does not, and nothing elsewhere
    dims: [scenario, global_constraint, snapshot, storage_unit]
    cases:
      per_period:
        when: StorageUnit_state_of_charge_initial_per_period AND GlobalConstraint_counts_snapshot AND position(snapshot, by=snapshot_period, within=period) == -1
        expression: at(period_weight_years, by=snapshot_period, over=period, into=snapshot)
      carried_over:
        when: NOT StorageUnit_state_of_charge_initial_per_period
        expression: GlobalConstraint_snapshot_closes
    otherwise: 0
  StorageUnit_primary_energy:
    expression: >-
      -sum(sum((StorageUnit_state_of_charge * StorageUnit_closing_weight) * StorageUnit_primary_energy_weight, over=snapshot), over=storage_unit)
  StorageUnit_operational_limit:
    expression: >-
      -sum(sum((StorageUnit_state_of_charge * StorageUnit_closing_weight) * StorageUnit_operational_limit_weight, over=snapshot), over=storage_unit)
  StorageUnit_tech_capacity_expansion:
    expression: sum(StorageUnit_p_nom_ext * StorageUnit_tech_capacity_weight, over=storage_unit)
  StorageUnit_opex:
    expression: >-
      sum(sum(((StorageUnit_p_dispatch * StorageUnit_marginal_cost) * snapshot_weightings_objective) * at(period_weight_objective, by=snapshot_period, over=period, into=snapshot), over=storage_unit), over=snapshot)
      + sum(sum((((StorageUnit_p_dispatch * StorageUnit_p_dispatch) * StorageUnit_marginal_cost_quadratic) * snapshot_weightings_objective) * at(period_weight_objective, by=snapshot_period, over=period, into=snapshot), over=storage_unit), over=snapshot)
      + sum(sum(((StorageUnit_state_of_charge * StorageUnit_marginal_cost_storage) * snapshot_weightings_objective) * at(period_weight_objective, by=snapshot_period, over=period, into=snapshot), over=storage_unit), over=snapshot)
      + sum(sum(((StorageUnit_spill * StorageUnit_spill_cost) * snapshot_weightings_objective) * at(period_weight_objective, by=snapshot_period, over=period, into=snapshot), over=storage_unit), over=snapshot)
  StorageUnit_additions:
    expression: >-
      sum(StorageUnit_p_nom_ext * StorageUnit_first_active, by=StorageUnit_carrier, over=storage_unit, into=carrier)
  StorageUnit_injection:
    expression: >-
      sum(StorageUnit_sign * (StorageUnit_p_dispatch - StorageUnit_p_store), by=StorageUnit_bus, over=storage_unit, into=bus)

constraints:
  StorageUnit_fix_p_dispatch_lower:
    description: "`StorageUnit-fix-p_dispatch-lower` — dispatch is non-negative"
    dims: [scenario, snapshot, storage_unit]
    where: not StorageUnit_p_nom_extendable AND StorageUnit_active
    expression: StorageUnit_p_dispatch >= 0
  StorageUnit_fix_p_dispatch_upper:
    description: "`StorageUnit-fix-p_dispatch-upper` — a fixed unit dispatches at most its nominal power"
    dims: [scenario, snapshot, storage_unit]
    where: not StorageUnit_p_nom_extendable AND StorageUnit_active
    expression: StorageUnit_p_dispatch <= StorageUnit_p_max_pu * StorageUnit_p_nom
  StorageUnit_fix_p_store_lower:
    description: "`StorageUnit-fix-p_store-lower` — storing is non-negative"
    dims: [scenario, snapshot, storage_unit]
    where: not StorageUnit_p_nom_extendable AND StorageUnit_active
    expression: StorageUnit_p_store >= 0
  StorageUnit_fix_p_store_upper:
    description: >-
      `StorageUnit-fix-p_store-upper` — a fixed unit stores at most its
      nominal power, the minimum-per-unit column carrying that cap negated
    dims: [scenario, snapshot, storage_unit]
    where: not StorageUnit_p_nom_extendable AND StorageUnit_active
    expression: StorageUnit_p_store <= -StorageUnit_p_min_pu * StorageUnit_p_nom
  StorageUnit_fix_state_of_charge_lower:
    description: "`StorageUnit-fix-state_of_charge-lower` — charge is non-negative"
    dims: [scenario, snapshot, storage_unit]
    where: not StorageUnit_p_nom_extendable AND StorageUnit_active
    expression: StorageUnit_state_of_charge >= 0
  StorageUnit_fix_state_of_charge_upper:
    description: "`StorageUnit-fix-state_of_charge-upper` — a fixed unit holds at most its hours at nominal power"
    dims: [scenario, snapshot, storage_unit]
    where: not StorageUnit_p_nom_extendable AND StorageUnit_active
    expression: StorageUnit_state_of_charge <= StorageUnit_max_hours * StorageUnit_p_nom
  StorageUnit_ext_p_dispatch_lower:
    description: "`StorageUnit-ext-p_dispatch-lower` — dispatch is non-negative"
    dims: [scenario, snapshot, storage_unit]
    where: StorageUnit_p_nom_extendable AND StorageUnit_active
    expression: StorageUnit_p_dispatch >= 0
  StorageUnit_ext_p_dispatch_upper:
    description: "`StorageUnit-ext-p_dispatch-upper` — an extendable unit dispatches at most the chosen build"
    dims: [scenario, snapshot, storage_unit]
    where: StorageUnit_p_nom_extendable AND StorageUnit_active
    expression: StorageUnit_p_dispatch <= StorageUnit_p_max_pu * StorageUnit_p_nom_ext
  StorageUnit_ext_p_store_lower:
    description: "`StorageUnit-ext-p_store-lower` — storing is non-negative"
    dims: [scenario, snapshot, storage_unit]
    where: StorageUnit_p_nom_extendable AND StorageUnit_active
    expression: StorageUnit_p_store >= 0
  StorageUnit_ext_p_store_upper:
    description: >-
      `StorageUnit-ext-p_store-upper` — an extendable unit stores at most the
      chosen build, the minimum-per-unit column carrying that cap negated
    dims: [scenario, snapshot, storage_unit]
    where: StorageUnit_p_nom_extendable AND StorageUnit_active
    expression: StorageUnit_p_store <= -StorageUnit_p_min_pu * StorageUnit_p_nom_ext
  StorageUnit_ext_state_of_charge_lower:
    description: "`StorageUnit-ext-state_of_charge-lower` — charge is non-negative"
    dims: [scenario, snapshot, storage_unit]
    where: StorageUnit_p_nom_extendable AND StorageUnit_active
    expression: StorageUnit_state_of_charge >= 0
  StorageUnit_ext_state_of_charge_upper:
    description: "`StorageUnit-ext-state_of_charge-upper` — an extendable unit holds at most its hours at the chosen build"
    dims: [scenario, snapshot, storage_unit]
    where: StorageUnit_p_nom_extendable AND StorageUnit_active
    expression: StorageUnit_state_of_charge <= StorageUnit_max_hours * StorageUnit_p_nom_ext
  StorageUnit_ext_p_nom_lower:
    description: "`StorageUnit-ext-p_nom-lower` — the chosen build is at least its floor in every scenario"
    dims: [scenario, storage_unit]
    where: StorageUnit_p_nom_extendable
    expression: StorageUnit_p_nom_ext >= StorageUnit_p_nom_min
  StorageUnit_ext_p_nom_upper:
    description: "`StorageUnit-ext-p_nom-upper` — the chosen build is at most its cap in every scenario; a cap of infinity is no row"
    dims: [scenario, storage_unit]
    where: StorageUnit_p_nom_extendable AND StorageUnit_p_nom_max
    expression: StorageUnit_p_nom_ext <= StorageUnit_p_nom_max
  StorageUnit_p_nom_set:
    description: "`StorageUnit-p_nom_set` — the chosen build pinned, wherever a value is given"
    dims: [scenario, storage_unit]
    where: StorageUnit_p_nom_extendable AND StorageUnit_p_nom_set
    expression: StorageUnit_p_nom_ext == StorageUnit_p_nom_set
  StorageUnit_energy_balance:
    description: >-
      `StorageUnit-energy_balance` — the charge carried in, plus what is
      stored after its efficiency, less what dispatch draws down before its
      own, plus inflow not spilled
    dims: [scenario, snapshot, storage_unit]
    where: StorageUnit_active
    expression: >-
      StorageUnit_state_of_charge ==
      StorageUnit_charge_carried_in
      + StorageUnit_efficiency_store * StorageUnit_p_store * snapshot_weightings_stores
      - StorageUnit_p_dispatch * snapshot_weightings_stores / StorageUnit_efficiency_dispatch
      + (StorageUnit_inflow - StorageUnit_spill) * snapshot_weightings_stores
  StorageUnit_p_set:
    description: "`StorageUnit-p_set` — net dispatch pinned to the given schedule, wherever one is given"
    dims: [scenario, snapshot, storage_unit]
    where: StorageUnit_p_set AND StorageUnit_active
    expression: StorageUnit_p_dispatch - StorageUnit_p_store == StorageUnit_p_set
  StorageUnit_p_dispatch_set:
    description: "`StorageUnit-p_dispatch_set` — dispatch pinned to the given schedule, wherever one is given"
    dims: [scenario, snapshot, storage_unit]
    where: StorageUnit_p_dispatch_set AND StorageUnit_active
    expression: StorageUnit_p_dispatch == StorageUnit_p_dispatch_set
  StorageUnit_p_store_set:
    description: "`StorageUnit-p_store_set` — charging pinned to the given schedule, wherever one is given"
    dims: [scenario, snapshot, storage_unit]
    where: StorageUnit_p_store_set AND StorageUnit_active
    expression: StorageUnit_p_store == StorageUnit_p_store_set
  StorageUnit_state_of_charge_set:
    description: "`StorageUnit-state_of_charge_set` — charge pinned to the given schedule, wherever one is given"
    dims: [scenario, snapshot, storage_unit]
    where: StorageUnit_state_of_charge_set AND StorageUnit_active
    expression: StorageUnit_state_of_charge == StorageUnit_state_of_charge_set

assumptions:
  StorageUnit_stands_in_one_run:
    holds: "count(StorageUnit_active AND NOT shift(StorageUnit_active, along=snapshot, offset=1), over=snapshot) <= 1"
    description: >-
      the snapshots a storage unit stands in are one unbroken run, as a build
      year and a lifetime make them. The opening row holds at the first
      of them only, and a cyclic storage unit reaches back
      `StorageUnit_inactive_snapshots` further to the last of them
  StorageUnit_opens_late_only_where_it_opens:
    holds: "StorageUnit_active AND NOT shift(StorageUnit_active, along=snapshot, offset=1) AND position(snapshot) > 0"
    where: "StorageUnit_opens_late"
    description: >-
      `StorageUnit_opens_late` marks the first snapshot the storage unit stands in, past
      the first of the horizon, and no other
  StorageUnit_opens_late_where_it_opens:
    holds: "StorageUnit_opens_late"
    where: "StorageUnit_active AND NOT shift(StorageUnit_active, along=snapshot, offset=1) AND position(snapshot) > 0"
    description: >-
      a storage unit that opens past the first snapshot of the horizon opens on
      its initial level, or its last level where it is cyclic, only where
      `StorageUnit_opens_late` marks the snapshot
  StorageUnit_primary_energy_per_period_closes_over_the_horizon:
    holds: "count(NOT GlobalConstraint_counts_snapshot, over=snapshot) == 0"
    where: "StorageUnit_primary_energy_weight AND StorageUnit_state_of_charge_initial_per_period"
    description: >-
      PyPSA reads the closing charge of a unit that reopens per period at
      the last snapshot of every period, and fails on a `primary_energy` row
      that names an `investment_period` (`global_constraints.py:474`)
  StorageUnit_primary_energy_carried_over_has_unit_years:
    holds: "period_weight_years == 1"
    where: "StorageUnit_primary_energy_weight AND NOT StorageUnit_state_of_charge_initial_per_period"
    description: >-
      a unit that carries its charge from one period to the next closes
      once, at the last counted snapshot, and no period's years weighs that
      level — PyPSA refuses it where any period's years is not one
      (`global_constraints.py:448`)
  StorageUnit_operational_limit_carried_over_has_unit_years:
    holds: "at(period_weight_years == 1, by=snapshot_period, over=period, into=snapshot)"
    where: "StorageUnit_operational_limit_weight AND NOT StorageUnit_state_of_charge_initial_per_period AND GlobalConstraint_counts_snapshot"
    description: >-
      the same for an `operational_limit` row, over the periods it counts —
      PyPSA refuses it (`global_constraints.py:647`)
  StorageUnit_marginal_cost_quadratic_without_risk_preference:
    holds: "StorageUnit_marginal_cost_quadratic == 0"
    where: "CVaR_omega > 0"
    description: >-
      a quadratic cost puts a square into every `CVaR-excess` row, and PyPSA
      refuses quadratic costs under any risk preference
      (`optimize.py:467-474`). The spec cannot tell no risk preference from
      one with `omega = 0`, so it refuses only where `omega` is positive

objective:
  sense: minimize
  expression: >-
    sum(((scenario_weight * StorageUnit_p_nom_ext) * StorageUnit_capital_cost) * StorageUnit_capital_weight)