Transformer models

This page is the normative reference for how BMOPFTools models transformers: the supported subtypes, the conventions every subtype follows, the exported primitive admittance (Yprim), and the explicit list of approximations. The overriding design goal is consistency with OpenDSS: at a given setpoint the OPF constraints and the exported Yprim describe the same device, and both are built to match OpenDSS's own Yprim term-by-term wherever OpenDSS is unambiguous.

The companion Transformer primitive admittance spec page carries the full symbolic matrix derivations; this page is the model-level contract. For the workflow that produces these fields — turning short-circuit/open-circuit test data into a validated model — see the transformer test-data tutorial.

Supported subtypes

A subtype string outside this set is not silently dropped — the OPF builder and the Yprim export both emit a warning that the device contributes no constraints / is omitted from the export.

Conventions

These hold across every subtype unless a row below says otherwise.

Magnetising-shunt placement

For the ordinary isolating subtypes below, OpenDSS places the no-load (core-loss + magnetising) branch across winding 2, referred to winding 2's coil voltage — not winding 1, and not phase-to-ground. This was verified empirically by differencing OpenDSS's Yprim with and without %noloadloss/%imag (the shunt follows winding 2 when the winding order is flipped). BMOPFTools matches this in both the OPF and the Yprim export:

For new exchange data, use no_load_shunt = {winding, g, b}: g and b are per coil, in siemens on the selected physical winding's coil voltage base, including that winding's tap. Normalization creates ordinary connected bus shunts and retains transformer ownership in _meta["explicit_transformer_core_shunts"]. The transformer primitive alone excludes these materialized bus shunts; include them when comparing the whole terminal model. Current PowerIO imports use this explicit representation.

For compatibility, existing g_no_load/b_no_load values retain their subtype meaning: single_phase, Yd and Dy store a total divided equally over coils; center_tap stores the entire value on winding 2 (first secondary half-winding); n_winding stores a per-coil value on winding 2. Thus copying legacy numbers between subtypes is not a conversion. To express a legacy bank with m coils explicitly, divide its total by m; for n_winding, retain the value. Both forms on one transformer are rejected. These rules resolve the package compatibility choice in #279 without silently changing old data. Schema descriptions now match these runtime meanings. The legacy from_dss recovery also accounts for multi-coil wye-bank coil voltage and winding-2 taps; PMD export uses winding 2's voltage base. For one L-N or L-L coil, the nominal voltage is the coil voltage; two- and three-coil wye banks use V_LL/√3. Neutral selection respects declared case/bus roles and the PMD numeric "4" convention. Zero excitation requires no tap-dependent voltage base, so empty or unequal coil-tap arrays do not cause the legacy zero-shunt recovery to fail.

Fixed taps and stored ohms

The ordinary subtype conventions are tested against independent OpenDSS primitives at taps 0.95, 1.0, and 1.06 with nonzero leakage and excitation, using both hand-authored dictionaries and imported DSS. The center-tap primary referral was corrected in #393; stored data continue to use nominal ohms. The same referral is used by its zero-arm and variable-ratio equations, with current coupling substituted to retain quadratic constraints. Fixed-tap tests do not certify control-law behavior or resolve unequal-kVA n-winding import (#356).

Primitive admittance export

transformer_yprim(xfmr, subtype) / export_yprim(net) return the SI Yprim block over the device's (bus, terminal) nodes. It includes the series leakage, the winding-2 magnetising shunt, and the rneut/xneut grounding branch. Two caveats for consumers:

• Regulators (single_phase_autotransformer, open_delta_regulator): the shared-bushing / shared-phase galvanic tie is an OPF topological constraint, not part of the device primitive (the exported block is the Yan et al. (2018) "unspecified neutral" matrix). The exported Yprim alone leaves the regulated side's return floating.
• Ideal transformers (Z = 0): no admittance form exists; the export returns a singular (shunt-only) block with a warning. The OPF still enforces the exact ratio.

OPF ↔ Yprim consistency

The OPF builders and the Yprim export are independent implementations. Their agreement at a given setpoint is a guarded invariant: the test suite reconstructs the element current I = Yₚ·V from a solved power flow and checks it node-by-node against the solved OPF winding-current variables, for single_phase, center_tap, wye_delta, and delta_wye, including off-nominal fixed taps. See Validating the OPF.

Approximations

Everything below is a deliberate, bounded approximation — listed here so nothing is hidden.

Nameplate rating (s_rating) as a loading cap

s_rating plays two roles, and they must not be conflated:

1. Per-unit impedance base (always). The short-circuit reactances are expressed on winding 1's kVA base — the OpenDSS convention (%XHL/%XHT/ %XLT are all on the winding-1 base, not the highest-powered winding). The OPF matches this: the leakage is per-unitised by z_base(winding-1 bus) and s_rating. This base never changes, so OpenDSS round-trips stay exact.
2. Apparent-power loading cap (always enforced). The nameplate is enforced as a per-winding coil apparent-power limit P² + Q² ≤ (s_rating / n_\text{ph})² (the coil voltage is phase-to-neutral for a wye winding, line-to-line for a delta winding, so it is never ≈ 0 — no neutral degeneracy), alongside the per-winding i_max_from/i_max_to current cones when present. Because s_rating is a required field, every transformer is power-limited; to solve without the limit (e.g. a determined power flow compared against limit-free OpenDSS), remove s_rating from the network dict before calling the OPF. Keep in mind the primary coil carries load plus copper losses, so at exactly-rated delivery the from-side cap binds slightly below the secondary nameplate throughput (by the loss margin). See current vs. apparent-power limits.

For n_winding transformers, add an optional per-winding s_max (the winding's own kVA) inside each winding entry; it is enforced when present. The per-unit impedance base still keys off winding 1's s_rating, so introducing per-winding ratings never re-bases the leakage.

Not approximations (common misconceptions): the Dy/Yd leakage under tap is exact (it matches OpenDSS's tap² winding-1 self-impedance scaling — the short-circuit impedance referred to the tapped side goes as tap², the non-tapped side is held at nominal; verified against OpenDSS's short-circuit Yprim, applied identically in the OPF and the Yprim export); the magnetising susceptance (%imag) is retained; zero-loss transformers are exact; the n_winding ZB leakage is exact for any winding count.

Grounding: the stand-alone contract

A transformer's model never absorbs an external grounding. Concretely:

• A grounded-wye star point earthed through OpenDSS rneut/xneut is modeled by the transformer's own r/x_neutral_* fields (an internal branch to earth).
• An OpenDSS earth node (.0) on a winding is routed to the bus neutral, and the bus's grounding (perfect, or an impedance shunt) does the earthing.
• External grounding reactors import as first-class shunt elements.

So the exported Yprim for a transformer is a function of the transformer's own data only — no bus grounding data leaks into it, and there is no Kron reduction of external nodes inside the builder.