Controllers Reference

Supertype of the per-controller state carried between outer iterations.

Supertype of the updates a controller requests after an outer iteration.

Supertype of the outer-loop controllers the control framework iterates (tap, shunt, machine, series reactance, UPFC, HVDC pair).

Outer-loop controller settings of a run: iteration budget, tolerance and logging of the controller loop.

Outcome of a controller-driven run: convergence, outer iterations and the per-controller updates that were applied.

collect_outer_controllers(net) -> Vector{AbstractOuterController}

Every outer-loop controller attached to the network, across all controller families.

controllableElements(net) -> Vector{NamedTuple}

One record per registered controller describing the controllable element in a uniform vocabulary: element (the physical device), device (its role label), actuator and its [actuator_min, actuator_max] range, the controlled quantity with target/target_value, discrete, enabled, and the live status/converged/at_limit flags. Derived on demand from the registered controllers — purely a reporting view, no control behavior attached.

latest_control_result(net) -> Union{Nothing,ControlRunResult}

The controller result of the network's last controlled run.

run_control!(net; ...)

Outer-loop orchestration layer around runpf! for controller-based network updates. It does not replace runpf!; it coordinates built-in or user-defined controllers and returns a ControlRunResult.

applyConfiguredControllers!(net::Net, control_cfg::ControlConfig) -> Int

Instantiate the outer-loop controllers declared under control.controllers onto net by calling the matching device function (addPowerTransformerControl!, addMachineVoltageControl!, addShuntVoltageControl!, addSeriesReactanceControl!, addHvdcPairControl!, addUpfcControl!). Returns the number of controllers added.

Entries whose controlled element already carries a controller of the same type are skipped, so repeated runs on the same Net stay idempotent; edit programmatically or rebuild the net to change an already-applied controller. Structural errors (unknown type or key, missing required key) and device errors (unknown bus/branch/transformer, invalid limits) throw an ArgumentError naming the entry.

The run pipeline calls this automatically before the outer control loop when control.enabled is true and entries exist; call it directly to apply a configuration to a programmatically built net.

HvdcPairControl <: AbstractOuterController

Pairing controller for the two converter injections of a back-to-back (or point-to-point) HVDC link. Sign convention follows the MATPOWER dcline: p_transfer_mw is the active power LEAVING the from-side AC bus into the link; the from-side injection is -p_transfer_mw, the to-side injection is p_transfer_mw - loss with loss = loss_mw + loss_fraction * |p_transfer|. In the default :setpoint mode the transfer is a control setpoint (HVDC has no angle coupling), so the active-power side needs no iteration; only voltage-target terminals iterate via the per-side secant on the terminal Q within its reactive range.

In :island_feed mode the dependency inverts: the receiving converter is grid-forming, it IS the reference (slack) of its island, and its output is the island balance outcome. The controller then mirrors that outcome onto the sending side each outer iteration, P_from = -(P_island + loss), with an honest at_limit once the island draw exceeds p_rating_mw (the power flow's slack still balances the island, so the model cannot show the real collapse; the flag marks the violated rating). State is owned by run_control!; construct via addHvdcPairControl!.

addHvdcLink!(net; from_bus, to_bus, name = nothing, kind = :b2b,
             status = 1, from_prosumer = nothing, to_prosumer = nothing)

Register a Stage-0 HVDC link record on a hand-built net so the result layer reports it (HVDC Link Flows table, ACPFlowReport.hvdc_links, hvdc_links.csv). Importers and addHvdcPairControl! register links automatically; this helper covers programmatic nets that keep fixed converter injections without a controller (including a grid-forming reference terminal, which a setpoint pair could not carry). Terminals resolve like the pair controller (unique generator-type injection per bus, explicit index on ambiguity) but without role restrictions: the record is bookkeeping, not an actuator. Returns the created HvdcLink.

addHvdcPairControl!(net; from_bus, to_bus, p_transfer_mw, ...)

Add a back-to-back HVDC pairing controller coupling the converter injections at from_bus and to_bus.

Arguments

• net::Net: the network.
• from_bus::String, to_bus::String: AC terminal buses of the two converters. The pair fixes the sign convention: p_transfer_mw leaves the from side.
• mode::Symbol = :setpoint: :setpoint steers a given transfer; :island_feed models a grid-forming receiving converter that is the reference (slack) of its island. There the transfer is derived from the island balance each outer iteration and mirrored onto the sending side, P_from = -(P_island + loss); p_transfer_mw must be omitted and the to side carries neither q_mvar nor vset_pu (the slack holds its own voltage). The island draw is read at the reference bus (net injection plus local load; a shunt at the PCC is not supported).
• p_transfer_mw::Float64: transfer setpoint in MW (signed; negative reverses the link). Required in :setpoint mode, forbidden in :island_feed.
• deadband_p_mw::Float64 = 1e-3: island_feed only, the mirror counts as settled when applied and derived transfer agree within this band.
• loss_mw::Float64 = 0.0, loss_fraction::Float64 = 0.0: converter loss model, loss = loss_mw + loss_fraction * |p_transfer_mw| (the MATPOWER LOSS0/LOSS1 pair maps directly).
• p_rating_mw = nothing: optional transfer rating; |p_transfer_mw| is clamped to it with honest at_limit.
• from_q_mvar, to_q_mvar: fixed terminal reactive injection in MVAr.
• from_vset_pu, to_vset_pu: terminal voltage target instead of fixed Q (per side exclusive with q_mvar); requires the matching from_qmin_mvar/from_qmax_mvar resp. to_qmin_mvar/to_qmax_mvar range (defaults from the prosumer's minQ/maxQ when present).
• deadband_vm_pu::Float64 = 1e-3, max_outer_iters::Int = 20, enabled::Bool = true, name = nothing: as in the other controllers.
• from_prosumer, to_prosumer: explicit prosumer indices when a bus carries more than one injection.

The active-power side is a setpoint (applied in the first outer iteration); the invariant P_to = p_transfer_mw - loss holds exactly after every apply step. Voltage-target terminals iterate a per-side secant on their reactive injection, mirroring addMachineVoltageControl!. Fails for unknown buses, ambiguous or regulated prosumers, identical from/to prosumers, a per-side q_mvar/vset_pu double specification, a missing reactive range in vset mode, or a second pair controller on one of the prosumers.

clearHvdcPairControllers!(net)

Remove all HVDC pair controllers from net (other controllers stay). The persistent link records in net.hvdcLinks are kept, only their controller_name is reset: the link exists independently of how it is steered.

printHvdcPairControllerSummary(io::IO, net::Net)
printHvdcPairControllerSummary(net::Net)

Engineering-style summary of the registered HVDC pair controllers, one block per pair: link and direction, transfer and loss, per-terminal P/Q and voltage state, and the honest limit flags. Prints nothing when no pair controller is registered.

MachineVoltageControl <: AbstractOuterController

Remote voltage controller for a single machine (generator prosumer).

The machine stays a PQ injection for the inner Newton-Raphson solve; between solves the controller moves the machine's reactive output q_mvar (clamped to [qmin_mvar, qmax_mvar]) until the voltage magnitude at target_bus is within deadband_vm_pu of target_vm_pu. This is the outer-loop counterpart of a PV bus whose regulated node is not the machine's own connection point (CGMES: a RegulatingControl whose terminal sits at a foreign bus).

The update rule is a secant iteration on the scalar map Q ↦ Vm(targetbus): the first move is a bounded fraction of the remaining reactive headroom in the physically expected direction (more injected Q raises the voltage), every following move uses the measured sensitivity of the two previous operating points. Reaching a reactive limit with the target still outside the deadband parks the controller `atlimit` — the exact analogue of PV→PQ switching under Q limits, and honest about what the machine can actually deliver.

Two limit modes (limit_mode):

• :constant_q (default): fixed machine limits [qmin_mvar, qmax_mvar], the classical synchronous-machine capability box.
• :current: STATCOM behavior (issue #297 Draft A). The device is a VSC whose bound is the converter current, so the deliverable reactive power scales with the terminal voltage: Q_lim = V_machine_bus * s_max_mva, symmetric (qmin = -Q_lim, qmax = +Q_lim), re-evaluated from the solved machine-bus voltage before every outer step. At the limit the injected Q therefore TRACKS the sagging or recovering voltage linearly — the defining contrast to the SVC's quadratic V^2 * B collapse (see ShuntVoltageControl) and to the constant-Q machine box. An at-limit STATCOM keeps adjusting while its voltage-dependent bound still moves and only parks at_limit once the bound has settled.

Runtime fields (status, converged, at_limit, achieved_vm_pu, …) are owned by run_control!; construct instances via addMachineVoltageControl!.

addMachineVoltageControl!(net; bus, target_bus, target_vm_pu, ...)

Add a remote voltage controller for the generator at bus that regulates the voltage magnitude at target_bus.

Arguments

• net::Net: the network.
• bus::String: the machine's own bus. The generator there must be a plain PQ injection (not voltage-regulating) — its reactive output is the actuator.
• target_bus::String: the regulated bus. Must be a PQ bus: a PV or slack target is already voltage-held by another unit and leaves this controller nothing to regulate (rejected with an error).
• target_vm_pu::Float64: voltage target at target_bus in p.u.
• qmin_mvar, qmax_mvar: reactive actuator range in MVAr. Default to the machine's own minQ/maxQ; required explicitly when the machine carries no scalar limits. Constant-Q mode only.
• s_max_mva::Union{Nothing,Float64}: STATCOM mode (issue #297 Draft A). The converter rating as MVA at 1.0 p.u. terminal voltage; the reactive bound becomes voltage-dependent, Q_lim = V_machine_bus * s_max_mva, symmetric around zero and refreshed every outer iteration. Mutually exclusive with qmin_mvar/qmax_mvar (the machine's own minQ/maxQ are deliberately ignored in this mode: the converter current IS the limit). Theory in FACTS Devices.
• i_max_ka::Union{Nothing,Float64}: alternative STATCOM rating as maximum converter current in kA; converted at add time via s_max_mva = sqrt(3) * vn_kV(bus) * i_max_ka. Mutually exclusive with s_max_mva.
• deadband_vm_pu::Float64 = 1e-3: convergence band around the target.
• prosumer_index::Union{Nothing,Int}: which prosumer to control when several generators sit at bus; defaults to the single generator there.
• max_outer_iters::Int = 20, enabled::Bool = true: outer-loop budget/switch.

Fails with an error for a missing bus, a missing or ambiguous machine, a voltage-regulating (PV) machine, a non-PQ target bus, an inverted Q range, a non-positive or doubly specified STATCOM rating, or a second active controller on the same machine or target bus.

buildMachineControllerReportRows(net; only=nothing) -> Vector{NamedTuple}

Typed report rows for machine voltage controllers, one per controller; only restricts the output to a single controller instance.

clearMachineControllers!(net)

Remove all machine voltage controllers from net.

printMachineControllerSummary(io, net)

Print a compact summary block for all configured machine voltage controllers.

addSeriesReactanceControl!(net; fromBus, toBus, p_target_mw, x_min_pu, x_max_pu, ...)

Add a TCSC-like series-reactance controller to the line branch fromBus to toBus. The outer control loop moves the branch series reactance x_pu within [x_min_pu, x_max_pu] until the branch carries p_target_mw in the fromBus to toBus direction.

Arguments

• net::Net: the network.
• fromBus::String, toBus::String: terminals of the controlled line branch; the pair also fixes the measurement direction of the flow.
• p_target_mw::Float64: active-power target for the branch in MW.
• x_min_pu::Float64, x_max_pu::Float64: admissible reactance range in p.u. Negative values (net capacitive branch) are allowed. TCSC mode only.
• v_inj_max_pu::Union{Nothing,Float64}: SSSC mode (issue #297 Draft F). The maximum injectable series voltage in p.u.; the reactance window becomes current-dependent, |x - x_base| <= v_inj_max_pu / |I| around the natural branch reactance, refreshed every outer iteration. Mutually exclusive with x_min_pu/x_max_pu (the injectable voltage IS the limit). Theory in FACTS Devices.
• deadband_p_mw::Float64 = 0.5: convergence band around the target.
• max_outer_iters::Int = 20, enabled::Bool = true: outer-loop budget and switch.
• name: optional controller name (defaults to TCSC_<from>_<to>, or SSSC_<from>_<to> in injected-voltage mode).

Fails with an error for a missing branch, a transformer branch (taps own transformer reactance, see the X(alpha) coupling of the tap controller), an inverted or missing range (TCSC mode), a doubly specified limit (both a range and v_inj_max_pu), a non-positive injectable voltage, a range whose series impedance magnitude enters the exclusion guard eps_z, a starting x_pu outside the range, or a second series controller on the same branch.

clearSeriesReactanceControllers!(net)

Remove all series-reactance controllers (TCSC/SSSC) from net, restoring each controlled branch to its physical base impedance (#329) so the cleared net carries the equipment model, not the last compensated operating point. Other controllers stay. Returns net.

printSeriesReactanceControllerSummary(io::IO, net::Net)
printSeriesReactanceControllerSummary(net::Net)

Engineering-style summary of the registered series-reactance (TCSC) controllers, one block per controller: branch and direction, target versus achieved flow, reactance and range, deadband, and the honest limit flags. Prints nothing when no series controller is registered; the classical result print calls it unconditionally, mirroring the machine controller summary.

ShuntVoltageControl <: AbstractOuterController

SVC-like variable-shunt voltage controller. The actuator is the shunt susceptance, expressed as MVAr at 1.0 p.u. of the bus nominal voltage (MATPOWER Bs convention, capacitive positive) within [bs_min_mvar, bs_max_mvar]. In range the controller holds target_vm_pu at its own bus via secant iteration; at a limit the susceptance stays clamped and the injected reactive power follows the bus voltage squared through the Y-bus stamp — the constant-B region of a real SVC. Reported honestly via at_limit.

Two actuator modes:

• continuous (default): the thyristor-controlled SVC, any susceptance in the range.
• discrete (step_mvar, issue #324): a mechanically switched capacitor/reactor bank (MSC/MSR). The susceptance moves in whole blocks of step_mvar; the secant proposal is truncated toward the target to whole steps, so the bank approaches from one side and NEVER overshoots (the anti-hunting guarantee). When no whole block improves the voltage further, the controller PARKS on the reached step (status = :parked, blocking like at_limit); it un-parks by itself when another controller moves the operating point far enough that a whole block helps again. At the outermost admissible block the constant-B limit region applies unchanged.

addShuntVoltageControl!(net; bus, target_vm_pu, bs_min_mvar, bs_max_mvar, ...)

Add an SVC-style variable-shunt voltage controller at bus. Creates its own shunt element (initially at bs_start_mvar) whose susceptance the outer control loop moves within [bs_min_mvar, bs_max_mvar] to hold target_vm_pu at the bus.

Arguments

• net::Net: the network.
• bus::String: the supported bus. Must be a PQ bus — a PV or slack bus is already voltage-held by another unit.
• target_vm_pu::Float64: voltage target at bus in p.u.
• bs_min_mvar, bs_max_mvar: susceptance range as MVAr at 1.0 p.u. (inductive negative, capacitive positive).
• step_mvar::Union{Nothing,Float64}: discrete MSC/MSR mode (issue #324). Block size of the switched bank in MVAr at 1.0 p.u.; the susceptance then only takes whole multiples of step_mvar inside the range, the start value is snapped to the grid, and the controller parks on the nearest step instead of hunting. nothing (default) is the continuous SVC actuator.
• bs_start_mvar::Float64 = 0.0: initial susceptance, clamped to the range (and snapped to the step grid in discrete mode).
• deadband_vm_pu::Float64 = 1e-3: convergence band around the target.
• max_outer_iters::Int = 20, enabled::Bool = true: outer-loop budget/switch.
• name: optional controller name (defaults to SVC_<bus>, or MSC_<bus> in discrete mode).

Fails with an error for a missing bus, an inverted susceptance range, a non-positive step, a step grid with no admissible block inside the range, a non-PQ bus, or a second shunt controller on the same bus. Warns when a transformer tap controller already regulates the same bus voltage (two controllers steering one voltage fight each other).

clearShuntControllers!(net)

Remove all shunt voltage controllers from net (machine controllers stay).

printShuntVoltageControllerSummary(io::IO, net::Net)
printShuntVoltageControllerSummary(net::Net)

Engineering-style summary of the registered shunt voltage controllers, one block per device: the controlled bus and its voltage target versus achieved, the actuator susceptance in MVar with its range, the mode (continuous SVC or discrete MSC/MSR switched bank with its step and block position), and the honest limit flags. Prints nothing when no shunt controller is registered; the classical result's "Transformer controls: none" line stays the deterministic parser anchor.

addPowerTransformerControl!(net; ...)

Add and validate a transformer tap controller.

Validation rules:

• Each actuator (ratio tap, phase tap) of a transformer may be driven by at most one active controller. Two controllers may coexist on one transformer when they drive disjoint actuators — the classic Schrägregelung split of a voltage controller (ratio tap) plus an active-power controller (phase tap).
• Required target fields must be set according to mode.
• control_ratio / control_phase must match the chosen mode.

addTapController!(net; kwargs...)

Attach a tap controller to a transformer; alias of addPowerTransformerControl!.

buildTapControllerReportRows(net::Net)

Build typed, machine-readable tap-controller report rows with engineering fields for textual and DataFrame-based reporting.

clearTapControllers!(net)

Remove all tap controllers from transformer windings in net.

get_branch_p_from_to_mw(net, from_bus, to_bus)

Return active power flow in MW for the oriented branch direction from_bus -> to_bus.

get_branch_q_from_to_mvar(net, from_bus, to_bus)

Return reactive power flow in MVAr for the oriented branch direction from_bus -> to_bus.

get_bus_vm_pu(net, bus_name)

Return solved voltage magnitude in p.u. for bus bus_name.

printTapControllerSummary(io, net)

Print a compact controller summary block for all configured tap controllers.

addUpfcControl!(net; fromBus, toBus, shunt_bus, target_bus, target_vm_pu,
                p_target_mw, v_inj_max_pu, s_max_mva | i_max_ka, ...)
    -> (name, series, shunt)

Register a UPFC in the STATIONARY QUADRATURE model: an SSSC series converter on the line branch fromBus to toBus (steering the branch active power to p_target_mw, limited by the injectable series voltage v_inj_max_pu) plus a STATCOM shunt converter at shunt_bus (holding the voltage at target_bus to target_vm_pu, limited by the converter rating s_max_mva or i_max_ka), paired under one composite name.

Model and its honest limitation

A real UPFC couples its two converters through the DC-link active-power balance. In the stationary model the series converter injects its voltage in quadrature with the line current, so it exchanges (approximately) no active power with the line, the DC link carries about zero, and the coupling degenerates: what remains is exactly the SSSC plus STATCOM pair this function registers. The composite therefore has NO series active-power injection: the phase-shifter degree of freedom a real UPFC feeds through its DC link is out of scope, and independent P and Q steering of the line via an injected voltage of arbitrary phase stays unavailable. For stationary P steering beyond the quadrature reach, the tap/phase-shift path on the same corridor remains the answer. Theory in FACTS Devices.

Arguments

• net::Net: the network.
• fromBus::String, toBus::String: terminals of the controlled line branch in the stored orientation (also the measurement direction of the flow).
• shunt_bus::String: bus carrying the shunt converter's machine; must be one of fromBus/toBus (a UPFC sits at one end of its own corridor).
• target_bus::String: the regulated (remote, PQ) bus of the shunt side.
• target_vm_pu::Float64: voltage target at target_bus in p.u.
• p_target_mw::Float64: series-side active-power target in MW, fromBus to toBus direction.
• v_inj_max_pu::Float64: maximum injectable series voltage in p.u. (the SSSC limit, must be positive).
• s_max_mva, i_max_ka: the shunt converter rating; exactly one of the two, positive (the STATCOM limit, see addMachineVoltageControl!).
• deadband_vm_pu = 1e-3, deadband_p_mw = 0.5: per-side convergence bands.
• prosumer_index: picks the machine when several generators sit at shunt_bus.
• name: composite name, default UPFC_<fromBus>_<toBus>; the two controllers are named <name>_series and <name>_shunt.
• max_outer_iters::Int = 20, enabled::Bool = true: forwarded to both sides.

Behavior

Registration is all-or-nothing: composite-level validation runs before anything is registered, and if the shunt-side registration fails after the series side succeeded, the series controller is removed again and the error rethrown. The two controllers keep their own result rows (one per actuator, at_limit per converter side) with the device strings "UPFC series (VSC pair, stationary quadrature model)" and "UPFC shunt (VSC pair, stationary quadrature model)".

Returns (name = <composite>, series = <SeriesReactanceControl>, shunt = <MachineVoltageControl>).

clearUpfcFullControllers!(net)

Remove all full-UPFC controllers (model = :full) from net, restoring each controlled branch to its physical base impedance (#329) so the cleared net carries the equipment model rather than the compensated operating point (whose resistance part can be negative). Other controllers stay. Returns net.

printUpfcFullControllerSummary(io::IO, net::Net)
printUpfcFullControllerSummary(net::Net)

Engineering-style summary of the registered full UPFC controllers (#326), one block per device: the controlled line and its P/Q targets versus achieved, the series injected voltage (magnitude and angle), the series/shunt active powers with the DC-link residual, the shunt reactive setpoint, and the honest limit flags. Prints nothing when no full UPFC is registered; the classical result's "Transformer controls: none" line stays the deterministic parser anchor.

_hvdc_pair_controllers(net) -> Vector{HvdcPairControl}

Collect the HVDC pair controllers stored on net (shared registry net.machineControls, hasproperty-guarded like the other collectors).

_machine_controllers(net) -> Vector{MachineVoltageControl}

Collect the machine voltage controllers stored on net. Guarded with hasproperty because collect_outer_controllers accepts net::Any.

SeriesReactanceControl <: AbstractOuterController

TCSC-like series compensation on a line branch. The actuator is the branch series reactance x_pu within [x_min_pu, x_max_pu]; the controlled quantity is the active power carried by that same branch, measured in the configured fromBus to toBus direction (the tap controller's achieved_p_mw convention). In range the controller holds p_target_mw via secant iteration on the scalar map x to P; at a range end the branch behaves as a fixed compensated line and the controller reports honest at_limit. Negative reactance (net capacitive branch) is admissible, the impedance-magnitude guard _SERIES_CTRL_EPS_Z protects the singular neighborhood of x = -0 (design choice, see the theory page).

Two limit modes (limit_mode):

• :reactance_range (default): fixed [x_min_pu, x_max_pu], the TCSC reactance window.
• :injected_voltage: SSSC behavior (issue #297 Draft F). The device injects a series voltage in quadrature with the line current; stationary it acts as a reactance deviation from the natural line reactance x_base_pu, bounded by the injectable voltage magnitude: |x - x_base_pu| <= v_inj_max_pu / |I|. The bound is re-evaluated from the solved branch current before every outer step, so at high loading the usable reactance window SHRINKS (less compensation available exactly when the current is large) — the defining contrast to the TCSC's fixed window. An at-limit SSSC keeps adjusting while its current-dependent bound still moves and only parks at_limit once the bound has settled.

_series_reactance_controllers(net) -> Vector{SeriesReactanceControl}

Collect the series-reactance controllers stored on net. They share the generic outer-controller registry (net.machineControls) with the machine and shunt controllers; guarded with hasproperty because collect_outer_controllers accepts net::Any.

_shunt_controllers(net) -> Vector{ShuntVoltageControl}

Collect the shunt voltage controllers stored on net. They share the generic outer-controller registry (net.machineControls) with the machine controllers; guarded with hasproperty because collect_outer_controllers accepts net::Any.

_find_trafo_branch(net, name)

Internal helper to resolve a transformer branch by component name, component id, or branch index represented as string.

_phase_probe_direction(...)

Internal helper: determines the empirical sign of ΔP_from_to for a positive phase increment (+phase_step_deg) on the controlled transformer and branch. Returns -1, 0, or +1.

_ratio_probe_direction(...)

Internal helper: determines the empirical sign of ΔVm_target for a positive ratio increment (+tap_step) on the controlled transformer and target bus. Returns -1, 0, or +1.

_tap_controllers(net)

Collect all tap controllers configured in net from transformer windings.

run_tap_controllers_outer!(net; ...)

Removed from the public control API; always throws. Use run_control!(net; pf_config = ..., control_config = ...) instead.

UpfcFullControl <: AbstractOuterController

Full unified power flow controller (issue #326), the DC-link-coupled model.

The series converter injects a voltage V_se of ARBITRARY phase into the line fromBus->toBus, steering the from-end line flow to (p_target_mw, q_target_mvar) INDEPENDENTLY (the phase-shifter degree of freedom the #325 quadrature composite lacks). The active power the series converter exchanges with the line, P_se = Re(V_se·conj(I_s)), flows through the DC link and is supplied by the shunt converter (P_sh = -P_se) at shunt_bus; the shunt also delivers the reactive setpoint q_shunt_mvar, clamped to the current-based rating whose reactive headroom is coupled to P_sh by Q_max = sqrt((V_shunt·s_max)^2 - P_sh^2).

series_phase = :quadrature constrains V_se ⟂ I_s (P_se = 0), reducing the series converter to the SSSC (the regression bridge to #325).

Runtime fields are owned by run_control!; construct via addUpfcControl! with model = :full.

_upfc_full_controllers(net) -> Vector{UpfcFullControl}

Collect the full-UPFC controllers stored on net (shared registry net.machineControls).

addUpfcFullControl!(net; ...) -> UpfcFullControl

Internal constructor for the full UPFC. Users call addUpfcControl! with model = :full, which validates the composite preconditions and forwards here. Registers one UpfcFullControl on net.machineControls and returns it. The shunt converter is the existing generator at shunt_bus (resolved and required, as in the #325 composite); no injection carrier is created (the series source is realised as an equivalent branch impedance).