PyPSA Store — one signed power, and no rating at all¶

description: >-
  PyPSA's Store component: one signed power at the bus, no efficiencies and no
  power rating — only the energy level limits how fast it moves. The tank fills
  early and drains late, losing a share of what it holds every snapshot, and its
  energy capacity is built rather than given. Optimum 7005.5025000000005, from
  PyPSA itself.

dimensions:
  snapshot:
    description: dispatch periods
    dtype: int
  bus:
    description: network nodes
    dtype: str
  generator:
    description: generating units, each sitting on one bus
    dtype: str
  store:
    description: energy stores, each sitting on one bus
    dtype: str

relations:
  gen_bus:
    description: the bus a generator sits on
    key: generator
    values: bus
  store_bus:
    description: the bus a store sits on
    key: store
    values: bus

parameters:
  p_nom:
    description: installed capacity of a generator
    dims: [generator]
  marginal_cost:
    description: cost of one unit of output
    dims: [generator]
  e_nom_max:
    description: most energy capacity that may be built at a store
    dims: [store]
  e_capital_cost:
    description: cost of holding one unit of energy capacity over the horizon
    dims: [store]
  e_initial:
    description: energy in the store before the first snapshot
    dims: [store]
  standing_loss:
    description: share of the carried-over level lost between snapshots
    dims: [store]
  load:
    description: demand at each bus in each snapshot
    dims: [snapshot, bus]

variables:
  p:
    description: output of a generator in a snapshot
    dims: [snapshot, generator]
    bounds:
      lower: 0
      upper: p_nom
  store_p:
    description: >-
      power a store puts onto its bus, negative when it takes power off —
      unbounded, because a Store has no rating of its own
    dims: [snapshot, store]
  e:
    description: energy in the store at the end of a snapshot
    dims: [snapshot, store]
    bounds:
      lower: 0
  e_nom:
    description: energy capacity built at a store
    dims: [store]
    bounds:
      lower: 0
      upper: e_nom_max

constraints:
  nodal_balance:
    description: what is generated at a bus, plus what the stores supply, meets the load there
    dims: [snapshot, bus]
    expression: sum(p, by=gen_bus, over=generator, into=bus) + sum(store_p, by=store_bus, over=store, into=bus) == load

  within_capacity:
    description: a store holds no more energy than the capacity built for it
    dims: [snapshot, store]
    expression: e <= e_nom

  energy_balance_initial:
    description: >-
      the first snapshot's level starts from the initial energy, which the
      standing loss does not decay because nothing was carried into it
    dims: [snapshot, store]
    where: "position(snapshot) == 0"
    expression: e == e_initial - store_p

  energy_balance:
    description: >-
      the level carried into a snapshot, decayed by the standing loss, less what
      the store supplied to its bus
    dims: [snapshot, store]
    expression: >-
      e == shift(e, along=snapshot, offset=1) * (1 - standing_loss) - store_p

objective:
  sense: minimize
  description: what the fleet costs to run, plus what the store's energy capacity costs to build
  expression: sum(p * marginal_cost) + sum(e_nom * e_capital_cost)

# sources: parameter name -> frame or parquet path
with sps.solve('examples/ports/pypsa_store.yaml', sources) as solution:
    solution.objective  # 7005.5025000000005
    solution.dual('nodal_balance')

def build(tables: dict[str, pd.DataFrame]) -> pypsa.Network:
    """The port's tables as a PyPSA network, column for column.

    ``tables`` is the same mapping the specsolve call attaches as ``sources``.

    ``Store`` takes no power rating: ``e_nom`` bounds the level, and the power
    that moves it is limited only by what the level allows within one snapshot.
    That is why the port declares its store power with no bounds at all.
    """
    n = pypsa.Network()
    n.set_snapshots(tables['snapshot']['snapshot'])
    n.add('Bus', tables['bus']['bus'])

    generators: pd.DataFrame = tables['generator'].set_index('generator')
    n.add(
        'Generator',
        generators.index,
        bus=generators['gen_bus'],
        p_nom=tables['p_nom'].set_index('generator')['value'],
        marginal_cost=tables['marginal_cost'].set_index('generator')['value'],
    )

    stores: pd.DataFrame = tables['store'].set_index('store')
    n.add(
        'Store',
        stores.index,
        bus=stores['store_bus'],
        e_nom_extendable=True,
        e_nom_max=tables['e_nom_max'].set_index('store')['value'],
        capital_cost=tables['e_capital_cost'].set_index('store')['value'],
        e_initial=tables['e_initial'].set_index('store')['value'],
        standing_loss=tables['standing_loss'].set_index('store')['value'],
        e_cyclic=False,
    )

    load: pd.DataFrame = tables['load'].pivot(index='snapshot', columns='bus', values='value')
    for bus in tables['bus']['bus']:
        n.add('Load', f'load_{bus}', bus=bus, p_set=load[bus])
    return n