# 最新 Train 保留证据图包阅读指南

## 最重要的证据谱系
本图包使用 15 个历史 scratch run 和 11 个 canonical eval 目录中的**保留 artifacts**。它们早于当前 calibration-v2/native policy normalization 源码契约，不能被表述为“修复后已完整重训”。历史 PPO/VecNormalize 评估使用明确的 `legacy-policy-v1` compatibility path。

训练最佳值以每个 run 的 `meta.json` 为权威，并用 `train.log` 提取同一 training iteration 的分量（若存在）。TensorBoard 仅作为被校验的辅助流；若与 meta 不一致，不使用其科学数值。一个所谓“episode”实际是 PPO learn chunk 加确定性评估，本图包称为 **training iteration**，不是终止型 Gym episode。

## 证据边界与混杂
只有 `kar_re100` 有 5 个种子；其余点均为 n=1 演示，不能估计种子不确定性。`kar_d075` 和 `kar_d2` 使用学习率 `1e-4`，多数 run 使用 `3e-4`，因此 variable-disturbance geometry 比较不是纯粹单因素消融。

## 两条不可混淆的证据链
1. **训练期：** authoritative best reward/iteration 来自 `meta.json`；同 iteration 分量来自 `train.log`。仅 Re100 的 retention/final 使用经 meta 校验一致的 TensorBoard。
2. **保留确定性评估：** `metrics.json` 对应 `all_seeds.json` 中 reward 最高 seed；signals/vorticity 是历史 policy compatibility-path artifacts，不等同于训练 reward，也不证明当前契约重训。

## 指标、动作与图像
Reward、`r_CD`、`r_CL`、`r_sim`、DTW similarity 均越高越好；DTW 是时间信号相似度，不是物理场误差。Target/Controlled/Zero 用于涡量结构对照。动作顺序已由 active env 与 symmetry code 核实为 `[front, top, bottom]`。动作均值接近零可能是振荡抵消；饱和定义为 `|a| >= 0.95`，窗口为最后 180 步。

## 图号与实际文件
- `fig00_graphical_abstract_reading_guide`：谱系与阅读规则。
- 仅 Re100、且 TB 已经 meta 校验：`fig01_re100_multiseed_learning`、`fig02_re100_discovery_drawdown`、`fig02_re100_policy_retention`、`fig03_re100_reward_components`。
- 全 case authoritative/meta 与 retained eval：`fig04_authoritative_training_vs_eval`、`fig05_authoritative_iteration_and_eval_gap`。本包没有 `fig06`。
- retained eval：`fig07_eval_cross_scene_metrics`、`fig08_eval_reward_components`、`fig09_action_profile_saturation`、`fig10_representative_signal_diagnostics`、`fig11_evidence_scope`。
- retained vorticity：`fig12_vorticity_cross_re`、`fig13_vorticity_disturbance`、`fig14_vorticity_illusion`。

## 复现
```bash
conda run -n pycuda_3_10 python src/drl_pinball/train/plot_latest_results.py
```
脚本要求 signals 和三类 vorticity PNG 全部存在，否则失败；不加载 fields.npz、不重跑 CFD。
