> 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/model-and-simulation/add-and-configure-a-circuit-model-to-the-system-definition/machine-section/im-sm-section/mechanical-model-im-sm.md).

# Mechanical Model (IM SM)

## Mechanical Model Configuration Page

In the System Explorer window configuration tree, expand the Power Electronics Add-On custom device and select **Circuit Model >> IM SM >> Mechanical Model** to display this page. Use this page to configure the IM SM Mechanical model.

## Mechanical Model Description

Attached to the machine model's shaft is a basic mechanical model. This model was chosen due to its common application, and the ability to extend its functionality. The behavior of the model varies depending upon whether the **Mechanical Model Mode** is set to **Torque Controlled (1)** or **Speed Controlled (0)**.

### Torque Controlled

When the **Mechanical Model Mode** is set to **Torque Controlled (1)**, the equation of the mechanical model can be expressed as follows:

$$
\frac{\partial \omega\_m}{\partial t}
\= \frac{1}{J},\bigl(T\_{total} - F\_v ,\omega\_m \bigr)
\\\[8pt]
$$

where

$$
T\_{total} = T\_e - T\_L - T\_f
\\\[8pt]
$$

There is a dead-zone implementation with the static friction torque; if the **Electromagnetic Torque (Te)** does not exceed the **Static Friction (Tf)** torque, the speed remains at zero.

<figure><img src="https://2999842053-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fe9Kk9pJCHht2LLBSxPap%2Fuploads%2F5mBWJx6zJ17oo3fDwqox%2F3bda006d-7faf-4ce0-a1fc-a3f8c9d5cced.png?alt=media&amp;token=5a7cc8af-89e0-4e06-b507-7501f6dd0953" alt=""><figcaption></figcaption></figure>

Note that in the equation, the value of the mechanical speed (ω<sub>m</sub>) is in radians per second, while the output of the **Mechanical Speed** channel is in RPM. The equation for the **Electromagnetic Torque (Te)** of the machine can be found on its description page under the Machine Section.

### Speed Controlled

When the **Mechanical Model Mode** is set to **Speed Controlled (0)**, the mechanical parameters (Viscous Damping, Static Friction, Inertia) are ignored. Instead, the rotor speed is directly set using the **User-Defined Speed** parameter, ω<sub>user</sub>.

#### Choosing a Mechanical Model Mode

Select **Speed Controlled** mode if:

1. Your project requires you to manually set the speed of the machine
2. Your project has a mechanical model that requires you to input the speed of the machine in to the model

Select **Torque Controlled** mode if:

1. Your project requires you to manually set the load torque of the machine
2. Your project has a mechanical model that requires you to input the load toque of the machine in to the model

## Parameters

This page includes the following components, configurable at edit-time only.

### Mechanical Model

<table><thead><tr><th width="220.22222900390625">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong>Name</strong></td><td>Specifies the name of the model.</td></tr><tr><td><strong>Description</strong></td><td>Specifies a description for the model.</td></tr></tbody></table>

### Configuration

<table><thead><tr><th width="219.77777099609375">Parameter</th><th>Description</th></tr></thead><tbody><tr><td>Viscous Damping</td><td>Combined viscous damping of the rotor and load, proportional to the angular velocity of the machine, Fv (Nm·s/rad)(Default: 0.006)</td></tr><tr><td>Static Friction</td><td>Static friction resisting initial rotation when the machine is at rest, Tf (Nm) (Default: 0)</td></tr><tr><td>Inertia</td><td>Moment of inertia of the rotor and load, J (Kg·m2) (Default: 0.05)</td></tr></tbody></table>

## Mechanical Model Section Channels

This section includes the following custom device channels. The value of an input channel can be modified dynamically at execution time.

<table><thead><tr><th width="210.64447021484375">Channel Name</th><th>Description</th></tr></thead><tbody><tr><td>Mechanical Model Mode <strong>(Input)</strong></td><td><p>Set this channel to one of the following values:<br><strong>0</strong> — Sets the mechanical model to Speed Controlled mode. The mechanical parameters are ignored in this case.<br><strong>1</strong> — Sets the mechanical model to Torque Controlled mode.<br>See the <strong>Mechanical Model Description</strong> section for more information,</p><p>Default Value: 0 (Speed Controlled)</p></td></tr><tr><td>User-Defined Speed <strong>(Input)</strong></td><td><p>Forces the speed of the machine to the defined value. This parameter is used in <strong>Speed Controlled</strong> mode, and ignored in <strong>Torque Controlled</strong> mode, ωuser (RPM)</p><p>Default Value: 0</p></td></tr><tr><td>Load Torque <strong>(Input)</strong></td><td><p>Torque applied to the shaft of the machine. This parameter is used in <strong>Torque Controlled</strong> mode, and ignored in <strong>Speed Controlled</strong> mode, TL (Nm)</p><p>Default Value: 0</p></td></tr><tr><td>Speed <strong>(output)</strong></td><td><p>Rotational speed of the machine rotor in RPM, ωm (RPM)</p><p>Default Value: 0</p></td></tr><tr><td>Angle <strong>(output)</strong></td><td><p>Mechanical rotor position. If this signal is routed to a <strong>Waveform Channel</strong> or an <strong>Analog Output Channel</strong>, its value is expressed in Turns. The signal ranges in value from 0 to 1, with 1 representing a full rotation, θm (deg)</p><p>Default Value: 0</p></td></tr><tr><td>Torque <strong>(output)</strong></td><td><p>Electromagnetic torque measured at the rotor, Te (Nm)</p><p>Default Value: 0</p></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/pe-add-on-simulink/model-and-simulation/add-and-configure-a-circuit-model-to-the-system-definition/machine-section/im-sm-section/mechanical-model-im-sm.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.
