Lift O/D into construction and enable Chromobius on decoding server

docs/sphinx/api/qec/cpp_api.rst

@@ -70,9 +70,10 @@ Decoder Interfaces
 .. doxygenstruct:: cudaq::qec::decoder_inputs
     :members:
 
-.. doxygenfunction:: cudaq::qec::d_sparse(const cudaq::M2DSparseMatrix &)
+.. doxygenclass:: cudaq::qec::decoder_init
+    :members:
 
-.. doxygentypedef:: cudaq::qec::decoder_init
+.. doxygenfunction:: cudaq::qec::d_sparse(const cudaq::M2DSparseMatrix &)
 
 .. doxygenclass:: cudaq::qec::decoder
     :members:

docs/sphinx/api/qec/cpp_realtime_decoding_api.rst

@@ -39,7 +39,8 @@ The configuration API enables setting up decoders before circuit execution. Deco
 .. doxygenclass:: cudaq::qec::decoding::config::multi_decoder_config
    :members:
 
-.. doxygenfunction:: cudaq::qec::decoding::config::configure_decoders
+.. doxygenfunction:: cudaq::qec::decoding::config::configure_decoders(multi_decoder_config &)
+.. doxygenfunction:: cudaq::qec::decoding::config::configure_decoders(multi_decoder_config &, const std::filesystem::path &)
 .. doxygenfunction:: cudaq::qec::decoding::config::configure_decoders_from_file
 .. doxygenfunction:: cudaq::qec::decoding::config::configure_decoders_from_str
 .. doxygenfunction:: cudaq::qec::decoding::config::finalize_decoders

libs/qec/include/cudaq/qec/decoder_init.h

@@ -0,0 +1,160 @@
+/****************************************************************-*- C++ -*-****
+ * Copyright (c) 2026 NVIDIA Corporation & Affiliates.                         *
+ * All rights reserved.                                                        *
+ *                                                                             *
+ * This source code and the accompanying materials are made available under    *
+ * the terms of the Apache License 2.0 which accompanies this distribution.    *
+ ******************************************************************************/
+
+#pragma once
+
+#include "cudaq/qec/detector_error_model.h"
+#include "cudaq/qec/sparse_binary_matrix.h"
+#include <cstddef>
+#include <cstdint>
+#include <memory>
+#include <optional>
+#include <string>
+#include <string_view>
+#include <vector>
+
+namespace cudaq::qec {
+
+/// @brief Authoritative representation from which a decoder model originates.
+///
+/// Matrix and Stim sources are implemented. This is the entry point for a
+/// compact chunked DEM: that source would be added here with a new enumerator
+/// plus its typed constructor and accessor, so a decoder that consumes chunks
+/// reads them directly instead of the handle first flattening them into
+/// matrices. Adding one changes neither the `decoder_init` object layout nor
+/// the decoder factory signature.
+enum class decoder_model_source : std::uint8_t {
+  matrices,
+  stim_dem,
+};
+
+/// @brief Stable, owning input contract shared by offline and server decoders.
+///
+/// This is a small immutable value handle. Copies share the same model state;
+/// the decoder factory takes the handle by value and the decoder base retains
+/// it. Source-specific data is authoritative and the common matrix accessors
+/// expose the projection stored when the handle is constructed. Model matrices
+/// are stored sparsely instead of composing detector_error_model, whose matrix
+/// fields are dense tensors.
+class decoder_init {
+public:
+  /// @brief Construct an H-only matrix model.
+  explicit decoder_init(sparse_binary_matrix detector_error_matrix);
+
+  /// Raw Stim DEM text enters through from_stim_dem(), which parses and
+  /// projects it. Deleted so the older spelling fails here rather than
+  /// through overload resolution somewhere less obvious.
+  explicit decoder_init(std::string) = delete;
+
+  /// @brief Construct a materialized matrix model.
+  /// @param detector_error_matrix H, with shape detectors x error mechanisms.
+  /// @param observable_flips_matrix O, with shape observables x error
+  /// mechanisms. Supplying it establishes an observable model; its row count is
+  /// retained even when a row has no nonzeros, so a zero-row O is a supplied
+  /// model rather than an absent one.
+  /// @param error_rates Optional rate per error mechanism.
+  /// @param measurement_to_detectors Optional D, with shape detectors x raw
+  /// measurements.
+  /// @param error_ids Optional correlation ID per error mechanism.
+  decoder_init(
+      sparse_binary_matrix detector_error_matrix,
+      std::optional<sparse_binary_matrix> observable_flips_matrix,
+      std::vector<double> error_rates = {},
+      std::optional<sparse_binary_matrix> measurement_to_detectors =
+          std::nullopt,
+      std::optional<std::vector<std::size_t>> error_ids = std::nullopt);
+
+  /// @brief Construct from the existing materialized detector-error model.
+  explicit decoder_init(detector_error_model model,
+                        std::optional<sparse_binary_matrix>
+                            measurement_to_detectors = std::nullopt);
+
+  /// @brief Construct from authoritative raw Stim DEM text.
+  ///
+  /// Matrix accessors expose the common lossy projection produced by
+  /// `dem_from_stim_text`; DEM-native decoders should consume `stim_dem()`.
+  static decoder_init
+  from_stim_dem(std::string stim_dem_text,
+                std::optional<sparse_binary_matrix> measurement_to_detectors =
+                    std::nullopt);
+
+  decoder_init(const decoder_init &) noexcept;
+  /// @brief Move construction leaves the source valid only for destruction or
+  /// assignment.
+  decoder_init(decoder_init &&) noexcept;
+  decoder_init &operator=(const decoder_init &) noexcept;
+  /// @brief Move assignment leaves the source valid only for destruction or
+  /// assignment.
+  decoder_init &operator=(decoder_init &&) noexcept;
+  ~decoder_init();
+
+  /// @brief The authoritative representation. Consumers that only need to
+  /// know whether raw DEM text is available should ask has_stim_dem(); this
+  /// discriminator is what a future compact source would extend.
+  decoder_model_source source() const noexcept;
+
+  /// @brief Return the stored common H projection.
+  const sparse_binary_matrix &detector_error_matrix() const;
+
+  /// @brief Whether this model supplies an observable mapping at all.
+  ///
+  /// Distinct from `num_observables() == 0`: a supplied O with zero rows is an
+  /// observable model, an H-only input is not. Construction-time validation of
+  /// an observable-output request depends on this distinction.
+  bool has_observable_model() const noexcept;
+
+  /// @brief Return the stored common O projection.
+  /// @throws std::logic_error if this model supplies no observable mapping.
+  const sparse_binary_matrix &observable_flips_matrix() const;
+
+  const std::vector<double> &error_rates() const;
+  const std::optional<std::vector<std::size_t>> &error_ids() const;
+
+  /// @brief Return D, or nullptr when input syndromes are already detectors.
+  const sparse_binary_matrix *measurement_to_detectors() const noexcept;
+
+  /// @brief Return the same inputs without D, for a decoder that is fed
+  /// detectors rather than a raw measurement stream. Everything else,
+  /// including the authoritative source, is preserved.
+  decoder_init decoder_init_without_d() const;
+
+  /// @brief Return the same inputs with H in GF(2)-canonical CSC form.
+  ///
+  /// Sorts indices within each compressed group and XOR-merges duplicates,
+  /// leaving column identity, ordering and dimensions unchanged. O and D are
+  /// passed through untouched, and the authoritative source is retained.
+  /// Consumers that need a canonical H should ask for it here rather than
+  /// rebuilding a matrix-authoritative handle by hand.
+  decoder_init canonicalize_H() const;
+
+  bool has_stim_dem() const noexcept;
+
+  /// @throws std::logic_error if the authoritative source is not a Stim DEM.
+  const std::string &stim_dem() const;
+
+  /// Dimensions are stored as source metadata so these accessors never need to
+  /// request H or O. For matrix sources they intentionally duplicate the O(1)
+  /// matrix shape values in preparation for compact source alternatives.
+  std::size_t num_detectors() const noexcept;
+  std::size_t num_error_mechanisms() const noexcept;
+  std::size_t num_observables() const noexcept;
+
+private:
+  struct impl;
+  static std::shared_ptr<const impl> make_matrix_state(
+      decoder_model_source source, sparse_binary_matrix detector_error_matrix,
+      std::optional<sparse_binary_matrix> observable_flips_matrix,
+      std::vector<double> error_rates,
+      std::optional<std::vector<std::size_t>> error_ids,
+      std::optional<sparse_binary_matrix> measurement_to_detectors,
+      std::optional<std::string> raw_stim_dem = std::nullopt);
+  explicit decoder_init(std::shared_ptr<const impl> state);
+  std::shared_ptr<const impl> state_;
+};
+
+} // namespace cudaq::qec

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

@@ -10,6 +10,7 @@
 #include "cudaq/algorithms/dem.h"
 #include "cudaq/qec/code.h"
 #include "cudaq/qec/detector_error_model.h"
+#include "cudaq/qec/sparse_binary_matrix.h"
 #include <cstddef>
 #include <vector>
 
@@ -207,6 +208,10 @@ struct decoder_context {
 /// realtime decoder config expects for its `D_sparse`.
 std::vector<std::int64_t> d_sparse(const cudaq::M2DSparseMatrix &m2d);
 
+/// @brief Convert CUDA-Q circuit-analysis M2D output to the QEC-owned sparse
+/// matrix used by decoder_init.
+sparse_binary_matrix m2d_to_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

libs/qec/include/cudaq/qec/realtime/decoding_config.h

@@ -10,6 +10,7 @@
 
 #include "cuda-qx/core/heterogeneous_map.h"
 #include <cstdint>
+#include <filesystem>
 #include <memory>
 #include <optional>
 #include <string>
@@ -70,11 +71,24 @@ struct decoder_config {
   /// GPU-accelerated decoder, hence at this level rather than inside the
   /// per-decoder custom args. Unset = unpinned.
   std::optional<int> cuda_device_id;
+  /// Path to a Stim detector error model, authoritative when set. Resolved
+  /// against the configuration file's directory, or the process working
+  /// directory for a programmatic or raw-string configuration. Mutually
+  /// exclusive with `H_sparse`, `O_sparse` and `error_rate_vec`, which are the
+  /// competing matrix representation of the same model; `block_size` and
+  /// `syndrome_size` remain accepted as checked assertions.
+  std::string stim_dem_path;
+  /// Required for a matrix model; derived from the DEM otherwise. Zero means
+  /// unset.
   uint64_t block_size = 0;
   uint64_t syndrome_size = 0;
   std::vector<std::int64_t> H_sparse;
   std::vector<std::int64_t> O_sparse;
+  /// Maps raw measurements to detectors. Orthogonal to the model source and
+  /// required by both.
   std::vector<std::int64_t> D_sparse;
+  /// Error probability per H column.
+  std::vector<double> error_rate_vec;
   decoder_custom_args_t decoder_custom_args;
 
   bool operator==(const decoder_config &) const = default;
@@ -181,6 +195,14 @@ __attribute__((visibility("default"))) std::string decoder_config_json_schema();
 __attribute__((visibility("default"))) int
 configure_decoders(multi_decoder_config &config);
 
+/// @brief Configure the decoders, resolving relative model paths (such as
+/// `stim_dem_path`) against @p base_dir. The overload above uses the process
+/// working directory as it stands when resolution starts.
+/// @return 0 on success, non-zero on failure.
+__attribute__((visibility("default"))) int
+configure_decoders(multi_decoder_config &config,
+                   const std::filesystem::path &base_dir);
+
 /// @brief 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.

libs/qec/lib/CMakeLists.txt

@@ -41,6 +41,7 @@ endif()
 
 set(DECODERS_SOURCES
   decoder.cpp
+  decoder_init.cpp
   decoder_config_payload.cpp
   decoder_config_schema.cpp
   detector_error_model.cpp