motor-pmsm-base — PMSM Simulation Modeling Base
Reusable plant + frame conventions + building blocks + sanity-check templates + broken-FOC defense + visual review standards for three-phase voltage-source-inverter-driven PMSM (SPMSM / IPMSM via parameterization). Method-specific control laws (FOC / FCS-MPC / DTC / SMC / sensorless / observer / MTPA / weak-field) layer on top of this base.
Must-Follow Rules
- Use
shared/* assets, do not duplicate. shared/formulas/pmsm_formulas.md has signed-off plant equations and control law derivations. shared/building_blocks/ provides verified atomic blocks. Reference them by path; do not re-derive or copy content.
- Run pre-build sanity grid before any build. See references/pre_build_grid.md. Fail-fast when Vdc/BEMF tight, Goto TagVisibility default-local, FF dimensional incorrect, or sector=7 startup unhandled.
- Visual 4-check before trusting numerical metrics: motor rotates / iq tracks reference / abc AC sinusoidal / Te energy balance. If any check fails, fix the implementation before computing 5-metric scores.
- Layout gate after build (MANDATORY, not advisory — prevents silent skip):
block_overlaps==0 is a HARD self-test (T7; build fails otherwise) + a mandatory human screenshot sign-off (same human-in-loop model as the Visual 4-check). Line-line crossings and line-through-block hits are SOFT (reported, NEVER numeric-gated): non-planar signal graphs (K3,3/K5) cannot reach zero crossings on a 2-D plane (Kuratowski), so reach zero only by restructuring (Subsystem encapsulation / Goto/From), never by hard-gating a count. See references/measurement_logger.md.
- One-click reproducibility: model must Run from
.slx double-click without prior script execution. Inject all parameters via set_param(mdl, 'InitFcn', ...).
- Don't guess conventions. dq is amplitude-invariant (factor 2/3); Anti_Park's internal
From "The" requires Goto_The TagVisibility='global'. See references/plant_modeling.md and references/building_blocks.md.
- PMSM block
RefAngle must be 'Aligned with phase A axis (original Park)'. R2024b sps_lib default is '90 degrees behind phase A axis (modified Park)', which rotates the plant dq frame 90° relative to the chart Park convention — a silent failure mode (motor drifts to wrong operating point, abc non-clean sinusoidal, id large drift, iq cannot track iq_ref). Either copy PMSM from shared/building_blocks/pmsm_blocks.slx (pre-set), or set_param([mdl '/PMSM'], 'RefAngle', 'Aligned with phase A axis (original Park)'). DTC αβ-frame methods exempt. See references/broken_foc_diagnostics.md F-CRIT 6.
Build Flow
| Phase |
Action |
Reference |
| 0 |
Validate params + sanity grid |
pre_build_grid.md |
| 1 |
Theory anchor (sign or AI-self-audit formulas) |
theory_anchor.md |
| 2 |
PMSM plant + InitFcn injection |
plant_modeling.md |
| 3 |
Building blocks (Park / Clarke / Anti_Park / SVPWM) |
building_blocks.md |
| 4 |
Control loop |
method-specific skill |
| 5 |
Modulation (FOC-based methods only; DTC skips) |
building_blocks.md |
| 6 |
Measurement + Logger |
measurement_logger.md |
| 7 |
Sanity check + Visual 4-check |
sanity_visual.md |
| 8 |
Solver + layout gate (T7 zero-overlap + screenshot sign-off) + save |
measurement_logger.md |
| 9 |
Idempotent self-tests |
measurement_logger.md |
If broken-FOC symptoms appear (motor stuck, abc DC-locked, iq permanently bang-bang), jump to broken_foc_diagnostics.md.
When to Use
| ✅ Use this skill |
❌ Skip |
| Starting a new PMSM control method study (sensorless, DTC-SVM, MP-DTC, deadbeat, MTPA, weak-field) |
Non-PMSM motors (induction / BLDC trapezoidal / SRM / DC) |
Designing your build script (conventionally named build_template.m) for a PMSM method |
Pure theory questions (dq frame, Park transform math) |
| Broken-FOC debugging (motor stalled, abc DC-locked, iq saturated) |
Method already covered by motor-fcs-mpc / motor-dtc-pmsm / motor-smc-pmsm (use the specific skill) |
| Need Phase 1.5 theory-anchor or Phase 4.5 sanity-check templates |
MATLAB performance tuning (use matlab-performance-optimizer) or unit tests (use matlab-test-creator) |
Known Limitations
- PMSM only (SPMSM / IPMSM). Induction motor / BLDC trapezoidal / SRM / DC are different plants.
- dq amplitude-invariant convention. Power-invariant requires extension.
- Three-phase 2-level VSI. Multilevel inverter / matrix converter out of scope.
- Nominal parameters. No robust / adaptive / online parameter ID.
- Ideal sensors. No encoder quantization or current sampling delay.
- No fault tolerance, no multi-motor coordination.
Method-specific Skills (Layered on This Base)
| Skill |
Method |
| motor-fcs-mpc |
Single-vector finite-control-set MPC current control |
| motor-dtc-pmsm |
Direct Torque Control with hysteresis switching table (Takahashi / Sutikno 6-state) |
| motor-smc-pmsm |
Sliding Mode Control speed-loop (PD-type sliding + super-twisting) |
External References
- Krause, Wasynczuk, Sudhoff (2013). Analysis of Electric Machinery and Drive Systems — PMSM dq modeling reference.
- Bose (2002). Modern Power Electronics and AC Drives — VSI + SVPWM reference.
- Slotine, Li (1991). Applied Nonlinear Control — Lyapunov-based design reference.
1---2name: motor-pmsm-base3description: PMSM Simulation Modeling Base — entry-point skill for building three-phase voltage-source-inverter-driven PMSM (SPMSM/IPMSM) control simulations in Simulink. Provides plant build standard, dq frame conventions, building blocks library SOP, sanity-check templates, broken-FOC defense checklist, and visual review standards. Method-specific skills (motor-fcs-mpc / motor-dtc-pmsm / motor-smc-pmsm) layer their control law on this base. Use when starting a new PMSM control method study, designing a build script skeleton, or debugging broken-FOC symptoms (motor stalled, abc DC-locked). Skip for non-PMSM motors (induction / BLDC / SRM) or pure theory questions.4---56# motor-pmsm-base — PMSM Simulation Modeling Base78Reusable plant + frame conventions + building blocks + sanity-check templates + broken-FOC defense + visual review standards for three-phase voltage-source-inverter-driven PMSM (SPMSM / IPMSM via parameterization). Method-specific control laws (FOC / FCS-MPC / DTC / SMC / sensorless / observer / MTPA / weak-field) layer on top of this base.910## Must-Follow Rules1112- **Use `shared/*` assets, do not duplicate.** `shared/formulas/pmsm_formulas.md` has signed-off plant equations and control law derivations. `shared/building_blocks/` provides verified atomic blocks. Reference them by path; do not re-derive or copy content.13- **Run pre-build sanity grid before any build.** See [references/pre_build_grid.md](references/pre_build_grid.md). Fail-fast when Vdc/BEMF tight, Goto TagVisibility default-local, FF dimensional incorrect, or sector=7 startup unhandled.14- **Visual 4-check before trusting numerical metrics**: motor rotates / iq tracks reference / abc AC sinusoidal / Te energy balance. If any check fails, fix the implementation before computing 5-metric scores.15- **Layout gate after build (MANDATORY, not advisory — prevents silent skip)**: `block_overlaps==0` is a HARD self-test (T7; build fails otherwise) + a mandatory human screenshot sign-off (same human-in-loop model as the Visual 4-check). Line-line crossings and line-through-block hits are SOFT (reported, NEVER numeric-gated): non-planar signal graphs (K3,3/K5) cannot reach zero crossings on a 2-D plane (Kuratowski), so reach zero only by restructuring (Subsystem encapsulation / Goto/From), never by hard-gating a count. See [references/measurement_logger.md](references/measurement_logger.md).16- **One-click reproducibility**: model must Run from `.slx` double-click without prior script execution. Inject all parameters via `set_param(mdl, 'InitFcn', ...)`.17- **Don't guess conventions.** dq is amplitude-invariant (factor 2/3); Anti_Park's internal `From "The"` requires `Goto_The TagVisibility='global'`. See [references/plant_modeling.md](references/plant_modeling.md) and [references/building_blocks.md](references/building_blocks.md).18- **PMSM block `RefAngle` must be `'Aligned with phase A axis (original Park)'`.** R2024b `sps_lib` default is `'90 degrees behind phase A axis (modified Park)'`, which rotates the plant dq frame 90° relative to the chart Park convention — a silent failure mode (motor drifts to wrong operating point, abc non-clean sinusoidal, `id` large drift, `iq` cannot track `iq_ref`). Either copy PMSM from `shared/building_blocks/pmsm_blocks.slx` (pre-set), or `set_param([mdl '/PMSM'], 'RefAngle', 'Aligned with phase A axis (original Park)')`. DTC αβ-frame methods exempt. See [references/broken_foc_diagnostics.md](references/broken_foc_diagnostics.md) F-CRIT 6.1920## Build Flow2122| Phase | Action | Reference |23|---|---|---|24| 0 | Validate params + sanity grid | [pre_build_grid.md](references/pre_build_grid.md) |25| 1 | Theory anchor (sign or AI-self-audit formulas) | [theory_anchor.md](references/theory_anchor.md) |26| 2 | PMSM plant + InitFcn injection | [plant_modeling.md](references/plant_modeling.md) |27| 3 | Building blocks (Park / Clarke / Anti_Park / SVPWM) | [building_blocks.md](references/building_blocks.md) |28| 4 | Control loop | method-specific skill |29| 5 | Modulation (FOC-based methods only; DTC skips) | [building_blocks.md](references/building_blocks.md) |30| 6 | Measurement + Logger | [measurement_logger.md](references/measurement_logger.md) |31| 7 | Sanity check + Visual 4-check | [sanity_visual.md](references/sanity_visual.md) |32| 8 | Solver + layout gate (T7 zero-overlap + screenshot sign-off) + save | [measurement_logger.md](references/measurement_logger.md) |33| 9 | Idempotent self-tests | [measurement_logger.md](references/measurement_logger.md) |3435If broken-FOC symptoms appear (motor stuck, abc DC-locked, iq permanently bang-bang), jump to [broken_foc_diagnostics.md](references/broken_foc_diagnostics.md).3637## When to Use3839| ✅ Use this skill | ❌ Skip |40|---|---|41| Starting a new PMSM control method study (sensorless, DTC-SVM, MP-DTC, deadbeat, MTPA, weak-field) | Non-PMSM motors (induction / BLDC trapezoidal / SRM / DC) |42| Designing your build script (conventionally named `build_template.m`) for a PMSM method | Pure theory questions (dq frame, Park transform math) |43| Broken-FOC debugging (motor stalled, abc DC-locked, iq saturated) | Method already covered by `motor-fcs-mpc` / `motor-dtc-pmsm` / `motor-smc-pmsm` (use the specific skill) |44| Need Phase 1.5 theory-anchor or Phase 4.5 sanity-check templates | MATLAB performance tuning (use `matlab-performance-optimizer`) or unit tests (use `matlab-test-creator`) |4546## Known Limitations4748- PMSM only (SPMSM / IPMSM). Induction motor / BLDC trapezoidal / SRM / DC are different plants.49- dq amplitude-invariant convention. Power-invariant requires extension.50- Three-phase 2-level VSI. Multilevel inverter / matrix converter out of scope.51- Nominal parameters. No robust / adaptive / online parameter ID.52- Ideal sensors. No encoder quantization or current sampling delay.53- No fault tolerance, no multi-motor coordination.5455## Method-specific Skills (Layered on This Base)5657| Skill | Method |58|---|---|59| [motor-fcs-mpc](../motor-fcs-mpc/SKILL.md) | Single-vector finite-control-set MPC current control |60| [motor-dtc-pmsm](../motor-dtc-pmsm/SKILL.md) | Direct Torque Control with hysteresis switching table (Takahashi / Sutikno 6-state) |61| [motor-smc-pmsm](../motor-smc-pmsm/SKILL.md) | Sliding Mode Control speed-loop (PD-type sliding + super-twisting) |6263## External References6465- Krause, Wasynczuk, Sudhoff (2013). *Analysis of Electric Machinery and Drive Systems* — PMSM dq modeling reference.66- Bose (2002). *Modern Power Electronics and AC Drives* — VSI + SVPWM reference.67- Slotine, Li (1991). *Applied Nonlinear Control* — Lyapunov-based design reference.
calebzu