Skip to content

0.9.0

Latest

Choose a tag to compare

@bmhowe23 bmhowe23 released this 16 Nov 15:56
· 1 commit to releases/v0.9.0 since this release
74e5e07

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-decoding container (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-decoder Relay 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_graph dispatch by @bmhowe23 in #682.
  • Cut HOST_CALL latency ~10x (direct dispatch + bounded spin-then-block) by @cketcham2333 in #750, then serve HOST_CALL requests inline on the dispatcher thread by @cketcham2333 in #769.
  • Add --host-loop=threaded|unified to choose how each host-dispatch ring is consumed; unified runs CUDA-Q realtime's single-thread host loop with no pump threads by @cketcham2333 in #842.
  • Add the MESSAGE_FORMAT.md byte-level wire-format reference for enqueue_syndromes, get_corrections and reset_decoder by @bmhowe23 in #830.
  • Add a get_logical_measurements RPC that releases each corrected logical value as soon as it is final, so a mid-circuit readout is available mid-shot; get_corrections now 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_qec install 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_demo example, 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.04 build-environment Dockerfiles for the decoders-only and Decoding Server builds by @bmhowe23 in #815.
  • Use YAML as the single source of truth for gpu_roce parameters by @melody-ren in #789.
  • Rename the GPU-side transceiver software from hololink to gpu_roce/GpuRoceTransceiver, and the FPGA-facing side to hsb, by @cketcham2333 in #754.

Playback emulator

  • Add the playback emulator, a tool (CLI and cudaq_qec.playback Python 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_graph blocks in the decoder YAML, syndrome_mapping rows with enqueue_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 ingest and decode_window nodes and the parallel_window pattern (#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, and async_num_workers by @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_token and a decode(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_batch take 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_qldpc Python package (TCBP model setup and noise learning for the nv-qldpc-decoder) by @bmhowe23 in #897, and named option presets (nv_qldpc.preset(name, **overrides)) in #925.
  • Make realtime_pipeline own its host dispatch loop, so the PyMatching predecoder and FPGA predecoder bridge examples build and run again, by @cketcham2333 in #888.
  • Emit int32 bounds in the exported configuration schema and reject a negative cuda_device_id at 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 the tcbp_model option; with use_osd=False the decoder returns the calibrated probabilities, and with osd_init_method="tcbp" they order the columns for OSD or JOBS. See the TCBP-JOBS performance study and the nv-qldpc-decoder option reference.
  • Jittered OSD Beam Search (JOBS) — a GPU-parallel OSD post-processor selected with osd_method=4, tuned with the jobs_* 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 the nv-qldpc-decoder option reference.
  • Noise learning — cudaq_qec.plugins.nv_qldpc.learn_noise learns the rate of every error mechanism on the GPU from detector outcomes alone (no logical labels, no prior knowledge of the noise), in per_mechanism, tied or parametric mode. On the [[144,12,12]] bivariate-bicycle code with si1000 noise, 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_model and learn_noise accept scipy.sparse matrices. See Noise Learning and Trajectory-Calibrated BP and the noise-learning performance study.
  • Sparsified OSD — osd_sparsify runs OSD on a prefix of the ordered columns instead of all of them (sized with osd_sparsify_pad or osd_sparsify_exact), which makes OSD much faster when few columns are needed. A new opt_results entry kstar reports 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_size 2, 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_solutions recording 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 after decode_batch() on a decoder that had already run decode() (@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 argument when 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) — the brickwall strategy 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 ValueError instead of aborting the process, in every C++ decoder in this repository, by @kvmto in #894.
  • Stop shipping a duplicate libcudaq-qec-decoders.so in 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_graph dispatch sessions, fixing a Decoding Server startup failure with dispatch: host, by @bmhowe23 in #829.
  • Fix multi-logical decoding over per-decoder rings and request-id collisions by @bmhowe23 in #751.
  • Guard device_graph dispatch against GPUs below compute capability 9.0 by @bmhowe23 in #752.
  • Fix DeviceGraphRingConsumer startup leaks and honor the factory's null-on-failure contract by @kaiqiy-nv in #933.
  • Fix pair-noise ndarray validation in error_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_window contributors 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 RuntimeError for a failure while running and ValueError for a rejected argument in cudaq_qec.plugins.nv_qldpc by @ivanbasov in #918.
  • Allow 180 s for nv-qldpc-decoder to reach READY in realtime_decoding_demo (first-use JIT on compute capability 12.x GPUs) by @cketcham2333 in #930.
  • Fix CMake generation failures when CUDA_TARGET_ARCHS is set explicitly by @melody-ren in #915.
  • Fix 32-bit truncation of the element count in cudaqx::tensor for shapes with more than 2^31 elements, which under-allocated storage for very large dense matrices and surfaced as xbuffer_storage not resizable (the root cause behind part of #821) by @melody-ren in #864.

Breaking Changes & Deprecations ⚠️

  • Supplying O no longer selects observable output (#765): an observable matrix is now model data only. Decoders that previously returned observable flips whenever O was 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, or decode_result_type::observables in C++.
  • Decoder plugin interface (#765, #838, #864): model data now arrives through decoder_init, the creator's requested-output parameter changes from std::optional<decode_result_type> to std::optional<decoder_output_request>, and decoder gains round_type and a virtual enqueue_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. Direct get_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_bp docs page and its gpu_roce_qldpc_graph_decoder_bridge tooling required an archive that no release ships, and have been removed.
  • inproc_rpc removed (#768): the in-process RPC session for real-time decoding is removed, along with the CUDAQ_QEC_REALTIME_MODE environment 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-qec and cudaq-qec-dev. The cudaqx and cudaqx-dev names 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_CALL handler contract by @cketcham2333 in #862.

Common / Misc

CUDA-Q version alignment

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

Tests

New Contributors

Full Changelog: 0.8.1...0.9.0