agentleFS
dtunaidtunai/agent-skills-for-compute/skills/cuda-quantum/SKILL.md

cuda-quantum

Skill8 starsChanged 8 months agoMITView on GitHub

Provides CUDA-Q hybrid quantum-classical programming patterns for GPU-accelerated quantum simulation, circuit construction, variational algorithms, hardware backend configuration, dynamics simulation, and CUDA-QX extension libraries (solvers for molecular chemistry, QEC for error correction). Applies to tasks involving quantum kernels, qubit operations, cuQuantum simulation, VQE/QAOA optimization, multi-GPU quantum workflows, noise modeling, dynamics/time-evolution, molecular Hamiltonians, or quantum error correction.

  • Installs packages

The file

Files
SKILL.md

CUDA-Q (CUDA Quantum)

Overview

Programming model and toolchain for hybrid quantum-classical computing on NVIDIA GPUs. CUDA-Q provides Python and C++ APIs for building quantum circuits, running GPU-accelerated simulations, executing variational algorithms, and targeting real quantum hardware — all through a unified kernel-based programming model.

Quick Pattern

Incorrect — raw gate operations without kernel:

# No kernel decorator, no GPU acceleration
from qiskit import QuantumCircuit
qc = QuantumCircuit(2)
qc.h(0)
qc.cx(0, 1)

Correct — CUDA-Q kernel with GPU simulation:

import cudaq

@cudaq.kernel
def bell_pair():
    qubits = cudaq.qvector(2)
    h(qubits[0])
    x.ctrl(qubits[0], qubits[1])
    mz(qubits)

result = cudaq.sample(bell_pair, shots_count=1000)
print(result)

Quick Command

# Install CUDA-Q
pip install cuda-quantum

# Install CUDA-QX extensions
pip install cudaq-solvers cudaq-qec

# Run with GPU backend
python my_circuit.py --target nvidia

# Run with multi-GPU
mpiexec -np 4 python my_circuit.py --target nvidia --target-option mgpu

# Draw circuit
python -c "import cudaq; print(cudaq.draw(my_kernel, *args))"

Quick Reference

Core API

FunctionPurpose
@cudaq.kernelDecorate function as quantum kernel (JIT compiled)
cudaq.qvector(N)Allocate N qubits
cudaq.qubit()Allocate single qubit
cudaq.sample(kernel, *args)Sample measurement outcomes
cudaq.run(kernel, *args)Execute kernel with return values
cudaq.observe(kernel, hamiltonian, *args)Compute expectation value
cudaq.evolve(hamiltonian, dims, schedule, state)Dynamics time evolution
cudaq.vqe(kernel, hamiltonian, optimizer)Run VQE optimization
cudaq.get_state(kernel, *args)Get full statevector
cudaq.draw(kernel, *args)ASCII circuit visualization
cudaq.translate(kernel, format)Translate to OpenQASM
cudaq.set_target(name)Select simulation/hardware backend

Quantum Gates

GateSyntaxDescription
Hadamardh(qubit)Superposition
Pauli-Xx(qubit)Bit flip
Pauli-Yy(qubit)Y rotation
Pauli-Zz(qubit)Phase flip
CNOTx.ctrl(control, target)Controlled-NOT
RXrx(angle, qubit)X-axis rotation
RYry(angle, qubit)Y-axis rotation
RZrz(angle, qubit)Z-axis rotation
Tt(qubit)T gate
Ss(qubit)S gate
SWAPswap(q0, q1)Swap qubits
Measuremz(qubit)Z-basis measurement
Adjointt.adj(qubit)Inverse gate

Simulation Backends

TargetTypeGPUDescription
qpp-cpuState vectorNoCPU-only Q++ simulator
nvidiaState vectorYescuStateVec GPU-accelerated
nvidia-fp64State vectorYesDouble precision GPU
nvidia-mgpuState vectorMultiDistributed across GPUs via MPI
nvidia-mqpuMulti-QPUMultiParallel QPU simulation
tensornetTensor networkYesExact tensor contraction
tensornet-mpsMPSYesMatrix product state approximation
density-matrix-cpuDensity matrixNoNoisy simulation support
dynamicsTime evolutionYesHamiltonian dynamics (Schrödinger/Lindblad)
stimStabilizerNoFast Clifford circuits, QEC, Pauli noise
fermioniqTensor networkCloudThird-party GPU tensor network emulator
orca-photonicsPhotonicNoBosonic/photonic qudit simulation

Hardware Backends

ProviderTargetType
IonQionqTrapped ion
QuantinuumquantinuumTrapped ion
IQMiqmSuperconducting
OQCoqcSuperconducting
ORCAorcaPhotonic
InfleqtioninfleqtionNeutral atom
PasqalpasqalNeutral atom
QuEraqueraNeutral atom
AnyonanyonSuperconducting
QCIqciCloud
Amazon BraketbraketCloud multi-vendor

When to Apply

Reference these guidelines when:

  • Building quantum circuits for simulation or hardware execution
  • Implementing variational algorithms (VQE, QAOA, quantum ML)
  • Scaling quantum simulations to multi-GPU or multi-node
  • Modeling quantum noise and error channels
  • Targeting real quantum hardware from cloud providers
  • Benchmarking quantum algorithms with GPU acceleration
  • Constructing hybrid quantum-classical optimization loops
  • Generating molecular Hamiltonians for quantum chemistry
  • Quantum error correction research and syndrome decoding
  • Simulating Hamiltonian dynamics and time evolution

Priority-Ordered Guidelines

PriorityCategoryImpactPrefix
1Kernel ConstructionCRITICALkernels-*
2Circuit ExecutionCRITICALsampling-*
3Variational AlgorithmsHIGHvariational-*
4Multi-GPU ScalingHIGHmulti-gpu-*
5CUDA-QX ExtensionsHIGHcudaqx-*
6Dynamics SimulationHIGHdynamics-*
7Noise ModelingMEDIUMnoise-*
8Hardware BackendsMEDIUMhardware-*

References

Full documentation with code examples in references/:

FileImpactDescription
kernels-and-gates.mdCRITICALKernel creation, qubit allocation, gate operations, parameterization
sampling-and-observe.mdCRITICALcudaq.sample, cudaq.observe, async execution, statevector access
variational-algorithms.mdHIGHVQE, QAOA, optimization loops, Hamiltonian construction
multi-gpu-workflows.mdHIGHMulti-GPU simulation, mqpu batching, distributed execution
cudaqx-extensions.mdHIGHMolecular Hamiltonians, ADAPT-VQE, QAOA, QEC codes, decoders
dynamics-simulation.mdHIGHcudaq.evolve, time-dependent Hamiltonians, Lindblad, bosonic operators
noise-modeling.mdMEDIUMNoise channels, density matrix simulation, Kraus operators, Stim
hardware-backends.mdMEDIUMIonQ, Quantinuum, IQM, OQC, ORCA, Infleqtion, Pasqal, Braket

Problem -> Skill Mapping

ProblemStart With
Build a quantum circuitkernels-and-gates.md
Run circuit and get resultssampling-and-observe.md
Implement VQE/QAOAvariational-algorithms.md
Scale to multiple GPUsmulti-gpu-workflows.md
Simulate with noisenoise-modeling.md
Run on real quantum hardwarehardware-backends.md
Compute expectation valuessampling-and-observe.md
Optimize circuit parametersvariational-algorithms.md
Batch parameter sweepsmulti-gpu-workflows.md
Molecular chemistry (H₂, N₂)cudaqx-extensions.md
Quantum error correctioncudaqx-extensions.md
Syndrome decodingcudaqx-extensions.md
Hamiltonian time evolutiondynamics-simulation.md
Open quantum systems (Lindblad)dynamics-simulation.md
Bosonic/photonic simulationdynamics-simulation.md

Attribution

Based on NVIDIA CUDA-Q, CUDA-QX documentation and cuda-quantum repository.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.