Skip to main content

motulator

Motor drive and grid converter simulator in Python

PyPI version Python versions Build Status License DOI All Contributors

Documentation · Drive examples · Grid examples · Installation

Simulated sensorless flux-vector control of a 2.2-kW IPMSM drive: speed step, load-torque step, and phase currents

motulator provides simulation models and control algorithms for electric machine drives and grid converter systems. The system models are simulated in the continuous-time domain, while the control algorithms run in discrete time, as they would in a real converter.

Features

  • Machine models: induction machines, synchronous reluctance machines, and permanent-magnet synchronous machines, including magnetic saturation and two-mass mechanics
  • Grid converter models: L and LCL filters, inductive-resistive grids, and DC-bus dynamics
  • Drive control: V/Hz control, current-vector and flux-vector control, sensorless observers, and signal injection
  • Grid converter control: grid-following and grid-forming control, including disturbance-observer-based and power-synchronization methods
  • Ready-to-run examples as Python scripts and Jupyter notebooks, including neural-network-based flux maps learned from measured data

Installation

pip install motulator

To develop motulator itself, clone the repository as described in the installation guide.

Quick start

A complete simulation takes about 20 lines. This example runs sensorless flux-vector control of a 2.2-kW interior permanent-magnet synchronous machine drive:

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

# Continuous-time system model: 2.2-kW IPMSM, mechanics, and converter
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),
)

# Discrete-time control system: sensorless flux-vector control
cfg = control.FluxVectorControllerCfg(i_s_max=6.5, sensorless=True)
ctrl = control.VectorControlSystem(
    control.FluxVectorController(par, cfg), control.SpeedController(J=0.015, alpha_s=25)
)

# Speed reference and load torque
ctrl.set_speed_ref(lambda t: (t > 0.1) * 50)  # rad/s
mdl.mechanics.set_external_load_torque(lambda t: (t > 0.7) * 10)  # Nm

res = model.Simulation(mdl, ctrl).simulate(t_stop=1.2)
utils.plot(res)

To go further, start from the drive examples and grid examples. New system models and controllers can be developed using the existing ones as templates.

From simulation to the laboratory

Laboratory test bench: a permanent-magnet synchronous machine coupled to a load machine through a torque sensor, with the converter cabinet in the background

Almost all control methods in the examples have also been implemented and tested on laboratory test benches at Aalto University, such as the one shown here. The simulation models aim to capture the dynamics that matter for control design.


The following packages extend motulator, each maintained in its own repository:

  • motulator-export: export of drive and grid converter systems to PLECS and Simulink, with the control algorithms ported to C
  • motulator-gradnet: training of gradient-network magnetic models of synchronous machines from measured or finite-element data
  • motulator-impedance: mechanical impedance of machine drives and output admittance of grid converters, measured by frequency sweeps
  • motulator-multiphase: multi-three-phase machine drives based on the decoupled multi-stator transformation

See the related packages page for the tested releases and for listing a package.

Contributing

If you would like to help us develop motulator, see these guidelines first.

Contributors

Thanks go to these wonderful people:

Lauri Tiitinen
Lauri Tiitinen

💻 🤔 💡 🧑‍🏫
HannuHar
HannuHar

💻 🐛
Marko Hinkkanen
Marko Hinkkanen

💻 🤔 💡 🧑‍🏫
silundbe
silundbe

💻 💡
JoonaKukkonen
JoonaKukkonen

💻 🚇
jarno-k
jarno-k

🤔 👀 🧑‍🏫
angelicaiaderosa
angelicaiaderosa

💻 💡
Luca Peretti
Luca Peretti

🤔 📣
GianmarioPellegrinoPolito
GianmarioPellegrinoPolito

🔣
Simone Ferrari
Simone Ferrari

🔣
Jialed0303
Jialed0303

🤔
murgui
murgui

🐛
Nithin Valiyaveettil Sadanandan
Nithin Valiyaveettil Sadanandan

🐛
saarela
saarela

🐛
Ushnish
Ushnish

🐛
Francesco-Lelli
Francesco-Lelli

💻 💡 🤔
Mikko Sarén
Mikko Sarén

💻 💡 🤔
Juho Määttä
Juho Määttä

💻 💡 🤔
rayanmour
rayanmour

💻 💡 🤔 👀 🧑‍🏫
Cosimo Bassi
Cosimo Bassi

🚇
Junyi Li
Junyi Li

💻 💡 🤔
Tim Foißner
Tim Foißner

🔣 🤔
Claudio Lima
Claudio Lima

💻 🤔

This project follows the all-contributors specification. Contributions of any kind welcome!

Acknowledgment

This project has been sponsored by ABB Oy and by the Research Council of Finland Centre of Excellence in High-Speed Electromechanical Energy Conversion Systems. The example control methods included in this repository are based on published algorithms (available in textbooks and scientific articles). They do not present any proprietary control software.

Metadata

Release files for motulator 0.16.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for motulator 0.16.0
File Size Uploaded Provenance Actions
motulator-0.16.0.tar.gz 28.3 MB Without provenance Details for motulator-0.16.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for motulator 0.16.0
File Interpreter ABI Platform Actions
motulator-0.16.0-py3-none-any.whl Python 3 none any Details for motulator-0.16.0-py3-none-any.whl

Total release size: 28.5 MB

Release files / motulator-0.16.0.tar.gz

Download URL motulator-0.16.0.tar.gz
Size 28.3 MB
Tags Source
SHA-256 checksum
How to use checksums
6494b963bbdd92b4c56c51980a22b84589129b128db5790ba6305f50fcfc50f7
BLAKE2b-256 checksum
How to use checksums
cb74e7daf2056079b0c31e22c888ebbe67c97483e13754ca5e9a792b09913c91
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.15

Release files / motulator-0.16.0-py3-none-any.whl

Download URL motulator-0.16.0-py3-none-any.whl
Size 149.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
01f27434e615f94dbf70c7ddfb6c7cf16760259f55b96c7fd0c21d51e4a9d495
BLAKE2b-256 checksum
How to use checksums
50f387c93853fa691bac752571300d5174724a7a47b4daaf377fedf907aa6d49
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.15

Security for motulator 0.16.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.16.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page