PyPSA global limits — four bounds, one shape¶

description: >-
  PyPSA's global constraints: four limits over four different selected sets —
  the energy a carrier may deliver, the capacity a carrier may hold at one bus,
  and the built transmission measured twice, once as length and once as money.
  Each is one grouped sum against a bound only some rows carry.
  Optimum 127211.66666666666, from PyPSA itself.

dimensions:
  snapshot:
    description: dispatch periods
    dtype: int
  bus:
    description: network nodes
    dtype: str
  carrier:
    description: what a generator burns, and what a global limit selects on
    dtype: str
  generator:
    description: generating units, each sitting on a bus and burning a carrier
    dtype: str
  link:
    description: controllable connections, each joining two buses
    dtype: str

relations:
  gen_placement:
    description: the bus a generator sits on and the carrier it burns
    key: generator
    values: [bus, carrier]
  link_from:
    description: the bus a link leaves
    key: link
    values: bus
  link_to:
    description: the bus a link arrives at
    key: link
    values: bus

parameters:
  load:
    description: demand at each bus in each snapshot
    dims: [snapshot, bus]
  p_max_pu:
    description: share of built capacity a generator can produce in a snapshot
    dims: [snapshot, generator]
  marginal_cost:
    description: cost of one unit of output
    dims: [generator]
  gen_capital_cost:
    description: annualised cost of a unit of generator capacity
    dims: [generator]
  link_capital_cost:
    description: annualised cost of a unit of link capacity
    dims: [link]
  link_length:
    description: how far a link reaches — what turns built capacity into a volume
    dims: [link]
  energy_cap:
    description: >-
      energy a carrier may deliver over the whole horizon, for the carriers that
      have such a limit
    dims: [carrier]
  bus_capacity_cap:
    description: >-
      capacity of one carrier a bus may hold, for the pairs that cap it — PyPSA
      writes the carrier into a column name (`nom_max_wind`), so the pair is the
      limit's own key
    dims: [bus, carrier]
  volume_cap:
    description: capacity times length the whole network may build
    dims: []
  expansion_cost_cap:
    description: money the whole network may spend building links
    dims: []

variables:
  p:
    description: output of a generator in a snapshot
    dims: [snapshot, generator]
    bounds:
      lower: 0
  p_nom:
    description: capacity built at a generator
    dims: [generator]
    bounds:
      lower: 0
  g:
    description: flow on a link, towards the bus it delivers at
    dims: [snapshot, link]
    bounds:
      lower: 0
  link_p_nom:
    description: capacity built on a link
    dims: [link]
    bounds:
      lower: 0

constraints:
  within_capacity:
    description: a generator produces no more than the built capacity available to it
    dims: [snapshot, generator]
    expression: p <= p_nom * p_max_pu

  within_link_capacity:
    dims: [snapshot, link]
    expression: g <= link_p_nom

  nodal_balance:
    description: what is generated at a bus plus what arrives over the links meets the load there
    dims: [snapshot, bus]
    expression: >-
      sum(p, by=gen_placement, over=generator, into=bus)
      + sum(g, by=link_to, over=link, into=bus) - sum(g, by=link_from, over=link, into=bus)
      == load

  carrier_energy:
    description: >-
      a carrier with an energy limit delivers no more than it over the horizon —
      the generators are grouped onto the carrier they burn, which is the
      selection PyPSA makes by querying its own table
    dims: [carrier]
    where: energy_cap
    expression: sum(sum(p, by=gen_placement, over=generator, into=carrier), over=snapshot) <= energy_cap

  carrier_capacity_at_bus:
    description: >-
      a bus that caps a carrier holds no more of it than that — one grouping
      lands the built capacity on the (bus, carrier) pair the limit is keyed by,
      so no selector column and no mask stand between the two
    dims: [bus, carrier]
    where: bus_capacity_cap
    expression: sum(p_nom, by=gen_placement, over=generator, into=[bus, carrier]) <= bus_capacity_cap

  transmission_volume:
    description: >-
      capacity times length, summed over the links — a limit on how much network
      is built, in the unit a planner is granted
    dims: []
    expression: sum(link_p_nom * link_length, over=link) <= volume_cap

  transmission_cost:
    description: >-
      the same set weighted by money instead of distance, which is why the two
      limits are not each other: the long link is the cheap one
    dims: []
    expression: sum(link_p_nom * link_capital_cost, over=link) <= expansion_cost_cap

objective:
  sense: minimize
  description: what the fleet costs to run, plus what the generation and link capacity cost to build
  expression: >-
    sum(p * marginal_cost)
    + sum(p_nom * gen_capital_cost)
    + sum(link_p_nom * link_capital_cost)

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

def build(
    tables: dict[str, pd.DataFrame],
    limits: dict[str, dict[str, object]] | None = None,
    bus_capacity_cap: bool = True,
) -> pypsa.Network:
    """The port's tables as a PyPSA network, column for column.

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

    ``limits`` defaults to all three global-constraint rows and
    ``bus_capacity_cap`` to on; dropping one is how ``main`` measures what it is
    worth. Every generator and every link is extendable, because a limit on
    capacity has nothing to bind on a component whose capacity is data.
    """
    n = pypsa.Network()
    n.set_snapshots(tables['snapshot']['snapshot'])
    n.add('Bus', tables['bus']['bus'])
    n.add('Carrier', tables['carrier']['carrier'])
    n.add('Carrier', 'DC')

    generators: pd.DataFrame = tables['generator'].set_index('generator')
    p_max_pu: pd.DataFrame = tables['p_max_pu'].pivot(index='snapshot', columns='generator', values='value')
    n.add(
        'Generator',
        generators.index,
        bus=generators['gen_bus'],
        carrier=generators['gen_carrier'],
        p_nom_extendable=True,
        p_max_pu=p_max_pu[generators.index],
        marginal_cost=tables['marginal_cost'].set_index('generator')['value'],
        capital_cost=tables['gen_capital_cost'].set_index('generator')['value'],
    )

    links: pd.DataFrame = tables['link'].set_index('link')
    n.add(
        'Link',
        links.index,
        bus0=links['link_from'],
        bus1=links['link_to'],
        carrier='DC',
        p_nom_extendable=True,
        length=tables['link_length'].set_index('link')['value'],
        capital_cost=tables['link_capital_cost'].set_index('link')['value'],
    )

    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])

    for name, attributes in (LIMITS if limits is None else limits).items():
        n.add('GlobalConstraint', name, **attributes)

    if bus_capacity_cap:
        bus, column, cap = BUS_CAPACITY_CAP
        n.buses.loc[bus, column] = cap
    return n