motor-foc-ltid-pmsm

motor-foc-ltid-pmsm — PMSM FOC + Load-Torque Estimator + Feed-Forward Builder

Three-phase 2-level voltage-source inverter + PMSM. Field-oriented speed control (outer Symmetric-Optimum speed PI → iq_ref; inner dq current PI ×2 with cross-coupling + back-EMF decoupling feed-forward; id_ref = 0), augmented with a linear load-torque state estimator on the model x = [ω_m; T_L], u = T_e, y = ω_m — seven selectable realizations on one shared structure (pole-placed Luenberger, steady-state KF, steady colored KF, recursive KF, recursive colored KF, correlated-noise KF, continuous Kalman-Bucy). The estimate T̂_L is fed forward into iq_ref (via the torque constant) to cut the load-step speed dip the speed PI alone cannot. v1 baseline supports SPMSM and mild-saliency IPMSM (Lq/Ld < 2, id_ref = 0); strong-saliency MTPA deferred.

Layered on motor-pmsm-base. All base discipline applies (plant build standard, dq conventions, building-blocks SOP, broken-FOC defense, visual 4-check).

⚠️ Estimator validation note

The base FOC plant + dq current PI + speed PI formulas are reused by pointer from the base pmsm_formulas.md §0–§7, §A. The load-torque estimator family (F2–F10: augmented model, observability, Luenberger, recursive/steady/colored/correlated KF, Kalman-Bucy) is documented in formulas/pmsm_foc_ltid_formulas.md, each formula cross-checked against ≥2 independent academic sources (see base/theory_anchor.md).

Validation requirement: a visual review on the MATLAB desktop (motor rotates / iq tracks / iabc AC sinusoidal / Te energy balance) plus the FF-on-vs-FF-off dip-reduction demonstration. Neither can be skipped.

Must-Follow Rules

1. Plan first — numbered plan with the input table (below), the design-decision choices (discretization path, KF tuning, plant choice — see the build template's parameter block), and the build-script structure. Get user approval before the first add_block.
2. One-click reproducibility — every numeric originates in the model InitFcn (machine, PI gains, all estimator matrices via c2d/place/dlqe, the augmented n=3 colored model, the F9.a cross-term, the F10 continuous intensities, plus guarded ff_enable/est_sel/plant_sel defaults). No external design script may need to run first. See base one-click discipline.
3. The six structural modules are non-negotiable — (1) plant exposing ω_m, θ_e, i_abc/i_dq, T_e + T_L input; (2) outer speed PI (saturation + anti-windup); (3) inner dq current PI ×2 with decoupling/back-EMF FF (id_ref=0); (4) Clarke/Park transforms on a single global θ_e; (5) load-torque estimator on x=[ω_m;T_L]; (6) feed-forward of T̂_L into iq_ref with an enable. Omitting any one breaks the method.
4. θ_e Goto TagVisibility='global' is MANDATORY in every plant variant — the base Anti_Park/Plark consume θ_e via an internal From "The"; a default 'local' Goto is the classic silent failure (FOC degenerates to lab-frame open-loop: motor stalls, iabc DC-locked). A build self-test must assert global visibility on every The Goto (look-under-masks). See base/broken_foc_diagnostics.md §F-CRIT 1.
5. Estimator on the augmented model + observability check — build x=[ω_m;T_L], u=T_e, y=ω_m with ṪL≈0 (random-walk internal model, F2). Assert observability rank(O)=2 (F3, det≈-1/J≠0) in InitFcn — a rank-deficient model is a build error, not a tuning issue.
6. All 7 variants on ONE shared structure = coverage, NOT copy — reproduce the variant structure/tuning method from F4–F10; never copy magic Q/R/pole numbers or a selector topology from any source. Realize the recursive KFs inline (KF_Estimator_EML atom / inline MATLAB Function) so the model is one-click. The steady-state KF must collapse onto the Luenberger (F7.b) — verify their T̂_L std match as a built-in cross-check.
7. Feed-forward enable is mandatory — iq_ref += (T̂_L/Kt)·ff_enable, with ff_enable toggling FF-on vs FF-off. The headline demonstrable effect is FF-on reduces the load-step speed dip and recovery time; FF-off is the baseline. This is the method's reason to exist (see misconception #3).
8. Speed PI = Symmetric Optimum, not pole-zero-cancellation — a PZC/IMC-tuned speed PI has a disturbance-rejection slow pole fixed by the plant mechanical ratio −B/J, independent of bandwidth (the Phase-4.5 trap: large inertia → long load-settling no matter the gain). Use Symmetric Optimum (a=4, Teq=1/αc) so rejection is bandwidth-dependent, and verify the evaluation window T_window ≥ 5·τ_max (τ_max=2·a·Teq). See base Phase-4.5 sanity check.
9. Reproducible measurement noise (fixed seed) — inject ω_m,meas = ω_m + n with a fixed-seed Random Number at a sub-ts rate. The sensor noise is the KF's reason to exist; without it a plain observer suffices and the Kalman story is unmotivated.
10. R2024b estimator sizing recipe + visual 4-check — the KF_Estimator_EML atom and the inline persistent/continuous charts (KF6/KF7) need their port Size pinned (DataType=Inherit, chart SampleTime='-1'); R2024b output-size inference fails for persistent xhat=zeros(size(A,1),1) and continuous-feedback charts. See building_blocks/foc_ltid_api_notes.md §E.1. Run the base visual 4-check before trusting any metric.