NVIDIA cuQuantum 设备¶

NVIDIA cuQuantum 设备是用于量子线路模拟的高性能多 GPU 多节点解决方案。它包含 NVIDIA 的 cuStateVec、cuTensorNet 和 cuDensityMat 库，分别优化状态向量、张量网络和密度矩阵模拟。 cuTensorNet 和 cuDensityMat 库功能也可通过 Python 访问，用于张量网络操作和加速模拟量子动力学求解器。
借助 cuStateVec 库，NVIDIA 提供了以下模拟器

IBM 的 Qiskit Aer 前端，通过 cusvaer，NVIDIA 的分布式状态向量后端求解器。
优化的多 GPU Google Cirq 前端，通过 qsim，Google 的状态向量模拟器。

前提条件¶

使用 NVIDIA 的 cuQuantum 设备 NGC 容器需要主机系统安装以下组件

Docker 引擎
 NVIDIA GPU 驱动程序
 NVIDIA 容器工具包
有关支持的版本，请参阅容器发行说明。无需其他安装、编译或依赖项管理。

使用 NVIDIA cuQuantum 设备与 Cirq 或 Qiskit¶

注意： ${march} 是 [x86_64, arm64] 之一。

# pull the image
...$ docker pull nvcr.io/nvidia/cuquantum-appliance:24.03-${march}
# launch the container interactively
...$ docker run --gpus all \
       -it --rm nvcr.io/nvidia/cuquantum-appliance:24.03-${march}
# interactive launch, but enumerate only GPUs 0,3
...$ docker run --gpus '"device=0,3"' \
       -it --rm nvcr.io/nvidia/cuquantum-appliance:24.03-${march}

示例位于 /home/cuquantum/examples 下。使用以下命令确认

...$ docker run --gpus all --rm \
...$ nvcr.io/nvidia/cuquantum-appliance:24.03-${march} ls \
       -la /home/cuquantum/examples
...

==========================================================================
===                 NVIDIA CUQUANTUM APPLIANCE v24.03                  ===
==========================================================================
=== COPYRIGHT © NVIDIA CORPORATION & AFFILIATES.  All rights reserved. ===
==========================================================================

INFO: nvidia devices detected
INFO: gpu functionality will be available

total 36
drwxr-xr-x 2 cuquantum cuquantum 4096 Nov 10 01:52 .
drwxr-x--- 1 cuquantum cuquantum 4096 Nov 10 01:54 ..
-rw-r--r-- 1 cuquantum cuquantum 2150 Nov 10 01:52 ghz.py
-rw-r--r-- 1 cuquantum cuquantum 7436 Nov 10 01:52 hidden_shift.py
-rw-r--r-- 1 cuquantum cuquantum 1396 Nov 10 01:52 qiskit_ghz.py
-rw-r--r-- 1 cuquantum cuquantum 8364 Nov 10 01:52 simon.py

运行示例非常简单

#### without an interactive session:
...$ docker run --gpus all --rm \
       nvcr.io/nvidia/cuquantum-appliance:24.03-${march} \
         python /home/cuquantum/examples/{example_name}.py
#### with an interactive session:
...$ docker run --gpus all --rm -it \
       nvcr.io/nvidia/cuquantum-appliance:24.03-${march}
...
(cuquantum-24.03) cuquantum@...:~$ cd examples && python {example_name}.py

所有示例都接受运行时参数。要查看它们是什么，请将 --help 传递给 python + 脚本命令。查看两个示例 ghz.py 和 qiskit_ghz.py，帮助消息如下

(cuquantum-24.03) cuquantum@...:~/examples$ python ghz.py --help
usage: ghz.py [-h] [--nqubits NQUBITS] [--nsamples NSAMPLES] [--ngpus NGPUS]

GHZ circuit

options:
  -h, --help           show this help message and exit
  --nqubits NQUBITS    the number of qubits in the circuit
  --nsamples NSAMPLES  the number of samples to take
  --ngpus NGPUS        the number of GPUs to use

(cuquantum-24.03) cuquantum@...:~/examples$ python qiskit_ghz.py --help
usage: qiskit_ghz.py [-h] [--nbits NBITS] [--precision {single,double}] [--disable-cusvaer]

Qiskit ghz.

options:
  -h, --help            show this help message and exit
  --nbits NBITS         the number of qubits
  --precision {single,double}
                        numerical precision
  --disable-cusvaer     disable cusvaer

重要的是，ghz.py 使用 Cirq 作为前端实现 GHZ 线路，而 qiskit_ghz.py 使用 Qiskit 作为前端实现 GHZ 线路。 cuQuantum 设备修改了这些框架的后端，优化它们以用于 Nvidia 的平台。有关任何更改的信息，请参阅 Nvidia cuQuantum 文档的设备部分。

运行 cd examples && python ghz.py --nqubits 30 将创建并模拟在单个 GPU 上运行的 GHZ 线路。要在 4 个可用 GPU 上运行，请使用 ... python ghz.py --nqubits 30 --ngpus 4。输出将如下所示

(cuquantum-24.03) cuquantum@...:~/examples$ python ghz.py --nqubits 30
q(0),...,q(29)=111,...,111

同样，cd examples && python qiskit_ghz.py --nbits 30 将创建并模拟 GHZ 线路。此脚本将为每个进程分配一个 GPU。要在 4 个 GPU 上运行，您需要显式枚举要使用的 GPU 并使用 MPI 执行

#### interactively:
...$ docker run --gpus '"device=0,1,2,3"' \
       -it --rm nvcr.io/nvidia/cuquantum-appliance:24.03-${march}
(cuquantum-24.03) cuquantum@...:~$ cd examples
(cuquantum-24.03) cuquantum@...:~$ mpirun -np 4 python qiskit_ghz.py --nbits 30
#### noninteractively:
...$ docker run --gpus '"device=0,1,2,3"' \
       --rm nvcr.io/nvidia/cuquantum-appliance:24.03-${march} \
       mpirun -np 4 python /home/cuquantum/examples/qiskit_ghz.py --nbits 30

来自 qiskit_ghz.py 的输出如下所示

(cuquantum-24.03) cuquantum@...:~$ cd examples
(cuquantum-24.03) cuquantum@...:~$ python qiskit_ghz.py --nbits 30
...
precision: single
{'0...0': 520, '1...1': 504}

注意： Qiskit 可能会为每个 rank 初始化所有可用 GPU 的 CUDA 上下文。

更多信息、示例和实用程序可在 GitHub 上的 NVIDIA cuQuantum 存储库中找到。值得注意的是，您可以找到使用基准测试工具开始多节点多 GPU 模拟的有用指南。

容器中的软件¶

默认用户环境¶

容器中的默认用户是 cuquantum，用户 ID 为 1000。cuquantum 用户是 sudo 组的成员。默认情况下，使用 cuquantum 用户通过 sudo 执行命令需要密码，密码可以通过读取位于 /home/cuquantum/.README 的文件获得，格式为 {user}:{password}。

要获取新软件包，我们建议在默认环境 (cuquantum-24.03) 中使用 conda install -c conda-forge ...。您可以使用 conda create --name {new_name} --clone cuquantum-24.03 克隆此环境并更改名称。这可能有助于将您的更改与默认环境隔离。

CUDA 在 /usr/local/cuda 下可用。/usr/local/cuda 是由 update-alternatives 管理的符号目录。要查询配置信息，请使用 update-alternatives --config cuda。

MPI¶

我们在位于 /usr/local/openmpi 的容器中提供了 Open MPI v4.1。可以使用 ompi_info --all --parseable 查询默认 mpirun 运行时配置。当在 cuQuantum 设备中使用多 GPU 功能时，必须向容器公开有效且兼容的 mpirun 运行时配置。它还必须可供容器运行时访问。

如果在容器中调用 mpirun 时观察到以下警告或错误:

    [LOG_CAT_ML] You must specify a valid HCA device by setting:
    -x HCOLL_MAIN_IB=<dev_name:port> or  or -x UCX_NET_DEVICES=<dev_name:port>.
    If no device was specified for HCOLL (or the calling library), automatic device detection will be run.
    ...
    In case of unfounded HCA device please contact your system administrator.
    ...
    ... Error: coll_hcoll_module.c:310 - mca_coll_hcoll_comm_query() Hcol library init failed

在容器的交互式会话中，指定模块化组件架构，以禁用跨内存附加 (CMA) 和分层集合 (HCOLL)

mpirun -np ${num_gpus} \
    --mca pml ucx \
    -x UCX_TLS=^cma \
    --mca coll_hcoll_enable 0 \
    -x OMPI_MCA_coll_hcoll_enable=0 \
    {your_command}

如果不再发出警告和错误，请咨询您的系统管理员并确认硬件和软件架构，以确保 cuQuantum 设备的最优使用。

重要变更通知¶

版本 `== 24.03`¶

以下镜像标签可用:

nvcr.io/nvidia/cuquantum-appliance:24.03-cuda11.8.0-devel-ubuntu20.04-x86_64
nvcr.io/nvidia/cuquantum-appliance:24.03-cuda12.2.2-devel-ubuntu20.04-x86_64
nvcr.io/nvidia/cuquantum-appliance:24.03-cuda11.8.0-devel-ubuntu22.04-x86_64
nvcr.io/nvidia/cuquantum-appliance:24.03-cuda12.2.2-devel-ubuntu22.04-x86_64

nvcr.io/nvidia/cuquantum-appliance:24.03-cuda11.8.0-devel-ubuntu20.04-arm64
nvcr.io/nvidia/cuquantum-appliance:24.03-cuda12.2.2-devel-ubuntu20.04-arm64
nvcr.io/nvidia/cuquantum-appliance:24.03-cuda11.8.0-devel-ubuntu22.04-arm64
nvcr.io/nvidia/cuquantum-appliance:24.03-cuda12.2.2-devel-ubuntu22.04-arm64

nvcr.io/nvidia/cuquantum-appliance:24.03-${march} 等同于
nvcr.io/nvidia/cuquantum-appliance:24.03-cuda12.2.2-devel-ubuntu22.04-${march}.
以下两个 docker pull 命令将下载相同的镜像。

docker nvcr.io/nvidia/cuquantum-appliance:24.03-${march}

docker pull nvcr.io/nvidia/cuquantum-appliance:24.03-cuda12.2.2-devel-ubuntu22.04-${march}

安全扫描通知¶

版本 `24.03` 安全扫描结果摘要¶

本节提供了潜在漏洞的摘要，这些漏洞根据 CVSS v3.1 标准评估为高严重性。要查看最新容器镜像的安全扫描结果，请参阅此页面顶部的安全扫描选项卡，或点击此链接。

CVE ID	分数	向量	状态	描述	参考文献
CVE-2023-36632	7.5	CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:N/I:N/A:H	有争议	调用 Python 对象时 `email.utils.parseaddr` 中出现 `RecursionError`	CVE

设备版本生命周期结束摘要¶

版本	状态	通知
24.03	受支持	N/A
23.10	受支持	在下一个版本中结束生命周期
23.06	生命周期结束	没有新功能或安全修复
23.03	生命周期结束	没有新功能或安全修复
22.*	生命周期结束	没有新功能或安全修复

注意：对于格式为 YY.* 的版本，该通知适用于所有同年份的版本。

文档¶

NVIDIA cuQuantum 设备文档托管在此处。
使用 qiskit 的指南可以在此处找到。
使用 cirq 的指南和教程可以在此处找到。
入门 qsimcirq 的指南可以在此处找到。

附加资源¶

NVIDIA cuQuantum SDK 主页
 NVIDIA cuQuantum Python 绑定和示例

有关拉取和运行容器的通用指南，请参阅拉取容器镜像和运行容器，在NGC 容器用户指南中。

许可协议¶

镜像受 NVIDIA 最终用户许可协议管辖。通过下载 NVIDIA cuQuantum 设备，您接受本许可证的条款和条件。 cuQuantum 设备最终用户许可协议可以在此处查看。由于镜像包含在开源许可证下许可的组件，因此这些组件的源代码可以在此处找到

引用 cuQuantum¶

H. Bayraktar 等人，“cuQuantum SDK：用于加速量子科学的高性能库”，2023 年 IEEE 量子计算与工程国际会议 (QCE)，美国华盛顿州贝尔维尤，2023 年，第 1050-1061 页，doi：10.1109/QCE57702.2023.00119