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.7apptainer version 1.2.5-1.el7和docker version 24.0.7
在出现问题的情况下，请尝试切换到这些版本。
配置Cluster参数#
首先，您需要在 docker/.env.cluster 文件中配置特定于Cluster的参数。以下描述了需要配置的参数:
参数 |
描述 |
|---|---|
CLUSTER_JOB_SCHEDULER |
您的Cluster使用的作业调度器/工作负载管理器。目前，我们支持 ‘SLURM’ 和 ‘PBS’ 工作负载管理器。 |
CLUSTER_ISAAC_SIM_CACHE_DIR |
存储 Isaac Sim 缓存的Cluster目录。该目录必须以 |
CLUSTER_ISAACLAB_DIR |
存储 Isaac Lab 日志的Cluster目录。该目录必须以 |
CLUSTER_LOGIN |
登录到Cluster。通常，这是用户和Cluster名称，例如， |
CLUSTER_SIF_PATH |
存储 singularity 镜像的Cluster路径。镜像将被复制到计算节点，但在提交作业时不会再次上传到Cluster。 |
REMOVE_CODE_COPY_AFTER_JOB |
是否在作业完成后应删除复制的代码。作业生成的日志不会被删除，因为这些日志保存在永久的 |
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 目录下。