Getting started#

Requirements#

Python 3.12 or later. The package installs motulator 0.16.0 or a later 0.16 release.
PLECS: PLECS Standalone. To simulate from Python, enable the RPC interface (Preferences > General > RPC interface, port 1080).
Simulink: MATLAB with Simulink, and a C compiler that supports complex.h: gcc (Linux), clang (macOS), or MinGW-w64 (Windows, selected with mex -setup C). MSVC does not work. The models with MATLAB Function blocks need no compiler. To simulate from Python, install the MATLAB Engine API for Python matching your MATLAB release (e.g., pip install matlabengine==26.1.* for R2026a).
Native simulation: a C compiler, by default gcc (or the one given by the environment variable CC).

Installation#

Install the package in a virtual environment. On Linux and macOS:

python3 -m venv .venv
source .venv/bin/activate
pip install motulator-export

On Windows:

py -m venv .venv
.venv\Scripts\activate
pip install motulator-export

If PowerShell does not allow running the activation script, allow it with Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser.

The plots need a GUI library for matplotlib. On some Linux systems, it must be installed separately; see the installation of motulator.

The examples are in the repository. To run them, clone the repository and install the package from it. On Linux and macOS:

git clone https://github.com/Aalto-Electric-Drives/motulator-export
cd motulator-export
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

On Windows, create and activate the virtual environment as above. In VS Code, the virtual environment can also be created with the Python extension. For development, see Development.

A first model#

Each example script builds a system of the motulator examples. Run the examples from the root of the repository.

PLECS#

python examples/ipmsm_2kw_fvc.py

Open examples/ipmsm_2kw_fvc.plecs in PLECS and start the simulation. If PLECS is running with the RPC interface enabled, the script also simulates the system in PLECS and in motulator and prints the differences.

Simulink#

python examples/ipmsm_2kw_fvc_simulink.py

In MATLAB, run examples/simulink/build_ipmsm_2kw_fvc.m, which compiles the blocks of the control system and saves ipmsm_2kw_fvc.slx. Without a C compiler, use MATLAB Function blocks instead:

python examples/ipmsm_2kw_fvc_simulink.py --matlab

and run examples/simulink/build_ipmsm_2kw_fvc_matlab.m, which saves ipmsm_2kw_fvc_matlab.slx. With the MATLAB Engine API for Python, the script also builds and simulates the model and prints the differences from motulator.

Native simulation#

python examples/native/plot_2kw_ipmsm_fvc.py

The script simulates the drive natively and plots the results. After you close the figure, it simulates the same system in motulator and prints the run times and the differences. The examples include, e.g., a parameter sweep.

Example scripts#

The scripts for PLECS and Simulink are:

System	PLECS	Simulink
2.2-kW IPMSM, sensorless flux-vector control	`ipmsm_2kw_fvc.py`	`ipmsm_2kw_fvc_simulink.py`
5.6-kW PM-SyRM, GradNet models, flux-vector control	`pmsyrm_6kw_gn_fvc.py`	`pmsyrm_6kw_gn_fvc_simulink.py`
2.2-kW induction machine, current-vector control	`im_2kw_cvc.py`	`im_2kw_cvc_simulink.py`
2.2-kW induction machine, dead time and its compensation	`im_2kw_dead_time_cvc.py`
2.2-kW induction machine, observer-based V/Hz control	`im_2kw_vhz.py`	`im_2kw_vhz_simulink.py`
10-kVA grid converter, LCL filter, grid-following control	`gfl_10kva_lcl.py`	`gfl_10kva_lcl_simulink.py`
12.5-kVA grid converter, weak grid, grid-forming control	`gfm_13kva_do.py`	`gfm_13kva_do_simulink.py`

Exporting your own system#

Build the system in motulator, set its references, and write the models:

import motulator.drive.control.sm as control
from motulator.drive import model

from motulator_export import StepSignal, plecs, simulink

par = model.SynchronousMachinePars(n_p=3, R_s=3.6, L_d=0.036, L_q=0.051, psi_f=0.545)
mdl = model.Drive(
    model.SynchronousMachine(par),
    model.MechanicalSystem(J=0.015),
    model.VoltageSourceConverter(u_dc=540),
    pwm=True,
)
cfg = control.FluxVectorControllerCfg(i_s_max=6.5)
ctrl = control.VectorControlSystem(
    control.FluxVectorController(par, cfg),
    control.SpeedController(J=0.015, alpha_s=25.0),
)
ctrl.set_speed_ref(StepSignal(time=0.1, after=50.0))
mdl.mechanics.set_external_load_torque(StepSignal(time=0.7, after=10.0))

plecs.write_model("ipmsm.plecs", mdl, ctrl, t_stop=1.2)
simulink.write_model("ipmsm.slx", mdl, ctrl, t_stop=1.2)

The references, the load torque, and the gate enable (ctrl.set_enable) can be constants or StepSignal objects. A function of time cannot be exported.
The models start from the state of the system model, e.g., a given initial speed (mdl.mechanics.state.w_M = 50.0). Write the models before simulating the system in motulator.
A system that is not supported raises NotImplementedError before any file is written.

Getting started

Contents