Isaac Gym 基准环境

官网 | 技术论文 | 视频

关于本仓库

本仓库包含 NVIDIA Isaac Gym 高性能环境的强化学习示例环境，这些环境在我们的 NeurIPS 2021 数据集与基准论文 中有所介绍。

安装

从 官网 下载 Isaac Gym Preview 4 版本，然后按照文档中的安装说明进行操作。我们强烈建议使用 conda 环境来简化设置。

确保 Isaac Gym 在您的系统上正常运行，方法是运行 python/examples 目录下的示例之一，例如 joint_monkey.py。如果运行示例时遇到任何问题，请按照 Isaac Gym Preview 4 的安装说明中的故障排除步骤进行操作。

一旦 Isaac Gym 已成功安装，并且当前 Python 环境中的示例能够正常运行，请安装本仓库：

pip install -e .

创建环境

我们提供了一个易于使用的 API 来创建预设的向量化环境。有关向量化环境的概念及其用法的更多信息，请参阅 Gym 库的 文档。

import isaacgym
import isaacgymenvs
import torch

num_envs = 2000

envs = isaacgymenvs.make(
	seed=0, 
	task="Ant", 
	num_envs=num_envs, 
	sim_device="cuda:0",
	rl_device="cuda:0",
)
print("观测空间为", envs.observation_space)
print("动作空间为", envs.action_space)
obs = envs.reset()
for _ in range(20):
	random_actions = 2.0 * torch.rand((num_envs,) + envs.action_space.shape, device = 'cuda:0') - 1.0
	envs.step(random_actions)

运行基准测试

要训练您的第一个策略，运行以下命令：

python train.py task=Cartpole

Cartpole 应该能够在开始后的几秒钟内学会保持杆直立。

另一个例子——蚂蚁行走：

python train.py task=Ant

请注意，默认情况下会显示一个预览窗口，这通常会降低训练速度。您可以在运行过程中按 v 键来禁用查看器更新，从而加快训练速度。训练几秒钟后，当蚂蚁已经学会更好地行走时，再次按下 v 键即可恢复查看。

按 esc 键或关闭查看器窗口可以提前停止训练。

或者，您也可以以无头模式进行训练，如下所示：

python train.py task=Ant headless=True

蚂蚁可能需要一两分钟才能训练出一个可运行的策略。在无头模式下，您可以使用终端中的 Control-C 提前终止训练。

加载已训练模型 // 检查点

检查点保存在 runs/EXPERIMENT_NAME/nn 文件夹中，其中 EXPERIMENT_NAME 默认为任务名称，但也可以通过 experiment 参数覆盖。

要加载已训练的检查点并继续训练，使用 checkpoint 参数：

python train.py task=Ant checkpoint=runs/Ant/nn/Ant.pth

要加载已训练的检查点并仅进行推理（不进行训练），请同时传递 test=True 参数和检查点名称。为了避免渲染开销，您还可以使用较少的环境数量，例如 num_envs=64：

python train.py task=Ant checkpoint=runs/Ant/nn/Ant.pth test=True num_envs=64

请注意，如果检查点名称中包含特殊字符，如 [ 或 =，则需要对这些字符进行转义，并将字符串用引号括起来。例如， checkpoint="./runs/Ant/nn/last_Antep\=501rew\[5981.31\].pth"

配置与命令行参数

我们使用 Hydra 来管理配置。请注意，这与 Isaac Gym 旧版本中的实现有一些差异。

train.py 脚本的关键参数包括：

• task=TASK - 选择要使用的任务。可选值包括 AllegroHand、AllegroHandDextremeADR、AllegroHandDextremeManualDR、AllegroKukaLSTM、AllegroKukaTwoArmsLSTM、Ant、Anymal、AnymalTerrain、BallBalance、Cartpole、FrankaCabinet、Humanoid、Ingenuity、Quadcopter、ShadowHand、ShadowHandOpenAI_FF、ShadowHandOpenAI_LSTM 和 Trifinger（这些对应于 isaacgymenvs/config/task 文件夹中每个环境的配置）。
• train=TRAIN - 选择要使用的训练配置。默认会自动选择与当前环境匹配的正确配置（即 <TASK>PPO）。
• num_envs=NUM_ENVS - 指定要使用的环境数量，覆盖任务配置中设置的默认环境数。
• seed=SEED - 设置随机化的种子值，覆盖任务配置中设置的默认种子。
• sim_device=SIM_DEVICE_TYPE - 用于物理模拟的设备。设置为 cuda:0（默认）以使用 GPU，或设置为 cpu 以使用 CPU。遵循 PyTorch 风格的设备语法。
• rl_device=RL_DEVICE - 用于强化学习算法的设备或 ID。默认为 cuda:0，同样遵循 PyTorch 风格的设备语法。
• graphics_device_id=GRAPHICS_DEVICE_ID - 用于渲染的 Vulkan 图形设备 ID。默认为 0。注意：这可能与 CUDA 设备 ID 不同，并且 不 遵循 PyTorch 风格的设备语法。
• pipeline=PIPELINE - 使用哪种 API 管道。默认为 gpu，也可设置为 cpu。当使用 gpu 管道时，所有数据都保留在 GPU 上，运行速度尽可能快；而使用 cpu 管道时，模拟可以在 CPU 或 GPU 上运行，具体取决于 sim_device 的设置，但每一步都会在 CPU 上复制一份数据。
• test=TEST - 如果设置为 True，则仅运行策略的推理，而不进行训练。
• checkpoint=CHECKPOINT_PATH - 指定要加载的检查点路径，用于训练或测试。
• headless=HEADLESS - 是否以无头模式运行。
• experiment=EXPERIMENT - 设置实验名称。
• max_iterations=MAX_ITERATIONS - 设置要运行的最大迭代次数。对于提供的环境，已提供合理的默认值。

Hydra 还允许直接通过命令行参数设置配置文件中的变量。例如，要设置 rl_games 训练的折扣因子，可以使用 train.params.config.gamma=0.999。同样，也可以设置任务配置中的变量，比如 task.env.enableDebugVis=True。

Hydra 注意事项

这些参数的默认值可在 isaacgymenvs/config/config.yaml 文件中找到。

配置中 task 和 train 部分的工作方式是通过配置组来实现。有关其工作原理的更多信息，请参阅 此处。

实际的任务配置位于 isaacgymenvs/config/task/<TASK>.yaml，而训练配置则位于 isaacgymenvs/config/train/<TASK>PPO.yaml。

在配置的某些地方，您会发现引用了其他变量（例如，num_actors: ${....task.env.numEnvs}）。每个 . 表示在配置层次结构中向上一级。完整的文档请参阅 这里。

任务

任务的源代码位于 isaacgymenvs/tasks 中。

每个任务都继承自 isaacgymenvs/base/vec_task.py 中的 VecEnv 基类。

有关如何创建自己的任务，请参阅 docs/framework.md。

关于可用任务的详细信息，请参阅 RL 示例文档。

域随机化

IsaacGymEnvs 包含一个用于域随机化的框架，以提高训练好的 RL 策略从仿真到现实世界的迁移能力。您可以阅读 这里 获取更多信息。

可重复性和确定性

如果您对 RL 策略的确定性训练非常重视，建议查阅我们的 可重复性和确定性文档。

多 GPU 训练

您可以使用 torchrun（即 torch.distributed）通过本仓库进行多 GPU 训练。

以下是一个以这种方式运行的示例命令： torchrun --standalone --nnodes=1 --nproc_per_node=2 train.py multi_gpu=True task=Ant <OTHER_ARGS>

其中 --nproc_per_node= 标志指定了要运行的进程数，并且必须在训练脚本中设置 multi_gpu=True 才能进行多 GPU 训练。

基于群体的训练

您可以运行基于群体的训练，以帮助寻找合适的超参数，或在那些如果没有它就很难学习的困难环境中进行训练。详情请参阅 readme。

WandB 支持

您可以通过在命令行中设置 wandb_activate=True 标志来使用 WandB 与 Isaac Gym Envs 集成。您还可以通过设置 wandb_group、wandb_name、wandb_entity 和 wandb_project 来指定运行的组、名称、实体和项目。在激活之前，请确保已通过 pip install wandb 安装 WandB。

录制视频

我们实现了标准的 env.render(mode='rgb_array') gym API，以提供模拟器视图的图像。此外，我们还可以利用 gym.wrappers.RecordVideo 来录制展示智能体游戏过程的视频。请尝试运行以下代码，它应该会在 videos 文件夹中生成一个视频。

import gym
import isaacgym
import isaacgymenvs
import torch

num_envs = 64

envs = isaacgymenvs.make(
	seed=0, 
	task="Ant", 
	num_envs=num_envs, 
	sim_device="cuda:0",
	rl_device="cuda:0",
	graphics_device_id=0,
	headless=False,
	multi_gpu=False,
	virtual_screen_capture=True,
	force_render=False,
)
envs.is_vector_env = True
envs = gym.wrappers.RecordVideo(
	envs,
	"./videos",
	step_trigger=lambda step: step % 10000 == 0, # 每 10000 步录制一次视频
	video_length=100  # 每段视频最多记录 100 步
)
envs.reset()
print("Isaac Gym 查看器的图像是一个形状为", envs.render(mode="rgb_array").shape, "的数组")
for _ in range(100):
	actions = 2.0 * torch.rand((num_envs,) + envs.action_space.shape, device = 'cuda:0') - 1.0
	envs.step(actions)

在训练过程中捕获视频

您可以通过切换 capture_video=True 标志来自动捕获智能体的游戏过程视频，并通过 capture_video_freq=1500 调整捕获频率，以及通过 capture_video_len=100 设置视频长度。当不需要捕获视频时，可以将 force_render=False 设置为禁用渲染。

python train.py capture_video=True capture_video_freq=1500 capture_video_len=100 force_render=False

您还可以将视频自动上传到 Weights and Biases：

python train.py task=Ant wandb_activate=True wandb_entity=nvidia wandb_project=rl_games capture_video=True force_render=False

Pre-commit

我们使用 pre-commit 来自动化一些能够提升代码质量的小任务。在向仓库提交更改之前，请确保运行 pre-commit run --all-files 时不出现任何错误。

故障排除

如果您遇到任何问题，请先查看 Isaac Gym 的安装说明。

您可以选择通过 GitHub 提交问题，也可以通过 Isaac Gym 论坛 提交。

引用

请按以下方式引用本项目：

@misc{makoviychuk2021isaac,
      title={Isaac Gym: High Performance GPU-Based Physics Simulation For Robot Learning}, 
      author={Viktor Makoviychuk and Lukasz Wawrzyniak and Yunrong Guo and Michelle Lu and Kier Storey and Miles Macklin and David Hoeller and Nikita Rudin and Arthur Allshire and Ankur Handa and Gavriel State},
      year={2021},
      journal={arXiv preprint arXiv:2108.10470}
}

注意：如果您使用了 DexPBT：通过基于群体的训练扩展手-臂系统的灵巧操作相关工作或代码，请引用以下论文：

@inproceedings{
	petrenko2023dexpbt,
	author = {Aleksei Petrenko, Arthur Allshire, Gavriel State, Ankur Handa, Viktor Makoviychuk},
	title = {DexPBT: Scaling up Dexterous Manipulation for Hand-Arm Systems with Population Based Training},
	booktitle = {RSS},
	year = {2023}
}

注意：如果您使用了 DeXtreme：从仿真到现实的敏捷手持操作迁移相关工作或与自动领域随机化相关的代码，请引用以下论文：

@inproceedings{
	handa2023dextreme,
	author = {Ankur Handa, Arthur Allshire, Viktor Makoviychuk, Aleksei Petrenko, Ritvik Singh, Jingzhou Liu, Denys Makoviichuk, Karl Van Wyk, Alexander Zhurkevich, Balakumar Sundaralingam, Yashraj Narang, Jean-Francois Lafleche, Dieter Fox, Gavriel State},
	title = {DeXtreme: Transfer of Agile In-hand Manipulation from Simulation to Reality},
	booktitle = {ICRA},
	year = {2023}
} 

注意：如果您在工作中使用了 ANYmal 复杂地形环境，请务必引用以下文献：

@misc{rudin2021learning,
      title={Learning to Walk in Minutes Using Massively Parallel Deep Reinforcement Learning}, 
      author={Nikita Rudin and David Hoeller and Philipp Reist and Marco Hutter},
      year={2021},
      journal = {arXiv preprint arXiv:2109.11978}
}

注意：如果您在工作中使用了 Trifinger 环境，请务必引用以下文献：

@misc{isaacgym-trifinger,
  title     = {{Transferring Dexterous Manipulation from GPU Simulation to a Remote Real-World TriFinger}},
  author    = {Allshire, Arthur and Mittal, Mayank and Lodaya, Varun and Makoviychuk, Viktor and Makoviichuk, Denys and Widmaier, Felix and Wuthrich, Manuel and Bauer, Stefan and Handa, Ankur and Garg, Animesh},
  year      = {2021},
  journal = {arXiv preprint arXiv:2108.09779}
}

注意：如果您在工作中使用了 AMP：对抗性运动先验环境，请务必引用以下文献：

@article{
	2021-TOG-AMP,
	author = {Peng, Xue Bin and Ma, Ze and Abbeel, Pieter and Levine, Sergey and Kanazawa, Angjoo},
	title = {AMP: Adversarial Motion Priors for Stylized Physics-Based Character Control},
	journal = {ACM Trans. Graph.},
	issue_date = {August 2021},
	volume = {40},
	number = {4},
	month = jul,
	year = {2021},
	articleno = {1},
	numpages = {15},
	url = {http://doi.acm.org/10.1145/3450626.3459670},
	doi = {10.1145/3450626.3459670},
	publisher = {ACM},
	address = {New York, NY, USA},
	keywords = {motion control, physics-based character animation, reinforcement learning},
} 

注意：如果您在工作中使用了 Factory 模拟方法（例如 SDF 碰撞、接触简化）或 Factory 学习工具（例如资产、环境或控制器），请引用以下论文：

@inproceedings{
	narang2022factory,
	author = {Yashraj Narang and Kier Storey and Iretiayo Akinola and Miles Macklin and Philipp Reist and Lukasz Wawrzyniak and Yunrong Guo and Adam Moravanszky and Gavriel State and Michelle Lu and Ankur Handa and Dieter Fox},
	title = {Factory: Fast contact for robotic assembly},
	booktitle = {Robotics: Science and Systems},
	year = {2022}
} 

注意：如果您在工作中使用了 IndustReal 培训环境或算法，请引用以下论文：

@inproceedings{
	tang2023industreal,
	author = {Bingjie Tang and Michael A Lin and Iretiayo Akinola and Ankur Handa and Gaurav S Sukhatme and Fabio Ramos and Dieter Fox and Yashraj Narang},
	title = {IndustReal: Transferring contact-rich assembly tasks from simulation to reality},
	booktitle = {Robotics: Science and Systems},
	year = {2023}
}

IsaacGymEnvs 快速上手指南

IsaacGymEnvs 是 NVIDIA Isaac Gym 的高性能强化学习（RL）基准环境集合，支持大规模并行仿真，专为机器人学习设计。

环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统: Linux (推荐 Ubuntu 18.04/20.04)
• GPU: 支持 CUDA 的 NVIDIA 显卡（需安装对应的驱动和 CUDA Toolkit）
• Python: 建议 Python 3.6 - 3.9
• 前置软件:
  • Isaac Gym Preview 4: 必须先从 NVIDIA 官网 下载并安装。
  • Conda: 强烈推荐使用 Conda 管理虚拟环境以简化依赖配置。

注意：在安装本仓库前，请务必先运行 Isaac Gym 自带的示例（如 python/examples/joint_monkey.py），确保基础仿真环境在您的机器上正常工作。

安装步骤

1. 创建并激活 Conda 环境

   conda create -n isaacgym python=3.8
   conda activate isaacgym
   

2. 安装 PyTorch 请根据您的 CUDA 版本安装对应的 PyTorch。例如使用 CUDA 11.3：

   pip install torch==1.10.0+cu113 torchvision==0.11.1+cu113 torchaudio==0.10.0 -f https://download.pytorch.org/whl/cu113/torch_stable.html
   

   (国内用户若下载缓慢，可尝试使用清华源：-i https://pypi.tuna.tsinghua.edu.cn/simple)

3. 克隆并安装 IsaacGymEnvs

   git clone https://github.com/NVIDIA-Omniverse/IsaacGymEnvs.git
   cd IsaacGymEnvs
   pip install -e .
   

   如果安装过程中缺少依赖，可根据报错信息手动安装 gym, hydra-core, rl-games 等包。

基本使用

1. 快速训练测试

运行以下命令即可开始训练经典的 Cartpole（倒立摆）任务。默认情况下会弹出可视化窗口，几秒内即可看到策略收敛（杆子保持直立）。

python train.py task=Cartpole

常用参数说明：

• task=Ant: 切换为蚂蚁行走任务。
• headless=True: 无头模式运行（不显示窗口），显著提升训练速度。
• num_envs=2048: 设置并行环境数量（默认为配置文件中的值）。
• sim_device=cuda:0: 指定物理仿真运行的设备。

无头模式训练示例：

python train.py task=Ant headless=True

提示：在有可视化窗口时，按 v 键可暂停渲染以加速训练，再次按 v 恢复；按 Esc 或关闭窗口可停止训练。在无头模式下，使用 Ctrl+C 停止。

2. 加载模型与推理

训练产生的检查点保存在 runs/<TASK_NAME>/nn/ 目录下。

继续训练：

python train.py task=Ant checkpoint=runs/Ant/nn/Ant.pth

仅进行推理测试（不训练）： 建议减少环境数量以降低渲染开销。

python train.py task=Ant checkpoint=runs/Ant/nn/Ant.pth test=True num_envs=64

3. Python API 调用

您可以在自己的脚本中直接创建矢量化环境并进行交互：

import isaacgym
import isaacgymenvs
import torch

num_envs = 2000

# 创建环境
envs = isaacgymenvs.make(
	seed=0, 
	task="Ant", 
	num_envs=num_envs, 
	sim_device="cuda:0",
	rl_device="cuda:0",
)

print("Observation space is", envs.observation_space)
print("Action space is", envs.action_space)

obs = envs.reset()

# 执行随机动作步
for _ in range(20):
	random_actions = 2.0 * torch.rand((num_envs,) + envs.action_space.shape, device = 'cuda:0') - 1.0
	envs.step(random_actions)

4. 高级配置 (Hydra)

本项目使用 Hydra 管理配置，支持通过命令行直接覆盖配置文件中的参数：

• 修改超参数: 例如修改折扣因子 gamma

  python train.py task=Ant train.params.config.gamma=0.999
  

• 多 GPU 训练:

  torchrun --standalone --nnodes=1 --nproc_per_node=2 train.py multi_gpu=True task=Ant
  

• 开启 WandB 日志记录:

  python train.py task=Ant wandb_activate=True wandb_project=my_project
  

更多任务列表及详细配置请参考 isaacgymenvs/config/ 目录下的 YAML 文件。