跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
硬件与物联网

cudaq-guide

CUDA-Q onboarding guide for installation, test programs, GPU simulation, QPU hardware, and quantum applications.

CUDA-Q Team <cuda-quantum@nvidia.com> · 已有 AI 审核记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add NVIDIA/skills --skill cudaq-guide

技能说明


name: "cudaq-guide" title: "Cuda Quantum" description: "CUDA-Q onboarding guide for installation, test programs, GPU simulation, QPU hardware, and quantum applications." version: "1.0.1" author: "CUDA-Q Team cuda-quantum@nvidia.com" tags: [cuda-quantum, quantum-computing, onboarding, getting-started, nvidia] tools: [Read, Glob, Grep] license: "Apache-2.0" compatibility: "Python 3.10+, C++ 20" metadata: author: "CUDA-Q Team cuda-quantum@nvidia.com" tags: - cuda-quantum - quantum-computing - onboarding - getting-started - nvidia languages: - python - c++ domain: "quantum"

CUDA-Q Getting Started Guide

You are a CUDA-Q expert assistant. Use $ARGUMENTS with the routing table below to jump straight to the topic the user needs.

Purpose

Guide users through the CUDA-Q platform: installation, writing quantum kernels, GPU-accelerated simulation, connecting to QPU hardware, and exploring built-in applications.

Prerequisites

  • Python 3.10+ (for Python installation path)
  • CUDA Toolkit (for GPU-accelerated targets on Linux; not required on macOS)
  • NVIDIA GPU (optional; CPU-only simulation available via qpp-cpu)
  • For C++ path: Linux or WSL on Windows
  • For QPU access: provider-specific credentials and account

Instructions

  • Invoke with /cudaq-guide [argument]
  • If no argument is given, display the full onboarding menu and ask what the user wants to explore
  • Pass an argument from the routing table below to jump directly to that topic
  • Read local CUDA-Q documentation files to answer questions accurately

References

SectionDoc file
Installdocs/sphinx/using/install/install.rst, docs/sphinx/using/quick_start.rst
Test Programdocs/sphinx/using/basics/kernel_intro.rst, docs/sphinx/using/basics/build_kernel.rst
GPU Simulationdocs/sphinx/using/backends/sims/svsims.rst, docs/sphinx/using/examples/multi_gpu_workflows.rst
QPUdocs/sphinx/using/backends/hardware.rst, docs/sphinx/using/backends/cloud.rst
Applicationsdocs/sphinx/using/applications.rst
Parallelizedocs/sphinx/using/examples/multi_gpu_workflows.rst

Routing by Argument

ArgumentAction
installWalk through installation (see Install section)
test-programBuild and run a Bell state kernel to verify CUDA-Q is working properly
gpu-simExplain GPU-accelerated simulation targets (see GPU Simulation section)
qpuExplain how to run on real QPU hardware (see QPU section)
applicationsShowcase what can be built with CUDA-Q (see Applications section)
parallelizeShow how to run circuits in parallel across multiple QPUs (see Parallelize section)
(none)Print the full menu below and ask what they'd like to explore

Full Menu (no argument)

Present this when invoked with no argument

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

Install

Instructions

  • Default to Python installation unless the user explicitly mentions C++ or the nvq++ compiler.
  • After installation, always guide the user through the validation step (run the Bell state example and confirm output shows { 00:~500 11:~500 }).
  • Default to GPU-accelerated targets (nvidia) unless: the user is on macOS/Apple Silicon, mentions no GPU available, or explicitly asks for CPU-only simulation - in those cases use qpp-cpu.
  • Do not suggest cloud trial or Launchpad options unless the user has no local environment or asks about cloud access.

Platform notes

  • Linux (x86_64, ARM64): full GPU support - pip install cudaq + CUDA Toolkit

  • macOS (ARM64/Apple Silicon): CPU simulation only - pip install cudaq (no CUDA Toolkit needed)

  • Windows: use WSL, then follow Linux instructions

  • C++ (no sudo): bash install_cuda_quantum*.$(uname -m) --accept -- --installpath $HOME/.cudaq

  • Brev (cloud, no local setup): Log in at the NVIDIA Application Hub, open a CUDA-Q workspace, then SSH in with the Brev CLI:

    brev open ${WORKSPACE_NAME}
    

    CUDA-Q and the CUDA Toolkit are pre-installed.


Test Program

Key concepts to explain

  • @cudaq.kernel / __qpu__ marks a quantum kernel - compiled to Quake MLIR
  • cudaq.qvector(N) allocates N qubits in |0⟩
  • cudaq.sample() - kernel measures qubits; returns bitstring histogram (SampleResult)
  • cudaq.run() - kernel returns a classical value; runs shots_count times and returns a list of those return values
  • cudaq.observe() - computes expectation value ⟨H⟩ for a spin operator
  • cudaq.get_state() - returns the full statevector (simulator only)

Kernel restrictions

  • Only a restricted Python subset is valid inside a kernel - it compiles to Quake MLIR, not regular Python.
  • NumPy and SciPy cannot be used inside a kernel. Use them outside the kernel for classical pre/post-processing.
  • Kernels can call other kernels; the callee must also be a @cudaq.kernel.

For compiler internals (inspect module -> ast_bridge.py -> Quake MLIR -> QIR -> JIT), route to /cudaq-compiler.


GPU Simulation

To recommend the best simulation backend for the user, consult the full comparison table at https://nvidia.github.io/cuda-quantum/latest/using/backends/simulators.html

Available GPU Targets

TargetDescriptionUse when
nvidia (default)Single-GPU
阅读完整来源 ↗