DOCSEARCHbyAlgolia
Submit Docs

CUDA-Q Documentation

repository·main·Indexed 22 days ago

https://github.com/nvidia/cuda-quantum

A hybrid quantum-classical computing platform designed to integrate QPUs, GPUs, and CPUs. It provides a unified programming model, the nvq++ compiler, a runtime, and Python bindings (cudaq) for heterogeneous quantum-classical workflows. The toolkit includes the CUDA-Q Realtime library for low-latency networking and coprocessing between FPGA and CPU-GPU systems, as well as support for external QPU plugins.

Tokens
169.5K
Snippets
461
Records
664
Agent score
75%

What's inside CUDA-Q

  1. Overview of CPU RoCE Transport

    main

    The CpuRoceTransceiver is a pure-CPU RoCEv2 RDMA transport implementation that does not require a GPU, DOCA, or HSB software. It moves RPC messages between a quantum control system (FPGA) and a CPU-based decoder entirely in host memory with microsecond latency.

    It is provided as a separate library: cudaq-realtime-cpu-roce-transport (located in realtime/lib/cpu_transport/).

    It serves two primary use cases:

    1. Direct realtime dispatch: Acts as a drop-in CPU replacement for the GPU HSB transport when wired to a libcudaq-realtime dispatcher (e.g., using hsb_bridge_cpu with CUDAQ_DISPATCH_HOST_CALL).
    2. Compiler-lowered device_call: Serves as the transport for the cpu_roce device-call channel. This allows a quantum kernel's cudaq::device_call (lowered by nvq++ to the realtime RPC ABI) to be dispatched to a CPU-based service over RDMA without requiring a GPU on either side.

  2. What is NVIDIA CUDA-Q?

    main

    NVIDIA CUDA-Q is a programming model designed for heterogeneous quantum-classical computing. It provides a set of primitive types, concepts, syntax, and semantics that allow for the integration of Quantum Processing Units (QPUs) with existing NVIDIA multi-node, multi-GPU parallel programming models and architectures.

    Key characteristics include:

    • C++ Native: The core language is designed for C++.
    • Language Bindings: Extensions to other languages (such as Python) are supported via bindings.
    • Library-based Extensions: Quantum code is defined as callables within the classical language being extended.
    • Annotated Kernels: Quantum coprocessing callables must be annotated so that compilers and runtimes can perform quantum-specific optimizations and transformations for execution on simulators or physical QPUs.

  3. Overview of CUDA-Q Realtime Library

    main

    CUDA-Q Realtime is designed to tightly couple GPU-accelerated compute with the control system of a quantum processor. It serves two main purposes:

    1. Realtime Coprocessing: Provides the low-level foundation for coprocessing between FPGA and CPU-GPU systems.
    2. Low Latency Networking: Implements the NVQLink architecture networking stack, allowing system integrators to achieve data round trips between FPGA and GPU in the range of a few microseconds.

  4. Overview of CUDA-QX libraries

    main
    CUDA-QX is a collection of C++ libraries and Python packages built on the CUDA-Q programming model. It is designed for developing hybrid quantum-classical applications that leverage CPUs, GPUs, and QPUs. The ecosystem is primarily divided into two functional areas: CUDA-Q Solvers for optimization and chemistry, and CUDA-Q QEC for quantum error correction research.

  5. Overview of CUDA-Q programming model

    main
    CUDA-Q is a programming model and toolchain designed for hybrid quantum-classical computing. It enables developers to build applications that leverage heterogeneous architectures, specifically integrating CPUs, GPUs, and QPUs (Quantum Processing Units) into a unified workflow. CUDA-Q provides native support for both Python and C++ programming languages.

  6. Overview of CUDA-Q Circuit Simulation Backends

    main

    CUDA-Q provides a variety of simulation backends categorized by their underlying mathematical method (State Vector, Tensor Network, Matrix Product State, etc.), the hardware they target (CPU, Single GPU, multi-GPU/multi-node), and the precision they support.

    When choosing a simulator, consider:

    • Method: State Vector for general purpose, Tensor Network for shallow/wide circuits, or Matrix Product State (MPS) for square-shaped circuits.
    • Scale: Use qpp-cpu for small testing (< 28 qubits), nvidia for general GPU simulation (< 33 qubits), and nvidia, option=mgpu or tensornet for large-scale simulations.
    • Noise: Use density-matrix-cpu for small noisy simulations (< 14 qubits) or Trajectory Noisy Simulation for larger noisy circuits.

  7. Overview of CUDA-Q Realtime

    main

    CUDA-Q Realtime is a library designed to tightly couple GPU-accelerated compute to the control system of a quantum processor through a specialized networking layer. It is intended for high-performance realtime co-processing between FPGA and CPU-GPU systems.

    Key Responsibilities:

    1. Realtime Co-processing: Provides the low-level foundation for interaction between FPGAs and CPU-GPU systems.
    2. Low Latency Networking: Implements the NVQLink architecture's networking layer, enabling data round trips between FPGA and GPU within a few microseconds.

    Hardware Requirements:

    • Host System: Must include an NVIDIA GPU and a ConnectX-7 or BlueField NIC.
    • FPGA: Must be connected to the NIC.

    Networking Implementation: The default networking layer utilizes the Holoscan Sensor Bridge to manage high-bandwidth data transfers over Ethernet using the RoCE (RDMA over Converged Ethernet) protocol. Users have the option to replace this default layer with a custom implementation.

  8. Use the cudaq.ptsbe submodule for Pre-Trajectory Sampling with Batch Execution

    main

    The cudaq.ptsbe submodule implements Pre-Trajectory Sampling with Batch Execution (PTSBE). It provides tools for sampling quantum trajectories and managing execution data.

    Key components include:

    • Sampling Functions: cudaq.ptsbe.sample and its asynchronous counterpart cudaq.ptsbe.sample_async.
    • Sampling Strategies: Controlled via PTSSamplingStrategy, with specific implementations like ProbabilisticSamplingStrategy, OrderedSamplingStrategy, and ExhaustiveSamplingStrategy.
    • Shot Allocation: Managed through ShotAllocationStrategy and ShotAllocationType.
    • Results and Data: Results are returned as PTSBESampleResult objects, and execution details are captured in PTSBEExecutionData containing TraceInstruction objects.

  9. Explore CUDA-Q compiler code organization

    main

    If you are developing compiler extensions or investigating the internals, the following directory structure is relevant:

    Frontend Bridges

    • C++ AST Bridge: cudaq/lib/Frontend/nvqpp (driven by cudaq-quake).
    • Python AST Bridge: python/cudaq/kernel/ast_bridge.py.
    • Python Kernel Builder: python/cudaq/kernel/kernel_builder.py.

    Dialects and Code Generation

    • Dialect Declarations (Quake, CC, QEC): cudaq/include/cudaq/Optimizer/Dialect.
    • CodeGen Helpers: cudaq/include/cudaq/Optimizer/CodeGen.
    • Transformations and Lowering Passes: cudaq/lib/Optimizer/Transforms and cudaq/lib/Optimizer/CodeGen.
    • Shared Pipelines: Defined in the corresponding Pipelines.cpp files within the transform/codegen directories.

    Tooling and Testing

    • cudaq-opt: Parses and runs registered MLIR passes.
    • cudaq-translate: Manages the standalone translation path.
    • cudaq-target-conf: Reads target configuration for the C++ driver.
    • C++ Tests: Located in cudaq/test/AST-Quake, cudaq/test/Transforms, and cudaq/test/Translate.
    • Python Tests: MLIR regression tests are in python/tests/mlir; general frontend behavior is in python/tests/kernel.

  10. Access hardware resources via CUDA-Q Cloud Backends

    main

    CUDA-Q provides several cloud backend options to access remote hardware resources, including GPUs and Quantum Processing Units (QPUs). Using cloud backends allows for more flexible access to simulation and physical hardware resources without requiring local infrastructure.

    Supported cloud backends include:

    • Amazon Braket (braket)
    • Scaleway QaaS (scaleway)
    • qBraid

  11. Extending CUDA-Q with a new Hardware Backend

    main

    CUDA-Q allows you to create new quantum hardware backends as external plugins. These are self-contained packages that register targets with the CUDA-Q runtime without requiring modifications to the core repository. Plugins can be distributed as Python packages for easy installation by end users.

    Common backend types include REST-style backends, which communicate with a provider's HTTP API by subclassing ServerHelper and reusing the built-in remote_rest QPU.

  12. Understand CUDA-Q backend categories

    main

    CUDA-Q provides several categories of backends for running hybrid quantum applications and simulations. Depending on your use case, you should choose from one of the following four categories:

    1. Circuit Simulation: For simulating quantum circuits on classical hardware.
    2. Quantum Hardware (QPUs): For executing programs on actual quantum processing units.
    3. Dynamics Simulation: For simulating quantum dynamics.
    4. Cloud: For accessing backends via cloud services.

    To implement a new hardware backend, refer to the extending/backend and extending/packaging documentation.