Repository navigation
CUDA-Q QEC 0.9.0
CUDA-Q QEC 0.9.0 introduces the Decoding Server, a pluggable reference application for real-time decoding on the CUDA-Q platform that you can run as shipped or use as a starting point for your own. Alongside it come decoding task graphs for composing decoders into pipelines. It is also a big release for the nv-qldpc-decoder, which gains two brand-new decoding algorithms and a faster version of its existing Relay BP decoding.
The most notable changes are:
- Decoding Server. CUDA-Q QEC 0.6 put GPU-accelerated decoders inside the control loop, but each user still had to write their own C++ to load decoders, manage buffers, and answer the controller. The Decoding Server is a reference implementation of that: one process, configured by one YAML file, that speaks one documented wire format. Switching decoders is a configuration edit, and you can add your own through the CUDA-Q QEC C++ decoder plugin interface. It ships as the
cudaq-decodingcontainer (nvcr.io/nvidia/quantum/cudaq-decoding) for x86-64 and arm64 with CUDA 12 and CUDA 13 variants. - Decoding task graphs. A decoding task graph composes decoders into a pipeline (windows, streaming decoders, pre-decoders, ensembles) described in YAML or built in code, and the Decoding Server serves it directly. Graphs are driven by dynamic detector error models, so one configuration serves a shot of any length. Parallel-window decoding decodes two interleaved layers of overlapping windows in parallel while syndromes are still arriving, so the response after the final round waits only for the last windows (contributed by @tlshannon, @eliotheinrich, @vedika-saravanan and @melody-ren).
- Two new decoding algorithms: Trajectory-Calibrated BP (TCBP) and Jittered OSD Beam Search (JOBS). Both are introduced in the NVIDIA Research article TCBP-JOBS: GPU-Accelerated Quantum Error Correction Decoding and Noise Learning with Near-Optimal Accuracy and are available in the
nv-qldpc-decoder. TCBP is a lightweight learned predecoder that turns BP's belief trajectories into a calibrated probability for each error mechanism, and JOBS is a GPU-parallel OSD post-processor that uses those probabilities to search many candidate corrections at once. With them you can decode surface, color and bivariate-bicycle circuits at near-optimal accuracy on a single GPU, either one shot at a time with millisecond-scale latency or in large batches for simulation studies. You can also post-select on a per-shot confidence score from JOBS, and learn the rate of every error mechanism from detector data alone with the new noise-learning workflow. The article reports up to 4.5x lower logical error rates and up to 13,000x faster decoding than a state-of-the-art most-likely-error search decoder; see it and the TCBP-JOBS performance study for more details. - Real-time Ising color-code decoding. A new color-code demo decodes the NVIDIA Ising superdense color-code memory experiment in the Decoding Server, with Chromobius alone or with the Ising AI predecoder in front of Chromobius, by replaying Stim-generated syndromes through the new playback emulator (contributed by @eliotheinrich).
- Faster Relay BP. The
nv-qldpc-decoderRelay BP GPU kernels were optimized for both the single-trajectory and gamma-ensemble paths. Results are bit-identical to 0.8 in repeatable mode. Each BP iteration is 1.3x to 3.2x faster for single-trajectory decoding and 1.1x to 3.5x faster for gamma ensembles across the GPUs measured (contributed by @ivanbasov).
Please check out the docs and examples for how to get started using CUDA-Q QEC.
Dependency note: CUDA-Q QEC 0.9.0 depends on CUDA-Q 0.17.
Rebuild required: the decoder plugin interface changed in this release (see Breaking Changes). Out-of-tree decoder plugins built against 0.8.x must be recompiled.
Features and Enhancements (QEC) 🎉
Decoding Server
- Add the Decoding Server release image, a multi-stage build that ships only compiled binaries and their runtime dependencies, by @anjbur in #798.
- Add transport-agnostic bridge providers, one ring per decoder, and mixed host +
device_graphdispatch by @bmhowe23 in #682. - Cut
HOST_CALLlatency ~10x (direct dispatch + bounded spin-then-block) by @cketcham2333 in #750, then serveHOST_CALLrequests inline on the dispatcher thread by @cketcham2333 in #769. - Add
--host-loop=threaded|unifiedto choose how each host-dispatch ring is consumed;unifiedruns CUDA-Q realtime's single-thread host loop with no pump threads by @cketcham2333 in #842. - Add the
MESSAGE_FORMAT.mdbyte-level wire-format reference forenqueue_syndromes,get_correctionsandreset_decoderby @bmhowe23 in #830. - Add a
get_logical_measurementsRPC that releases each corrected logical value as soon as it is final, so a mid-circuit readout is available mid-shot;get_correctionsnow returns corrections only by @tlshannon in #906. - Accept a raw Stim DEM in the server YAML, enabling Chromobius on the Decoding Server, and pass the observable and detector matrices to decoders at construction (
decoder_init) by @melody-ren in #765. - Export the configuration JSON Schema from an installation with
decoding_server --export-schema(and a C entry point), reflecting exactly the plugins that installation has, by @ivanbasov in #878. - Add an offline validator for Decoding Server YAML configurations that needs no GPU and no
cudaq_qecinstall by @ivanbasov in #877. - Add
memory-experiment-generator, a command-line tool that writes a ready-to-serve YAML configuration for surface-code memory experiments (distance, rounds, basis, decoder, window geometry, patch count) by @vedika-saravanan in #869. - Add the
realtime_decoding_demoexample, which drives the Decoding Server from an FPGA or a QPU kernel, by @cketcham2333 in #703. - Build the Decoding Server without CUDA-Q by @bmhowe23 in #806, with plain
ubuntu:24.04build-environment Dockerfiles for the decoders-only and Decoding Server builds by @bmhowe23 in #815. - Use YAML as the single source of truth for
gpu_roceparameters by @melody-ren in #789. - Rename the GPU-side transceiver software from
hololinktogpu_roce/GpuRoceTransceiver, and the FPGA-facing side tohsb, by @cketcham2333 in #754.
Playback emulator
- Add the playback emulator, a tool (CLI and
cudaq_qec.playbackPython API) that replays a scripted, precisely timed sequence of decoder RPCs against a decoding session and reports per-event status, responses and timing, by @eliotheinrich in #805, with a CPU RoCE session backend in #834 and an API cleanup in #849. - Add a real-time Ising color-code decoding demo (Chromobius, and Ising predecoder + Chromobius) driven by the playback emulator by @eliotheinrich in #844.
- Add a SIFL demo with a per-round decoder plugin orchestrated through the playback emulator by @eliotheinrich in #841.
Decoding task graphs
- Add the decoding task graph: composable node/edge decode pipelines with window, streaming, XOR, pre-decoder and ensemble nodes, synchronous and asynchronous streaming,
task_graphblocks in the decoder YAML,syndrome_mappingrows withenqueue_syndromes_mapped(), and Python bindings by @tlshannon in #864. - Add parallel-window decoding by @tlshannon: window model and configuration (#871), serial reference and data artifact store (#872), sparse window models and the window decode step (#873), the
ingestanddecode_windownodes and theparallel_windowpattern (#880), and executor, Decoding Server and surface-code integration (#885). - Extend the task graph executor for parallel-window decoding: per-record contexts with in-order retirement, shared persistent workers, fire pools for stateless nodes (
max_in_flight), indexed joins, andasync_num_workersby @eliotheinrich in #870. - Speed up asynchronous parallel-window decoding 2-4x in throughput with a lower final-round tail, and add windowed executions to
benchmark-qec-decoder, by @tlshannon in #893. - Stream a native decoder over rounds of different widths (for example a memory experiment whose preparation and readout rounds differ from the bulk round) by @tlshannon in #898.
- Add chunked DEM support (
dem_chunks) to decoder configuration: a DEM is described as per-round phases with a repeating bulk, so one configuration serves any round count, by @tlshannon in #847, building on the dynamic DEM infrastructure in #759. - Add cancellation semantics to decoders (
cancellation_source/cancellation_tokenand adecode(syndrome, token)overload) for orchestrating ensembles under deadlines by @eliotheinrich in #833, with a registration point for custom ensemble patterns in #891. - Build task-graph chunk models sparsely (faster graph setup for long shots) and validate individual phase widths by @vedika-saravanan in #889.
Decoders
- Make
decode/decode_batchtake NumPy syndromes directly (any bool, integer or floating-point dtype) and copy large batch results on several threads, removing about a second of host-side conversion for a 16384 x 1728 batch, by @bmhowe23 in #887. - Add a multi-output TensorRT decoder contract for observables and residual detectors by @tlshannon in #838.
- Add the
cudaq_qec.plugins.nv_qldpcPython package (TCBP model setup and noise learning for thenv-qldpc-decoder) by @bmhowe23 in #897, and named option presets (nv_qldpc.preset(name, **overrides)) in #925. - Make
realtime_pipelineown its host dispatch loop, so the PyMatching predecoder and FPGA predecoder bridge examples build and run again, by @cketcham2333 in #888. - Emit
int32bounds in the exported configuration schema and reject a negativecuda_device_idat parse time by @ivanbasov in #876.
nv-qldpc-decoder Updates (Closed Source)
New features and options
- Trajectory-Calibrated BP (TCBP) — a soft reweighting predecoder. A small model, fitted once per code family from simulated data with
cudaq_qec.plugins.nv_qldpc.init_tcbp_model(no experimental training set needed), maps each mechanism's BP trajectory to a calibrated error probability. Enabled with thetcbp_modeloption; withuse_osd=Falsethe decoder returns the calibrated probabilities, and withosd_init_method="tcbp"they order the columns for OSD or JOBS. See the TCBP-JOBS performance study and thenv-qldpc-decoderoption reference. - Jittered OSD Beam Search (JOBS) — a GPU-parallel OSD post-processor selected with
osd_method=4, tuned with thejobs_*options. It can also return a per-shot confidence signal (opt_results={"jobs_gap": True}) for post-selection. Named presets (tcbp-jobs,tcbp-jobs-sc,tcbp-jobs-sc-gap) bundle matching BP, TCBP and JOBS settings. The options and presets are listed in thenv-qldpc-decoderoption reference. - Noise learning —
cudaq_qec.plugins.nv_qldpc.learn_noiselearns the rate of every error mechanism on the GPU from detector outcomes alone (no logical labels, no prior knowledge of the noise), inper_mechanism,tiedorparametricmode. On the[[144,12,12]]bivariate-bicycle code withsi1000noise, decoding with the learned rates gives an observed logical error rate 1.00x to 1.05x that of the true rates and up to ~30x lower than a uniform prior (numbers TBR).init_tcbp_modelandlearn_noiseacceptscipy.sparsematrices. See Noise Learning and Trajectory-Calibrated BP and the noise-learning performance study. - Sparsified OSD —
osd_sparsifyruns OSD on a prefix of the ordered columns instead of all of them (sized withosd_sparsify_padorosd_sparsify_exact), which makes OSD much faster when few columns are needed. A newopt_resultsentrykstarreports the prefix size per shot. - Cancellation (@eliotheinrich) — the decoder and its GPU kernels honor the new decoder cancellation token, so an ensemble member can stop early once another member has answered.
Performance
- Relay BP kernel optimization (@ivanbasov) — optimized GPU kernels for single-syndrome sequential Relay BP and for gamma-ensemble Relay BP (
gamma_ensemble_size2, 4, 8). Results are bit-identical to 0.8 in repeatable mode. Measured on bivariate-bicycle codes across five GPU types (GB200, H100, A100, L40S, RTX PRO 6000 Blackwell), each BP iteration is 1.3x to 3.2x faster for single-trajectory decoding (1.7x to 3.1x on GB200) and 1.1x to 3.5x faster for gamma ensembles.relay_solutionsrecording benefits as well. No options change.
Correctness fixes
- Fix the int32 overflow in OSD setup and dense GPU BP when detectors × mechanisms exceeds 2^31 (#821; first released in 0.8.1) (@eliotheinrich).
- Fix an illegal memory access when
decode()is called afterdecode_batch()on a decoder that had already rundecode()(@eliotheinrich). - Raise an exception on CUDA errors (for example an out-of-memory from a too-large
bp_batch_size) instead of exiting the process, so a caller can retry with a smaller batch (@ivanbasov). - Fix Relay BP decodes failing with
invalid argumentwhen several decoder instances with different model sizes are used in one process (@vedika-saravanan).
nv-fusion-decoder Updates (Closed Source)
- Real-time shots of any length, ended by
FINAL(@tlshannon) — thebrickwallstrategy now decodes long shots through a fixed-size rolling window when the model allows it, so memory is bounded by the window rather than the shot length, with observables identical to a finite brickwall over the whole shot. Compared with 0.8, this uses up to 5x less memory and gives 30-60% lower end-of-shot latency. When shot lengths repeat, an open-ended shot gets the same latency as a fixed-length one. - Report committed rounds to streaming task graphs, so a graph can publish corrections for the rounds the decoder has already committed (@tlshannon).
- Improve streaming throughput by no longer rescanning every node on each round (@tlshannon).
Bug Fixes 🐛
- Reject wrong-length syndromes with
ValueErrorinstead of aborting the process, in every C++ decoder in this repository, by @kvmto in #894. - Stop shipping a duplicate
libcudaq-qec-decoders.soin the wheels, which let two copies with separate global state load into one process, by @bmhowe23 in #857. - Capture a decoder's CUDA decode graph only for
device_graphdispatch sessions, fixing a Decoding Server startup failure withdispatch: host, by @bmhowe23 in #829. - Fix multi-logical decoding over per-decoder rings and request-id collisions by @bmhowe23 in #751.
- Guard
device_graphdispatch against GPUs below compute capability 9.0 by @bmhowe23 in #752. - Fix
DeviceGraphRingConsumerstartup leaks and honor the factory's null-on-failure contract by @kaiqiy-nv in #933. - Fix pair-noise
ndarrayvalidation inerror_pairs_noise_model(a stacked(N, 2, 2)array is now accepted and(N, 2)rejected) by @kaiqiy-nv in #831. - Task graph fixes: retire staged deltas in round order so a large record cannot overflow the output stager, by @vedika-saravanan in #890; preserve metering and delivery order in coalesced asynchronous input (#910), preserve aggregate closure in asynchronous snapshots (#912), and reject overlapping
decode_windowcontributors at graph construction (#914) by @melody-ren; report only a native decoder's committed rounds in streaming coverage by @tlshannon in #926. - Fix three playback-emulator CLI bugs (unreported CSV write failures, ignored
--lead-in, unvalidated Stim noise probabilities) by @melody-ren in #916. - Raise
RuntimeErrorfor a failure while running andValueErrorfor a rejected argument incudaq_qec.plugins.nv_qldpcby @ivanbasov in #918. - Allow 180 s for
nv-qldpc-decoderto reach READY inrealtime_decoding_demo(first-use JIT on compute capability 12.x GPUs) by @cketcham2333 in #930. - Fix CMake generation failures when
CUDA_TARGET_ARCHSis set explicitly by @melody-ren in #915. - Fix 32-bit truncation of the element count in
cudaqx::tensorfor shapes with more than 2^31 elements, which under-allocated storage for very large dense matrices and surfaced asxbuffer_storage not resizable(the root cause behind part of #821) by @melody-ren in #864.
Breaking Changes & Deprecations ⚠️
- Supplying
Ono longer selects observable output (#765): an observable matrix is now model data only. Decoders that previously returned observable flips wheneverOwas given (PyMatching,nv-qldpc-decoder,nv-fusion-decoder) return an error frame unless you ask for observables explicitly:get_decoder(name, H, O=O, output="observables")in Python, ordecode_result_type::observablesin C++. - Decoder plugin interface (#765, #838, #864): model data now arrives through
decoder_init, the creator's requested-output parameter changes fromstd::optional<decode_result_type>tostd::optional<decoder_output_request>, anddecodergainsround_typeand a virtualenqueue_syndrome(ptr, len, round_type). Out-of-tree decoder plugins must be updated and recompiled; a plugin built against 0.8.x will not load. Directget_decoder(...)callers are largely source-compatible. Python is unaffected. nv-fusion-decoder:fusion_strategy="sliding-window"is now rejected, because"brickwall"rolls on its own.- Relay BP device-graph walkthrough removed (#892): the
realtime_relay_bpdocs page and itsgpu_roce_qldpc_graph_decoder_bridgetooling required an archive that no release ships, and have been removed. inproc_rpcremoved (#768): the in-process RPC session for real-time decoding is removed, along with theCUDAQ_QEC_REALTIME_MODEenvironment variable. Use the Decoding Server or the direct-call path instead.- Container image names (#896): images are now also published as
ghcr.io/nvidia/cudaq-qecandcudaq-qec-dev. Thecudaqxandcudaqx-devnames remain for this release and will be deprecated in a future one.
Documentation ✏️
- Add the Decoding Server User Guide for the prebuilt Docker image (configuration, playback, CUDA-Q and third-party clients, custom decoder plugins, troubleshooting) by @vedika-saravanan in #686, with an image-path correction by @anjbur in #938.
- Rewrite the task graph and dynamic DEM documentation, adding Task Graph Parallel Window and Task Graph Reference pages, by @tlshannon in #907.
- Expand the task graph ensemble documentation (cancellation, candidate sinks, selection strategies) by @eliotheinrich in #917.
- Add playback emulator documentation and a runnable demo by @eliotheinrich in #850.
- Document the all-threads
DEVICE_CALLhandler contract by @cketcham2333 in #862.
Common / Misc
CUDA-Q version alignment
- Bump the CUDA-Q dependency to 0.17 by @anjbur in #922.
- Adopt the two-pointer
DEVICE_CALLhandler ABI by @cketcham2333 in #853, thecudaq_dispatcher_set_bridgeAPI by @Renaud-K in #854, and the removal of the host graph launch fields by @cketcham2333 in #882 (also #861). - Adapt to CUDA-Q build changes: target-backend setter and GPU server stubs by @tlshannon in #846 (follow-up #852), CMake import fixes by @bmhowe23 in #848 and #859, nvJitLink for cudaq-realtime in #895, and
RTLD_LOCALloading in #900 and #902. - Consolidate realtime dependency building by @Renaud-K in #794.
- Address deprecation warnings surfaced by the nightly build by @bmhowe23 in #879.
- CUDA-Q commit bumps (#845, #866).
Licensing
- Replace the Contributor License Agreement with DCO sign-off, update
NOTICE, and move source headers to the two-line SPDX form by @anjbur in #837.
CI / images / wheels
- Add a PR license-header check by @anjbur in #804.
- Release image fixes:
libibverbsupgrade and bundled test data (#923), base-image security updates and rdma-core alignment (#929), GHCR credentials (#928) by @anjbur. - Wheel and build workflow fixes by @anjbur: #813, #814, #863, #875, #886, #913, #924; release test script updates by @kaiqiy-nv in #919.
- Smoke-test the offline config validator against installed libraries by @ivanbasov in #881.
Tests
- Add a verified HSB playback-loop regression by @vedika-saravanan in #824.
- Fix a flaky windowed-graph allocation test by @eliotheinrich in #911; skip nv-qldpc TCBP tests when no GPU is present by @anjbur in #909.
New Contributors
- @ivanbasov made their first contribution in #876
Full Changelog: 0.8.1...0.9.0