How to Add a New Benchmark

本节介绍如何在 XuanCe 中添加一个新的基准测试。 在 XuanCe 中，一个基准测试由 一种算法、一个环境场景以及多个随机种子 共同定义。

Step 1: 选择基准测试任务

确定基准测试环境及场景任务。例如:

  • Environment: Atari

  • Scenario: Breakout-v5

如果对应的目录不存在，请创建该目录：

Step 2: 创建对应算法目录

在场景目录下，为该算法创建一个子目录:

例如，针对 **PPO**算法:

Step 3: 准备算法配置（可选）

如果该算法需要特定的配置文件，请将其放置在算法目录中:

benchmarks/Atari/Breakout-v5/ppo/ppo_atari.yaml

该配置文件用于定义基准测试中使用的超参数以及与环境相关的设置。

Step 4: 编写基准测试脚本

创建基准测试脚本，文件命名如下:

例如:

每个基准测试脚本应该:

  • 调用共享的 train.py 脚本

  • 运行多个随机种子（默认：5 个）

  • 清晰标明每个随机种子的开始与结束

  • 不重复输出 XuanCe 已经打印的算法或环境信息

结构示例:

Step 5: 将该基准测试添加到套件脚本中（可选）

如果希望将新的基准测试纳入某个基准测试套件，请编辑场景目录下的套件脚本:

将新的基准测试脚本添加到列表中:

Step 6: 运行并验证

运行基准测试脚本:

验证如下信息: - 所有随机种子按顺序依次运行 - 每个随机种子均清晰打印 START / END 标记 - 实验结果保存在正确的目录结构下 - 重新运行脚本可以复现实验结果

设计原则

在添加新的基准测试时，建议遵循以下原则： - 一个脚本 = 一个基准测试 - 基准测试脚本是唯一的权威来源 - 避免硬编码绝对路径 - 避免重复输出 XuanCe 已经处理的日志信息 - 优先保证清晰性与可复现性