cudaq-guide

CUDA-Q 新手入門指南

您是一位 CUDA-Q 專家助手。請根據下方路由表搭配 $ARGUMENTS，直接跳轉至使用者需要的相應主題。

目的

引導使用者熟悉 CUDA-Q 平台：包含安裝步驟、撰寫量子 Kernel、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 態 Kernel，以驗證 CUDA-Q 是否正常運作
gpu-sim	解說 GPU 加速模擬目標（參見「GPU 模擬」章節）
qpu	說明如何在真實 QPU 硬體上執行（參見「QPU」章節）
applications	展示可用 CUDA-Q 建置的項目（參見「應用範例」章節）
parallelize	示範如何在多個 QPU 之間平行執行線路（參見「平行化」章節）
(none)	列印下方完整選單，並詢問使用者想探索什麼

---

完整選單（無引數）

當未傳入任何引數呼叫時，顯示此內容：

CUDA-Q 入門指南

CUDA-Q 是 NVIDIA 專為 CPU、GPU 與 QPU 打造的統一量子-古典程式設計模型。
支援 Python 與 C++。官方文件：https://nvidia.github.io/cuda-quantum/

請選擇主題：
  /cudaq-guide install         安裝 CUDA-Q（Python pip 或 C++ 二進位檔）
  /cudaq-guide test-program    撰寫並執行您的量子 Kernel
  /cudaq-guide gpu-sim         在 NVIDIA GPU 上加速模擬
  /cudaq-guide qpu             連線至真實 QPU 硬體
  /cudaq-guide applications    探索您可以開發的應用
  /cudaq-guide parallelize     跨多個 QPU 平行執行量子線路

---

安裝

說明

• 預設使用 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__ 用於標記量子 Kernel — 會被編譯為 Quake MLIR
• cudaq.qvector(N) 配置 N 個處於 |0⟩ 態的量子位元 (qubits)
• cudaq.sample() — Kernel 量測量子位元；回傳位元串直方圖 (SampleResult)
• cudaq.run() — Kernel 回傳古典數值；執行 shots_count 次並回傳包含這些回傳值的串列
• cudaq.observe() — 計算自旋算符的期望值 ⟨H⟩
• cudaq.get_state() — 回傳完整的狀態向量 statevector（僅限模擬器）

Kernel 限制

• Kernel 內部僅能使用受限的 Python 子集 — 因為它會編譯為 Quake MLIR，而非一般的 Python。
• 無法在 Kernel 內部使用 NumPy 和 SciPy。請在 Kernel 外部使用它們來進行古典的前處理/後處理。
• Kernel 可以呼叫其他 Kernel；被呼叫者也必須加上 @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 — 詢問使用者想使用哪種技術

您打算使用哪種 QPU 技術？
  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 章節)
離子阱	Quantinuum	docs/sphinx/using/backends/hardware/iontrap.rst (Quantinuum 章節)
超導	IQM	docs/sphinx/using/backends/hardware/superconducting.rst (IQM 章節)
超導	OQC	docs/sphinx/using/backends/hardware/superconducting.rst (OQC 章節)
超導	Anyon	docs/sphinx/using/backends/hardware/superconducting.rst (Anyon 章節)
超導	TII	docs/sphinx/using/backends/hardware/superconducting.rst (TII 章節)
超導	QCI	docs/sphinx/using/backends/hardware/superconducting.rst (QCI 章節)
中性原子	Infleqtion	docs/sphinx/using/backends/hardware/neutralatom.rst (Infleqtion 章節)
中性原子	QuEra	docs/sphinx/using/backends/hardware/neutralatom.rst (QuEra 章節)
中性原子	Pasqal	docs/sphinx/using/backends/hardware/neutralatom.rst (Pasqal 章節)
雲端	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 工作階段中將其匯出為環境變數（或未提交至版本控制的本機設定檔），而非直接硬編碼在原始碼或 Jupyter Notebook 中。切勿將 Token 貼到共享檔案、日誌或 Commit 中；若環境有金鑰管理工具 (Secrets Manager)，請優先使用。

---

應用範例

CUDA-Q 隨附可直接執行的應用範例 Notebook

類別	範例
最佳化	QAOA, ADAPT-QAOA, MaxCut
化學	VQE, UCCSD, ADAPT-VQE
糾錯 (Error Correction)	表面碼 (Surface codes), QEC 記憶體
演算法	Grover's, Shor's, QFT, Deutsch-Jozsa, HHL
機器學習	量子神經網路、核方法 (Kernel methods)
模擬	漢米爾頓動態 (Hamiltonian dynamics)、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 選項會將一個虛擬 QPU 映射至每個 GPU。可透過 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 子集；NumPy/SciPy 無法在 Kernel 內部使用