> 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/simulation-and-analysis/transformer-hysteresis-design-tool.md).

# Transformer Hysteresis Design Tool

## Description

The **Transformer** **Hysteresis Designer Tool app** allows you to view and edit a hysteresis characteristic for the saturable core of the Multi-Winding Transformer, Saturable Transformer, Three-Phase Transformer (Two Windings), and Three-Phase Transformer (Three Windings) blocks. The hysteresis characteristic includes the saturation region located at the limits of the hysteresis loop.

A default hysteresis characteristic displays when you open the app, but you can build as many hysteresis characteristics as you want and save them in different MAT-files. You can use the same characteristic for all your transformer blocks, or you can use different characteristics for each transformer block in the circuit. In the mask of a transformer block, select **Simulate hysteresis** and specify a MAT-file to use.

The **Hysteresis Designer** app includes a flux animation tool that can visualize how by SPS software performs the simulation of the hysteresis. This is an optional tool that is not necessary for the model parameterization. The app calculates the initial trajectory according to the defined hysteresis characteristic. The tool assumes that the last reversal point before starting flux is located on the major loop. The operating point travels until the defined stop flux.

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

## Open the Transformer Hysteresis Design Tool App

* MATLAB® command prompt:

{% code lineNumbers="true" %}

```matlab
power_hysteresis
```

{% endcode %}

* In the Powergui block, click **Hysteresis Designer**

## Parameters

### **Hysteresis Parameters**

<table data-header-hidden><thead><tr><th width="249.6666259765625"></th><th></th></tr></thead><tbody><tr><td><strong>Parameter units</strong> — App parameter units<br>pu (default) | SI</td><td>Convert the fluxes and currents that define the hysteresis characteristic from SI to pu or from pu to SI.</td></tr><tr><td><strong>Segments</strong> — Number of linear segments<br>512 (default) | 32 | 64 | 128 | 256</td><td>Number of linear segments used to define the right side of the hysteresis loop. The left side of the loop is the symmetric image of the right side.</td></tr><tr><td><strong>Remnant flux FR</strong> — Remnant flux<br>0.85 (default) | positive scalar</td><td>Remnant flux point of the hysteresis characteristic (flux at zero current). The remnant flux point is identified by a + mark in the plot.</td></tr><tr><td><strong>Coercive current IC</strong> — Coercive current<br>0.004 (default) | positive scalar</td><td>Coercive current point of the hysteresis characteristic.</td></tr><tr><td><strong>dF/dI at coercive current</strong> — Flux slope at coercive current<br>1000 (default) | positive scalar</td><td>Slope of the flux at the coercive current point (current at zero flux).</td></tr><tr><td><strong>Saturation flux Fs</strong> — Saturation flux<br>1.2 (default) | positive scalar</td><td>Saturation flux point where the hysteresis loop becomes a single-valued saturation curve. The saturation flux point is identified by a * mark in the plot.</td></tr><tr><td><strong>Saturation current Is</strong> — Saturation current<br>0.015 (default) | positive scalar</td><td>Saturation current point where the hysteresis loop becomes a single-valued saturation curve. The saturation region is defined by the <strong>Saturation region currents</strong> parameter.</td></tr><tr><td><strong>Nominal parameters [ P(VA), V(Vrms), f(Hz) ]</strong> — Transformer nominal parameters<br>[150e6, 500e3/sqrt(3), 60] (default) | vector of 3</td><td>Nominal parameters (nominal power in VA, nominal voltage of winding 1 in volts RMS, and nominal frequency in Hz) used in the conversion of the hysteresis parameters.</td></tr><tr><td><strong>Saturation region currents</strong> — Saturation current<br>[0.015 0.03 0.06 0.09 0.12 2.5e+12] (default) | vector</td><td>Vector of current values that define the saturation characteristic. The number of specified points must be the same as the <strong>Saturation region fluxes</strong> parameter. You need to specify only the positive part of the characteristic.</td></tr><tr><td><strong>Saturation region fluxes</strong> — Saturation current<br>[1.2 1.35 1.5 1.56 1.572 1e+12] (default) | positive scalar</td><td>Vector of flux values that define the saturation characteristic. The number of specified points must be the same as for the <strong>Saturation region currents</strong> parameter. You need to specify only the positive part of the characteristic.</td></tr><tr><td><strong>Tolerances [Tol_F, Tol_I]</strong> — Saturation current<br>0.015 (default) | positive scalar</td><td>This parameter is mainly used to minimize the generation of superfluous, very small internal loops or new trajectories because they have little effect and they consume computer memory space. The model can memorize up to 50 embedded minor loops at any time. The <strong>TOL_F</strong> parameter is the tolerance value used to detect whether, after a flux reversal, the operating point remains on the same minor loop or a new embedded loop is created. The smaller the value, the lesser the effect on the normal trajectory behavior. The bigger the value, the lesser the generated number of embedded minor loops. Finally, when the distance between the I coordinate of the actual point of reversal and the penultimate one is less than <strong>TOL_I</strong>, then evolution within these two points follows a line segment instead of a loop.</td></tr><tr><td><strong>Zoom around hysteresis</strong> — Saturation current<br>on (default) | off</td><td>Select to zoom the plot around the hysteresis curve.</td></tr></tbody></table>

### **Flux Animation**

<table data-header-hidden><thead><tr><th width="250.22216796875"></th><th></th></tr></thead><tbody><tr><td><strong>Start</strong> — Starting flux<br><code>0.0</code> (default) | scalar</td><td>Starting flux.</td></tr><tr><td><strong>Stop</strong> — Ending flux<br>? (default) | scalar</td><td>Flux at which the flux animation stops.</td></tr><tr><td><strong>Delta</strong> — Flux delta<br><code>1,78e-08</code> (default) | positive scalar</td><td>Flux increment, in pu or SI, that is used to go from start flux to stop flux.</td></tr></tbody></table>

### **Buttons**

<table data-header-hidden><thead><tr><th width="249.5555419921875"></th><th></th></tr></thead><tbody><tr><td><strong>Update diagram</strong> — Update hysteresis diagram</td><td>Update the hysteresis diagram after you changed hysteresis parameters.</td></tr><tr><td><strong>Animate</strong> — Animate flux animation</td><td>Start the flux animation tool.</td></tr><tr><td><strong>Reset</strong> — Reset flux animation</td><td>Reset the flux animation tool.</td></tr></tbody></table>

### **Menu**

<table data-header-hidden><thead><tr><th width="250.22222900390625"></th><th></th></tr></thead><tbody><tr><td><strong>Load</strong> — Load hysteresis parameters</td><td>Opens a browser window where you can select your own cable data. Select the desired MAT file.</td></tr><tr><td><strong>Save</strong> — Save hysteresis parameters</td><td>Saves your cable data by generating a MAT file that contains the GUI information and the cable data.</td></tr><tr><td><strong>Help</strong> — App documentation</td><td>Open the documentation page of the app.</td></tr></tbody></table>


---

# 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/simulation-and-analysis/transformer-hysteresis-design-tool.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.
