/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

| Section | Doc file | | --- | --- | | Install | `docs/sphinx/using/install/install.rst`, `docs/sphinx/using/quick_start.rst` | | Test Program | `docs/sphinx/using/basics/kernel_intro.rst`, `docs/sphinx/using/basics/build_kernel.rst` | | GPU Simulation | `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` | | Applications | `docs/sphinx/using/applications.rst` | | Parallelize | `docs/sphinx/using/examples/multi_gpu_workflows.rst` |

Routing by Argument

| Argument | Action | |---|---| | `install` | Walk through installation (see Install section) | | `test-program` | Build and run a Bell state kernel to verify CUDA-Q is working properly | | `gpu-sim` | Explain GPU-accelerated simulation targets (see GPU Simulation section) | | `qpu` | Explain how to run on real QPU hardware (see QPU section) | | `applications` | Showcase what can be built with CUDA-Q (see Applications section) | | `parallelize` | Show 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

| Target | Description | Use when | |---|---|---| | `nvidia` (default) | Single-GPU