> 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/get-started/build-and-customize-sps-models.md).

# Build and Customize SPS Models

Peak amplitudeSPS provides a wide collection of models. It can happen, however, that you need to interface your own model with the standard models provided in the SPS library. This model could be a simple nonlinear resistance simulating an arc or a varistor, a saturable inductor, a new type of motor, etc.

In the following sections, a simple saturable inductance and a nonlinear resistance serve as examples.

## Modeling a nonlinear inductance

Consider an inductor of 2 henries designed to operate at a nominal voltage, Vnom = 120 V RMS, and a nominal frequency, fnom = 60 Hz. From zero to 120 V RMS the inductor has a constant inductance, L = 2 H. When voltage exceeds its nominal voltage, the inductor saturates and its inductance is reduced to Lsat = 0.5 H. The nonlinear flux-current characteristic is plotted in the next figure. Flux and current scales are in per units. The nominal voltage and nominal current are chosen as base values for the per-unit system.

<figure><img src="https://799605156-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdlNg8IbOdahCpFCyzxSN%2Fuploads%2Fgit-blob-82358a347aac88aa86ef561bb6cd911de2c90b7a%2Fflux_current_charca_nonlinear_inductance.png?alt=media" alt=""><figcaption><p><strong>Flux-Current Characteristic of the Nonlinear Inductance</strong></p></figcaption></figure>

The current i flowing in the inductor is a nonlinear function of flux linkage ψ that, in turn, is a function of v appearing across its terminals. These relations are given by the following equations:

$$
v = L \cdot \frac{di}{dt} = \frac{d\psi}{dt}
\quad \text{or} \quad
\psi = \int v \cdot dt \ i = \frac{\psi}{L(\psi)}
$$

The model of the nonlinear inductance can therefore be implemented as a controlled current source, where current i is a nonlinear function of voltage v.

## Model of a nonlinear inductance

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

The implementation shows a circuit using a 2 H nonlinear inductance connected in series with two voltage sources (an AC Voltage Source Preview block of 120 volts RMS, 60 Hz, and a DC Voltage Source Preview block) and a 5 ohm resistor.

All the elements used to build the nonlinear model are grouped in a subsystem named Nonlinear Inductance. The inductor terminals are labeled In and Out. A Simulink® output returning the flux has been added to the subsystem. You can connect this output to a Scope block to observe the flux.

The nonlinear model uses a Voltage Measurement Preview block to read the voltage at the inductance terminals and a Controlled Current Source Preview block. The direction of the arrow of the current source is oriented from input to output according to the model shown above.

An Integrator block computes the flux from the voltage input, and a 1‑D Lookup Table block implements the saturation characteristic i = f(ψ) described above.

### Implementation of a nonlinear inductance

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

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

Two Fourier blocks from the **SPS > Sensors and Measurements** library are used to analyze the fundamental component and the DC component of the current.

Using blocks of the SPS and Simulink libraries, build the circuit shown above. To implement the $$i = f(ψ)$$ relation, specify the following vectors in the 1‑D Lookup Table block:

| Vector from 1‑D Lookup table | Value                                          |
| ---------------------------- | ---------------------------------------------- |
| **Breakpoints 1 (flux)**     | \[-1.25 -1 1 1.25 ] *(120*sqrt(2)/(2*pi*60))\* |
| **Table data (current)**     | \[-2 -1 1 2] *(120*sqrt(2)/(4*pi*60))\*        |

Set the following parameters for the two sources:

| Source         | Value                |
| -------------- | -------------------- |
| **AC source**  |                      |
| Peak amplitude | $$120\times \sqrt2$$ |
| Phase          | 90 degrees           |
| Frequency      | 60 Hz                |
| **DC source**  |                      |
| Amplitude      | 0 V                  |

Adjust the simulation time to 1.5s and select the `ode23tb` integration algorithm with default parameters. Start the simulation.

As expected, the current and the flux are sinusoidal. Their peak values correspond to the nominal values.

$$Peak Current = \frac{120 \times \sqrt{2}}{2 \times 2\pi \times 60} = 0.225 A$$

$$Peak Flux= \frac{120 \times \sqrt{2}}{2\pi \times 60} = 0.450 , Vs$$

Now change the DC voltage to 1 V and restart the simulation. Observe that the current is distorted. The 1 V DC voltage is now integrated, causing a flux offset, which makes the flux enter into the nonlinear region of the flux-current characteristic (ψ > 0.450 V.s). As a result of this flux saturation, the current contains harmonics. Zoom in on the last three cycles of the simulation. The peak value of the current now reaches 0.70 A and the fundamental component has increased to 0.368 A. As expected, the DC component of the current is 1 V / 0.5 Ω = 0.2 A.

You can create a mask that specifies the following prompts, variables, and values:

<table><thead><tr><th width="352.20001220703125">Prompt</th><th align="right">Variable</th><th align="right">Default</th></tr></thead><tbody><tr><td>Nominal voltage (Volts rms)</td><td align="right"><code>Vnom</code></td><td align="right">120</td></tr><tr><td>Nominal frequency (Hz)</td><td align="right"><code>fnom</code></td><td align="right">60</td></tr><tr><td>Unsaturated inductance (H)</td><td align="right"><code>L</code></td><td align="right">2</td></tr><tr><td>Saturation characteristic [i1(pu) phi1(pu); i2 phi2; …]</td><td align="right"><code>sat</code></td><td align="right">[0, 0; 1, 1; 2, 1.25]</td></tr></tbody></table>

The following code in the mask initializations of the block prepares the two vectors Current\_vect and Flux\_vect to be used in the Look-Up Table block of the model.

```
% Define base current and Flux for pu system
I_base = Vnom*sqrt(2)/(L*2*pi*fnom);
Phi_base = Vnom*sqrt(2)/(2*pi*fnom); 
% Check first two points of the saturation characteristic
if ~all(all(sat(1:2,:)==[0 0; 1 1])),
	h=errordlg('The first two points of the characteristic must 
be [0 0; 1 1]','Error');
	uiwait(h);
end 
% Complete negative part of saturation characteristic
[npoints,ncol]=size(sat);
sat1=[sat ; -sat(2:npoints,:)];
sat1=sort(sat1); 
% Current vector (A)  and flux vector (V.s)
Current_vect=sat1(:,1)*I_base;
Flux_vect=sat1(:,2)*Phi_base;
```

As the saturation characteristic is specified only in the first quadrant, three lines of code are added to complete the negative part of the saturation characteristic. Notice also how the validity of the first segment of the saturation characteristic is verified. This segment must be defined by two points \[0 0; 1 1] specifying a 1 pu inductance (nominal value) for the first segment.

## Modeling a nonlinear resistance

The technique for modeling a nonlinear resistance is similar to the one used for the nonlinear inductance.

A good example is a metal-oxide varistor (MOV) having the following V–I characteristic:

$$
i = I\_0 \times (\frac{v} {V\_0})^α
$$

where

* v, i = Instantaneous voltage and current
* V<sub>0</sub> = Protection voltage
* I<sub>0</sub> = Reference current used to specify the protection voltage
* α = Exponent defining the nonlinear characteristic (typically between 10 and 50)

The following figure shows an application of such a nonlinear resistance to simulate a MOV used to protect equipment on a 120 kV network. To keep the circuit simple, only one phase of the circuit is represented.

<figure><img src="https://799605156-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdlNg8IbOdahCpFCyzxSN%2Fuploads%2Fgit-blob-aa3fc3f55c467cf4828ee0499c64d0c7e3ca5729%2Fex_nonlinear_resitance_applied.png?alt=media" alt=""><figcaption><p><strong>Nonlinear Resistance Applied on a 120 kV Network</strong></p></figcaption></figure>

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

This model is available in the **power\_nonlinearresistor** example.

The model does not use a Look‑Up Table block as in the case of the nonlinear inductance model. As the analytical expression of current as a function of voltage is known, the nonlinear I(V) characteristic is implemented directly with a Fcn block from the Simulink library.

This purely resistive model contains no states. It produces an algebraic loop in the state-space representation of the circuit.

Algebraic loops often lead to slow simulation times. You should break the loop with a block that does not change the nonlinear characteristic. Here a first-order transfer function H(s) = 1/(1+T s) is introduced into the system, using a fast time constant (T = 0.01 µs).

## Connecting your model with other nonlinear blocks

Nonlinear models implemented as a current source cannot be connected in series with an inductor, another current source, or an open circuit. Such circuit topologies cause errors in SPS.

Similarly, if your nonlinear model uses a Controlled Voltage Source Preview block, this model could not be short-circuited or connected across a capacitor.

Suppose, for example, that you want to study the inrush current in the nonlinear resistance of the power\_nonlinearresistor example model when it is energized on a voltage source:

<figure><img src="https://799605156-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdlNg8IbOdahCpFCyzxSN%2Fuploads%2Fgit-blob-95d8d2d6477c909781f2045a2b1bad8aeb93bb9b%2Fex_nonlinear_resistance_error.png?alt=media" alt=""><figcaption><p><strong>Circuit Topology Causing an Error</strong></p></figcaption></figure>

If you try to simulate this circuit, you may get an error because two nonlinear elements simulated by current sources are connected in series: the Breaker Preview block and the Nonlinear Inductance block.

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

To be able to simulate this circuit, you must provide a current path around one of the two nonlinear blocks. You could, for example, connect a large resistance, say 1 MΩ, across the Breaker Preview block or the Inductance block. In this case, it is more convenient to choose the Breaker Preview block because a series RC snubber circuit is provided with the model.

When implementing nonlinear elements as controlled current or voltage sources, always check allowed circuit topologies. If you encounter algebraic loops or series connections of current-mode nonlinear elements, add an appropriate shunt/parallel path or a small dynamic element (fast transfer function) to break the problematic topology.

{% hint style="info" %}
Using an inductive source impedance (R–L series) instead of a purely resistive impedance would have produced another error message, because the current source modeling the nonlinear inductance would have been in series with an inductance, even with a resistive snubber connected across the breaker.\
In such a case, you could add either a parallel resistance across the source impedance or a large shunt resistance connected between one breaker terminal and the source neutral terminal.
{% endhint %}


---

# 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/get-started/build-and-customize-sps-models.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.
