CUDA-Q Guide
Purpose
Guide users through CUDA-Q installation, basic kernels, GPU simulation targets,
QPU access, built-in applications, multi-GPU execution, and Python
@cudaq.kernel authoring. For Qiskit-to-CUDA-Q ports, route to the
cudaq-importing skill instead.
Prerequisites
- Python 3.10+ for Python CUDA-Q workflows.
- CUDA Toolkit and an NVIDIA GPU for GPU-accelerated targets on Linux.
- CPU-only simulation is available through
qpp-cpu; macOS is CPU-only.
- C++ workflows require Linux or WSL and C++20.
- QPU workflows require provider-specific credentials and accounts.
Instructions
- Invoke with
/cudaq-guide [argument].
- If no argument is given, display the onboarding menu and ask which topic the
user wants.
- Use the routing table below to choose the relevant reference file.
- Read local CUDA-Q documentation files when the answer depends on a specific
CUDA-Q version or backend behavior.
- Do not answer Qiskit porting questions from this skill; use
cudaq-importing.
Routing by Argument
| Argument |
Action |
Reference |
install |
Walk through Python or C++ installation and validation. |
references/onboarding.md |
test-program |
Build and run a Bell-state kernel. |
references/onboarding.md |
gpu-sim |
Select GPU, multi-GPU, tensor-network, or CPU targets. |
references/onboarding.md |
qpu |
Guide provider selection and credential-safe QPU setup. |
references/onboarding.md |
applications |
Summarize CUDA-Q application areas and notebooks. |
references/onboarding.md |
parallelize |
Choose mgpu, mqpu, async dispatch, or distributed observe. |
references/onboarding.md |
author |
Author CUDA-Q Python kernels, select execution APIs, and debug compiler issues. |
references/authoring.md |
| (none) |
Print the menu below and ask which topic to explore. |
This file |
Menu
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/latest/
Choose a topic:
/cudaq-guide install Install CUDA-Q
/cudaq-guide test-program Write and run a Bell-state 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 across GPUs or QPUs
/cudaq-guide author Author @cudaq.kernel Python code
Reference Files
- references/onboarding.md: installation, test
program, GPU targets, QPU providers, application areas, parallelization
modes, examples, and platform troubleshooting.
- references/authoring.md: execution APIs,
kernel-language constraints, silent-failure pitfalls, recurring coding
patterns, resource metrics, debugging, and validation.
Limitations
- Guidance targets CUDA-Q Python/C++ workflows, with authoring details focused
on decorator-mode Python APIs used in CUDA-Q 0.14 and 0.15.
- GPU and multi-GPU support depends on local CUDA-Q, CUDA Toolkit, driver, MPI,
and hardware availability.
- QPU access and target options are provider-specific and may change; verify
against local docs before giving operational steps.
Troubleshooting
- Import error after
pip install cudaq: check Python 3.10+ and supported
OS.
- No GPU detected: verify CUDA Toolkit and
nvidia-smi; fall back to
qpp-cpu.
- Kernel compile error: read references/authoring.md
and check the restricted kernel-language subset.
- Version-specific behavior differs: compare
cudaq.__version__ with the
latest documentation, then review relevant documentation or source changes
when debugging an installed version that is not the latest release.
- QPU submission fails: verify provider credentials are set as environment
variables or through a secrets manager, never hardcoded.
- Documentation lookup fails: retry transient MCP or repository lookup once,
then fall back to local docs or official CUDA-Q documentation.
1---2name: cudaq-guide-23title: "CUDA-Q Guide"4description: "Use for CUDA-Q setup, simulation targets, QPU access, and @cudaq.kernel authoring guidance."5version: "1.1.2"6author: "CUDA-Q Team <cuda-quantum@nvidia.com>"7tags: [cuda-quantum, quantum-computing, onboarding, getting-started, authoring, kernels, nvidia]8tools: [Read, Glob, Grep]9license: "Apache-2.0"10compatibility: "Python 3.10+, C++ 20"11metadata:12 source: https://skillmd.com/skills/nvidia/cudaq-guide-213 author: "CUDA-Q Team <cuda-quantum@nvidia.com>"14 tags:15 - cuda-quantum16 - quantum-computing17 - onboarding18 - getting-started19 - nvidia20 languages:21 - python22 - c++23 domain: "quantum"24---2526# CUDA-Q Guide2728## Purpose2930Guide users through CUDA-Q installation, basic kernels, GPU simulation targets,31QPU access, built-in applications, multi-GPU execution, and Python32`@cudaq.kernel` authoring. For Qiskit-to-CUDA-Q ports, route to the33`cudaq-importing` skill instead.3435## Prerequisites3637- Python 3.10+ for Python CUDA-Q workflows.38- CUDA Toolkit and an NVIDIA GPU for GPU-accelerated targets on Linux.39- CPU-only simulation is available through `qpp-cpu`; macOS is CPU-only.40- C++ workflows require Linux or WSL and C++20.41- QPU workflows require provider-specific credentials and accounts.4243## Instructions4445- Invoke with `/cudaq-guide [argument]`.46- If no argument is given, display the onboarding menu and ask which topic the47 user wants.48- Use the routing table below to choose the relevant reference file.49- Read local CUDA-Q documentation files when the answer depends on a specific50 CUDA-Q version or backend behavior.51- Do not answer Qiskit porting questions from this skill; use52 `cudaq-importing`.5354## Routing by Argument5556| Argument | Action | Reference |57|---|---|---|58| `install` | Walk through Python or C++ installation and validation. | [references/onboarding.md](references/onboarding.md) |59| `test-program` | Build and run a Bell-state kernel. | [references/onboarding.md](references/onboarding.md) |60| `gpu-sim` | Select GPU, multi-GPU, tensor-network, or CPU targets. | [references/onboarding.md](references/onboarding.md) |61| `qpu` | Guide provider selection and credential-safe QPU setup. | [references/onboarding.md](references/onboarding.md) |62| `applications` | Summarize CUDA-Q application areas and notebooks. | [references/onboarding.md](references/onboarding.md) |63| `parallelize` | Choose `mgpu`, `mqpu`, async dispatch, or distributed observe. | [references/onboarding.md](references/onboarding.md) |64| `author` | Author CUDA-Q Python kernels, select execution APIs, and debug compiler issues. | [references/authoring.md](references/authoring.md) |65| _(none)_ | Print the menu below and ask which topic to explore. | This file |6667## Menu6869```text70CUDA-Q Getting Started7172CUDA-Q is NVIDIA's unified quantum-classical programming model for CPUs, GPUs, and QPUs.73Supports Python and C++. Docs: https://nvidia.github.io/cuda-quantum/latest/7475Choose a topic:76 /cudaq-guide install Install CUDA-Q77 /cudaq-guide test-program Write and run a Bell-state kernel78 /cudaq-guide gpu-sim Accelerate simulation on NVIDIA GPUs79 /cudaq-guide qpu Connect to real QPU hardware80 /cudaq-guide applications Explore what you can build81 /cudaq-guide parallelize Run across GPUs or QPUs82 /cudaq-guide author Author @cudaq.kernel Python code83```8485## Reference Files8687- [references/onboarding.md](references/onboarding.md): installation, test88 program, GPU targets, QPU providers, application areas, parallelization89 modes, examples, and platform troubleshooting.90- [references/authoring.md](references/authoring.md): execution APIs,91 kernel-language constraints, silent-failure pitfalls, recurring coding92 patterns, resource metrics, debugging, and validation.9394## Limitations9596- Guidance targets CUDA-Q Python/C++ workflows, with authoring details focused97 on decorator-mode Python APIs used in CUDA-Q 0.14 and 0.15.98- GPU and multi-GPU support depends on local CUDA-Q, CUDA Toolkit, driver, MPI,99 and hardware availability.100- QPU access and target options are provider-specific and may change; verify101 against local docs before giving operational steps.102103## Troubleshooting104105- **Import error after `pip install cudaq`:** check Python 3.10+ and supported106 OS.107- **No GPU detected:** verify CUDA Toolkit and `nvidia-smi`; fall back to108 `qpp-cpu`.109- **Kernel compile error:** read [references/authoring.md](references/authoring.md)110 and check the restricted kernel-language subset.111- **Version-specific behavior differs:** compare `cudaq.__version__` with the112 latest documentation, then review relevant documentation or source changes113 when debugging an installed version that is not the latest release.114- **QPU submission fails:** verify provider credentials are set as environment115 variables or through a secrets manager, never hardcoded.116- **Documentation lookup fails:** retry transient MCP or repository lookup once,117 then fall back to local docs or official CUDA-Q documentation.