> 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/pe-add-on-simulink/examples/scim-with-saturation.md).

# SCIM with Saturation

## Description

The **SCIM With Saturation** example demonstrates the effects of saturation on the **IM with Saturation** machine model.

The example is available as VeriStand projects providing support for the PXIe-7868R FPGA card.

## Detailed explanation

Two identical squirrel-cage induction machines are simulated, one with typical saturation characteristics and the other without saturation.

Both machines are powered by the same three-phase voltage source simulated using the built-in FPGA **Sinewave Generators**. At the output of the machines, the amplitudes of their respective A, B, and C phase currents are measured and compared to observe the effects of saturation on the model.

<figure><img src="https://2999842053-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fe9Kk9pJCHht2LLBSxPap%2Fuploads%2FQLn42orXltJEKuSpuVoS%2Fimage.png?alt=media&amp;token=4f13c509-0c4b-42b8-af4c-563a41367445" alt=""><figcaption><p><em>SCIM_eHS_Passthrough circuit model</em></p></figcaption></figure>

## Configuration

<details>

<summary><strong>Hardware Configuration</strong></summary>

* In the Configuration Tree, expand **Controller >> Custom Devices** and click the **Power Electronics Add-On** custom device to open its configuration page.
* The **eHSx64\_Quad\_IM\_Saturation\_IO\_7868R** hardware configuration is selected in the **Configuration** dropdow&#x6E;**.**

<figure><img src="https://2999842053-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fe9Kk9pJCHht2LLBSxPap%2Fuploads%2FZDBWGcdcSj6Z1T3rQybh%2Fimage.png?alt=media&amp;token=b6048948-cd36-4487-8f96-a46126e3aaa7" alt="" width="563"><figcaption></figcaption></figure>

</details>

<details>

<summary><strong>Circuit Model</strong></summary>

The **Circuit Model** in this example serves as a simple three-phase voltage source for the machines. The **Sources** are controlled by the same set of three **Sinewave Generators**, while the phase voltage **Measurements** are mapped to the voltage inputs of both **IM with Saturation** machine models.

* In the Configuration Tree, expand **Power Electronics Add-On** and click **Circuit Model.**
* The **Circuit Model File Path** points to the currently loaded Circuit Model. Open the file in Simulink to observe the circuit.

**Circuit Model File Path:** *\<SCIM With Saturation>\Circuit Model\SCIM\_eHS\_Passthrough.slx*

<figure><img src="https://2999842053-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fe9Kk9pJCHht2LLBSxPap%2Fuploads%2FHWepshl3rMFPKFyzK3v3%2Fimage.png?alt=media&amp;token=750841d9-3176-48df-91eb-ae7b26c0b78f" alt="" width="563"><figcaption></figcaption></figure>

</details>

<details>

<summary><strong>Sources</strong></summary>

The **Sources page** maps signals to each source of the circuit model. In this example, the machine phase currents are fed back to the circuit. The six AC voltage sources are controlled using three **Sinewave Generators**.

* In the Configuration Tree, expand **Circuit Model** and click **Sources**. This page is populated with a list of sources from the circuit model.
* The mappings are configured as shown below.

<figure><img src="https://2999842053-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fe9Kk9pJCHht2LLBSxPap%2Fuploads%2FgLPbuemPnok8cM84jwcH%2Fimage.png?alt=media&amp;token=fa7f5ff1-acaa-47c5-bdce-0c03f468ba9f" alt="" width="563"><figcaption></figcaption></figure>

</details>

<details>

<summary><strong>Switches</strong></summary>

The **Switches page** maps signals to each switch of the circuit model. In this example, a single dummy switch is used to meet the minimum requirements of the eHS solver. The switch mapping configuration does not affect the results of the simulation.

* In the Configuration Tree, expand **Circuit Model** and click **Switches**. This page is populated with a list of switches from the circuit model.
* The mappings are configured as shown below; any **Group** and **Element** can be mapped to the switch.

<figure><img src="https://2999842053-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fe9Kk9pJCHht2LLBSxPap%2Fuploads%2FpRhnn5VfkR5puDOjA57f%2Fimage.png?alt=media&amp;token=dd2811ec-f901-417d-b323-04f939aa7415" alt="" width="563"><figcaption></figcaption></figure>

</details>

<details>

<summary><strong>Machine model</strong></summary>

In this example, two **IM with Saturation** models are configured using identical electrical parameters, but different Magnetizing Inductance files. The first model simulates an induction machine with a typical saturation profile, while the second model simulates a standard induction machine with no saturation.

* In the configuration tree, expand **Circuit Model** and click **IM with Saturation 1** and **IM with Saturation 2** to open the configuration pages for the machines.
* A different **Magnetizing Inductance File Path** is configured for each of the two machines:
  * **IM with Saturation 1:** *\<SCIM With Saturation>\Magnetizing Inductance\MagnetizingInductance\_withSaturation.json*
  * **IM with Saturation 2:** *\<SCIM With Saturation>\Magnetizing Inductance\MagnetizingInductance\_withoutSaturation.json*

The other **Machine Configuration** parameters and the **Input Mapping Configuration** parameters of both machines are configured identically, as summarized below.

| Machine Configuration parameter                  | Value                           |
| ------------------------------------------------ | ------------------------------- |
| **Machine Type**                                 | Squirrel-Cage Induction Machine |
| **Stator Resistance (Ohm)**                      | 0.087                           |
| **Stator Leakage Inductance (H)**                | 0.000801061                     |
| **Rotor Resistance (Ohm)**                       | 0.228                           |
| **Rotor Leakage Inductance (H)**                 | 0.000801061                     |
| **Pole Pairs**                                   | 2                               |
| **Magnetizing Inductance Cutoff Frequency (Hz)** | 3000                            |
| **Synchronous Reference Frame Orientation**      | Stator Flux                     |
| **Synchronous Reference Frame Offset (Deg)**     | 0                               |
| **Stator Rotor Turn Ratio**                      | 1                               |
| **Rotor Temperature Coefficient**                | 0                               |
| **Stator Temperature Coefficient**               | 0                               |

| Input Mapping Configuration                       | Value                   |
| ------------------------------------------------- | ----------------------- |
| **Stator Voltage Phase A** (IM with Saturation 1) | Circuit Model 1.Va\_l-n |
| **Stator Voltage Phase B** (IM with Saturation 1) | Circuit Model 1.Vb\_l-n |
| **Stator Voltage Phase C** (IM with Saturation 1) | Circuit Model 1.Vc\_l-n |
| **Stator Voltage Phase A** (IM with Saturation 2) | Circuit Model 1.Vx\_l-n |
| **Stator Voltage Phase B** (IM with Saturation 2) | Circuit Model 1.Vy\_l-n |
| **Stator Voltage Phase C** (IM with Saturation 2) | Circuit Model 1.Vz\_l-n |

<figure><img src="https://2999842053-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fe9Kk9pJCHht2LLBSxPap%2Fuploads%2FKjggapo1Igx7OBF3T5rN%2Fimage.png?alt=media&amp;token=e540eced-6348-44cf-ab57-2d8200216272" alt="" width="563"><figcaption></figcaption></figure>

#### For the mechanical model <a href="#mechanical-model" id="mechanical-model"></a>

* In the configuration tree, expand **IM with Saturation 1** and **IM with Saturation 2**, then click **Mechanical Model** to view their respective mechanical model parameters.
* In the configuration tree, expand each **Mechanical Model** and click the **Mechanical Model Mode** channel. The **Default Value** of each **Mechanical Model Mode** channel is set to 1 (Torque Controlled).

The **Initial Values** and **Configuration** parameters are configured as summarized below.

| Mechanical Model - Configuration parameter | Value |
| ------------------------------------------ | ----- |
| **Viscous Damping**                        | 0.006 |
| **Static Friction**                        | 0     |
| **Inertia**                                | 1.662 |

| Mechanical Model - Initial Values | Value |
| --------------------------------- | ----- |
| **Initial Rotor Angle (Deg)**     | 1     |

<figure><img src="https://2999842053-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fe9Kk9pJCHht2LLBSxPap%2Fuploads%2FVcrFXn2yUprGMxPRzlFc%2Fimage.png?alt=media&amp;token=94d7b86d-c3e9-4d75-8360-efd9c9e6e86f" alt="" width="563"><figcaption></figcaption></figure>

</details>

<details>

<summary><strong>Sinewave Generators</strong></summary>

In this example, the FPGA-based **Sinewave Generators** drive the six AC voltage sources of the **Circuit Model**.

* In the configuration tree, expand **Circuit Model** and click **Sinewave Generators**.
* The default channel values for **SWG 0**, **SWG 1**, and **SWG 2** are configured as summarized below.

| Frequency Engines - Channel Name | Default Value |
| -------------------------------- | ------------- |
| **Frequency Engine 0**           | 60Hz          |

| SWG 0 - Channel Name | Default Value |
| -------------------- | ------------- |
| **Frequency Engine** | 0             |
| **Phase**            | 0º            |
| **Amplitude**        | 460 V         |

| SWG 1 - Channel Name | Default Value |
| -------------------- | ------------- |
| **Frequency Engine** | 0             |
| **Phase**            | -120º         |
| **Amplitude**        | 460 V         |

| SWG 2 - Channel Name | Default Value |
| -------------------- | ------------- |
| **Frequency Engine** | 0             |
| **Phase**            | 120º          |
| **Amplitude**        | 460 V         |

<figure><img src="https://2999842053-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fe9Kk9pJCHht2LLBSxPap%2Fuploads%2FfG7wD2QEQNNasGxIMgYt%2Fimage.png?alt=media&amp;token=a4e75b2c-6561-4bbd-98cf-86dcb79696d5" alt="" width="563"><figcaption></figcaption></figure>

</details>

<details>

<summary><strong>Waveform Channels</strong></summary>

**Waveform Channels** allow signals to be streamed from the FPGA at a rate faster than that of the CPU execution.

* In the Configuration Tree, expand **Circuit Model** and click **Waveforms**.
* The signals in the example are mapped to the Waveform channels as shown below. The data from these channels will be streamed at the **Sample Rate (S/s)** specified at the bottom of the page.

<figure><img src="https://2999842053-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fe9Kk9pJCHht2LLBSxPap%2Fuploads%2FMeVcywkXnWG5ZzlseLSv%2Fimage.png?alt=media&amp;token=5aa4eebe-346e-4e0d-b0cf-ebbe59c2610a" alt="" width="563"><figcaption></figcaption></figure>

</details>

## Simulation

Open *Main.nivsscr* and monitor the **Stator Phase Currents** and **Speed** of both machines. Manipulate the **Supply Voltage** and observe its effects on the output signals.

<figure><img src="https://2999842053-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fe9Kk9pJCHht2LLBSxPap%2Fuploads%2F91ErR6y6eMEfudaxCLA0%2Fimage.png?alt=media&amp;token=0f7500f3-5acf-40d4-a5e7-11c460c8bfb9" alt=""><figcaption><p>Comparison of the machine <strong>Phase Currents</strong> and <strong>Speed</strong> with a <strong>Supply Voltage</strong> of 460V.</p></figcaption></figure>

### Interpreting the Results <a href="#interpreting-the-results" id="interpreting-the-results"></a>

This example can be used to validate the saturation parameters defined in the **Magnetizing Inductance File**. By manipulating the **Supply Voltage**, we can observe the phase currents output by the saturated machine model at various operating points along the saturation curve. A second machine with linear parameters is also simulated to help compare the effects of a machine with no saturation.

The table and graph below summarize the saturation parameters defined in the Magnetizing Inductance File, as well as the results obtained from the saturated machine model. Note that the measured phase currents obtained from the simulation are peak values, while the currents defined in the Magnetizing Inductance File are RMS values.

| Saturation Parameters - Supply Voltage (Vrms L-L) | Saturation Parameters - No Load Stator Current (Arms) | Saturation Parameters - No Load Stator Current (Apeak) | Simulation Measurements - Peak Stator Phase Current (Apeak) |
| ------------------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------ | ----------------------------------------------------------- |
| 230                                               | 9.9249                                                | 14.03592819                                            | 13.9                                                        |
| 322                                               | 19.6672                                               | 27.81362097                                            | 28                                                          |
| 414                                               | 38.0377                                               | 53.79343122                                            | 53.7                                                        |
| 460                                               | 51.3988                                               | 72.68888005                                            | 72.75                                                       |
| 506                                               | 69.2824                                               | 97.98010971                                            | 97.47                                                       |
| 552                                               | 105.1337                                              | 148.6815044                                            | 148.16                                                      |
| 598                                               | 152.5532                                              | 215.7428044                                            | 214.97                                                      |
| 644                                               | 214.2421                                              | 302.9840835                                            | 301.27                                                      |
| 690                                               | 302                                                   | 427.0924958                                            | 423.05                                                      |

<figure><img src="https://2999842053-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fe9Kk9pJCHht2LLBSxPap%2Fuploads%2FzeRDyD2i0jaa1MrOUcKM%2Fimage.png?alt=media&amp;token=345f6d63-6c7c-491b-aede-106df19a3d86" alt=""><figcaption><p>Comparison of the saturation parameters defined for the machine model and the simulation results.</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/pe-add-on-simulink/examples/scim-with-saturation.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.
