# 课程设计作业：LeWorldModel (LeWM) — TwoRoom 评估

**目标**：部署环境，加载老师提供的模型权重，**跑通 TwoRoom 任务的评估流程**。无需训练模型。
**有 GPU 用 GPU（结果更全），没 GPU 用 CPU 也能跑通。**

> 本作业所需的全部文件（数据集、模型权重、配置）由老师以压缩包 `tworoom_student_data.zip` 形式提供，
> **无需任何下载**——解压到本仓库内即可。

---

## 第 1 步：装环境（macOS / Linux / Windows 通用）

要求：**Python 3.10**。先按你的系统装好 Python 3.10 与必要的系统库，再装 Python 依赖。

### ① 各系统准备 Python 3.10

**macOS（Apple Silicon / Intel，无 NVIDIA GPU → 走 CPU 版）**
```bash
brew install python@3.10
# Homebrew 会把 python3.10 放进 PATH（Apple Silicon 在 /opt/homebrew/bin/python3.10）
```

**Linux（服务器/无图形界面，先装渲染库）**
```bash
sudo apt-get update
sudo apt-get install -y python3.10 python3.10-venv libegl1 libgl1 libglib2.0-0
```
> 有 NVIDIA GPU 才能跑完整配置（50 回合）；否则同样走 CPU 版。

**Windows（强烈建议用 WSL2 Ubuntu，然后照上面 Linux 步骤做）**
> 原生 Windows 跑 MuJoCo 渲染较麻烦。若坚持原生 Windows：装 [Python 3.10](https://www.python.org/downloads/)，
> 用 PowerShell 激活虚拟环境后再装依赖（仅 CPU 版，渲染可能需额外配置）。

### ② 建虚拟环境并装 Python 依赖（三系统通用）
```bash
cd blockworld-challenge

# 建并激活 Python 3.10 虚拟环境
python3.10 -m venv .venv
source .venv/bin/activate                 # Windows PowerShell: .venv\Scripts\Activate.ps1

# 装依赖（末尾的 hdf5plugin 必装，否则读不了 .h5 数据集）
pip install --upgrade pip
pip install "stable-worldmodel[train,env]" hdf5plugin
```

> 💡 **`hdf5plugin` 必须单独装**：它不在 `[train,env]` 里，但本仓库评估脚本用 HDF5 格式读数据集，
> 缺它会报 `module 'stable_worldmodel.data' has no attribute 'HDF5Dataset'`。
>
> 也可用 `uv` 代替上面 venv/pip：
> `uv venv --python=3.10 && source .venv/bin/activate && uv pip install "stable-worldmodel[train,env]" hdf5plugin`

---

## 第 2 步：放好数据与权重（放在仓库内，不用隐藏目录）

把老师提供的 **`tworoom_student_data.zip`** 解压到**仓库内的 `data/` 目录**
（不要放到 `~/.stable_worldmodel` 这类隐藏目录）：

```bash
cd blockworld-challenge
unzip /你保存压缩包的路径/tworoom_student_data.zip -d ./data
```

解压后应在仓库里形成如下结构：
```
blockworld-challenge/
└── data/
    ├── datasets/tworoom.h5                      ← 数据集（精简版）
    └── checkpoints/tworoom/
        ├── weights_epoch_24.pt                  ← 模型权重
        └── config.json                          ← 模型结构
```
> 若解压后多了一层目录（如 `data/tworoom_student_data/datasets/...`），
> 把里面的 `datasets/` 和 `checkpoints/` 移到 `data/` 下，保证路径是 `data/datasets/...`。

**把这个仓库内目录设为数据根目录**（数据集、权重、以及评估输出都会落在这里）：
```bash
export STABLEWM_HOME="$(pwd)/data"            # Windows PowerShell: $env:STABLEWM_HOME = "$PWD\data"
```
> 每开一个新终端都要重新 `export`（建议写进自己的启动脚本）。

**自检**（确认环境/文件都就位，再跑评估）：
```bash
bash scripts/check_setup.sh
```

> ⚠️ **关于数据集**：为缩小体积，这是**精简版**，只包含默认评估会用到的图像帧。
> **请不要修改 `seed` 或回合数 `num_eval`** —— 否则会用到没保留图像的帧，导致结果错误。
> 直接用下面第 3 步的命令即可。

---

## 第 3 步：运行评估

### ▶ 有 GPU（完整评估，50 回合）
```bash
python eval.py --config-name=tworoom policy=tworoom/weights_epoch_24.pt
```
预期：`success_rate` ≈ **84%**，几十秒完成。

### ▶ 没 GPU（CPU 轻量版，5 回合，约十几秒）
```bash
python eval.py --config-name=tworoom_cpu policy=tworoom/weights_epoch_24.pt
```
预期：几秒~十几秒完成，打印 `success_rate`（默认 5 个回合，实测 **5/5 成功**）。
> CPU 版为了速度把回合数和规划规模调小了，成功率数值会和 84% 不同，**这是正常的**——本作业只要求“跑通流程”。
> （不要用 GPU 的完整配置在 CPU 上跑：默认参数在 CPU 上要 **50 分钟以上**。）

`policy=tworoom/weights_epoch_24.pt` 是相对 `checkpoints/` 的路径，**不要**加 `checkpoints/` 前缀。

---

## 第 4 步：确认跑通

终端打印类似：
```
{'success_rate': 100.0, 'episode_successes': array([ True, True, ...]), 'seeds': None}
```
同时在 **`$STABLEWM_HOME/tworoom/`**（即仓库内 `data/tworoom/`）下生成：
- 结果文件 `tworoom_results.txt`（CPU 版为 `tworoom_cpu_results.txt`）
- 每个回合的可视化视频 `env_*.mp4`

**只要看到 `success_rate` 并生成结果文件/视频，即视为评估流程跑通。**

---

## 常见问题

| 现象 | 解决 |
|---|---|
| `module 'stable_worldmodel.data' has no attribute 'HDF5Dataset'` | 没装 `hdf5plugin`。执行 `pip install hdf5plugin` 后重试。 |
| 找不到 `tworoom.h5` / 数据集 | 确认已解压到仓库内 `data/`，且 `export STABLEWM_HOME="$(pwd)/data"` 已执行（新终端要重设）。 |
| 加载模型报错 / 找不到 config | `config.json` 必须和 `.pt` 在同一目录 `data/checkpoints/tworoom/`（解压后即满足）。 |
| `goal not in info_dict` / 结果异常 | 你改了 `seed` 或 `num_eval`。精简数据集只支持默认配置，请用原命令。 |
| `policy` 路径错误 | 路径相对 `checkpoints/` 写，不要带 `checkpoints/` 前缀。 |
| Python 版本不对 | 必须 3.10。`python --version` 确认虚拟环境已激活。 |
| Linux EGL / 渲染报错 | 执行第 1 步的 `apt-get install libegl1 libgl1 libglib2.0-0`。 |
| 没有 GPU | 用 CPU 轻量版命令（`--config-name=tworoom_cpu`）。 |

---

## 提交要求（建议）
1. 运行截图（含 `success_rate` 那一行）。
2. 结果文件 `tworoom(_cpu)_results.txt`。
3. 任意一个 `env_*.mp4`。
4. 简短报告：部署步骤、遇到的问题及解决、对评估流程（基于世界模型的 MPC 规划 + 成功率指标）的理解。
