NVIDIA CUDA-Q
latest

Contents

  • Quick Start
    • Install CUDA-Q
    • Validate your Installation
    • CUDA-Q Academic
  • Basics
    • What is a CUDA-Q Kernel?
    • Building your first CUDA-Q Program
    • Running your first CUDA-Q Program
      • Sample
      • Run
      • Observe
      • Running on a GPU
    • Troubleshooting
      • Debugging and Verbose Simulation Output
  • Examples
    • Introduction
    • Building Kernels
      • Defining Kernels
      • Initializing states
      • Applying Gates
      • Controlled Operations
      • Multi-Controlled Operations
      • Adjoint Operations
      • Custom Operations
      • Building Kernels with Kernels
      • Parameterized Kernels
    • Quantum Operations
      • Quantum States
      • Quantum Gates
      • Measurements
    • Measuring Kernels
      • Mid-circuit Measurement and Conditional Logic
    • Visualizing Kernels
      • Qubit Visualization
      • Kernel Visualization
    • Executing Kernels
      • Sample
        • Sample Asynchronous
      • Run
        • Return Custom Data Types
        • Run Asynchronous
      • Observe
        • Observe Asynchronous
      • Get State
        • Get State Asynchronous
    • Computing Expectation Values
      • Parallelizing across Multiple Processors
    • Multi-GPU Workflows
      • From CPU to GPU
      • Pooling the memory of multiple GPUs (mgpu)
      • Parallel execution over multiple QPUs (mqpu)
        • Batching Hamiltonian Terms
        • Circuit Batching
      • Multi-QPU + Other Backends (remote-mqpu)
    • Optimizers & Gradients
      • CUDA-Q Optimizer Overview
        • Gradient-Free Optimizers (no gradients required):
        • Gradient-Based Optimizers (require gradients):
      • 1. Built-in CUDA-Q Optimizers and Gradients
        • 1.1 Adam Optimizer with Parameter Configuration
        • 1.2 SGD (Stochastic Gradient Descent) Optimizer
        • 1.3 SPSA (Simultaneous Perturbation Stochastic Approximation)
      • 2. Third-Party Optimizers
      • 3. Parallel Parameter Shift Gradients
    • Noisy Simulations
    • PTSBE End-to-End Workflow
      • Set up the environment
      • Define the circuit and noise model
        • Inline noise with apply_noise
      • Run PTSBE sampling
        • Larger circuit for execution data
      • Inspecting trajectories with execution data
    • Constructing Operators
      • Constructing Spin Operators
      • Pauli Words and Exponentiating Pauli Words
    • Performance Optimizations
      • Gate Fusion
    • Using Quantum Hardware Providers
      • Amazon Braket
      • Anyon Technologies
      • Infleqtion
      • IonQ
      • IQM
      • OQC
      • ORCA Computing
      • Pasqal
      • Quantinuum
      • Quantum Circuits, Inc.
      • Quantum Machines
      • QuEra Computing
      • Scaleway
      • TII
    • When to Use sample vs. run
      • Introduction
      • Usage Guidelines
      • What Is Supported with sample
      • What Is Not Supported with sample
      • How to Migrate
        • Step 1: Add a return type to the kernel
        • Step 2: Replace sample with run
        • Step 3: Update result processing
      • Migration Examples
        • Example 1: Simple conditional logic
        • Example 2: Returning multiple measurement results
        • Example 3: Quantum teleportation
      • Additional Notes
    • Dynamics Examples
      • Introduction to CUDA-Q Dynamics (Jaynes-Cummings Model)
        • Why dynamics simulations vs. circuit simulations?
        • Functionality
        • Performance
        • Section 1 - Simulating the Jaynes-Cummings Hamiltonian
        • Exercise 1 - Simulating a many-photon Jaynes-Cummings Hamiltonian
        • Section 2 - Simulating open quantum systems with the collapse_operators
        • Exercise 2 - Adding additional jump operators \(L_i\)
        • Section 3 - Many qubits coupled to the resonator
      • Introduction to CUDA-Q Dynamics (Time Dependent Hamiltonians)
        • The Landau-Zener model
        • Section 1 - Implementing time dependent terms
        • Section 2 - Implementing custom operators
        • Section 3 - Heisenberg Model with a time-varying magnetic field
        • Exercise 1 - Define a time-varying magnetic field
        • Exercise 2 (Optional)
      • Superconducting Qubits
        • Cavity QED
        • Cross Resonance
        • Transmon Resonator
      • Spin Qubits
        • Silicon Spin Qubit
        • Heisenberg Model
      • Trapped Ion Qubits
        • GHZ state
      • Control
        • Gate Calibration
        • Pulse
        • Qubit Control
        • Qubit Dynamics
        • Landau-Zenner
  • Applications
    • Max-Cut with QAOA
    • Molecular docking via DC-QAOA
      • Setting up the Molecular Docking Problem
      • CUDA-Q Implementation
    • Multi-reference Quantum Krylov Algorithm - \(H_2\) Molecule
      • Setup
      • Computing the matrix elements
      • Determining the ground state energy of the subspace
    • Quantum-Selected Configuration Interaction (QSCI)
      • 0. Problem definition
      • 1. Prepare an Approximate Quantum State
      • 2 Quantum Sampling to Select Configuration
      • 3. Classical Diagonalization on the Selected Subspace
      • 5. Compuare results
      • Reference
    • Bernstein-Vazirani Algorithm
      • Classical case
      • Quantum case
      • Implementing in CUDA-Q
    • Cost Minimization
    • Deutsch’s Algorithm
      • XOR \(\oplus\)
      • Quantum oracles
      • Phase oracle
      • Quantum parallelism
      • Deutsch’s Algorithm:
    • Divisive Clustering With Coresets Using CUDA-Q
      • Data preprocessing
      • Quantum functions
      • Divisive Clustering Function
      • QAOA Implementation
      • Scaling simulations with CUDA-Q
    • Hybrid Quantum Neural Networks
    • Using the Hadamard Test to Determine Quantum Krylov Subspace Decomposition Matrix Elements
      • Numerical result as a reference:
      • Using Sample to perform the Hadamard test
      • Multi-GPU evaluation of QKSD matrix elements using the Hadamard Test
        • Classically Diagonalize the Subspace Matrix
    • Anderson Impurity Model ground state solver on Infleqtion’s Sqale
      • Performing logical Variational Quantum Eigensolver (VQE) with CUDA-QX
      • Constructing circuits in the [[4,2,2]] encoding
      • Setting up submission and decoding workflow
      • Running a CUDA-Q noisy simulation
      • Running logical AIM on Infleqtion’s hardware
    • Spin-Hamiltonian Simulation Using CUDA-Q
      • Introduction
        • Heisenberg Hamiltonian
        • Transverse Field Ising Model (TFIM)
        • Time Evolution and Trotter Decomposition
      • Key steps
        • 1. Prepare initial state
        • 2. Hamiltonian Trotterization
        • 3. Compute overlap
        • 4. Construct Heisenberg Hamiltonian
        • 5. Construct TFIM Hamiltonian
        • 6. Extract coefficients and Pauli words
      • Main code
      • Visualization of probablity over time
      • Expectation value over time:
      • Visualization of expectation over time
      • Additional information
      • Relevant references
    • Quantum Fourier Transform
      • Quantum Fourier Transform revisited
    • Quantum Teleporation
      • Teleportation explained
    • Quantum Volume
    • Readout Error Mitigation
      • Inverse confusion matrix from single-qubit noise model
      • Inverse confusion matrix from k local confusion matrices
      • Inverse of full confusion matrix
    • Compiling Unitaries Using Diffusion Models
      • Diffusion model pipeline
      • Setup and load models
        • Load discrete model
        • Load continuous model
        • Create helper functions
      • Unitary compilation
        • Random unitary
        • Discrete model
        • Continuous model
        • Quantum Fourier transform
        • XXZ-Hamiltonian evolution
      • Choosing the circuit you need
    • VQE with gradients, active spaces, and gate fusion
      • The Basics of VQE
      • Installing/Loading Relevant Packages
      • Implementing VQE in CUDA-Q
      • Parallel Parameter Shift Gradients
      • Using an Active Space
      • Gate Fusion for Larger Circuits
    • Quantum Transformer
      • Installation
      • Algorithm and Example
        • Creating the self-attention circuits
      • Usage
        • Model Training
        • Generating Molecules
        • Attention Maps
    • Quantum Enhanced Auxiliary Field Quantum Monte Carlo
      • Hamiltonian preparation for VQE
      • Run VQE with CUDA-Q
      • Auxiliary Field Quantum Monte Carlo (AFQMC)
      • Preparation of the molecular Hamiltonian
      • Preparation of the trial wave function
      • Setup of the AFQMC parameters
    • ADAPT-QAOA algorithm
      • Simulation input:
      • The problem Hamiltonian \(H_C\) of the max-cut graph:
      • Th operator pool \(A_j\):
      • The commutator \([H_C,A_j]\):
      • Beginning of ADAPT-QAOA iteration:
    • ADAPT-VQE algorithm
      • Classical pre-processing
      • Jordan Wigner:
      • UCCSD operator pool
        • Single excitation
        • Double excitation
      • Commutator [\(H\), \(A_i\)]
      • Reference State:
      • Quantum kernels:
      • Beginning of ADAPT-VQE:
    • Quantum edge detection
      • Image
      • Quantum Probability Image Encoding (QPIE):
        • Below we show how to encode an image using QPIE in cudaq.
      • Flexible Representation of Quantum Images (FRQI):
        • Building the FRQI State:
      • Quantum Hadamard Edge Detection (QHED)
        • Post-processing
    • Factoring Integers With Shor’s Algorithm
      • Shor’s algorithm
        • Solving the order-finding problem classically
        • Solving the order-finding problem with a quantum algorithm
        • Determining the order from the measurement results of the phase kernel
        • Postscript
    • Generating the electronic Hamiltonian
      • Second Quantized formulation.
        • Computational Implementation
        • (a) Generate the molecular Hamiltonian using Restricted Hartree Fock molecular orbitals
        • (b) Generate the molecular Hamiltonian using Unrestricted Hartree Fock molecular orbitals
        • (a) Generate the active space hamiltonian using RHF molecular orbitals.
        • (b) Generate the active space Hamiltonian using the natural orbitals computed from MP2 simulation
        • (c) Generate the active space Hamiltonian computed from the CASSCF molecular orbitals
        • (d) Generate the electronic Hamiltonian using ROHF
        • (e) Generate electronic Hamiltonian using UHF
    • Grover’s Algorithm
      • Overview
      • Problem
      • Structure of Grover’s Algorithm
        • Step 1: Preparation
        • Good and Bad States
        • Step 2: Oracle application
        • Step 3: Amplitude amplification
        • Steps 4 and 5: Iteration and measurement
    • Quantum PageRank
      • Problem Definition
      • Simulating Quantum PageRank by CUDA-Q dynamics
      • Breakdown of Terms
    • The UCCSD Wavefunction ansatz
      • What is UCCSD?
      • Implementation in Quantum Computing
      • Run VQE
      • Challenges and consideration
    • Approximate State Preparation using MPS Sequential Encoding
      • Ran’s approach
    • QM/MM simulation: VQE within a Polarizable Embedded Framework.
      • Key concepts:
      • PE-VQE-SCF Algorithm Steps
        • Step 1: Initialize (Classical pre-processing)
        • Step 2: Build the Hamiltonian
        • Step 3: Run VQE
        • Step 4: Update Environment
        • Step 5: Self-Consistency Loop
        • Requirments:
        • Example 1: LiH with 2 water molecules.
        • VQE, update environment, and scf loop.
        • Example 2: NH3 with 46 water molecule using active space.
    • Sample-Based Krylov Quantum Diagonalization (SKQD)
      • Why SKQD?
      • Understanding Krylov Subspaces
        • What is a Krylov Subspace?
        • The SKQD Algorithm
      • Problem Setup: 22-Qubit Heisenberg Model
      • Krylov State Generation via Repeated Evolution
      • Quantum Measurements and Sampling
        • The Sampling Process
      • Classical Post-Processing and Diagonalization
        • The SKQD Algorithm: Matrix Construction Details
      • Results Analysis and Convergence
        • What to Expect:
      • GPU Acceleration for Postprocessing
    • Entanglement Accelerates Quantum Simulation
      • 2. Model Definition
        • 2.1 Initial product state
        • 2.2 QIMF Hamiltonian
        • 2.3 First-Order Trotter Formula (PF1)
        • 2.4 PF1 step for the QIMF partition
        • 2.5 Hamiltonian helpers
      • 3. Entanglement metrics
      • 4. Simulation workflow
        • 4.1 Single-step Trotter error
        • 4.2 Dual trajectory update
      • 5. Reproducing the paper’s Figure 1a
        • 5.1 Visualising the joint behaviour
        • 5.2 Interpreting the result
      • 6. References and further reading
  • Backends
    • Circuit Simulation
      • State Vector Simulators
        • CPU
        • Single-GPU
        • Multi-GPU multi-node
      • Tensor Network Simulators
        • Multi-GPU multi-node
        • Matrix product state
        • Fermioniq
      • Multi-QPU Simulators
        • Simulate Multiple QPUs in Parallel
        • Multi-QPU + Other Backends
      • Noisy Simulators
        • Trajectory Noisy Simulation
        • Density Matrix
        • Stim
      • Photonics Simulators
        • orca-photonics
    • Quantum Hardware (QPUs)
      • Ion Trap QPUs
        • IonQ
        • Quantinuum
      • Superconducting QPUs
        • Anyon Technologies/Anyon Computing
        • IQM
        • OQC
        • Quantum Circuits, Inc.
        • TII
      • Neutral Atom QPUs
        • Infleqtion
        • Pasqal
        • QuEra Computing
      • Photonic QPUs
        • ORCA Computing
      • Quantum Control Systems
        • Quantum Machines
    • Dynamics Simulation
    • Cloud
      • Amazon Braket (braket)
        • Setting Credentials
        • Submitting
      • Scaleway QaaS (scaleway)
        • Setting Credentials
        • Submitting
        • Manage your QPU session
  • Dynamics
    • Quick Start
    • Operator
    • Time-Dependent Dynamics
    • Super-operator Representation
    • Numerical Integrators
    • Batch simulation
    • Multi-GPU Multi-Node Execution
    • Examples
  • CUDA-QX
    • CUDA-Q Solvers
    • CUDA-Q QEC
  • Installation
    • Local Installation
      • Introduction
        • Docker
        • Known Blackwell Issues
        • Singularity
        • Python wheels
        • Pre-built binaries
      • Development with VS Code
        • Using a Docker container
        • Using a Singularity container
      • Connecting to a Remote Host
        • Developing with Remote Tunnels
        • Remote Access via SSH
      • DGX Cloud
        • Get Started
        • Use JupyterLab
        • Use VS Code
      • Additional CUDA Tools
        • Installation via PyPI
        • Installation In Container Images
        • Installing Pre-built Binaries
      • Distributed Computing with MPI
      • Updating CUDA-Q
      • Dependencies and Compatibility
      • Next Steps
    • Data Center Installation
      • Prerequisites
      • Build Dependencies
        • CUDA
        • Toolchain
      • Building CUDA-Q
      • Python Support
      • C++ Support
      • Installation on the Host
        • CUDA Runtime Libraries
        • MPI
  • Integration
    • Downstream CMake Integration
    • Combining CUDA with CUDA-Q
    • Integrating with Third-Party Libraries
      • Calling a CUDA-Q library from C++
      • Calling an C++ library from CUDA-Q
      • Interfacing between binaries compiled with a different toolchains
  • Extending
    • Add a new Hardware Backend
      • Overview
      • Server Helper Implementation
        • Directory Structure
        • Server Helper Class
        • CMakeLists.txt
      • Target Configuration
        • Update Parent CMakeLists.txt
      • Testing
        • Unit Tests
        • Mock Server
        • Python Tests
        • Integration Tests
      • Documentation
      • Example Usage
      • Code Review
      • Maintaining a Backend
      • Conclusion
    • Create a new NVQIR Simulator
      • CircuitSimulator
      • Let’s see this in action
    • Working with CUDA-Q IR
    • Create an MLIR Pass for CUDA-Q
  • Specifications
    • Language Specification
      • 1. Machine Model
      • 2. Namespace and Standard
      • 3. Quantum Types
        • 3.1. cudaq::qudit<Levels>
        • 3.2. cudaq::qubit
        • 3.3. Quantum Containers
      • 4. Quantum Operators
        • 4.1. cudaq::spin_op
      • 5. Quantum Operations
        • 5.1. Operations on cudaq::qubit
      • 6. Quantum Kernels
      • 7. Sub-circuit Synthesis
      • 8. Control Flow
      • 9. Just-in-Time Kernel Creation
      • 10. Quantum Patterns
        • 10.1. Compute-Action-Uncompute
      • 11. Platform
      • 12. Algorithmic Primitives
        • 12.1. cudaq::sample
        • 12.2. cudaq::run
        • 12.3. cudaq::observe
        • 12.4. cudaq::optimizer (deprecated, functionality moved to CUDA-Q libraries)
        • 12.5. cudaq::gradient (deprecated, functionality moved to CUDA-Q libraries)
      • 13. Example Programs
        • 13.1. Hello World - Simple Bell State
        • 13.2. GHZ State Preparation and Sampling
        • 13.3. Quantum Phase Estimation
        • 13.4. Deuteron Binding Energy Parameter Sweep
        • 13.5. Grover’s Algorithm
        • 13.6. Iterative Phase Estimation
    • Quake Specification
      • General Introduction
      • Motivation
  • API Reference
    • C++ API
      • Operators
      • Quantum
      • Common
      • Noise Modeling
      • Kernel Builder
      • Algorithms
      • Platform
      • Utilities
      • Namespaces
    • Python API
      • Program Construction
        • make_kernel()
        • PyKernel
        • Kernel
        • PyKernelDecorator
        • kernel()
      • Kernel Execution
        • sample()
        • sample_async()
        • run()
        • run_async()
        • observe()
        • observe_async()
        • get_state()
        • get_state_async()
        • vqe()
        • draw()
        • translate()
        • estimate_resources()
      • Backend Configuration
        • has_target()
        • get_target()
        • get_targets()
        • set_target()
        • reset_target()
        • set_noise()
        • unset_noise()
        • register_set_target_callback()
        • unregister_set_target_callback()
        • cudaq.apply_noise()
        • initialize_cudaq()
        • num_available_gpus()
        • set_random_seed()
      • Dynamics
        • evolve()
        • evolve_async()
        • Schedule
        • BaseIntegrator
        • InitialState
        • InitialStateType
        • IntermediateResultSave
      • Operators
        • OperatorSum
        • ProductOperator
        • ElementaryOperator
        • ScalarOperator
        • RydbergHamiltonian
        • SuperOperator
        • operators.define()
        • operators.instantiate()
        • Spin Operators
        • Fermion Operators
        • Boson Operators
        • General Operators
      • Data Types
        • SimulationPrecision
        • Target
        • State
        • Tensor
        • QuakeValue
        • qubit
        • qreg
        • qvector
        • ComplexMatrix
        • SampleResult
        • AsyncSampleResult
        • ObserveResult
        • AsyncObserveResult
        • AsyncStateResult
        • OptimizationResult
        • EvolveResult
        • AsyncEvolveResult
        • Resources
        • Optimizers
        • Gradients
        • Noisy Simulation
      • MPI Submodule
        • initialize()
        • rank()
        • num_ranks()
        • all_gather()
        • broadcast()
        • is_initialized()
        • finalize()
      • ORCA Submodule
        • sample()
    • Quantum Operations
      • Unitary Operations on Qubits
        • x
        • y
        • z
        • h
        • r1
        • rx
        • ry
        • rz
        • s
        • t
        • swap
        • u3
      • Adjoint and Controlled Operations
      • Measurements on Qubits
        • mz
        • mx
        • my
      • User-Defined Custom Operations
      • Photonic Operations on Qudits
        • create
        • annihilate
        • phase_shift
        • beam_splitter
        • mz
  • Other Versions
NVIDIA CUDA-Q
  • CUDA-Q by Example
Previous Next

CUDA-Q by Example¶

Examples that illustrate how to use CUDA-Q for application development are available in C++ and Python.

  • Introduction
  • Building Kernels
  • Quantum Operations
  • Measuring Kernels
  • Visualizing Kernels
  • Executing Kernels
  • Computing Expectation Values
  • Multi-GPU Workflows
  • Optimizers & Gradients
  • Noisy Simulations
  • PTSBE End-to-End Workflow
  • Constructing Operators
  • Performance Optimizations
  • Using Quantum Hardware Providers
  • When to Use sample vs. run
  • Dynamics Examples
Previous Next

© Copyright 2026, NVIDIA Corporation & Affiliates.

Built with Sphinx using a theme provided by Read the Docs.