mqt-core 3.0.2__cp313-cp313-win_amd64.whl → 3.2.0__cp313-cp313-win_amd64.whl

mqt/core/include/mqt-core/dd/Package.hpp

@@ -194,63 +194,160 @@ public:
   void clearUniqueTables();
 
   /**
-   * @brief Increment the reference count of an edge
-   * @details This is the main function for increasing reference counts within
-   * the DD package. It increases the reference count of the complex edge weight
-   * as well as the DD node itself. If the node newly becomes active, meaning
-   * that it had a reference count of zero beforehand, the reference count of
-   * all children is recursively increased.
+   * @brief Add the DD to a tracking hashset and update its reference count.
    * @tparam Node The node type of the edge.
-   * @param e The edge to increase the reference count of
+   * @param e The edge to increase the reference count of.
    */
   template <class Node> void incRef(const Edge<Node>& e) noexcept {
-    cn.incRef(e.w);
-    const auto& p = e.p;
-    const auto inc = getUniqueTable<Node>().incRef(p);
-    if (inc && p->ref == 1U) {
-      for (const auto& child : p->e) {
-        incRef(child);
-      }
+    if (Edge<Node>::trackingRequired(e)) {
+      roots.addToRoots(e);
     }
   }
 
   /**
-   * @brief Decrement the reference count of an edge
-   * @details This is the main function for decreasing reference counts within
-   * the DD package. It decreases the reference count of the complex edge weight
-   * as well as the DD node itself. If the node newly becomes dead, meaning
-   * that its reference count hit zero, the reference count of all children is
-   * recursively decreased.
+   * @brief Decrease the DD's reference count and remove it from the tracking
+   * hashset if the count hits zero.
    * @tparam Node The node type of the edge.
-   * @param e The edge to decrease the reference count of
+   * @param e The edge to decrease the reference count of.
+   * @throws std::invalid_argument If the edge is not part of the tracking
+   * hashset.
    */
-  template <class Node> void decRef(const Edge<Node>& e) noexcept {
-    cn.decRef(e.w);
-    const auto& p = e.p;
-    const auto dec = getUniqueTable<Node>().decRef(p);
-    if (dec && p->ref == 0U) {
-      for (const auto& child : p->e) {
-        decRef(child);
-      }
+  template <class Node> void decRef(const Edge<Node>& e) {
+    if (Edge<Node>::trackingRequired(e)) {
+      roots.removeFromRoots(e);
     }
   }
 
+  template <class Node> [[nodiscard]] auto& getRootSet() noexcept {
+    return roots.getRoots<Node>();
+  }
+
+private:
+  struct RootSetManager {
+  public:
+    template <class Node>
+    using RootSet = std::unordered_map<Edge<Node>, std::size_t>;
+
+    /// @brief Add to respective root set.
+    template <class Node> void addToRoots(const Edge<Node>& e) noexcept {
+      getRoots<Node>()[e]++;
+    }
+
+    /// @brief Remove from respective root set.
+    template <class Node> void removeFromRoots(const Edge<Node>& e) {
+      auto& set = getRoots<Node>();
+      auto it = set.find(e);
+      if (it == set.end()) {
+        throw std::invalid_argument("Edge is not part of the root set.");
+      }
+      if (--it->second == 0U) {
+        set.erase(it);
+      }
+    }
+
+    /// @brief Execute mark() -> op() -> unmark().
+    template <class Result, typename Fn> Result execute(Fn& op) noexcept {
+      mark();
+      Result res = op();
+      unmark();
+      return res;
+    }
+
+    /// @brief Clear all root sets.
+    void reset() {
+      vRoots.clear();
+      mRoots.clear();
+      dRoots.clear();
+    }
+
+  private:
+    /// @brief Mark edges contained in @p roots.
+    template <class Node> static void mark(const RootSet<Node>& roots) {
+      for (auto& [edge, _] : roots) {
+        edge.mark();
+      }
+    }
+
+    /// @brief Unmark edges contained in @p roots.
+    template <class Node> static void unmark(const RootSet<Node>& roots) {
+      for (auto& [edge, _] : roots) {
+        edge.unmark();
+      }
+    }
+
+    /// @brief Mark edges contained in all root sets.
+    void mark() noexcept {
+      RootSetManager::mark(vRoots);
+      RootSetManager::mark(mRoots);
+      RootSetManager::mark(dRoots);
+    }
+
+    /// @brief Unmark edges contained in all root sets.
+    void unmark() noexcept {
+      RootSetManager::unmark(vRoots);
+      RootSetManager::unmark(mRoots);
+      RootSetManager::unmark(dRoots);
+    }
+
+    /// @brief Return vector roots.
+    template <class Node,
+              std::enable_if_t<std::is_same_v<Node, vNode>, bool> = true>
+    auto& getRoots() noexcept {
+      return vRoots;
+    }
+
+    /// @brief Return matrix roots.
+    template <class Node,
+              std::enable_if_t<std::is_same_v<Node, mNode>, bool> = true>
+    auto& getRoots() noexcept {
+      return mRoots;
+    }
+
+    /// @brief Return density roots.
+    template <class Node,
+              std::enable_if_t<std::is_same_v<Node, dNode>, bool> = true>
+    auto& getRoots() noexcept {
+      return dRoots;
+    }
+
+    RootSet<vNode> vRoots;
+    RootSet<mNode> mRoots;
+    RootSet<dNode> dRoots;
+
+    template <class Node> friend auto& Package::getRootSet() noexcept;
+  };
+
+  RootSetManager roots;
+
+public:
   /**
-   * @brief Trigger garbage collection in all unique tables
-   *
-   * @details Garbage collection is the process of removing all nodes from the
-   * unique tables that have a reference count of zero.
-   * Such nodes are considered "dead" and they can be safely removed from the
-   * unique tables. This process is necessary to free up memory that is no
-   * longer needed. By default, garbage collection is only triggered if the
-   * unique table indicates that it possibly needs collection. Whenever some
-   * nodes are recollected, some compute tables need to be invalidated as well.
-   *
-   * @param force
-   * @return
+   * @brief Trigger garbage collection on all unique tables.
+   * @details Mark-and-sweep algorithm: First, mark all nodes and complex
+   * numbers tracked in @p roots. Second, remove any unmarked nodes and numbers
+   * from the respective unique tables. Lastly, unmark all nodes and complex
+   * numbers again.
+   * @note By default, garbage collection is only triggered if the unique tables
+   * report that a collection might be necessary.
+   *
+   * @param force Force garbage collect, regardless of whether any
+   * table reports that it may need collecting.
+   * @returns Whether at least one vector, matrix, density-matrix node, or
+   *          any complex number was reclaimed.
    */
   bool garbageCollect(bool force = false);
 
+  struct ActiveCounts {
+    std::size_t vector = 0U;
+    std::size_t matrix = 0U;
+    std::size_t density = 0U;
+    std::size_t reals = 0U;
+  };
+  /**
+   * @brief Compute the active number of nodes and numbers
+   * @note This traverses every currently tracked DD twice.
+   */
+  [[nodiscard]] ActiveCounts computeActiveCounts();
+
   ///
   /// Vector nodes, edges and quantum states
   ///
@@ -263,60 +360,6 @@ public:
    */
   dEdge makeZeroDensityOperator(std::size_t n);
 
-  /**
-   * @brief Construct the all-zero state \f$|0...0\rangle\f$
-   * @param n The number of qubits
-   * @param start The starting qubit index. Default is 0.
-   * @return A decision diagram for the all-zero state
-   */
-  vEdge makeZeroState(std::size_t n, std::size_t start = 0);
-
-  /**
-   * @brief Construct a computational basis state \f$|b_{n-1}...b_0\rangle\f$
-   * @param n The number of qubits
-   * @param state The state to construct
-   * @param start The starting qubit index. Default is 0.
-   * @return A decision diagram for the computational basis state
-   */
-  vEdge makeBasisState(std::size_t n, const std::vector<bool>& state,
-                       std::size_t start = 0);
-
-  /**
-   * @brief Construct a product state out of
-   *        \f$\{0, 1, +, -, R, L\}^{\otimes n}\f$.
-   * @param n The number of qubits
-   * @param state The state to construct
-   * @param start The starting qubit index. Default is 0.
-   * @return A decision diagram for the product state
-   */
-  vEdge makeBasisState(std::size_t n, const std::vector<BasisStates>& state,
-                       std::size_t start = 0);
-
-  /**
-   * @brief Construct a GHZ state \f$|0...0\rangle + |1...1\rangle\f$
-   * @param n The number of qubits
-   * @return A decision diagram for the GHZ state
-   */
-  vEdge makeGHZState(std::size_t n);
-
-  /**
-   * @brief Construct a W state
-   * @details The W state is defined as
-   * \f[
-   * |0...01\rangle + |0...10\rangle + |10...0\rangle
-   * \f]
-   * @param n The number of qubits
-   * @return A decision diagram for the W state
-   */
-  vEdge makeWState(std::size_t n);
-
-  /**
-   * @brief Construct a decision diagram from an arbitrary state vector
-   * @param stateVector The state vector to convert to a DD
-   * @return A decision diagram for the state
-   */
-  vEdge makeStateFromVector(const CVec& stateVector);
-
   ///
   /// Matrix nodes, edges and quantum gates
   ///
@@ -399,30 +442,6 @@ public:
   mEdge makeDDFromMatrix(const CMat& matrix);
 
 private:
-  /**
-   * @brief Constructs a decision diagram (DD) from a state vector using a
-   * recursive algorithm.
-   *
-   * @param begin Iterator pointing to the beginning of the state vector.
-   * @param end Iterator pointing to the end of the state vector.
-   * @param level The current level of recursion. Starts at the highest level of
-   * the state vector (log base 2 of the vector size - 1).
-   * @return A vCachedEdge representing the root node of the created DD.
-   *
-   * @details This function recursively breaks down the state vector into halves
-   * until each half has only one element. At each level of recursion, two new
-   * edges are created, one for each half of the state vector. The two resulting
-   * decision diagram edges are used to create a new decision diagram node at
-   * the current level, and this node is returned as the result of the current
-   * recursive call. At the base case of recursion, the state vector has only
-   * two elements, which are converted into terminal nodes of the decision
-   * diagram.
-   *
-   * @note This function assumes that the state vector size is a power of two.
-   */
-  vCachedEdge makeStateFromVector(const CVec::const_iterator& begin,
-                                  const CVec::const_iterator& end, Qubit level);
-
   /**
    * @brief Constructs a decision diagram (DD) from a complex matrix using a
    * recursive algorithm.
@@ -477,7 +496,6 @@ public:
              [[maybe_unused]] const bool generateDensityMatrix = false) {
     auto& memoryManager = getMemoryManager<Node>();
     auto p = memoryManager.template get<Node>();
-    assert(p->ref == 0U);
 
     p->v = var;
     if constexpr (std::is_same_v<Node, mNode> || std::is_same_v<Node, dNode>) {
@@ -1803,7 +1821,7 @@ public:
           if (edge.w.approximatelyZero()) {
             continue;
           }
-          if (mappedNode.find(edge.p) != mappedNode.end()) {
+          if (mappedNode.contains(edge.p)) {
             continue;
           }
 
@@ -1822,7 +1840,7 @@ public:
         if (edge.w.approximatelyZero()) {
           continue;
         }
-        if (mappedNode.find(edge.p) != mappedNode.end()) {
+        if (mappedNode.contains(edge.p)) {
           continue;
         }
         hasChild = edge.p == stack.top()->p;
@@ -1834,7 +1852,7 @@ public:
         stack.push(currentEdge);
         currentEdge = temp;
       } else {
-        if (mappedNode.find(currentEdge->p) != mappedNode.end()) {
+        if (!mappedNode.contains(currentEdge->p)) {
           currentEdge = nullptr;
           continue;
         }

mqt/core/include/mqt-core/dd/RealNumber.hpp

@@ -21,18 +21,16 @@
 namespace dd {
 /**
  * @brief A struct for representing real numbers as part of the DD package.
- * @details Consists of a floating point number (the value), a next pointer
- * (used for chaining entries), and a reference count.
+ * @details Consists of a floating point number (the value) and a next pointer
+ * (used for chaining entries). Numbers are marked for garbage collection via
+ * the second least significant bit of pointers referencing them.
  * @note Due to the way the sign of the value is encoded, special care has to
  * be taken when accessing the value. The static functions in this struct
  * provide safe access to the value of a RealNumber* pointer.
  */
 struct RealNumber final : LLBase {
-
   /// Getter for the next object.
-  [[nodiscard]] RealNumber* next() const noexcept {
-    return reinterpret_cast<RealNumber*>(next_);
-  }
+  [[nodiscard]] RealNumber* next() const noexcept;
 
   /**
    * @brief Check whether the number points to the zero number.
@@ -65,15 +63,6 @@ struct RealNumber final : LLBase {
    */
   [[nodiscard]] static fp val(const RealNumber* e) noexcept;
 
-  /**
-   * @brief Get the reference count of the number.
-   * @param num A pointer to the number to get the reference count for.
-   * @returns The reference count of the number.
-   * @note This function accounts for the sign of the number embedded in the
-   * memory address of the number.
-   */
-  [[nodiscard]] static RefCount refCount(const RealNumber* num) noexcept;
-
   /**
    * @brief Check whether two floating point numbers are approximately equal.
    * @details This function checks whether two floating point numbers are
@@ -115,42 +104,6 @@ struct RealNumber final : LLBase {
    */
   [[nodiscard]] static bool approximatelyZero(const RealNumber* e) noexcept;
 
-  /**
-   * @brief Indicates whether a given number needs reference count updates.
-   * @details This function checks whether a given number needs reference count
-   * updates. A number needs reference count updates if the pointer to it is
-   * not the null pointer, if it is not one of the special numbers (zero,
-   * one, 1/sqrt(2)), and if the reference count has saturated.
-   * @param num Pointer to the number to check.
-   * @returns Whether the number needs reference count updates.
-   * @note This function assumes that the pointer to the number is aligned.
-   */
-  [[nodiscard]] static bool noRefCountingNeeded(const RealNumber* num) noexcept;
-
-  /**
-   * @brief Increment the reference count of a number.
-   * @details This function increments the reference count of a number. If the
-   * reference count has saturated (i.e. reached the maximum value of RefCount)
-   * the reference count is not incremented.
-   * @param num A pointer to the number to increment the reference count of.
-   * @returns Whether the reference count was incremented.
-   * @note Typically, you do not want to call this function directly. Instead,
-   * use the RealNumberUniqueTable::incRef(RelNumber*) function.
-   */
-  [[nodiscard]] static bool incRef(const RealNumber* num) noexcept;
-
-  /**
-   * @brief Decrement the reference count of a number.
-   * @details This function decrements the reference count of a number. If the
-   * reference count has saturated (i.e. reached the maximum value of RefCount)
-   * the reference count is not decremented.
-   * @param num A pointer to the number to decrement the reference count of.
-   * @returns Whether the reference count was decremented.
-   * @note Typically, you do not want to call this function directly. Instead,
-   * use the RealNumberUniqueTable::decRef(RelNumber*) function.
-   */
-  [[nodiscard]] static bool decRef(const RealNumber* num) noexcept;
-
   /**
    * @brief Write a binary representation of the number to a stream.
    * @param e The number to write.
@@ -195,13 +148,6 @@ struct RealNumber final : LLBase {
   [[nodiscard]] static RealNumber*
   getNegativePointer(const RealNumber* e) noexcept;
 
-  /**
-   * @brief Check whether the number is a negative pointer.
-   * @param e The number to check.
-   * @returns Whether the number is a negative pointer.
-   */
-  [[nodiscard]] static bool isNegativePointer(const RealNumber* e) noexcept;
-
   /**
    * @brief Flip the sign of the number pointer.
    * @param e The number to flip the sign of.
@@ -214,6 +160,48 @@ struct RealNumber final : LLBase {
   [[nodiscard]] static RealNumber*
   flipPointerSign(const RealNumber* e) noexcept;
 
+  /**
+   * @brief Mark @p e for garbage collection.
+   * @details Sets the 2nd least significant bit of the next_ pointer.
+   * @param e The number to mark.
+   */
+  static void mark(RealNumber* e) noexcept;
+
+  /**
+   * @brief Unmark @p e after garbage collection.
+   * @details Unsets the 2nd least significant bit of the next_ pointer.
+   * @param e The number to unmark.
+   */
+  static void unmark(RealNumber* e) noexcept;
+
+  /**
+   * @brief Immortalize @p e.
+   * @details Sets the 3rd least significant bit of the next_ pointer.
+   * @param e The number to immortalize.
+   */
+  static void immortalize(RealNumber* e) noexcept;
+
+  /**
+   * @brief Check whether the number is flagged as negative.
+   * @param e The number to check.
+   * @returns Whether the number is negative.
+   */
+  [[nodiscard]] static bool isNegativePointer(const RealNumber* e) noexcept;
+
+  /**
+   * @brief Check whether the number is flagged as marked.
+   * @param e The number to check.
+   * @returns Whether the number is marked.
+   */
+  [[nodiscard]] static bool isMarked(const RealNumber* e) noexcept;
+
+  /**
+   * @brief Check whether the number is flagged as immortal.
+   * @param e The number to check.
+   * @returns Whether the number is immortal.
+   */
+  [[nodiscard]] static bool isImmortal(const RealNumber* e) noexcept;
+
   /**
    * @brief The value of the number.
    * @details The value of the number is a floating point number. The sign of
@@ -224,19 +212,14 @@ struct RealNumber final : LLBase {
    */
   fp value{};
 
-  /**
-   * @brief The reference count of the number.
-   * @details The reference count is used to determine whether a number is
-   * still in use. If the reference count is zero, the number is not in use
-   * and can be garbage collected.
-   */
-  RefCount ref{};
-
   /// numerical tolerance to be used for floating point values
   // NOLINTNEXTLINE(cppcoreguidelines-avoid-non-const-global-variables)
   static inline fp eps = std::numeric_limits<dd::fp>::epsilon() * 1024;
 };
 
+static_assert(sizeof(RealNumber) == 16);
+static_assert(alignof(RealNumber) == 8);
+
 namespace constants {
 // NOLINTBEGIN(cppcoreguidelines-avoid-non-const-global-variables)
 /// The constant zero.

mqt/core/include/mqt-core/dd/RealNumberUniqueTable.hpp

@@ -23,6 +23,14 @@ namespace dd {
 
 struct RealNumber;
 
+/**
+ * @brief Immortal numbers that will never be garbage collected.
+ */
+namespace immortals {
+constexpr std::array<fp, 1> get() { return {.5}; }
+constexpr std::size_t size() { return get().size(); }
+} // namespace immortals
+
 /**
  * @brief A unique table for real numbers.
  * @details A hash table that stores real numbers. The hash table is implemented
@@ -93,28 +101,6 @@ public:
    */
   [[nodiscard]] RealNumber* lookup(fp val);
 
-  /**
-   * @brief Increment the reference count of a number.
-   * @details This is a pass-through function that calls the increment function
-   * of the number. It additionally keeps track of the number of active entries
-   * in the table (entries with a reference count greater than zero). Reference
-   * counts saturate at the maximum value of RefCount.
-   * @param num A pointer to the number to increase the reference count of.
-   * @see RealNumber::incRef(RealNumber*)
-   */
-  void incRef(RealNumber* num) noexcept;
-
-  /**
-   * @brief Decrement the reference count of a number.
-   * @details This is a pass-through function that calls the decrement function
-   * of the number. It additionally keeps track of the number of active entries
-   * in the table (entries with a reference count greater than zero). Reference
-   * counts saturate at the maximum value of RefCount.
-   * @param num A pointer to the number to decrease the reference count of.
-   * @see RealNumber::decRef(RealNumber*)
-   */
-  void decRef(RealNumber* num) noexcept;
-
   /**
    * @brief Check whether the table possibly needs garbage collection.
    * @returns Whether the number of entries in the table has reached the garbage
@@ -126,9 +112,9 @@ public:
    * @brief Perform garbage collection.
    * @details This function performs garbage collection. It first checks whether
    * garbage collection is necessary. If not, it does nothing. Otherwise, it
-   * iterates over all entries in the table and returns all entries with a
-   * reference count of zero to the available list. If the force flag is set,
-   * garbage collection is performed even if it is not necessary.
+   * iterates over all entries in the table and removes all numbers whose
+   * pointers are unmarked. If the force flag is set, garbage collection is
+   * performed even if it is not strictly necessary.
    * Based on how many entries are returned to the available list, the garbage
    * collection limit is dynamically adjusted.
    * @param force Whether to force garbage collection.
@@ -156,6 +142,9 @@ public:
    */
   std::ostream& printBucketDistribution(std::ostream& os = std::cout);
 
+  /// Count the marked entries in the table
+  [[nodiscard]] std::size_t countMarkedEntries() const noexcept;
+
 private:
   /// Typedef for a bucket in the table.
   using Bucket = RealNumber*;