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. 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).
control_limits	MinMax	—	1 / 1 / 1 / rad / 1 / rad / 1 / 1 / 1 / rad / 1 / rad (by control_objective)	Control band (PSS/E RMA/RMI), per control_objective. Units: per control_objective — UNDEFINED: 1, VOLTAGE_DISABLED: 1, REACTIVE_POWER_FLOW_DISABLED: 1, ACTIVE_POWER_FLOW_DISABLED: rad, CONTROL_OF_DC_LINE_DISABLED: 1, ASYMMETRIC_ACTIVE_POWER_FLOW_DISABLED: rad, FIXED: 1, VOLTAGE: 1, REACTIVE_POWER_FLOW: 1, ACTIVE_POWER_FLOW: rad, CONTROL_OF_DC_LINE: 1, ASYMMETRIC_ACTIVE_POWER_FLOW: rad .
controlled_quantity_limits	MinMax	—	pu / pu / MVAr / MW / MW / MW / pu / pu / MVAr / MW / MW / MW (by control_objective)	Controlled-quantity band (PSS/E VMA/VMI), per control_objective. Units: per control_objective — UNDEFINED: pu, VOLTAGE_DISABLED: pu, REACTIVE_POWER_FLOW_DISABLED: MVAr, ACTIVE_POWER_FLOW_DISABLED: MW, CONTROL_OF_DC_LINE_DISABLED: MW, ASYMMETRIC_ACTIVE_POWER_FLOW_DISABLED: MW, FIXED: pu, VOLTAGE: pu, REACTIVE_POWER_FLOW: MVAr, ACTIVE_POWER_FLOW: MW, CONTROL_OF_DC_LINE: MW, ASYMMETRIC_ACTIVE_POWER_FLOW: MW .
number_of_tap_positions	integer	—	—	Number of tap positions (PSS/E NTP).
rating	number	—	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 .
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.