CUDA-Q QEC C++ API

using cudaq::qec::float_t = float

struct decoder_result

Decoder results.

Public Members

bool converged = false: Whether or not the decoder converged.

std::vector<float_t> result: Vector of length block_size with soft probabilities of errors in each index.

class decoder : public cudaqx::extension_point<decoder, const cudaqx::tensor<uint8_t>&, const cudaqx::heterogeneous_map&>

The decoder base class should be subclassed by specific decoder implementations. The heterogeneous_map provides a placeholder for arbitrary constructor parameters that can be unique to each specific decoder.

Public Functions

decoder(const cudaqx::tensor<uint8_t> &H)

Constructor.

Parameters:: H – Decoder’s parity check matrix represented as a tensor. The tensor is required be rank 2 and must be of dimensions syndrome_size x block_size. will use the same H.

virtual decoder_result decode(const std::vector<float_t> &syndrome) = 0

Decode a single syndrome.

Parameters:: syndrome – A vector of syndrome measurements where the floating point value is the probability that the syndrome measurement is a |1>. The length of the syndrome vector should be an integer multiple of the decoder’s syndrome_size.
Returns:: Vector of length block_size with soft probabilities of errors in each index.

virtual decoder_result decode(const cudaqx::tensor<uint8_t> &syndrome)

Decode a single syndrome.

Parameters:: syndrome – An order-1 tensor of syndrome measurements where a 1 bit represents that the syndrome measurement is a |1>. The length of the syndrome vector should be an integer multiple of the decoder’s syndrome_size.
Returns:: Vector of length block_size of errors in each index.

virtual std::future<decoder_result> decode_async(const std::vector<float_t> &syndrome)

Decode a single syndrome.

Parameters:: syndrome – A vector of syndrome measurements where the floating point value is the probability that the syndrome measurement is a |1>.
Returns:: std::future of a vector of length block_size with soft probabilities of errors in each index.

virtual std::vector<decoder_result> decode_multi(const std::vector<std::vector<float_t>> &syndrome)

Decode multiple independent syndromes (may be done in serial or parallel depending on the specific implementation)

Parameters:: syndrome – A vector of N syndrome measurements where the floating point value is the probability that the syndrome measurement is a |1>.
Returns:: 2-D vector of size N x block_size with soft probabilities of errors in each index.

inline virtual ~decoder(): Destructor.

Public Static Functions

static std::unique_ptr<decoder> get(const std::string &name, const cudaqx::tensor<uint8_t> &H, const cudaqx::heterogeneous_map &param_map = cudaqx::heterogeneous_map()): This get overload supports default values.

struct patch

Represents a logical qubit patch for quantum error correction.

This type is for CUDA-Q kernel code only.

This structure defines a patch of qubits used in quantum error correction codes. It consists of data qubits and ancilla qubits for X and Z stabilizer measurements.

Public Members

cudaq::qview data: View of the data qubits in the patch.

cudaq::qview ancx: View of the ancilla qubits used for X stabilizer measurements.

cudaq::qview ancz: View of the ancilla qubits used for Z stabilizer measurements.

class steane : public cudaq::qec::code 

Steane code implementation.

Public Functions

steane(const heterogeneous_map&): Constructor for the Steane code.

class repetition : public cudaq::qec::code 

Implementation of the repetition quantum error correction code.

Public Functions

repetition(const heterogeneous_map&): Constructs a repetition code instance.

class code : public cudaqx::extension_point<code, const heterogeneous_map&>

Base class for quantum error correcting codes in CUDA-Q.

This class provides the core interface and functionality for implementing quantum error correcting codes in CUDA-Q. It defines the basic operations that any QEC code must support and provides infrastructure for syndrome measurement and error correction experiments.

To implement a new quantum error correcting code:

Create a new class that inherits from code
Implement the protected virtual methods:
Define quantum kernels for each required logical operation (these are the fault tolerant logical operation implementations)
Register the operations in your constructor using the operation_encodings map on the base class
Register your new code type using CUDAQ_REGISTER_TYPE

Example implementation:

__qpu__ void x_kernel(patch p);
__qpu__ void z_kernel(patch p);
class my_code : public qec::code {
protected:
  std::size_t get_num_data_qubits() const override { return 7; }
  std::size_t get_num_ancilla_qubits() const override { return 6; }
  std::size_t get_num_ancilla_x_qubits() const override { return 3; }
  std::size_t get_num_ancilla_z_qubits() const override { return 3; }

public:
  my_code(const heterogeneous_map& options) : code() {
    // Can use user-specified options, e.g. auto d =
    options.get<int>("distance");
    operation_encodings.insert(std::make_pair(operation::x, x_kernel));
    operation_encodings.insert(std::make_pair(operation::z, z_kernel));
    // Register other required operations...

    // Define the default stabilizers!
    m_stabilizers = qec::stabilizers({"XXXX", "ZZZZ"});
  }

  CUDAQ_EXTENSION_CUSTOM_CREATOR_FUNCTION(
    my_code,
    static std::unique_ptr<qec::code> create(const heterogeneous_map
&options) { return std::make_unique<my_code>(options);
    }
  )
};

CUDAQ_REGISTER_TYPE(my_code)

Supported quantum operations for error correcting codes

Subclassed by cudaq::qec::repetition::repetition, cudaq::qec::steane::steane

Public Types

using one_qubit_encoding = cudaq::qkernel<void(patch)>: Type alias for single qubit quantum kernels.

using two_qubit_encoding = cudaq::qkernel<void(patch, patch)>: Type alias for two qubit quantum kernels.

using stabilizer_round = cudaq::qkernel<std::vector<cudaq::measure_result>(patch, const std::vector<std::size_t>&, const std::vector<std::size_t>&)>: Type alias for stabilizer measurement kernels.

using encoding = std::variant<one_qubit_encoding, two_qubit_encoding, stabilizer_round>: Type alias for quantum operation encodings.

Public Functions

virtual std::size_t get_num_data_qubits() const = 0

Get the number of physical data qubits needed for the code.

Returns:: Number of data qubits

virtual std::size_t get_num_ancilla_qubits() const = 0

Get the total number of ancilla qubits needed.

Returns:: Total number of ancilla qubits

virtual std::size_t get_num_ancilla_x_qubits() const = 0

Get number of ancilla qubits needed for X stabilizer measurements.

Returns:: Number of X-type ancilla qubits

virtual std::size_t get_num_ancilla_z_qubits() const = 0

Get number of ancilla qubits needed for Z stabilizer measurements.

Returns:: Number of Z-type ancilla qubits

cudaqx::tensor<uint8_t> get_parity() const

Get the full parity check matrix H = (Hx | Hz)

Returns:: Tensor representing the parity check matrix

cudaqx::tensor<uint8_t> get_parity_x() const

Get the X component of the parity check matrix.

Returns:: Tensor representing Hx

cudaqx::tensor<uint8_t> get_parity_z() const

Get the Z component of the parity check matrix.

Returns:: Tensor representing Hz

cudaqx::tensor<uint8_t> get_pauli_observables_matrix() const

Get Lx stacked on Lz.

Returns:: Tensor representing pauli observables

cudaqx::tensor<uint8_t> get_observables_x() const

Get the Lx observables.

Returns:: Tensor representing Lx

cudaqx::tensor<uint8_t> get_observables_z() const

Get the Lz observables.

Returns:: Tensor representing Lz

inline const std::vector<cudaq::spin_op> &get_stabilizers() const

Get the stabilizer generators.

Returns:: Reference to stabilizers

inline bool contains_operation(operation op) const: Return true if this code contains the given operation encoding.

Public Static Functions

static std::unique_ptr<code> get(const std::string &name, const std::vector<cudaq::spin_op> &stabilizers, const heterogeneous_map options = {})

Factory method to create a code instance with specified stabilizers.

Parameters:

name – Name of the code to create
stabilizers – Stabilizer generators for the code
options – Optional code-specific configuration options

Returns:

Unique pointer to created code instance

static std::unique_ptr<code> get(const std::string &name, const heterogeneous_map options = {})

Factory method to create a code instance.

Parameters:

name – Name of the code to create
options – Optional code-specific configuration options

Returns:

Unique pointer to created code instance

enum class cudaq::qec::operation

Enum describing all supported logical operations.

Values:

enumerator x: Logical X gate.

enumerator y: Logical Y gate.

enumerator z: Logical Z gate.

enumerator h: Logical Hadamard gate.

enumerator s: Logical S gate.

enumerator cx: Logical controlled-X gate.

enumerator cy: Logical controlled-Y gate.

enumerator cz: Logical controlled-Z gate.

enumerator stabilizer_round: Stabilizer measurement round.

enumerator prep0: Prepare logical |0⟩ state.

enumerator prep1: Prepare logical |1⟩ state.

enumerator prepp: Prepare logical |+⟩ state.

enumerator prepm: Prepare logical |-⟩ state.

std::tuple<cudaqx::tensor<uint8_t>, cudaqx::tensor<uint8_t>> cudaq::qec::sample_code_capacity(const cudaqx::tensor<uint8_t> &H, std::size_t numShots, double error_probability)

Sample syndrome measurements with code capacity noise.

Parameters:

H – Parity check matrix of a QEC code
numShots – Number of measurement shots
error_probability – Probability of bit flip on data

Returns:

Tuple containing syndrome measurements and data qubit measurements

std::tuple<cudaqx::tensor<uint8_t>, cudaqx::tensor<uint8_t>> cudaq::qec::sample_code_capacity(const cudaqx::tensor<uint8_t> &H, std::size_t numShots, double error_probability, unsigned seed)

Sample syndrome measurements with code capacity noise.

Parameters:

H – Parity check matrix of a QEC code
numShots – Number of measurement shots
error_probability – Probability of bit flip on data
seed – RNG seed for reproducible experiments

Returns:

Tuple containing syndrome measurements and data qubit measurements

std::tuple<cudaqx::tensor<uint8_t>, cudaqx::tensor<uint8_t>> cudaq::qec::sample_code_capacity(const code &code, std::size_t numShots, double error_probability)

Sample syndrome measurements with code capacity noise.

Parameters:

code – QEC Code to sample
numShots – Number of measurement shots
error_probability – Probability of bit flip on data

Returns:

Tuple containing syndrome measurements and data qubit measurements

std::tuple<cudaqx::tensor<uint8_t>, cudaqx::tensor<uint8_t>> cudaq::qec::sample_code_capacity(const code &code, std::size_t numShots, double error_probability, unsigned seed)

Sample syndrome measurements with code capacity noise.

Parameters:

code – QEC Code to sample
numShots – Number of measurement shots
error_probability – Probability of bit flip on data
seed – RNG seed for reproducible experiments

Returns:

Tuple containing syndrome measurements and data qubit measurements

std::tuple<cudaqx::tensor<uint8_t>, cudaqx::tensor<uint8_t>> cudaq::qec::sample_memory_circuit(const code &code, std::size_t numShots, std::size_t numRounds = 1)

Sample syndrome measurements starting from |0⟩ state.

Parameters:

numShots – Number of measurement shots
numRounds – Number of stabilizer measurement rounds

Returns:

Tuple containing syndrome measurements and data qubit measurements (mz for z basis state prep, mx for x basis)

std::tuple<cudaqx::tensor<uint8_t>, cudaqx::tensor<uint8_t>> cudaq::qec::sample_memory_circuit(const code &code, std::size_t numShots, std::size_t numRounds, cudaq::noise_model &noise)

Sample syndrome measurements from |0⟩ state with noise.

Parameters:

numShots – Number of measurement shots
numRounds – Number of stabilizer measurement rounds
noise – Noise model to apply

Returns:

Tuple containing syndrome measurements and data qubit measurements (mz for z basis state prep, mx for x basis)

std::tuple<cudaqx::tensor<uint8_t>, cudaqx::tensor<uint8_t>> cudaq::qec::sample_memory_circuit(const code &code, operation statePrep, std::size_t numShots, std::size_t numRounds = 1)

Sample syndrome measurements from the memory circuit.

Parameters:

statePrep – Initial state preparation operation
numShots – Number of measurement shots
numRounds – Number of stabilizer measurement rounds

Returns:

Tuple containing syndrome measurements and data qubit measurements (mz for z basis state prep, mx for x basis)

std::tuple<cudaqx::tensor<uint8_t>, cudaqx::tensor<uint8_t>> cudaq::qec::sample_memory_circuit(const code &code, operation statePrep, std::size_t numShots, std::size_t numRounds, cudaq::noise_model &noise)

Sample syndrome measurements with circuit-level noise.

Parameters:

statePrep – Initial state preparation operation
numShots – Number of measurement shots
numRounds – Number of stabilizer measurement rounds
noise – Noise model to apply

Returns:

Tuple containing syndrome measurements and data qubit measurements (mz for z basis state prep, mx for x basis)