# SR Analysis Pipeline — Handover Notes (2026-06-15)

## 交接人 → 接手人

### 当前管线状态

| 模块 | 状态 | 说明 |
|------|:----:|------|
| Illusion 0.75L + 1L phase-state + abs | **已验证** | 闭环 0.974 / 0.958，无动作历史，可进 PySR |
| Illusion 1.5L | **边界 case** | bang-bang 机制，线性 SINDy 不适用 |
| Karman phase-state + abs | **0.699** | 优于 deriv 模式，但低于旧 v23 的 0.901 |
| Karman old v23 (a_lag) | **0.901** | 保留作基线对照 |
| Karman 泛化测试 | **已完成** | Re70/150/300/25 约 0.54-0.60 |
| PySR 符号回归 | **有 shell** | 需要修复 run_pysr.py 后重新跑 |
| Vortex 偏移扩展 | **未做** | 低优先级 |

### 核心文件改动（2026-06-14~15）

| 文件 | 改动类型 |
|------|----------|
| `utils/feature_builder.py` | **新增** PHASE_STATE_KEYS, ILLUSION_PHASE_KEYS, KARMAN_EXPANDED_KEYS, obs dynamics, error-state, mu_Cl_tot |
| `utils/sindy_fitter.py` | **新增** compute_action_deriv, get_feature_matrix_deriv(output_mode) |
| `sindy/run_all_v2.py` | **新增** --deriv, --phase, --karman-expand, --karman-mu, --output-mode, --augment-level CLI |
| `validate/run_closed_loop.py` | **新增** predict_v23_deriv, mode="abs", load_sindy_coefs返回mode |
| `validate/run_closed_loop_illusion.py` | **修改** 支持 predict_v23_deriv, 自动检测模式 |
| `validate/eval_rollout.py` | **新文件** 离线多步 rollout 评估 |
| `scripts/plot_sr_results.py` | **新文件** 结果可视化图表 |
| `docs/SR_analysis_results.md` | **新文件** 完整分析报告 |
| `docs/figures/SR_analysis/fig*.png` | **新文件** 6 张图表 |

### 关键设计决策（接手前必读）

1. **phase-state 特征** = `u_a, du_a/dt, Cl_tot, dCl_tot/dt, Cd_tot, Cd_rear` (6维)
2. **ILLUSION_PHASE_KEYS** = phase-state + `Cd_err, Cl_err, dCd_err/dt, dCl_err/dt` (10维)
3. **绝对动作输出** `output_mode="absolute"` 优于导数 `"deriv"`，无积分累积
4. **v23 结构**始终默认：front no-bias, rear shared-head
5. **时间一阶导**统一除以 `dt_c = SAMPLE_INTERVAL/2000`，跨场景可比较
6. `controlled.npz` 中新加了 `target_forces` 字段，illusion 场景必须有
7. **FIFO bias ≠ DRL action bias**，1U vs 2U 不要混淆

### 常用命令速查

```bash
# 拟合 + 验证 Illusion phase-state + absolute (完整流程)
conda run -n pycuda_3_10 python src/SR_analysis/sindy/run_all_v2.py \
    --scenes illusion_0.75L,illusion_1L --deriv --phase --output-mode absolute
conda run -n pycuda_3_10 python src/SR_analysis/validate/run_closed_loop_illusion.py \
    --scene illusion_0.75L --device 0 --steps 320 \
    --sindy-results src/SR_analysis/sindy/illusion/sindy_results_deriv.json

# 拟合 + 验证 Karman phase-state + absolute
conda run -n pycuda_3_10 python src/SR_analysis/sindy/run_all_v2.py \
    --scenes karman_re100 --deriv --phase --output-mode absolute
conda run -n pycuda_3_10 python src/SR_analysis/validate/run_closed_loop.py \
    --scene karman_re100 --device 0 --steps 200 --mode abs \
    --sindy-results src/SR_analysis/sindy/karman/sindy_results_deriv.json

# 离线 rollout 评估
python3 src/SR_analysis/validate/eval_rollout.py \
    --sindy-results src/SR_analysis/sindy/karman/sindy_results_deriv.json \
    --scene karman_re100

# PySR (需要先修复滞后的 bug！)
conda run -n sr_env python src/SR_analysis/sindy/run_pysr.py --scene illusion_1L

# 画图
python3 scripts/plot_sr_results.py
```

### 目前最适合推进的方向

1. **Illusion PySR 符号回归**（0.75L + 1L separate → 公式比较）
2. **Karman 状态补强**（配合 CCD/OID 分析找出缺失的状态量，再回 SR）
3. **Karman 跨 Re 联合**（在 phase-state + mu 基础上做跨 Re 联合拟合 + 泛化）

### 注意重新运行 run_pysr.py

当前 `run_pysr.py` 有路径/导入问题，接手后需先确认：
- `env_sr` 或 `sr_env` 环境内的 PySR 可用性
- whitelist 特征与 `controlled.npz` 中的字段匹配（特别是 illusion 的 `target_forces`）
- 滞后构造正确（`a_prev[1:] = actions_phys[:-1]`）