Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Um comando direto ignora o prompt de revisão. Verifique a origem antes de executá-lo.
{"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
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
After walking through the provider steps, always close with
Test locally first with emulate=True before submitting to real hardware.
Use cudaq.sample_async() / cudaq.observe_async() for non-blocking submission.
Handle provider credentials securely: export them as environment variables
in your shell session (or a local profile that is not committed to version
control) rather than hardcoding them in source or notebooks. Never paste
tokens into shared files, logs, or commits, and prefer a secrets manager
where one is available.
Applications
CUDA-Q ships with ready-to-run application notebooks
Category
Examples
Optimization
QAOA, ADAPT-QAOA, MaxCut
Chemistry
VQE, UCCSD, ADAPT-VQE
Error Correction
Surface codes, QEC memory
Algorithms
Grover's, Shor's, QFT, Deutsch-Jozsa, HHL
ML
Quantum neural networks, kernel methods
Simulation
Hamiltonian dynamics, Trotter evolution
Finance
Portfolio optimization, Monte Carlo
Parallelize
CUDA-Q supports two distinct multi-GPU parallelization strategies - pick based
on what you are trying to scale.
Goal
Strategy
Target option
Single circuit too large for one GPU
Pool GPU memory
nvidia --target-option mgpu
Many independent circuits at once
Run circuits in parallel
nvidia --target-option mqpu
Large Hamiltonian expectation value
Distribute terms across GPUs
mqpu + execution=cudaq.parallel.thread
Circuit batching with mqpu (sample_async / observe_async)
The mqpu option maps one virtual QPU to each GPU. Dispatch circuits
asynchronously with qpu_id to all GPUs simultaneously.
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 inenumerate(param_sets)
]
results = [f.get().expectation() for f in futures]
Hamiltonian batching
For a single kernel with a large Hamiltonian, add execution= to
cudaq.observe — no other code change needed.
# 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)
See the docs above for complete working examples of both patterns.
Examples
/cudaq-guide — print the onboarding menu and ask the user which topic to
explore.
/cudaq-guide install — walk through installation, defaulting to the Python
pip install cudaq path, then validate with the Bell state example.
/cudaq-guide test-program — build and run a Bell state kernel and confirm
the output shows roughly { 00:~500 11:~500 }.
/cudaq-guide gpu-sim — recommend a simulation backend (for example
nvidia for a single GPU, or nvidia --target-option mgpu for circuits
larger than one GPU's memory).
/cudaq-guide qpu — start the two-step QPU dialogue (technology, then
provider) and read the matching hardware doc.
/cudaq-guide parallelize — choose between mgpu (pool memory for one large
circuit) and mqpu (run many circuits in parallel).
Limitations
GPU simulation requires Linux (x86_64 or ARM64); macOS is CPU-only
Multi-GPU mgpu target requires MPI
Kernel code must use a restricted Python subset; NumPy/SciPy are not
allowed inside kernels
QPU access requires provider-specific credentials and accounts
Troubleshooting
Import error after pip install cudaq: Ensure Python 3.10+ and a
supported OS (Linux or macOS)
No GPU detected: Verify CUDA Toolkit is installed and nvidia-smi
shows your GPU; fall back to qpp-cpu
Kernel compile error: Check that only supported Python constructs are
used inside @cudaq.kernel
QPU submission fails: Confirm credentials are set as environment
variables per the provider docs
