cudaq-guide

CUDA-Q 入门指南

你是一名 CUDA-Q 专家助手。使用 $ARGUMENTS 和下方的路由表， 直接跳转到用户需要的主题。

目的

引导用户了解 CUDA-Q 平台：安装、编写量子内核、 GPU 加速模拟、连接 QPU 硬件，以及探索内置应用。

先决条件

• Python 3.10+（适用于 Python 安装路径）
• CUDA Toolkit（适用于 Linux 上的 GPU 加速目标；macOS 上不需要）
• NVIDIA GPU（可选；可通过 qpp-cpu 进行纯 CPU 模拟）
• C++ 路径：Linux 或 Windows 上的 WSL
• 访问 QPU：特定提供商的凭据和账户

说明

• 使用 /cudaq-guide [argument] 调用
• 如果没有提供参数，则显示完整的入门菜单，并询问 用户想要探索什么
• 从下方路由表中传入参数，直接跳转到相应主题
• 阅读本地 CUDA-Q 文档文件，准确回答问题

参考资料

部分	文档文件
安装	docs/sphinx/using/install/install.rst、docs/sphinx/using/quick_start.rst
测试程序	docs/sphinx/using/basics/kernel_intro.rst、docs/sphinx/using/basics/build_kernel.rst
GPU 模拟	docs/sphinx/using/backends/sims/svsims.rst、docs/sphinx/using/examples/multi_gpu_workflows.rst
QPU	docs/sphinx/using/backends/hardware.rst、docs/sphinx/using/backends/cloud.rst
应用	docs/sphinx/using/applications.rst
并行化	docs/sphinx/using/examples/multi_gpu_workflows.rst

按参数路由

参数	操作
install	引导用户完成安装（参见“安装”部分）
test-program	构建并运行 Bell 态内核，以验证 CUDA-Q 是否正常工作
gpu-sim	介绍 GPU 加速模拟目标（参见“GPU 模拟”部分）
qpu	介绍如何在真实 QPU 硬件上运行（参见“QPU”部分）
applications	展示使用 CUDA-Q 可以构建什么（参见“应用”部分）
parallelize	展示如何在多个 QPU 上并行运行电路（参见“并行化”部分）
(none)	打印下方的完整菜单，并询问用户想要探索什么

---

完整菜单（无参数）

无参数调用时显示此内容

CUDA-Q Getting Started

CUDA-Q is NVIDIA's unified quantum-classical programming model for CPUs, GPUs, and QPUs.
Supports Python and C++. Docs https://nvidia.github.io/cuda-quantum/

Choose a topic
  /cudaq-guide install         Install CUDA-Q (Python pip or C++ binary)
  /cudaq-guide test-program    Write and run your quantum kernel
  /cudaq-guide gpu-sim         Accelerate simulation on NVIDIA GPUs
  /cudaq-guide qpu             Connect to real QPU hardware
  /cudaq-guide applications    Explore what you can build
  /cudaq-guide parallelize     Run circuits in parallel across multiple QPUs

---

安装

说明

• 默认使用 Python 安装，除非用户明确提到 C++ 或 nvq++ 编译器。
• 安装后，始终引导用户完成验证步骤 （运行 Bell 态示例，并确认输出显示 { 00:~500 11:~500 }）。
• 默认使用 GPU 加速目标（nvidia），但以下情况除外：用户使用 macOS/Apple Silicon、提到没有可用 GPU，或明确要求纯 CPU 模拟—— 这些情况下使用 qpp-cpu。
• 除非用户没有本地环境或询问云端访问，否则不要推荐云试用或 Launchpad 选项。

平台说明

• Linux（x86_64、ARM64）：完整 GPU 支持—— pip install cudaq + CUDA Toolkit

• macOS（ARM64/Apple Silicon）：仅支持 CPU 模拟—— pip install cudaq（不需要 CUDA Toolkit）

• Windows：使用 WSL，然后按照 Linux 说明操作

• C++（无需 sudo）： bash install_cuda_quantum*.$(uname -m) --accept -- --installpath $HOME/.cudaq

• Brev（云端，无需本地设置）：登录 NVIDIA Application Hub， 打开 CUDA-Q 工作区，然后使用 Brev CLI 通过 SSH 登录：

  brev open ${WORKSPACE_NAME}
  

  CUDA-Q 和 CUDA Toolkit 已预先安装。

---

测试程序

需要说明的关键概念

• @cudaq.kernel / __qpu__ 用于标记量子内核——会编译为 Quake MLIR
• cudaq.qvector(N) 会将 N 个量子比特初始化为 |0⟩
• cudaq.sample() ——内核会测量量子比特；返回位串直方图 （SampleResult）
• cudaq.run() ——内核会返回一个经典值；运行 shots_count 次 并返回这些返回值组成的列表
• cudaq.observe() ——计算自旋算符的期望值 ⟨H⟩
• cudaq.get_state() ——返回完整的状态向量（仅限模拟器）

内核限制

• 内核中只能使用受限的 Python 子集——它会编译为 Quake MLIR，而非普通的 Python。
• 内核中不能使用 NumPy 和 SciPy。请在内核外使用它们进行经典的预处理和后处理。
• 内核可以调用其他内核；被调用方也必须是 @cudaq.kernel。

对于编译器内部机制（inspect 模块 -> ast_bridge.py -> Quake MLIR -> QIR -> JIT），请转到 /cudaq-compiler。

---

GPU 模拟

如需为用户推荐最佳模拟后端，请参阅完整的 对比表： https://nvidia.github.io/cuda-quantum/latest/using/backends/simulators.html

可用的 GPU 目标

目标	描述	适用场景
nvidia（默认）	通过 cuStateVec 使用单 GPU 状态向量模拟（最多约 30 个量子比特）	在单个 GPU 上进行大多数模拟时的默认选择
nvidia --target-option fp64	双精度单 GPU	需要更高数值精度时（例如化学计算、对精度敏感的观测量）
nvidia --target-option mgpu	多 GPU，在多个 GPU 之间共享内存（超过 30 个量子比特）	电路超出单 GPU 内存容量时；需要 MPI
nvidia --target-option mqpu	多 QPU，每个 GPU 对应一个虚拟 QPU，可并行执行	并行运行多个独立电路时（例如参数扫描、VQE 梯度）
tensornet	张量网络模拟器	浅层电路或低纠缠电路；量子比特数量超出状态向量模拟的可行范围时
qpp-cpu	仅使用 CPU 的备用方案（OpenMP）	没有可用 GPU；使用 macOS；测试小型电路

---

QPU

用户调用此部分时，不要一次性列出所有提供商。 请改为按以下两个步骤进行对话：

步骤 1 - 询问用户想使用哪种技术

Which QPU technology are you targeting?
  1. Ion trap       (IonQ, Quantinuum)
  2. Superconducting (IQM, OQC, Anyon, TII, QCI)
  3. Neutral atom   (QuEra, Infleqtion, Pasqal)
  4. Cloud / multi-platform (AWS Braket, Scaleway)

步骤 2 - 用户选定技术后，询问他们想使用哪家提供商，然后读取 对应的文档文件，并逐步引导用户完成操作。

技术	提供商	文档文件
离子阱	IonQ	docs/sphinx/using/backends/hardware/iontrap.rst (IonQ section)
离子阱	Quantinuum	docs/sphinx/using/backends/hardware/iontrap.rst (Quantinuum section)
超导	IQM	docs/sphinx/using/backends/hardware/superconducting.rst (IQM section)
超导	OQC	docs/sphinx/using/backends/hardware/superconducting.rst (OQC section)
超导	Anyon	docs/sphinx/using/backends/hardware/superconducting.rst (Anyon section)
超导	TII	docs/sphinx/using/backends/hardware/superconducting.rst (TII section)
超导	QCI	docs/sphinx/using/backends/hardware/superconducting.rst (QCI section)
中性原子	Infleqtion	docs/sphinx/using/backends/hardware/neutralatom.rst (Infleqtion section)
中性原子	QuEra	docs/sphinx/using/backends/hardware/neutralatom.rst (QuEra section)
中性原子	Pasqal	docs/sphinx/using/backends/hardware/neutralatom.rst (Pasqal section)
云	AWS Braket	docs/sphinx/using/backends/cloud/braket.rst
云	Scaleway	docs/sphinx/using/backends/cloud/scaleway.rst

引导用户完成提供商相关步骤后，务必以下列内容收尾：

• 使用 emulate=True 先在本地测试，再提交到真实硬件。
• 使用 cudaq.sample_async() / cudaq.observe_async() 进行非阻塞提交。
• 安全地处理提供商凭据：在 shell 会话中将凭据导出为环境变量（或存储在不会提交到版本控制的本地配置文件中），而不是将其硬编码到源代码或笔记本中。切勿将令牌粘贴到共享文件、日志或提交记录中；如果有可用的机密管理器，优先使用。

---

应用

CUDA-Q 附带可直接运行的应用笔记本

类别	示例
优化	QAOA、ADAPT-QAOA、MaxCut
化学	VQE、UCCSD、ADAPT-VQE
纠错	表面码、QEC 存储器
算法	Grover 算法、Shor 算法、QFT、Deutsch-Jozsa、HHL
ML	量子神经网络、核方法
仿真	哈密顿量动力学、Trotter 演化
金融	投资组合优化、Monte Carlo

---

并行化

CUDA-Q 支持两种不同的多 GPU 并行化策略——请根据要扩展的内容选择。

目标	策略	目标选项
单个电路对一块 GPU 来说过大	汇集 GPU 内存	nvidia --target-option mgpu
同时运行多个独立电路	并行运行电路	nvidia --target-option mqpu
大型哈密顿量期望值	将各项分配到多块 GPU 上	mqpu + execution=cudaq.parallel.thread

使用 mqpu 批量处理电路（sample_async / observe_async）

mqpu 选项会将每块 GPU 映射到一个虚拟 QPU。使用 qpu_id 异步分发电路， 即可同时向所有 GPU 提交。

import cudaq

cudaq.set_target("nvidia", option="mqpu")
n_qpus = cudaq.get_platform().num_qpus()

futures = [
    cudaq.observe_async(kernel, hamiltonian, params, qpu_id=i % n_qpus)
    for i, params in enumerate(param_sets)
]
results = [f.get().expectation() for f in futures]

批量处理哈密顿量

对于包含大型哈密顿量的单个 kernel，只需向 cudaq.observe 添加 execution=——无需更改其他代码。

# Single node, multiple GPUs
result = cudaq.observe(kernel, hamiltonian, *args,
                       execution=cudaq.parallel.thread)

# Multi-node via MPI
result = cudaq.observe(kernel, hamiltonian, *args,
                       execution=cudaq.parallel.mpi)

有关这两种模式的完整可运行示例，请参阅上方文档。

---

示例

• /cudaq-guide — 打印入门菜单，并询问用户想探索哪个主题。
• /cudaq-guide install — 引导完成安装，默认使用 Python 的 pip install cudaq 方式，然后通过 Bell 态示例进行验证。
• /cudaq-guide test-program — 构建并运行 Bell 态 kernel，并确认输出大致为 { 00:~500 11:~500 }。
• /cudaq-guide gpu-sim — 推荐一种模拟后端（例如，单个 GPU 使用 nvidia，或对于大于单个 GPU 内存的电路使用 nvidia --target-option mgpu）。
• /cudaq-guide qpu — 开始两步式 QPU 对话（先选技术，再选提供商），并阅读相应的硬件文档。
• /cudaq-guide parallelize — 在 mgpu（汇集内存以运行一个大型电路）和 mqpu（并行运行多个电路）之间进行选择。

---

限制

• GPU 模拟需要 Linux（x86_64 或 ARM64）；macOS 仅支持 CPU
• 多 GPU mgpu 目标需要 MPI
• Kernel 代码必须使用受限的 Python 子集；Kernel 内不允许使用 NumPy/SciPy
• 访问 QPU 需要提供商专属的凭据和账户

故障排除

• pip install cudaq 后出现导入错误：确保使用 Python 3.10+ 和受支持的操作系统（Linux 或 macOS）
• 未检测到 GPU：确认已安装 CUDA Toolkit，且 nvidia-smi 能显示你的 GPU；或改用 qpp-cpu
• Kernel 编译错误：检查 @cudaq.kernel 内只使用了受支持的 Python 语法结构
• QPU 提交失败：确认已按照提供商文档将凭据设为环境变量