Added bundled decoder_context struct for measurement extraction (#671)

<!--
Thanks for contributing to CUDA-Q Libraries!

Please read the full Pull Request Guidelines in Contributing.md:

https://github.com/NVIDIA/cudaqx/blob/main/Contributing.md#pull-request-guidelines
-->

## Description

In order to process enqueued syndromes, the decoder needs access to a
measurement map so it knows how to form detectors. Right now, this comes
from `generate_timelike_sparse_detector_matrix`, which does not include
boundary detectors.

Rather than refactor this function (which would require it to be aware
of the stabilizer structure of the code), I include the `m2d` map
calculated by `dem_from_kernel`, and bundle it into a new struct
`decoder_context`, and provide a new helper function
`decoder_context_from_memory_circuit` with a similar signature to
`dem_from_memory_circuit`, which it essentially supersedes. This new
function returns the DEM as well as the measurement map needed by the
decoder. The `decoder_context` struct also provides helper methods for
extracting the X/Z components, alleviating the need for helper functions
(in the style of `*_dem_from_memory_circuit`) as well as allowing a
single circuit analysis to provide both the X and Z decoder contexts.

The PR also applies some changes to the `real_time_complete`
documentation examples to use this function.

New tests:

`test_dem.py::test_decoder_context_from_memory_circuit_requires_noise_model`
- asserts a throw on the `decoder_context_from_memory_circuit` if no
noise model is provided
`test_dem.py::test_decoder_context_and_components` - asserts that
`decoder_context_from_memory_circuit` matches output of superceded
`*_dem_from_memory_circuit`
`test_dem.py::test_decoder_context_d_sparse_layout()` - asserts that
`.d_sparse()` on `decoder_context` flattens m2d map into correct
-1-terminated sparse vector
`test_dem.py::test_decoder_context_single_type_code_empty_component` -
check that empty component (i.e. x-component of a repetition code) is
consistent
`test_qec_stim.cpp::checkTealtimeDecodeFromMemoryCircuit` - end-to-end
check of realtime API using decoder_context
`test_qec_stim.cpp::checkDecoderContextAndComponents` - Verify DEM
output by `decoder_context_from_memory_circuit` matches superseded
`*_dem_from_memory_circuit`, and that extracting `x/z` components is
idempotent and consistent.

## Runtime / performance impact

N/A

## Self-review checklist

Please confirm each item before requesting review. Check `[x]` or strike
through and explain.

### Before requesting review
- [x] I reviewed my own full diff in GitHub or my editor.
- [x] PR is in Draft if it is not yet ready for review.
- [x] Temporary / debugging changes have been removed.
- [x] Local test logs reviewed; no unexplained warnings or errors.
- [x] CI logs reviewed; no unexplained warnings or errors.
- [x] Full CI has been run.

### Scope and size
- [x] PR is under ~1000 lines, or an exception is justified in the
description.
- [x] Refactoring-only changes are isolated in their own PR(s).
- [x] No existing tests were disabled or modified just to make this PR
pass
      (if so, an issue has been raised).

### Tests
- [x] New functionality has new tests.
- [x] Tests fail if the new functionality is broken (including crashes),
not
      just when it is missing.
- [x] Negative tests added where exceptions are expected.
- [x] Truth data added where simple `EXPECT_*` / `assert` checks are
      insufficient for algorithmic correctness.
- [x] CI runtime impact considered; team notified if significant.

### Documentation
- [x] Public-facing APIs have Doxygen docs.
- [x] User-visible behavior changes have public docs, or a follow-up is
      tracked.

### Code style
- [x] Naming follows the existing convention (`snake_case` vs
`camelCase`) for
      the area being modified.

### Dependencies
- [x] No new third-party dependencies, **or** the team has been notified
and
      OSRB tickets filed.

---------

Signed-off-by: Eliot Heinrich <eheinrich@nvidia.com>
Signed-off-by: Eliot Heinrich <38039898+eliotheinrich@users.noreply.github.com>

Author: eliotheinrich

docs/sphinx/api/qec/cpp_api.rst

@@ -30,9 +30,13 @@ Detector Error Model
 .. doxygenstruct:: cudaq::qec::detector_error_model
     :members:
 
+.. doxygenstruct:: cudaq::qec::decoder_context
+    :members:
+
 .. doxygenfunction:: cudaq::qec::dem_from_memory_circuit(const code &, operation, std::size_t, cudaq::noise_model &, bool)
 .. doxygenfunction:: cudaq::qec::x_dem_from_memory_circuit(const code &, operation, std::size_t, cudaq::noise_model &, bool)
 .. doxygenfunction:: cudaq::qec::z_dem_from_memory_circuit(const code &, operation, std::size_t, cudaq::noise_model &, bool)
+.. doxygenfunction:: cudaq::qec::decoder_context_from_memory_circuit(const code &, operation, std::size_t, cudaq::noise_model &, bool)
 .. doxygenfunction:: cudaq::qec::dem_from_stim_text(const std::string &, bool)
 
 Decoder Interfaces

docs/sphinx/api/qec/python_api.rst

@@ -29,9 +29,13 @@ Detector Error Model
 .. autoclass:: cudaq_qec.DetectorErrorModel
     :members:
 
+.. autoclass:: cudaq_qec.DecoderContext
+    :members:
+
 .. autofunction:: cudaq_qec.dem_from_memory_circuit
 .. autofunction:: cudaq_qec.x_dem_from_memory_circuit
 .. autofunction:: cudaq_qec.z_dem_from_memory_circuit
+.. autofunction:: cudaq_qec.decoder_context_from_memory_circuit
 .. autofunction:: cudaq_qec.dem_from_stim_text
 
 Decoder Interfaces

docs/sphinx/examples/qec/cpp/real_time_complete.cpp

@@ -28,8 +28,9 @@
 
 // [Begin Save DEM]
 // Save decoder configuration to YAML file
-void save_dem(const cudaq::qec::detector_error_model &dem,
+void save_dem(const cudaq::qec::decoder_inputs &inputs,
               const std::string &filename) {
+  const auto &dem = inputs.dem;
   // Create decoder config
   cudaq::qec::decoding::config::decoder_config config;
   config.id = 0;
@@ -38,12 +39,7 @@ void save_dem(const cudaq::qec::detector_error_model &dem,
   config.syndrome_size = dem.num_detectors();
   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);
-
-  // Calculate numRounds from DEM (we send 1 additional round, so add 1)
-  uint64_t numSyndromesPerRound = 2; // Z0Z1 and Z1Z2
-  auto numRounds = dem.num_detectors() / numSyndromesPerRound + 1;
-  config.D_sparse = cudaq::qec::generate_timelike_sparse_detector_matrix(
-      numSyndromesPerRound, numRounds, false);
+  config.D_sparse = cudaq::qec::d_sparse(inputs.m2d);
 
   // Decoder parameters are a plain heterogeneous_map; keys are governed by
   // the parameter schema the decoder registered.
@@ -120,14 +116,21 @@ __qpu__ int64_t qec_circuit() {
     cudaq::qec::decoding::enqueue_syndromes(0, syndromes);
   }
 
+  // Final data readout
+  std::vector<cudaq::measure_result> data_meas = {mz(data[0]), mz(data[1]),
+                                                  mz(data[2])};
+  cudaq::qec::decoding::enqueue_syndromes(0, data_meas);
+  std::vector<bool> result = cudaq::to_bools(data_meas);
+
   // Get corrections and apply them (single logical observable)
-  auto corrections = cudaq::qec::decoding::get_corrections(0, 1);
+  std::vector<bool> corrections = cudaq::qec::decoding::get_corrections(0, 1);
+  result[0] = static_cast<bool>(result[0]) ^ static_cast<bool>(corrections[0]);
   if (corrections[0]) {
     for (std::size_t i = 0; i < 3; ++i)
       cudaq::x(data[i]);
   }
 
-  return cudaq::to_integer(cudaq::to_bools(mz(data)));
+  return cudaq::to_integer(result);
 }
 // [End QEC Circuit]
 
@@ -141,17 +144,17 @@ int main() {
   cudaq::noise_model noise;
   noise.add_all_qubit_channel("x", cudaq::depolarization2(0.01), 1);
 
-  auto dem = cudaq::qec::z_dem_from_memory_circuit(
+  auto ctx = cudaq::qec::decoder_context_from_memory_circuit(
       *code, cudaq::qec::operation::prep0, 3, noise);
   // [End DEM Generation]
 
-  save_dem(dem, "config.yaml");
+  save_dem(ctx.full_component(), "config.yaml");
 
   // Step 2: Load config and run circuit
   printf("\nStep 2: Running circuit with decoding...\n");
   load_dem("config.yaml");
 
-  cudaq::run(10, qec_circuit);
+  cudaq::run(10, noise, qec_circuit);
   printf("Ran 10 shots\n");
 
   cudaq::qec::decoding::config::finalize_decoders();

docs/sphinx/examples/qec/python/real_time_complete.py

@@ -63,14 +63,19 @@ def qec_circuit() -> int:
     for _ in range(3):
         syndromes = measure_stabilizers(logical)
         qec.enqueue_syndromes(0, syndromes, 0)
+    # Final data readout
+    data_meas = [mz(data[0]), mz(data[1]), mz(data[2])]
+    qec.enqueue_syndromes(0, data_meas, 0)
+    result = cudaq.to_bools(data_meas)
 
     # Get corrections and apply them (single logical observable)
     corrections = qec.get_corrections(0, 1, False)
+    result[0] ^= corrections[0]
     if corrections[0]:
         for i in range(3):
             x(data[i])
 
-    return cudaq.to_integer(cudaq.to_bools(mz(data)))
+    return cudaq.to_integer(result)
 
 
 # [End QEC Circuit]
@@ -88,7 +93,9 @@ def main():
     noise = cudaq.NoiseModel()
     noise.add_all_qubit_channel("x", cudaq.Depolarization2(0.01), 1)
 
-    dem = qec.z_dem_from_memory_circuit(code, qec.operation.prep0, 3, noise)
+    ctx = qec.decoder_context_from_memory_circuit(code, qec.operation.prep0, 3,
+                                                  noise)
+    dem, m2d, m2o = ctx.full_component()
     # [End DEM Generation]
 
     # [Begin Save DEM]
@@ -101,12 +108,7 @@ def main():
     config.H_sparse = qec.pcm_to_sparse_vec(dem.detector_error_matrix)
     config.O_sparse = qec.pcm_to_sparse_vec(dem.observables_flips_matrix)
 
-    # Calculate numRounds from DEM (we send 1 additional round, so add 1)
-    num_syndromes_per_round = 2  # Z0Z1 and Z1Z2
-    num_rounds = dem.detector_error_matrix.shape[
-        0] // num_syndromes_per_round + 1
-    config.D_sparse = qec.generate_timelike_sparse_detector_matrix(
-        num_syndromes_per_round, num_rounds, False)
+    config.D_sparse = qec.d_sparse(m2d)
     # Decoder parameters are a plain dict; keys are governed by the parameter
     # schema the decoder registered (see qec.decoder_param_schema).
     config.decoder_custom_args = {"lut_error_depth": 2}
@@ -128,7 +130,7 @@ def main():
     qec.configure_decoders_from_file("config.yaml")
     # [End Load DEM]
 
-    run_result = cudaq.run(qec_circuit, shots_count=10)
+    run_result = cudaq.run(qec_circuit, shots_count=10, noise_model=noise)
     print("Ran 10 shots")
 
     qec.finalize_decoders()

libs/qec/include/cudaq/qec/experiments.h

@@ -7,9 +7,10 @@
  ******************************************************************************/
 #pragma once
 
+#include "cudaq/algorithms/dem.h"
 #include "cudaq/qec/code.h"
 #include "cudaq/qec/detector_error_model.h"
-#include <tuple>
+#include <cstddef>
 #include <vector>
 
 namespace cudaq::qec {
@@ -159,6 +160,53 @@ std::tuple<cudaqx::tensor<uint8_t>, cudaqx::tensor<uint8_t>>
 sample_memory_circuit(const code &code, std::size_t numShots,
                       std::size_t numRounds, cudaq::noise_model &noise);
 
+/// @brief Finalized decoder inputs: a canonicalized DEM and measurement maps.
+struct decoder_inputs {
+  detector_error_model dem;
+  cudaq::M2DSparseMatrix m2d;
+  cudaq::M2OSparseMatrix m2o;
+};
+
+/// @brief Lazy handle returned by `decoder_context_from_memory_circuit`.
+///
+/// Stores the raw (uncanonicalized) circuit analysis. Call a component method
+/// to canonicalize exactly the stabilizer type needed and obtain a
+/// `decoder_inputs`:
+///   - `x_component()` — X-stabilizer detectors only
+///   - `z_component()` — Z-stabilizer detectors only
+///   - `full_component()` — both stabilizer types, boundary-aware
+struct decoder_context {
+  /// @brief Total number of measurements per shot (column count of m2d/m2o).
+  std::size_t num_measurements() const;
+
+  /// @brief Canonicalize X-stabilizer detectors; return decoder_inputs.
+  decoder_inputs x_component() const;
+
+  /// @brief Canonicalize Z-stabilizer detectors; return decoder_inputs.
+  decoder_inputs z_component() const;
+
+  /// @brief Canonicalize both stabilizer types with boundary awareness;
+  /// return decoder_inputs.
+  decoder_inputs full_component() const;
+
+private:
+  cudaq::M2DSparseMatrix m2d_;
+  cudaq::M2OSparseMatrix m2o_;
+  detector_error_model dem_;
+  std::size_t num_rounds_ = 0;
+  std::size_t num_x_stabilizers_ = 0;
+  std::size_t num_z_stabilizers_ = 0;
+  bool fixed_basis_is_z_ = false;
+
+  friend decoder_context
+  decoder_context_from_memory_circuit(const code &, operation, std::size_t,
+                                      cudaq::noise_model &, bool);
+};
+
+/// @brief Flatten an M2DSparseMatrix into the `-1`-terminated sparse vector a
+/// realtime decoder config expects for its `D_sparse`.
+std::vector<std::int64_t> d_sparse(const cudaq::M2DSparseMatrix &m2d);
+
 /// @brief Given a memory circuit setup, generate a DEM
 /// @param code QEC Code to sample
 /// @param statePrep Initial state preparation operation
@@ -167,10 +215,11 @@ sample_memory_circuit(const code &code, std::size_t numShots,
 /// @param decompose_errors If true, hyperedge error mechanisms are decomposed
 ///        into pairs of two-detector edges by Stim before returning.
 /// @return Detector error model
-cudaq::qec::detector_error_model
-dem_from_memory_circuit(const code &code, operation statePrep,
-                        std::size_t numRounds, cudaq::noise_model &noise,
-                        bool decompose_errors = false);
+detector_error_model dem_from_memory_circuit(const code &code,
+                                             operation statePrep,
+                                             std::size_t numRounds,
+                                             cudaq::noise_model &noise,
+                                             bool decompose_errors = false);
 
 /// @brief Given a memory circuit setup, generate a DEM for X stabilizers.
 /// @param code QEC Code to sample
@@ -199,4 +248,13 @@ detector_error_model z_dem_from_memory_circuit(const code &code,
                                                std::size_t numRounds,
                                                cudaq::noise_model &noise,
                                                bool decompose_errors = false);
+
+/// @brief Run a memory-circuit analysis and return a lazy handle.
+///
+/// Executes `dem_from_kernel` once and stores the raw result. Call
+/// `x_component()`, `z_component()`, or `full_component()` on the returned
+/// handle to canonicalize exactly the stabilizer type needed.
+decoder_context decoder_context_from_memory_circuit(
+    const code &code, operation statePrep, std::size_t numRounds,
+    cudaq::noise_model &noise, bool decompose_errors = false);
 } // namespace cudaq::qec