calebzu motor-dtc-pmsm — PMSM Direct Torque Control Builder
Three-phase 2-level voltage-source inverter + PMSM (SPMSM / IPMSM via parameterization). Outer-loop = Speed PI providing Te_ref. Inner-loop = Direct Torque Control in αβ stationary frame: stator flux integrator + magnitude/angle/sector + 2-level hysteresis on (T, ψ) + Sutikno 6-state switching table → V_k → gate.
Layered on motor-pmsm-base. All base discipline applies.
Must-Follow Rules
- Plan first — Numbered plan with 21 input table, design-decision choices (design_decisions.md), build-script structure. Get user approval.
- One-click reproducibility — All parameters injected via
set_param(mdl, 'InitFcn', ...). Model must Run from.slxdouble-click in fresh MATLAB session. See crit_conditions.md §E-CRIT. - Default 6-state switching table for PMSM —
switching_table_mode='6state'(Sutikno 2011 Table 2). Never default to 8-state Takahashi for PMSM — V0/V7 zero vectors cause flux to decay. See switching_table.md and crit_conditions.md §A-CRIT. ψ_ref ≠ ψ_fby default — Takepsi_reffrom reference if supplied; else compute the id=0 load-point stator flux|ψ_s|_load = sqrt(ψ_f² + (Lq·iq_max)²)(not true MTPA, which needs id<0). Never defaultψ_ref = ψ_ffor IPMSM. See crit_conditions.md §B-CRIT.T_eq_factor = 15for DTC, NOT 5 — DTC's hysteresis inner loop has lower bandwidth than FCS-MPC's current PI. Compute Speed PI gains viapi_design('SO', J, 1, T_eq, a_so)withT_eq = 15·Tsc,a_so = 4. PassKt = 1because DTC outer PI directly outputsTe_ref[N·m] (plant has no Kt). See crit_conditions.md §C-CRIT.- Chart config = INHERITED + dual ZOH —
ch.SampleTime='-1',ch.ChartUpdate='INHERITED'. ZOH @ Tsc on every chart input (5 inputs:Te_ref, ia, ib, ua, ub) AND every chart output (9 outputs:gate, Te_meas, mag_psi, ψ_α, ψ_β, sector, V_k, C_ψ, C_T). See crit_conditions.md §D-CRIT. - Speed PI saturation is mandatory —
Saturationblock after PI with limits[-T_max, +T_max]. Anti-windup off for v1 baseline; production should add clamp or back-calc. - Add 4 Scopes for human inspection —
Scope_wm_RPM/Scope_Te/Scope_psi_mag/Scope_psi_alphabeta(XY Graph). The αβ XY plot is the most diagnostic — circular trajectory means healthy 6-state; hexagonal-with-inner-circle means 8-state pollution. See crit_conditions.md §F-CRIT. - Non-overlapping wiring — Every
add_blockspecifiesPositionper X/Y bands;arrangeSystem(mdl, 'FullLayout')as final fallback. - HB reverse-calculation from
fs_max— Use plant + Tsc to back-calcHB_T_minandHB_psi_min. Percentages (HB_T = 7.5% T_max, HB_ψ = 2.5% ψ_ref) are fallback only whenfs_maxis unknown. See hb_sizing.md.
Build Flow
| Phase | Action | Reference |
|---|---|---|
| 0 | Validate inputs + sanity grid | base/pre_build_grid.md |
| 1 | Plant layer (powergui Discrete @ step_size, DC, UB, PMSM, TL Step, current/voltage measurement) | (this skill) |
| 2 | Measurement + αβ transform layer (Clark for currents, Clark for voltages) | (this skill) |
| 3 | Outer Speed PI (RPM domain, mandatory saturation, SO method T_eq=15·Tsc) |
crit_conditions.md §C-CRIT |
| 4 | Inner DTC chart (flux integrator + magnitude/sector + hysteresis + 6-state table) | chart_algorithm.md + switching_table.md |
| 5 | Logger (19 channels, including ψ_α and ψ_β) | crit_conditions.md §F-CRIT |
| 6 | 4 Scopes (wm_RPM / Te / mag_psi / αβ XY) | crit_conditions.md §F-CRIT |
| 7 | Solver (Fixed-step ode3, FixedStep = step_size; powergui Discrete) | (this skill) |
| 8 | InitFcn injection | crit_conditions.md §E-CRIT |
| 9 | Layout cleanup (arrangeSystem('FullLayout')) |
(this skill) |
| 10 | Self-tests + acceptance | acceptance_criteria.md |
Required User Inputs (21)
Ask user before starting. Defaults in parameter_defaults.md.
| Group | Parameters |
|---|---|
| Machine (6) | Pn, Rs, Ld, Lq, psi_f, J, B (B=0 forces SO method for Speed PI) |
| Power stage (1) | Vdc |
| Control (3) | psi_ref (reference value if supplied; else id=0 load-point stator flux — never ψ_f for IPMSM), T_max (reference value if supplied; else 1.5·Pn·ψf·iq_max), iq_max |
| Sampling (3) | Tsc (default 50 μs), step_size (default 1 μs; step_size ≤ Tsc/50), fs_max (default 10 kHz) |
| PI design (2) | T_eq_factor (default 15 for DTC), a_so (default 4 for SO ζ_eq ≈ 0.71) |
| Mode (4) | switching_table_mode (default '6state'), torque_hysteresis_levels (default 2), Te_feedback_mode (default 'alphabeta'), flux_drift_compensation (default 'none') |
| Solver (1) | solver (default 'ode3') |
| Scenario (4) | omega_ref_rpm, sim_time, TL_step_t, TL_after |
Triggers / Skip
| ✅ Use | ❌ Skip |
|---|---|
| Build / port / extend DTC simulation in Simulink | FCS-MPC, FOC, sensorless, scalar V/Hz, BLDC trapezoidal |
| Takahashi DTC, Sutikno DTC, hysteresis-based torque control | DTC-SVM (constant switching freq variant), MP-DTC (predictive DTC), 12-sector schemes, deadbeat flux/torque control |
| Switching table for PMSM DTC (6-state) | Online parameter adaptation, MTPA mid-loop, weak-field |
| Generalizing DTC to a new PMSM machine parameter set | Pure theory questions, paper writing, MATLAB perf, unit tests |
Generalization Across Machine Sub-Types
| Sub-type | Parameter constraint | Strategy |
|---|---|---|
| SPMSM | Ld == Lq |
psi_ref ≈ ψ_f workable (verify load doesn't push |ψ_s|_load above ψ_f) |
| IPMSM mild saliency | Lq > Ld, Lq/Ld ≤ 1.5 |
psi_ref = id=0 load-point flux: sqrt(ψ_f² + (Lq·iq_max)²) |
| IPMSM strong saliency | Lq/Ld ≥ 2 |
Same id=0 flux formula; T_max may need higher headroom |
Topology does not change — same blocks, same wiring, same chart, same CRIT conditions. Only psi_ref and iq_max budgets differ.
Out-of-scope sub-types: SynRM (ψ_f ≈ 0), IM, BLDC trapezoidal — different prediction equations and switching tables.
Known Limitation: Classical DTC Te Ripple
Hysteresis-driven switching produces an inherent torque ripple intrinsic to the bang-bang structure. Steady-state mean Te tracks reference within < 1%, but the instantaneous-Te ripple band may exceed simple ±5% bands. Acceptance Criteria Mode A allows S2 to be the marginal metric in the 4/5 budget per acceptance_criteria.md. Advanced variants that reduce ripple (DTC-SVM, MP-DTC, Sutikno Table 3) are out of scope.
Sibling Skills
- motor-pmsm-base — base infrastructure
- motor-fcs-mpc — FCS-MPC alternative
- motor-smc-pmsm — SMC alternative