Document MSK-Bench weight folders

data/README.md

@@ -0,0 +1,109 @@
+# MSK-Bench 权重与实验产物说明
+
+本目录 `data/` 存放不同算法在 MyoSuite/MSK-Bench 任务上的策略权重，以及与这些权重对应的配置、训练日志和评估结果。目录名用于区分算法或实验系列；同一任务在不同目录下的权重不能直接互换。
+
+## 从哪里找权重
+
+| 目录 | 内容 | 首先查看 |
+| --- | --- | --- |
+| [`deprl/`](./deprl/) | DEPRL 的步行、跑步和上楼梯基线；配置中使用 DEP + MPO | `walk/`、`run/`、`stair/` 下的 `checkpoints/best.pt` |
+| [`msgym/`](./msgym/) | 按 MyoSuite 环境和实验批次组织的 `SAC_DynSyn` 策略 | `<环境>/<运行批次>/checkpoint/best_model.zip` |
+| [`ppo/`](./ppo/) | PPO 任务权重、归一化状态、评估报告和训练日志 | `ppo_<任务>_checkpoints/best_model.zip` |
+| [`residualrl/`](./residualrl/) | ResidualRL 步行、跑步和上楼梯实验；配置中使用 DEP + MPO | `<任务>/checkpoints/best.pt` |
+| [`sac/`](./sac/) | SAC 任务权重、归一化状态、评估报告和训练日志 | `sac_<任务>_checkpoints/best_model.zip` |
+
+`best` 是原实验文件的命名；这里不根据文件名推断选择它所用的指标。要复现评估，请同时核对同目录的配置、环境版本，以及对应的预处理或归一化状态。
+
+## `deprl/`：DEPRL 基线
+
+这里有三个任务目录，每个目录下的数字目录是一次实验运行。环境名称来自各自的 `config.yaml`：
+
+| 子目录 | 配置中的环境 | 主要用途 |
+| --- | --- | --- |
+| `walk/260521.131030/` | `myoLegWalk-v0` | 腿部步行策略及其评估结果 |
+| `run/260502.131631/` | `MyoRun-v0` | 跑步策略及其评估结果 |
+| `stair/260202.174137/` | `myoLegStair-v0` | 上楼梯策略及其评估结果 |
+
+每次运行通常包含：
+
+- `config.yaml`：环境、DEP、MPO、训练和检查点设置。
+- `script.py`：该实验保存的训练脚本；阅读或复现训练时参考。
+- `checkpoints/best.pt`：命名为最佳的策略检查点；`step_*.pt` 是特定训练步数的检查点。
+- `checkpoints/logger.pt`、`checkpoints/time.pt`：与日志或训练进度有关的保存状态，不是单独的策略权重。
+- `log.csv`：训练与测试过程的指标。
+- `eval_*.png`、`*_compliance_report.csv`：能耗、抖动及肌肉动作或物理关节的评估图表和数值报告。
+- `EMG_*`：仅在有这类文件的运行中提供肌电相关结果。
+
+## `msgym/`：按环境和运行批次组织的策略
+
+第一层目录是 MyoSuite 环境名，如 `myoLegWalk-v0/`、`MyoRun-v0/`。其下一层（如 `0625-005737_0/`）是一组实验产物；部分环境有多组运行，选择权重时应保留对应批次的配置和环境状态。当前的运行配置 JSON 均将 `agent` 记为 `SAC_DynSyn`。
+
+包含的环境目录：
+
+```text
+MyoBunnyHop-v0       MyoCatch-v0            MyoChinUp-v0
+MyoCrawl-v0          MyoDoorOpen-v0         MyoHurdle-v0
+myoLegBalance-v0     myoLegSquat-v0         myoLegStair-v0
+myoLegStandRandom-v0 myoLegWalk-v0          MyoMazeWalk-v0
+MyoPoleWalk-v0       myoPowerlift-v0        MyoRun-v0
+MyoSidestep-v0       MyoSingleLegStance-v0  MyoSteppingStones-v0
+myoWalkAndSit-v0
+```
+
+运行目录中的常见文件：
+
+| 路径或文件 | 作用 |
+| --- | --- |
+| `<任务>.json` | 算法、环境、网络和训练参数；具体文件名随任务变化。 |
+| `checkpoint/best_model.zip`、`final_model.zip` | Stable-Baselines3 格式的策略保存文件，分别对应原实验命名的最佳和最终模型。部分运行可能只包含其中一种。 |
+| `checkpoint/best_env.zip`、`final_env.zip` | 与模型配套保存的环境状态。**这些文件虽以 `.zip` 结尾，实际是 Python pickle 序列化流，不是普通 ZIP 压缩包**；应使用原实验的加载方式。 |
+| `eval/evaluations.npz` | NumPy 格式的定期评估数据。 |
+| `monitor/*.monitor.csv` | 每次 episode 的奖励 `r`、长度 `l` 和时间 `t` 等记录。 |
+| `events.out.tfevents.*` | TensorBoard 事件日志。 |
+
+## `ppo/` 与 `sac/`：按任务配对的检查点和日志
+
+这两个目录使用相同的组织方式：`<算法>_<任务>_checkpoints/` 放模型和评估结果，`<算法>_<任务>_logs/` 放评估与训练日志。例如 `ppo_balance_checkpoints/` 与 `ppo_balance_logs/` 是一对；SAC 使用 `sac_` 前缀。
+
+`ppo/` 当前的任务后缀为：
+
+```text
+balance, bunny, catch, chinup, crawl, door, hurdle, maze, pole_walk,
+powerlift, reach, run, sidestep, sit, slidehard, squat, stair, stance,
+stepping_stones, walkandsit
+```
+
+`sac/` 当前的任务后缀为：
+
+```text
+balance, bunnyhop, catch, chinup, crawl, door, hurdle, maze, pole_walk,
+powerlift, reach, run, sidestep, singlelegstance, sit, slidehard, squat,
+stair, stepping_stones, walkandsit
+```
+
+任务后缀按原目录名保留；两种算法的任务集合和拼写并不完全相同。`checkpoints/` 类目录中的主要文件：
+
+- `best_model.zip`：Stable-Baselines3 格式的策略模型。
+- `vec_normalize.pkl`：与该任务模型配套的向量环境归一化状态；评估时应核对并使用对应文件。
+- `eval_*_energy_plot.png`、`eval_*_jitter_report.png`：能耗与抖动的评估图。
+- `Muscle_Actions_compliance_report.csv`、`Physical_Joints_compliance_report.csv`：肌肉动作与关节维度的合规性或平滑度统计；表中包括导数能量和 jerk 等字段。
+
+配对的 `logs/` 类目录通常包含 `eval_logs/evaluations.npz`（评估数据）和 `PPO_1/` 或 `SAC_1/` 下的 `events.out.tfevents.*`（TensorBoard 训练日志）。
+
+## `residualrl/`：ResidualRL 实验
+
+`run/`、`stair/`、`walk/` 分别对应配置中的 `MyoRunResidual-v0`、`MyoStairResidual-v0`、`MyoWalkResidual-v0` 环境。每个任务目录有：
+
+- `config.yaml`：环境、DEP、MPO 及训练参数。
+- `script.py`：保存的训练脚本。
+- `checkpoints/best.pt`：命名为最佳的策略检查点。
+- `checkpoints/step_*.pt`：按训练步数保存的检查点；`walk/` 保留了更多中间步数。
+- `checkpoints/logger.pt`、`checkpoints/time.pt`：日志或训练进度状态。
+- `log.csv`：训练和测试指标。
+
+## 使用时的对应关系
+
+1. 先按**算法与环境/任务**选择目录，再选该目录中的权重。相似名字的任务或不同算法的权重不应仅凭文件名互换。
+2. `ppo/`、`sac/` 的 `best_model.zip` 应与同任务的 `vec_normalize.pkl` 一起核对；`msgym/` 的模型应与同一运行批次的 JSON 配置和环境状态一起核对。
+3. `.pt`、`.pkl` 及 `msgym` 的 `*_env.zip` 需要相应的 Python 类和库版本才能正确加载。这里保存的是实验产物，并不保证仅凭权重文件就能运行推理。
+4. `log.csv`、`*.npz`、`*.monitor.csv`、`events.out.tfevents.*` 和评估图表用于分析训练或比较实验，不是策略权重。