cuQuantum Appliance

cuQuantum Applianceについて

NVIDIA cuQuantumは、量子回路シミュレーションをGPUで加速できるソフトウェア開発キットです。量子回路シミュレーションとしては、IBM Qiskit Aer、Google Cirq qsimに対応しています。

NVIDIA cuQuantum Applianceは、NVIDIA cuQuantumを簡単に利用できるようデプロイ可能なソフトウェアとしてコンテナ化されたもので、複数のGPUと複数のノードを活用して量子回路シミュレーションを実行することができます。

本ドキュメントでは、次の流れに沿ってcuQuantum Applianceの使い方について説明します。

cuQuantum ApplianceをABCIで実行可能なSingularityイメージに変換する。
IBM Qiskit Aerの状態ベクトルシミュレーションをシングルノード・マルチGPUで実行する。
Open MPIを用いて、状態ベクトルシミュレーションをマルチノード・マルチGPUで実行する。

cuQuantum ApplianceをSingularityイメージに変換する

NVIDIA NGC(以下「NGC」という)で公開されているcuQuantum ApplianceのDockerイメージからSingularityイメージを作成します。

最初に、コンテナを作成するためのDefinition fileを用意します。（以下、ファイル名の cuquantum-appliance は、任意の名前で構いません）

[username@qes01 ~]$ cat cuquantum-appliance.def
Bootstrap: docker
From: nvcr.io/nvidia/cuquantum-appliance:25.11-cuda12.9.1-devel-ubuntu24.04-x86_64
%environment
    source /opt/etc/bashrc
    export CONDA_ENV_NAME=cuquantum
    conda info -e >> /dev/stderr

%post -c /bin/bash
    apt update
    apt dist-upgrade -y
    apt install git vim -y
    chmod -R o+rX /home/cuquantum
    mkdir -p /opt/etc
    echo -e "#! /bin/bash\n\n# script to activate the conda environment" > ~/.bashrc \
    && conda init bash \
    && echo -e "\nconda activate cuquantum" >> ~/.bashrc \
    && echo "echo \"Hello World\" >>/dev/stderr " >>  ~/.bashrc \
    && conda clean -a \
    && cp ~/.bashrc /opt/etc/bashrc

次に、インタラクティブジョブを投入し計算ノードにログインし、コンテナを作成します。

[username@qes01 ~]$ qsub -I -W group_list=your_group_name -l rt_QG=1 -l walltime=1:00:00
.
.
[username@qh001 ~]$ SINGULARITY_TMPDIR=$PBS_LOCALDIR singularity build --fakeroot cuquantum-appliance.img cuquantum-appliance.def
.
.
INFO:    Creating SIF file...
INFO:    Build complete: cuquantum-appliance.img

singularity build/pullコマンドは一時ファイルの作成場所として/tmpを使用します。 cuQuantum Applianceは、イメージサイズの大きいコンテナで、計算ノード上でsingularity build/pullする際に/tmpの容量が足りずエラーになる場合があります。そこで、ローカルスクラッチを使用するようSINGULARITY_TMPDIR環境変数を設定しています。

作成したSingularityイメージcuquantum-appliance.imgを利用する方法は以下のとおりです。

[username@hnode001 ~]$ singularity run --nv ./cuquantum-appliance.img

以下のように、cuQuantum Applianceが起動します。

.
.
==========================================================================
===                 NVIDIA CUQUANTUM APPLIANCE v25.11                  ===
==========================================================================
=== COPYRIGHT © NVIDIA CORPORATION & AFFILIATES.  All rights reserved. ===
==========================================================================


WARNING: no nvidia devices were detected
WARNING: gpu functionality will not be available

Singularity>

シングルノード・マルチGPUで実行する

バッチジョブでの実行

cuQuantum Applianceのコンテナイメージでは、インストールされているOpen MPIを使用して、マルチGPUでシミュレーションが実行可能です。また、Google の qsimcirq ではマルチGPUの使用をサポートしています。アプライアンス内のサンプルプログラム(/home/cuquantum/examples/ghz.py)を参照ください。（割り当てるGPUの数をオプションで指定可能です。）

ここでは、cuQuantum Appliance内に用意されているサンプルプログラム(/home/cuquantum/examples/qiskit_ghz.py)を実行してみます。

バッチスクリプトjob.sh(名前は任意)を用意し、ジョブを投入します。

[username@qes01 ~]$ cat job.sh
#!/bin/sh
#PBS -W group_list=your_group
#PBS -l rt_QF=1:mpiprocs=4
#PBS -l walltime=00:15:00

cd ${HOME}/cuQuantum

source /etc/profile.d/modules.sh
module load openmpi/5.0.8

mpirun -np 4 -display map singularity exec --nv cuquantum-appliance.sif python3 /home/cuquantum/examples/qiskit_ghz.py --nbits 33 --precision double

[username@qes01 ~]$ qsub job.sh

結果は、以下の様に、1ノード上に8プロセスが起動されていることがわかります。

========================   JOB MAP   ========================
Data for JOB prterun-qh035-2013862@1 offset 0 Total slots allocated 4
    Mapping policy: BYCORE:NOOVERSUBSCRIBE  Ranking policy: FILL Binding policy: CORE:IF-SUPPORTED
    Cpu set: N/A  PPR: N/A  Cpus-per-rank: N/A  Cpu Type: CORE


Data for node: qh035    Num slots: 4    Max slots: 0    Num procs: 4
        Process jobid: prterun-qh035-2013862@1 App: 0 Process rank: 0 Bound: package[0][core:0]
        Process jobid: prterun-qh035-2013862@1 App: 0 Process rank: 1 Bound: package[0][core:1]
        Process jobid: prterun-qh035-2013862@1 App: 0 Process rank: 2 Bound: package[0][core:2]
        Process jobid: prterun-qh035-2013862@1 App: 0 Process rank: 3 Bound: package[0][core:3]

=============================================================
precision: double
{'000000000000000000000000000000000': 510, '111111111111111111111111111111111': 514}
backend: cusvaer_simulator_statevector

PBS のジョブのリソースとして、"rt_QF=1:mpiprocs=4" を指定し、1 計算ノードを資源タイプrt_QFで1ノードを要求しています。（１ノードを確保し、ノード上でで４プロセスまで同時に起動可能です。）

マルチノード・マルチGPUで実行する

マルチノードでの実行を行うには、ABCI-Q で提供されている Open MPIを使用して、実行が可能です。

バッチジョブでの実行

シングルノード、マルチGPUで使用したサンプルと同じpython スクリプトを使用し、計算ノード４台を用いたジョブスクリプト job.sh を用意し、ジョブを投入します。（mpirun のオプション --display-allocationは、確保されたリソースの状況を表示するためのオプションで、なくても構いません。）

[username@qes01 ~]$ cat jobm.sh
#!/bin/sh
#PBS -W group_list=your_group
#PBS -l rt_QF=2:mpiprocs=4
#PBS -l walltime=00:30:00

source /etc/profile.d/modules.sh
module load openmpi/5.0.8

export MPIOPTS="-n 8 --map-by ppr:4:node --display map"

cd /home/your_home_directory/your_work_directory
MPIRUN=`which mpirun`
$MPIRUN -v $MPIOPTS --display-allocation  singularity exec --nv $MPIENVS cuquantum-appliance.sif python3 ./qiskit_ghz.py --nbits 20 --precision double

[username@qes01 ~]$ qsub jobm.sh

結果は、以下の様になります。

MPI option is : -n 8 --map-by ppr:4:node --display map

========================   JOB MAP   ========================
Data for JOB prterun-qh033-111644@1 offset 0 Total slots allocated 8
    Mapping policy: BYNODE:NOOVERSUBSCRIBE  Ranking policy: SLOT Binding policy: NUMA:IF-SUPPORTED
    Cpu set: N/A  PPR: 4:node  Cpus-per-rank: N/A  Cpu Type: CORE


Data for node: qh033    Num slots: 4    Max slots: 0    Num procs: 4
        Process jobid: prterun-qh033-111644@1 App: 0 Process rank: 0 Bound: package[0][core:0-47]
        Process jobid: prterun-qh033-111644@1 App: 0 Process rank: 1 Bound: package[0][core:0-47]
        Process jobid: prterun-qh033-111644@1 App: 0 Process rank: 2 Bound: package[0][core:0-47]
        Process jobid: prterun-qh033-111644@1 App: 0 Process rank: 3 Bound: package[0][core:0-47]

Data for node: qh035    Num slots: 4    Max slots: 0    Num procs: 4
        Process jobid: prterun-qh033-111644@1 App: 0 Process rank: 4 Bound: package[0][core:0-47]
        Process jobid: prterun-qh033-111644@1 App: 0 Process rank: 5 Bound: package[0][core:0-47]
        Process jobid: prterun-qh033-111644@1 App: 0 Process rank: 6 Bound: package[0][core:0-47]
        Process jobid: prterun-qh033-111644@1 App: 0 Process rank: 7 Bound: package[0][core:0-47]

=============================================================
precision: double
{'00000000000000000000': 539, '11111111111111111111': 485}
backend: cusvaer_simulator_statevector

PBS のジョブのリソースとして、"rt_QF=2:mpiprocs=4" を指定し、計算ノードを資源タイプrt_QFで2ノードで起動しています。（２ノードを確保し、それぞれのノードで４プロセスまで同時に起動可能です。）

mpirun のオプションで、"-np 8 -map-by ppr:4:node" で、総プロセス数8、ノード当たり4プロセスを指定しています。

上記の出力から、2ノードが割り当てられ、それぞれに4プロセスづつ割り当てられてられ、それぞれのプロセスにMPIのランクが割り当てられていることがわかります。

オプションの詳細は、cuQuantum Applianceのドキュメントを参照してください。

cuQuantum Appliance

cuQuantum Applianceについて

cuQuantum ApplianceをSingularityイメージに変換する

シングルノード・マルチGPUで実行する

バッチジョブでの実行

マルチノード・マルチGPUで実行する

バッチジョブでの実行

参考