> For the complete documentation index, see [llms.txt](https://www.opal-rt.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.opal-rt.com/docs/rt-lab/model-and-simulation/phasor-domain-with-ephasorsim/integrate-a-power-system-model-to-ephasorsim/native-library-components/transformer-components.md).

# Transformer Components

## Positive-sequence network <a href="#parameters" id="parameters"></a>

In a **positive-sequence network**, a 2-winding transformer model or a 3-winding transformer model can be used.

{% hint style="info" %}

* All impedance and magnetizing parameters are expressed on the **network MVA base** and referenced to the **primary winding voltage base**.
* Phase shifts must be within: −180∘≤θ≤180∘-180. A positive phase shift indicates that the primary winding voltage leads the secondary winding voltage. The default value of all phase-shift parameters is `0`.
* The default values for **Ratio W1**, **Ratio W2**, and **Ratio W3** is `1`.
* The default value of all phase-shift parameters is:
  {% endhint %}

### 2-Winding transformer

A positive-sequence 2-winding transformer connects a primary bus to a secondary bus and supports off-nominal tap ratios and phase shifting.

The admittance matrix for this model is:

$$
Y= \begin{bmatrix} Y\_{11} & Y\_{12}\ Y\_{21} & Y\_{22} \end{bmatrix} = \begin{bmatrix} \dfrac{Y\_{sr}}{T^2}+Y\_m & -\dfrac{Y\_{sr}}{T\angle(-\varphi)} \\\[10pt] -\dfrac{Y\_{sr}}{T\angle\varphi} & Y\_{sr} \end{bmatrix}
$$

where

$$
Y\_{sr} = \frac{1} {\left(\mathrm{RatioW2}\right)^2 \left(R+jX\_L\right)}, Y\_m = G\_{mag} + jB\_{mag}, T = \frac{\mathrm{RatioW1}} {\mathrm{RatioW2}}
$$

| Excel Column Name     | Native Component Parameter | Description                                                                                   |
| --------------------- | -------------------------- | --------------------------------------------------------------------------------------------- |
| **ID**                | `name`                     | Transformer identifier.                                                                       |
| **Status**            | `status`                   | <p>Initial service status.<br><code>1</code> = connected<br><code>0</code> = disconnected</p> |
| **From bus**          | `bus0`                     | Primary bus identifier.                                                                       |
| **To bus**            | `bus1`                     | Secondary bus identifier.                                                                     |
| **R (pu)**            | `impedance.re`             | Series resistance between primary and secondary windings.                                     |
| **Xl (pu)**           | `impedance.im`             | Series reactance between primary and secondary windings.                                      |
| **Gmag (pu)**         | `magnetization.re`         | Magnetizing conductance.                                                                      |
| **Bmag (pu)**         | `magnetization.im`         | Magnetizing susceptance.                                                                      |
| **Ratio W1 (pu)**     | `rW1`                      | Primary off-nominal tap ratio.                                                                |
| **Ratio W2 (pu)**     | `rW2`                      | Secondary off-nominal tap ratio.                                                              |
| **Phase Shift (deg)** | `phaseW1`                  | Phase shift between primary and secondary voltages.                                           |

### 3-Winding transformer

A positive-sequence 3-winding transformer connects primary, secondary, and tertiary buses. Each winding supports independent tap ratios and phase shifts.

| Excel Column Name  | Native Component Parameter | Description                                                                                   |
| ------------------ | -------------------------- | --------------------------------------------------------------------------------------------- |
| **ID**             | `name`                     | Transformer identifier.                                                                       |
| **Status**         | `status`                   | <p>Initial service status.<br><code>1</code> = connected<br><code>0</code> = disconnected</p> |
| **Bus1**           | `buses[0]`                 | Primary bus identifier.                                                                       |
| **Bus2**           | `buses[1]`                 | Secondary bus identifier.                                                                     |
| **Bus3**           | `buses[2]`                 | Tertiary bus identifier.                                                                      |
| **R\_12 (pu)**     | `impedance.re`             | Series resistance between primary and secondary windings.                                     |
| **Xl\_12 (pu)**    | `impedance.im`             | Series reactance between primary and secondary windings.                                      |
| **R\_23 (pu)**     | `impedance.re`             | Series resistance between secondary and tertiary windings.                                    |
| **Xl\_23 (pu)**    | `impedance.im`             | Series reactance between secondary and tertiary windings.                                     |
| **R\_31 (pu)**     | `impedance.re`             | Series resistance between primary and tertiary windings.                                      |
| **Xl\_31 (pu)**    | `impedance.im`             | Series reactance between primary and tertiary windings.                                       |
| **Gmag (pu)**      | `magnetization.re`         | Magnetizing conductance.                                                                      |
| **Bmag (pu)**      | `magnetization.im`         | Magnetizing susceptance.                                                                      |
| **Ratio W1 (pu)**  | `rW1`                      | Off-nominal tap ratio of winding 1.                                                           |
| **Ratio W2 (pu)**  | `rW2`                      | Off-nominal tap ratio of winding 2.                                                           |
| **Ratio W3 (pu)**  | `rW3`                      | Off-nominal tap ratio of winding 3.                                                           |
| **Phase Shift W1** | `phaseW1`                  | Phase shift of winding 1.                                                                     |
| **Phase Shift W2** | `phaseW2`                  | Phase shift of winding 2.                                                                     |
| **Phase Shift W3** | `phaseW3`                  | Phase shift of winding 3.                                                                     |

## Multiphase network <a href="#parameters" id="parameters"></a>

In a **multiphase network**, two 2-winding transformer modelscan be used. Each model can represent a single-phase, two-phase, or three-phase transformer. To represent a single-phase transformer, define Bus1 only. To represent a two-phase transformer, define Bus1 and Bus2. To represent a three-phase transformer, define Bus1, Bus2, and Bus3.

{% hint style="info" %}

* Unused bus connections must appear after all populated entries. For example, defining Bus2 while leaving Bus1 empty is invalid.
* For each phase connection, the corresponding bus must be specified on both windings. For example, if **Winding From / Bus2** is defined, **Winding To / Bus2** must also be defined.
* Each phase can be connected independently. For example, **Winding From/Bus 1** can be connected to phase A while **Winding To/Bus 1** is connected to phase B.
* Supported winding configurations are: *DD0*, *YgYg0*, *DYg1*, *YgD1*.
  {% endhint %}

### 2-Winding transformer

| Excel Column Name                   | Native Component Parameter | Description                                                                                   |
| ----------------------------------- | -------------------------- | --------------------------------------------------------------------------------------------- |
| **ID**                              | `name`                     | Transformer identifier.                                                                       |
| **Status**                          | `status`                   | <p>Initial service status.<br><code>1</code> = connected<br><code>0</code> = disconnected</p> |
| **Number of Phases**                | N/A                        | Number of phases represented by the transformer (`1`, `2`, or `3`).                           |
| **Bus1, Bus2, Bus3 - Winding From** | `windings[0].buses`        | Bus identifiers connected to the primary winding.                                             |
| **V (kV) - - Winding From**         | `windings[0].kVll`         | Primary winding nominal line-to-line voltage (kV).                                            |
| **S\_base (kVA) - Winding From**    | `windings[0].kVA_base`     | Primary winding rated apparent power (kVA).                                                   |
| **Conn. type - Winding From**       | `windings[0].conn`         | Primary winding connection type (`wye` or `delta`).                                           |
| **Bus1, Bus2, Bus3 - Winding To**   | `windings[1].buses`        | Bus identifiers connected to the secondary winding.                                           |
| **V (kV) - Winding To**             | `windings[1].kVll`         | Secondary winding nominal line-to-line voltage.                                               |
| **S\_base (kVA) - Winding To**      | `windings[1].kVA_base`     | Secondary winding rated apparent power.                                                       |
| **Conn. type - Winding To**         | `windings[1].conn`         | Secondary winding connection type (`wye` or `delta`).                                         |
| **Tap 1, Tap 2, Tap 3**             | `taps`                     | Initial tap positions for phases 1, 2, and 3.                                                 |
| **Lowest Tap**                      | `min_tap`                  | Minimum allowable tap position.                                                               |
| **Highest Tap**                     | `max_tap`                  | Maximum allowable tap position.                                                               |
| **Min Range (%)**                   | `min_range_percent`        | Maximum voltage buck associated with the minimum tap position.                                |
| **Max Range (%)**                   | `max_range_percent`        | Maximum voltage boost associated with the maximum tap position.                               |
| **X (pu)**                          | `xhl_pu`                   | Leakage reactance between windings.                                                           |
| **Rw1 (pu)**                        | `windings[0].r_pu`         | Primary winding resistance.                                                                   |
| **Rw2 (pu)**                        | `windings[1].r_pu`         | Secondary winding resistance.                                                                 |

### 2-Winding transformer with mutual impedance

| Excel Column Name                   | Native Component Parameter | Description                                                                                   |
| ----------------------------------- | -------------------------- | --------------------------------------------------------------------------------------------- |
| **ID**                              | `name`                     | Transformer identifier.                                                                       |
| **Status**                          | `status`                   | <p>Initial service status.<br><code>1</code> = connected<br><code>0</code> = disconnected</p> |
| **Number of Phases**                | N/A                        | Number of phases represented by the transformer (`1`, `2`, or `3`).                           |
| **Bus1, Bus2, Bus3 - Winding From** | `windings[0].buses`        | Bus identifiers connected to the primary winding.                                             |
| **V (kV) - - Winding From**         | `windings[0].kVll`         | Primary winding nominal line-to-line voltage (kV).                                            |
| **S\_base (kVA) - Winding From**    | `windings[0].kVA_base`     | Primary winding rated apparent power (kVA).                                                   |
| **Conn. type - Winding From**       | `windings[0].conn`         | Primary winding connection type (`wye` or `delta`).                                           |
| **Bus1, Bus2, Bus3 - Winding To**   | `windings[1].buses`        | Bus identifiers connected to the secondary winding.                                           |
| **V (kV) - Winding To**             | `windings[1].kVll`         | Secondary winding nominal line-to-line voltage.                                               |
| **S\_base (kVA) - Winding To**      | `windings[1].kVA_base`     | Secondary winding rated apparent power.                                                       |
| **Conn. type - Winding To**         | `windings[1].conn`         | Secondary winding connection type (`wye` or `delta`).                                         |
| **Tap 1, Tap 2, Tap 3**             | `taps`                     | Initial tap positions for phases 1, 2, and 3.                                                 |
| **Lowest Tap**                      | `min_tap`                  | Minimum allowable tap position.                                                               |
| **Highest Tap**                     | `max_tap`                  | Maximum allowable tap position.                                                               |
| **Min Range (%)**                   | `min_range_percent`        | Maximum voltage buck associated with the minimum tap position.                                |
| **Max Range (%)**                   | `max_range_percent`        | Maximum voltage boost associated with the maximum tap position.                               |
| **Z0 leakage (pu)**                 |                            | Zero-sequence leakage impedance.                                                              |
| **Z1 leakage (pu)**                 |                            | Positive-sequence leakage impedance.                                                          |
| **X0/R0**                           |                            | Ratio of zero-sequence reactance to zero-sequence resistance.                                 |
| **X1/R1**                           |                            | Ratio of positive-sequence reactance to positive-sequence resistance.                         |
| **No Load Loss (kW)**               |                            | No-load power loss.                                                                           |

### Model equations

Multiphase transformer components are modeled using the primitive nodal admittance matrix formulation **Y**<sub>**prim**</sub>. \[1] \[2]

$$
\begin{aligned} Y\_{\mathrm{prim}} &= A N B Z\_B^{-1} B^T N^T A^T \ Y\_1 &= B Z\_B^{-1} B^T \ Y\_w &= N Y\_1 N^T \ Y\_{\mathrm{prim}} &= A Y\_w A^T \end{aligned}
$$

Then describe the variables in point form:

* **Y**<sub>**prim**</sub>**​**: Primitive nodal admittance matrix.
* **Y**<sub>**1**</sub>**​**: Ground-referenced nodal admittance matrix on a 1 V base.
* **Y**<sub>**w**</sub>**​**: Winding admittance matrix.
* **N**: Incidence matrix whose nonzero elements are the inverses of the winding turns ratios. This matrix represents the effect of the ideal transformers used to obtain the actual winding voltages.
* **B**: Incidence matrix with elements equal to 1, −1, or 0. It relates currents in the short-circuit reference frame to currents in the nodal-admittance reference frame.
* **A**: Incidence matrix relating winding currents to the transformer terminal currents.
* **Z**<sub>**B​**</sub>: Short-circuit impedance matrix.
* **Y**<sub>**w**</sub>**​**: Winding admittance matrix.
* **n**<sub>**p**</sub>**​**: Number of phases.
* **m**: Number of windings.
* **n**<sub>**c**</sub>**​**: Number of terminal currents.

### Configuration examples

#### Single-phase 2-winding transformer

Consider a single-phase 2-winding transformer with the following ratings:

* Primary and secondary voltages: **7.2/0.12 kV**
* Rated apparent power: **25 kVA**
* Total leakage reactance (X): **20%**
* Total winding resistance (R): **1.1%**

In this case, **np** = 1 and **m** = 2.

<figure><img src="https://96827845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNRdpSk8kjn20gXAexnt6%2Fuploads%2Fgit-blob-3ea86b8cfc7cd0bd903e85312ead47ec2916630f%2Feph-Single-phase-2-winding-transformer.png?alt=media" alt=""><figcaption></figcaption></figure>

**Short-circuit impedance:**

$$
Z\_B ; (\mathrm{pu}) = 0.011 + 0.02i
$$

$$
Z\_B ; (1,\mathrm{V\ base})
===========================

Z\_B ; (\mathrm{pu})
\times
\frac{1^2}{25,\mathrm{kVA}}
===========================

4.4\times10^{-7}
\+
8\times10^{-7} i
$$

$$
Z\_B^{-1}
=========

## 527.831\times10^{3}

959.692\times10^{3} i
$$

**Ground-referenced admittance matrix:**

$$
Y\_1 = B Z\_B^{-1} B^T
$$

**Incidence matrix B:**

$$
B=
\begin{bmatrix}
1 \\
-1
\end{bmatrix}
$$

**Resulting matrix Y**<sub>**1**</sub>**:**

$$
Y\_1=
\begin{bmatrix}
a & -a \\
-a & a
\end{bmatrix}
$$

where

$$
a=
527.831\times10^{3}
-------------------

959.692\times10^{3} i
$$

$$N \text{ is a matrix of dimension } 2 np *m \times np*m = 4 \times 2$$ :

$$
N = \begin{bmatrix} \dfrac{1}{7200} & 0 \\\[6pt] -\dfrac{1}{7200} & 0 \\\[6pt] 0 & \dfrac{1}{120} \\\[6pt] 0 & -\dfrac{1}{120} \end{bmatrix}
$$

$$
Y\_w = N Y\_1 N^T
$$

To generate matrix **A**, the number of terminal currents in the transformer model must first be determined. In this example, there are **2 terminal currents**, therefore:

$$
A = \begin{bmatrix} 1 & 0 & 0 & 0 \ 0 & 0 & 1 & 0 \end{bmatrix}
$$

**Resulting Excel file with component parameters:**

The total resistance was divided equally between the two windings (**RW1** = **RW2** = 0.011 pu/2 = 0.0055 pu). Although the transformer model is single-phase, the voltage ratings must be entered as **phase-to-phase voltages**, as specified in the table above.

<figure><img src="https://96827845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNRdpSk8kjn20gXAexnt6%2Fuploads%2Fgit-blob-5a607a12468bf0d8595b01aef77bfab5f0a95454%2Fimage%20(195).png?alt=media" alt=""><figcaption></figcaption></figure>

#### Three-phase 2-winding transformer

Consider a three-phase 2-winding transformer with the following ratings:

* Primary and secondary voltages: **12.47/0.208 kV**
* Winding configuration: **wye/delta**
* Rated apparent power: **75 kVA**
* Total leakage reactance (X): **20%**
* Total winding resistance (R): **1.1%**

In this case, **np** = 3 and **m** = 2.

<figure><img src="https://96827845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNRdpSk8kjn20gXAexnt6%2Fuploads%2Fgit-blob-df7f0cc1acc90e09ff0b468320a38c023e3570db%2Feph-Three-phase-2-winding-transformer.png?alt=media" alt=""><figcaption></figcaption></figure>

**Short-circuit impedance:**

$$
Z\_B ; (\mathrm{pu}) = 0.011 + 0.02i
$$

$$
Z\_B ; (1,\mathrm{V\ base})
===========================

Z\_B ; (\mathrm{pu})
\times
\frac{1^2}{75,\mathrm{kVA}}
===========================

1.4667\times10^{-7}
\+
2.6667\times10^{-7} i
$$

$$
Z\_B^{-1}
=========

## 158.349\times10^{3}

287.907\times10^{3} i
\ (\Omega^{-1})
$$

**Ground-referenced admittance matrix:**

$$
Y\_1 = B Z\_B^{-1} B^T
$$

**Incidence matrix B:**

$$
B=
\begin{bmatrix}
1 & 0 & 0\\
-1 & 0 & 0\\
0 & 1 & 0\\
0 & -1 & 0\\
0 & 0 & 1\\
0 & 0 & -1
\end{bmatrix}
$$

**Resulting matrix Y**<sub>**1**</sub>**:**

$$
Y\_1=
\begin{bmatrix}
a & -a & 0 & 0 & 0 & 0\\
-a & a & 0 & 0 & 0 & 0\\
0 & 0 & a & -a & 0 & 0\\
0 & 0 & -a & a & 0 & 0\\
0 & 0 & 0 & 0 & a & -a\\
0 & 0 & 0 & 0 & -a & a
\end{bmatrix}
$$

where

$$
a=
158.349\times10^{3}
-------------------

287.907\times10^{3}i
$$

$$N \text{ is a matrix of dimension } 2 np*m \times np*m = 12 \times 6$$ :

$$
N = \begin{bmatrix} \dfrac{1}{12470} & 0 & 0 & 0 & 0 & 0 \ -\dfrac{1}{12470} & 0 & 0 & 0 & 0 & 0 \ 0 & \dfrac{1}{208\sqrt{3}} & 0 & 0 & 0 & 0 \ 0 & -\dfrac{1}{208\sqrt{3}} & 0 & 0 & 0 & 0 \ 0 & 0 & \dfrac{1}{12470} & 0 & 0 & 0 \ 0 & 0 & -\dfrac{1}{12470} & 0 & 0 & 0 \ 0 & 0 & 0 & \dfrac{1}{208\sqrt{3}} & 0 & 0 \ 0 & 0 & 0 & -\dfrac{1}{208\sqrt{3}} & 0 & 0 \ 0 & 0 & 0 & 0 & \dfrac{1}{12470} & 0 \ 0 & 0 & 0 & 0 & -\dfrac{1}{12470} & 0 \ 0 & 0 & 0 & 0 & 0 & \dfrac{1}{208\sqrt{3}} \ 0 & 0 & 0 & 0 & 0 & -\dfrac{1}{208\sqrt{3}} \end{bmatrix}
$$

$$
Y\_w = N Y\_1 N^T
$$

To generate matrix **A**, the number of terminal currents in the transformer model must first be determined. In this example, there are **6 terminal currents**, therefore:

$$
A = \begin{bmatrix} 1 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 \ 0 & 0 & 0 & 0 & 1 & 0 & 0 & 0 & 0 & 0 & 0 & 0 \ 0 & 0 & 0 & 0 & 0 & 0 & 0 & 0 & 1 & 0 & 0 & 0 \ 0 & 0 & 1 & 0 & 0 & 0 & 0 & 1 & 0 & 0 & 0 & 1 \ 0 & 0 & 0 & 1 & 0 & 0 & 1 & 0 & 0 & 0 & 0 & 0 \ 0 & 0 & 0 & 0 & 0 & 0 & 0 & 1 & 0 & 0 & 1 & 0 \end{bmatrix}
$$

**Resulting Excel file with component parameters:**

<figure><img src="https://96827845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNRdpSk8kjn20gXAexnt6%2Fuploads%2Fgit-blob-eb479c45df97bf8d4d520afd435872c4199c341f%2FTransformer-Example4.png?alt=media" alt=""><figcaption></figcaption></figure>

### References

\[1] Roger C. Dugan, “A Perspective on Transformer Modeling for Distribution Systems Analysis,” \*2003 IEEE Power Engineering Society General Meeting\*. DOI: 10.1109/PES.2003.1267146

\[2] Roger C. Dugan and Surya Santoso, “An Example of 3-Phase Transformer Modeling for Distribution Systems Analysis,” \*2003 IEEE PES Transmission and Distribution Conference and Exposition\*. DOI: 10.1109/TDC.2003.1335084


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://www.opal-rt.com/docs/rt-lab/model-and-simulation/phasor-domain-with-ephasorsim/integrate-a-power-system-model-to-ephasorsim/native-library-components/transformer-components.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
