> 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/ehs/model-in-schematic-editor/library-blocks-reference/machines-blocks/permanent-magnet-synchronous-machine-3-phase.md).

# Permanent Magnet Synchronous Machine 3-phase

## Description

<figure><img src="https://3212678799-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FABuoXNYgvaoO7wIe3bfO%2Fuploads%2Fgit-blob-52b48b103c3fc61d59013a90c86d277c877abc87%2FSE_PMSM-3Pblock.png?alt=media" alt="" width="226"><figcaption></figcaption></figure>

The **Permanent Magnet Synchronous Machine 3-phase** block implements a three-phase permanent magnet synchronous machine (PMSM) with optional resolver and encoder models. It supports **Constant DQ**, **Variable DQ**, and **Spatial Harmonics SH** configurations.

The model uses an orthonormal (power-invariant) Park transform for analysis and control, and provides active/reactive power calculation. On FPGA implementations, low-pass filters are applied to improve signal visualization and numerical behavior.

{% hint style="info" %}
This block is only available in the eHS library.
{% endhint %}

### **Equations & Characteristics** <a href="#equations-and-characteristics" id="equations-and-characteristics"></a>

The equation of the PMSM model can be expressed as follows:

$$
I\_{abc} = \[L\_{abc}(\theta)]^{-1} \left\[ \int (V\_{abc} - R I\_{abc}) , dt - \psi\_{abc} \right] \\\[8pt]
$$

where **L**<sub>**abc**</sub> is the time-varying inductance matrix (global inductance for DQ and VDQ models), **I**<sub>**abc**</sub> is the stator current inside the winding, **R** is the stator resistance and **V**<sub>**abc**</sub> is the voltage across the stator windings. As for **ψ**<sub>**abc**</sub>, it defines the magnet flux linked into the stator windings (for DQ and VDQ models), or the total flux (for the SH model).

### Standard DQ motor characteristics <a href="#standard-dq-motor-characteristics" id="standard-dq-motor-characteristics"></a>

In normal conditions, the ideal sinusoidal stator voltages of the PMSM, back-EMFs, and inductances all have sinusoidal shapes. One can transform the equation using the Park transformation with a referential locked on the rotor position **θ** using the following equations.

$$
\begin{bmatrix}
V\_{ds} \\
V\_{qs}
\end{bmatrix}
=============

T
\begin{bmatrix}
V\_{as} \\
V\_{bs} \\
V\_{cs}
\end{bmatrix}
\\\[8pt]

T = \sqrt{2/3}
\begin{bmatrix}
\cos(\theta) & \sin(\theta) \\
-\sin(\theta) & \cos(\theta)
\end{bmatrix}
\begin{bmatrix}
1 & -0.5 & -0.5 \\
0 & \sqrt{3}/2 & -\sqrt{3}/2
\end{bmatrix}
\\\[8pt]
$$

The Park transform (also called ‘DQ’ transform) reduces sinusoidal varying quantities of inductances, flux, current, and voltage to constant values in the D-Q frame thus greatly facilitating the analysis and control of the device under study.

It is important to note that there are many different types of Park transforms and this often leads to confusion when interpreting the motor states inside the D-Q frame. The one used here presents the advantage of being orthonormal (notice the √*3/2* factor). This particular Park orthonormal transform is power-invariant which means that the power computed in the D-Q frame by performing a dot product of currents and voltages will be numerically equal to the one computed in the phase domain. With this transform (and only this transform) the PMSM torque can be expressed by (3), where ***pp*** is the **number of pole pairs**.

$$
T\_{e} = pp \left\[ \sqrt{\tfrac{3}{2}}, \psi\_{M}, i\_{q} ;+; (L\_{d} - L\_{q}), i\_{d}, i\_{q} \right] \\\[8pt]
$$

One may notice the absence of the 3/2 factor in (3), which is usually present in the PMSM torque equation when using non-orthonormal transforms. This is, again, because this model uses the orthonormal Park transform. Figure 1 explains the principle of the Park transform. Considering fixed ABC referential with all quantities (***V***<sub>***bemf***</sub>, *motor current **I***) rotating at the electric frequency **ω**, if we observe these quantities in a D-Q frame turning at the same speed we can see that the motor quantities will be constant.

This is easy to see for the Back-EMF voltage ***V***<sub>***bemf***</sub> that directly follows the Q-axis (because the magnet flux is on the D-axis by definition). In Figure 3, ***I*** leads and the Q-axis by an angle called **β** (beta). The modulus of the vector ***I*** is called ***I***<sub>***amp***</sub>. In the figure below, **θ** is the rotor angle, aligned with the D-axis.

The Vd and Vq are not calculated directly inside the blackbox. But using P and Q could estimate Vd and Vq using the following equations since Instantaneous calculated P and Q in the phase domain are equivalent to instantaneous calculated P and Q in the DQ domain.

$$
P = V\_d \* I\_d + V\_q \* I\_q \\\[8pt]

Q = V\_q \* I\_d - V\_d \* I\_q \\\[8pt]

V\_d = (P \* I\_d - Q \* I\_q)/(I\_d^2 + I\_q^2) \\\[8pt]

V\_q = (P \* I\_q + Q \* I\_d)/(I\_d^2 + I\_q^2)
$$

### Mechanical model

The equation of the mechanical model in torque mode can be expressed as follows

$$
\omega\_r\left\[k+1\right]=a \times \omega\_r\left\[k\right]+b \times \left(T\_{e}\left\[k\right]-T\_{l}\left\[k\right]-T\_{f,s}\left\[k\right]\right)
$$

with

$$
a=1-\frac{F\_vT\_S}{J} \\\[8pt]
b=\frac{30}{\pi}\frac{T\_S}{J} \\\[8pt]
$$

where $$\omega\_r$$ is the rotor speed in RPM, $$T\_e$$ is the electromagnetic torque in $$N.m$$, $$T\_i$$ is the torque command in $$N.m$$, $$F\_v$$ is the viscous friction coefficient in $$N.m.s/rad$$, $$J$$ is the rotor moment of inertia in $$kg.m^2$$, and $$T\_s$$ the time step in $$s$$. There is a dead-zone implementation with the static friction torque $$T\_{f,s}$$, if the net torque doesn't exceed the static friction torque threshold value $$F\_s$$, given in $$N.m$$, the speed remains zero.

In speed mode, the rotor speed is directly set to the speed command $$\omega\_{r,c}$$.

### FPGA Implementation <a href="#fpga-implementation" id="fpga-implementation"></a>

Since the simulation is performed on FPGA hardware, the block implements a low pass filter on **V**<sub>**abc**</sub> of stator set at 1000 Hz to help visualize the voltage. Because the original traces are square-like, it is harder to figure out the trace of **V**<sub>**abc**</sub> without the filter.

The FPGA block also implements a low-pass filter that is used to remove high harmonics of the DQ currents from accessing the table, which could make the model stiffer. Its default cut-off frequency is set at 200 Hz, but it can be adjusted by the parameter “TableInputCutoffFrequency“ in the json parameter file (see **PMSM files parameters** section).

The block also calculates the active and reactive power consumed by the machine. This calculation uses the unfiltered voltage inputs and the computed phase currents. The resulting power values are then filtered using a low-pass filter with a cutoff frequency of 200 Hz.

A resolver is a rotary transformer where the magnitude of the signal through the resolver windings varies sinusoidally as the shaft rotates.

## Single excitation resolver <a href="#single-excitation-resover" id="single-excitation-resover"></a>

The equations of the resolver can be expressed as follows:

$$
\theta\_{res}=\left(\theta\_{mec}+\theta\_{offset}\right) R\_{pp} \\\[8pt]
\text{cosine}=\text{Excitation} \times \left\[ R\_{cc} \cos \left( \theta\_{res} \right) + R\_{cs} \sin \left( \theta\_{res} \right) \right] \\\[8pt]
\text{sine}= \left(-1\right)^{R\_{dir}} \times \text{Excitation} \times \left\[ R\_{sc} \cos \left( \theta\_{res} \right) + R\_{ss} \sin \left( \theta\_{res} \right) \right]
$$

where $$\theta\_{res}$$ is the resolver angle, $$\theta\_{mec}$$ is the mechanical angle of the machine, $$\theta\_{offset}$$ is the angle offset, $$R\_{pp}$$ is the number of pole pairs of the resolver, $$R\_{cc}$$, $$R\_{sc}$$, $$R\_{cs}$$, and $$R\_{ss}$$ are the resolver sine cosine gains and $$R\_{dir}$$ is the direction of the sensor rotation (0 = clockwise, 1 = counterclockwise).

{% hint style="info" %}
$$R\_{dir}$$ does not have an effect to the resolver angle, but change the resolver sine sign to match the counterclockwise convention.
{% endhint %}

When the gains are set to its default values ( $$R\_{cc}=1$$, $$R\_{sc}=0$$, $$R\_{cs}=0$$, and $$R\_{ss}=1$$), the sensor rotation is clockwise, and the excitation is a sinusoidal wave ( $$\text{Excitation}=\sin 2 \pi f t$$, where $$f$$ is the excitation frequency), the outputs are given by the following expressions:

$$
\text{cosine}=\sin \left( 2 \pi f t \right) \times \cos \left( \theta\_{res} \right) \\\[8pt]
\text{sine}= \sin \left( 2 \pi f t \right) \times \sin \left( \theta\_{res} \right)
$$

It means the excitation signals are modulated by the sine and cosine of the rotor position angle.

## **Excitation source**

The excitation signal can be selected among one of the following options:

* DC: a continuous signal is used as excitation, so the outputs are $$\text{cosine}= \cos \left( \theta\_{res} \right)$$ and $$\text{sine}= \sin \left( \theta\_{res} \right)$$;
* AC: a constant-frequency sinusoidal, unitary amplitude waveform is used as excitation

  $$\text{Excitation}=\sin 2 \pi f t$$, so the outputs are those expressed in the previous section.
* External: a external signal, coming from one of the analog inputs, is used as excitation. This incoming signal may be rescaled by the Analog Input Differential Rescaling module (AIR).

## **Resolver gains**

The resolver gains can be used to simulate non-ideal conditions of the sensor, occurring due to manufacturing imperfections.

**Amplitude imbalance:** Output phases have unequal inductances. Assuming the coupling between the rotor excitation winding and the cosine winding as the reference:

$$
\begin{aligned}
\left\[\begin{matrix}R\_{cc} & R\_{cs}\R\_{sc} & R\_{ss}\end{matrix}\right]
\end{aligned}=\begin{aligned}
\left\[\begin{matrix}1 & 0\0 & \alpha\end{matrix}\right]
\end{aligned}
$$

where $$0< \alpha <1$$

**Imperfect quadrature:** Output phases are not in perfect spatial quadrature. Assuming the angle $$\theta\_{res}=0$$ when the rotor excitation winding is aligned with the cosine winding:

$$
\begin{aligned}
\left\[\begin{matrix}R\_{cc} & R\_{cs}\R\_{sc} & R\_{ss}\end{matrix}\right]
\end{aligned}=\begin{aligned}
\left\[\begin{matrix}1 & 0\ \cos \alpha & \sin \alpha\end{matrix}\right]
\end{aligned}
$$

where $$\alpha$$ is the angle between the cosine winding and the sine winding. When $$\alpha = 90°$$, the windings are in perfect quadrature, and the default gain values are recovered.

## **Faults**

One of the windings is not connected due to a fault. In this case, the corresponding gain is equal to zero.

<p align="center"><span class="math">\begin{aligned} \left[\begin{matrix}R_{cc} &#x26; R_{cs}\\R_{sc} &#x26; R_{ss}\end{matrix}\right] \end{aligned}=\begin{aligned} \left[\begin{matrix}1 &#x26; 0\\ 0 &#x26; 0\end{matrix}\right] \end{aligned} \text{ or }\begin{aligned} \left[\begin{matrix}R_{cc} &#x26; R_{cs}\\R_{sc} &#x26; R_{ss}\end{matrix}\right] \end{aligned}=\begin{aligned} \left[\begin{matrix}0 &#x26; 0\\ 0 &#x26; 1\end{matrix}\right] \end{aligned}</span></p>

## **Excitation time shift**

When the excitation signal comes from an external source (one of the analog input channels) the signal can be shifted by a given amount of time.

Some resolvers have two rotor windings at 90º degrees to each other, as represented in this figure.

For the double excitation resolver, the equations can be expressed as follows:

$$
\text{cosine}=\text{Excitation}*1 \times \left\[ R*{cc,1} \cos \left( \theta\_{res} \right) + R\_{cs,1} \sin \left( \theta\_{res} \right) \right] \\\[4pt]+ \text{Excitation}*2 \times \left\[ R*{cc,2} \cos \left( \theta\_{res} \right) + R\_{cs,2} \sin \left( \theta\_{res} \right) \right] \\\[8pt]
$$

$$
\text{sine}= (-1)^{R\_{dir}} \Big( \text{Excitation}*1 \times \left\[ R*{sc,1} \cos \left( \theta\_{res} \right) + R\_{ss,1} \sin \left( \theta\_{res} \right) \right] \\\[4pt]+ \text{Excitation}*2 \times \left\[ R*{sc,2} \cos \left( \theta\_{res} \right) + R\_{ss,2} \sin \left( \theta\_{res} \right) \right] \Big) \\\[8pt]
$$

When the gains are set to its default values:

$$R\_{cc,1}=0, R\_{sc,1}=0, R\_{cs,1}=0, R\_{ss,1}=0, R\_{cc,2}=1, R\_{sc,2}=0, R\_{cs,2}=0 \text{ and } R\_{ss,2}=-1$$

the sensor rotation is clockwise, and the excitations are in quadrature ( $$\text{Excitation}\_1=\sin 2 \pi f t$$ and $$\text{Excitation}\_2=\sin\left(2\pi ft+\frac{\pi}{2}\right)=\cos\left(2\pi ft\right)$$, where $$f$$ is the excitation frequency), the outputs are given by the following expressions:

$$
\text{cosine}=\sin \left( 2 \pi f t \right) \times \sin \left( \theta\_{res} \right) + \cos \left( 2 \pi f t \right) \times \cos \left( \theta\_{res} \right) = \cos \left( 2 \pi f t - \theta\_{res} \right) \\\[8pt]
\text{sine} = \sin \left( 2 \pi f t \right) \times \cos \left( \theta\_{res} \right) - \cos \left( 2 \pi f t \right) \times \sin \left( \theta\_{res} \right) = \sin \left( 2 \pi f t - \theta\_{res} \right)
$$

which means the excitation signals are shifted by the rotor position angle.

**Excitation source:** For the double excitation resolver, the excitation source can be selected between an internally generated AC signal or an external one, as described for the single excitation. When the AC option is selected, the signals have unit amplitude, constant frequency, and are in quadrature, with the second excitation leading by 90 degrees.

Number of resolver pole pairs affects the number of electrical turns per mechanical turns.

Resolver sine cosine gains affect the sine (first axis) and cosine (second axis) modulation output. Default values set to 1, 0, 0, 1 make it so the sine modulation has a sine form and the cosine modulation has a cosine form. If set to 0, 1, 1, 0, the sine modulation would have a cosine and the cosine modulation would have a sine form.

Number of pulses per revolution (**Q**<sub>**ppr**</sub>) defines how many times signals A and B pulse between two Z pulses (one full rotation).

Direction of the sensor rotation describes if A leads B (Clockwise) or if B leads A (Counterclockwise)

## Parameters

{% tabs %}
{% tab title="Electrical" %}

<table><thead><tr><th width="180">Parameter</th><th width="310">Description</th><th width="100">Sets feature</th><th width="120">I/O &#x26; Monitoring</th></tr></thead><tbody><tr><td><strong>Motor configuration type</strong></td><td>Type of motor: three options: <strong>Constant DQ</strong>, <strong>Variable DQ</strong>, or <strong>Spatial Harmonics</strong>.<br>In Variable DQ and Spatial Harmonics mode, electrical input parameters are hidden and a resource file must be provided.</td><td>No</td><td>N/A</td></tr><tr><td><strong>Motor configuration M</strong><sub><strong>file</strong></sub></td><td>Only visible in Variable DQ and Spatial Harmonics modes.<br>Imports a Variable DQ (.json file) or Spatial Harmonics (.pmsmsh file) motor configuration resource file</td><td>No</td><td>N/A</td></tr><tr><td><strong>Stator resistances R</strong><sub><strong>S</strong></sub></td><td>In Constant DQ mode:<br>Resistances of the stator windings for phases a, b, and c (Ω).</td><td>No</td><td>N/A</td></tr><tr><td><strong>Stator inductances L</strong><sub><strong>S</strong></sub></td><td>In Constant DQ mode:<br>d- and q-axis inductances (H).</td><td>No</td><td>N/A</td></tr><tr><td><strong>Back EMF profile</strong></td><td>Profile of the back EMF<br>Two options: Sinusoidal or User defined.</td><td>No</td><td>N/A</td></tr><tr><td><strong>Back EMF profile table</strong></td><td>Only visible in back EMF User defined mode.<br>Imports a back EMF resource file.</td><td>No</td><td>N/A</td></tr><tr><td><strong>Permanent magnet flux linkage λ</strong><sub><strong>m</strong></sub></td><td>In Constant DQ mode:<br>Amplitude of the rotor permanent magnet flux λ<sub>m</sub>(Wb).</td><td>No</td><td>N/A</td></tr><tr><td><strong>Number of pole pairs pp</strong></td><td>In Constant DQ mode:<br>Number of pole pairs.</td><td>No</td><td>N/A</td></tr><tr><td><strong>Stator currents i</strong><sub><strong>S</strong></sub></td><td>Currents measured at phases a, b, and c of the stator (A)</td><td>No</td><td><p>To model<br>To AO</p><p>To SFP<br>To Waveform</p></td></tr><tr><td><strong>Stator currents (DQ)</strong> <strong>i</strong><sub><strong>sdq</strong></sub></td><td>Currents measured of axis d and q</td><td>No</td><td>To model<br>To AO<br>To SFP<br>To Waveform</td></tr><tr><td><strong>Stator voltages V</strong><sub><strong>s</strong></sub></td><td>Voltages measured at phases a, b, and c of the stator</td><td>No</td><td>To model<br>To AO<br>To SFP<br>To Waveform</td></tr><tr><td><strong>Back EMF voltages B</strong><sub><strong>emf</strong></sub></td><td>Phase to neutral voltage generated from the permanent magnet flux linkage</td><td>No</td><td>To model<br>To AO<br>To SFP<br>To Waveform</td></tr><tr><td><strong>Active power (3ph, instantaneous) P</strong></td><td>Instantaneous electrical active power (W)</td><td>No</td><td>To model<br>To AO<br>To SFP<br>To Waveform</td></tr><tr><td><strong>Reactive power (3ph, instantaneous) Q</strong></td><td>Instantaneous electrical reactive power (VAr)</td><td>No</td><td>To model<br>To AO<br>To SFP<br>To Waveform</td></tr><tr><td><strong>Electrical rotor position θ</strong><sub><strong>e</strong></sub></td><td>Position of the rotor from 0 to 360 degrees</td><td>No</td><td>To model<br>To AO<br>To SFP<br>To Waveform</td></tr><tr><td><strong>Snubber resistance R</strong><sub><strong>S</strong></sub></td><td>Snubber resistances on phases a, b, and c (Ω).</td><td>No</td><td>N/A</td></tr><tr><td><strong>Snubber capacitance C</strong><sub><strong>S</strong></sub></td><td>Snubber capacitances on phases a, b, and c (F).</td><td>No</td><td>N/A</td></tr></tbody></table>
{% endtab %}

{% tab title="Mechanical" %}

<table><thead><tr><th width="180">Parameter</th><th width="310">Description</th><th width="100">Stets feature</th><th width="120">I/O &#x26; Monitoring</th></tr></thead><tbody><tr><td><strong>J Rotor inertia</strong></td><td>Rotor moment of inertia available only in Torque mode (kg·m<sup>2</sup>)</td><td>No</td><td>N/A</td></tr><tr><td><strong>F</strong><sub><strong>s</strong></sub><strong> Static friction torque</strong></td><td>Static friction torque (N·m)</td><td>No</td><td>N/A</td></tr><tr><td><strong>F</strong><sub><strong>v</strong></sub><strong> Viscous friction coefficient</strong></td><td>Viscous friction available only in Torque mode (N·m·s/rad)</td><td>No</td><td>N/A</td></tr><tr><td><strong>ctrl Mechanical control mode</strong></td><td><p>Options: Speed or Torque.</p><p>In <strong>Speed (0) mode</strong>, the mechanical model is bypassed and the speed command is applied directly.<br>In <strong>Torque (1) mode</strong>, the torque command drives the mechanical model to compute speed.</p></td><td>Yes</td><td>From model</td></tr><tr><td><strong>T Torque command</strong></td><td>Torque command to the mechanical model (N·m)</td><td>Yes</td><td>From model</td></tr><tr><td><strong>ω</strong><sub><strong>r0</strong></sub><strong> Initial rotor speed command</strong></td><td>Initial rotor speed setpoint (rpm)</td><td>No</td><td>N/A</td></tr><tr><td><strong>ω</strong><sub><strong>rc</strong></sub><strong> Rotor speed command</strong></td><td>Rotor speed command to the mechanical model (rpm)</td><td>Yes</td><td>From model</td></tr><tr><td><strong>Rotor speed, ω</strong><sub><strong>r</strong></sub></td><td>Mechanical rotor speed (rpm)</td><td>No</td><td>To model<br>To AO<br>To Waveform</td></tr><tr><td><strong>θ</strong><sub><strong>0</strong></sub><strong> Initial rotor angle</strong></td><td>Rotor position at time t = 0 (°)</td><td>No</td><td>N/A</td></tr><tr><td><strong>Rotor angle, θ</strong></td><td>Mechanical rotor angle (0–360°) (°)</td><td>No</td><td>To model<br>To AO<br>To Waveform</td></tr></tbody></table>
{% endtab %}

{% tab title="Resolver" %}

<table><thead><tr><th width="180">Parameter</th><th width="310">Description</th><th width="100">Sets feature</th><th width="1205">I/O &#x26; Monitoring</th></tr></thead><tbody><tr><td><strong>Enable resolver Ren</strong></td><td><p><strong>Disable</strong> the resolver.</p><p><strong>Enable</strong> the resolver, the following parameters are displayed.</p></td><td>No</td><td>N/A</td></tr><tr><td><strong>Resolver feedback signals R</strong><sub><strong>sc</strong></sub></td><td>Resolver sine and cosine feedback signals proportional to the angle.</td><td>No</td><td>To model<br>To AO<br>To SFP<br>To Waveform</td></tr><tr><td><strong>R</strong><sub><strong>pp</strong></sub><strong> Number of resolver pole pairs</strong></td><td>Resolver pole-pair count.</td><td>No</td><td>N/A</td></tr><tr><td><strong>R</strong><sub><strong>dir</strong></sub><strong> Direction of the sensor rotation</strong></td><td>Options: Clockwise or counterclockwise.</td><td>No</td><td>N/A</td></tr><tr><td><strong>R</strong><sub><strong>θ</strong></sub><strong> Angle offset Δθ (Sensor − Rotor)</strong></td><td>Angle offset between resolver and rotor position (°)</td><td>No</td><td>N/A</td></tr><tr><td><strong>R</strong><sub><strong>k</strong></sub><strong> Resolver sine/cosine gains</strong></td><td>The sine/cosine modulation output sine/cosine component amplitude. Default value are 1, 0, 0 and 1.</td><td>No</td><td>N/A</td></tr><tr><td><strong>E</strong><sub><strong>mod</strong></sub><strong> Excitation mode</strong></td><td>Number of resolver excitation windings. Two options: Single or Double<br>If <strong>Double</strong> is selected, <strong>R</strong><sub><strong>k2</strong></sub> and <strong>E</strong><sub><strong>src1</strong></sub> are displayed.</td><td>No</td><td>N/A</td></tr><tr><td><strong>E</strong><sub><strong>type</strong></sub><strong> Excitation source type</strong></td><td><p>Options AC, DC External<br><strong>AC</strong>: generated in FPGA at the specified frequency,</p><p><strong>DC:</strong> single excitation mode only<br><strong>External</strong> provided from outside the model.</p></td><td>No</td><td>N/A</td></tr><tr><td><strong>E</strong><sub><strong>src1</strong></sub><strong> Excitation source</strong></td><td>External excitation source in External mode.</td><td>No</td><td>From AI</td></tr><tr><td><strong>E</strong><sub><strong>f</strong></sub><strong> Excitation frequency</strong></td><td>Frequency of the excitation when in AC mode (Hz)</td><td>No</td><td>N/A</td></tr><tr><td><strong>E</strong><sub><strong>ts</strong></sub><strong> Excitation time shift</strong></td><td>Compensates time offset between the carrier generation input and modulated signal output (s)</td><td>No</td><td>N/A</td></tr></tbody></table>
{% endtab %}

{% tab title="Encoder" %}

<table><thead><tr><th width="180">Parameter</th><th width="310">Description</th><th width="100">Sets feature</th><th>I/O &#x26; Monitoring</th></tr></thead><tbody><tr><td><strong>Enc</strong><sub><strong>en</strong></sub><strong> Enable encoder</strong></td><td><p><strong>Disable</strong> the encoder.</p><p><strong>Enable</strong> the encoder, the following parameters are displayed.</p></td><td>No</td><td>N/A</td></tr><tr><td><strong>Enc</strong><sub><strong>type</strong></sub><strong> Encoder type</strong></td><td>Options : Quadrature or Hall Effect.</td><td>No</td><td>N/A</td></tr><tr><td><strong>A B Z encoder signals Q</strong><sub><strong>ABZ</strong></sub></td><td>Quadrature encoder A, B, and Z signals in Quadrature mode</td><td>No</td><td>To DO</td></tr><tr><td><strong>A B C encoder signals H</strong><sub><strong>ABC</strong></sub></td><td>Hall-effect encoder A, B, and C signals in hall effect mode.</td><td>No</td><td>To DO</td></tr><tr><td><strong>Q</strong><sub><strong>ppr</strong></sub><strong> Number of pulses per revolution</strong></td><td>Number of pulses in one full revolution of the encoder in Quadrature mode.</td><td>No</td><td>N/A</td></tr><tr><td><strong>Q</strong><sub><strong>dir</strong></sub><strong> Direction of the sensor rotation</strong></td><td>Direction in which the sensor is turning, A leads B or B leads A in Quadrature mode.</td><td>No</td><td>N/A</td></tr><tr><td><strong>Q</strong><sub><strong>θ</strong></sub><strong> Angle offset Δθ (Sensor − Rotor)</strong></td><td>Angle offset between the encoder and the rotor position from 0 to 360 degrees in Quadrature mode (°)</td><td>No</td><td>N/A</td></tr><tr><td><strong>Q</strong><sub><strong>rat</strong></sub><strong> Encoder speed ratio</strong></td><td>Sensor-to-mechanical position ratio. Encoder angle = Qrat × machine mechanical angle in Quadrature mode.</td><td>No</td><td>N/A</td></tr><tr><td><strong>H</strong><sub><strong>θ</strong></sub><strong> Hall effect sensor position</strong></td><td>Positions of phases a, b, and c in Hall effect mode (°)</td><td>No</td><td>N/A</td></tr><tr><td><strong>H</strong><sub><strong>rat</strong></sub><strong> Hall effect sensor speed ratio</strong></td><td>Mechanical to encoder ratio. Angle of Encoder = Hrat * machine mechanical angle in Hall effect mode</td><td>No</td><td>N/A</td></tr></tbody></table>
{% endtab %}
{% endtabs %}

### PMSM files parameters

<details>

<summary><strong>How to specify variable DQ parameters in the motor configuration file</strong></summary>

This block allows you to specify the electrical parameters values by providing a file when the **Variable DQ** option is selected. The parameters must be defined in **JSON format**, and the file must include the following parameters:

<table><thead><tr><th width="125">Parameter (JSON key)</th><th width="100">Value type</th><th width="85">Unit</th><th width="210">Description</th><th>Example</th></tr></thead><tbody><tr><td>PolePairs</td><td>int</td><td>N.A.</td><td>Number of pole pairs of the machine.</td><td>"PolePairs": 2</td></tr><tr><td>DqTransformAngleOffset</td><td>double</td><td>degree</td><td>Angle offset applied for the DQ Park Transform</td><td>"DqTransformAngleOffset": -90.0</td></tr><tr><td>Ra</td><td>double</td><td>Ohm</td><td>Resistance of the phase A</td><td>"Ra": 0.04</td></tr><tr><td>Rb</td><td>double</td><td>Ohm</td><td>Resistance of the phase B</td><td>"Rb": 0.04</td></tr><tr><td>Rc</td><td>double</td><td>Ohm</td><td>Resistance of the phase C</td><td>"Rc": 0.04</td></tr><tr><td>Id_axis</td><td>double[]</td><td>A</td><td>One dimensional array of the current values along the <strong>direct</strong> axis</td><td>"Id_axis": [<br>-50.0,<br>0.0,<br>50.0<br>],</td></tr><tr><td>Iq_axis</td><td>double[]</td><td>A</td><td>One dimensional array of the current values along the <strong>quadratic</strong> axis</td><td>"Iq_axis": [<br>-50.0,<br>0.0,<br>50.0<br>],</td></tr><tr><td>Ld</td><td>double[][]</td><td>H</td><td><p>Two dimensional array of the <strong>direct</strong> inductance values.</p><p>The first index is for the direct axis.</p><p>The second index is for the quadrature axis.</p></td><td>"Ld": [<br>[<br>0.0004,<br>0.00042,<br>0.00041<br>],<br>[<br>0.00041,<br>0.00044,<br>0.00043<br>],<br>[<br>0.0004,<br>0.00042,<br>0.000425<br>]<br>],</td></tr><tr><td>Lq</td><td>double[][]</td><td>H</td><td><p>Two dimensional array of the <strong>quadratic</strong> inductance values.</p><p>The first index is for the direct axis.</p><p>The second index is for the quadrature axis.</p></td><td>"Lq": [<br>[<br>0.0004,<br>0.00042,<br>0.00041<br>],<br>[<br>0.00041,<br>0.00044,<br>0.00043<br>],<br>[<br>0.0004,<br>0.00042,<br>0.000425<br>]<br>],</td></tr><tr><td>Fm</td><td>double[][]</td><td>Wb</td><td><p>Two dimensional array of the Permanent magnet flux values.</p><p>The first index is for the direct axis.</p><p>The second index is for the quadrature axis.</p></td><td>"Fm": [<br>[<br>0.1,<br>0.1,<br>0.1<br>],<br>[<br>0.1,<br>0.1,<br>0.1<br>],<br>[<br>0.1,<br>0.1,<br>0.1<br>]<br>]</td></tr><tr><td>TableInputCutoffFrequency (optional, default value 200 Hz)</td><td>double</td><td>Hz</td><td>Cut-off frequency of the low-pass filter applied on Id and Iq inputs of Ld, Lq, and Fm look-up tables.</td><td>"Ta</td></tr></tbody></table>

Concatenating the example above results in the following valid JSON:

</details>

<details>

<summary><strong>How to specify spatial harmonic parameters in the motor configuration file</strong></summary>

This block allows you to specify the electrical parameters values by providing a **.pmsmsh** file when the **spatial harmonic** option is selected. To generate this file, use the **PMSM SH File Converter executable**. This tool converts files from ANSYS JSON format (v2) or JMAG (.rtt) format into the required format.

A RTT file contains the electrical parameters that define the motor model. These parameters are derived from the JMAG CAD design using finite element analysis with two sets of parameters:

1. Parameters for the Spatial harmonics model (3D tables of Phase inductance, phase flux, and torque)
2. Parameters for the Variable DQ model (2D tables of Ld Lq inductances and magnet flux, torque is computed using the textbook equation)

It is important to generate Spatial Harmonics data and/or DQ data depending on the intended use of the model. However, generating both is recommended to avoid potential issues later on.

#### Spatial Harmonics Data Generation <a href="#spatial-harmonics-data-generation" id="spatial-harmonics-data-generation"></a>

<table><thead><tr><th width="125">Description</th><th width="100">Number of tables</th><th width="160">Theta axis recommendation</th><th width="160">Beta axis recommendation</th><th>lamp axis recommendation</th></tr></thead><tbody><tr><td>Phase inductance</td><td>9</td><td>65 samples or more [0 ... 180/Number Of Pole Pair]</td><td>33 samples or more [0 ... 360]</td><td>32 samples or more [0 ... 3*maximum peak phase current]</td></tr><tr><td>Phase total flux</td><td>3</td><td>129 samples or more [0 ... 360/Number Of Pole Pair]</td><td>33 samples or more [0 ... 360]</td><td>32 samples or more [0 ... 3*maximum peak phase current]</td></tr><tr><td>Torque</td><td>1</td><td>65 samples or more [0 ... 180/Number Of Pole Pair]</td><td>33 samples or more [0 ... 360]</td><td>32 samples or more [0 ... 3*maximum peak phase current]</td></tr></tbody></table>

where

* Theta = mechanical angle of the rotor
* Beta = polar angle of the (Id,Iq) vector in the DQ reference frame. JMAG use the power invariant DQ transform convention with D axis aligned with A phase at theta = 0.
* Iamp = amplitude of the (Id, Iq) vector in the DQ reference frame.

#### Generation Recommendations <a href="#generation-recommendations" id="generation-recommendations"></a>

**Number of samples:** To obtain accuracy, it is important to have a sufficient number of samples per axis and to respect the recommendations above.

**Axis boundaries:** It is also important to respect the recommended boundaries of these axes since lack of table section may lead to unexpected model behavior.\
The Spatial Harmonics PMSM model in particular can demonstrate noticeable stiffness if the currents exceed the axis limit and the LUT output is being saturated.

**Use of phase symmetry:** During the generation of the data, we recommend **not** using any symmetry options (generating a 3rd of the data since phase A is symmetrical in regards to B with a 120 deg electrical difference).\
It might be tempting to use this option to save generation time, but the OPAL-RT model does not support it. This is valid for inductance/flux and torque (slot symmetry for torque).

#### Table post-process performed by OPAL-RT's PMSM SH model implementation <a href="#table-post-process-performed-by-opal-rts-pmsm-sh-model-implementation" id="table-post-process-performed-by-opal-rts-pmsm-sh-model-implementation"></a>

**Before simulation:** Before the real-time simulation, since the FPGA size is limited, the OPAL-RT's PMSM block will reshape the RTT file table data to match the size reserved in the FPGA following the specification in the tables below.\
The space reserved depends on the version of the PMSM SH block and the number of machine simulated in a FPGA model instance.

**Table reshape method:** The FPGA models expects equally spaced samples for each axis. Before the simulation, we perform an tri-linear interpolation on the user's table data to find the table for the FPGA. Since the samples are equally spaced the resolution can be found by dividing the maximum value of each axis by the number of samples that are used.

**Single machine mode**: The memory space of the PMSM model core is shared with the two machine models. When only one machine is used, the full size of the table is available to model the machine. This table shows the default settings for both PMSM SH versions.

<table><thead><tr><th width="80">Axis</th><th width="200">Theta (Electrical angle)</th><th width="200">Beta</th><th width="200">Iamp</th></tr></thead><tbody><tr><td><strong>L</strong></td><td><strong>V2</strong>: 65 samples per half-electrical turn (Resolution 2.77 deg)<br><strong>V1</strong>: 33 samples per half-electrical turn (Resolution 5.45 deg)</td><td>33 (Resolution 10.9 deg)</td><td><strong>V2</strong>: 32 (Resolution IampMax / 32 Amps)<br><strong>V1</strong>: 16 (Resolution IampMax / 16 Amps)</td></tr><tr><td><strong>Flux</strong></td><td>65 samples per full-electrical turn (Resolution 5.54 deg)</td><td>33 (Resolution 10.9 deg)</td><td><strong>V2</strong>: 32 (Resolution IampMax / 32 Amps)<br><strong>V1</strong>: 16 (Resolution IampMax / 16 Amps)</td></tr><tr><td><strong>Torque</strong></td><td><strong>V2</strong>: 65 samples per slot (1/6 of electrical turn) (Resolution 0.92 deg)<br><strong>V1</strong>: 33 samples per slot (1/6 of electrical turn) (Resolution 5.45 deg)</td><td>33 (Resolution 10.9 deg)</td><td><strong>V2</strong>: 32 (Resolution IampMax / 32 Amps)<br><strong>V1</strong>: 16 (Resolution IampMax / 16 Amps)</td></tr></tbody></table>

**Dual machine mode**: The total allocated FPGA memory is split between the two machine models.

<table><thead><tr><th width="80">Axis</th><th width="200">Theta (Electrical angle)</th><th width="200">Beta</th><th width="200">Iamp</th></tr></thead><tbody><tr><td><strong>L</strong></td><td>33 samples per half-electrical turn (Resolution 5.45 deg)</td><td><strong>V2</strong>: 33 (Resolution 10.9 deg)<br><strong>V1</strong>: 17 (Resolution 2.17 deg)</td><td><strong>V2</strong>: 32 (Resolution IampMax / 32 Amps)<br><strong>V1</strong>: 16 (Resolution IampMax / 16 Amps)</td></tr><tr><td><strong>Flux</strong></td><td><strong>V2</strong>: 33 samples per full-electrical turn (Resolution 10.9 deg)<br><strong>V1</strong>: 65 samples per full-electrical turn (Resolution 5.54 deg)</td><td><strong>V2</strong>: 33 (Resolution 10.9 deg)<br><strong>V1</strong>: 17 (Resolution 2.17 deg)</td><td><strong>V2</strong>: 32 (Resolution IampMax / 32 Amps)<br><strong>V1</strong>: 16 (Resolution IampMax / 16 Amps)</td></tr><tr><td><strong>Torque</strong></td><td><strong>V2</strong>: 33 samples per slot (1/6 of electrical turn) (Resolution 1.98 deg)<br><strong>V1</strong>: 33 samples per slot (1/6 of electrical turn) (Resolution 5.45 deg)</td><td><strong>V2</strong>: 33 (Resolution 10.9 deg)<br><strong>V1</strong>: 17 (Resolution 2.17 deg)</td><td><strong>V2</strong>: 32 (Resolution IampMax / 32 Amps)<br><strong>V1</strong>: 16 (Resolution IampMax / 16 Amps)</td></tr></tbody></table>

**During simulation:** During the simulation, the tables are accessed using a 18bits Tri-linear interpolation. The effective resolution on a linear segment will be 1/2^18 \* resolution values provided in the tables.

#### Ansys file generation (JSON v2) <a href="#heading-title-text" id="heading-title-text"></a>

To generate a JSON file from Ansys Maxwell, that can be converted using the **PMSM SH File Converter Executable** to fit in the Schematic Editor, follow the procedure :

The script used in the presentation is available here

{% hint style="info" %}
**Phase Sequence:** The presentation above specifies on Page 8, that the Windings Phase Sequence should be Phase A, Phase B and Phase C during the Current Sweep. However, the intermediate files which Ansys generates, that are used by the Python script, depend on the Windings Phase Sequence in the Finite Element Model, which should also be ensured to follow Phase A, Phase B and Phase C sequence. If the Finite Element Model and Current Sweep follow different Phase Sequence, the imported data in Schematic Editor will be incorrect.
{% endhint %}

</details>

<details>

<summary><strong>How to specify Back EMF parameters in the Back-EMF file</strong></summary>

This block allows you to specify the **Back‑EMF values** by providing a file when the **User‑defined** option is selected. The Back‑EMF parameters must be defined in **JSON format**, and the file must include the following parameters:

<table><thead><tr><th width="150">Parameter (JSON key)</th><th width="130">Value type</th><th width="75">Unit</th><th width="230">Description</th><th>Example</th></tr></thead><tbody><tr><td><strong>backEmfValues</strong></td><td>double[1024]</td><td>N/A</td><td><p>One dimensional array of the back EMF waveform values.</p><p>The range of values must be from -1 to 1!</p><p>Needs to be 1024 values!</p></td><td>"backEmfValues": [<br>-0.0,<br>-0.005,<br>-0.01,<br>[…]<br>0.01,<br>0.005<br>],</td></tr></tbody></table>

Concatenating the example above results in the following valid JSON:

</details>

## Conserving ports

| Port               | Description                                       |
| ------------------ | ------------------------------------------------- |
| **Stator phase a** | Electrical conserving port for stator terminal a. |
| **Stator phase b** | Electrical conserving port for stator terminal b. |
| **Stator phase c** | Electrical conserving port for stator terminal c. |


---

# 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/ehs/model-in-schematic-editor/library-blocks-reference/machines-blocks/permanent-magnet-synchronous-machine-3-phase.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.
