PyPSA fixed by data — a schedule, and a capacity already decided¶

description: >-
  PyPSA dispatch and capacity fixed by data: a row that is present pins its
  variable, a row that is absent leaves it free. A must-run unit runs in the two
  snapshots it is pinned in even though it is the dearest in the fleet.
  Optimum 49900.0, 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

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

parameters:
  p_nom_max:
    description: most capacity that may stand at a generator once built
    dims: [generator]
  capital_cost:
    description: cost of holding one unit of capacity over the horizon
    dims: [generator]
  marginal_cost:
    description: cost of one unit of output
    dims: [generator]
  p_nom_set:
    description: >-
      the capacity a generator is to hold, for the generators whose capacity is
      already decided
    dims: [generator]
  p_set:
    description: >-
      the output a generator is to deliver, for the snapshots in which it is
      scheduled rather than chosen
    dims: [snapshot, generator]
  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
  p_nom:
    description: capacity built at a generator
    dims: [generator]
    bounds:
      lower: 0
      upper: p_nom_max

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

  capacity_fixed:
    description: >-
      a generator whose capacity is already decided holds exactly that — the
      row exists only where the table has one
    dims: [generator]
    where: p_nom_set
    expression: p_nom == p_nom_set

  dispatch_fixed:
    description: >-
      a generator scheduled for a snapshot delivers exactly its schedule there,
      and is free everywhere else
    dims: [snapshot, generator]
    where: p_set
    expression: p == p_set

  nodal_balance:
    description: what is generated at a bus meets the load there
    dims: [snapshot, bus]
    expression: sum(p, by=gen_bus, over=generator, into=bus) == load

objective:
  sense: minimize
  description: what the fleet costs to run, plus what its capacity costs to build
  expression: sum(p * marginal_cost) + sum(p_nom * capital_cost)

# sources: parameter name -> frame or parquet path
with sps.solve('examples/ports/pypsa_fixed.yaml', sources) as solution:
    solution.objective  # 49900.0
    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``.

    Both fixings arrive as short frames and are widened to the shape PyPSA
    reads, with ``NaN`` where the port simply has no row: ``p_nom_set``
    reindexed onto the generator index, ``p_set`` pivoted to snapshots by names.
    NaN is PyPSA's own spelling for *not fixed here* — it is what its mask
    tests — so the widening is the translation, not a defaulting choice.

    Every generator is extendable, because ``p_nom_set`` fixes the capacity
    *variable*: a non-extendable component has none for the equality to bind.
    """
    n = pypsa.Network()
    n.set_snapshots(tables['snapshot']['snapshot'])
    n.add('Bus', tables['bus']['bus'])

    generators: pd.DataFrame = tables['generator'].set_index('generator')
    p_set = (
        tables['p_set']
        .pivot(index='snapshot', columns='generator', values='value')
        .reindex(index=n.snapshots, columns=generators.index)
    )
    n.add(
        'Generator',
        generators.index,
        bus=generators['gen_bus'],
        p_nom_extendable=True,
        p_nom_max=tables['p_nom_max'].set_index('generator')['value'],
        p_nom_set=tables['p_nom_set'].set_index('generator')['value'].reindex(generators.index, fill_value=np.nan),
        capital_cost=tables['capital_cost'].set_index('generator')['value'],
        marginal_cost=tables['marginal_cost'].set_index('generator')['value'],
        p_set=p_set,
    )

    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