Usage#

After Installation, motulator can be used by creating a continuous-time system model, a discrete-time control system, and a simulation object.

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.

Simulation Results#

The motulator.common.model.SimulationResults object returned by the simulation contains the time series of the system model in res.mdl and those of the control system in res.ctrl, see Control System Framework. The plotting functions, such as motulator.drive.utils.plot() and motulator.grid.utils.plot_control_signals(), plot the main signals in SI units or, if base values are given, in per-unit values.

Conventions#

  • Space vectors are peak-valued complex numbers, see Space Vectors. The suffix _ab marks stationary coordinates and _dq rotor coordinates, e.g., i_s_ab and psi_s_dq. Inside the controllers, the vectors are in the controller coordinates and have no suffix.

  • Reference values end in _ref, e.g., tau_M_ref. Signals inside the controllers are estimates without a special suffix.

  • Lowercase m denotes electrical and uppercase M mechanical quantities, e.g., the electrical angular speed w_m = n_p*w_M and the mechanical angular speed w_M.

  • SI units are used. The per-unit base values motulator.common.utils.BaseValues are only used for plotting.