The Real-Time Decoding API enables low-latency error correction on quantum hardware by allowing CUDA-Q quantum kernels to interact with decoders during circuit execution. This API is designed for use cases where corrections must be calculated and applied within qubit coherence times.

The real-time decoding system supports simulation environments for local testing and hardware integration (e.g., on Quantinuum’s Helios QPU).

Core Decoding Functions

These functions can be called from within CUDA-Q quantum kernels (__qpu__ functions) to interact with real-time decoders.

void cudaq::qec::decoding::enqueue_syndromes(std::uint64_t decoder_id, const std::vector<cudaq::measure_result> &syndromes, std::uint64_t tag = 0)

Enqueue syndromes for decoding.

Parameters:

decoder_id – The ID of the decoder to use.
syndromes – The syndromes to enqueue.
tag – The tag to use for the syndrome (currently useful for logging only)

std::vector<bool> cudaq::qec::decoding::get_corrections(std::uint64_t decoder_id, std::uint64_t return_size, bool reset = false)

Get the corrections for a given decoder.

Parameters:

decoder_id – The ID of the decoder to use.
return_size – The number of bits to return (in bits). This is expected to match the number of observables in the decoder.
reset – Whether to reset the decoder corrections after retrieving them.

Returns:

The corrections (detected bit flips) for the given decoder, based on all of the decoded syndromes since the last time any corrections were reset.

void cudaq::qec::decoding::reset_decoder(std::uint64_t decoder_id)

Reset the decoder. This clears any queued syndromes and resets any corrections back to 0.

Parameters:: decoder_id – The ID of the decoder to reset.

Configuration API

The configuration API enables setting up decoders before circuit execution. Decoders are configured using YAML files or programmatically constructed configuration objects.

int cudaq::qec::decoding::config::configure_decoders(multi_decoder_config &config)

Configure the decoders (multi_decoder_config variant). This function configures both local decoders, and if running on remote target hardware, will submit the configuration to the remote target for further processing.

Parameters:: config – The configuration to use.
Returns:: 0 on success, non-zero on failure.

int cudaq::qec::decoding::config::configure_decoders_from_file(const char *config_file)

Configure the decoders from a file. This function configures both local decoders, and if running on remote target hardware, will submit the configuration to the remote target for further processing.

Parameters:: config_file – The file to read the configuration from.
Returns:: 0 on success, non-zero on failure.

int cudaq::qec::decoding::config::configure_decoders_from_str(const char *config_str)

Configure the decoders from a string. This function configures both local decoders, and if running on remote target hardware, will submit the configuration to the remote target for further processing.

Parameters:: config_str – The string to read the configuration from.
Returns:: 0 on success, non-zero on failure.

void cudaq::qec::decoding::config::finalize_decoders(): Finalize the decoders. This function finalizes local decoders.

Helper Functions

Real-time decoding requires converting matrices to sparse format for efficient decoder configuration. The following utility functions are essential:

cudaq::qec::pcm_to_sparse_vec() for converting a dense PCM to a sparse PCM.

Usage in real-time decoding:

config.H_sparse = cudaq::qec::pcm_to_sparse_vec(dem.detector_error_matrix);
config.O_sparse = cudaq::qec::pcm_to_sparse_vec(dem.observables_flips_matrix);

cudaq::qec::pcm_from_sparse_vec() for converting a sparse PCM to a dense PCM.

cudaq::qec::generate_timelike_sparse_detector_matrix() for generating a sparse detector matrix.

Usage in real-time decoding:

config.D_sparse = cudaq::qec::generate_timelike_sparse_detector_matrix(
    numSyndromesPerRound, numRounds, false);

See also Parity Check Matrix Utilities for additional PCM manipulation functions.