GPU 機房使用者教學

NYCU CSIT HPC service

Access login node

ssh <username>@hpclogin[01-03].cs.nycu.edu.tw

Setup environment

Note

  • 若課程有任何軟體需求，請助教來信告知
  • 建議使用 bash

若助教有先告知課程軟體需求，會根據需求產生對應套件環境。

Example

以「平行程式設計」課程作範例，課程環境名稱為 pp。

本 HPC 服務使用 lmod 來管理軟體環境，使用者可以透過 module 指令來載入課程環境。

$ module load pp

想退出環境可以使用：

$ module unload pp

重新登入之後，本來啟用的環境不會保留，如果想要每次登入都自動載入環境，可以將 module load pp 加入到 .bashrc 中。

Using lmod on fish

預設情況下，Lmod 會自動支援 bash、zsh、tcsh 等 shell，但 fish shell 需要手動啟用相應初始化設定。

若你使用 fish shell，請在你的個人設定檔中加入以下內容：

nano ~/.config/fish/config.fish

在檔案中加入這一行：

source /usr/share/lmod/lmod/init/fish

儲存後重新啟動一個新的 fish session，或執行：

source ~/.config/fish/config.fish

即可啟用 module 指令

Submit job

Caution

  • 無法直接使用 srun 指令是正常的，請使用 sbatch 指令用腳本發送 job
  • 須確保程式中讀寫的檔案以及程式本身在 NFS 中，否則會執行異常或看不到結果

To simply put, just prepare your job script, then use sbatch <script name>.sh to submit job

Examples

Submit a MPI job

  1. 準備好程式
  • mpi.cpp 
#include <mpi.h>
#include <stdio.h>

int main(int argc, char** argv) {
    MPI_Init(NULL, NULL);

    int world_size;
    MPI_Comm_size(MPI_COMM_WORLD, &world_size);

    int world_rank;
    MPI_Comm_rank(MPI_COMM_WORLD, &world_rank);

    char processor_name[MPI_MAX_PROCESSOR_NAME];
    int name_len;
    MPI_Get_processor_name(processor_name, &name_len);

    printf("Hello world from processor %s, rank %d out of %d processors\n",
           processor_name, world_rank, world_size);

    MPI_Finalize();
}
  1. 在 Login node 上編譯
user@login01:~$ mpic++ mpi.cpp
  1. 準備好 sbatch script，在 Login node 上發 job
user@login01:~$ sbatch test.sh
  • test.sh 
#!/bin/bash
#SBATCH -A general              # Account name (可透過 sshare 查看)
#SBATCH -p class_nodes          # Partition name (可透過 sinfo 查看 partition)
#SBATCH -n 3                   # Number of MPI tasks (i.e. processes)
#SBATCH -c 1                     # Number of cores per MPI task
#SBATCH -N 3                     # Maximum number of nodes to be allocated
#SBATCH -t 00:05:00             # (--time) Wall time limit (days-hrs:min:sec)
# 還有很多其他參數，可參考官方文件(https://slurm.schedmd.com/sbatch.html)

export PMIX_MCA_psec="^munge"

srun --mpi=pmix ./a.out

  1. 可以透過 squeue 查看 job 排隊/運行狀況，或是用 sacct 查看以往的 job (包含剛剛發出的)

  2. 完成後，可以在家目錄看到 slurm-<job id>.out 的文字檔，可以直接查看結果

user@login01:~$ cat slurm-74.out
Hello world from processor cmpt001.hpc.cc.cs.nctu.edu.tw, rank 0 out of 3 processors
Hello world from processor cmpt002.hpc.cc.cs.nctu.edu.tw, rank 1 out of 3 processors
Hello world from processor cmpt003.hpc.cc.cs.nctu.edu.tw, rank 2 out of 3 processors

Submit a job using GPU

Take cuda-samples for example.

  1. Prepare your code
    user@login01:~$ git clone https://github.com/NVIDIA/cuda-samples.git

  2. Compile it
    cd cuda-samples/Samples/1_Utilities/deviceQuery && cmake . && make

  3. Prepare sbatch script test.sh

#!/bin/bash
#SBATCH -A general              # Account name (可透過 sshare 查看)
#SBATCH -p class_nodes           # Partition name (可透過 sinfo 查看 partition)
#SBATCH -N 1                     # Maximum number of nodes to be allocated
#SBATCH --gres=gpu:1            # specify GPU number
# 還有很多其他參數，可參考官方文件(https://slurm.schedmd.com/sbatch.html)

export LD_PRELOAD=/lib/x86_64-linux-gnu/libcuda.so.1 # for CUDA driver API

./deviceQuery
  1. 透過 sbatch 發送 job
user@login01:~/cuda-samples/Samples/1_Utilities/deviceQuery$ sbatch test.sh

之後一樣會在當前目錄看到 slurm-<job id>.out 的文字檔，可以直接查看結果

Cancel job

為避免一個使用者發出大量 job 佔據大多資源，所以有限制一個使用者同時就只能發一個 job。若上個 job 發錯，想要發新的 job 就需要 cancel 上個 job

scancel -u <your username>

Apptainer 使用說明

Apptainer 是由 Singularity 分支出的 rootless container 專案，因為被 Linux Foundation 納入維護，所以選擇使用它而非 singularity-ce（community edition）。

Apptainer setup

Apptainer 已透過 Spack 安裝於系統中，透過lmod啟用環境後即可直接使用：

ml container

# check apptainer command existence
apptainer --version

使用者無需自行安裝。

建立 Apptainer Image

Build image（使用 definition file）

apptainer build <image>.sif <definition>.def

Pull image（從 Docker Hub）

Apptainer 可直接讀取 Docker Hub image 並轉為 .sif：

# 這會輸出ubuntu_20.04.sif
apptainer pull docker://ubuntu:20.04

或指定輸出檔名：

apptainer pull <filename>.sif docker://ubuntu:20.04

Apptainer Definition File（.def）說明

一個標準的 .def 檔通常包含以下區段：

  • Header
    定義映像檔來源。

    • Bootstrap: 來源類型 (如 docker, library, localimage)。
    • From: 具體的映像檔名稱 (如 ubuntu:20.04, debian:bullseye-slim)。

  • %environment

    • 執行時機：每次執行容器（run / exec / shell）
    • 用途：設定環境變數（PATH、LD_LIBRARY_PATH）

  • %post

    • 執行時機：Build image 過程中
    • 權限：容器內具有 root 權限
    • 用途：安裝套件、編譯程式

  • %runscript

    • 執行時機：apptainer run <image>.sif
    • 用途：容器預設執行指令（類似 Docker ENTRYPOINT）

Example usage

1. OSU Micro-Benchmarks（MPI）

Build image

  • Definition file: osu.def 
Bootstrap: docker
From: debian:12-slim

%environment
    export PMIX_MCA_gds=^ds12
    export PMIX_MCA_psec=^munge
    export OSU_DIR=/opt/libexec/osu-micro-benchmarks/mpi

%post
    apt-get -y update && \
    DEBIAN_FRONTEND=noninteractive apt-get -y install \
        build-essential libopenmpi-dev wget

    cd /root
    wget https://mvapich.cse.ohio-state.edu/download/mvapich/osu-micro-benchmarks-7.5-1.tar.gz
    tar -xzf osu-micro-benchmarks-7.5-1.tar.gz
    cd osu-micro-benchmarks-7.5-1

    ./configure --prefix=/opt CC=/usr/bin/mpicc CXX=/usr/bin/mpicxx
    make -j6 && make install

%runscript
    echo "Rank ${SLURM_PROCID} - Running: ${OSU_DIR}/$*"
    exec ${OSU_DIR}/$*

在 login node 執行

apptainer build osu.sif osu.def

查看容器內檔案系統

想確認 OSU_DIR 底下有什麼可以透過 apptainer exec <image> <command> 去查看容器內部的檔案系統。

apptainer exec osu.sif ls -R /opt/libexec/osu-micro-benchmarks/mpi

在 Slurm 環境中執行

範例：OSU Micro-Benchmarks（MPI）執行腳本

  • run_osu.sh 
#!/bin/bash
#SBATCH --job-name=osu_test
#SBATCH --nodes=2
#SBATCH --ntasks-per-node=1
#SBATCH --output=osu_bw.out
#SBATCH --partition=class_nodes

IMAGE="osu.sif"

srun --mpi=pmix apptainer run $IMAGE pt2pt/osu_bw

在 login node 執行

sbatch run_osu.sh

2. CUDA Sample: deviceQuery (GPU)

Build image

  • Definition file: sample.def 
Bootstrap: docker
From: nvidia/cuda:12.8.1-base-ubuntu24.04

%post
    sed -i 's|http://archive.ubuntu.com/ubuntu/|http://ubuntu.cs.nycu.edu.tw/ubuntu/|g' /etc/apt/sources.list.d/ubuntu.sources
    apt-get -y update && DEBIAN_FRONTEND=noninteractive apt-get -y install wget cmake make unzip cuda-compiler-12.8
    apt-get clean autoclean && apt-get autoremove --yes && rm -rf /var/lib/apt/lists/*

    cd /opt
    wget https://github.com/NVIDIA/cuda-samples/archive/refs/heads/master.zip
    unzip master.zip
    cd cuda-samples-master
    cd Samples/1_Utilities/deviceQuery
    cmake .
    make -j$(nproc)
    rm /opt/master.zip

在 login node 執行

apptainer build sample.sif sample.def

在 Slurm 環境中執行

於 login node 下 sbatch sample.sh 指令

  • sample.sh 
#!/bin/bash
#SBATCH -A <account>  # specify your account name
#SBATCH -p class_nodes
#SBATCH -N 1
#SBATCH --gres=gpu:1

#apptainer exec --nv sample.sif nvidia-smi
apptainer exec --nv sample.sif /opt/cuda-samples-master/Samples/1_Utilities/deviceQuery/deviceQuery

3. PyTorch with CUDA (GPU)

Build image

  • Definition file: torch.def 
Bootstrap: docker
From: nvidia/cuda:12.8.1-base-ubuntu24.04

%post
    sed -i 's|http://archive.ubuntu.com/ubuntu/|http://ubuntu.cs.nycu.edu.tw/ubuntu/|g' /etc/apt/sources.list.d/ubuntu.sources
    apt-get -y update && DEBIAN_FRONTEND=noninteractive apt-get -y install python3 python3-pip
    apt-get clean autoclean && apt-get autoremove --yes && rm -rf /var/lib/apt/lists/*

    pip3 install --no-cache-dir torch torchvision --break-system-packages

在 login node 執行

apptainer build torch.sif torch.def

在 Slurm 環境中執行

於 login node 下 sbatch pytorch.sh 指令

  • pytorch.sh 
#!/bin/bash
#SBATCH -A <account>  # specify your account name
#SBATCH -p class_nodes
#SBATCH -N 1
#SBATCH --gres=gpu:nvidia_geforce_rtx_5050:1

apptainer exec --nv torch.sif python -c "import torch; print(torch.cuda.is_available()); print(torch.cuda.get_device_name(0));"

Reference