nvidia/cudaqx

Purpose and Build Surface

CUDA-QX is a C++/CUDA extension suite atop NVIDIA CUDA-Q for hybrid quantum-classical applications across CPUs, GPUs, and QPUs. The root CMake build composes a shared core plus independently consumable QEC and solver libraries: CMakeLists.txt, libs/core/CMakeLists.txt, libs/qec/CMakeLists.txt, libs/solvers/CMakeLists.txt.

Public Entry Points

C++ consumers use headers under cuda-qx/core, cudaq/qec, and cudaq/solvers. Python consumers import compiled bindings plus package facades: libs/qec/python/bindings/cudaqx_qec.cpp, libs/qec/python/cudaq_qec/__init__.py, libs/solvers/python/bindings/cudaqx_solvers.cpp, libs/solvers/python/cudaq_solvers/__init__.py. A standalone real-time decoding-server executable is defined at libs/qec/tools/decoding-server/decoding_server.cpp.

Shared Core

libs/core supplies reusable extension and data abstractions rather than domain algorithms: plugin/extension-point support, graphs, heterogeneous maps, teardown management, and tensor implementations. The central boundary is a lightweight common library consumed by QEC and solver modules: libs/core/include/cuda-qx/core/extension_point.h, libs/core/include/cuda-qx/core/graph.h, libs/core/lib/tensor_impls/xtensor_impl.cpp.

QEC Modeling and Offline Decoding

The QEC library models stabilizer codes, noise, patches, sparse parity-check matrices, detector error models (DEMs), and experiments. Primary flow is code/noise definition → DEM construction or sampling → decoder selection → correction/result. CUDA code supports repetition, Steane, and surface-code device paths: libs/qec/include/cudaq/qec/code.h, libs/qec/include/cudaq/qec/detector_error_model.h, libs/qec/lib/dem_construction.cpp, libs/qec/lib/dem_sampling/dem_sampling_gpu.cpp.

Decoder Plugin Boundary

Decoders are abstracted behind a decoder API and dynamically loaded plugins, allowing built-in LUT/sliding-window logic and optional integrations without coupling callers to a backend. Available integrations include PyMatching, Chromobius, and TensorRT; an NVIDIA QLDPC decoder binary is a closed-source distribution exception. Relevant boundaries: libs/qec/include/cudaq/qec/decoder.h, libs/qec/include/cudaq/qec/plugin_loader.h, libs/qec/lib/decoders/plugins/pymatching/pymatching.cpp, libs/qec/lib/decoders/plugins/trt_decoder/trt_decoder.cpp.

Real-Time QEC Pipeline and Service

A CUDA real-time pipeline accepts syndrome/decoder context, dispatches GPU kernels or AI pre/decoders, and emits decoding results. It supports in-process execution, simulation, Quantinuum-specific integration, and a CQR decoding-server transport with sessions, RPC wire format, transceivers, and device graph/ring consumers. This is the primary latency-sensitive control plane: libs/qec/include/cudaq/qec/realtime/pipeline.h, libs/qec/lib/realtime/realtime_pipeline.cu, libs/qec/lib/realtime/decoding-server-cqr/DecodingServer.cpp, libs/qec/lib/realtime/quantinuum/quantinuum_realtime_decoding.cpp.

Quantum Algorithm Solvers

The solvers library builds quantum operators/Hamiltonians, state preparation, gradients, and classical optimization into VQE, ADAPT, and QAOA workflows. Typical flow is molecule/graph input → operator compilation and pool/state preparation → CUDA-Q kernel observation/gradient evaluation → optimizer iteration. Molecular workflows can invoke PySCF through a driver boundary: libs/solvers/include/cudaq/solvers/vqe.h, libs/solvers/lib/adapt/adapt.cpp, libs/solvers/lib/qaoa/qaoa.cpp, libs/solvers/lib/operators/molecule/drivers/pyscf_driver.cpp.

Runtime, Packaging, and Deployment

The project targets C++ and Python with CUDA 12/13 wheel definitions, CUDA-Q as its foundational runtime, and CUDA/C++ GPU kernels. Optional infrastructure includes TensorRT/ONNX for AI decoders, cuStabilizer discovery, PySCF for chemistry, Docker images, and GitHub Actions builds. Real-time decoding is deployable as a dedicated Docker service: libs/qec/pyproject.toml.cu12, cmake/Modules/FindcuStabilizer.cmake, docker/decoding-server/Dockerfile, .github/workflows/build_decoding_server_docker.yaml.