Transformers#

given:
  parameters:
    scenario_weight: { dims: [scenario] }
    transmission_losses: { dims: [], dtype: bool }
  expressions:
    total_cost: { dims: [] }
    Bus_injection: { dims: [bus, scenario, snapshot] }
    Cycle_angle_sum: { dims: [cycle, scenario, snapshot] }

dimensions:
  scenario:
    description: the futures dispatch is chosen in, each with a weight
  snapshot:
    description: dispatch periods
    dtype: datetime
    ordered: true
  bus:
    description: network nodes
  transformer:
    description: passive branches between two buses, their flow set by impedance and tap ratio, with a phase shift fixed or optimised
  cycle:
    description: >-
      independent cycles of the passive network graph, the cycle basis, data
      prep. Each period has its own basis, of the branches that are active in it. A
      label is a position in that period's basis, so one label is a different
      cycle in another period
  segment:
    description: >-
      the cuts a passive branch's loss curve is held above. They are PyPSA's
      tangents, as many as its `segments` count, or its secants, as many as
      its tolerance loop places. A lossless run has none
    dtype: int
  period:
    description: investment periods. It is PyPSA's `investment_periods`
    dtype: int
    ordered: true

relations:
  snapshot_period:
    description: the investment period a snapshot falls in
    key: snapshot
    values: period
  Transformer_bus0:
    description: the bus a transformer's flow is measured at
    key: transformer
    values: bus
  Transformer_bus1:
    description: the bus at a transformer's other end
    key: transformer
    values: bus

parameters:
  Transformer_active:
    description: whether a transformer is active in a snapshot's period. It is PyPSA's `active`, data prep
    dims: [snapshot, transformer]
    dtype: bool
  Transformer_active_asset:
    description: >-
      whether a transformer is one of PyPSA's `active_assets`, by its `active`
      flag alone, without build year and lifetime. A unit that is active in no
      snapshot of the horizon still counts. PyPSA refuses one that differs by
      scenario (`constants.py:54`)
    dims: [transformer]
    dtype: bool
  Transformer_capital_weight:
    description: the sum of period weights a transformer is active in. It is PyPSA's `active * period_weighting`, summed, data prep
    dims: [transformer]
  Transformer_s_nom:
    description: nominal apparent power
    dims: [scenario, transformer]
  Transformer_s_nom_extendable:
    description: whether the nominal apparent power is a decision
    dims: [transformer]
    dtype: bool
  Transformer_s_nom_mod:
    description: the module size a build comes in whole numbers of. No value means the build is continuous
    dims: [transformer]
    missing: absent
  Transformer_s_max_pu:
    description: most flow either way, per unit of nominal apparent power
    dims: [scenario, snapshot, transformer]
  Transformer_s_nom_min:
    description: least nominal apparent power an extendable transformer may be built at
    dims: [scenario, transformer]
  Transformer_s_nom_max:
    description: most nominal apparent power an extendable transformer may be built at
    dims: [scenario, transformer]
  Transformer_capital_cost:
    description: >-
      cost of one unit of nominal apparent power for the modelled horizon
      (PyPSA's `periodized_cost`), data prep. It is `overnight_cost` as an
      annuity over `lifetime` at `discount_rate`, times `nyears`, where
      `overnight_cost` is given, and `capital_cost` where it is not. Both add
      `fom_cost` (`components.py:1157-1178`, `costs.py:102-203`)
    dims: [scenario, transformer]
  Transformer_s_nom_set:
    description: a given nominal apparent power for an extendable transformer. One without a value has no row here
    dims: [transformer]
    missing: absent
  Transformer_s_set:
    description: a given flow schedule. A transformer without one has no row here
    dims: [scenario, snapshot, transformer]
    missing: absent
  Transformer_v_ang_max:
    description: >-
      the most the voltage angle difference across a transformer, its phase
      shift included, may be either way, in degrees. It is PyPSA's
      `v_ang_max`. Infinite, and so no row, by default. The deprecated
      `v_ang_min` is ignored, as a line's
    dims: [scenario, transformer]
    missing: absent
  Transformer_x_pu_eff:
    description: >-
      the transformer's effective series reactance. It is PyPSA's `x_pu_eff`,
      `x` over its `s_nom` times its tap ratio, data prep
    dims: [scenario, transformer]
  Transformer_cycle_weight:
    description: >-
      the transformer's effective series reactance, `x` times its tap ratio,
      signed by its orientation in the cycle. It is PyPSA's `x_pu_eff`, the
      cycle basis, data prep. A transformer in no cycle has no row. It is the
      same in every scenario, as a line's
    dims: [period, transformer, cycle]
    missing: absent
  Transformer_phase_shift_weight:
    description: >-
      a fixed transformer's phase shift in radians at each snapshot, signed by
      its orientation in the cycle, data prep. It is a constant added to the
      cycle sum. It is zero for a varying transformer, whose shift is a
      decision instead. The constant and the variable term thus never both
      count a shift. A transformer with no shift or in no cycle of its
      snapshot's period has no row
    dims: [scenario, snapshot, transformer, cycle]
    missing: absent
  Transformer_phase_shift_varying:
    description: >-
      whether a transformer's phase shift is a decision (PyPSA's
      `phase_shift_min < phase_shift_max`, read as a flag in data prep). False
      is a fixed shift, set by `phase_shift`. It may differ by scenario, as
      PyPSA reads it per scenario (`variables.py:446-456`)
    dims: [scenario, transformer]
    dtype: bool
  Transformer_phase_shift_min:
    description: >-
      the least a varying transformer's phase shift may take, in degrees. It
      is PyPSA's `phase_shift_min`. Where it is below `phase_shift_max` the
      shift is a decision, otherwise the transformer keeps its fixed
      `phase_shift`
    dims: [scenario, transformer]
  Transformer_phase_shift_max:
    description: >-
      the most a varying transformer's phase shift may take, in degrees. It is
      PyPSA's `phase_shift_max`. Equal to `phase_shift_min` for a fixed
      transformer
    dims: [scenario, transformer]
  Transformer_phase_shift_fixed:
    description: >-
      a fixed transformer's phase shift at each snapshot, in degrees. It is
      PyPSA's `phase_shift`, zero by default. A varying transformer's shift is
      a decision instead
    dims: [scenario, snapshot, transformer]
  Transformer_phase_shift_cycle_weight:
    description: >-
      the cycle sign for a varying transformer's phase shift, times π/180 so a
      shift in degrees enters the cycle sum in radians, data prep. It is zero
      for a fixed transformer or one in no cycle
    dims: [scenario, period, transformer, cycle]
  Transformer_loss_max:
    description: >-
      the loss at a transformer's rating (PyPSA's `r_pu_eff * (s_max_pu *
      s_nom_max)**2`), data prep. Its `r_pu_eff` is the resistance over the
      given `s_nom` times the tap ratio
    dims: [scenario, snapshot, transformer]
  Transformer_loss_slope:
    description: >-
      the slope of a cut to a transformer's loss curve, data prep. It is a
      tangent's `2 * r_pu_eff * p_k` or a secant's `r_pu_eff * (p_k + p_k+1)`,
      as a line's. It uses the transformer's own `r_pu_eff` and rating
    dims: [scenario, snapshot, transformer, segment]
  Transformer_loss_offset:
    description: >-
      where that cut meets the loss axis: a tangent's `loss_k - slope_k *
      p_k`, a secant's `-r_pu_eff * p_k * p_k+1`, negative, data prep
    dims: [scenario, snapshot, transformer, segment]

variables:
  Transformer_s:
    description: >-
      `Transformer-s` — PyPSA's `p0`, the flow measured at the
      `Transformer_bus0` end: a positive value withdraws there and injects at
      `Transformer_bus1`, lossless
    dims: [scenario, snapshot, transformer]
    where: Transformer_active
  Transformer_loss:
    description: >-
      `Transformer-loss` — what a transformer dissipates carrying its flow, as
      a line does. Absent, and zero in the balance, where the network is
      lossless
    dims: [scenario, snapshot, transformer]
    where: Transformer_lossy
    missing: 0
    bounds:
      lower: 0
  Transformer_phase_shift:
    description: >-
      `Transformer-phase_shift` — a phase-shifting transformer's voltage angle
      shift in degrees, chosen per snapshot to redistribute the flows around
      its cycles without moving active power. Absent, and zero in the cycle
      sum, where the shift is fixed
    dims: [scenario, snapshot, transformer]
    where: Transformer_phase_shift_varying AND Transformer_active
    missing: 0
    bounds:
      lower: Transformer_phase_shift_min
      upper: Transformer_phase_shift_max
  Transformer_s_nom_ext:
    description: >-
      `Transformer-s_nom` — nominal apparent power where it is a decision, for
      a transformer that is active. A fixed build is the parameter of the same
      PyPSA name
    dims: [transformer]
    where: Transformer_s_nom_extendable AND Transformer_active_asset
  Transformer_n_mod:
    description: "`Transformer-n_mod` — how many modules of an extendable modular build. A unit that is not active has none"
    dims: [transformer]
    where: Transformer_s_nom_extendable AND Transformer_s_nom_mod > 0 AND Transformer_active_asset
    domain: integer
    bounds:
      lower: 0

expressions:
  Transformer_capex:
    expression: sum(scenario_weight * Transformer_s_nom_ext * Transformer_capital_cost * Transformer_capital_weight)
    adds_to: total_cost
  Transformer_s_monitored:
    description: the flow a transformer's post-contingency rows read, as a line's
    dims: [scenario, snapshot, transformer]
    cases:
      standing: { when: Transformer_active, expression: Transformer_s }
    otherwise: 0
  Transformer_injection:
    expression: >-
      -sum(Transformer_s, over=transformer, by=Transformer_bus0[bus])
      + sum(Transformer_s, over=transformer, by=Transformer_bus1[bus])
      - (0.5 * sum(Transformer_loss, over=transformer, by=Transformer_bus0[bus]))
      - (0.5 * sum(Transformer_loss, over=transformer, by=Transformer_bus1[bus]))
    adds_to: Bus_injection
  Transformer_angle_sum:
    expression: >-
      sum(Transformer_s * at(Transformer_cycle_weight, by=snapshot_period[period]), over=transformer)
      + sum(Transformer_phase_shift_weight, over=transformer)
      + sum(Transformer_phase_shift * at(Transformer_phase_shift_cycle_weight, by=snapshot_period[period]), over=transformer)
    adds_to: Cycle_angle_sum

conditions:
  Transformer_lossy:
    description: >-
      a transformer that is active in the snapshot's period, where the run models
      transmission losses
    condition: transmission_losses AND Transformer_active

constraints:
  Transformer_fix_s_lower:
    description: "`Transformer-fix-s-lower` — a fixed transformer carries at least the negative of its rating, the loss counted against it"
    dims: [scenario, snapshot, transformer]
    where: not Transformer_s_nom_extendable AND Transformer_active
    expression: Transformer_s - Transformer_loss >= -Transformer_s_max_pu * Transformer_s_nom
  Transformer_fix_s_upper:
    description: "`Transformer-fix-s-upper` — a fixed transformer carries at most its rating, the loss included"
    dims: [scenario, snapshot, transformer]
    where: not Transformer_s_nom_extendable AND Transformer_active
    expression: Transformer_s + Transformer_loss <= Transformer_s_max_pu * Transformer_s_nom
  Transformer_ext_s_lower:
    description: "`Transformer-ext-s-lower` — an extendable transformer carries at least the negative of its rating of the chosen build, the loss counted against it"
    dims: [scenario, snapshot, transformer]
    where: Transformer_s_nom_extendable AND Transformer_active
    expression: Transformer_s - Transformer_loss >= -Transformer_s_max_pu * Transformer_s_nom_ext
  Transformer_ext_s_upper:
    description: "`Transformer-ext-s-upper` — an extendable transformer carries at most its rating of the chosen build, the loss included"
    dims: [scenario, snapshot, transformer]
    where: Transformer_s_nom_extendable AND Transformer_active
    expression: Transformer_s + Transformer_loss <= Transformer_s_max_pu * Transformer_s_nom_ext
  Transformer_ext_s_nom_lower:
    description: "`Transformer-ext-s_nom-lower` — the chosen build is at least its floor in every scenario"
    dims: [scenario, transformer]
    where: Transformer_s_nom_extendable AND Transformer_active_asset
    expression: Transformer_s_nom_ext >= Transformer_s_nom_min
  Transformer_ext_s_nom_upper:
    description: "`Transformer-ext-s_nom-upper` — the chosen build is at most its cap in every scenario. A cap of infinity is no row"
    dims: [scenario, transformer]
    where: Transformer_s_nom_extendable AND Transformer_active_asset AND Transformer_s_nom_max
    expression: Transformer_s_nom_ext <= Transformer_s_nom_max
  Transformer_s_nom_set:
    description: "`Transformer-s_nom_set` — the chosen build pinned, wherever a value is given"
    dims: [transformer]
    where: Transformer_s_nom_extendable AND Transformer_active_asset AND Transformer_s_nom_set
    expression: Transformer_s_nom_ext == Transformer_s_nom_set
  Transformer_s_nom_modularity:
    description: "`Transformer-s_nom_modularity` — the chosen build is a whole number of modules"
    dims: [transformer]
    where: Transformer_s_nom_extendable AND Transformer_s_nom_mod > 0 AND Transformer_active_asset
    expression: Transformer_s_nom_ext == Transformer_s_nom_mod * Transformer_n_mod
  Transformer_s_set:
    description: "`Transformer-s_set` — flow pinned to the given schedule, wherever one is given"
    dims: [scenario, snapshot, transformer]
    where: Transformer_s_set AND Transformer_active
    expression: Transformer_s == Transformer_s_set
  Transformer_v_ang_lower:
    description: >-
      `Transformer-v_ang-lower` — a transformer with a fixed shift carries at
      least the flow at which the voltage angle difference across it is minus
      its limit. That difference is `x_pu_eff` times the flow plus the shift
    dims: [scenario, snapshot, transformer]
    where: Transformer_v_ang_max AND NOT Transformer_phase_shift_varying AND Transformer_active
    expression: Transformer_s >= -(Transformer_v_ang_max + Transformer_phase_shift_fixed) * (3.141592653589793 / 180) / Transformer_x_pu_eff
  Transformer_v_ang_upper:
    description: >-
      `Transformer-v_ang-upper` — a transformer with a fixed shift carries at
      most the flow at which the voltage angle difference across it reaches
      its limit. That difference includes the shift
    dims: [scenario, snapshot, transformer]
    where: Transformer_v_ang_max AND NOT Transformer_phase_shift_varying AND Transformer_active
    expression: Transformer_s <= (Transformer_v_ang_max - Transformer_phase_shift_fixed) * (3.141592653589793 / 180) / Transformer_x_pu_eff
  Transformer_v_ang_var_lower:
    description: >-
      `Transformer-v_ang-var-lower` — for a transformer whose shift is a
      decision, the flow plus the shift over `x_pu_eff` is at least minus the
      limit over `x_pu_eff`
    dims: [scenario, snapshot, transformer]
    where: Transformer_v_ang_max AND Transformer_phase_shift_varying AND Transformer_active
    expression: Transformer_s + Transformer_phase_shift * (3.141592653589793 / 180) / Transformer_x_pu_eff >= -Transformer_v_ang_max * (3.141592653589793 / 180) / Transformer_x_pu_eff
  Transformer_v_ang_var_upper:
    description: >-
      `Transformer-v_ang-var-upper` — for a transformer whose shift is a
      decision, the flow plus the shift over `x_pu_eff` is at most the limit
      over `x_pu_eff`
    dims: [scenario, snapshot, transformer]
    where: Transformer_v_ang_max AND Transformer_phase_shift_varying AND Transformer_active
    expression: Transformer_s + Transformer_phase_shift * (3.141592653589793 / 180) / Transformer_x_pu_eff <= Transformer_v_ang_max * (3.141592653589793 / 180) / Transformer_x_pu_eff
  Transformer_loss_upper:
    description: "`Transformer-loss_upper` — a transformer dissipates at most the loss at its rating"
    dims: [scenario, snapshot, transformer]
    where: Transformer_lossy
    expression: Transformer_loss <= Transformer_loss_max
  Transformer_loss_tangents_forward:
    description: >-
      `Transformer-loss_tangents-{k}-1`, `Transformer-loss_secants-pos` — the
      loss sits above every cut to its curve for flow one way, as a line's
      does, over the segment dimension
    dims: [scenario, snapshot, transformer, segment]
    where: Transformer_lossy
    expression: Transformer_loss + Transformer_loss_slope * Transformer_s >= Transformer_loss_offset
  Transformer_loss_tangents_reverse:
    description: >-
      `Transformer-loss_tangents-{k}--1`, `Transformer-loss_secants-neg` — the
      same fan mirrored, the loss depending on the flow's magnitude
    dims: [scenario, snapshot, transformer, segment]
    where: Transformer_lossy
    expression: Transformer_loss - Transformer_loss_slope * Transformer_s >= Transformer_loss_offset