feat: eval benchmark + cloud-trained models replace train/

- eval/: 统一推理评估框架 (infer_train.py, infer_reproduce.py, viz_flow.py, viz_signals.py, generate_report.py, run_all.sh, scene_manifest.py) - train/: 替换为云端正式训练产出，覆盖 11 个场景 - Karman: Re100 (5 seeds), Re60/200/400 transfer - VarDist: d075/d15/d2 scratch - Illusion: 0.75L/1.0L/1.5L/2.0L scratch - train_karman.py: 新增 --resume-from 断点续训支持 - calibrations: 17 组标定数据 (kar/ill 命名规范) - scripts/: 7 个自动化训练脚本 - 清理旧 calibrations/shell scripts/visualize Co-authored-by: Cursor <cursoragent@cursor.com>
2026-07-12 23:56:02 +08:00
parent f2f88c2442
commit 4feac49f1c
52 changed files with 4053 additions and 1341 deletions
@@ -0,0 +1,221 @@
+# DynamisLab — 训练目录
+
+> `src/drl_pinball/train/`  
+> 更新: 2026-07-12
+
+---
+
+## 命名规则
+
+```
+{domain}_{variant}_{method}_seed{seed}
+
+domain:  kar = Karman  |  ill = Illusion
+variant: re{60,100,200,400} = 雷诺数  |  d{075,15,2} = 扰动圆柱直径(L)  |  {1L,15L,075L,2L} = 目标圆柱尺寸
+method:  sc = from scratch  |  tr = transfer from re100 baseline
+seed:    seed{41..45}
+
+Examples:
+  kar_re100_sc_seed45   — Karman Re100 scratch, seed 45
+  kar_d075_sc_seed44    — Karman 0.75L dist-cyl scratch
+  kar_d15_tr_seed45     — Karman 1.5L dist-cyl transfer
+  kar_re200_sc_seed43   — Karman Re200 scratch
+  ill_2L_sc_seed43      — Illusion 2L target scratch
+```
+
+---
+
+## 目录结构
+
+```
+train/
+├── train_karman.py              # Karman PPO 训练 (核心)
+├── train_illusion.py            # Illusion PPO 训练
+├── calibrate.py                 # Phase 0 校准
+│
+├── env_karman.py                # Karman 环境
+├── env_illusion.py              # Illusion 环境
+├── symmetry_wrapper.py          # G-symmetry 数据增强
+│
+├── scripts/                     # 启动脚本
+│   ├── train_baseline.sh        # kar_re100_sc multi-seed
+│   ├── train_illusion.sh        # ill_*_sc 4 个尺寸
+│   ├── vardist_scratch.sh       # kar_d*_sc (推荐)
+│   ├── vardist_transfer.sh      # kar_d*_tr (参考)
+│   ├── crossre_scratch.sh       # kar_re*_sc
+│   ├── crossre_transfer.sh      # kar_re*_tr (参考)
+│   └── resume.sh                # 中断恢复
+│
+├── calibrations/                # 校准文件
+│   ├── kar_re100/               # Re100 基准
+│   ├── kar_d*_sc/               # 变直径 scratch (generic SIM_BP)
+│   ├── kar_d*_tr/               # 变直径 transfer (实测 SIM_BP)
+│   ├── kar_re*_sc/              # 变雷诺数 scratch (generic SIM_BP)
+│   ├── kar_re*/                 # 变雷诺数 transfer (实测 SIM_BP)
+│   └── ill_*/                   # Illusion
+│
+├── output/                      # 训练输出 (21 dirs)
+│   ├── kar_re100_sc_seed{41..45}/
+│   ├── kar_d*_sc_seed{44,45}/
+│   ├── kar_d*_tr_seed{44,45}/
+│   ├── kar_re*_sc_seed43/
+│   ├── kar_re*_tr_seed43/
+│   └── ill_*_sc_seed43/
+│
+├── archive/                     # 旧版本 (保留)
+├── README.md                    # 当前文件
+├── VARDIST_ANALYSIS.md
+├── CROSSRE_ANALYSIS.md
+└── SERVER_DEPLOY.md
+```
+
+---
+
+## 快速开始
+
+### 基准训练
+
+```bash
+cd scripts
+bash train_baseline.sh --gpu 0 --episodes 500
+# → output/kar_re100_sc_seed{41..45}/
+```
+
+### 变直径 scratch (推荐)
+
+```bash
+cd scripts
+bash vardist_scratch.sh --gpu 0
+bash vardist_scratch.sh --only d075
+# → output/kar_d075_sc_seed44/  etc.
+```
+
+### 变雷诺数 scratch
+
+```bash
+cd scripts
+bash crossre_scratch.sh --gpu 0
+bash crossre_scratch.sh --only re200
+# → output/kar_re200_sc_seed43/  etc.
+```
+
+### Illusion
+
+```bash
+cd scripts
+bash train_illusion.sh --gpu 0
+# → output/ill_2L_sc_seed43/  etc.
+```
+
+### 中断恢复
+
+```bash
+cd scripts
+bash resume.sh --case kar_re60_sc --seed 43 --resume 460 --episodes 500
+```
+
+---
+
+## 核心训练脚本
+
+### `train_karman.py`
+
+```bash
+conda run -n pycuda_3_10 python -u train_karman.py \
+    --case-name kar_re100_sc --device-id 0 --seed 42 \
+    --config config.json --calibration calibrations/kar_re100/calibration.json \
+    --total-episodes 500 [--transfer-model PATH] [--resume-from N]
+```
+
+| 参数 | 默认值 | 说明 |
+|------|:-----:|------|
+| n_steps | 2048 | PPO 每轮收集步数 |
+| batch_size | 64 | minibatch |
+| n_epochs | 10 | 经验重用次数 |
+| lr | 3e-4 | 学习率 |
+| gamma | 0.995 | 折扣因子 |
+| net_arch | [64, 64] | MLP 两层 sin 激活 |
+
+---
+
+## 最终结果
+
+### Re100 基准 — `kar_re100_sc`
+
+| Seed | r_sim | r_cd | r_cl |
+|:----:|:-----:|:----:|:----:|
+| 45 | 0.883 | 0.977 | 0.982 |
+| Avg | 0.866 | 0.971 | 0.965 |
+
+### Vardist 变直径
+
+| Case | 方式 | r_sim | r_cd | r_cl |
+|------|:----:|:-----:|:-----:|:-----:|
+| **kar_d075_sc** | scratch | **0.918** | 0.954 | 0.879 |
+| kar_d075_tr | transfer | 0.450 | 0.585 | 0.236 |
+| **kar_d15_sc** | scratch | **0.904** | 0.991 | 0.992 |
+| kar_d15_tr | transfer | 0.791 | 0.918 | 0.470 |
+| **kar_d2_sc** | scratch | **0.793** | 0.967 | 0.961 |
+| kar_d2_tr | transfer | 0.673 | 0.537 | 0.192 |
+
+> Scratch 全面领先 transfer。
+
+### Cross-Re 变雷诺数
+
+| Case | 方式 | r_sim | r_cd | r_cl |
+|------|:----:|:-----:|:-----:|:-----:|
+| kar_re60_tr | transfer | 0.446 | **0.882** | 0.936 |
+| kar_re60_sc | scratch | 0.261 | **0.987** | 0.981 |
+| **kar_re200_sc** | scratch | **0.664** | 0.667 | 0.281 |
+| kar_re200_tr | transfer | 0.374 | 0.749 | 0.427 |
+| **kar_re400_sc** | scratch | **0.509** | 0.714 | 0.420 |
+| kar_re400_tr | transfer | 0.293 | 0.883 | 0.571 |
+
+> Scratch sim 最优，transfer CD 最优。两者均保留。
+
+### Illusion
+
+| Case | r_sim | r_cd | r_cl |
+|------|:-----:|:-----:|:-----:|
+| ill_1L_sc | 0.725 | 0.774 | 0.449 |
+| ill_15L_sc | 0.810 | 0.825 | 0.384 |
+| ill_075L_sc | 0.794 | 0.840 | 0.486 |
+| **ill_2L_sc** | **0.896** | 0.863 | 0.570 |
+
+---
+
+## Calibration 参考
+
+| Calibration | 物理 | SI | SIM_BP | K_CD/K_CL | 对应 output |
+|------------|------|:--:|--------|:---------:|------------|
+| `kar_re100` | Re=100, 1.0L | 800 | 实测 | 50/100 | `kar_re100_sc` |
+| `kar_d075_sc` | Re=100, 0.75L | 800 | generic | 50/100 | `kar_d075_sc` |
+| `kar_d075_tr` | Re=100, 0.75L | 800 | 实测 | 50/100 | `kar_d075_tr` |
+| `kar_d15_sc` | Re=100, 1.5L | 800 | generic | 50/100 | `kar_d15_sc` |
+| `kar_d15_tr` | Re=100, 1.5L | 800 | 实测 | 50/100 | `kar_d15_tr` |
+| `kar_d2_sc` | Re=100, 2.0L | 800 | generic | 50/100 | `kar_d2_sc` |
+| `kar_d2_tr` | Re=100, 2.0L | 800 | 实测 | 50/100 | `kar_d2_tr` |
+| `kar_re60` | Re=60 | 800 | 实测 | 12/25 | `kar_re60_tr` |
+| `kar_re60_sc` | Re=60 | 800 | generic | 50/100 | `kar_re60_sc` |
+| `kar_re200` | Re=200 | 500 | 实测 | 12/25 | `kar_re200_tr` |
+| `kar_re200_sc` | Re=200 | 500 | generic | 50/100 | `kar_re200_sc` |
+| `kar_re400` | Re=400 | 400 | 实测 | 12/25 | `kar_re400_tr` |
+| `kar_re400_sc` | Re=400 | 400 | generic | 50/100 | `kar_re400_sc` |
+| `ill_*` | Illusion | — | 实测 | 12/25 | `ill_*_sc` |
+
+---
+
+## Key Findings
+
+1. **SIM_BP 映射是跨场景训练的最关键变量。** 实测 gap ≠ 0.35 会导致 reward 梯度异常。
+   - Generic SIM_BP `[0, 0.30, 0.65, 0.79, 0.89, 1.0]` (gap=0.35) → 稳定学习
+
+2. **变直径: scratch > transfer.** Generic SIM_BP + K_CD/CL=50/100 + lr=3e-4 + 500ep 是最优配方。
+
+3. **变雷诺数: scratch 和 transfer 各有侧重。** 两者均保留。
+
+4. **变雷诺数存在 CD/CL ↔ r_sim 根本性 trade-off。** 训练越久 r_cd 越高但 r_sim 越低（re60_sc: Ep60 r_sim=0.48 → Ep390 r_sim=0.26, r_cd=0.99）。CD/CL reward 分量主导了优化方向。
+
+5. **降低 W_drag/W_lift (0.1) 有害。** CD/CL reward 是稳定器而非瓶颈。
+
+6. **Ep1 r_sim ≥ 0.5 可预测 transfer 成功。**