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	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

---

インストール

手順

• ユーザーが C++ または nvq++ コンパイラーについて明示的に言及しない限り、Python でのインストールを標準とします。
• インストール後は、必ず検証手順を案内します（ベル状態の例を実行し、出力に { 00:~500 11:~500 } が表示されることを確認します）。
• ユーザーが macOS／Apple Silicon を使用している場合、利用可能な GPU がないと言及した場合、または CPU のみのシミュレーションを明示的に希望した場合を除き、GPU アクセラレーション対応ターゲット（nvidia）を標準とします。その場合は 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) は |0⟩ の N 量子ビットを割り当てます。
• cudaq.sample() — カーネルが量子ビットを測定し、ビット文字列のヒストグラム（SampleResult）を返します。
• cudaq.run() — カーネルが古典値を返します。shots_count 回実行し、返された値のリストを返します。
• cudaq.observe() — スピン演算子の期待値 ⟨H⟩ を計算します。
• cudaq.get_state() — 完全な状態ベクトルを返します（シミュレーターのみ）。

カーネルの制約

• カーネル内で有効なのは、制限された Python サブセットのみです。通常の Python ではなく、Quake MLIR にコンパイルされます。
• カーネル内では 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 を 1 つ割り当て、並列実行します	独立した回路を多数並列実行する場合（例：パラメーターのスイープ、VQE の勾配計算）
tensornet	テンソルネットワークシミュレーター	浅い回路またはエンタングルメントが少ない回路で、量子ビット数が状態ベクトルで実行可能な範囲を超える場合
qpp-cpu	CPU 専用のフォールバック（OpenMP）	GPU を利用できない場合、macOS の場合、テスト用の小規模な回路の場合

---

QPU

ユーザーがこのセクションを呼び出したときは、すべてのプロバイダーを一度に表示しないでください。 代わりに、次の2段階のやり取りに従ってください。

ステップ 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() を使用します。
• プロバイダーの認証情報は安全に取り扱います。ソースコードやノートブックにハードコードするのではなく、シェルセッションの環境変数としてエクスポートするか、バージョン管理にコミットしないローカルプロファイルに保存します。トークンを共有ファイル、ログ、コミットに貼り付けないでください。また、利用できる場合はシークレットマネージャーを優先します。

---

アプリケーション

CUDA-Q には、すぐに実行できるアプリケーションノートブックが用意されています。

カテゴリー	例
最適化	QAOA、ADAPT-QAOA、MaxCut
化学	VQE、UCCSD、ADAPT-VQE
誤り訂正	表面符号、QEC メモリ
アルゴリズム	Grover、Shor、QFT、Deutsch-Jozsa、HHL
ML	量子ニューラルネットワーク、カーネル法
シミュレーション	ハミルトニアン・ダイナミクス、トロッター発展
金融	ポートフォリオ最適化、モンテカルロ

---

並列化

CUDA-Q は、異なる2種類のマルチ GPU 並列化戦略をサポートしています。何をスケールさせたいかに応じて選択してください。

目的	戦略	ターゲットオプション
1つの回路が単一 GPU に収まらない	GPU メモリをプールする	nvidia --target-option mgpu
多数の独立した回路を同時に実行する	回路を並列実行する	nvidia --target-option mqpu
大規模なハミルトニアン期待値	項を複数の GPU に分散する	mqpu + execution=cudaq.parallel.thread

mqpu による回路のバッチ処理（sample_async / observe_async）

mqpu オプションは、各 GPU に1つの仮想 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]

ハミルトニアンのバッチ処理

大規模なハミルトニアンを持つ単一カーネルの場合は、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 の手順を使い、その後ベル状態の例で検証します。
• /cudaq-guide test-program — ベル状態のカーネルを作成して実行し、 出力におおよそ { 00:~500 11:~500 } と表示されることを確認します。
• /cudaq-guide gpu-sim — シミュレーションバックエンドを推奨します（たとえば、 単一 GPU には nvidia、1 つの GPU のメモリを超える回路には nvidia --target-option mgpu）。
• /cudaq-guide qpu — 2 段階の QPU 対話（テクノロジー、次に プロバイダー）を開始し、該当するハードウェアのドキュメントを読みます。
• /cudaq-guide parallelize — mgpu（大規模な 1 つの 回路にメモリをプール）と mqpu（複数の回路を並列実行）のどちらかを選びます。

---

制限事項

• GPU シミュレーションには Linux（x86_64 または ARM64）が必要です。macOS は CPU のみです
• マルチ GPU の mgpu ターゲットには MPI が必要です
• カーネルコードでは制限された Python サブセットを使用する必要があります。カーネル内では NumPy／SciPy は使用できません
• QPU へのアクセスには、プロバイダー固有の認証情報とアカウントが必要です

トラブルシューティング

• pip install cudaq 後のインポートエラー：Python 3.10 以降と 対応 OS（Linux または macOS）を使用していることを確認してください
• GPU が検出されない：CUDA Toolkit がインストールされていること、 nvidia-smi に GPU が表示されることを確認してください。代わりに qpp-cpu を使用します
• カーネルのコンパイルエラー：@cudaq.kernel 内でサポート対象の Python 構文のみを 使用していることを確認してください
• QPU の送信に失敗する：プロバイダーのドキュメントに従って、認証情報が環境 変数として設定されていることを確認してください