> 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/example-models/ehs-example-models/features-example-models/saturable-transformer-energization.md).

# Saturable Transformer Energization

## Description <a href="#description" id="description"></a>

This model illustrates the use of the saturable transformer and eHS solver to compute the transformer flux during energization of a transformer. When the breaker is closed, voltage is applied to the transformer. Transformer flux is observed in the CPU model by integrating the secondary voltage of the transformer. Distortion in the sinusoidal wave form shows the saturation effect. By closing the breaker at a different time, transformer flux, and its saturation will vary.

## Detailed explanation

The RT-LAB model consists of a master subsystem (i.e. "sm\_computation") and a console subsystem (i.e. "sc\_user\_interface").

* The **master subsystem** has power network interface ("eHS\_SE\_SFunction\_Drivers")

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

* The **console subsystem** is used to control set points, such as magnitude of source voltage and breaker activation during real-time simulation. Users can also monitor voltages and currents of the transformer at any point during the simulation.

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

For this example the role of each set points are as following:

* “**VLN peak**”: This sets the amplitude of the AC voltage source;
* “**breaker manual command**”: This sets the break state:
  1. the breaker opens;
  2. the breaker closes.

The **"eHS\_SE\_SFunction\_Drivers" solver** solves the power network built using schematic editor software during the real time simulation. The circuit built in schematic editor can be edited or viewed by choosing the edit option available in the solver block.

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

eFPGASIM allows to simulate two different models for transformers:

* linear (or unsaturated) transformer;
* saturated transformer.

In the linear model the effects of magnetic saturation are neglected, in contrast with the saturable transformer, where these effects are taken into account. Each model has its own block in OPAL-RT Schematic Editor Library Browser, with different parameters to be set.

When the model is compiled in Simulink, the configuration of the eHS solver will be generated according to the schematic editor circuit characteristics. Elements will be put into matrices and stored in .mat files that will be transferred into the solver when the model is run from the RT-LAB interface. Matrices are generated during model compilation in RT-LAB.

## Requirements <a href="#requirements" id="requirements"></a>

The RT-LAB, Schematic Editor/Unified Database and eFPGASIM toolboxes must be installed on the host and target computers in order to run this example model properly. Please refer to the product documentation for details on version compatibility.

## Simulation and results

In order to run the example, follow the procedure below:

1. If eFPGASIM is installed, add the example project to RT-LAB by selecting **File>>New>>RT-LAB Project>>eFPGASIM>Schematic\_Editor\_Workflow>>Features >>Saturable Transformer Energization**.
2. Compile the RT Model by clicking on **Build** in RT-LAB.
3. Once the model has been successfully built, **Load** and **Execute** the model in RT-LAB in order to begin the real-time simulation.
4. Once the real-time model and the eHS are running, observe the results of the eHS simulation by opening the **measurements** subsystem in the Simulink Console.

<details>

<summary><strong>S-function Workflow</strong></summary>

The **Mezzanine Option block** is an RT-LAB block used in the **S-Function workflow** to configure the settings of the I/O cards for each mezzanine. The available settings depend on the specific type of I/O card.

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

</details>

<details>

<summary><strong>OpalBoard workflow</strong></summary>

[OPAL-RT Board](https://www.opal-rt.com/docs/rt-lab/configure-ios/analog-digital-and-sfp-ios/opal-rt-board-workflow.md) allow the configuration of I/O card settings for each mezzanine.

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

If, for a given I/O mezzanine, this block is not used, then the corresponding settings will be kept at their default values. These default values are dependent on particularities of the bitstream, and they are not guaranteed to be exposed to the user loading their model. Further, the default values populating the Mezzanine Option block do not necessarily correspond to the default settings that will be seen if the Mezzanine Option block is not used.

Note that if a Mezzanine Option block is used, and the choice of mezzanine type is incorrect for the given slot, the model will still load and run. However, there will be errors in the load log in RT-LAB. For example, the following error is observed in the case that slot 1A on the simulator holds an OP5330-3, when we place a Mezzanine Option block that attempts to configure an OP5369 on slot 1A:

{% code overflow="wrap" lineNumbers="true" %}

```
Mezzanine configurator: OP5369 Threshold configuration.
ERROR: OPAL-RT Board: The threshold control register for slot 1A is in an unexpected state. Please reprogram the bitstream.
ERROR: Mezzanine configurator: Threshold configuration failed...
```

{% endcode %}

Further, as documented in the aforementioned RT-LAB page, the block outputs its status: a 0 in the case when the block’s settings have been correctly applied, and a -1 otherwise. For example, in the below model I incorrectly configured one block by giving it the wrong I/O card, and set the other correctly. The result when we load the model reflects this:

<figure><img src="https://96827845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNRdpSk8kjn20gXAexnt6%2Fuploads%2Fgit-blob-a4fe002fb70685f86d0a022ad92068069ae7264d%2Fehs-opalboard-block-workflow.png?alt=media" alt="" width="188"><figcaption></figcaption></figure>

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

</details>

{% hint style="info" %}
In S-Function workflow, example models support any chassis. You can contextualize your example model by selecting the chassis in the Chassis selection block.
{% endhint %}

### Setup and connections <a href="#setup-and-connections" id="setup-and-connections"></a>

This model does not require any IOs, as it is more a demonstrator of the expected results.

It is possible to execute this simulation in different chassis. The "Simulator Selection" block in "satXfmrEnergization" root allows the user to select the appropriate target and automatically change the configuration and firmware.

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

### Run the model

During real-time execution;

1. Set reference voltage amplitude of the source VLN peak in the console. If voltage value is larger than transformer nominal voltage (V<sub>LL,RMS</sub>=500 kV → V<sub>LN,peak</sub>=408 kV), the core saturates and current and flux curves are distorted.
2. Set the breaker state “breaker manual command” in the console. The energization process may be different depending on the instant the breaker is closed.

<figure><img src="https://96827845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNRdpSk8kjn20gXAexnt6%2Fuploads%2Fgit-blob-84666eed309be840c2d0fb23ab1a6b4f83cf8b7f%2Fehs-model-saturabletransfo-6.png?alt=media" alt=""><figcaption><p>Simulation results during steady-state and nominal voltage.</p></figcaption></figure>

<figure><img src="https://96827845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNRdpSk8kjn20gXAexnt6%2Fuploads%2Fgit-blob-9d2d052aef8d885f5e1c2dc37c00ec0331db1cc0%2Fehs-model-saturabletransfo-7.png?alt=media" alt=""><figcaption><p>Simulation results during energization (the results may be different depending on the instant the breaker is closed).</p></figcaption></figure>


---

# 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/example-models/ehs-example-models/features-example-models/saturable-transformer-energization.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.
