Links, the commitment#

dimensions:
  scenario:
    description: the futures dispatch is chosen in, each with a weight
  snapshot:
    description: dispatch periods
    dtype: datetime
  link:
    description: controllable connections, each from one bus to the buses it delivers to
  period:
    description: investment periods — PyPSA's `investment_periods`
    dtype: int

relations:
  snapshot_period:
    description: the investment period a snapshot falls in
    key: snapshot
    values: period

parameters:
  Link_committable:
    description: whether flow is gated by an on/off status decision
    dims: [link]
    dtype: bool
  Link_min_up_time:
    description: least snapshots a link stays on once started
    dims: [scenario, link]
    dtype: int
  Link_min_down_time:
    description: least snapshots a link stays off once stopped
    dims: [scenario, link]
    dtype: int
  Link_status_initial:
    description: one where the link was on before the first snapshot, zero where off — PyPSA's `up_time_before > 0`, data prep
    dims: [scenario, link]
    dtype: int
  Link_must_stay_up:
    description: >-
      true while the up time a link brought into the horizon still binds —
      data prep, since `position()` compares against a literal rather than a
      parameter
    dims: [scenario, snapshot, link]
    dtype: bool
  Link_must_stay_down:
    description: >-
      true while the down time a link brought into the horizon still binds —
      PyPSA's `min_down_time - down_time_before` snapshots, where
      `down_time_before > 0`, data prep for the same reason
    dims: [scenario, snapshot, link]
    dtype: bool
  Link_start_up_cost:
    description: cost of one start
    dims: [scenario, link]
  Link_shut_down_cost:
    description: cost of one stop
    dims: [scenario, link]
  Link_stand_by_cost:
    description: cost of one snapshot spent on
    dims: [scenario, snapshot, link]
  Link_big_m:
    description: a bound safely above any feasible flow — the build cap at full availability, data prep
    dims: [scenario, link]

variables:
  Link_status:
    description: >-
      `Link-status` — how much of a committable link is on: an integer
      the rows below cap at one, or at the module count where the build is
      modular
    dims: [scenario, snapshot, link]
    where: Link_committable AND Link_active
    domain: integer
    bounds:
      lower: 0
  Link_start_up:
    description: "`Link-start_up` — how much of a committable link turns on this snapshot, capped as the status is"
    dims: [scenario, snapshot, link]
    where: Link_committable AND Link_active
    domain: integer
    bounds:
      lower: 0
  Link_shut_down:
    description: "`Link-shut_down` — how much of a committable link turns off this snapshot, capped as the status is"
    dims: [scenario, snapshot, link]
    where: Link_committable AND Link_active
    domain: integer
    bounds:
      lower: 0

given:
  parameters:
    snapshot_weightings_objective: { dims: [snapshot] }
    Link_p_nom: { dims: [scenario, link] }
    Link_p_nom_extendable: { dims: [link], dtype: bool }
    Link_p_min_pu: { dims: [scenario, snapshot, link] }
    Link_p_max_pu: { dims: [scenario, snapshot, link] }
    Link_p_nom_mod: { dims: [link] }
    Link_modules_installed: { dims: [scenario, link] }
    Link_p_min_pu_nonneg: { dims: [link], dtype: bool }
    Link_maintenance_pu: { dims: [scenario, link] }
    period_weight_objective: { dims: [period] }
    Link_active: { dims: [snapshot, link], dtype: bool }
  variables:
    Link_p: { dims: [scenario, snapshot, link] }
    Link_n_mod: { dims: [link], domain: integer }
    Link_maintenance_capacity: { dims: [scenario, snapshot, link] }
    Link_maintenance_status: { dims: [scenario, snapshot, link] }
    Link_p_nom_ext: { dims: [link] }
  expressions:
    scenario_opex: { dims: [scenario] }

expressions:
  Link_previous_status:
    description: >-
      the commitment state a link carries into a snapshot — the state it
      brought into the horizon at the first, the previous snapshot's after that
    dims: [scenario, snapshot, link]
    cases:
      opening: { when: "position(snapshot) == 0", expression: Link_status_initial }
    otherwise: shift(Link_status, along=snapshot, offset=1)
  Link_commitment_opex:
    expression: >-
      sum(sum(((Link_status * Link_stand_by_cost) * snapshot_weightings_objective) * at(period_weight_objective, by=snapshot_period, over=period, into=snapshot), over=link), over=snapshot)
      + sum(sum(Link_start_up * Link_start_up_cost, over=link), over=snapshot)
      + sum(sum(Link_shut_down * Link_shut_down_cost, over=link), over=snapshot)
    adds_to: scenario_opex

constraints:
  Link_com_p_lower:
    description: "`Link-com-p-lower` — a committed link flows at least its minimum; off, at least nothing"
    dims: [scenario, snapshot, link]
    where: Link_committable AND not Link_p_nom_extendable AND Link_active
    expression: Link_p >= Link_p_min_pu * Link_p_nom * (Link_status - Link_maintenance_pu * Link_maintenance_status)
  Link_com_p_upper:
    description: "`Link-com-p-upper` — a committed link flows at most what is available; off, at most nothing"
    dims: [scenario, snapshot, link]
    where: Link_committable AND not Link_p_nom_extendable AND Link_active
    expression: Link_p <= Link_p_max_pu * Link_p_nom * (Link_status - Link_maintenance_pu * Link_maintenance_status)
  Link_com_transition_start_up:
    description: "`Link-com-transition-start-up` — turning on is a start, counted against the state the link carried into the snapshot"
    dims: [scenario, snapshot, link]
    where: Link_committable AND Link_active
    expression: Link_start_up >= Link_status - Link_previous_status
  Link_com_transition_shut_down:
    description: "`Link-com-transition-shut-down` — turning off is a stop, counted against the state the link carried into the snapshot"
    dims: [scenario, snapshot, link]
    where: Link_committable AND Link_active
    expression: Link_shut_down >= Link_previous_status - Link_status
  Link_com_up_time:
    description: >-
      `Link-com-up-time` — a link started within its own minimum up time
      is still on. The first snapshot's share of the window is the brought-in
      up time's, which the must-stay-up mask carries
    dims: [scenario, snapshot, link]
    where: Link_committable AND Link_min_up_time > 0 AND position(snapshot) > 0 AND Link_active
    expression: sum_back(Link_start_up, along=snapshot, window=Link_min_up_time) <= Link_status
  Link_com_down_time:
    description: >-
      `Link-com-down-time` — a link stopped within its own minimum down
      time is still off. The first snapshot's share of the window is the
      brought-in down time's, which the must-stay-down mask carries
    dims: [scenario, snapshot, link]
    where: Link_committable AND Link_min_down_time > 0 AND position(snapshot) > 0 AND Link_active
    expression: sum_back(Link_shut_down, along=snapshot, window=Link_min_down_time) <= 1 - Link_status
  Link_com_status_must_stay_up:
    description: "`Link-com-status-min_up_time_must_stay_up` — a link still serving the up time it brought in stays on"
    dims: [scenario, snapshot, link]
    where: Link_committable AND Link_must_stay_up AND Link_active
    expression: Link_status == 1
  Link_com_status_must_stay_down:
    description: >-
      `Link-com-status-min_down_time_must_stay_up` — a link still serving
      the down time it brought in stays off; PyPSA names the row `_must_stay_up`
    dims: [scenario, snapshot, link]
    where: Link_committable AND Link_must_stay_down AND Link_active
    expression: Link_status == 0
  Link_com_ext_p_upper_cap:
    description: >-
      `Link-com-ext-p-upper-cap` — a committed extendable link flows
      at most what is available of the chosen build, whatever its status
    dims: [scenario, snapshot, link]
    where: Link_committable AND Link_p_nom_extendable AND NOT (Link_p_nom_mod > 0) AND Link_active
    expression: Link_p <= Link_p_max_pu * (Link_p_nom_ext - Link_maintenance_pu * Link_maintenance_capacity)
  Link_com_ext_p_upper_big_m:
    description: "`Link-com-ext-p-upper-bigM` — off, a link flows nothing; on, the big M is no bound"
    dims: [scenario, snapshot, link]
    where: Link_committable AND Link_p_nom_extendable AND NOT (Link_p_nom_mod > 0) AND Link_active
    expression: Link_p <= Link_big_m * Link_status
  Link_com_ext_p_lower:
    description: >-
      `Link-com-ext-p-lower` — a committed extendable link flows at
      least its minimum of the chosen build; off, the big M releases the row
    dims: [scenario, snapshot, link]
    where: Link_committable AND Link_p_nom_extendable AND NOT (Link_p_nom_mod > 0) AND Link_active
    expression: >-
      Link_p >=
      Link_p_min_pu * (Link_p_nom_ext - Link_maintenance_pu * Link_maintenance_capacity)
      + Link_big_m * Link_status - Link_big_m
  Link_com_ext_p_lower_nonneg:
    description: >-
      `Link-com-ext-p-lower-nonneg` — where no minimum-per-unit is
      negative, flow is also plainly non-negative, a row the big-M lower
      cannot assert while the link is off
    dims: [scenario, snapshot, link]
    where: >-
      Link_committable AND Link_p_nom_extendable
      AND Link_p_min_pu_nonneg AND NOT (Link_p_nom_mod > 0) AND Link_active
    expression: Link_p >= 0
  Link_com_mod_p_lower:
    description: >-
      `Link-com-mod-p-lower` — a committed modular link flows at least
      its minimum of one module, whether the build is fixed or a decision
    dims: [scenario, snapshot, link]
    where: Link_committable AND Link_p_nom_mod > 0 AND Link_active
    expression: Link_p >= Link_p_min_pu * Link_p_nom_mod * (Link_status - Link_maintenance_pu * Link_maintenance_status)
  Link_com_mod_p_upper:
    description: >-
      `Link-com-mod-p-upper` — a committed modular link flows at most
      one module's share, whether the build is fixed or a decision
    dims: [scenario, snapshot, link]
    where: Link_committable AND Link_p_nom_mod > 0 AND Link_active
    expression: Link_p <= Link_p_max_pu * Link_p_nom_mod * (Link_status - Link_maintenance_pu * Link_maintenance_status)
  Link_status_p_fixed_upper:
    description: >-
      `Link-status-p-fixed-upper` — a status is at most the modules in
      place, an explicit row as PyPSA writes it: one where the build is not
      modular, and the fixed build's whole count of modules where it is
    dims: [scenario, snapshot, link]
    where: Link_committable AND NOT (Link_p_nom_extendable AND Link_p_nom_mod > 0) AND Link_active
    expression: Link_status <= Link_modules_installed
  Link_start_up_p_fixed_upper:
    description: >-
      `Link-start_up-p-fixed-upper` — a start is at most the modules in
      place, an explicit row as PyPSA writes it: one where the build is not
      modular, and the fixed build's whole count of modules where it is
    dims: [scenario, snapshot, link]
    where: Link_committable AND NOT (Link_p_nom_extendable AND Link_p_nom_mod > 0) AND Link_active
    expression: Link_start_up <= Link_modules_installed
  Link_shut_down_p_fixed_upper:
    description: >-
      `Link-shut_down-p-fixed-upper` — a stop is at most the modules in
      place, an explicit row as PyPSA writes it: one where the build is not
      modular, and the fixed build's whole count of modules where it is
    dims: [scenario, snapshot, link]
    where: Link_committable AND NOT (Link_p_nom_extendable AND Link_p_nom_mod > 0) AND Link_active
    expression: Link_shut_down <= Link_modules_installed
  Link_status_p_nom_variable_upper:
    description: "`Link-status-p_nom-variable-upper` — a modular link is on only where a module is built"
    dims: [scenario, snapshot, link]
    where: Link_committable AND Link_p_nom_extendable AND Link_p_nom_mod > 0 AND Link_active
    expression: Link_status <= Link_n_mod
  Link_start_up_p_nom_variable_upper:
    description: "`Link-start_up-p_nom-variable-upper` — a modular link starts only where a module is built"
    dims: [scenario, snapshot, link]
    where: Link_committable AND Link_p_nom_extendable AND Link_p_nom_mod > 0 AND Link_active
    expression: Link_start_up <= Link_n_mod
  Link_shut_down_p_nom_variable_upper:
    description: "`Link-shut_down-p_nom-variable-upper` — a modular link stops only where a module is built"
    dims: [scenario, snapshot, link]
    where: Link_committable AND Link_p_nom_extendable AND Link_p_nom_mod > 0 AND Link_active
    expression: Link_shut_down <= Link_n_mod