> 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/blocks-functions-tools/machines/blocks/dc-machine.md).

# DC Machine

## Description

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

The **DC Machine** block, located in the **OPAL-RT SPS Software/Electrical Machines** library, block implements a wound-field or permanent magnet DC machine.

For the wound-field DC machine, access is provided to the field terminals (F+, F−) so that the machine model can be used as a shunt-connected or a series-connected DC machine. The torque applied to the shaft is provided at the Simulink® input TL.

The armature circuit (A+, A−) consists of an inductor La and resistor Ra in series with a counter-electromotive force (CEMF) E.

$$
E=K\_E \omega
$$

The CEMF is proportional to the machine speed.

$$K\_E$$ is the voltage constant and *ω* is the machine speed.

In a separately excited DC machine model, the voltage constant $$K\_E$$ is proportional to the field current $$I\_f$$:

$$
K\_E= L\_{af} I\_f
$$

$$L\_{af}$$ is the field-armature mutual inductance.

The electromechanical torque developed by the DC machine is proportional to the armature current $$I\_a$$

$$
T\_e= K\_TI\_a
$$

$$K\_T$$ is the torque constant. The sign convention for $$T\_e$$ and $$T\_L$$ is:

$$
\begin{aligned}
T\_e,T\_L > 0: \text{Motor mode} \\\[8pt]
T\_e,T\_L < 0: \text{Generator mode}
\end{aligned}
$$

The torque constant is equal to the voltage constant.

$$
K\_T=K\_E
$$

The armature circuit is connected between the A+ and A− ports of the DC Machine block. It is represented by a series Ra La branch in series with a Controlled Voltage Source and a Current Measurement block.

In the **wound-field DC machine mode**l, the field circuit is represented by an RL circuit. It is connected between the F+ and F− ports of the DC Machine block.

In the **permanent magnet DC machine model**, there is no field current as the excitation flux is established by the magnets.

The mechanical part computes the speed of the DC machine from the net torque applied to the rotor. The speed is used to implement the CEMF voltage E of the armature circuit.

The mechanical part implements this equation:

$$
J \frac{d\omega}{dt} = T\_e - T\_L - B\_m \omega - T\_f
$$

where *J* is the inertia, *B*<sub>*m*</sub> is the viscous friction coefficient, and *T*<sub>*f*</sub> is the Coulomb friction torque.

## Ports

### Input

<table data-header-hidden><thead><tr><th width="268.4000244140625"></th><th></th></tr></thead><tbody><tr><td><strong>TL</strong> — Mechanical load torque, N*m<br>scalar</td><td>Mechanical load torque, in N*m. <strong>Dependencies</strong> To enable this port, set <strong>Mechanical input</strong> to Torque TL.</td></tr><tr><td><strong>w</strong> — Machine speed, rad/s<br>scalar</td><td>Speed of the machine, in rad/s.<strong>Dependencies</strong> To enable this port, set <strong>Mechanical input</strong> to Speed w.</td></tr></tbody></table>

### Output

<table data-header-hidden><thead><tr><th width="261.3999938964844"></th><th width="501.79998779296875"></th></tr></thead><tbody><tr><td><strong>m</strong> — Measurement signals<br>four elements vector</td><td>Vector of measurement signals. To demultiplex these signals, use the Bus Selector block in the Simulink library.<br>w: Speed wm (rad/s)<br>iA: Armature current ia (A)<br>iF: Field current if (A)<br>Te: Electrical torque Te (N.m)</td></tr></tbody></table>

### Conserving

<table data-header-hidden><thead><tr><th width="270"></th><th></th></tr></thead><tbody><tr><td><strong>A+</strong> — Positive terminal of armature<br>SPS electrical</td><td>SPS electrical conserving port associated with the positive terminal of the armature circuit.</td></tr><tr><td><strong>A-</strong> — Negative terminal of armature<br>SPS electrical</td><td>SPS electrical conserving port associated with the negative terminal of the armature circuit.</td></tr><tr><td><strong>F+</strong> — Positive terminal of field circuit<br>SPS electrical</td><td><p>SPS electrical conserving port associated with the positive terminal of the field circuit.</p><p><strong>Dependencies</strong> To enable this port, set <strong>Field type</strong> to Wound.</p></td></tr><tr><td><strong>F-</strong> — Negative terminal of field circuit<br>SPS electrical</td><td><p>SPS electrical conserving port associated with the negative terminal of the field circuit.</p><p><strong>Dependencies</strong> To enable this port, set <strong>Field type</strong> to Wound.</p></td></tr><tr><td><strong>S</strong> — Machine shaft<br>Mechanical rotational</td><td><p>Mechanical rotational conserving port associated with the machine shaft.</p><p><strong>Dependencies</strong> To enable this port, set <strong>Mechanical input</strong> to Mechanical rotational port.</p></td></tr></tbody></table>

## Parameters

### Configuration

<table data-header-hidden><thead><tr><th width="332.4000244140625"></th><th></th></tr></thead><tbody><tr><td><strong>Preset model</strong> — Set of predetermined electrical and mechanical parameters for DC machine<br>No (default) | 01: 5HP 240V 1750RPM Field:300V | 02: 5HP 240V 1750RPM Field:150V | 03: 5HP 500V 1750RPM Field:300V | 04: 10HP 240V 1750RPM Field:300V | 05: 10HP 500V 1750RPM Field:300V | 06: 20HP 240V 1750RPM Field:300V | 07: 20HP 500V 1750RPM Field:300V | 08: 30HP 240V 1750RPM Field:300V | 09: 30HP 500V 1750RPM Field:300V | 10: 40HP 240V 1750RPM Field:300V | 11: 40HP 500V 1750RPM Field:300V | 12: 50HP 240V 1750RPM Field:300V | 13: 50HP 500V 1750RPM Field:300V | 14: 75HP 500V 1750RPM Field:300V | 15: 100HP 500V 1750RPM Field:300V | 16: 125HP 500V 1750RPM Field:300V | 17: 150HP 500V 1750RPM Field:300V | 18: 175HP 500V 1750RPM Field:300V | 19: 200HP 440V 1184RPM Field:310V | 20: 200HP 500V 1750RPM Field:150V | 21: 200HP 500V 1750RPM Field:300V | 22: 225HP 500V 1750RPM Field:300V | 23: 250HP 500V 1750RPM Field:300V</td><td><p>Option to choose a set of predetermined electrical and mechanical parameters for various DC machine ratings of power (HP), DC voltage (V), rated speed (rpm), and field voltage (V). Select one of the preset models to load the corresponding electrical and mechanical parameters in the entries of the dialog box. Select No if you do not want to use a preset model, or if you want to modify some of the parameters of a preset model. When you select a preset model, the electrical and mechanical parameters in the <strong>Parameters</strong> section of the dialog box become unmodifiable (unavailable). To start from a given preset model and then modify machine parameters:</p><ul><li>Select the preset model that you want to initialize the parameters.</li><li>Change the <strong>Preset model</strong> parameter value to No. This does not change the machine parameters. By doing so, you break the connection with the particular preset model.</li><li>Modify the machine parameters as you want, then click <strong>Apply</strong>.</li></ul><p><strong>Dependencies</strong> To enable this parameter, set <strong>Field type</strong> to <code>Wound</code>.</p></td></tr><tr><td><strong>Mechanical input</strong> — Mechanical input<br>Torque TL (default) | Speed w | Mechanical rotational port</td><td><p>Torque applied to the shaft or the rotor speed as a Simulink input of the block, or represent the machine shaft by a Simscape™ rotational mechanical port:</p><ul><li>Torque TL — Specify a torque input, in N*m. The block determines the machine speed by using the machine Inertia J and the difference between the applied mechanical load torque TL and the internal electromagnetic torque Te. The sign convention for the mechanical torque is: when the speed is positive, a positive torque signal indicates motor mode and a negative signal indicates generator mode.</li><li>Speed w — Specify a speed input, in rad/s. The block imposes the machine speed and ignores the mechanical part of the model (inertia J). Use the speed as the mechanical input to model a mechanical coupling between two machines. The next figure indicates how to model a stiff shaft interconnection in a motor-generator. The speed output of machine 1 (motor) is connected to the speed input of machine 2 (generator), while machine 2 electromagnetic torque output Te is applied to the mechanical load torque input TL of machine 1. The Kw factor takes into account speed units of both machines (rad/s) and gear box ratio. The KT factor takes into account torque units of both machines (N.m) and machine ratings. Also, as the inertia J2 is ignored in machine 2, J2 referred to machine 1 speed must be added to machine 1 inertia J1.</li></ul><p><img src="https://799605156-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdlNg8IbOdahCpFCyzxSN%2Fuploads%2Fgit-blob-ab007a5a9e3e90af5dcb3c9208211428bc91894c%2FDC_machine_mechanical_model.png?alt=media" alt="" data-size="original"></p><ul><li>Mechanical rotational port — Add to the block a Simscape mechanical rotational port that allows connection of the machine shaft with other Simscape blocks having mechanical rotational ports. The next figure indicates how to connect an Ideal Torque Source block from the Simscape library to the machine shaft to represent the machine in motor mode, or in generator mode, when the rotor speed is positive.</li></ul><p><img src="https://799605156-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdlNg8IbOdahCpFCyzxSN%2Fuploads%2Fgit-blob-112d85ed62888fea3143aa804f0e57db7e5c568d%2FDC_machine_ideal_torqu_block_connexion.png?alt=media" alt="" data-size="original"></p></td></tr><tr><td><strong>Field type</strong> — Field type of machine<br>Wound (default) | Permanent magnet</td><td>Whether to model a wound-field machine or a permanent magnet DC machine.</td></tr><tr><td><strong>Use signal names to identify bus labels</strong> — Whether to use signal names in measurement output<br>off (default) | on</td><td>Whether to use the signal names in the measurement output to identify the bus labels. Select this parameter for applications that require bus signal label to have only alphanumeric characters. When you clear this parameter, the measurement output uses the signal definition to identify the bus labels. The labels contain non alphanumeric characters that are incompatible with some Simulink applications.</td></tr></tbody></table>

### Parameters

<table data-header-hidden><thead><tr><th width="251.5999755859375"></th><th></th></tr></thead><tbody><tr><td><strong>Armature resistance and inductance [Ra (ohms) La (H) ]</strong> — Armature resistance and inductance<br>[ 0.6 0.012] (default)</td><td>Armature resistance Ra, in ohms, and armature inductance La, in henries.</td></tr><tr><td><strong>Field resistance and inductance [Rf (ohms) Lf (H) ]</strong> — Field resistance and inductance<br>[ 240 120] (default)</td><td><p>Field resistance Rf, in ohms, and field inductance Lf, in henries.</p><p><strong>Dependencies</strong> To enable this parameter, in the <strong>Configuration</strong> section, set <strong>Field type</strong> to Wound.</p></td></tr><tr><td><strong>Field-armature mutual inductance Laf (H)</strong> — Field-armature mutual inductance<br>1.8 (default)</td><td><p>Field-armature mutual inductance, in henries.</p><p><strong>Dependencies</strong> To enable this parameter, in the <strong>Configuration</strong> section, set <strong>Field type</strong> to Wound.</p></td></tr><tr><td><strong>Specify</strong> — Machine constant for block parameterization<br>Torque constant (N.m/A) (default) | Back-emf constant (V/rpm)</td><td><p>For a permanent magnet DC machine, select the machine constant that you want to specify for block parameterization.</p><p><strong>Dependencies</strong> To enable this parameter, in the <strong>Configuration</strong> section, set <strong>Field type</strong> to Permanent magnet.</p></td></tr><tr><td><strong>Back-emf constant (V/rpm)</strong> — Voltage per speed constant<br>1.8 (default)</td><td><p>Voltage per speed constant of the permanent magnet DC machine, in V/rpm.</p><p><strong>Dependencies</strong> To enable this parameter, in the <strong>Configuration</strong> section, set <strong>Field type</strong> to Permanent magnet and, in the <strong>Parameters</strong> section, set <strong>Specify</strong> to Back-emf constant.</p></td></tr><tr><td><strong>Torque constant (N.m/A)</strong> — Torque per current constant<br>1.8 (default)</td><td><p>Torque per current constant of the permanent magnet DC machine, in N.m/A.</p><p><strong>Dependencies</strong> To enable this parameter, in the <strong>Configuration</strong> section, set <strong>Field type</strong> to Permanent magnet and, in the <strong>Parameters</strong> section, set <strong>Specify</strong> to Torque constant.</p></td></tr><tr><td><strong>Total inertia J (kg.m^2)</strong> — Total inertia of DC machine<br>1 (default)</td><td>Total inertia of the DC machine, in kg.m<sup>2</sup>.</td></tr><tr><td><strong>Viscous friction coefficient Bm (N.m.s)</strong> — Total friction coefficient of DC machine<br>0 (default)</td><td>Total friction coefficient of the DC machine, in N.m.s.</td></tr><tr><td><strong>Coulomb friction torque Tf (N.m)</strong> — Coulomb friction torque constant of DC machine<br>0 (default)</td><td>Total Coulomb friction torque constant of the DC machine, in N.m.</td></tr><tr><td><strong>Initial speed (rad/s)</strong> — Initial speed for DC machine<br>1 (default)</td><td>Initial speed for the DC machine, in rad/s, in order to start the simulation with a specific initial speed. To start the simulation in steady state, the initial value of the input torque signal T<sub>L</sub> must be proportional to the initial speed.</td></tr></tbody></table>

### Advanced

<table data-header-hidden><thead><tr><th width="261.20001220703125"></th><th></th></tr></thead><tbody><tr><td><strong>Sample time (-1 for inherited)</strong> — Sample time of block<br>-1 (default)</td><td>Sample time that the block uses. To inherit the sample time specified in the Powergui block, set this parameter to −1.</td></tr></tbody></table>

## Examples <a href="#examples" id="examples"></a>

The [Starting a DC Motor ](https://www.opal-rt.com/docs/smart-power-simulation-software-sps/example-models/machines/starting-a-dc-motor.md)(power\_dcmotor) example illustrates the starting of a 5 HP 240-V DC machine with a three-step resistance starter.

## References <a href="#references" id="references"></a>

\[1] *Analysis of Electric Machinery,* Krause et al., pp. 89–92.


---

# 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/blocks-functions-tools/machines/blocks/dc-machine.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.
