PyPSA multi-link¶

description: >-
  PyPSA multi-link: one Link, one input bus, several output buses, each output
  derated by its own efficiency. PyPSA spells the relation wide — bus0, bus1,
  bus2, efficiency, efficiency2, an empty bus2 where a link has no third
  terminal — and grows a column pair per arity. Here the relation is one
  incidence parameter over link and bus, so arity is the number of rows that
  name the link. Optimum 1100.0, from PyPSA itself.

dimensions:
  bus:
    description: network nodes
    dtype: str
  generator:
    description: generating units, each sitting on one bus
    dtype: str
  link:
    description: conversions, each drawing at one bus and delivering at several
    dtype: str

relations:
  gen_bus: {key: generator, values: bus, description: "the bus a generator sits on"}

parameters:
  gen_p_nom:
    description: installed capacity of a generator
    dims: [generator]
  marginal_cost:
    description: cost of one unit of output
    dims: [generator]
  p_nom:
    description: the link's own capacity — a cap on what it draws at its input, p0 in PyPSA
    dims: [link]
  incidence:
    description: >-
      each bus's share of the link's draw — minus one at the input and plus the
      efficiency at each output, with rows absent elsewhere; PyPSA's efficiency
      columns and the input's fixed minus one, tidied into rows
    dims: [link, bus]
  load:
    description: demand at each bus
    dims: [bus]

variables:
  gen:
    description: output of a generator
    dims: [generator]
    bounds:
      lower: 0
      upper: gen_p_nom
  p:
    description: >-
      the one decision per link, PyPSA's p — what it draws at its input. Every
      other end's flow is that draw scaled by its incidence entry, so it needs
      no variable of its own.
    dims: [link]
    bounds:
      lower: 0
      upper: p_nom

constraints:
  nodal_balance:
    description: >-
      what is generated at a bus plus what the links deliver there meets the
      load. The contraction lands the draw on every bus its link's incidence
      rows name — three ends or two, the expression never says.
    dims: [bus]
    expression: >-
      sum(gen, by=gen_bus, over=generator, into=bus)
      + sum(incidence * p, over=link)
      == load

objective:
  sense: minimize
  description: total cost of generation; the conversions themselves are free here
  expression: sum(gen * marginal_cost)

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

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

    ``tables`` is the same mapping the specsolve call attaches as ``sources``; only
    the incidence table changes shape on the way in, pivoted from one row per
    link end into PyPSA's one row per link. The input end is the one with the
    negative value — PyPSA fixes its share at -1, so the pivot asserts it: a
    different input share is sayable in rows and not in these columns. Each
    output end becomes the link's next port, its value the port's efficiency,
    in the incidence table's row order. A link narrower than the instance's
    widest is padded with ``''`` — PyPSA's spelling for a port a link does not
    have — and a filler efficiency of 1.0 that no equation reads.
    """
    incidence = tables['incidence']
    inputs = incidence[incidence['value'] < 0].set_index('link')
    assert (inputs['value'] == -1.0).all(), 'PyPSA fixes the input share of a Link at -1; this instance must too'

    outputs = incidence[incidence['value'] > 0].copy()
    outputs['port'] = outputs.groupby('link', sort=False).cumcount() + 1
    buses = outputs.pivot(index='link', columns='port', values='bus')
    efficiencies = outputs.pivot(index='link', columns='port', values='value')

    links = pd.DataFrame(index=pd.Index(tables['link']['link'], name='link'))
    links['bus0'] = inputs['bus']
    for port in buses.columns:
        links[f'bus{port}'] = buses[port].reindex(links.index).fillna('')
        links['efficiency' if port == 1 else f'efficiency{port}'] = efficiencies[port].reindex(links.index).fillna(1.0)

    n = pypsa.Network()
    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['gen_p_nom'].set_index('generator')['value'],
        marginal_cost=tables['marginal_cost'].set_index('generator')['value'],
    )
    n.add('Link', links.index, p_nom=tables['p_nom'].set_index('link')['value'], **dict(links.items()))

    load: pd.Series = tables['load'].set_index('bus')['value']
    for bus in tables['bus']['bus']:
        n.add('Load', f'load_{bus}', bus=bus, p_set=load[bus])
    return n