Transformer (3-phase, 2-winding)

Three-phase two-winding (HV / LV) mutually-coupled transformer. Leakage plus a magnetizing branch that is linear by default and can take an optional core-saturation curve (exponential, SE datasheet points, or a two-slope air-core knee for inrush studies); no hysteresis or residual flux. Fixed 3-leg core (shared magnetic circuit blocks zero-sequence flux). Vector-clock phase shift on HV→LV. Optional tap changer (first-order lag toward a tap_cmd named input) on a user-selectable host winding. Carries a load-flow PSSE 2-winding record; the column values are derived from the EMT parameters via the schema's computations block (no separate load-flow tab). Same parameter shape as the 3-winding sibling (transformer_3w_3ph) with the TV side dropped.

Category: Transformers

Ports

Name	Direction	Value type	Notes
HV	electrical_3ph	double
LV	electrical_3ph	double
HV_n	electrical	double	Visible when hv_connection == 'YN' && hv_neutral == 'exposed'
LV_n	electrical	double	Visible when lv_connection == 'yn' && lv_neutral == 'exposed'

Parameters

Config

Name	Label	Type	Default	Units	Description
s_rated	S rated	double	100	MVA (VA, kVA, MVA)	Three-phase apparent-power rating. The unit selector beside this field lets you enter the value in VA, kVA, or MVA — at netlist-export time the schema's `computations` block converts the selection to canonical VA, which is what the EMT model and load-flow extractor read. Sets the transformer's per-unit base (Z_base_pu = V_LL² / S_rated) and the load-flow R / X system-base conversion (R_pu_sys = R_pu_tx · 100 MVA / S_rated_canonical).
f_rated_hz	f rated	double	60	—	Rated electrical frequency, in hertz. Drives every per-unit-to-henries conversion (X_pu → L = X_pu · Z_base / (2πf)) on the EMT side; the load-flow extractor uses the system base frequency (60 Hz) for its own conversions, so f_rated_hz is EMT-only.
v_hv_rated_v	V HV rated (LL)	double	230000	V (V, kV)	HV-winding rated line-to-line RMS voltage. The unit selector beside this field lets you enter the value in V or kV — at netlist-export time the schema's `computations` block converts the selection to canonical volts, which is what the EMT model and load-flow extractor read. Drives the HV-side per-unit base and the HV:LV turns ratio (per-winding rated voltage: V_LL/√3 for Y, V_LL for Δ). Surfaces as load-flow NOMV1 (converted to kV at extract time).
v_lv_rated_v	V LV rated (LL)	double	115000	V (V, kV)	LV-winding rated line-to-line RMS voltage. Pick V or kV in the unit selector; the computations block converts to canonical volts at netlist export. Sets the LV-side per-unit base. Surfaces as load-flow NOMV2.
hv_connection	HV connection	enum (Y (floating N) / YN (wye + neutral) / Δ delta)	YN	—	HV winding connection. `Y` = wye with a floating (isolated) neutral — no zero-sequence path. `YN` = wye with an accessible neutral; the `HV neutral` selector below decides whether it is grounded internally or brought out to the HV_n port. `D` = delta.
hv_neutral	HV neutral	enum (Neutral exposed (HV_n port) / Grounded internally)	exposed	—	How the HV wye star point is handled (only applies to the YN connection). `Exposed`: the neutral is brought out to the HV_n port wired directly to the star point — ground it externally with a `gnd` cell or leave it floating. `Grounded`: the neutral is tied to ground inside the transformer (no HV_n port); pick solid or Rn+jXn impedance grounding on the Grounding tab.
lv_connection	LV connection	enum (y (floating n) / yn (wye + neutral) / d (delta))	yn	—	LV winding connection. `y` = wye with a floating (isolated) neutral. `yn` = wye with an accessible neutral; the `LV neutral` selector below decides whether it is grounded internally or brought out to the LV_n port. `d` = delta.
lv_neutral	LV neutral	enum (Neutral exposed (LV_n port) / Grounded internally)	exposed	—	How the LV wye star point is handled (only applies to the yn connection). `Exposed`: the neutral is brought out to the LV_n port wired directly to the star point. `Grounded`: the neutral is tied to ground inside the transformer (no LV_n port); pick solid or Rn+jXn impedance grounding on the Grounding tab.
hv_lv_vector_clock	HV→LV vector clock	enum (0 (in phase) / 1 (−30°) / 5 (−150°) / 6 (180°) / 7 (+150°) / 11 (+30°))	0	—	Phase shift of LV relative to HV, in 30° clock units (0 = in-phase, 1 = LV lags HV 30°, 11 = LV leads 30°, 6 = 180°). Maps directly to PSSE ANG2 = −30° × clock.
r_hv_lv_pu	R HV-LV (pu)	double	0.005	—	HV-LV pair series resistance, per-unit on the transformer's own base (S_rated, V_HV-rated). Measured by short-circuiting LV and energising HV at rated current. Typical 0.002 – 0.01. Split evenly between the HV and LV winding leakages (R_HV_pu = R_LV_pu = R_HV-LV_pu / 2) when stamped on the EMT side.
x_hv_lv_pu	X HV-LV (pu)	double	0.1	—	HV-LV pair leakage reactance, per-unit on the transformer's own base. Typical 0.08 – 0.12. Split evenly between the two windings (X_HV_pu = X_LV_pu = X_HV-LV_pu / 2). Surfaces as PSSE column R / X (after a 100 MVA / S_rated rebase).
i_mag_hv_pct	I_mag HV (%)	double	1	—	No-load magnetizing current on the HV side at rated voltage, in percent of HV rated current (= 100 × I_mag / I_HV_rated). Sets the linear magnetizing inductance referred to the HV winding (the model uses HV as the magnetisation reference).
i_mag_lv_pct	I_mag LV (%)	double	1	—	No-load magnetizing current on the LV side at rated voltage, in percent of LV rated current. Informational in v1 — the LV magnetisation contribution is implied by the per-pair leakages and the HV-side L_m. Round to the same value as i_mag_hv_pct if you have no separate measurement.
no_load_loss_pu	No-load loss (pu)	double	0	—	No-load (iron) loss, per-unit on S_rated. Lumps hysteresis + eddy at f_rated. The `No-load loss topology` parameter below picks where the resulting conductance is stamped. Set to 0 to disable.
no_load_loss_topology	No-load loss topology	enum (Across HV winding / Line-to-ground per phase)	winding	—	Where the no-load-loss conductance is stamped. `winding`: in parallel with the HV magnetising branch (across the per-leg HV winding). `line_ground`: as a shunt from each HV line terminal to ground (3-phase Y of conductors, common for surge / lightning models).
saturation	Magnetic saturation	enum (Off (linear) / On)	0	—	Enable the exponential open-circuit core-saturation curve acting on the per-leg magnetizing inductance L_m (the same shared saturation model used by the synchronous machine). When on, the magnetizing branch draws extra current above the knee flux ψT1. Define the curve directly (Asat/Bsat) or via the SE(1.0)/SE(1.2) datasheet points on the Saturation tab. Off = linear core (the v1 default).
enable_tap_changer	Tap changer	enum (Off / On)	0	—	Enable the named-input-driven tap. When 0, the host winding's turns ratio is the rated value and `tap_cmd` is ignored. When 1, the schema surfaces the Tap Changer tab and resolves the `tap_cmd` named input — the host winding's effective ratio tracks `tap_cmd` through a first-order lag with time constant `tap_time_constant_s` (initial value `tap_init_pu`).
measure_hv_current	Measure HV current	enum (Off / Line current / Winding current)	off	—	Emit HV per-phase currents. `off`: do not emit. `line`: per-phase line current (current into the HV port — coincides with winding current for Y connection). `winding`: per-phase winding current (line current rotated into the Δ winding for D connection; same as line for Y).
measure_lv_current	Measure LV current	enum (Off / Line current / Winding current)	off	—	Emit LV per-phase currents. Same options as `Measure HV current`.
measure_mag_current	Measure mag current	enum (Off / On)	0	—	Emit per-leg magnetizing current i_mag_a/b/c (A) through the linear magnetising branch.
measure_flux	Measure core flux	enum (Off / On)	0	—	Emit per-leg magnetizing flux linkage psi_a/b/c in per-unit of the peak HV-winding flux base (1.0 pu = the flux a rated sinusoidal winding voltage produces at f_rated). This is the state that drives saturation, so it is the signal that explains a magnetizing-current waveform: compare it against the saturation threshold to see when the core goes over. Available whether or not saturation is enabled.

Tap Changer

Name	Label	Type	Default	Units	Description
tap_host_winding	Host winding	enum (HV / LV)	hv	—	Which winding's turns ratio the tap modulates. Only that winding's WINDV column in the load-flow record deviates from 1.0; the other stays at nominal.
tap_time_constant_s	Time constant (s)	double	1	—	First-order time constant (seconds) used to ramp the host winding's effective ratio toward `tap_cmd` after each step. The EMT model applies the lag exp(-h/τ) per step.
tap_init_pu	Initial ratio (pu)	double	1	—	Initial value of the host winding's effective ratio at t = 0, in pu of rated voltage. 1.0 = nominal turns. Also seeds the load-flow WINDV column on the host winding.
tap_cmd_signal_name	Tap signal name	string	tap	—	Name of the published signal that drives the tap command (in pu of nominal). The named input is always 1-step delayed via MemoryArena.prev — no algebraic-loop risk even when the source transitively depends on this transformer's voltage. Leave empty to disable the binding (the lag still runs from the initial value).

Grounding

Name	Label	Type	Default	Units	Description
hv_grounding	HV neutral grounding	enum (Solidly grounded / Grounded via Rn + jXn)	solid	—	Grounding of the HV wye neutral when `HV neutral` = Grounded. `Solid`: the star point is bonded directly to ground (no neutral impedance). `Impedance`: grounded through a neutral resistor / reactor Rn + jXn — the terminal zero-sequence impedance gains 3·(Rn + jXn).
hv_rn_pu	HV Rn (pu)	double	0	—	HV neutral-grounding resistance, per-unit on the HV-winding base (Z_base_HV = V_HV_winding² / (S_rated / 3)). Adds 3·Rn to the terminal zero-sequence impedance.
hv_xn_pu	HV Xn (pu)	double	0	—	HV neutral-grounding reactance, per-unit on the HV-winding base. Adds 3·Xn to the terminal zero-sequence impedance.
lv_grounding	LV neutral grounding	enum (Solidly grounded / Grounded via Rn + jXn)	solid	—	Grounding of the LV wye neutral when `LV neutral` = Grounded. `Solid`: bonded directly to ground. `Impedance`: grounded through Rn + jXn referred to the LV-winding base.
lv_rn_pu	LV Rn (pu)	double	0	—	LV neutral-grounding resistance, per-unit on the LV-winding base (Z_base_LV = V_LV_winding² / (S_rated / 3)).
lv_xn_pu	LV Xn (pu)	double	0	—	LV neutral-grounding reactance, per-unit on the LV-winding base.

Saturation

Name	Label	Type	Default	Units	Description
sat_definition	Definition	enum (Exponential (Asat/Bsat) / SE points (SE1.0/SE1.2) / Two-slope (air-core))	0	—	How the core-saturation curve is specified. `Exponential` enters the coefficients Asat / Bsat directly. `SE points` enters the two datasheet saturation factors SE(1.0) and SE(1.2); the exponential is fit through them — both end up as the same Ssat(ψ) = Asat·exp(Bsat·(ψ − ψT1)) curve internally. `Two-slope (air-core)` instead uses the piecewise-linear λ–i characteristic: unsaturated L_m below the knee ψT1, air-core L_air above it. Pick the exponential form for steady-state over-excitation near 1.0–1.2 pu (that is the range it is fitted over); pick two-slope for energization / inrush studies, where the flux swings to nearly 2 pu and the answer is governed by how close the saturated inductance gets to air-core — a regime the exponential does not extrapolate into sensibly.
Asat	Asat	double	0.03	—	Exponential saturation coefficient A: the saturation function is Ssat(ψ) = Asat·exp(Bsat·(ψ − ψT1)) for per-unit magnetizing flux ψ above the knee ψT1, else 0. The saturated magnetizing inductance is L_m = L_m,unsat / (1 + Ssat). 0 disables saturation.
Bsat	Bsat	double	7	—	Exponential saturation coefficient B (1/pu-flux): controls how sharply saturation increases with magnetizing flux above ψT1.
SE10	SE(1.0)	double	0.1	—	Open-circuit saturation factor at 1.0 pu flux: the fractional extra magnetizing current (vs. the air-gap line) needed to reach 1.0 pu. Typical 0.05–0.15.
SE12	SE(1.2)	double	0.3	—	Open-circuit saturation factor at 1.2 pu flux. Must exceed SE(1.0). Typical 0.2–0.5. With SE(1.0) it fixes Bsat = ln(SE12/SE10)/0.2 and Asat = SE10/exp(Bsat·(1.0 − ψT1)).
l_air_pu	L air-core (pu)	double	0.2	—	Saturated (air-core) inductance in per-unit on the transformer base — the slope of the λ–i characteristic once the core is over the knee. Physically the winding's inductance with the iron gone, so it is set by winding geometry and lands near the leakage reactance: typical values are 1–4 × x_hv_lv_pu, i.e. roughly 0.1–0.5 pu. This single number governs the peak inrush current, because above the knee the energization loop is just the source impedance plus leakage plus L_air.
psi_knee_pu	ψ knee (pu)	double	1.2	—	Flux linkage (pu) at which the λ–i characteristic breaks from L_m to the air-core slope. Unlike the exponential form's ψT1 — a curve-fitting threshold that can sit below rated flux because the exponential is still negligible there — this is a hard break, so it MUST be above the transformer's normal operating flux or the unit saturates every cycle in ordinary service. Real cores knee over at 1.1–1.25 pu; values below 1.0 are almost certainly a mistake.
psiT1	ψT1 (pu)	double	0.8	—	Magnetizing-flux threshold (pu) below which the exponential curve is clamped to Ssat = 0. This is the fitting origin of the exponential, not a physical knee — the standard 0.8 sits below rated flux and is harmless there because Ssat(0.8) = 0 and grows smoothly.

Monitoring

Name	Label	Type	Default	Units	Description
i_hv_name_a	HV name A	string	I_HVa	—	Signal name for the HV-side Phase A current. Blank skips this phase.
i_hv_name_b	HV name B	string	I_HVb	—	Signal name for the HV-side Phase B current.
i_hv_name_c	HV name C	string	I_HVc	—	Signal name for the HV-side Phase C current.
i_lv_name_a	LV name A	string	I_LVa	—	Signal name for the LV-side Phase A current.
i_lv_name_b	LV name B	string	I_LVb	—	Signal name for the LV-side Phase B current.
i_lv_name_c	LV name C	string	I_LVc	—	Signal name for the LV-side Phase C current.
i_mag_name_a	Mag name A	string	ImagA	—	Signal name for the Phase A magnetising current.
i_mag_name_b	Mag name B	string	ImagB	—	Signal name for the Phase B magnetising current.
i_mag_name_c	Mag name C	string	ImagC	—	Signal name for the Phase C magnetising current.
flux_name_a	Flux name A	string	PsiA	—	Signal name for the Phase A core flux linkage (pu). Blank skips this phase.
flux_name_b	Flux name B	string	PsiB	—	Signal name for the Phase B core flux linkage (pu).
flux_name_c	Flux name C	string	PsiC	—	Signal name for the Phase C core flux linkage (pu).

Observables

Signal	Type	Default name	Enable	Description
i_HV_a	signal	from i_hv_name_a	measure_hv_current	HV-side Phase A current (A). `line` mode reports the current into the HV_a port; `winding` mode reports the current through the HV winding (rotated to the Δ winding loop for D connection).
i_HV_b	signal	from i_hv_name_b	measure_hv_current
i_HV_c	signal	from i_hv_name_c	measure_hv_current
i_LV_a	signal	from i_lv_name_a	measure_lv_current
i_LV_b	signal	from i_lv_name_b	measure_lv_current
i_LV_c	signal	from i_lv_name_c	measure_lv_current
i_mag_a	signal	from i_mag_name_a	measure_mag_current
i_mag_b	signal	from i_mag_name_b	measure_mag_current
i_mag_c	signal	from i_mag_name_c	measure_mag_current
psi_mag_a	signal	from flux_name_a	measure_flux	Phase A core (magnetizing) flux linkage, in pu of the peak HV-winding flux base. 1.0 pu is the peak flux a rated sinusoidal winding voltage sustains at f_rated, so the knee ψT1 and this signal are directly comparable.
psi_mag_b	signal	from flux_name_b	measure_flux
psi_mag_c	signal	from flux_name_c	measure_flux

Used in samples

• Transformer Energization
• Transformer Sc Test