> 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/simulink-blocks-reference/artemis-library/ssn-jmag-spatial-harmonic-pmsm-block.md).

# SSN JMAG Spatial Harmonic PMSM

## Description

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

The **SSN PMSM-SH** block, located in the **ARTEMiS/SSN/SSn rotating machines** library, implements a 3-phase permanent magnet synchronous machine with inductance and flux provided by JMAG-RT or Maxwell in the form of 3-D tables. The model can also support tables from other companies such as Infolytica and ANSYS with minimum modifications.

{% hint style="danger" %}
This block requires a valid RT-LAB license on the simulator with the feature ARTEMiS enabled. Refer to[ ARTEMiS Requirements](https://www.opal-rt.com/docs/rt-lab/model-and-simulation/power-systems-with-artemis/artemis-requirements.md) for details.
{% endhint %}

### Discretized PMSM-SH Model Theory <a href="#ssnjmagspatialharmonicpmsmblock-discretizedpmsm-shmodeltheory" id="ssnjmagspatialharmonicpmsmblock-discretizedpmsm-shmodeltheory"></a>

The so-called Spatial Harmonic PMSM (SH-PMSM) model is provided by JMAG as tables of inductance and total flux. We derive here the discrete model for the SH-PMSM model.

The **JMAG-RT tables for the SH-PMSM** come in the form of 3-D tables that provides the total flux Ψ, the differential inductance Ldiff and the motor torque as a function of 3 variables: the current amplitude Iamp, the current angle β and the rotor angle, using the orthonormal Park transform to obtain dq-domain values.

$$
\begin{array}{c}
{\left\[\begin{array}{c}
V\_{d s} \\
V\_{q s}
\end{array}\right]=\sqrt{2 / 3}\left\[\begin{array}{ccc}
\cos (\theta) & \sin (\theta) \\
-\sin (\theta) & \cos (\theta)
\end{array}\right]\left\[\begin{array}{ccc}
1 & -0.5 & -0.5 \\
0 & \sqrt{3} / 2 & -\sqrt{3} / 2
\end{array}\right]\left\[\begin{array}{c}
V\_{a s} \\
V\_{b s} \\
V\_{c s}
\end{array}\right]} \\
\qquad I\_{a m p}=\sqrt{\frac{2}{3}\left(i\_{d}^{2}+i\_{q}^{2}\right)} \\
\beta=\frac{180}{\pi} \operatorname{Tan}^{-1}\left(-\frac{i\_{d}}{i\_{q}}\right) \quad \text { (in degrees) }
\end{array}
$$

The inductance table is provided as a 3x3 matrix. It does not assume a specific winding connection but floating-wye is the most common. This inductance Ldiff is the linearized inductance at the point of operation. This linearization as the effect of creating a flux offset Ψo which must be carefully considered.

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

#### Differential equation of the SH-PMSM model <a href="#ssnjmagspatialharmonicpmsmblock-differentialequationofthesh-pmsmmodel" id="ssnjmagspatialharmonicpmsmblock-differentialequationofthesh-pmsmmodel"></a>

$$
\begin{array}{c}
\psi=\psi\_{0}+\psi^{\prime \prime}=\psi\_{0}+L\_{d i f f} \cdot I\_{a b c} \\
\frac{d \psi^{\prime \prime}}{d t}=-\mathrm{R} I\_{a b c}-\frac{\mathrm{d} \psi\_{0}}{\mathrm{dt}}+V\_{a b c}
\end{array}
$$

with Ψ (vector of 3) as the total flux, Ψo (vector of 3) as the flux offset at the point of operation, Ldiff is differential inductance matrix (3x3), that is the local slope of the total flux at the point of operation, Iabc (or *I* in the figure) are the coil currents (vector of 3).

In equations 1-2, one must consider that the null-current magnet flux Ψp (if any, depending on the rotor angle) is included in Ψo. Also note that in a non-saturated PMSM, Ψo = Ψp and Ldiff is constant.

#### Discretization of the model and use into a nodal admittance solver <a href="#ssnjmagspatialharmonicpmsmblock-discretizationofthemodelanduseintoanodaladmittancesolver" id="ssnjmagspatialharmonicpmsmblock-discretizationofthemodelanduseintoanodaladmittancesolver"></a>

A central difference method is applied on equation 2 to obtain the discrete nodal model:

$$
\begin{array}{c}
I\_{a b c(n+1)}=\left(L\_{d i f f(n+1)}+\frac{h R}{2}\right)^{-1}\left{\left(L\_{d i f f(n)}-\frac{h R}{2}\right) I\_{a b c(n)}-\left(\psi\_{0(n+1)}-\psi\_{0(n)}\right) \ldots\right. \\\[8pt]
+\frac{h}{2} \* V\_{a b c(n+1)}+\frac{h}{2} \* V\_{a b c(n)} }
\end{array} \\\[8pt]
$$

With *(n-1),* *(n)* and *(n+1)* representing to time instant separated by the time step length *h*. Flux and inductance values are obtained from the table with a one time-step delay so their time indices could be *(n)* and *(n-1)* instead of *(n+1)* and *(n)* above. In the equation, *V*<sub>*abc*</sub> is the vector of coil voltages, which is different than the node voltages.

The ‘discrete admittance’ of the equation is therefore:

$$
Y=\frac{I\_{a b c(n+1)}}{V\_{a b c(n+1)}}=2 / h\left(L\_{d i f f(n+1)}-\frac{h R}{2}\right)^{-1}
$$

In order to obtain the coil voltages in the floating Y configuration of the PMSM, we have to find the neutral point voltage, and therefore, a system with 4 terminal needs to be created, which a very high impedance to ground on the neutral point.

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

Star-connected PMSM-SH with neutral point as SSN node.

$$
\left\[\begin{array}{cc}
Y & -\sum Y\_{\text {row }} \\
-\sum Y\_{c o l} & \sum \sum\_{Y}
\end{array}\right]\left\[\begin{array}{c}
V\_{a b c} \\
V\_{\text {neutral }}
\end{array}\right]=\left\[\begin{array}{c}
I\_{a b c} \\
i\_{\text {neutral }}
\end{array}\right]+\left\[\begin{array}{c}
\text { Ihist}*{\text {abc }}  \\
\text { Ihist}*{\text {neutral }}
\end{array}\right]
$$

With Ihist<sub>neutral</sub> = -ΣIhist<sub>abc</sub> since all phases are connected together on the neutral side.

### 3-wire model <a href="#ssnjmagspatialharmonicpmsmblock-3-wiremodel" id="ssnjmagspatialharmonicpmsmblock-3-wiremodel"></a>

It is possible to get rid of the neutral node with some gymnastics, and thus hopefully increase the calculation speed by the reduction of the global admittance matrix. The 3-wire model reduction is obtained first by adding the neutral admittance into the extended Y matrix:

$$
Y\_{\text {ext }}=\left\[\begin{array}{cc}
Y & -\sum Y\_{\text {row }} \\
-\sum Y\_{\text {col }} & \left(\sum \sum Y\right)+Y\_{\text {neutral }}
\end{array}\right]
$$

Then I<sub>neutral</sub>=0, we can solve for V<sub>neutral</sub> and the system can be reduced to a 3x3 system, the discrete Norton model being equal to:

$$
Y \cdot \frac{\left(\sum Y\_{\text {row }}\right) \cdot\left(\sum Y\_{\text {col }}\right)}{\left(\sum \sum Y+Y\_{\text {neutral }}\right)} V\_{a b c}=I\_{a b c}+\text { Ihist}*{a b c}+\frac{\sum Y*{\text {row }}}{\left(\sum \sum Y+Y\_{\text {neutral }}\right)} \text { Ihist}\_{a b c}
$$

The neutral voltage, still required to find the coil voltages, is equal to:

$$
V\_{\text {neutral }}=\frac{\left(\sum Y\_{\text {col }}\right) V\_{a b c}+\sum \text { Ihist}*{a b c}}{\left(\sum \sum Y+Y*{\text {neutral }}\right)}
$$

{% hint style="danger" %}
This block requires a valid ARTEMiS license on the simulator. Refer to[ ARTEMiS Requirements](https://www.opal-rt.com/docs/rt-lab/model-and-simulation/power-systems-with-artemis/artemis-requirements.md) for details.
{% endhint %}

## Mask parameters

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

<table><thead><tr><th width="255.60003662109375">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong>Motor data file</strong></td><td>JMAG-RT .rtt or .json data file (entered with ' ' )</td></tr><tr><td><strong>Motor data file type</strong></td><td>choice of .json (Maxwell), .rtt (JMAG-RT) or mat-file.</td></tr><tr><td><strong>Mechanical offset angle</strong></td><td>Mechanical angle offset of the rotor in degrees (deg).</td></tr><tr><td><strong>Sample Time</strong></td><td>Sample time of the model in seconds (s)</td></tr></tbody></table>

## Conserving ports

<table><thead><tr><th width="210.800048828125">Port</th><th>Description</th></tr></thead><tbody><tr><td><strong>a</strong></td><td>Stator phase a connection point.</td></tr><tr><td><strong>b</strong></td><td>Stator phase b connection point.</td></tr><tr><td><strong>c</strong></td><td>Stator phase c connection point.</td></tr><tr><td><strong>N</strong></td><td>The star neutral point (4-wire model only). This point should always be connected to a high impedance to the ground (ex: 1e8 Ohms).</td></tr></tbody></table>

## Inputs

This block has no inputs.

## Outputs

<table><thead><tr><th width="210">Name</th><th>Description</th></tr></thead><tbody><tr><td><strong>SHdata</strong></td><td><p>Simulink bus containing the following signals:</p><ul><li>Rs: stator resistance in Ohms (3x3 matrix).</li><li>Te: electric torque in N.m.</li><li>dphi0/dt: apparent back-EMF of the motor at the point of operation in Volts, mechanical speed of the machine in rad/s. This speed is usually computed from a mechanical model that includes the machine and other devices torques and inertias.</li><li>Iabc: ABC terminal currents in Amperes.</li></ul></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/rt-lab/simulink-blocks-reference/artemis-library/ssn-jmag-spatial-harmonic-pmsm-block.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.
