NVIDIA CUDA-Q QEC
0.9.0

Getting Started

  • Installation Guide
    • Installation Methods
      • pip install
      • Docker Container
      • Building from Source
    • Installing PyTorch

Libraries

  • CUDA-Q QEC - Quantum Error Correction Library
    • QEC Codes
      • QEC Code Framework cudaq::qec::code
        • Class Structure
        • Implementing a New Code
        • Example: Steane Code
        • Implementing a New Code in Python
        • Key Points
        • Using the Code Framework
      • Pre-built QEC Codes
        • Steane Code
        • Repetition Code
        • Surface Code
    • QEC Decoders
      • Decoder Framework cudaq::qec::decoder
        • Class Structure
        • Migrating Existing C++ Decoder Plugins
        • Implementing a New Decoder in C++
        • Example: Lookup Table Decoder
        • Implementing a Decoder in Python
        • Key Features
        • Usage Example
      • Detector Error Model
        • Decoding from Stim DEM Text
        • DEM Sampling
        • Dynamic DEM
      • Pre-built QEC Decoders
        • Quantum Low-Density Parity-Check Decoder
        • NVIDIA Fusion Decoder
        • Tensor Network Decoder
        • TensorRT Decoder
        • PyMatching Decoder
        • Chromobius Decoder
        • Sliding Window Decoder
    • Realtime Decoding
      • Workflow
      • Terminology and Data Flow
      • Memory experiment configuration generator
      • See Also
    • Experiments and Noise Modeling
      • Code-Capacity Noise Modeling
      • Circuit-level Noise Modeling
      • Memory Circuit Experiments
    • Conventions

Examples

  • CUDA-Q QEC by Example
    • Creating New QEC Codes
    • Experiments and Noise Modeling
      • Code-Capacity Noise Modeling
        • CUDA-Q QEC Implementation
        • Code Explanation
      • Circuit-level Noise Modeling
        • CUDA-Q QEC Implementation
        • Code Explanation
      • Memory Circuit Experiments
        • Function Variants
        • Return Values
        • Example Usage
        • Additional Noise Models
    • Decoders
      • Decoding From Stim DEM Text
      • Generating a Multi-Round Parity Check Matrix
      • DEM Sampling — Monte-Carlo Sampling from Detector Error Models
        • Example
        • GPU Acceleration
        • Input Types and Backend Selection
        • See Also
      • Getting Started with the NVIDIA QLDPC Decoder
        • Belief Propagation Methods
        • Usage Example
      • Exact Maximum Likelihood Decoding with NVIDIA Tensor Network Decoder
      • Deploying AI Decoders with TensorRT
        • Overview of the Training-to-Deployment Pipeline
        • Training a Neural Network Decoder with PyTorch and Stim
        • Using the TensorRT Decoder in CUDA-Q QEC
        • Converting ONNX Models to TensorRT Engines
        • Dependencies and Requirements
        • See Also
      • Matching-Based Decoding with PyMatching
      • Color-Code Decoding with Chromobius
    • Decoding Task Graphs
      • Quick start: a sliding window
      • Decoding complete shots
      • Streaming
      • Reading results
      • Logical measurements
      • Graphs of several nodes
      • Node kinds
      • Guarded sliding windows
      • Asynchronous streaming
    • Task Graph Parallel Window
      • How it works
      • The model
      • Configuration
        • Advanced options
      • Building a graph in code
      • Decoding a shot
      • Serving with the decoding server
      • What the pattern builds
        • Sharing data across decoders
    • Task Graph Decoder Ensembles
      • How it works
      • Configuration
      • Building a graph in code
      • Extending ensembles
        • Reporting a cost
        • Honoring cancellation
        • Pushing candidates
        • Adding a selection strategy
    • Task Graph Reference
      • Asynchronous streaming options
      • Fire pools
      • Streaming results in detail
      • Staged outputs
      • Edge values
      • Logical outputs
      • Native streaming nodes
      • Arbitrary-length sliding windows
    • Realtime Decoding
      • Getting Started with Realtime Decoding
        • Configuration
        • Backend Selection
        • Compilation and Execution Examples
        • Troubleshooting
      • Decoding Server User Guide
        • Workflow at a glance
        • Prerequisites
        • Generate a memory-experiment configuration
        • Color-code-enabled AI decoder
        • CUDA-Q examples: surface-code programs
        • Use a custom decoder plugin
        • Integrate a third-party runtime
        • Troubleshooting
        • See also
      • Realtime Decoding with CUDA-Q Decoding Server
        • Deliverables versus the example
        • Building the example
        • Running
        • Ising decoder (TensorRT predecoder + PyMatching)
        • Decoders
        • The example source
      • Playback Emulator
        • Schedule Format
        • Output Format
        • Syndrome Sources
        • Sessions
        • Run Options
        • Example
      • AI Predecoder with CUDA-Q Realtime
        • Prerequisites
        • Data Directory Layout
        • Building
        • Running
        • Changing the Predecoder Model
        • Reading the Output
        • See Also
      • AI Predecoder with CUDA-Q Realtime (with FPGA Data Injection)
        • Prerequisites
        • Repository Layout
        • Data Directory Layout
        • Building
        • Emulated End-to-End Test
        • FPGA End-to-End Test
        • Changing the Predecoder Model
        • Orchestration Script Reference
        • See Also
      • Ising Color-Code Emulator with Decoding Server
        • Prerequisites
        • Running
        • Reading the Output
        • The example source
        • See Also
      • Streaming Interleaved Feed-forward Latency (SIFL)
        • Running
        • The example source
      • Dynamic DEM
        • A model
        • Detectors and seams
        • Measurements and readout
        • Building a model in code
        • See also
      • See Also

Performance Studies

  • Performance Studies
    • Improving Relay BP Decoding With Gamma Ensembles
      • Performance Comparison
      • Latency Distribution
      • Logical Error Rate Under Hard Deadlines
      • See Also
    • Sweeping Relay BP Stopping Criteria From a Single Run
      • Recording a run
      • Example: RelayBP-N on the gross code
      • Practical notes
      • See Also
    • Improving BP+OSD Decoding With Min-LLR OSD Initialization
      • Column Ordering Importance and Sensitivity
      • Experiment
      • Results
      • Controls: Ordering Versus Iteration Count
      • See Also
    • Trajectory-Calibrated BP and Jittered OSD Beam Search
      • Key Decoder Options
      • Using TCBP and JOBS
      • Comparison With Tesseract
      • Complementary-Gap Post-Selection
      • Limitations and Practical Guidance
      • References
    • Bounding Real-Time Decode Latency With NV-Fusion
      • What Is Streaming Tail Latency?
      • Experiment Configuration
      • Streaming Tail Latency
      • Latency With Concurrent Decoders
      • See Also
    • Learning Noise From Detector Data and Decoding With the Learned Rates
      • Experiment Setup
      • Step 1: Get the Circuit and Fit the TCBP Model
      • Step 2: Learn the Rates From Detector Data
      • Step 3: Decode With Each Prior
      • Learning Time and Accuracy
      • Error of the Learned Rates Versus the Number of Shots
      • Logical Error Rate Under the Three Priors
      • Choosing the Number of Passes
      • Reproducing These Results
      • See Also

API Reference

  • CUDA-Q QEC Namespaces and Core Library C++ API
    • Namespaces
    • Core
  • CUDA-Q QEC C++ API
    • Code
    • Detector Error Model
    • Dynamic DEM
    • Detector Error Model (DEM) Sampling
    • Decoder Interfaces
    • Decoding Task Graph
      • I/O types
      • Graph
    • Built-in Decoders
      • NVIDIA QLDPC Decoder
        • nv_qldpc_decoder
      • NVIDIA Fusion Decoder
        • nv_fusion_decoder
      • Sliding Window Decoder
        • sliding_window
      • TensorRT Decoder
        • trt_decoder
      • PyMatching Decoder
        • pymatching
      • Chromobius Decoder
        • chromobius
    • Realtime Decoding
      • Core Decoding Functions
      • Configuration API
      • Helper Functions
    • Realtime Pipeline API
      • Configuration
      • GPU Stage
      • CPU Stage
      • Completion
      • Ring Buffer Injector
      • Pipeline
    • Parity Check Matrix Utilities
    • Logger
    • Common
  • CUDA-Q QEC Python API
    • Code
      • Code
        • Code.contains_operation
        • Code.get_num_ancilla_qubits
        • Code.get_num_ancilla_x_qubits
        • Code.get_num_ancilla_z_qubits
        • Code.get_num_data_qubits
        • Code.get_num_x_stabilizers
        • Code.get_num_z_stabilizers
        • Code.get_observables_x
        • Code.get_observables_z
        • Code.get_operation_one_qubit
        • Code.get_operation_two_qubit
        • Code.get_parity
        • Code.get_parity_x
        • Code.get_parity_z
        • Code.get_pauli_observables_matrix
        • Code.get_stabilizer_round
        • Code.get_stabilizer_schedule_x
        • Code.get_stabilizer_schedule_z
        • Code.get_stabilizers
    • Surface code layout
      • stabilizer_grid
        • stabilizer_grid.data_coords
        • stabilizer_grid.data_indices
        • stabilizer_grid.distance
        • stabilizer_grid.format_data_grid
        • stabilizer_grid.format_stabilizer_coords
        • stabilizer_grid.format_stabilizer_grid
        • stabilizer_grid.format_stabilizer_indices
        • stabilizer_grid.format_stabilizers
        • stabilizer_grid.get_cnot_schedule_pairs_x
        • stabilizer_grid.get_cnot_schedule_pairs_z
        • stabilizer_grid.get_cnot_schedule_x
        • stabilizer_grid.get_cnot_schedule_z
        • stabilizer_grid.get_spin_op_observables
        • stabilizer_grid.get_spin_op_stabilizers
        • stabilizer_grid.grid_length
        • stabilizer_grid.orientation
        • stabilizer_grid.roles
        • stabilizer_grid.x_stab_coords
        • stabilizer_grid.x_stab_indices
        • stabilizer_grid.x_stabilizers
        • stabilizer_grid.z_stab_coords
        • stabilizer_grid.z_stab_indices
        • stabilizer_grid.z_stabilizers
    • Detector Error Model
      • DetectorErrorModel
        • DetectorErrorModel.canonicalize_for_rounds
        • DetectorErrorModel.canonicalize_for_rounds_with_boundary
        • DetectorErrorModel.detector_error_matrix
        • DetectorErrorModel.error_ids
        • DetectorErrorModel.error_rates
        • DetectorErrorModel.num_detectors
        • DetectorErrorModel.num_error_mechanisms
        • DetectorErrorModel.num_observables
        • DetectorErrorModel.observables_flips_matrix
      • DecoderContext
        • DecoderContext.full_component
        • DecoderContext.num_measurements
        • DecoderContext.x_component
        • DecoderContext.z_component
      • dem_from_memory_circuit()
      • x_dem_from_memory_circuit()
      • z_dem_from_memory_circuit()
      • decoder_context_from_memory_circuit()
      • dem_from_stim_text()
      • d_sparse()
    • Dynamic DEM
      • DemChunksSpec
        • DemChunksSpec.connections
        • DemChunksSpec.detectors_of
        • DemChunksSpec.get_phase
        • DemChunksSpec.has_D_sparse
        • DemChunksSpec.has_repeating_phase
        • DemChunksSpec.is_empty
        • DemChunksSpec.measurements_of
        • DemChunksSpec.measurements_per_round
        • DemChunksSpec.minimum_rounds
        • DemChunksSpec.num_observables
        • DemChunksSpec.num_rounds
        • DemChunksSpec.observable_names
        • DemChunksSpec.phase_sequence
        • DemChunksSpec.phases
        • DemChunksSpec.phases_supply_D_sparse
        • DemChunksSpec.repeating_phase
        • DemChunksSpec.seam
        • DemChunksSpec.validate
      • PhaseSpecEntry
        • PhaseSpecEntry.id
        • PhaseSpecEntry.spec
      • PhaseConnection
        • PhaseConnection.from_phase
        • PhaseConnection.is_self
        • PhaseConnection.to_phase
      • SeamConnection
        • SeamConnection.from_seam
        • SeamConnection.to_seam
      • DemChunkSpec
        • DemChunkSpec.D_sparse
        • DemChunkSpec.H_sparse
        • DemChunkSpec.O_sparse
        • DemChunkSpec.error_rates
        • DemChunkSpec.expand
        • DemChunkSpec.is_empty
        • DemChunkSpec.m2o_sparse
        • DemChunkSpec.num_faults
        • DemChunkSpec.num_measurements
        • DemChunkSpec.seam_specs
        • DemChunkSpec.validate
      • SeamSpecEntry
        • SeamSpecEntry.id
        • SeamSpecEntry.spec
      • DemSeamSpec
        • DemSeamSpec.H_sparse
        • DemSeamSpec.O_sparse
      • SeamId
        • SeamId.value
      • seam_name
      • phase_name
    • Decoder Interfaces
      • Decoder
        • Decoder.decode
        • Decoder.decode_async
        • Decoder.decode_batch
        • Decoder.get_block_size
        • Decoder.get_syndrome_size
        • Decoder.get_version
    • Decoding Task Graph
      • DecodingTaskGraph
        • DecodingTaskGraph.clear_corrections
        • DecodingTaskGraph.combine
        • DecodingTaskGraph.enqueue_syndrome
        • DecodingTaskGraph.from_spec
        • DecodingTaskGraph.from_topology
        • DecodingTaskGraph.get_logical_measurements
        • DecodingTaskGraph.get_num_logical_measurements
        • DecodingTaskGraph.get_num_msyn_per_decode
        • DecodingTaskGraph.get_num_msyn_per_round
        • DecodingTaskGraph.get_num_observables
        • DecodingTaskGraph.get_obs_corrections
        • DecodingTaskGraph.output_names
        • DecodingTaskGraph.reset_decoder
        • DecodingTaskGraph.run
        • DecodingTaskGraph.run_all
        • DecodingTaskGraph.run_batch
        • DecodingTaskGraph.streaming_incompatibility_reason
        • DecodingTaskGraph.streaming_result
        • DecodingTaskGraph.supports_streaming
      • TaskGraphNodeConfig
        • TaskGraphNodeConfig.d_sparse
        • TaskGraphNodeConfig.decoder_type
        • TaskGraphNodeConfig.dem
        • TaskGraphNodeConfig.ensemble
        • TaskGraphNodeConfig.h_sparse
        • TaskGraphNodeConfig.id
        • TaskGraphNodeConfig.kind
        • TaskGraphNodeConfig.max_in_flight
        • TaskGraphNodeConfig.node_params
        • TaskGraphNodeConfig.o_sparse
        • TaskGraphNodeConfig.params
        • TaskGraphNodeConfig.stim_dem
        • TaskGraphNodeConfig.windows
      • TaskGraphEnsembleSpec
        • TaskGraphEnsembleSpec.add_member
        • TaskGraphEnsembleSpec.join_params
        • TaskGraphEnsembleSpec.join_strategy
        • TaskGraphEnsembleSpec.num_members
      • TaskGraphOptions
        • TaskGraphOptions.async_coordinator_cpu
        • TaskGraphOptions.async_num_workers
        • TaskGraphOptions.async_queue_capacity
        • TaskGraphOptions.async_spin_pause_iters
        • TaskGraphOptions.async_streaming
        • TaskGraphOptions.async_worker_cpus
      • TaskGraphStreamingResult
        • TaskGraphStreamingResult.closure
        • TaskGraphStreamingResult.completed_operations
        • TaskGraphStreamingResult.error
        • TaskGraphStreamingResult.generation
        • TaskGraphStreamingResult.operation_completed
        • TaskGraphStreamingResult.outputs
        • TaskGraphStreamingResult.result_revision
        • TaskGraphStreamingResult.shot_epoch
        • TaskGraphStreamingResult.status
        • TaskGraphStreamingResult.values
      • TaskGraphOutputProgress
        • TaskGraphOutputProgress.closure
        • TaskGraphOutputProgress.coverage_begin_round
        • TaskGraphOutputProgress.coverage_end_round
        • TaskGraphOutputProgress.generation
        • TaskGraphOutputProgress.name
        • TaskGraphOutputProgress.released
        • TaskGraphOutputProgress.status
        • TaskGraphOutputProgress.value_offset
        • TaskGraphOutputProgress.value_width
      • TaskGraphStreamingStatus
      • TaskGraphClosure
      • DecoderResult
        • DecoderResult.converged
        • DecoderResult.opt_results
        • DecoderResult.result
      • BatchDecoderResult
        • BatchDecoderResult.batch_opt_results
        • BatchDecoderResult.converged
        • BatchDecoderResult.opt_results
        • BatchDecoderResult.result
      • AsyncDecoderResult
        • AsyncDecoderResult.get
        • AsyncDecoderResult.ready
      • get_decoder()
    • Built-in Decoders
      • NVIDIA QLDPC Decoder
        • nv_qldpc_decoder
        • Relay Solutions Post-Processing
      • NVIDIA Fusion Decoder
        • nv_fusion_decoder
      • Sliding Window Decoder
        • sliding_window
      • TensorRT Decoder
        • trt_decoder
      • Tensor Network Decoder
        • cudaq_qec.plugins.decoders.tensor_network_decoder.TensorNetworkDecoder
      • PyMatching Decoder
        • pymatching
      • Chromobius Decoder
        • chromobius
    • Realtime Decoding
      • Core Decoding Functions
        • cudaq_qec.qec.enqueue_syndromes()
        • cudaq_qec.qec.enqueue_syndromes_mapped()
        • cudaq_qec.qec.get_corrections()
        • cudaq_qec.qec.get_logical_measurements()
        • cudaq_qec.qec.reset_decoder()
      • Configuration API
        • Decoder Parameters
        • Deprecated Typed Configuration Classes
        • Configuration Functions
      • Helper Functions
        • cudaq_qec.pcm_to_sparse_vec()
        • cudaq_qec.pcm_from_sparse_vec()
        • cudaq_qec.d_sparse()
    • Common
      • sample_memory_circuit()
      • x_sample_memory_circuit()
      • z_sample_memory_circuit()
      • sample_code_capacity()
    • Detector Error Model (DEM) Sampling
      • dem_sampling()
    • Parity Check Matrix Utilities
      • generate_random_pcm()
      • generate_timelike_sparse_detector_matrix()
      • get_pcm_for_rounds()
      • get_sorted_pcm_column_indices()
      • pcm_extend_to_n_rounds()
      • pcm_is_sorted()
      • pcm_to_sparse_vec()
      • reorder_pcm_columns()
      • shuffle_pcm_columns()
      • simplify_pcm()
      • sort_pcm_columns()
NVIDIA CUDA-Q QEC
  • Performance Studies
  • Trajectory-Calibrated BP and Jittered OSD Beam Search
  • View page source
Previous Next

Trajectory-Calibrated BP and Jittered OSD Beam Search

Belief propagation (BP) produces more information than its final hard decision. At every iteration, it updates a marginal log-likelihood ratio (LLR) for every error mechanism. A successful BP run turns those marginals into a syndrome-consistent correction. An unsuccessful run still leaves a trajectory: which mechanisms appeared likely to be in error, when that happened, whether the estimate was stable or oscillatory, and how it was moving when BP stopped.

Conventional BP+OSD decoders [1] retain only one number from each trajectory. Most order the columns of the detector error matrix by the final LLR; minimum-LLR variants (Using Min-LLR OSD Initialization with BP+OSD) retain the minimum value reached during BP. Both give that single summary ordering to an ordered-statistics decoder (OSD), which discards valuable information. The final LLR can miss a strong signal from an earlier iteration, while a minimum LLR records the strength of an excursion but not its timing or stability. OSD then explores candidates around only that one summary ordering.

Starting in CUDA-Q QEC 0.9.0, the NV-qLDPC decoder provides two components that use this information more fully:

  • Trajectory-Calibrated BP (TCBP) is a soft reweighting predecoder. It maps each mechanism’s BP trajectory to a calibrated probability that the mechanism fired.

  • Jittered OSD Beam Search (JOBS) is a GPU-parallel OSD post-processor. It searches many perturbed column orderings and refines each OSD-0 solution with a bounded beam search.

This page summarizes how to use the two components and what to expect from them. The algorithms, the training procedure and the full evaluation are in the TCBP-JOBS research article [2].

TCBP uses AI in a deliberately lightweight form: a small neural network learns how BP trajectory shapes relate to error probabilities. Training uses simulations generated from the parity-check matrix (PCM), requires no experimental training set, and completed in under a minute in our development runs on NVIDIA GPUs. The default model has only 529 trainable weights. It is designed for reuse across physical error rates and code distances within the same code family, so one fit can support many decoding runs. The same model is what noise learning uses to estimate error rates from detector data; see Learning Noise From Detector Data and Decoding With the Learned Rates.

TCBP also works well with short BP trajectories. Every experiment in this study uses 10 BP iterations. Larger iteration counts give BP more opportunities to explore different beliefs and give TCBP a longer trajectory to interpret, at the cost of additional BP work. Because the iteration count is part of the fitted model configuration, changing it requires a matching TCBP model.

The components are useful separately, but their combination is the focus of this study. TCBP gives JOBS high-quality, syndrome-specific probability estimates, which JOBS uses to explore multiple syndrome-consistent corrections in parallel. During the search it can also retain the cheapest candidate found in every logical class, providing complementary information about the returned answer.

NV-qLDPC pipeline from BP trajectories through TCBP calibrated scores, column ordering and JOBS

TCBP is both a soft-output predecoder and a source of calibrated column scores for OSD. JOBS is the GPU-parallel hard-decoding path that consumes those scores.

Key Decoder Options

The main options selecting and tuning the TCBP path are:

  • tcbp_model supplies the model bytes returned by init_tcbp_model or the path to a saved model. Its BP method, iteration count, clipping value and processing precision must match the decoder.

  • use_osd=False returns TCBP’s soft probabilities. use_osd=True, osd_init_method="tcbp" instead uses its scores as the column ordering for OSD or JOBS.

JOBS is selected with use_osd=True, osd_method=4. Its principal search options are:

  • jobs_draws (default 16) sets the number of orderings searched per round; jobs_rounds (default 1) permits additional rounds while they continue to improve the answer.

  • jobs_draw_noise (default 1.0) sets the Gumbel perturbation applied after draw zero.

  • jobs_beam_width (default 32), jobs_beam_depth (default 40) and jobs_beam_patience (default 8) bound the search from each OSD-0 solution.

  • jobs_search_converged (default false) also searches BP-converged shots and returns the cheaper correction.

  • osd_sparsify_pad (default 8) sizes JOBS’s mandatory \(K^*\)-based window. \(K^*\) is the smallest number of leading columns of the ordering whose span contains the syndrome; JOBS searches the first \(\lceil\) osd_sparsify_pad \(\times K^*\rceil\) columns. bp_batch_size controls the shots in flight; the search’s device memory is allocated at construction for bp_batch_size * jobs_draws items.

  • opt_results={"jobs_gap": True} returns jobs_gap and jobs_gap_class for every shot. The JOBS gap is the cost, in nats, of the cheapest correction the search visited in a different logical class minus the cost of the returned correction; it is a search-limited approximation of the complementary gap, and it is +inf (class -1) when no competing class was visited. This requires an observables matrix and supports at most 12 observables.

TCBP and JOBS require the sparse GPU path (use_sparsity=True) and composition=0; JOBS supports at most 8192 detector rows and a beam width of 64. See the complete nv-qldpc-decoder option reference for Python or C++ for types, constraints and memory behavior.

Using TCBP and JOBS

The named presets encode the matching BP, TCBP and JOBS configuration. The following example fits a model for a code family, constructs a decoder that searches every shot, and requests the complementary gap:

import numpy as np
import cudaq_qec as qec
from cudaq_qec.plugins import nv_qldpc

# H: detector-error matrix
# O: observable-flips matrix
# rates: prior probability of each error mechanism
model, report = nv_qldpc.init_tcbp_model(H, return_report=True)

decoder = qec.get_decoder(
    "nv-qldpc-decoder",
    H,
    O=O,
    output="observables",
    error_rate_vec=rates,
    bp_batch_size=2048,
    **nv_qldpc.preset("tcbp-jobs-sc-gap", tcbp_model=model),
)

results = decoder.decode_batch(syndromes)
predicted = np.asarray([r.result for r in results])
gap = np.asarray([r["jobs_gap"] for r in results.opt_results])
competitor = np.asarray(
    [r["jobs_gap_class"] for r in results.opt_results])

tcbp-jobs omits search on BP-converged shots. tcbp-jobs-sc searches them without allocating the logical-class table, and tcbp-jobs-sc-gap requests both behaviors. The presets use sparse sum-product BP, 10 iterations, an LLR clip of 15, FP32 processing and repeatable execution. JOBS then uses its default search parameters unless they are overridden. The options of init_tcbp_model, its report and recommendations for fitting a model are in the Trajectory-Calibrated BP section of the API reference.

Comparison With Tesseract

We compare TCBP-JOBS with Tesseract [3], the search-based most-likely-error decoder from Google Quantum AI. Tesseract runs on CPUs, needs neither a GPU nor a fitted model, and is the accuracy reference for this study. We use its tesseract-long-beam configuration, one of the two recommended starting points in the Tesseract repository: beam width 20, 21 detector orderings, a priority-queue limit of 1,000,000, beam climbing and no detector revisits. The Tesseract measurements are the results in that repository [4] and are treated as source data rather than rerun as part of this study.

The scope of the comparison is this one configuration. Tesseract also offers a short-beam configuration and error sparsification, which trade some accuracy for speed and are not shown here, so the ratios below should not be read as applying to Tesseract in general. The results in the repository do not record the Tesseract version or the hardware they were measured on, and other versions or machines may perform differently. The research article [2] has the fuller comparison: both measurement bases, further physical error rates and additional Tesseract configurations.

The comparison uses the circuit-level SI1000 memory circuits in the tesseract-decoder repository, at physical error rate p = 0.002 in the Z basis. They cover rotated surface codes, superdense color codes and bivariate-bicycle codes over several distances. Detector error models are flattened with approximate_disjoint_errors=True. TCBP-JOBS runs with the tcbp-jobs-sc preset: sparse sum-product BP for 10 iterations with clip value 15 and FP32 processing, a TCBP model fitted from simulated data before decoding, and the default JOBS search of 16 draws, one round, beam width 32, beam depth 40, patience 8 and noise scale 1.0. With this preset JOBS searches every shot, including the shots BP converges on (jobs_search_converged=True). TCBP-JOBS decodes the same number of shots per circuit as the Tesseract results in the repository, sampled independently with Stim: the two decoders see the same distribution, not the same shots.

Accuracy is reported as shot failure probability divided by the number of syndrome-extraction rounds. For a circuit with r rounds and per-experiment logical error rate LER, the plotted value is

\[p_{\mathrm{fail,round}} = \frac{\mathrm{LER}}{r}.\]

Runtime is likewise divided by the number of rounds. TCBP-JOBS serial latency is the mean over 4,096 shots per circuit, each decoded by its own decode() call on one NVIDIA GB200. The Tesseract values are the per-shot decode times recorded in the repository’s results [4], summed over worker threads. That data is from a machine that had at least 30 active threads. Timings from an otherwise quiet machine would differ somewhat; we do not estimate by how much. The horizontal axis therefore compares one CPU thread with one whole GPU: it shows time to an answer, not performance on equivalent hardware. Batched GPU runs (decode_batch() calls of 16,384 shots) are used separately to measure logical error rate and total compute. Those aggregate GPU-hours must not be interpreted as the serial response latency shown on the horizontal axis.

The figure connects the two decoders at each code point. Filled colored markers show TCBP-JOBS on one GB200; hollow markers show the long-beam CPU result. The horizontal coordinate is time per round and the vertical coordinate is failure probability per round, so movement toward the lower left is better. An arrow therefore shows the change in both runtime and accuracy for the same circuit rather than a scaling trend across different codes.

Accuracy and latency tradeoff between TCBP plus JOBS on a GB200 and Tesseract long beam on CPUs

Failure probability and decode time per syndrome-extraction round at p = 0.002, Z basis, with TCBP-JOBS in the tcbp-jobs-sc preset. Each arrow connects the Tesseract and TCBP-JOBS result for the same circuit. The annotations report the corresponding time and error ratios; lower and farther left are better. Tesseract times are per CPU thread from the results on the tesseract-decoder repository; TCBP-JOBS times are serial latency on one GB200.

Across the 14 circuits, TCBP-JOBS stays in a narrow sub-millisecond latency band per round, while Tesseract’s time per round grows with code size, from below that band on the distance-3 surface code to several seconds on the larger bivariate-bicycle codes. The logical error rates are of the same order throughout. On two circuits the 95% intervals of the two decoders do not overlap: TCBP-JOBS has fewer failures on the distance-11 color code and more on the distance-9 color code. On the other twelve circuits the two decoders are indistinguishable at this sample size. Because the two decoders saw independent samples, a difference on a single circuit should be read together with its interval.

The compute behind the points differs as well. The TCBP-JOBS study decoded 12.0 million shots in 0.36 GB200 GPU-hours using batched execution. The long-beam results on the tesseract-decoder repository cover the same 12.0 million shots in 63,334 CPU core-hours. These totals describe the cost of collecting the data, not a hardware-normalized speed ratio: GPU-hours and CPU core-hours are different resources, the timing modes differ, and the GPU-hours count the decode calls only, not shot sampling, detector error model construction or TCBP model fitting. They do show what GPU-parallel search offers for large simulation studies: an accuracy sweep of this size fits in under an hour on one GPU.

Complementary-Gap Post-Selection

The complementary-gap experiment is separate from the Tesseract comparison. It uses the [[144,12,12]] bivariate-bicycle (gross) code at p = 0.003 and p = 0.004, with the same BP, TCBP and JOBS search settings and opt_results={"jobs_gap": True}. We sweep a minimum accepted gap and report both the fraction of shots retained and the logical error rate per shot among retained shots. At both physical error rates, increasing the threshold generally lowers the logical error rate. The trade-off is especially favorable over the first several tens of nats: many failures are concentrated among the low-gap shots, before the retained fraction begins to fall rapidly.

Logical error rate and retained-shot fraction versus minimum JOBS gap for the gross code

Post-selection with the JOBS gap for the [[144,12,12]] bivariate-bicycle code. The upper panel shows logical error rate per shot among retained shots, with 95% Wilson intervals; dashed segments are upper bounds where no retained shot failed. The lower panel shows the percentage of shots retained.

Limitations and Practical Guidance

TCBP-JOBS is a bounded learned search, not maximum-likelihood decoding. TCBP calibration depends on the training distribution and matching BP configuration. JOBS explores only its sampled orderings, window and beam, and the reported complementary gap covers only candidates it visited. Changing code families or BP settings requires validating or refitting the TCBP model; changing the JOBS budget changes both memory use and search quality.

Latency and throughput answer different deployment questions. Serial decode() measurements approximate the response time of one available syndrome, while decode_batch() measures how efficiently a study or offline workload can fill the GPU. bp_batch_size, jobs_draws and the detector-matrix dimensions determine whether the device has enough work and memory to reach its throughput regime. Results should always identify which mode was measured.

The gap should be calibrated operationally rather than treated as a universal probability. A threshold that gives a useful acceptance/error tradeoff for one code and noise regime need not transfer unchanged to another. +inf is especially important to interpret correctly: it can mean that the bounded search saw no competing class, or that the search did not run on a BP-converged shot.

Within those limits, the components form a useful hierarchy. TCBP alone exposes calibrated soft information. TCBP ordering can improve an existing OSD post-processor. TCBP-JOBS spends parallel GPU work on alternative valid corrections. Enabling search on converged shots and the complementary gap adds an all-shot confidence signal when the extra search and class-table memory are justified.

References

[1]

J. Roffe, D. R. White, S. Burton and E. T. Campbell, “Decoding across the quantum LDPC code landscape,” Phys. Rev. Research 2, 043423 (2020). doi:10.1103/PhysRevResearch.2.043423

[2] (1,2)

B. Howe, S. Maurya, J. Olle, I. Basov, M. Li, J. G. Lietz, K. Young and K. M. Svore, “TCBP-JOBS: GPU-Accelerated Quantum Error Correction Decoding and Noise Learning with Near-Optimal Accuracy,” NVIDIA Research (2026).

[3]

L. Aghababaie Beni, O. Higgott and N. Shutty, “Tesseract: A search-based decoder for quantum error correction” (2025). arXiv:2503.10988

[4] (1,2)

Results file benchmarking/sparsify_errors/aggregated_results.jsonl (error sparsification benchmarks) in the tesseract-decoder repository; the rows without error sparsification are used here.

Previous Next

© Copyright 2025, NVIDIA Corporation & Affiliates.

Built with Sphinx using a theme provided by Read the Docs.