Cluster 指南

Cluster 指南#

Cluster是加快训练和学习算法评估的好方法。尽管 Isaac Lab Docker 镜像可用于在Cluster上运行作业，但许多Cluster只支持 singularity 镜像。这是因为 singularity 专为共享多用户系统和高性能计算（HPC）环境的易用性而设计。它不需要 root 权限来运行容器，并且可以用于运行用户定义的容器。

Singularity 与所有 Docker 镜像兼容。在本节中，我们将描述如何将 Isaac Lab Docker 镜像转换为 singularity 镜像，并使用它提交作业到Cluster。

注意

Cluster设置因不同的机构而异。以下说明已在使用 SLURM 工作负载管理器的 ETH Zurich Euler Cluster和使用 PBS 工作负载管理器的 IIT Genoa Franklin Cluster上进行了测试。

指示可能需要针对其他Cluster进行调整。如果您已成功地为另一个Cluster调整了指示，请考虑为文档做出贡献。

设置说明#

为了将 Docker 镜像导出为singularity镜像，需要使用 apptainer 。关于 apptainer 的安装过程的详细概述可以在其 文档 中找到。为方便起见，我们在这里总结了本地安装的步骤：

sudo apt update
sudo apt install -y software-properties-common
sudo add-apt-repository -y ppa:apptainer/ppa
sudo apt update
sudo apt install -y apptainer

为简单起见，我们建议在本地开发机器和Cluster之间建立 SSH 连接。这样的连接将简化文件传输，避免用户多次请求用户Cluster密码。

注意

工作流已针对 apptainer version 1.2.5-1.el7 和 docker version 24.0.7 进行了测试。

  • apptainer ：已报告了与先前版本（如 apptainer version 1.1.3-1.el7 ）相关的绑定问题。请确保您使用的是最新版本。

  • Docker ：最新版本（ 25.x ）目前无法使用，因为它们与 apptainer/singularity 尚不兼容。

    我们正在等待 apptainer 团队的更新。要跟踪此问题，请查看 论坛帖子 。

配置Cluster参数#

首先，您需要在 docker/.env.cluster 文件中配置特定于Cluster的参数。以下描述了需要配置的参数：

参数

描述

CLUSTER_JOB_SCHEDULER 集群作业调度器

您的Cluster使用的作业调度器/工作负载管理器。目前，我们支持 ‘SLURM’ 和 ‘PBS’ 工作负载管理器。

CLUSTER_ISAAC_SIM_CACHE_DIR

存储 Isaac Sim 缓存的Cluster目录。该目录必须以 docker-isaac-sim 结尾。此目录将被复制到计算节点并挂载到 singularity 容器中。这应该提高模拟的启动速度。

CLUSTER_ISAACLAB_DIR

存储 Isaac Lab 日志的Cluster目录。该目录必须以 isaaclab 结尾。此目录将被复制到计算节点并挂载到 singularity 容器中。提交作业时，最新的本地更改将复制到集群的新目录中，格式为 ${CLUSTER_ISAACLAB_DIR}_${datetime} ，其中包含作业提交的日期和时间。这允许同时运行具有不同代码版本的多个作业。

CLUSTER_LOGIN

登录到Cluster。通常，这是用户和Cluster名称，例如， your_user@euler.ethz.ch 。

CLUSTER_SIF_PATH

存储 singularity 镜像的Cluster路径。镜像将被复制到计算节点，但在提交作业时不会再次上传到Cluster。

REMOVE_CODE_COPY_AFTER_JOB

是否在作业完成后应删除复制的代码。作业生成的日志不会被删除，因为这些日志保存在永久的 CLUSTER_ISAACLAB_DIR 下。此功能对于节省集群上的磁盘空间非常有用。如果设置为 true，则代码副本将被删除。

CLUSTER_PYTHON_EXECUTABLE

Isaac Lab 中应在提交的作业中执行的 Python 可执行文件的路径。

当一个 job 被提交时，它还会使用在 docker/.env.base 中定义的变量，尽管这些变量默认情况下应该是正确的。

导出为 singularity 镜像#

接下来，我们需要将 Docker 镜像导出为 singularity 镜像并上传到Cluster。这一步仅在首次提交作业或更新 Docker 镜像时需要。例如，由于升级 Isaac Sim 版本，或者项目的其他要求。

要导出为 singularity 镜像，请执行以下命令：

./docker/cluster/cluster_interface.sh push [profile]

该命令将在 docker/exports 目录下创建一个 singularity 镜像，并将其上传到Cluster上定义的位置。它要求您先前使用 container.py 接口构建了镜像。请注意，创建 singularity 镜像可能需要一段时间。 [profile] 是一个可选参数，用于指定要使用的容器配置文件。如果未指定配置文件，则将使用默认配置文件 base 。

备注

默认情况下，通过在 apptainer build 命令中提供 --fakeroot 标志，无需 root 访问权限即可创建 singularity 镜像。如果镜像创建失败，您可以尝试通过在 docker/cluster/cluster_interface.sh 中删除该标志以带有 root 访问权限创建它。

定义作业参数#

作业参数需要根据Cluster使用的作业调度器进行定义。您只需要更新适用于您的调度器的适当脚本。

  • 对于 SLURM，请更新 docker/cluster/submit_job_slurm.sh 中的参数。

  • 对于 PBS，请更新 docker/cluster/submit_job_pbs.sh 中的参数。

对于 SLURM#

作业参数在 docker/cluster/submit_job_slurm.sh 中定义。典型的 SLURM 操作需要指定 CPU 和 GPU 的数量，内存和时间限制。有关更多信息，请查看 SLURM 文档 。

默认配置如下：

12#SBATCH --cpus-per-task=8
13#SBATCH --gpus=rtx_3090:1
14#SBATCH --time=23:00:00
15#SBATCH --mem-per-cpu=4048
16#SBATCH --mail-type=END
17#SBATCH --mail-user=name@mail
18#SBATCH --job-name="training-$(date +"%Y-%m-%dT%H:%M")"

Cluster的一个重要要求是计算节点始终可以访问互联网。这是从 Nucleus 服务器加载资产所需的。对于某些Cluster体系结构，必须加载额外的模块才能允许访问互联网。

例如，在 ETH Zurich Euler Cluster上，需要加载 eth_proxy 模块。这可以通过向 submit_job_slurm.sh 脚本添加以下行来完成：

3# in the case you need to load specific modules on the cluster, add them here
4# e.g., `module load eth_proxy`

对于 PBS#

作业参数在 docker/cluster/submit_job_pbs.sh 中定义。典型的 PBS 操作需要指定 CPU 和 GPU 的数量以及时间限制。有关更多信息，请查看 PBS 官方网站 。

默认配置如下：

11#PBS -l select=1:ncpus=8:mpiprocs=1:ngpus=1
12#PBS -l walltime=01:00:00
13#PBS -j oe
14#PBS -q gpu
15#PBS -N isaaclab
16#PBS -m bea -M "user@mail"

提交作业#

要在Cluster上提交作业，可以使用以下命令：

./docker/cluster/cluster_interface.sh job [profile] "argument1" "argument2" ...

此命令将会将您代码的最新更改复制到Cluster并提交一个作业。请确保您的 Python 可执行文件的输出存储在 isaaclab/logs 下，因为该目录将再次从计算节点复制到 CLUSTER_ISAACLAB_DIR 。

[profile] 是一个可选参数，用于指定要使用的与容器配置文件对应的 singularity 镜像。如果未指定配置文件，所有其他参数将传递给 Python 可执行文件。如果未定义配置文件，所有参数都将传递给 Python 可执行文件。

训练参数将传递给 Python 可执行文件。例如，标准的 ANYmal 粗糙地形运动训练可以使用以下命令执行：

./docker/cluster/cluster_interface.sh job --task Isaac-Velocity-Rough-Anymal-C-v0 --headless --video --enable_cameras

上述命令还会渲染训练进度的视频，并将其存储在 isaaclab/logs 目录下。

目录