remove verbose doc added during testing

Signed-off-by: vedika-saravanan <vsaravanan@nvidia.com>

Author: vedika-saravanan

libs/qec/include/cudaq/qec/decoder.h

@@ -30,21 +30,10 @@ using float_t = CUDAQX_QEC_FLOAT_TYPE;
 using float_t = double;
 #endif
 
-/// @brief Construction input for a decoder: either an explicit parity-check
-/// matrix (`cudaq::qec::sparse_binary_matrix`) or a Stim detector error model
-/// string (`std::string`).
-///
-/// Parity-check-matrix-based decoders (LUT, sliding_window, TRT, PyMatching,
-/// nv-qldpc, ...) accept either alternative: a DEM string is parsed into a
-/// parity-check matrix via `dem_from_stim_text`. Decoders that require the raw
-/// DEM (e.g. Chromobius, which needs detector color/basis annotations) require
-/// the string alternative and reject a bare matrix.
-///
-/// @note The factory input owns the DEM text. Public overloads accept
-/// `std::string`, `const char *`, and `std::string_view` and copy into this
-/// variant before dispatching to decoder plugins.
-using decoder_init =
-    std::variant<cudaq::qec::sparse_binary_matrix, std::string>;
+/// Decoder construction input: either a parity-check matrix or raw Stim DEM
+/// text. PCM-based decoders can accept both; DEM-native decoders can require
+/// the string alternative via `require_dem_text`.
+using decoder_init = std::variant<sparse_binary_matrix, std::string>;
 
 /// @brief Validates that all keys in a heterogeneous map are found in a list of
 /// acceptable types
@@ -195,10 +184,7 @@ class decoder
 
   /// @brief Construct a registered decoder by name.
   /// @param name The registered decoder name.
-  /// @param init Either a parity-check matrix or a Stim DEM string (see
-  /// `decoder_init`). The variant is forwarded to the decoder's creator, so
-  /// parity-check-matrix-based decoders and DEM-native decoders (Chromobius)
-  /// share a single entry point.
+  /// @param init A parity-check matrix or raw Stim DEM string.
   /// @param param_map Optional decoder-specific parameters.
   static std::unique_ptr<decoder>
   get(const std::string &name, const decoder_init &init,
@@ -530,39 +516,22 @@ get_decoder(const std::string &name, std::string_view stim_dem_text,
   return get_decoder(name, decoder_init{std::string{stim_dem_text}}, options);
 }
 
-/// @brief DEM-derived defaults; pointers alias into the source `dem`.
+/// DEM-derived defaults; pointers alias into the source `dem`.
 struct dem_default_values {
   const cudaqx::tensor<uint8_t> *O = nullptr;
   const std::vector<double> *error_rate_vec = nullptr;
 };
 
-/// @brief Return DEM defaults for any key not already supplied by the user.
-/// Shared by `make_pcm_decoder` and the Python binding.
+/// Return DEM defaults for keys not already supplied by the user.
 dem_default_values dem_defaults_for_missing_keys(
     const std::function<bool(const std::string &)> &contains_user_key,
     const detector_error_model &dem);
 
-/// @brief Extract the Stim DEM text from a `decoder_init`, throwing if it
-/// holds a parity-check matrix instead. Use this in the create() function of
-/// decoders that require a raw DEM (e.g. Chromobius), which cannot be
-/// reconstructed from a bare parity-check matrix.
+/// Extract raw Stim DEM text for DEM-native decoders.
 std::string_view require_dem_text(const decoder_init &init);
 
-/// @brief Build a parity-check-matrix-based decoder from a `decoder_init`.
-///
-/// If `init` holds a sparse matrix, it is used directly as the parity-check
-/// matrix. If it holds a Stim DEM string, it is parsed via
-/// `dem_from_stim_text` and the derived observables (`"O"`) and per-error
-/// rates (`"error_rate_vec"`) are injected into `params` unless the user
-/// already supplied them (user values win). This is the shared implementation
-/// behind the create() function of every parity-check-matrix-based decoder,
-/// giving them DEM-string support for free.
-///
-/// @note The DEM parse is lossy: detector annotations, decomposition
-/// separators, and `error_ids` are dropped. Sufficient for matching-style /
-/// parity-check-matrix decoders (LUT, NV, sliding_window, TRT, PyMatching).
-/// Decoders that need full DEM metadata (e.g. Chromobius detector color/basis)
-/// must consume the string directly via `require_dem_text`.
+/// Build a PCM-based decoder. If `init` holds DEM text, it is parsed into a PCM
+/// and DEM-derived `"O"` / `"error_rate_vec"` defaults are added when absent.
 template <typename DecoderT>
 std::unique_ptr<decoder>
 make_pcm_decoder(const decoder_init &init,
@@ -582,10 +551,8 @@ make_pcm_decoder(const decoder_init &init,
       cudaq::qec::sparse_binary_matrix(dem.detector_error_matrix), merged);
 }
 
-/// @brief Construct a decoder by name from a Stim detector error model string.
-///
 /// @deprecated Prefer `get_decoder`, which now accepts a Stim DEM string
-/// directly via `decoder_init`. Retained as a thin convenience alias.
+/// directly.
 std::unique_ptr<decoder>
 get_decoder_from_stim_dem(const std::string &name,
                           const std::string &stim_dem_text,

libs/qec/include/cudaq/qec/detector_error_model.h

@@ -66,18 +66,8 @@ struct detector_error_model {
   void canonicalize_for_rounds(uint32_t num_syndromes_per_round);
 };
 
-/// @brief Parse a Stim detector error model text into a
-/// `cudaq::qec::detector_error_model`. Each `error` instruction in the DEM
-/// becomes a single column in `detector_error_matrix` and
-/// `observables_flips_matrix`; suggested decomposition separators are
-/// folded into the same column.
-///
-/// @note Lossy: only detector/observable flips and error probabilities
-/// are extracted. Annotations (`detector`, `logical_observable`),
-/// suggested-decomposition separators, and `error_ids` are dropped.
-/// Decoders that need full DEM metadata (e.g. Chromobius detector
-/// color/basis) should consume the raw Stim DEM string via `decoder_init`
-/// and `require_dem_text` instead of this lossy representation.
+/// Parse Stim DEM text into detector/observable flip matrices and error rates.
+/// This is lossy; DEM-native decoders should consume raw DEM text instead.
 detector_error_model dem_from_stim_text(const std::string &dem_text);
 
 } // namespace cudaq::qec

libs/qec/lib/CMakeLists.txt

@@ -62,7 +62,6 @@ add_library(${LIBRARY_NAME} SHARED ${QEC_SOURCES})
 add_subdirectory(decoders/plugins/example)
 add_subdirectory(decoders/plugins/pymatching)
 
-# libstim comes from the parent build (CUDA-Q).
 if(NOT TARGET libstim)
   message(FATAL_ERROR
     "libstim target not available; required by cudaq-qec for Stim DEM parsing.")

libs/qec/lib/decoder_stim_dem.cpp

@@ -37,8 +37,6 @@ std::unique_ptr<decoder>
 get_decoder_from_stim_dem(const std::string &name,
                           const std::string &stim_dem_text,
                           const cudaqx::heterogeneous_map &options) {
-  // Retained for backward compatibility: get_decoder now accepts a Stim DEM
-  // string directly via decoder_init.
   return get_decoder(name, decoder_init{stim_dem_text}, options);
 }
 

libs/qec/lib/detector_error_model.cpp

@@ -34,7 +34,7 @@ detector_error_model dem_from_stim_text(const std::string &dem_text) {
   std::size_t instruction_index = 0;
 
   dem.iter_flatten_error_instructions([&](const stim::DemInstruction &inst) {
-    if (inst.arg_data.size() == 0)
+    if (inst.arg_data.empty())
       throw std::runtime_error(
           "Stim DEM error instruction missing probability argument (index " +
           std::to_string(instruction_index) + ")");
@@ -54,9 +54,6 @@ detector_error_model dem_from_stim_text(const std::string &dem_text) {
       } else if (target.is_observable_id()) {
         obs.push_back(static_cast<std::size_t>(target.val()));
       } else {
-        // Forward-compat tripwire; unreachable today (stim's three
-        // DemTarget categories are exhaustive -- pinned by
-        // StimDemTargetCategoriesAreExhaustive).
         throw std::runtime_error(
             "Stim DEM error instruction (index " +
             std::to_string(instruction_index) +
@@ -71,8 +68,6 @@ detector_error_model dem_from_stim_text(const std::string &dem_text) {
   });
 
   const std::size_t num_errors = rates.size();
-  // Reject zero-column H at the boundary instead of letting decoders
-  // crash with block_size == 0.
   if (num_errors == 0)
     throw std::runtime_error(
         "Stim DEM contains no error mechanisms after flattening");

libs/qec/python/bindings/py_decoder.cpp

@@ -339,16 +339,14 @@ makeBatchDecoderResult(const std::vector<decoder_result> &results) {
   };
 }
 
-// Wrap a borrowed cudaqx buffer in a NumPy array and force a Python-side copy,
-// so the returned object owns its data.
-nb::object toPyArray(const cudaqx::tensor<uint8_t> &t) {
+nb::object copyToPyArray(const cudaqx::tensor<uint8_t> &t) {
   size_t shape[2] = {t.shape()[0], t.shape()[1]};
   auto arr = nb::ndarray<nb::numpy, uint8_t>(const_cast<uint8_t *>(t.data()), 2,
                                              shape, nb::none());
   return nb::cast(arr).attr("copy")();
 }
 
-nb::object toPyArray(const std::vector<double> &v) {
+nb::object copyToPyArray(const std::vector<double> &v) {
   size_t shape[1] = {v.size()};
   auto arr = nb::ndarray<nb::numpy, double>(const_cast<double *>(v.data()), 1,
                                             shape, nb::none());
@@ -735,25 +733,21 @@ void bindDecoder(nb::module_ &mod) {
     });
   });
 
-  // Shared implementation for constructing a decoder from a Stim DEM string,
-  // used by both get_decoder overload paths and the (deprecated)
-  // get_decoder_from_stim_dem entry point.
   auto get_decoder_from_dem_text = [](const std::string &name,
                                       const std::string &dem_text,
                                       nb::kwargs options)
       -> std::variant<nb::object, std::unique_ptr<decoder>> {
     if (PyDecoderRegistry::contains(name)) {
       auto dem = dem_from_stim_text(dem_text);
 
-      // Keep in sync with make_pcm_decoder in decoder.h.
       auto defaults = dem_defaults_for_missing_keys(
           [&](const std::string &key) { return options.contains(key); }, dem);
       if (defaults.O)
-        options["O"] = toPyArray(*defaults.O);
+        options["O"] = copyToPyArray(*defaults.O);
       if (defaults.error_rate_vec)
-        options["error_rate_vec"] = toPyArray(*defaults.error_rate_vec);
+        options["error_rate_vec"] = copyToPyArray(*defaults.error_rate_vec);
 
-      nb::object H_obj = toPyArray(dem.detector_error_matrix);
+      nb::object H_obj = copyToPyArray(dem.detector_error_matrix);
       return PyDecoderRegistry::get_decoder(name, H_obj, options);
     }
 
@@ -824,7 +818,7 @@ void bindDecoder(nb::module_ &mod) {
   qecmod.def(
       "get_decoder_from_stim_dem", get_decoder_from_dem_text,
       "Deprecated: prefer get_decoder, which now accepts a Stim detector error "
-      "model string directly. Retained as a thin alias.");
+      "model string directly.");
 
   qecmod.def(
       "get_sorted_pcm_column_indices",

libs/qec/python/tests/test_decoder.py

@@ -763,9 +763,6 @@ def test_generate_random_pcm_signed_weight_rejects_negative():
 
 
 def test_get_decoder_from_stim_dem():
-    # 2 detectors, 1 observable, 3 errors. Matches the C++
-    # StimDemDecoderFactory.ConstructsLutDecoderFromStimDemText DEM so the
-    # truth-data assertions stay in sync across language bindings.
     dem_text = ("error(0.1) D0 L0\n"
                 "error(0.1) D1 L0\n"
                 "error(0.05) D0 D1\n")
@@ -788,8 +785,6 @@ def test_get_decoder_from_stim_dem():
 
 
 def test_get_decoder_accepts_stim_dem_string():
-    # get_decoder dispatches on the second argument: a str is treated as a Stim
-    # DEM, an ndarray as a parity-check matrix.
     dem_text = ("error(0.1) D0 L0\n"
                 "error(0.1) D1 L0\n"
                 "error(0.05) D0 D1\n")
@@ -833,8 +828,6 @@ def test_get_decoder_from_stim_dem_rejects_unknown_decoder():
 
 
 def test_get_decoder_from_stim_dem_user_O_wins_over_dem_derived():
-    # Wrong-shape user O trips PyMatching's validation; silent overwrite
-    # by the DEM-derived O would suppress the throw.
     dem_text = ("error(0.1) D0 L0\n"
                 "error(0.1) D1 L0\n"
                 "error(0.05) D0 D1\n")

libs/qec/unittests/CMakeLists.txt

@@ -35,8 +35,6 @@ find_package(CUDAToolkit REQUIRED)
 add_compile_options(-Wno-attributes) 
 
 add_executable(test_decoders test_decoders.cpp decoders/sample_decoder.cpp)
-# Direct libstim link for StimDemTargetCategoriesAreExhaustive;
-# cudaq-qec hides stim symbols via --exclude-libs.
 target_link_libraries(test_decoders PRIVATE GTest::gtest_main cudaq-qec cudaq-qec-realtime-decoding cudaq::cudaq libstim)
 add_dependencies(CUDAQXQECUnitTests test_decoders)
 gtest_discover_tests(test_decoders)
@@ -511,4 +509,3 @@ add_subdirectory(decoders/pymatching)
 if(CUDAQX_QEC_ENABLE_HOLOLINK_TOOLS)
   add_subdirectory(utils)
 endif()
-

libs/qec/unittests/test_decoders.cpp

@@ -779,8 +779,6 @@ error(0.05) D0 D1
 }
 
 TEST(StimDemDecoderFactory, UnifiedGetDecoderAcceptsStimDemString) {
-  // get_decoder and decoder::get accept a Stim DEM string directly via
-  // decoder_init, matching the (deprecated) get_decoder_from_stim_dem path.
   const std::string dem_text = R"(error(0.1) D0 L0
 error(0.1) D1 L0
 error(0.05) D0 D1
@@ -800,7 +798,6 @@ error(0.05) D0 D1
 }
 
 TEST(StimDemDecoderFactory, UnifiedGetDecoderStillAcceptsParityCheckMatrix) {
-  // Dense tensor inputs still convert to sparse PCM storage unchanged.
   cudaqx::tensor<uint8_t> H({2, 3});
   H.copy(std::vector<uint8_t>{1, 0, 1, 0, 1, 1}.data(), {2, 3});
   auto d = cudaq::qec::get_decoder("single_error_lut", H);
@@ -845,17 +842,13 @@ TEST(StimDemDecoderFactory, ThrowsOnUnknownDecoderName) {
 }
 
 TEST(StimDemDecoderFactory, ThrowsOnEmptyErrorMechanisms) {
-  // A bare detector(...) line parses but yields zero error mechanisms.
   const std::string dem_text = "detector(0, 0, 0)\n";
   EXPECT_THROW(
       cudaq::qec::get_decoder_from_stim_dem("single_error_lut", dem_text),
       std::runtime_error);
 }
 
 TEST(StimDemDecoderFactory, StimDemTargetCategoriesAreExhaustive) {
-  // Pins the invariant that keeps the defensive throw in
-  // dem_from_stim_text unreachable. Fires first if stim's encoding
-  // changes.
   const std::vector<stim::DemTarget> samples = {
       stim::DemTarget::separator(),
       stim::DemTarget::relative_detector_id(0),
@@ -878,7 +871,7 @@ error(0.1) D1 L0
 error(0.05) D0 D1
 )";
   cudaqx::heterogeneous_map opts;
-  opts.insert("error_rate_vec", std::vector<double>{0.5}); // wrong size
+  opts.insert("error_rate_vec", std::vector<double>{0.5});
   EXPECT_THROW(
       cudaq::qec::get_decoder_from_stim_dem("single_error_lut", dem_text, opts),
       std::runtime_error);