reserves¶

description: >-
  Energy and reserve co-optimization on a two-bus grid: an offer is a
  generator, market and tranche together, reserve zones overlap, and one line
  dangles. The model exists to prove a claim — every many-to-many shape the
  language covers, in one instance, each one load-bearing.

dimensions:
  bus:
    description: network nodes
    dtype: str
  generator:
    description: generating units, each sitting on one bus
    dtype: str
  market:
    description: reserve markets, each with a requirement to fill
    dtype: str
  tranche:
    description: how fast a reserve has to be deliverable
    dtype: str
  zone:
    description: reserve zones, which overlap
    dtype: str
  line:
    description: transmission lines, which may have an open end
    dtype: str
  offer:
    description: one generator's bid into one market at one tranche
    dtype: str

relations:
  gen_bus: {key: generator, values: bus, description: "the bus a generator sits on"}
  line_from: {key: line, values: bus, description: "the bus a line leaves, null where the end is open"}
  line_to: {key: line, values: bus, description: "the bus a line arrives at, null where the end is open"}
  gen_of: {key: offer, values: generator, description: "the generator behind an offer"}
  market_of: {key: offer, values: market, description: "the market an offer is made into"}
  tranche_of: {key: offer, values: tranche, description: "the tranche an offer is made at"}

parameters:
  p_max:
    description: installed capacity
    dims: [generator]
  energy_cost:
    description: cost of one unit of output
    dims: [generator]
  load:
    description: demand at each bus
    dims: [bus]
  cap:
    description: forward transmission limit
    dims: [line]
  neg_cap:
    description: reverse transmission limit
    dims: [line]
  bus_cap:
    description: most a bus may export over any one line
    dims: [bus]
  offer_cost:
    description: cost of holding one unit of reserve on an offer
    dims: [offer]
  req:
    description: reserve a market has to be filled with
    dims: [market]
  tranche_frac:
    description: share of capacity a generator may offer at a tranche
    dims: [tranche]
  zone_share:
    description: >-
      how much of a generator's reserve counts towards a zone — a generator may
      back several zones at a per-zone weight, so this cannot be a relation over
      the generator, which is single-valued per label; rows are absent where a
      generator backs no part of a zone
    dims: [generator, zone]
  zone_req:
    description: reserve a zone has to be covered by
    dims: [zone]

variables:
  p:
    description: output of a generator
    dims: [generator]
    bounds:
      lower: 0
  f:
    description: flow on a line, signed towards its `line_to` bus
    dims: [line]
    bounds:
      lower: neg_cap
      upper: cap
  r:
    description: reserve held against an offer
    dims: [offer]
    bounds:
      lower: 0

expressions:
  reserve_of:
    expression: sum(r, by=gen_of, over=offer, into=generator)
    description: all the reserve a generator holds, across every offer it made

constraints:
  balance:
    description: what is generated at a bus plus what arrives over the lines meets the load there
    dims: [bus]
    expression: >-
      sum(p, by=gen_bus, over=generator, into=bus)
      + sum(f, by=line_to, over=line, into=bus)
      - sum(f, by=line_from, over=line, into=bus)
      == load
  export_cap:
    description: a line carries no more than the bus it leaves is allowed to export
    dims: [line]
    expression: f <= at(bus_cap, by=line_from, over=bus, into=line)
  requirement:
    description: the offers made into a market fill its requirement
    dims: [market]
    expression: sum(r, by=market_of, over=offer, into=market) >= req
  headroom:
    description: a generator's output plus the reserve it holds stays inside its capacity
    dims: [generator]
    expression: p + reserve_of <= p_max
  offer_cap:
    description: >-
      an offer is capped by its tranche's share of its generator's capacity —
      two other dimensions' parameters pulled back through two legs of one edge
      set
    dims: [offer]
    expression: r <= at(tranche_frac, by=tranche_of, over=tranche, into=offer) * at(p_max, by=gen_of, over=generator, into=offer)
  zone_cover:
    description: the weighted reserve of the generators backing a zone covers its requirement
    dims: [zone]
    expression: sum(zone_share * reserve_of, over=generator) >= zone_req

objective:
  sense: minimize
  description: what the energy costs to generate, plus what the reserve costs to hold
  expression: sum(p * energy_cost) + sum(r * offer_cost)

# sources: parameter name -> frame or parquet path
with sps.solve('examples/reserves.yaml', sources) as solution:
    solution.objective  # 915.0
    solution.dual('balance')

def build(tables: dict[str, pd.DataFrame]) -> linopy.Model:
    """The instance's tables as a linopy model, row for row.

    ``tables`` is the same mapping the specsolve call attaches as ``sources``.
    """
    series = {
        k: tables[k].set_index(tables[k].columns[0])['value']
        for k in (
            'p_max',
            'energy_cost',
            'load',
            'cap',
            'neg_cap',
            'bus_cap',
            'offer_cost',
            'req',
            'tranche_frac',
            'zone_req',
        )
    }
    buses = pd.Index(series['load'].index, name='bus')
    offers = tables['offer'].set_index('offer')
    zones = pd.Index(series['zone_req'].index, name='zone')

    gen_at = indicator(buses, tables['gen_bus'], 'generator', 'bus')
    line_in = indicator(buses, tables['line_to'], 'line', 'bus')
    line_out = indicator(buses, tables['line_from'], 'line', 'bus')
    offer_gen = indicator(pd.Index(series['p_max'].index, name='generator'), tables['gen_of'], 'offer', 'generator')
    offer_market = indicator(pd.Index(series['req'].index, name='market'), tables['market_of'], 'offer', 'market')

    zone_at = pd.DataFrame(0.0, index=zones, columns=series['p_max'].index)
    for gen, zone, share in zip(
        tables['zone_share']['generator'], tables['zone_share']['zone'], tables['zone_share']['value'], strict=True
    ):
        zone_at.loc[zone, gen] = share
    zone_at.columns.name = 'generator'

    tranche_of = tables['tranche_of'].set_index('offer')['tranche']
    gen_of = tables['gen_of'].set_index('offer')['generator']
    r_cap = tranche_of.map(series['tranche_frac']) * gen_of.map(series['p_max'])
    f_cap = tables['line_from'].set_index('line')['bus'].map(series['bus_cap'])

    m = linopy.Model()
    p = m.add_variables(lower=0, coords=[series['p_max'].index], name='p')
    f = m.add_variables(lower=series['neg_cap'], upper=series['cap'], coords=[series['cap'].index], name='f')
    r = m.add_variables(lower=0, upper=r_cap, coords=[offers.index], name='r')

    m.add_constraints(
        (p * gen_at).sum('generator') + (f * line_in).sum('line') - (f * line_out).sum('line') == series['load'],
        name='balance',
    )
    m.add_constraints(f <= f_cap, name='export_cap')
    m.add_constraints((r * offer_market).sum('offer') >= series['req'], name='requirement')
    reserve_of = (r * offer_gen).sum('offer')
    m.add_constraints(p + reserve_of <= series['p_max'], name='headroom')
    m.add_constraints((reserve_of * xr.DataArray(zone_at)).sum('generator') >= series['zone_req'], name='zone_cover')
    m.add_objective((p * series['energy_cost']).sum() + (r * series['offer_cost']).sum())
    return m