Add recorded result and distribution (#23)

* Add recorded result

* Add documentation

* Add results distribution and test

* Add missing include and pull out key construction

Author: sethrj

src/qiree/CMakeLists.txt

@@ -18,6 +18,7 @@ qiree_add_library(qiree
   Assert.cc
   Module.cc
   Executor.cc
+  ResultDistribution.cc
   QuantumNotImpl.cc
 )
 target_compile_features(qiree PUBLIC cxx_std_17)

src/qiree/RecordedResult.hh

@@ -0,0 +1,95 @@
+//----------------------------------*-C++-*----------------------------------//
+// Copyright 2025 UT-Battelle, LLC, and other QIR-EE developers.
+// See the top-level COPYRIGHT file for details.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//---------------------------------------------------------------------------//
+//! \file qiree/RecordedResult.hh
+//---------------------------------------------------------------------------//
+#pragma once
+
+#include <string>
+#include <vector>
+
+#include "Types.hh"
+
+namespace qiree
+{
+//---------------------------------------------------------------------------//
+/*!
+ * Accumulate sequential measurement outcomes from a single "shot".
+ *
+ * Each call to result_record_output appends a measurement bit (derived from
+ * the provided Result) and its associated label. The storage is preallocated
+ * via array_record_output.
+ */
+//---------------------------------------------------------------------------//
+
+class RecordedResult
+{
+  public:
+    //!@{
+    //! \name Type aliases
+    using VecBits = std::vector<bool>;
+    using VecString = std::vector<std::string>;
+    //!@}
+
+  public:
+    RecordedResult() = default;
+
+    // Construct with size and optional label
+    RecordedResult(std::size_t count, OptionalCString label);
+
+    explicit RecordedResult(std::size_t count) : RecordedResult{count, nullptr}
+    {
+    }
+
+    //! Construct with an explicit vector for testing
+    explicit RecordedResult(VecBits&& bits)
+        : bits_(std::move(bits)), entry_labels_(bits_.size())
+    {
+    }
+
+    inline void push_back(QState result, OptionalCString label = nullptr);
+
+    //! Accessors
+    std::string const& container_label() const { return container_label_; }
+    VecBits const& bits() const { return bits_; }
+    VecString const& entry_labels() const { return entry_labels_; }
+
+  private:
+    std::string container_label_;
+    VecBits bits_;
+    VecString entry_labels_;
+};
+
+//---------------------------------------------------------------------------//
+// INLINE DEFINITIONS
+//---------------------------------------------------------------------------//
+/*!
+ * Preallocate storage for measurement results.
+ *
+ * \param count  Number of measurement bits expected.
+ * \param label  Label for the container
+ */
+RecordedResult::RecordedResult(std::size_t count, OptionalCString label)
+{
+    if (label)
+    {
+        container_label_ = label;
+    }
+    bits_.reserve(count);
+    entry_labels_.reserve(count);
+}
+
+//---------------------------------------------------------------------------//
+/*!
+ * Record a measurement result and its optional label.
+ */
+void RecordedResult::push_back(QState state, OptionalCString label)
+{
+    bits_.push_back(static_cast<bool>(state));
+    entry_labels_.push_back(label ? label : std::string{});
+}
+
+//---------------------------------------------------------------------------//
+}  // namespace qiree

src/qiree/ResultDistribution.cc

@@ -0,0 +1,99 @@
+//----------------------------------*-C++-*----------------------------------//
+// Copyright 2025 UT-Battelle, LLC, and other QIR-EE developers.
+// See the top-level COPYRIGHT file for details.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//---------------------------------------------------------------------------//
+//! \file qiree/ResultDistribution.cc
+//---------------------------------------------------------------------------//
+#include "ResultDistribution.hh"
+
+#include <algorithm>
+
+#include "RecordedResult.hh"
+#include "qiree/Assert.hh"
+
+namespace qiree
+{
+namespace
+{
+//---------------------------------------------------------------------------//
+/*!
+ * Convert bits to a bit string key ("0" for false, "1" for true).
+ */
+std::string to_key(std::vector<bool> const& bits)
+{
+    std::string key;
+    key.reserve(bits.size());
+    for (bool bit : bits)
+    {
+        key.push_back(bit ? '1' : '0');
+    }
+    return key;
+}
+
+}  // namespace
+
+//---------------------------------------------------------------------------//
+/*!
+ * Accumulate a single shot.
+ */
+void ResultDistribution::accumulate(RecordedResult const& result)
+{
+    auto const& bits = result.bits();
+
+    if (QIREE_UNLIKELY(key_length_ == 0))
+    {
+        // This is the first result: store the key length
+        key_length_ = bits.size();
+    }
+    else
+    {
+        QIREE_VALIDATE(bits.size() == key_length_,
+                       << "RecordedResult bit length " << bits.size()
+                       << " does not match distribution key length "
+                       << key_length_);
+    }
+
+    ++distribution_[to_key(bits)];
+}
+
+//---------------------------------------------------------------------------//
+/*!
+ * Access the number of shots that resulted in this bit string.
+ */
+std::size_t ResultDistribution::count(std::string const& key) const
+{
+    QIREE_VALIDATE(key.length() == key_length_,
+                   << "invalid key length: expected " << key_length_
+                   << " but got " << key.length());
+    QIREE_VALIDATE(std::all_of(key.begin(),
+                               key.end(),
+                               [](char c) { return c == '0' || c == '1'; }),
+                   << "invalid key: expected only '0' or '1'");
+
+    auto it = distribution_.find(key);
+    return (it != distribution_.end()) ? it->second : 0;
+}
+
+//---------------------------------------------------------------------------//
+/*!
+ * Build a JSON string of the distribution.
+ */
+std::string ResultDistribution::to_json() const
+{
+    std::ostringstream oss;
+    oss << "{";
+    bool first = true;
+    for (auto const& kv : distribution_)
+    {
+        if (!first)
+            oss << ",";
+        first = false;
+        oss << "\"" << kv.first << "\":" << kv.second;
+    }
+    oss << "}";
+    return oss.str();
+}
+
+//---------------------------------------------------------------------------//
+}  // namespace qiree

src/qiree/ResultDistribution.hh

@@ -0,0 +1,58 @@
+//----------------------------------*-C++-*----------------------------------//
+// Copyright 2025 UT-Battelle, LLC, and other QIR-EE developers.
+// See the top-level COPYRIGHT file for details.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//---------------------------------------------------------------------------//
+//! \file qiree/ResultDistribution.hh
+//---------------------------------------------------------------------------//
+#pragma once
+
+#include <string>
+#include <unordered_map>
+
+namespace qiree
+{
+class RecordedResult;
+//---------------------------------------------------------------------------//
+/*!
+ * Distribution of recorded results from shots.
+
+The distribution is formed by accumulating multiple \c RecordedResult
+instances into a sparse map of {bit string -> count}. The length of the bit
+string is the same for all keys. We provide accessors by string key such
+as \c 01001 which corresponds to a bit string `{false, true, ...}`. It is
+serializable to JSON, creating an object that has bit strings as keys and
+counts as values.
+
+ */
+class ResultDistribution
+{
+  public:
+    // Accumulate the results from a RecordedResult instance.
+    // Throws if the bit-length of the new result
+    // differs from previously accumulated ones.
+    void accumulate(RecordedResult const& result);
+
+    // Access the count for a given bit string key (e.g. "01001").
+    // Returns 0 if the key is not present.
+    std::size_t count(std::string const& key) const;
+
+    // Serialize the distribution to a JSON string.
+    // The JSON object has bit string keys and count values.
+    std::string to_json() const;
+
+    // Provide const iterators to iterate over the distribution.
+    auto begin() const { return distribution_.begin(); }
+    auto end() const { return distribution_.end(); }
+
+  private:
+    // Sparse map of {bit string -> count}
+    std::unordered_map<std::string, std::size_t> distribution_;
+
+    // key_length_ is 0 until the first RecordedResult is accumulated.
+    // All subsequent RecordedResult instances must have the same bit length.
+    std::size_t key_length_ = 0;
+};
+
+//---------------------------------------------------------------------------//
+}  // namespace qiree

src/qirqsim/QsimDefaultRuntime.cc

@@ -25,30 +25,4 @@ void QsimDefaultRuntime::initialize(OptionalCString env)
     }
 }
 
-//---------------------------------------------------------------------------//
-/*!
- * Execute circuit and mark the following N results as being part of an array
- * named tag
- */
-void QsimDefaultRuntime::array_record_output(size_type, OptionalCString) {}
-
-//---------------------------------------------------------------------------//
-/*!
- * Execute circuit and mark the following N results as being part of a tuple
- * named tag.
- */
-void QsimDefaultRuntime::tuple_record_output(size_type, OptionalCString) {}
-
-//---------------------------------------------------------------------------//
-/*!
- * Execute circuit and report a single measurement result.
- */
-void QsimDefaultRuntime::result_record_output(Result, OptionalCString)
-{
-    // Access values through the getter
-    // This prints results every time result_record_output is called
-    // Can comment out if only want to see final results
-    (void)sizeof(sim_);
-}
-
 }  // namespace qiree

src/qirqsim/QsimDefaultRuntime.hh

@@ -8,6 +8,7 @@
 #pragma once
 
 #include "QsimQuantum.hh"
+#include "qiree/RecordedResult.hh"
 
 namespace qiree
 {
@@ -41,22 +42,35 @@ class QsimDefaultRuntime final : virtual public RuntimeInterface
 
     //!@{
     //! \name Runtime interface
+
     // Initialize the execution environment, resetting qubits
     void initialize(OptionalCString env) override;
 
     //! Mark the following N results as being part of an array named tag
-    void array_record_output(size_type, OptionalCString tag) final;
+    void array_record_output(size_type size, OptionalCString tag) final
+    {
+        result_ = RecordedResult(size, tag);
+    }
 
     //! Mark the following N results as being part of a tuple named tag
-    void tuple_record_output(size_type, OptionalCString) final;
+    void tuple_record_output(size_type size, OptionalCString tag) final
+    {
+        result_ = RecordedResult(size, tag);
+    }
 
-    // Save one result
-    void result_record_output(Result result, OptionalCString tag) final;
+    //! Save one result
+    void result_record_output(Result result, OptionalCString tag) final
+    {
+        result_.push_back(sim_.get_result(result), tag);
+    }
     //!@}
 
+    RecordedResult const& result() const { return result_; }
+
   private:
     std::ostream& output_;
     QsimQuantum& sim_;
+    RecordedResult result_;
 };
 
 }  // namespace qiree

test/CMakeLists.txt

@@ -45,6 +45,7 @@ endfunction()
 
 qiree_add_test(qiree Executor)
 qiree_add_test(qiree Module)
+qiree_add_test(qiree ResultDistribution)
 
 #---------------------------------------------------------------------------##
 # QIRXACC TESTS