Coding Project 4 - Sensorless Position Estimation via Active Flux Observer

Background Theory / Observer = Prediction + Innovation

From flux to position to speed: the sensorless chain从磁链到位置到转速：无传感器的推导链

Step 1 — Voltage model gives stator flux (Prediction)第一步 — 电压模型给出定子磁链（Prediction）

The stator voltage equation of a PMSM in the stationary $\alpha\beta$ frame can be rearranged as: PMSM 在静止 $\alpha\beta$ 坐标系下的定子电压方程可以改写为：

$$\frac{d\hat{\boldsymbol{\psi}}_s}{dt} = \mathbf{u}_s - R \, \mathbf{i}_s$$

This is a pure prediction: given the measured voltage $\mathbf{u}_s$ and current $\mathbf{i}_s$, integrate to get the stator flux. This is the open-loop integrator. Its problem: any error in $R$, any voltage offset, or any initial condition error will accumulate over time indefinitely. 这是一个纯预测（prediction）：利用测量的电压 $\mathbf{u}_s$ 和电流 $\mathbf{i}_s$ 进行积分，得到定子磁链。这就是开环积分器。它的问题：$R$ 的任何估计误差、任何电压偏置、或初值误差都会无限期累积。

Step 2 — Active flux extracts rotor position第二步 — Active flux 提取转子位置

For an SPMSM ($L_d = L_q = L$), the active flux is defined as: 对于表贴式 PMSM（$L_d = L_q = L$），有功磁链（active flux）定义为：

$$\hat{\boldsymbol{\psi}}_{\text{AF}} = \hat{\boldsymbol{\psi}}_s - L \, \mathbf{i}_s$$

In steady state, the active flux equals the PM flux linkage vector $\psi_{\text{PM}}$, whose direction is the rotor position: 稳态下，active flux 等于永磁磁链向量 $\psi_{\text{PM}}$，其方向就是转子位置：

$$\hat{\theta}_r = \text{atan2}\!\left(\hat{\psi}_{\text{AF},\beta},\;\hat{\psi}_{\text{AF},\alpha}\right)$$

Step 3 — Speed from position differentiation第三步 — 位置微分得到转速

Once you have the estimated electrical angle $\hat{\theta}_r$ at each control step, the electrical angular velocity is obtained by differentiating and low-pass filtering: 一旦在每个控制周期获得了估计电角度 $\hat{\theta}_r$，电角速度就可以通过微分加低通滤波获得：

$$\hat{\omega}_e = \text{LPF}\!\left(\frac{\Delta\hat{\theta}_r}{\Delta t}\right), \qquad \hat{n}_{\text{rpm}} = \frac{\hat{\omega}_e}{2\pi \cdot n_{pp}} \times 60$$

This is a derived quantity: the speed is not estimated by the observer directly — it is computed from the estimated position. The quality of the speed estimate depends entirely on the quality of the position estimate. 这是一个派生量：转速不是观测器直接估计的——而是从估计位置计算出来的。转速估计的质量完全取决于位置估计的质量。

Step 4 — PI correction is the Innovation第四步 — PI 校正就是 Innovation

Key insight: every observer = prediction + innovation核心洞察：所有观测器 = prediction + innovation The open-loop integrator only has prediction — no innovation. The active flux observer adds a PI correction term that acts as the innovation: it compares the estimated active flux amplitude $|\hat{\boldsymbol{\psi}}_{\text{AF}}|$ against the known PM flux constant $\psi_{\text{PM}}$, and uses the error to correct the integration. 开环积分器只有 prediction —— 没有 innovation。Active flux 观测器增加了一个 PI 校正项作为 innovation：它将估计的 active flux 幅值 $|\hat{\boldsymbol{\psi}}_{\text{AF}}|$ 与已知的永磁磁链常数 $\psi_{\text{PM}}$ 比较，用误差来校正积分。

Although $\boldsymbol{\psi}_s$ cannot be measured directly, we know its amplitude constraint: $|\boldsymbol{\psi}_{\text{AF}}| = \psi_{\text{PM}}$. This known constant serves as an "indirect measurement": 虽然 $\boldsymbol{\psi}_s$ 不能直接测量，但我们知道一个幅值约束：$|\boldsymbol{\psi}_{\text{AF}}| = \psi_{\text{PM}}$。这个已知常数充当了"间接测量"：

$$\underbrace{\frac{d\hat{\boldsymbol{\psi}}_s}{dt} = \mathbf{u}_s - R\,\mathbf{i}_s}_{\text{prediction}} \;+\; \underbrace{\left[K_p\,e + K_i\!\int\!e\,dt\right] \cdot \hat{\mathbf{n}}_{\text{AF}}}_{\text{innovation (PI correction)}}$$

where $e = \psi_{\text{PM}} - |\hat{\boldsymbol{\psi}}_{\text{AF}}|$ is the amplitude error, and $\hat{\mathbf{n}}_{\text{AF}}$ is the unit vector along $\hat{\boldsymbol{\psi}}_{\text{AF}}$. 其中 $e = \psi_{\text{PM}} - |\hat{\boldsymbol{\psi}}_{\text{AF}}|$ 是幅值误差，$\hat{\mathbf{n}}_{\text{AF}}$ 是 $\hat{\boldsymbol{\psi}}_{\text{AF}}$ 方向的单位向量。

P term — why?P 项 — 为什么需要？

Provides immediate restoring force when the flux amplitude drifts from $\psi_{\text{PM}}$. Like a spring: the farther it drifts, the harder it pulls back. 当磁链幅值偏离 $\psi_{\text{PM}}$ 时，立刻提供恢复力。就像弹簧：偏得越远，拉力越大。

I term — why?I 项 — 为什么需要？

Eliminates steady-state drift caused by constant errors (wrong $R$, voltage offsets). Without it, P alone leaves a residual error. This is exactly analogous to the integral action in a speed PI regulator that eliminates speed static error. 消除由恒定误差（$R$ 不准、电压偏置）导致的稳态漂移。没有它，仅靠 P 项会留下残差。这和速度 PI 调节器中积分项消除静差的原理完全一样。

Summary: the sensorless estimation chain总结：无传感器估计链

Stage阶段	What is computed计算什么	Equation / method方程/方法
1. Flux integration	Stator flux $\hat{\boldsymbol{\psi}}_s$定子磁链 $\hat{\boldsymbol{\psi}}_s$	$d\hat{\boldsymbol{\psi}}_s/dt = \mathbf{u}_s - R\mathbf{i}_s + \text{correction}$
2. Active flux	$\hat{\boldsymbol{\psi}}_{\text{AF}}$	$\hat{\boldsymbol{\psi}}_s - L_q \, \mathbf{i}_s$
3. Position	Rotor angle $\hat{\theta}_r$转子角度 $\hat{\theta}_r$	$\text{atan2}(\hat{\psi}_{\text{AF},\beta},\, \hat{\psi}_{\text{AF},\alpha})$
4. Speed	$\hat{\omega}_r$	$\text{LPF}(\Delta\hat{\theta}_r / \Delta t)$$\text{LPF}(\Delta\hat{\theta}_r / \Delta t)$

Project Goal / What You Must Show

Show why open-loop integration fails and how PI correction saves it说明开环积分为何失败，PI 校正如何挽救

Your final report should demonstrate through simulation evidence that: 你的最终报告需要通过仿真证据说明：

You must investigate你必须研究

position estimation accuracy: Active Flux observer vs open-loop integrator位置估计精度：Active Flux 观测器 vs 开环积分器
speed estimation quality derived from estimated position从估计位置推导的转速估计质量
effect of parameter mismatch ($R$ error, voltage offset) on both methods参数失配（$R$ 误差、电压偏置）对两种方法的影响
flux trajectory in $\alpha\beta$ plane: circle vs drift$\alpha\beta$ 平面磁链轨迹：圆形 vs 漂移
role of PI gains ($K_p$, $K_i$) in the observer观测器中 PI 增益（$K_p$, $K_i$）的作用

Conceptual understanding required需要理解的概念

Why every observer is prediction + innovation为什么所有观测器都是 prediction + innovation
What serves as the "indirect measurement" when flux is unmeasured当磁链不可测时，什么充当了"间接测量"
How speed is a derived quantity from position, not a direct estimate转速是如何从位置派生出来的，而非直接估计
Why DC drift is the fundamental problem of pure integration为什么直流漂移是纯积分的根本问题

Core deliverable核心交付物 Use figures and short quantitative analysis to convince the reader that you understand why the open-loop integrator drifts, how the PI correction prevents drift, and how speed is obtained from the estimated position angle. 用图和简洁的定量分析，让读者相信你真正理解了开环积分器为什么会漂移、PI 校正如何防止漂移、以及转速如何从估计位置角度中获得。

Setup / Run the Demo

How to run the experiment如何运行实验

The demo script runs two observers (Active Flux + open-loop) in parallel on the same motor simulation and saves comparison plots automatically: Demo 脚本在同一个电机仿真上并行运行两个观测器（Active Flux + 开环），自动保存对比图：

git clone https://github.com/horychen/ee275.git
cd ee275
python demo_eso.py

Direct GitHub link: demo_eso.py GitHub 链接：demo_eso.py

The script deliberately introduces parameter mismatch to simulate real-world conditions: 脚本故意引入参数失配来模拟真实工况：

$R$ mismatch

Observer uses $R_{\text{obs}} = 1.5 \times R_{\text{true}}$ (50% overestimation — simulates temperature drift)观测器使用 $R_{\text{obs}} = 1.5 \times R_{\text{true}}$（高估 50%——模拟温度漂移）

Voltage offset电压偏置

$\alpha$: +20 mV, $\beta$: −15 mV (simulates inverter deadzone / ADC offset)$\alpha$: +20 mV, $\beta$: −15 mV（模拟逆变器死区/ADC 偏移）

Speed profile转速命令

Ramp → hold → load step → reversal, over 2 seconds斜坡 → 保持 → 加载 → 反转，共 2 秒

Important design note重要设计说明 The motor is always controlled by the true encoder (sensored FOC). The two observers run in open loop alongside, so you can objectively evaluate their accuracy without instability from feeding back a bad estimate. 电机始终由真实编码器控制（有传感器 FOC）。两个观测器是并行开环运行的，这样你可以客观地评估它们的精度，而不用担心反馈不良估计导致不稳定。

Code Map / Where the Observer Lives

Read these places before editing动手前先看这些位置

File / function文件/函数	What to inspect看什么	Relation to theory与理论的对应
`demo_eso.py`	`run_sensorless_demo()` — the main simulation loop with both observers`run_sensorless_demo()` — 包含两个观测器的主仿真循环	Contains the complete prediction + innovation structure. Start here.包含完整的 prediction + innovation 结构。从这里开始。
Observer (A) Active Flux观测器 (A) Active Flux	Lines with `af_psi_s`, `af_corr_int`, `psi_af_error`搜索 `af_psi_s`、`af_corr_int`、`psi_af_error`	Prediction: flux integration. Innovation: PI on $\|\hat{\psi}_{\text{AF}}\| - \psi_{\text{PM}}$Prediction：磁链积分。Innovation：PI 作用于 $\|\hat{\psi}_{\text{AF}}\| - \psi_{\text{PM}}$
Observer (B) Open-loop int.观测器 (B) 开环积分器	Lines with `ol_psi_s`搜索 `ol_psi_s`	Prediction only — no innovation. Same wrong $R$, same voltage offsets, but no correction.只有 Prediction——没有 innovation。同样的 $R$ 错误、同样的电压偏置，但没有修正。
Speed estimation转速估计	`d_theta_af`, `lpf_alphad_theta_af`、`lpf_alpha`	$\hat{\omega} = \text{LPF}(\Delta\hat{\theta}/\Delta t)$ — speed is derived from position, not estimated independently.$\hat{\omega} = \text{LPF}(\Delta\hat{\theta}/\Delta t)$ — 转速是从位置派生的，不是独立估计的。
`tutorials_ep6_svpwm.py`	Motor model, FOC loop, `ACMSimPyIncremental`电机模型、FOC 循环、`ACMSimPyIncremental`	Provides the plant simulation. You don't need to modify this file.提供被控对象仿真。你不需要修改这个文件。

Where does "position → speed" happen in code?代码中"位置 → 转速"在哪里？ Search for d_theta_af in the demo script. You will see: raw_omega_af = d_theta_af / CL_TS followed by a first-order LPF. This is exactly the chain: flux → active flux → angle → differentiate → filter → speed. The speed is not a state of the observer — it is computed after the position is obtained. 在 demo 脚本中搜索 d_theta_af。你会看到：raw_omega_af = d_theta_af / CL_TS，后面跟一个一阶低通滤波。这正是推导链：磁链 → active flux → 角度 → 微分 → 滤波 → 转速。转速不是观测器的状态——而是在获得位置之后计算出来的。

Experiments / Minimum Work

Complete these four experiment blocks完成这四组实验

Part A — Baseline comparison at medium speedPart A — 中速基线对比

Run the default demo (200 rpm with ramp, hold, load, reversal). Compare the angle estimates from both observers against the encoder truth. Report the RMS angle error for each method. Observe the flux trajectories in the $\alpha\beta$ plane. 运行默认 demo（200 rpm，包含斜坡、保持、加载、反转）。比较两个观测器的角度估计与编码器真值。报告每种方法的 RMS 角度误差。观察 $\alpha\beta$ 平面的磁链轨迹。

Part B — Effect of R mismatchPart B — R 失配的影响

Vary R_mismatch_factor (e.g., 1.0, 1.5, 2.0). With factor=1.0, both observers should work well. As the factor increases, show how the open-loop integrator degrades rapidly while the Active Flux observer still maintains accuracy thanks to the PI correction. 改变 R_mismatch_factor（例如 1.0, 1.5, 2.0）。factor=1.0 时两种方法都应该表现不错。随着 factor 增大，展示开环积分器如何迅速恶化，而 Active Flux 观测器由于 PI 校正仍然保持精度。

Part C — PI gain tuningPart C — PI 增益调节

Vary the observer PI gains (af_Kp, af_Ki). Try at least three settings: (small, small), (default), and (large, large). Observe the tradeoff: too small → slow correction, residual drift; too large → oscillation or noise amplification. 改变观测器 PI 增益（af_Kp, af_Ki）。至少尝试三种设置：（小, 小）、（默认）、（大, 大）。观察折中：太小 → 修正慢、残差漂移；太大 → 振荡或噪声放大。

Part D — Speed estimation analysisPart D — 转速估计分析

Focus on the speed estimation subplot. Explain how the estimated speed is derived from the angle estimate via differentiation + LPF. Discuss: at what operating conditions does the speed estimate degrade? Try running at a lower speed command (e.g., 30 rpm) and compare the quality. 关注转速估计子图。解释估计转速如何通过角度微分 + 低通滤波得到。讨论：在什么工况下转速估计会变差？尝试更低的速度命令（如 30 rpm），比较估计质量。

How to modify the demo parameters如何修改 demo 参数 All tunable parameters are passed as arguments to run_sensorless_demo() at the bottom of the script. You can directly edit the values in the if __name__ == '__main__' block: 所有可调参数都在脚本底部的 run_sensorless_demo() 调用中。你可以直接在 if __name__ == '__main__' 块中修改：

results = run_sensorless_demo(
    d,
    af_Kp=500.0,               # ← try 50, 500, 5000
    af_Ki=5000.0,              # ← try 500, 5000, 50000
    R_mismatch_factor=1.5,     # ← try 1.0, 1.5, 2.0, 3.0
    voltage_offset_alpha=0.02, # ← try 0, 0.02, 0.1
    voltage_offset_beta=-0.015,
)

Required Figures / Final PDF

The final PDF must contain these 4 figures最终 PDF 必须包含这 4 张图

Figure图	What to plot画什么	What to discuss要讨论什么
Figure 1	Angle estimation comparison: encoder truth vs Active Flux estimate vs open-loop estimate (time domain). Include the angle error subplot.角度估计对比：编码器真值 vs Active Flux 估计 vs 开环估计（时域）。包含角度误差子图。	Quantify RMS angle error for both methods. Explain why the open-loop integrator error grows over time while the Active Flux error stays bounded.量化两种方法的 RMS 角度误差。解释为什么开环积分器误差随时间增长而 Active Flux 误差保持有界。
Figure 2	Flux trajectories in the $\alpha\beta$ plane for both observers: Active Flux (should be a clean circle) vs open-loop (should show DC offset / spiral).两个观测器在 $\alpha\beta$ 平面的磁链轨迹：Active Flux（应为圆形）vs 开环（应显示直流偏移/螺旋）。	Use this figure to explain the "indirect measurement" concept: the PI correction maintains the circle radius at $\psi_{\text{PM}}$, while the open-loop integrator's circle drifts away from the origin.用此图解释"间接测量"概念：PI 校正维持圆半径为 $\psi_{\text{PM}}$，而开环积分器的圆从原点偏移。
Figure 3	Speed estimation comparison: true speed vs Active Flux-derived speed vs open-loop-derived speed. Include the speed command.转速估计对比：真实转速 vs Active Flux 推导转速 vs 开环推导转速。包含速度指令。	Explain how speed is obtained from position via differentiation + LPF. Discuss the delay introduced by the LPF and how it affects the accuracy during transients (ramp, reversal).解释转速如何通过位置微分 + 低通滤波获得。讨论低通滤波引入的延迟及其在暂态（斜坡、反转）中对精度的影响。
Figure 4	Effect of R mismatch: show angle error comparison for at least two different `R_mismatch_factor` values (e.g., 1.0 and 2.0).R 失配的影响：展示至少两个不同 `R_mismatch_factor`（如 1.0 和 2.0）下的角度误差对比。	Demonstrate that the Active Flux observer remains robust to R error while the open-loop integrator's performance degrades proportionally. Connect this to the role of PI integral action in compensating for steady-state drift.说明 Active Flux 观测器对 R 误差保持鲁棒性，而开环积分器的性能成比例恶化。将这一现象与 PI 积分项补偿稳态漂移的作用联系起来。

Important requirement重要要求 These four figures are the minimum. Every figure must have a caption and at least 2–4 sentences of interpretation. Do not submit screenshots only. 这四张图是最低要求。每张图都必须有图注，并附带至少 2–4 句解释。不要只提交截图。

Analysis Questions / What Your Report Must Answer

Use your figures to answer these questions基于你的图回答这些问题

Q1

An observer can always be decomposed as prediction + innovation. In the active flux observer, the flux state $\boldsymbol{\psi}_s$ is not directly measurable. How is the innovation implemented? What serves as the "indirect measurement"? 观测器永远可以分解为 prediction + innovation。在 active flux 观测器中，磁链状态 $\boldsymbol{\psi}_s$ 不可直接测量。Innovation 是如何实现的？什么充当了"间接测量"？

Q2

The PI correction term has a P part and an I part. What does each do physically? What happens if you remove the I term entirely (set af_Ki=0)? What happens if you remove the P term (set af_Kp=0)? PI 校正项有 P 和 I 两部分。每部分在物理上做什么？如果完全去掉 I 项（设 af_Ki=0）会怎样？如果去掉 P 项（设 af_Kp=0）呢？

Q3

The speed estimate is not a state of the observer. How is it obtained? In the code, find the line where speed is computed from position. Explain why a low-pass filter is needed and what happens if the filter time constant lpf_tau is too large or too small. 转速估计不是观测器的状态。它是怎么获得的？在代码中找到从位置计算转速的那行代码。解释为什么需要低通滤波，以及滤波时间常数 lpf_tau 太大或太小会怎样。

Q4

Look at the $\alpha\beta$ flux trajectory plots. Why does the Active Flux observer maintain a circle while the open-loop integrator does not? Connect this to the physics of the correction term. 看 $\alpha\beta$ 磁链轨迹图。为什么 Active Flux 观测器保持圆形而开环积分器不行？将这与校正项的物理含义联系起来。

Q5

Why does the open-loop integrator fail in practice even when the motor model is "correct"? What real-world error sources cause the DC drift? (Hint: think about $R$, voltage measurement, inverter dead time, ADC offset.) 为什么开环积分器即使在电机模型"正确"时也会在实际中失效？哪些真实世界的误差源导致了直流漂移？（提示：考虑 $R$、电压测量、逆变器死区、ADC 偏移。）

Q6

At very low speed, the back-EMF becomes very small. How does this affect the quality of the flux-based position estimate? Run the demo at 30 rpm or lower and compare with the 200 rpm case. Why is low-speed sensorless control fundamentally more challenging? 在极低转速下，反电动势变得很小。这对基于磁链的位置估计精度有什么影响？在 30 rpm 或更低转速下运行 demo 并与 200 rpm 情况对比。为什么低速无传感器控制从根本上更具挑战性？

Good reports do this好报告会这样写 Do not only write "the Active Flux observer works better." Explain why it works — what signal provides the correction, what the P and I terms each contribute, and where the method starts to struggle (hint: low speed, large R error). Connect every observation to the prediction + innovation structure. 不要只写"Active Flux 观测器更好"。要解释为什么它有效——什么信号提供了修正，P 和 I 项各起什么作用，以及该方法从哪里开始吃力（提示：低速、大 R 误差）。将每一个现象都与 prediction + innovation 结构对应起来。

Report / PDF Only

Suggested PDF structure建议的 PDF 结构

Recommended outline推荐提纲

Introduction and theory: voltage model, active flux, position → speed chain引言与理论：电压模型、active flux、位置 → 转速推导链
Observer structure: prediction + innovation, PI correction explained观测器结构：prediction + innovation，PI 校正说明
Figure 1–4 with interpretation图 1–4 及分析
Answers to Q1–Q6Q1–Q6 的回答
Conclusion: when Active Flux works, where it struggles, and what the open-loop integrator teaches us about the necessity of innovation结论：Active Flux 什么时候好用、在哪里吃力，以及开环积分器如何告诉我们 innovation 的必要性

Checklist before export导出 PDF 前检查

All 4 required figures are present with captions.4 张必做图齐全，有图注。

Axes, units, and legends are readable.坐标轴、单位和图例清楚可读。

The prediction + innovation decomposition is clearly explained.prediction + innovation 分解有清楚的说明。

The "position → speed" derivation chain is explained with code reference."位置 → 转速"推导链有代码对应说明。

RMS angle error numbers are reported for at least two scenarios.至少两个场景报告了 RMS 角度误差数值。

The report discusses why open-loop integration fails and how PI correction fixes it.报告讨论了开环积分为何失败以及 PI 校正如何修复。