# nvidia/cudaqx architecture

> Architecture diagram of the GitHub repository nvidia/cudaqx, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nvidia/cudaqx
- Repository: https://github.com/nvidia/cudaqx

## Overview

#### 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`.

Main entry points: [`libs/qec/include/cudaq/qec/decoder.h`](https://github.com/nvidia/cudaqx/blob/main/libs/qec/include/cudaq/qec/decoder.h) (Decoder API & loader), [`libs/solvers/include/cudaq/solvers/vqe.h`](https://github.com/nvidia/cudaqx/blob/main/libs/solvers/include/cudaq/solvers/vqe.h) (VQE, ADAPT & QAOA), [`libs/qec/include/cudaq/qec/code.h`](https://github.com/nvidia/cudaqx/blob/main/libs/qec/include/cudaq/qec/code.h) (QEC code & noise model), [`libs/qec/lib/realtime/realtime_pipeline.cu`](https://github.com/nvidia/cudaqx/blob/main/libs/qec/lib/realtime/realtime_pipeline.cu) (Real-time pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_build["Build & deployment"]
  node_root_build["Root build<br/>CMake build<br/>[CMakeLists.txt]"]
  node_decoding_server_bin["Decoding-server executable<br/>service executable"]
  node_server_docker["Decoding-server image<br/>Docker deployment"]
end

subgraph group_core["Shared core"]
  node_core_api["Core extension APIs<br/>C++ headers<br/>[extension_point.h]"]
  node_tensor_impl["Tensor implementations<br/>C++ implementation<br/>[xtensor_impl.cpp]"]
end

subgraph group_qec["QEC &amp; real-time decoding"]
  node_qec_model["QEC code &amp; noise model<br/>C++ API<br/>[code.h]"]
  node_detector_model["Detector error model<br/>QEC model API"]
  node_dem_builder["DEM construction<br/>QEC processing"]
  node_gpu_dem_sampler["GPU DEM sampling<br/>CUDA implementation"]
  node_decoder_api{{"Decoder API &amp; loader<br/>plugin boundary<br/>[decoder.h]"}}
  node_pymatching_plugin["PyMatching decoder<br/>decoder plugin<br/>[pymatching.cpp]"]
  node_trt_plugin["TensorRT decoder<br/>AI decoder plugin<br/>[trt_decoder.cpp]"]
  node_realtime_pipeline["Real-time pipeline<br/>CUDA QEC pipeline"]
  node_cqr_server["CQR decoding server<br/>RPC service<br/>[DecodingServer.cpp]"]
end

subgraph group_solvers["Quantum solvers"]
  node_solver_workflows["VQE, ADAPT &amp; QAOA<br/>solver workflows<br/>[vqe.h]"]
  node_pyscf_driver["PySCF chemistry driver<br/>optional integration<br/>[pyscf_driver.cpp]"]
end

subgraph group_python["Python packages"]
  node_qec_python["cudaq_qec package<br/>Python facade<br/>[__init__.py]"]
  node_solvers_python["cudaq_solvers package<br/>Python facade<br/>[__init__.py]"]
end

node_cudaq_runtime{{"CUDA-Q runtime<br/>foundational runtime"}}

node_root_build -->|"builds"| node_core_api
node_root_build -->|"builds"| node_qec_model
node_root_build -->|"builds"| node_solver_workflows
node_core_api -->|"supports"| node_tensor_impl
node_qec_model -->|"defines inputs for"| node_detector_model
node_detector_model -->|"constructed by"| node_dem_builder
node_detector_model -->|"sampled on GPU"| node_gpu_dem_sampler
node_dem_builder -->|"provides decoding input"| node_decoder_api
node_gpu_dem_sampler -->|"provides syndromes"| node_decoder_api
node_decoder_api -.->|"loads"| node_pymatching_plugin
node_decoder_api -.->|"loads"| node_trt_plugin
node_realtime_pipeline -->|"dispatches decoders"| node_decoder_api
node_cqr_server -->|"serves requests through"| node_realtime_pipeline
node_decoding_server_bin -->|"hosts"| node_cqr_server
node_server_docker -->|"deploys"| node_decoding_server_bin
node_qec_python -->|"exposes"| node_qec_model
node_qec_python -->|"accesses"| node_realtime_pipeline
node_pyscf_driver -.->|"provides molecular inputs"| node_solver_workflows
node_solver_workflows -->|"observes kernels on"| node_cudaq_runtime
node_solvers_python -->|"exposes"| node_solver_workflows
node_qec_model -->|"uses shared abstractions"| node_core_api
node_solver_workflows -->|"uses shared abstractions"| node_core_api
node_realtime_pipeline -->|"executes with"| node_cudaq_runtime

click node_root_build "https://github.com/nvidia/cudaqx/blob/main/CMakeLists.txt"
click node_core_api "https://github.com/nvidia/cudaqx/blob/main/libs/core/include/cuda-qx/core/extension_point.h"
click node_tensor_impl "https://github.com/nvidia/cudaqx/blob/main/libs/core/lib/tensor_impls/xtensor_impl.cpp"
click node_qec_model "https://github.com/nvidia/cudaqx/blob/main/libs/qec/include/cudaq/qec/code.h"
click node_detector_model "https://github.com/nvidia/cudaqx/blob/main/libs/qec/include/cudaq/qec/detector_error_model.h"
click node_dem_builder "https://github.com/nvidia/cudaqx/blob/main/libs/qec/lib/dem_construction.cpp"
click node_gpu_dem_sampler "https://github.com/nvidia/cudaqx/blob/main/libs/qec/lib/dem_sampling/dem_sampling_gpu.cpp"
click node_decoder_api "https://github.com/nvidia/cudaqx/blob/main/libs/qec/include/cudaq/qec/decoder.h"
click node_pymatching_plugin "https://github.com/nvidia/cudaqx/blob/main/libs/qec/lib/decoders/plugins/pymatching/pymatching.cpp"
click node_trt_plugin "https://github.com/nvidia/cudaqx/blob/main/libs/qec/lib/decoders/plugins/trt_decoder/trt_decoder.cpp"
click node_realtime_pipeline "https://github.com/nvidia/cudaqx/blob/main/libs/qec/lib/realtime/realtime_pipeline.cu"
click node_cqr_server "https://github.com/nvidia/cudaqx/blob/main/libs/qec/lib/realtime/decoding-server-cqr/DecodingServer.cpp"
click node_decoding_server_bin "https://github.com/nvidia/cudaqx/blob/main/libs/qec/tools/decoding-server/decoding_server.cpp"
click node_qec_python "https://github.com/nvidia/cudaqx/blob/main/libs/qec/python/cudaq_qec/__init__.py"
click node_solver_workflows "https://github.com/nvidia/cudaqx/blob/main/libs/solvers/include/cudaq/solvers/vqe.h"
click node_pyscf_driver "https://github.com/nvidia/cudaqx/blob/main/libs/solvers/lib/operators/molecule/drivers/pyscf_driver.cpp"
click node_solvers_python "https://github.com/nvidia/cudaqx/blob/main/libs/solvers/python/cudaq_solvers/__init__.py"
click node_server_docker "https://github.com/nvidia/cudaqx/blob/main/docker/decoding-server/Dockerfile"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_root_build,node_decoding_server_bin,node_server_docker toneBlue
class node_core_api,node_tensor_impl toneAmber
class node_qec_model,node_detector_model,node_dem_builder,node_gpu_dem_sampler,node_decoder_api,node_pymatching_plugin,node_trt_plugin,node_realtime_pipeline,node_cqr_server toneMint
class node_solver_workflows,node_pyscf_driver toneRose
class node_qec_python,node_solvers_python toneIndigo
class node_cudaq_runtime toneNeutral
```

## Components

### Build & deployment

- [Root build](https://github.com/nvidia/cudaqx/blob/main/CMakeLists.txt): CMake build · Composes core, QEC, and solver libraries. · `CMakeLists.txt`
- [Decoding-server executable](https://github.com/nvidia/cudaqx/blob/main/libs/qec/tools/decoding-server/decoding_server.cpp): service executable · `libs/qec/tools/decoding-server/decoding_server.cpp`
- [Decoding-server image](https://github.com/nvidia/cudaqx/blob/main/docker/decoding-server/Dockerfile): Docker deployment · `docker/decoding-server/Dockerfile`

### Shared core

- [Core extension APIs](https://github.com/nvidia/cudaqx/blob/main/libs/core/include/cuda-qx/core/extension_point.h): C++ headers · Extension points and shared graph abstractions. · `libs/core/include/cuda-qx/core/extension_point.h`
- [Tensor implementations](https://github.com/nvidia/cudaqx/blob/main/libs/core/lib/tensor_impls/xtensor_impl.cpp): C++ implementation · `libs/core/lib/tensor_impls/xtensor_impl.cpp`

### QEC & real-time decoding

- [QEC code & noise model](https://github.com/nvidia/cudaqx/blob/main/libs/qec/include/cudaq/qec/code.h): C++ API · Defines stabilizer codes, noise, patches, and experiments. · `libs/qec/include/cudaq/qec/code.h`
- [Detector error model](https://github.com/nvidia/cudaqx/blob/main/libs/qec/include/cudaq/qec/detector_error_model.h): QEC model API · `libs/qec/include/cudaq/qec/detector_error_model.h`
- [DEM construction](https://github.com/nvidia/cudaqx/blob/main/libs/qec/lib/dem_construction.cpp): QEC processing · `libs/qec/lib/dem_construction.cpp`
- [GPU DEM sampling](https://github.com/nvidia/cudaqx/blob/main/libs/qec/lib/dem_sampling/dem_sampling_gpu.cpp): CUDA implementation · `libs/qec/lib/dem_sampling/dem_sampling_gpu.cpp`
- [Decoder API & loader](https://github.com/nvidia/cudaqx/blob/main/libs/qec/include/cudaq/qec/decoder.h): plugin boundary · Selects and dynamically loads decoder backends. · `libs/qec/include/cudaq/qec/decoder.h`
- [PyMatching decoder](https://github.com/nvidia/cudaqx/blob/main/libs/qec/lib/decoders/plugins/pymatching/pymatching.cpp): decoder plugin · `libs/qec/lib/decoders/plugins/pymatching/pymatching.cpp`
- [TensorRT decoder](https://github.com/nvidia/cudaqx/blob/main/libs/qec/lib/decoders/plugins/trt_decoder/trt_decoder.cpp): AI decoder plugin · `libs/qec/lib/decoders/plugins/trt_decoder/trt_decoder.cpp`
- [Real-time pipeline](https://github.com/nvidia/cudaqx/blob/main/libs/qec/lib/realtime/realtime_pipeline.cu): CUDA QEC pipeline · Latency-sensitive syndrome-to-result execution path. · `libs/qec/lib/realtime/realtime_pipeline.cu`
- [CQR decoding server](https://github.com/nvidia/cudaqx/blob/main/libs/qec/lib/realtime/decoding-server-cqr/DecodingServer.cpp): RPC service · Session and transport layer for real-time decoding. · `libs/qec/lib/realtime/decoding-server-cqr/DecodingServer.cpp`

### Quantum solvers

- [VQE, ADAPT & QAOA](https://github.com/nvidia/cudaqx/blob/main/libs/solvers/include/cudaq/solvers/vqe.h): solver workflows · Builds variational quantum algorithms over operators and optimizers. · `libs/solvers/include/cudaq/solvers/vqe.h`
- [PySCF chemistry driver](https://github.com/nvidia/cudaqx/blob/main/libs/solvers/lib/operators/molecule/drivers/pyscf_driver.cpp): optional integration · Supplies molecular inputs through PySCF. · `libs/solvers/lib/operators/molecule/drivers/pyscf_driver.cpp`

### Python packages

- [cudaq_qec package](https://github.com/nvidia/cudaqx/blob/main/libs/qec/python/cudaq_qec/__init__.py): Python facade · `libs/qec/python/cudaq_qec/__init__.py`
- [cudaq_solvers package](https://github.com/nvidia/cudaqx/blob/main/libs/solvers/python/cudaq_solvers/__init__.py): Python facade · `libs/solvers/python/cudaq_solvers/__init__.py`

### Other components

- **CUDA-Q runtime**: foundational runtime · Execution substrate for hybrid quantum-classical workloads.

## Connections

- Root build → Core extension APIs: builds
- Root build → QEC code & noise model: builds
- Root build → VQE, ADAPT & QAOA: builds
- Core extension APIs → Tensor implementations: supports
- QEC code & noise model → Detector error model: defines inputs for
- Detector error model → DEM construction: constructed by
- Detector error model → GPU DEM sampling: sampled on GPU
- DEM construction → Decoder API & loader: provides decoding input
- GPU DEM sampling → Decoder API & loader: provides syndromes
- Decoder API & loader → PyMatching decoder: loads
- Decoder API & loader → TensorRT decoder: loads
- Real-time pipeline → Decoder API & loader: dispatches decoders
- CQR decoding server → Real-time pipeline: serves requests through
- Decoding-server executable → CQR decoding server: hosts
- Decoding-server image → Decoding-server executable: deploys
- cudaq_qec package → QEC code & noise model: exposes
- cudaq_qec package → Real-time pipeline: accesses
- PySCF chemistry driver → VQE, ADAPT & QAOA: provides molecular inputs
- VQE, ADAPT & QAOA → CUDA-Q runtime: observes kernels on
- cudaq_solvers package → VQE, ADAPT & QAOA: exposes
- QEC code & noise model → Core extension APIs: uses shared abstractions
- VQE, ADAPT & QAOA → Core extension APIs: uses shared abstractions
- Real-time pipeline → CUDA-Q runtime: executes with