> 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/smart-power-simulation-software-sps/blocks-functions-tools/power-transmission-and-distribution/transformers/linear-transformer.md).

# Linear Transformer

## Description

<figure><img src="https://799605156-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdlNg8IbOdahCpFCyzxSN%2Fuploads%2Fgit-blob-b7fcf5a2dacf40c2e323d5cc92e1250c0cabdf8a%2Flinear_transformer_block.png?alt=media" alt=""><figcaption></figcaption></figure>

The **Linear Transformer** block, located in the **OPAL-RT SPS Software/Power Grid Elements** library, models shown consists of three coupled windings wound on the same core.

<figure><img src="https://799605156-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdlNg8IbOdahCpFCyzxSN%2Fuploads%2Fgit-blob-69f98761303c25d060ba402049072dd6b6c16481%2Flinear_transformer_eq_circuit.png?alt=media" alt=""><figcaption></figcaption></figure>

The model takes into account the winding resistances (R1 R2 R3) and the leakage inductances (L1 L2 L3), as well as the magnetizing characteristics of the core, which is modeled by a linear (Rm Lm) branch.

### The Per Unit conversion

In order to comply with industry, the block allows you to specify the resistance and inductance of the windings in per unit (pu). The values are based on the transformer rated power Pn, in VA, nominal frequency fn, in Hz, and nominal voltage Vn, in Vrms, of the corresponding winding. For each winding, the per unit resistance and inductance are defined as

$$
R\_{\text{pu}} = \frac{R(\Omega)}{R\_{\text{base}}} \\\[8pt]
L\_{\text{pu}} = \frac{L(\text{H})}{L\_{\text{base}}} \\\[8pt]
$$

The base impedance, base resistance, base reactance, and base inductance used for each winding are

$$
Z\_{\text{base}} = R\_{\text{base}} = X\_{\text{base}} = \frac{(V\_n)^2}{P\_n} \\\[8pt]

L\_{\text{base}} = \frac{X\_{\text{base}}}{2\pi f\_n} \\\[8pt]
$$

For the magnetization resistance Rm and inductance Lm, the pu values are based on the transformer rated power and on the nominal voltage of winding 1.

For example, the default parameters of winding 1 specified in the dialog box section give the following bases:

$$
R\_{\text{base}} = \frac{(735 \times 10^3)^2}{250 \times 10^6} = 2161,\Omega \\\[8pt]

L\_{\text{base}} = \frac{2161}{2\pi \cdot 60} = 5.732,\text{H} \\\[8pt]
$$

Suppose that the winding 1 parameters are R1 = 4.32 Ω and L1 = 0.4586 H; the corresponding values to be entered in the dialog box are

$$
R\_1 = \frac{4.32,\Omega}{2161,\Omega} = 0.002,\text{pu} \\\[8pt]

L\_1 = \frac{0.4586,\text{H}}{5.732,\text{H}} = 0.08,\text{pu} \\\[8pt]
$$

To specify a magnetizing current of 0.2% (resistive and inductive) based on nominal current, you must enter per unit values of 1/0.002 = 500 pu for the resistance and the inductance of the magnetizing branch. Using the base values calculated previously, these per unit values correspond to Rm = 1.08e6 ohms and Lm = 2866 henries.

### Modeling an ideal transformer

To implement an ideal transformer model, set the winding resistances and inductances to 0, and the magnetization resistance and inductance (Rm Lm) to inf.

## Ports

### Conserving

<table data-header-hidden><thead><tr><th width="249.11114501953125"></th><th></th></tr></thead><tbody><tr><td><strong>+1</strong> — Primary winding positive polarity<br>SPS electrical</td><td>SPS electrical conserving port associated with the primary winding positive polarity.</td></tr><tr><td><strong>-1</strong> — Primary winding negative polarity<br>SPS electrical</td><td>SPS electrical conserving port associated with the primary winding negative polarity.</td></tr><tr><td><strong>+2</strong> — Secondary winding positive polarity<br>SPS electrical</td><td>SPS electrical conserving port associated with the secondary winding positive polarity.</td></tr><tr><td><strong>-2</strong> — Secondary winding negative polarity<br>SPS electrical</td><td>SPS electrical conserving port associated with the secondary winding negative polarity.</td></tr><tr><td><strong>+3</strong> — Tertiary winding positive polarity<br>SPS electrical</td><td><p>SPS electrical conserving port associated with the tertiary winding positive polarity.</p><p><strong>Dependencies</strong> To enable this port, select the <strong>Three windings transformer</strong> parameter.</p></td></tr><tr><td><strong>-3</strong> — Tertiary winding negative polarity<br>SPS electrical</td><td><p>SPS electrical conserving port associated with the tertiary winding negative polarity.</p><p><strong>Dependencies</strong> To enable this port, select the <strong>Three windings transformer</strong> parameter.</p></td></tr></tbody></table>

## Parameters

<table data-header-hidden><thead><tr><th width="249.77777099609375"></th><th></th></tr></thead><tbody><tr><td><strong>Units</strong> — Units<br>pu (default) | SI</td><td><p>Specify the units used to enter the parameters of the Linear Transformer block. Set to pu to use per unit. Set to SI to use SI units. Changing the <strong>Units</strong> parameter from pu to SI or from SI to pu automatically converts the parameters displayed in the mask of the block.</p><p>The per unit conversion is based on the transformer rated power Pn in VA, nominal frequency fn in Hz, and nominal voltage Vn in Vrms, of the windings.</p></td></tr><tr><td><strong>Nominal power and frequency [Pn(VA) fn(Hz)]</strong> — Nominal power and frequency<br>[250e6 60] (default)</td><td><p>The nominal power rating Pn in VA and frequency fn in Hz, of the transformer.</p><p>This parameter does not impact the transformer model when you set the <strong>Units</strong> parameter to SI.</p></td></tr><tr><td><strong>Winding 1 parameters [V1(Vrms) R1(pu) L1(pu)]</strong> — Winding 1 parameters<br>[7.35e+05 0.002 0.08] (default)</td><td><p>The nominal voltage V1 in volts RMS, resistance R1 in pu, and leakage inductance L1 in pu, of the primary winding.</p><p>The pu values are based on the nominal power Pn and on V1. To implement an ideal winding, set R1 and L1 to 0.</p><p><strong>Dependencies</strong> To enable this parameter, set the <strong>Units</strong> parameter to pu.</p></td></tr><tr><td><strong>Winding 1 parameters [V1(Vrms) R1(ohm) L1(H)]</strong> — Winding 1 parameters<br>[7.35e+05 4.3218 0.45856] (default)</td><td><p>The nominal voltage V1 in volts RMS, resistance R1 in ohms, and leakage inductance L1 in H, of the primary winding.</p><p>To implement an ideal winding, set R1 and L1 to 0.</p><p><strong>Dependencies</strong> To enable this parameter, set the <strong>Units</strong> parameter to SI.</p></td></tr><tr><td><strong>Winding 2 parameters [V2(Vrms) R2(pu) L2(pu)]</strong> — Winding 2 parameters<br>[3.15e+05 0.002 0.08] (default)</td><td><p>The nominal voltage, V2 in volts RMS, resistance R2 in pu, and leakage inductance L2 in pu, of the secondary winding.</p><p>The pu values are based on the nominal power Pn and on V2.</p><p>To implement an ideal winding, set R2 and L2 to 0.</p><p><strong>Dependencies</strong> To enable this parameter, set the <strong>Units</strong> parameter to pu.</p></td></tr><tr><td><strong>Winding 2 parameters [V2(Vrms) R2(ohm) L2(H)]</strong> — Winding 2 parameters<br>[3.15e+05 0.7938 0.084225] (default)</td><td><p>The nominal voltage V2 in volts RMS, resistance R2 in ohms, and leakage inductance L2 in H, of the secondary winding. To implement an ideal winding, set R2 and L2 to 0.</p><p><strong>Dependencies</strong> To enable this parameter, set the <strong>Units</strong> parameter to SI.</p></td></tr><tr><td><strong>Three windings transformer</strong> — Three windings transformer<br>on (default) | off</td><td><p>Select this option to implement a linear transformer with three windings.</p><p>Clear this option to implement a linear transformer with two windings.</p><p>A transformer with the number of selected windings is displayed in the block icon.</p></td></tr><tr><td><strong>Winding 3 parameters [V3(Vrms) R3(pu) L3(pu)]</strong> — Winding 3 parameters<br>[3.15e+05 0.002 0.08] (default)</td><td><p>The nominal voltage V3 in volts RMS, resistance R3 in pu, and leakage inductance L3 in pu, of the tertiary winding.</p><p>The pu values are based on the nominal power Pn and on V3.</p><p>To implement an ideal winding, set R3 and L3 to 0.</p><p><strong>Dependencies</strong> To enable this parameter, set the <strong>Units</strong> parameter to pu and select the <strong>Three windings transformer</strong> parameter.</p></td></tr><tr><td><strong>Winding 3 parameters [V3(Vrms) R3(ohm) L3(H)]</strong> — Winding 3 parameters<br>[3.15e+05 0.7938 0.084225] (default)</td><td><p>The nominal voltage V3 in volts RMS, resistance R3 in ohms, and leakage inductance L3 in H, of the tertiary winding.</p><p>To implement an ideal winding, set R3 and L3 to 0.</p><p><strong>Dependencies</strong> To enable this parameter, set the <strong>Units</strong> parameter to SI and select the <strong>Three windings transformer</strong> parameter.</p></td></tr><tr><td><strong>Magnetization resistance and inductance [Rm(pu) Lm(pu)]</strong> — Magnetization resistance and inductance<br>[500 500] (default)</td><td><p>The resistance Rm and inductance Lm simulating the core active and reactive losses. The pu values are based on the nominal power Pn and on V1.</p><p>For example, to specify 0.2% of active and reactive core losses, at nominal voltage, use Rm = 500 pu and Lm = 500 pu. To implement an ideal winding, set this parameter to [inf inf]. Rm must have a finite value when the inductance of winding 1 is greater than zero.</p><p><strong>Dependencies</strong> To enable this parameter, set the <strong>Units</strong> parameter to pu.</p></td></tr><tr><td><strong>Magnetization resistance and inductance [Rm(ohm) Lm(H)]</strong> — Magnetization resistance and inductance<br>[1.0805e+06 2866] (default)</td><td><p>The resistance Rm and inductance Lm simulating the core active and reactive losses. To implement an ideal winding, set this parameter to [inf inf]. Rm must have a finite value when the inductance of winding 1 is greater that zero.</p><p><strong>Dependencies</strong> To enable this parameter, set the <strong>Units</strong> parameter to SI.</p></td></tr><tr><td><strong>Measurements</strong> — Measurements<br>None (default) | Winding voltages | Winding currents | Magnetization current | All voltages and currents</td><td><p>Set to Winding voltages to measure the voltage across the winding terminals of the Linear Transformer block.</p><p>Set to Winding currents to measure the current flowing through the windings of the Linear Transformer block.</p><p>Set to Magnetization current to measure the magnetization current of the Linear Transformer block.</p><p>Set to All voltages and currents to measure the winding voltages and currents plus the magnetization current.</p><p>Place a Multimeter block in your model to display the selected measurements during the simulation.</p><p>In the <strong>Available Measurements</strong> list box of the Multimeter block, the measurements are identified by a label followed by the block name.</p></td></tr></tbody></table>

| **Measurement**       | **Label** |
| --------------------- | --------- |
| Winding voltages      | Uw1:      |
| Winding currents      | Iw1:      |
| Magnetization current | Imag:     |

## Limitations

Windings can be left floating (that is, not connected to the rest of the circuit). However, an internal resistor is automatically added between the floating winding and the main circuit. This internal connection does not affect voltage and current measurements.

Due to limitations inherent to graph theory and its application to electric network theory as implemented in SPS software, the following topologies are unsolvable:

* Loops containing only ideal transformer secondary windings (for example, delta-connected ideal secondary windings of three-phase transformer). To solve this topology issue, you can add a small impedance in series with the loop.
* Loops containing only ideal transformer secondary windings and ideal voltage sources. To solve this topology issue, you can add a small impedance in series with the loop.
* Loops containing only ideal transformer secondary windings and capacitors. To solve this topology issue, you can add a small impedance in series with the loop.
* All topologies where an ideal transformer primary has at least one of its nodes that is connected to elements consisting only of ideal transformer primary windings or current sources (for example, wye-connected three-phase primary windings with floating common point). To resolve this circuit topology, you connect a small resistance to problematic node.

## Examples

The power\_transformer example shows a typical residential distribution transformer network feeding line-to-neutral and line-to-line loads.

To open this example, at the MATLAB Command Window enter power\_transformer.


---

# 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/smart-power-simulation-software-sps/blocks-functions-tools/power-transmission-and-distribution/transformers/linear-transformer.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.
