Appearance
Transformer (3-phase, 3-winding)
Three-phase three-winding (HV / LV / TV) 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 shifts on HV→LV and HV→TV are independent. Optional tap changer (first-order lag toward a tap_cmd named input) on a user-selectable host winding. Carries a load-flow 5-line PSSE 3-winding record; the column values are derived from the EMT parameters via the schema's computations block (no separate load-flow tab).
Category: Transformers
Ports
| Name | Direction | Value type | Notes |
|---|---|---|---|
HV | electrical_3ph | double | |
LV | electrical_3ph | double | |
TV | 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' |
TV_n | electrical | double | Visible when tv_connection == 'yn' && tv_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 / HV:TV turns ratios (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. |
v_tv_rated_v | V TV rated (LL) | double | 13800 | V (V, kV) | Tertiary-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 TV-side per-unit base. Surfaces as load-flow NOMV3. |
hv_connection | HV connection | enum (Y (floating N) / YN (wye + neutral) / Δ delta) | YN | — | HV winding connection. `Y` = wye with a floating (isolated) neutral. `YN` = wye with an accessible neutral; the `HV neutral` selector decides grounded-internally vs brought-out to HV_n. `D` = delta. |
hv_neutral | HV neutral | enum (Neutral exposed (HV_n port) / Grounded internally) | exposed | — | How the HV wye star point is handled (only for the YN connection). `Exposed`: brought out to the HV_n port wired to the star point. `Grounded`: tied to ground inside the transformer (no HV_n port); pick solid or Rn+jXn 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 neutral. `yn` = wye with an accessible neutral; the `LV neutral` selector decides grounded-internally vs brought-out to LV_n. `d` = delta. |
lv_neutral | LV neutral | enum (Neutral exposed (LV_n port) / Grounded internally) | exposed | — | How the LV wye star point is handled (only for the yn connection). `Exposed`: brought out to the LV_n port wired to the star point. `Grounded`: tied to ground inside the transformer (no LV_n port); pick solid or Rn+jXn grounding on the Grounding tab. |
tv_connection | TV connection | enum (y (floating n) / yn (wye + neutral) / d (delta)) | d | — | Tertiary winding connection. `y` = wye with a floating neutral. `yn` = wye with an accessible neutral; the `TV neutral` selector decides grounded-internally vs brought-out to TV_n. `d` = delta — the customary choice for a stabilising tertiary (provides a path for zero-sequence circulating current on Y-Y banks). |
tv_neutral | TV neutral | enum (Neutral exposed (TV_n port) / Grounded internally) | exposed | — | How the TV wye star point is handled (only for the yn connection). `Exposed`: brought out to the TV_n port wired to the star point. `Grounded`: tied to ground inside the transformer (no TV_n port); pick solid or Rn+jXn 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. |
hv_tv_vector_clock | HV→TV vector clock | enum (0 (in phase) / 1 (−30°) / 5 (−150°) / 6 (180°) / 7 (+150°) / 11 (+30°)) | 1 | — | Phase shift of TV relative to HV, in 30° clock units. Default `1` matches the typical YNd1 stabilising-tertiary group. Maps to PSSE ANG3 = −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 with TV open. Typical 0.002 – 0.01. |
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. Surfaces as PSSE column R1-2 / X1-2 (after a 100 MVA/S_rated rebase). |
r_hv_tv_pu | R HV-TV (pu) | double | 0.005 | — | HV-TV pair series resistance, per-unit on the transformer's own base. Measured by short-circuiting TV and energising HV with LV open. |
x_hv_tv_pu | X HV-TV (pu) | double | 0.1 | — | HV-TV pair leakage reactance, per-unit on the transformer's own base. Maps to PSSE R3-1 / X3-1. |
r_lv_tv_pu | R LV-TV (pu) | double | 0.005 | — | LV-TV pair series resistance, per-unit on the transformer's own base. |
x_lv_tv_pu | X LV-TV (pu) | double | 0.1 | — | LV-TV pair leakage reactance, per-unit on the transformer's own base. Maps to PSSE R2-3 / X2-3. |
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. |
i_mag_tv_pct | I_mag TV (%) | double | 1 | — | No-load magnetizing current on the TV side at rated voltage, in percent of TV rated current. Informational in v1, same as i_mag_lv_pct. |
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_tv_current | Measure TV current | enum (Off / Line current / Winding current) | off | — | Emit TV 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 / TV) | 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 two stay 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`: star point bonded directly to ground. `Impedance`: grounded through 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)). |
hv_xn_pu | HV Xn (pu) | double | 0 | — | HV neutral-grounding reactance, per-unit on the HV-winding base. |
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. |
lv_xn_pu | LV Xn (pu) | double | 0 | — | LV neutral-grounding reactance, per-unit on the LV-winding base. |
tv_grounding | TV neutral grounding | enum (Solidly grounded / Grounded via Rn + jXn) | solid | — | Grounding of the TV wye neutral when `TV neutral` = Grounded. `Solid`: bonded directly to ground. `Impedance`: grounded through Rn + jXn referred to the TV-winding base. |
tv_rn_pu | TV Rn (pu) | double | 0 | — | TV neutral-grounding resistance, per-unit on the TV-winding base. |
tv_xn_pu | TV Xn (pu) | double | 0 | — | TV neutral-grounding reactance, per-unit on the TV-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: 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_tv_name_a | TV name A | string | I_TVa | — | Signal name for the TV-side Phase A current. |
i_tv_name_b | TV name B | string | I_TVb | — | Signal name for the TV-side Phase B current. |
i_tv_name_c | TV name C | string | I_TVc | — | Signal name for the TV-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_TV_a | signal | from i_tv_name_a | measure_tv_current | |
i_TV_b | signal | from i_tv_name_b | measure_tv_current | |
i_TV_c | signal | from i_tv_name_c | measure_tv_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 |