> 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/power_hysteresis.md).

# power\_hysteresis

## Description

The **power\_hysteresis** function offers to view and edit hysteresis characteristic for saturable core of Saturable Transformer blocks

The power\_hysteresis command opens a graphical user interface (GUI) that allows you to view and edit a hysteresis characteristic for the saturable core of the Multi-Winding Transformer, the Saturable Transformer, the Three-Phase Two Windings Transformer, and the Three-Phase Three Windings Transformer blocks. Hysteresis characteristic includes the saturation region located at the limits of the hysteresis loop. This GUI can also be activated from the powergui block dialog box.

hparam = power\_hysteresis(matfile) returns a structure variable hparam with hysteresis parameter values defining the hysteresis characteristic of the specified .mat file.

A default hysteresis characteristic is first displayed when you open the GUI, but you can build as many hysteresis characteristics as you want and save them in different .mat files names. You can use the same characteristic for all of your transformer blocks, or you can use different ones for each transformer block in the circuit. You need to select the **Simulate hysteresis** check box in the masks of the transformer blocks and specify a .mat file to be used by the model.

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

## Syntax <a href="#syntax" id="syntax"></a>

{% code lineNumbers="true" %}

```matlab
power_hysteresis 
hparam = power_hysteresis(matfile)
```

{% endcode %}

## Parameters

### Hysteresis Parameters

<table data-header-hidden><thead><tr><th width="199.73333740234375">Parameter</th><th>Description</th></tr></thead><tbody><tr><td>Segments</td><td>In the pull-down menu, specify the 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>Remanent flux Fr</td><td>Specify the remanent flux point of the hysteresis characteristic (flux at zero current). It is identified by a + mark in the plot.</td></tr><tr><td>Saturation flux Fs</td><td><p>Specify the saturation flux point where the hysteresis loop becomes a single-valued saturation curve.</p><p>It is identified by a * mark in the plot.</p></td></tr><tr><td>Saturation current Is</td><td><p>Specify the saturation current point where the hysteresis loop becomes a single-valued saturation curve.</p><p>The saturation region is defined by the <strong>Saturation region currents</strong> parameter.</p></td></tr><tr><td>Coercive current Ic</td><td>Specify the coercive current point of the hysteresis characteristic.</td></tr><tr><td>dF/dl at coercive current</td><td>Set the slope of the flux at the coercive current point (current at zero flux).</td></tr><tr><td>Saturation region currents</td><td><p>Specify the vector of current values that define the saturation characteristic.</p><p>The number of specified points must be the same as for the <strong>Saturation region fluxes</strong> parameter.</p><p>You only need to specify the positive part of the characteristic.</p></td></tr><tr><td>Saturation region fluxes</td><td><p>Specify the vector of flux values that define the saturation characteristic.</p><p>The number of specified points must be the same as for the <strong>Saturation region currents</strong> parameter.</p><p>You only need to specify the positive part of the characteristic.</p></td></tr><tr><td>Nominal Parameters</td><td>Specify the 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>Parameter units</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>Load</td><td>Load an existing hysteresis characteristic from a .mat file.</td></tr><tr><td>Save</td><td>Save current hysteresis characteristic into a .mat file.</td></tr><tr><td>Close</td><td>Close the hysteresis GUI window.</td></tr></tbody></table>

### Hysteresis Curve

<table data-header-hidden><thead><tr><th width="199.77777099609375">Option</th><th>Description</th></tr></thead><tbody><tr><td>Zoom around the hysteresis</td><td><p>If selected, zoom the plot around the hysteresis curve.</p><p>The default is selected.</p></td></tr><tr><td>Update diagram</td><td>When the parameters are entered, you can click <strong>Display</strong> to visualize the hysteresis characteristic.</td></tr></tbody></table>

### Flux Animation Tool

The Flux Animation tool can be used to visualize how the simulation of the hysteresis is performed by SPS Software. This is an optional tool that is not necessary for the model parameterization. The initial trajectory will be calculated according to the defined hysteresis characteristic.

The model assumes that the last reversal point before starting flux is located on the major loop. The operating point will travel till the defined stop flux.

<table data-header-hidden><thead><tr><th width="200.66680908203125">Option</th><th>Description</th></tr></thead><tbody><tr><td>Start</td><td>Specify the starting flux.</td></tr><tr><td>Stop</td><td>Specify the flux at which the flux animation will stop.</td></tr><tr><td>Flux delta</td><td>Specify flux increment (in pu, or in SI) that is used to go from start flux to stop flux.</td></tr><tr><td>Animate</td><td>Start the Flux Animation tool.</td></tr><tr><td>Reset</td><td>Reset the Flux Animation tool.</td></tr></tbody></table>

### Tolerances Tool

The Tolerances tool is an advanced tool 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 at any time up to 50 embedded minor loops).

The TOL\_F 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 is the effect on the normal trajectory behavior. The bigger the value, the lesser is 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 TOL\_I, then evolution within these two points will follow a line segment instead of a loop.


---

# 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/power_hysteresis.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.
