Renamed decoder_context structs

Signed-off-by: Eliot Heinrich <eheinrich@nvidia.com>

Author: eliotheinrich

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

@@ -28,9 +28,9 @@
 
 // [Begin Save DEM]
 // Save decoder configuration to YAML file
-void save_dem(const cudaq::qec::decoder_context &ctx,
+void save_dem(const cudaq::qec::decoder_inputs &inputs,
               const std::string &filename) {
-  const auto &dem = ctx.dem;
+  const auto &dem = inputs.dem;
   // Create decoder config
   cudaq::qec::decoding::config::decoder_config config;
   config.id = 0;
@@ -39,7 +39,7 @@ void save_dem(const cudaq::qec::decoder_context &ctx,
   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);
-  config.D_sparse = cudaq::qec::d_sparse(ctx.m2d);
+  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.

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

@@ -161,7 +161,7 @@ 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_context {
+struct decoder_inputs {
   detector_error_model dem;
   cudaq::M2DSparseMatrix m2d;
   cudaq::M2OSparseMatrix m2o;
@@ -171,23 +171,23 @@ struct decoder_context {
 ///
 /// Stores the raw (uncanonicalized) circuit analysis. Call a component method
 /// to canonicalize exactly the stabilizer type needed and obtain a
-/// `decoder_context`:
+/// `decoder_inputs`:
 ///   - `x_component()` — X-stabilizer detectors only
 ///   - `z_component()` — Z-stabilizer detectors only
 ///   - `full_component()` — both stabilizer types, boundary-aware
-struct decoder_context_handle {
+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_context.
-  decoder_context x_component() const;
+  /// @brief Canonicalize X-stabilizer detectors; return decoder_inputs.
+  decoder_inputs x_component() const;
 
-  /// @brief Canonicalize Z-stabilizer detectors; return decoder_context.
-  decoder_context z_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_context.
-  decoder_context full_component() const;
+  /// return decoder_inputs.
+  decoder_inputs full_component() const;
 
 private:
   cudaq::M2DSparseMatrix m2d_;
@@ -198,7 +198,7 @@ struct decoder_context_handle {
   std::size_t num_z_stabilizers_ = 0;
   bool fixed_basis_is_z_ = false;
 
-  friend decoder_context_handle
+  friend decoder_context
   decoder_context_from_memory_circuit(const code &, operation, std::size_t,
                                       cudaq::noise_model &, bool);
 };
@@ -254,7 +254,7 @@ detector_error_model z_dem_from_memory_circuit(const code &code,
 /// 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_handle decoder_context_from_memory_circuit(
+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

libs/qec/lib/experiments.cpp

@@ -440,7 +440,7 @@ namespace details {
 /// (dem, m2d, m2o). For the full (both-basis) case the boundary-aware
 /// canonicalization is used; for a single-type selection the layout is uniform
 /// so the simpler overload suffices.
-static decoder_context
+static decoder_inputs
 make_component(detector_error_model dem, cudaq::M2DSparseMatrix m2d,
                cudaq::M2OSparseMatrix m2o, std::size_t num_rounds,
                std::size_t num_x_stabilizers, std::size_t num_z_stabilizers,
@@ -513,9 +513,11 @@ std::vector<std::int64_t> d_sparse(const cudaq::M2DSparseMatrix &m2d) {
   return out;
 }
 
-decoder_context_handle decoder_context_from_memory_circuit(
-    const code &code, operation statePrep, std::size_t numRounds,
-    cudaq::noise_model &noise, bool decompose_errors) {
+decoder_context decoder_context_from_memory_circuit(const code &code,
+                                                    operation statePrep,
+                                                    std::size_t numRounds,
+                                                    cudaq::noise_model &noise,
+                                                    bool decompose_errors) {
   if (numRounds == 0)
     throw std::runtime_error(
         "dem_from_memory_circuit error - numRounds must be >= 1. The memory "
@@ -556,7 +558,7 @@ decoder_context_handle decoder_context_from_memory_circuit(
 
   cudaq::dem_options dem_opts;
   dem_opts.decompose_errors = decompose_errors;
-  decoder_context_handle result;
+  decoder_context result;
   auto dem_text = cudaq::dem_from_kernel(
       memory_circuit, &noise, dem_opts, result.m2d_, result.m2o_, stabRound,
       prep, numData, numAncx, numAncz, numRounds, xVec, zVec, obs_flat, num_obs,
@@ -569,25 +571,25 @@ decoder_context_handle decoder_context_from_memory_circuit(
   return result;
 }
 
-std::size_t decoder_context_handle::num_measurements() const {
+std::size_t decoder_context::num_measurements() const {
   return m2d_.num_measurements;
 }
 
-decoder_context decoder_context_handle::x_component() const {
+decoder_inputs decoder_context::x_component() const {
   return details::make_component(dem_, m2d_, m2o_, num_rounds_,
                                  num_x_stabilizers_, num_z_stabilizers_,
                                  fixed_basis_is_z_, /*keep_x=*/true,
                                  /*keep_z=*/false);
 }
 
-decoder_context decoder_context_handle::z_component() const {
+decoder_inputs decoder_context::z_component() const {
   return details::make_component(dem_, m2d_, m2o_, num_rounds_,
                                  num_x_stabilizers_, num_z_stabilizers_,
                                  fixed_basis_is_z_, /*keep_x=*/false,
                                  /*keep_z=*/true);
 }
 
-decoder_context decoder_context_handle::full_component() const {
+decoder_inputs decoder_context::full_component() const {
   return details::make_component(dem_, m2d_, m2o_, num_rounds_,
                                  num_x_stabilizers_, num_z_stabilizers_,
                                  fixed_basis_is_z_, /*keep_x=*/true,

libs/qec/python/bindings/py_code.cpp

@@ -697,20 +697,19 @@ void bindCode(nb::module_ &mod) {
       nb::arg("code"), nb::arg("op"), nb::arg("numShots"), nb::arg("numRounds"),
       nb::arg("noise") = nb::none());
 
-  nb::class_<decoder_context_handle>(qecmod, "DecoderContext",
-                                     R"pbdoc(
+  nb::class_<decoder_context>(qecmod, "DecoderContext",
+                              R"pbdoc(
       Lazy handle returned by ``decoder_context_from_memory_circuit``.
 
       Stores the raw circuit analysis. Each *_component method canonicalizes
       exactly the requested stabilizer type and returns a ``(dem, m2d, m2o)``
       tuple.
     )pbdoc")
-      .def_prop_ro("num_measurements",
-                   &decoder_context_handle::num_measurements,
+      .def_prop_ro("num_measurements", &decoder_context::num_measurements,
                    "Total number of measurements per shot.")
       .def(
           "x_component",
-          [](const decoder_context_handle &h) {
+          [](const decoder_context &h) {
             auto ctx = h.x_component();
             return nb::make_tuple(ctx.dem, ctx.m2d.rows, ctx.m2o.rows);
           },
@@ -722,7 +721,7 @@ void bindCode(nb::module_ &mod) {
     )pbdoc")
       .def(
           "z_component",
-          [](const decoder_context_handle &h) {
+          [](const decoder_context &h) {
             auto ctx = h.z_component();
             return nb::make_tuple(ctx.dem, ctx.m2d.rows, ctx.m2o.rows);
           },
@@ -734,7 +733,7 @@ void bindCode(nb::module_ &mod) {
     )pbdoc")
       .def(
           "full_component",
-          [](const decoder_context_handle &h) {
+          [](const decoder_context &h) {
             auto ctx = h.full_component();
             return nb::make_tuple(ctx.dem, ctx.m2d.rows, ctx.m2o.rows);
           },
@@ -761,8 +760,10 @@ void bindCode(nb::module_ &mod) {
        whose XOR forms detector ``d``. Each detector's indices are emitted in
        order, followed by -1.
 
-       This is a standalone helper for ``dem_from_kernel`` consumers who hold
-       an m2d map but not a full ``DecoderContext``.
+       This is a standalone helper for consumers who hold an m2d map (e.g.,
+       extracted from a ``decoder_inputs`` returned by a component method)
+       and want to build the D_sparse vector without going through a
+       ``DecoderContext``.
     )pbdoc",
       nb::arg("m2d"));
 

libs/qec/python/tests/test_dem.py

@@ -756,7 +756,7 @@ def test_decoder_context_from_memory_circuit_requires_noise_model():
 
 
 def test_decoder_context_and_components():
-    # decoder_context_from_memory_circuit returns a memory_circuit_handle;
+    # decoder_context_from_memory_circuit returns a decoder_context;
     # canonicalization is deferred until a component method is called.
     # full_component() matches dem_from_memory_circuit;
     # x_component() / z_component() reproduce x_/z_dem_from_memory_circuit.

libs/qec/unittests/backend-specific/stim/test_qec_stim.cpp

@@ -593,7 +593,7 @@ void check_matrix_bits(const std::string &name,
   }
 }
 
-// End-to-end realtime decode driven by the memory_circuit_handle API,
+// End-to-end realtime decode driven by the decoder_context API,
 // built from a full-basis CSS memory circuit. Steane's boundary is
 // inhomogeneous: only the fixed (Z) stabilizers carry boundary detectors while
 // interior rounds carry both types. The measurement
@@ -627,7 +627,7 @@ TEST(QECCodeTester, checkRealtimeDecodeFromMemoryCircuit) {
   }
   EXPECT_LT(minRow, maxRow);
 
-  // Configure the realtime decoder entirely from the decoder context.
+  // Configure the realtime decoder from the decoder_inputs returned by full_component().
   auto decoder =
       cudaq::qec::get_decoder("single_error_lut", dem.detector_error_matrix);
   decoder->set_O_sparse(
@@ -660,7 +660,7 @@ bool tensors_equal(const cudaqx::tensor<uint8_t> &a,
 }
 } // namespace
 
-// decoder_context_from_memory_circuit returns a memory_circuit_handle;
+// decoder_context_from_memory_circuit returns a decoder_context;
 // canonicalization is deferred until a component method is called. Verify that
 // full_component() matches dem_from_memory_circuit and that x_component() /
 // z_component() reproduce x_/z_dem_from_memory_circuit and partition the