TransformerCircuit

Package: PowerOperationsOpenAPIModels · Source: Operations/Branch/TransformerCircuit.json

The data defining one modeled arc of a transformer.

A TwoWindingTransformer has one circuit; a ThreeWindingTransformer has three, each connecting a terminal bus to the star bus. Circuit available is the single source of truth for availability; the owning transformer derives its availability from its circuits. r/x are the circuit impedance (for a two-winding transformer, the series impedance; for a three-winding transformer, the star-leg equivalent), in pu (device base) on base_power referenced to base_voltage_primary. Tap-changer / phase-shifter control is described by the flat control fields: control_objective = UNDEFINED means the circuit has no control block. Each objective selects exactly one actuator band (tap_ratio_limits or phase_angle_limits) and one target band (controlled_voltage_limits, controlled_reactive_power_flow_limits or controlled_active_power_flow_limits); every other band is null. For a TwoWindingTransformer, the single circuit’s base_power is the transformer’s device base.

Properties

Property	Type	Required	Unit	Description
id	integer	yes	—	Unique integer identifier for this component.
available	boolean	yes	—	Indicator of whether this circuit is connected and online.
arc	integer	yes	—	An Arc defining this circuit from a terminal bus to the transformer’s other terminal or star bus.
tap	number	—	1	Normalized tap changer position for voltage control, varying between 0 and 2, with 1 centered at the nominal voltage. Units: 1.
alpha	number	—	rad	Initial condition of phase shift across this circuit. Units: rad.
parameter_units	string (ImpedanceUnitBasis)	—	—	Unit basis for this circuit’s impedance fields (r, x).
r	number	—	ohm / pu (by parameter_units)	Circuit resistance. Units: per parameter_units — NATURAL_UNITS: ohm, COMPONENT_BASE: pu .
x	number	—	ohm / pu (by parameter_units)	Circuit reactance. Units: per parameter_units — NATURAL_UNITS: ohm, COMPONENT_BASE: pu .
control_objective	string (TransformerControlObjective)	—	—	Tap-changer / phase-shifter control objective (PSS/E COD). UNDEFINED means this circuit has no control block.
regulated_bus_number	integer	—	—	Controlled bus number (PSS/E CONT; sign = regulation side).
tap_ratio_limits	MinMax	—	1	Tap-ratio actuator band (PSS/E RMA/RMI) when control_objective moves the tap; null otherwise. Under the tap-moving objectives it may be omitted and then defaults to 0.9 to 1.1, PSS/E’s own RMI/RMA defaults, which is why it is the one band the conditional blocks do not require. Units: 1.
phase_angle_limits	MinMax	—	rad	Phase-shift actuator band (PSS/E RMA/RMI when the objective moves the angle). null unless control_objective selects it. Units: rad.
controlled_voltage_limits	MinMax	—	pu	Regulated-voltage target band (PSS/E VMA/VMI), per unit of the regulated bus’s base voltage. null unless control_objective selects it. Units: pu.
controlled_reactive_power_flow_limits	MinMax	—	MVAr / pu (by power_units)	Regulated reactive-power-flow target band (PSS/E VMA/VMI). null unless control_objective selects it. Units: per power_units — NATURAL_UNITS: MVAr, COMPONENT_BASE: pu .
controlled_active_power_flow_limits	MinMax	—	MW / pu (by power_units)	Regulated active-power-flow target band (PSS/E VMA/VMI). null unless control_objective selects it. Units: per power_units — NATURAL_UNITS: MW, COMPONENT_BASE: pu .
number_of_tap_positions	integer	—	—	Number of tap positions (PSS/E NTP).
rating	number	yes	MVA / pu (by power_units)	Thermal rating. Units: per power_units — NATURAL_UNITS: MVA, COMPONENT_BASE: pu .
rating_b	number	—	MVA / pu (by power_units)	Second current rating. Units: per power_units — NATURAL_UNITS: MVA, COMPONENT_BASE: pu .
rating_c	number	—	MVA / pu (by power_units)	Third current rating. Units: per power_units — NATURAL_UNITS: MVA, COMPONENT_BASE: pu .
operational_flow_limit	OperationalFlowLimit	—	MW / pu (by power_units)	Operator-set minimum and maximum flow in each direction, applied in addition to rating. Absent means no operational limit. Units: per power_units — NATURAL_UNITS: MW, COMPONENT_BASE: pu .
active_power_flow	number	—	MW / pu (by power_units)	Initial condition of active power flow through this circuit. Units: per power_units — NATURAL_UNITS: MW, COMPONENT_BASE: pu .
reactive_power_flow	number	—	MVAr / pu (by power_units)	Initial condition of reactive power flow through this circuit. Units: per power_units — NATURAL_UNITS: MVAr, COMPONENT_BASE: pu .
base_power	number	—	MVA	Base power for per unitization of this circuit. Units: MVA.
power_units	string (UnitSystem)	yes	—	Unit basis for this component’s power-family fields (active/reactive/apparent power, ratings, limits, ramp rates). COMPONENT_BASE: per unit on this component’s own base_power. NATURAL_UNITS: the field’s physical unit.
base_voltage_primary	number	—	kV	Primary (from) terminal-side base voltage; the reference voltage for this circuit’s per-unit impedance. Units: kV.
base_voltage_secondary	number	—	kV	Secondary (to) terminal-side base voltage. For a three-winding transformer this defaults to the primary base voltage at parse time. Units: kV.