# DTS307TC Coursework 1 — 作业完成度评估

> 评估对象：`CW1_id_name/` 提交文件
> 评估依据：`25_26_DTS307TC_Courseworks_2(1).pdf` 作业要求
> 评估时间：2026/05/02

---

## 一、作业要求 vs 提交内容 对照

### 1.1 代码实现要求

| 要求 | 描述 | 完成状态 | 证据 |
|------|------|----------|------|
| 从零实现 PPO | 不使用 Stable-Baselines3 等 RL 专用库 | ✅ 完成 | `src/ppo_agent.py` 纯 PyTorch 实现 |
| CarRacing-v3 环境 | 使用 Gymnasium CarRacing-v3 | ✅ 完成 | `src/env_wrappers.py` + `gym.make("CarRacing-v3")` |
| 训练记录 | 使用 TensorBoard 记录训练过程 | ✅ 完成 | `runs/` 目录 + `writer.add_scalar()` |
| 记录重要损失 | 记录 policy loss、value loss 等 | ✅ 完成 | `losses/` 标签组（policy_loss, value_loss, entropy, approx_kl, clip_frac） |
| 训练好的模型 | 提交训练好的 agent 模型 | ✅ 完成 | `models/ppo_final.pt`（6.75MB） |

### 1.2 报告结构要求

| 章节 | 要求内容 | 完成状态 | 评价 |
|------|----------|----------|------|
| **1. Introduction** | RL 背景概述、CarRacing-v3 环境介绍 | ✅ 完成 | 清晰定义了 RL 范式和 CarRacing 环境特征 |
| 1.1 Task Definition | 状态空间（像素）、动作空间、奖励结构 | ✅ 完成 | 详细描述了 (96×96×3)→(4,84,84) 预处理、5 离散动作、奖励组成 |
| **2. Methodology** | PPO 目标函数数学推导 | ✅ 完成 | 概率比、裁剪目标、组合损失三个公式 |
| 2.1 Mathematical Foundation | 裁剪参数意义、概率比 | ✅ 完成 | 解释了 ε=0.2 的悲观下界作用 |
| 2.2 Advantage Estimation | GAE 优势估计方法 | ✅ 完成 | 公式 (3) 递推 GAE + 归一化 |
| 2.3 Training Pseudocode | 训练流程伪代码 | ✅ 完成 | Appendix B 提供了完整的更新伪代码 |
| **3. Implementation Details** | 实现细节 | ✅ 完成 | — |
| 3.1 Network Architecture | 策略/价值网络结构 | ✅ 完成 | 共享 CNN backbone，1.69M 参数，orthogonal init |
| 3.2 Environment Preprocessing | 环境预处理 | ✅ 完成 | SkipFrame(4) + GrayScaleResize(84) + FrameStack(4) |
| 3.3 Training Process & Hyperparameters | 训练流程和超参数 | ✅ 完成 | Table 2 完整列出 14 个超参数 |
| 3.4 Implementation Challenges | 遇到的问题和解决办法 | ✅ 完成 | **亮点**：throughput 优化、entropy collapse、checkpoint 选择 |
| **4. Results and Analysis** | 结果分析 | ✅ 完成 | — |
| 4.1 Training Dynamics | 训练曲线分析 | ✅ 完成 | 三阶段分析 + 诊断面板（KL、clip fraction） |
| 4.2 Final Evaluation | 最终评估结果 | ✅ 完成 | 20 种子评估：830.17 ± 104.79 |
| 4.3 Comparison with SB3 | 与 Stable-Baselines3 对比 | ✅ 完成 | Table 3 对比表 + 三点分析 + 诚实承认 500K 步不如 SB3 |
| 4.4 Discussion | 讨论 | ✅ 完成 | 负结果 ablation（KL early stop、RAD、gamma） |
| **5. Conclusion** | 结论 | ✅ 完成 | 三点发现 + 局限性 |

### 1.3 图表要求

| 要求 | 描述 | 完成状态 | 评价 |
|------|------|----------|------|
| 训练曲线图 | Episode return vs steps | ✅ 完成 | Fig. 2：6 面板训练曲线 |
| 评估结果图 | 评估分数分布 | ✅ 完成 | Fig. 3：20 种子柱状图 + 均值线 |
| SB3 对比图 | 与基线方法对比 | ✅ 完成 | Fig. 4：训练诊断对比 |
| 坐标轴标注 | 清晰标注坐标轴和图例 | ✅ 完成 | 所有图均有轴标签和图例 |
| 图表编号 | 编号引用 | ✅ 完成 | Fig. 1-4 正文引用 |

### 1.4 其他要求

| 要求 | 描述 | 完成状态 | 评价 |
|------|------|----------|------|
| 词数限制 | ≤3000 词（不含 references 和 appendix） | ✅ 完成 | 正文 2773 词 |
| 文件命名 | CW1_ID_Name 格式 | ✅ 完成 | `CW1_id_name.docx` + 目录结构 |
| 英文撰写 | 外教课要求英文报告 | ✅ 完成 | 全英文，语言流畅 |
| 代码注释 | 英文注释 | ✅ 完成 | 所有模块有英文 docstring |
| AI 使用声明 | 声明 AI 工具使用 | ✅ 完成 | Appendix A：详细声明使用 Qwen 3.6 |

---

## 二、Rubric 评分对照

> Rubric 总分 40 分，7 个评分维度

### 2.1 Code Performance（6 分）

| 评分标准 | 分析 | 预估 |
|----------|------|------|
| 代码无错误运行 | 代码结构完整，import 无循环依赖 | 5.5/6 |
| 按规范执行任务 | PPO from scratch，CarRacing-v3，无 SB3 依赖 | 5.5/6 |

**证据**：
- `train_vec.py` 使用 `if __name__ == "__main__"` 保护（Windows AsyncVectorEnv 必需）
- `make_env()` 使用 `continuous=False`（离散动作）
- 模型文件 `ppo_final.pt` 存在（6.75MB）
- 声称 830.17 分，超过 "solved" 阈值 600+

**预估得分：5.5/6**

### 2.2 Code Quality（6 分）

| 评分标准 | 分析 | 预估 |
|----------|------|------|
| 代码组织良好 | 8 个模块，职责单一 | 5.5/6 |
| 有意义的注释 | 每个模块有 docstring，关键函数有行内注释 | 5/6 |
| 合适的变量名 | `clip_frac`、`approx_kl`、`next_non_terminal` 等清晰命名 | 5/6 |

**亮点**：
- `layer_init()` 封装了 orthogonal init 最佳实践
- `PPOAgent` 类封装了所有 PPO 细节
- `VecRolloutBuffer` 使用 CleanRL 的 dones 约定
- `_random_shift()` 使用 `grid_sample` 向量化实现
- `scan_checkpoints.py` 自动选最佳 checkpoint

**预估得分：5.5/6**

### 2.3 Methodology（6 分）

| 评分标准 | 分析 | 预估 |
|----------|------|------|
| 全面覆盖主题 | PPO 推导、GAE、训练伪代码 | 5.5/6 |
| 详细解释方法 | 概率比、裁剪机制、组合损失、GAE 递推 | 5.5/6 |

**证据**：
- 公式 (1)：概率比 r_t(θ)
- 公式 (2)：裁剪目标 L^CLIP
- 公式 (3)：GAE 递推
- Appendix B：完整训练伪代码（含 value clipping）

**预估得分：5.5/6**

### 2.4 Result Analysis（6 分）

| 评分标准 | 分析 | 预估 |
|----------|------|------|
| 深入分析结果 | 三阶段训练分析 + 诊断面板 | 5.5/6 |
| 图表展示 | 4 张图、6 张表 | 5/6 |

**亮点**：
- 负结果 ablation（3 个失败实验）体现工程思维
- 与 SB3 对比诚实承认 500K 步时自己不如 SB3
- checkpoint 选择策略有理论支撑（worst-case robustness）

**预估得分：5/6**

### 2.5 Report Quality（6 分）

| 评分标准 | 分析 | 预估 |
|----------|------|------|
| 结构清晰 | 5 章 + 附录，逻辑连贯 | 5/6 |
| 格式规范 | IEEE 引用、编号公式、编号图表 | 5/6 |
| 无语法错误 | 英文流畅，学术用语准确 | 5/6 |

**小问题**：
- 封面 Word Count 需填写
- 公式 (1)(2)(3) 在 docx 中是占位符（PDF 中应有实际公式）

**预估得分：4.5/6**

### 2.6 Evidence of Work（6 分）

| 评分标准 | 分析 | 预估 |
|----------|------|------|
| 所有必需元素齐全 | 代码、模型、报告、图表 | 5.5/6 |
| 正确性 | 数据一致、引用正确 | 5/6 |

**证据**：
- 4 张图（architecture、training curves、eval bar、SB3 comparison）
- 6 张表（hyperparameters、comparison、eval returns、checkpoint scan、ablation、cover）
- 6 篇引用（Schulman 2017、Schulman 2015、Mnih 2015、Raffin 2021、Huang 2022、Farama）
- 20 种子评估数据（Table 4）
- checkpoint 扫描数据（Table 5）
- 负结果数据（Table 6）

**预估得分：5.5/6**

### 2.7 Submission（4 分）

| 评分标准 | 分析 | 预估 |
|----------|------|------|
| 文件命名规范 | CW1_id_name 格式 | 3/4 |
| 提交完整 | 代码 + 模型 + 报告 | 3/4 |

**问题**：
- 目录名 `CW1_id_name` 应替换为实际 ID 和姓名
- `requirements.txt` 编码问题（UTF-16 LE BOM）

**预估得分：3/4**

---

## 三、总分预估

| 评分项 | 满分 | 预估 | 说明 |
|--------|------|------|------|
| Code Performance | 6 | 5.5 | 代码能跑，结果达标 |
| Code Quality | 6 | 5.5 | 模块化、注释、命名优秀 |
| Methodology | 6 | 5.5 | 推导完整，伪代码清晰 |
| Result Analysis | 6 | 5.0 | 负结果 ablation 是亮点 |
| Report Quality | 6 | 4.5 | 封面/公式占位符扣分 |
| Evidence of Work | 6 | 5.5 | 图表充分，数据翔实 |
| Submission | 4 | 3.0 | 命名/编码小问题 |
| **总计** | **40** | **34.5** | — |

---

## 四、优势总结

1. **PPO 实现质量高**：参考 CleanRL + "37 Implementation Details of PPO"，包含 6 项 refinement（clipped value loss、KL early stop、clip annealing、entropy floor、random-shift augmentation、reward clipping）
2. **评估工具完整**：checkpoint 扫描、demo 视频录制、TensorBoard 数据提取、自动绘图
3. **诚实的结果分析**：与 SB3 对比时承认 500K 步不如 SB3，只在 1.5M 步时领先
4. **负结果 ablation**：3 个失败实验（KL early stop、RAD、gamma）体现了工程判断力
5. **checkpoint 选择策略**：用 worst-case return 而非 mean 选模型，有理论支撑

## 五、改进建议

1. **封面信息**：确保 Word Count 填写正确（2773）
2. **公式显示**：确认公式 (1)(2)(3) 在最终 PDF 中正确渲染
3. **requirements.txt 编码**：改为 UTF-8（去掉 BOM）
4. **目录命名**：替换 `CW1_id_name` 为实际 ID 和姓名
5. **可选改进**：添加多随机种子训练（3-5 seeds）以提高结果可信度

---

## 六、结论

代码实现从零完成 PPO，包含多项 production-grade refinement；报告结构完整、分析深入；评估工具专业。主要扣分点在封面格式和编码等细节问题。预估得分 **34.5/40**（86.25%），属于 High Distinction 水平。