Real-time quantum error correction decoding server from CUDA-Q QEC, compatible with the CUDA-Q toolchain, with worked examples.
NVIDIA CUDA-Q QEC Decoding Server
The CUDA-Q Decoding Server is a standalone, real-time quantum error correction decoding service from the CUDA-Q QEC library. A CUDA-Q program streams syndrome measurements to the server and receives corrections back, over UDP for development and testing, or over RDMA (RoCE) from an FPGA-attached ConnectX NIC in a real-time deployment. This container provides:
decoding_server, with the pymatching, chromobius, TensorRT and lookup-table decoders, and the NVIDIA QLDPC GPU decoder where included- The CUDA-Q runtime and the NVQ++ compiler, so programs that decode against the server can be written, compiled and run inside the container
- The syndrome playback and tools for emulating the FPGA data path
- Worked examples under
~/examples, with a build script and run instructions
Prerequisites
Using the container requires the host system to have the following installed:
Docker Engine
NVIDIA GPU Drivers (instructions for datacenters)
For the RDMA data path: an NVIDIA ConnectX NIC with its drivers, and the container started with access to the RDMA devices (--privileged, or--device /dev/infinibandwith the required capabilities)
For supported versions, see the release notes. No other installation, compilation, or dependency management is required.
Running the Decoding Server
The image is available built for CUDA 13 and for CUDA 12. Adjust the tags in the following commands to select a version compatible with your driver. To pull the container image built for CUDA 13 with Docker, enter the command:
docker pull nvcr.io/nvidia/quantum/cudaq-decoding:cu13-<VERSION>
To run an interactive container with Docker, enter the command:
docker run --gpus all -it nvcr.io/nvidia/quantum/cudaq-decoding:cu13-<VERSION>
The container opens a shell in a directory containing the examples and a README. To build and run the first example against the server:
cd ~/examples && ./build.sh
./build/surface_code-1-local --distance 3 --num_rounds 3 --num_shots 200
This is the one-process flow: the program decodes in-process, with no server involved, which is the quickest way to confirm the container works. Each example also has a -cqr variant whose decoding calls go over the realtime channel to a separately running decoding_server.
The README describes that two-process flow, in which the program writes a decoder
configuration from its detector error model and a separately started
decoding_server serves it, as well as syndrome replay and the hardware path.
For more information about the decoding server and real-time decoding with CUDA-Q QEC, see the CUDA-Q QEC documentation.
Additional Resources
The CUDA-Q QEC documentation and source code are hosted on GitHub. See also the CUDA-Q documentation and the NVIDIA CUDA-Q homepage.
License Agreement
CUDA-Q QEC is an open source project. The source code is available on GitHub and licensed under Apache License 2.0. This container includes CUDA-Q, also licensed under Apache License 2.0, and makes use of NVIDIA TensorRT and the NVIDIA cuQuantum SDK, which are held to their own respective licenses. Where included, the NVIDIA QLDPC decoder is proprietary NVIDIA software. For more information about licenses of included components, see the Notice.