Four Rooms：Option Planning Utility Baseline

这是一个面向“option 质量是否能在固定 planning budget 下提升 model-based planning 效率”问题的可复现实验基线。它实现三组方法：

1. primitive_dyna：只用 primitive-action model 做 Dyna-Q planning；
2. doorway_options：加入指向 Four Rooms 门口（bottleneck）的高效用 options；
3. random_options：加入随机非门口 waypoint、且 option policy 更随机的低效用 options。

关键实验隔离

默认情况下，三组 agent 在真实环境里都只执行 primitive actions。Options 只用于 background planning。因此，结果不会把 option execution 带来的探索或行为加速误当成 planning 加速。

真实 transition 用于更新经验 primitive model。Option model 不读取隐藏的真实环境，而是由已经学到的 primitive model 组合采样得到。一次 option planning backup 使用 SMDP target：

Q(s, a_first) <- Q(s, a_first)
  + alpha * [R_option + gamma^k max_a Q(s_terminal, a) - Q(s, a_first)]

这里 a_first 是 option 在起点选择的第一个 primitive action，k 是 option 时长。这样，多步价值信息可直接传播回 option 起点，同时行为策略仍是 primitive-action epsilon-greedy。

Planning utility 的操作性定义

输出同时覆盖两个组成部分：

• 可靠性：经验 option endpoint distribution 与真实环境下 Monte Carlo endpoint distribution 的 total-variation error，见 mean_option_model_tv_error；越低越好。
• 有用性：每次 option backup 前后相对于精确 V* 的全局 value RMSE 减少量，见 mean_option_backup_rmse_gain；越高越好，负值表示该 backup 平均有害。

--option-model-noise 是受控模型失配：以给定概率把 option model 的预测终点替换为一个已知状态，而真实环境和 oracle option outcome 保持不变。它用于画性能退化曲线，不代表唯一可能的模型误差形式。random_options 另外带有默认 0.55 的 option-policy 随机性。

环境与公平性

• 11 x 11 Four Rooms，四个 doorway bottlenecks；
• 稀疏奖励：进入固定 goal 得到 +1，其他步为 0；
• 每个 seed 内三种 agent 使用同一 start-state schedule；
• 同一条件下，每个真实 primitive transition 后严格执行相同数量的 planning backups；
• planning_backups == cumulative_real_steps * planning_steps，自动测试会检查这个不变量；
• 需要注意：固定 backup 数并不等于固定 wall-clock 或固定 primitive-model query 数。Option backup 内部可能组合多个 primitive transitions；若研究“elementary planning operations”，应把模型查询数或运行时间作为第二种预算。

快速运行

项目只依赖 NumPy。启动脚本会依次寻找项目 .venv、本机 Codex 自带 Python、py -3 和 python。

cd C:\Users\zy105\Desktop\code\Plan
.\run.cmd test
.\run.cmd smoke

较完整的实验：

.\run.cmd experiment --episodes 300 --seeds 20 --planning-steps 0,5,20,50 --option-model-noise 0,0.1,0.3,0.5 --max-steps 300 --output outputs/full

run.cmd 会用 -ExecutionPolicy Bypass 仅启动本项目的 run.ps1，不会修改系统的全局 PowerShell 策略。

如果已把项目安装到虚拟环境，也可直接运行：

python -m pip install -e .
python -m option_planning.experiment --episodes 100 --seeds 3

输出

每次实验会在 --output 指定目录生成：

• episodes.csv：逐 episode 的步数、成功率、Bellman residual、value RMSE、backup 计数；
• summary.csv：按 agent / planning budget / option-model noise 汇总；
• learning_curves.svg：到达目标所需步数；
• bellman_residual_curves.svg：Bellman residual 收敛；
• model_noise_degradation.svg：option model 失配下的性能退化；
• bellman_residual_heatmaps.svg：训练不同阶段的状态级 residual 热图；
• config.json：完整实验配置。

SVG 是纯 Python 生成的，不需要 Matplotlib，可以直接用浏览器、PowerPoint 或 Illustrator 打开。

如何判断假设是否成立

重点比较相同 planning_steps 下：

1. doorway_options 是否以更少的 cumulative_real_steps 达到目标成功率；
2. 它的 final_bellman_residual 和 final_value_rmse 是否下降更快；
3. mean_option_backup_rmse_gain 是否高于随机 options；
4. 随着 mean_option_model_tv_error 增大，优势是否减弱或反转；
5. residual 热图中的低误差区域是否更快跨 doorway 传播到远端房间。

建议正式结论使用至少 20–30 个 seeds，并报告均值、bootstrap 置信区间和 paired-seed 检验。本基线的 summary.csv 先给出均值和达到目标的 seed 比例，便于后续加入统计检验。

代码结构

src/option_planning/
  env.py          Four Rooms 与精确 transition distribution
  options.py      doorway/random waypoint options
  model.py        primitive/option 经验模型与模型组合 rollout
  agents.py       Dyna-Q 和 planning-only SMDP option backups
  metrics.py      V*、value RMSE、Bellman residual、TV error
  svg_plots.py    无额外依赖的曲线与热图
  experiment.py   参数扫描、CSV 汇总和 CLI
tests/            环境、预算不变量、option backup、端到端 smoke tests

文献依据

• Sutton, R. S. (1990), Integrated Architectures for Learning, Planning, and Reacting Based on Approximating Dynamic Programming：Dyna 把真实经验、学习模型和 planning update 整合在同一架构中。
• Sutton, Precup & Singh (1999), Between MDPs and Semi-MDPs: A Framework for Temporal Abstraction in Reinforcement Learning, Artificial Intelligence 112, 181–211, DOI: 10.1016/S0004-3702(99)00052-1：options 与 SMDP backup 的基础。
• Wan & Sutton (2022), Toward Discovering Options that Achieve Faster Planning, arXiv:2205.12515：直接研究以更少 planning operations 获得近优价值函数，并在 Four Rooms 变体中观察到 doorway-like options。

下一步优化接口

当前 WaypointOption 是可替换的最小接口。后续可以把“手工 doorway”替换为：

• 根据 graph betweenness / successor representation 自动发现 bottlenecks；
• 直接最大化 model_accuracy_weight * (1 - TV) + value_gain_weight * RMSE_gain；
• 用 bandit 或 prioritized sweeping 动态分配 primitive/option backup 比例；
• 给 option termination、initiation set 和 policy 加入可学习参数；
• 同时约束 option backup 的 primitive-model query cost，避免只优化宏观 backup 数。