# CG-RVC 主线证据复现指南

本文档面向“局部证书引导的低方差安全残差控制”投稿证据包。复现目标是把主线证据链、统计检验、Full-minus 消融和图表索引对应到本地可检查文件；不把本项目声明为通用 safe RL benchmark。

## 环境

- 推荐工作目录：`D:\kooopam_rl_low_varience\variance_regularized_safe_rl`
- Python：优先使用当前可运行项目脚本的解释器；历史正式脚本使用过 `C:\Python38\python.exe`
- 最小依赖见 `requirements.txt`：`numpy`、`scipy`、`matplotlib`
- 训练型 runner 还依赖现有环境中的 `torch`、`stable_baselines3` 等包；统计脚本只需要 `numpy/scipy`

## 一键重算统计检验

在项目目录运行：

```powershell
cd D:\kooopam_rl_low_varience\variance_regularized_safe_rl
python scripts\analyze_claim_statistics.py
```

默认读取：

- `outputs\rl\v3_tac_matched_5seed_safe10_20260504_193109\metrics_long.csv`
- `outputs\rl\paper_baseline_compare_5seed_safe10_formal_20260421_20260421_224626\metrics_long.csv`
- 最新的 `outputs\rl\fullminus_5seed_safe10_*\metrics_long.csv`，若不存在则在报告中明确标记缺失
- `outputs\uav\full3d_5seed_20260510_233952\metrics_long.csv`

输出目录：

- `outputs\statistics\claim_statistics_<timestamp>\claim_statistics.csv`
- `outputs\statistics\claim_statistics_<timestamp>\claim_statistics.json`
- `outputs\statistics\claim_statistics_<timestamp>\claim_statistics.md`
- `outputs\statistics\claim_statistics_<timestamp>\paper_claim_table.csv`
- `outputs\statistics\claim_statistics_<timestamp>\paper_claim_table.md`

统计口径：

- 2D learned-policy 主结果按 matched seed 做 paired comparison；高噪声主表使用每个 seed 的最高噪声点，补充表使用每个 seed 的全噪声均值。
- Full3D 只做 white-vs-filtered 高噪声数值诊断，先按 seed 聚合场景，再做 paired comparison。
- 所有主指标默认 lower is better：RMSE、Applied Var、Diff MSE、Dense violation、Bellman-Lyapunov max、Full3D state covariance、Full3D motor/action variance。

## Full-minus 消融重跑

Smoke run：

```powershell
cd D:\kooopam_rl_low_varience\variance_regularized_safe_rl
powershell -ExecutionPolicy Bypass -File scripts\launch_fullminus_safe10_5seed_20260516.ps1 -Smoke
```

正式 5-seed run：

```powershell
cd D:\kooopam_rl_low_varience\variance_regularized_safe_rl
powershell -ExecutionPolicy Bypass -File scripts\launch_fullminus_safe10_5seed_20260516.ps1
```

固定方法集：

- Full CG-RVC：`ale_reg_variance_aware_koopman_safe`
- Direct TD3：`direct_td3`
- P-ALE only：`td3_p_ale_only`
- P-ALE + smoothing：`td3_p_ale_smoothing`
- P-ALE + projection：`td3_p_ale_projection`
- P-ALE + smoothing + projection：`td3_p_ale_smoothing_projection`
- smoothing + projection：`td3_smoothing_projection`
- projection only：`td3_projection_only`
- low-pass only：`td3_low_pass_only`
- action-diff penalty：`td3_action_diff_penalty`

输出目录命名为 `outputs\rl\fullminus_5seed_safe10_<timestamp>`。该消融用于证明组件链条贡献；除非代码结构进一步改成严格开关式实现，不应写成每个 variant 都是 Full CG-RVC 内部唯一组件的严格移除。

## 图表和表格生成

刷新现有阶段性论文表格：

```powershell
cd D:\kooopam_rl_low_varience\variance_regularized_safe_rl
python scripts\stage_final_tables.py --run-all
```

最新版图表总索引：

- `paper_workspace_2d_lienard_safe10_20260422\10_tac_full_paper\tac_figures_tables_evidence_map_v4_1.md`

根目录中文证据地图：

- `D:\kooopam_rl_low_varience\PROJECT_EXPERIMENT_EVIDENCE_MAP.md`

## 外部 variance baseline：averaging-nstep-returns

第三方仓库：

- `D:\kooopam_rl_low_varience\external_baselines\averaging-nstep-returns`
- commit：`b29d23aec9a9e487d3add452720069dbb4afe463`

运行 smoke：

```powershell
cd D:\kooopam_rl_low_varience
python variance_regularized_safe_rl\scripts\run_averaging_nstep_returns_baseline.py --smoke --cpu
```

运行较完整的 Pendulum return-estimator variance baseline：

```powershell
cd D:\kooopam_rl_low_varience
python variance_regularized_safe_rl\scripts\run_averaging_nstep_returns_baseline.py --cpu --env-id Pendulum-v1 --estimators lambda-0.95 nstep-1 nstep-3 nstep-5 --seeds 0 1 2 3 4 --total-timesteps 20000 --num-steps 512 --num-minibatches 8 --update-epochs 4
```

输出目录：

- `variance_regularized_safe_rl\outputs\external_baselines\averaging_nstep_returns_<timestamp>\metrics_long.csv`
- `variance_regularized_safe_rl\outputs\external_baselines\averaging_nstep_returns_<timestamp>\summary.json`
- `variance_regularized_safe_rl\outputs\external_baselines\averaging_nstep_returns_<timestamp>\report.md`

写作边界：

该 baseline 的方差目标是 PPO 的 return / advantage estimator variance，不是 applied control input variance。它可以作为“学习估计器方差降低”外部背景对照，但不能替代主线中的 action variance、applied input statistics、state covariance 和 non-normal amplification 证据。

## 主线证据范围

主论点写作边界固定为：

`source -> suppressor -> applied input statistics -> non-normal amplifier -> transient gain -> state covariance`

允许声称：

- 机制隔离实验支持 non-normal amplifier 和 source-side intervention 的因果拆分。
- 2D safe10 matched evidence 支持 CG-RVC 相比若干 TD3/smoothing/projection/variance baseline 同时降低跟踪误差、输入方差、动作差分、安全违约和 posterior residual。
- Planar UAV 和 Full3D 数值实验支持飞行闭环中的机制一致性。

禁止过度声称：

- 不声称真实飞行验证。
- 不声称全局非线性安全定理。
- 不把 safe10 写成 leaderboard。
- 不把 Planar UAV / Full3D 写成完整高维 RL benchmark。
- 不把趋势性统计写成显著结论；当 `p >= 0.05` 或 bootstrap CI 跨 0 时，按趋势或探索性证据处理。

## 打包

在仓库根目录运行主线证据包脚本：

```powershell
cd D:\kooopam_rl_low_varience
powershell -ExecutionPolicy Bypass -File create_paper_packages_20260516.ps1
```

## CORE-RL CartPole state-variance baseline

第三方仓库：

- `D:\kooopam_rl_low_varience\external_baselines\CORE-RL`
- commit: `c95ed46439001c1c529d59ecde9b9e244ebb06da`

Smoke run：

```powershell
cd D:\kooopam_rl_low_varience
python variance_regularized_safe_rl\scripts\run_core_cartpole_state_variance_compare.py --smoke --device cpu
```

正式 5-seed run：

```powershell
cd D:\kooopam_rl_low_varience
python variance_regularized_safe_rl\scripts\run_core_cartpole_state_variance_compare.py --device cpu
```

当前正式输出：

- `variance_regularized_safe_rl\outputs\external_baselines\core_cartpole_state_variance_20260517_011917\metrics_long.csv`
- `variance_regularized_safe_rl\outputs\external_baselines\core_cartpole_state_variance_20260517_011917\aggregate_metrics.csv`
- `variance_regularized_safe_rl\outputs\external_baselines\core_cartpole_state_variance_20260517_011917\core_cartpole_claim_statistics.csv`
- `variance_regularized_safe_rl\outputs\external_baselines\core_cartpole_state_variance_20260517_011917\report.md`

写作边界：

这是 `CORE-style control-prior regularization baseline`，不是 CORE-RL 原 TensorFlow 代码的完整复现。采用 CORE-RL CartPole plant、DARE/LQR prior 和 prior-mixing 公式，在统一 runner 中比较 `prior_only`、`direct_td3`、`core_style_lambda5`、`core_style_lambda12` 和 `cg_rvc_cartpole`。高噪声结果可写成：CG-RVC 明显优于 Direct TD3；相对 CORE-style `lambda=12` 改善 state covariance、action-diff、dense failure 和 return，但 action variance 不是显著优势；相对 CORE prior-only 基本持平，不应写成压倒先验控制器。

输出包含：

- `MANIFEST.csv`
- `SHA256SUMS.txt`
- `MISSING_SOURCES_ALL.csv`
- 主线代码、核心 outputs、统计结果、图表索引、证据地图和复现指南

如果正式 Full-minus 尚未跑完，打包脚本会继续打包现有统计报告，并在缺失源报告中记录 Full-minus 输出缺失；论文正文中只能把该项写作“待补/趋势”，不能写成完成的正式消融。
