mqt-core 3.0.2__cp313-cp313t-win_amd64.whl → 3.1.0__cp313-cp313t-win_amd64.whl

mqt/core/__init__.py

@@ -12,14 +12,14 @@ from __future__ import annotations
 
 
 # start delvewheel patch
-def _delvewheel_patch_1_10_0():
+def _delvewheel_patch_1_10_1():
     import os
     if os.path.isdir(libs_dir := os.path.abspath(os.path.join(os.path.dirname(__file__), os.pardir, os.pardir, 'mqt_core.libs'))):
         os.add_dll_directory(libs_dir)
 
 
-_delvewheel_patch_1_10_0()
-del _delvewheel_patch_1_10_0
+_delvewheel_patch_1_10_1()
+del _delvewheel_patch_1_10_1
 # end delvewheel patch
 
 import os

mqt/core/_version.py

@@ -17,5 +17,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '3.0.2'
-__version_tuple__ = version_tuple = (3, 0, 2)
+__version__ = version = '3.1.0'
+__version_tuple__ = version_tuple = (3, 1, 0)

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

@@ -0,0 +1,45 @@
+/*
+ * Copyright (c) 2023 - 2025 Chair for Design Automation, TUM
+ * Copyright (c) 2025 Munich Quantum Software Company GmbH
+ * All rights reserved.
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * Licensed under the MIT License
+ */
+
+#pragma once
+
+#include "dd/Node.hpp"
+#include "dd/Package.hpp"
+
+namespace dd {
+
+/**
+ * @brief Useful metadata of an approximation run.
+ */
+struct ApproximationMetadata {
+  /// @brief The fidelity between the source and the approximated state.
+  double fidelity;
+  /// @brief The number of nodes visited during the mark stage.
+  std::size_t nodesVisited;
+  /// @brief The lowest qubit number that requires rebuilding.
+  Qubit min;
+};
+
+/**
+ * @brief Approximate the @p state based on fidelity. The fidelity of the
+ * approximated state will be at least @p fidelity.
+ * @details Traverses the decision diagram layer by layer in a breadth-first
+ * manner (iterative deepening algorithm) and eliminates edges greedily until
+ * the budget (1 - @p fidelity) is exhausted.
+ *
+ * @param state The DD to approximate.
+ * @param fidelity The desired minimum fidelity after approximation.
+ * @param dd The DD package to use for the approximation.
+ * @return Metadata about the approximation.
+ */
+ApproximationMetadata approximate(VectorDD& state, double fidelity,
+                                  Package& dd);
+
+} // namespace dd

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

@@ -88,6 +88,12 @@ struct Complex {
    */
   [[nodiscard]] bool approximatelyZero() const noexcept;
 
+  /// @brief Mark the complex number as used.
+  void mark() const noexcept;
+
+  /// @brief Unmark the complex number.
+  void unmark() const noexcept;
+
   /**
    * @brief Convert the complex number to a string.
    * @param formatted Whether to apply special formatting to the numbers.

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

@@ -128,24 +128,6 @@ public:
     return e;
   }
 
-  /**
-   * @brief Increment the reference count of a complex number.
-   * @details This is a pass-through function that increments the reference
-   * count of the real and imaginary parts of the given complex number.
-   * @param c The complex number
-   * @see RealNumberUniqueTable::incRef(RealNumber*)
-   */
-  void incRef(const Complex& c) const noexcept;
-
-  /**
-   * @brief Decrement the reference count of a complex number.
-   * @details This is a pass-through function that decrements the reference
-   * count of the real and imaginary parts of the given complex number.
-   * @param c The complex number
-   * @see RealNumberUniqueTable::decRef(RealNumber*)
-   */
-  void decRef(const Complex& c) const noexcept;
-
   /**
    * @brief Check whether a complex number is one of the static ones.
    * @param c The complex number.

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

@@ -36,11 +36,14 @@ namespace dd {
 template <class LeftOperandType, class RightOperandType, class ResultType>
 class ComputeTable {
 public:
+  /// Default number of buckets for the compute table
+  static constexpr std::size_t DEFAULT_NUM_BUCKETS = 16384U;
+
   /**
    * Default constructor
    * @param numBuckets Number of hash table buckets. Must be a power of two.
    */
-  explicit ComputeTable(const size_t numBuckets = 16384U) {
+  explicit ComputeTable(const size_t numBuckets = DEFAULT_NUM_BUCKETS) {
     // numBuckets must be a power of two
     if ((numBuckets & (numBuckets - 1)) != 0) {
       throw std::invalid_argument("Number of buckets must be a power of two.");

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

@@ -32,13 +32,6 @@ namespace dd {
  */
 using Qubit = std::uint16_t;
 
-/**
- * @brief Integer type used for reference counting
- * @details Allows a maximum reference count of roughly 4 billion.
- */
-using RefCount = std::uint32_t;
-static_assert(std::is_unsigned_v<RefCount>, "RefCount should be unsigned.");
-
 /**
  * @brief Floating point type to use for computations
  * @note Adjusting the precision might lead to unexpected results.

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

@@ -88,6 +88,16 @@ template <class Node> struct Edge {
     return Edge{Node::getTerminal(), w};
   }
 
+  /**
+   * @brief Check whether an edge requires tracking.
+   * @param e The edge to check.
+   * @return Whether the edge requires tracking.
+   */
+  [[nodiscard]] static constexpr bool trackingRequired(const Edge& e) {
+    return !e.isTerminal() || !constants::isStaticNumber(e.w.r) ||
+           !constants::isStaticNumber(e.w.i);
+  }
+
   /**
    * @brief Check whether this is a terminal
    * @return whether this is a terminal
@@ -131,6 +141,12 @@ template <class Node> struct Edge {
    */
   [[nodiscard]] std::size_t size() const;
 
+  /// @brief Mark the edge as used.
+  void mark() const noexcept;
+
+  /// @brief Unmark the edge.
+  void unmark() const noexcept;
+
 private:
   /**
    * @brief Recursively traverse the DD and count the number of nodes

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

@@ -163,8 +163,7 @@ static std::ostream& memoryNode(const Edge<Node>& e, std::ostream& os) {
   os << nodelabel << "[label=<";
   os << R"(<font point-size="10"><table border="1" cellspacing="0" cellpadding="2" style="rounded">)";
   os << R"(<tr><td colspan=")" << n << R"(" border="1" sides="B">)" << std::hex
-     << reinterpret_cast<std::uintptr_t>(e.p) << std::dec
-     << " ref: " << e.p->ref << "</td></tr>";
+     << reinterpret_cast<std::uintptr_t>(e.p) << std::dec << "</td></tr>";
   os << "<tr>";
   for (std::size_t i = 0; i < n; ++i) {
     os << "<td port=\"" << i << R"(" href="javascript:;" border="0" tooltip=")"

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

@@ -18,7 +18,6 @@
 #include <array>
 #include <cassert>
 #include <cstdint>
-#include <limits>
 
 namespace dd {
 
@@ -27,11 +26,9 @@ namespace dd {
  * @details This class is used to store common information for all DD nodes.
  * The `flags` makes the implicit padding explicit and can be used for storing
  * node properties.
- * Data Layout (8)|(4|2|2) = 16B.
+ * Data Layout (8)|(2|2|4) = 16B.
  */
 struct NodeBase : LLBase {
-  /// Reference count
-  RefCount ref = 0;
   /// Variable index
   Qubit v{};
 
@@ -40,13 +37,28 @@ struct NodeBase : LLBase {
    * @details Not required for all node types, but padding is required either
    * way.
    *
-   * 0b1000 = marks a reduced dm node,
-   *  0b100 = marks a dm (tmp flag),
-   *   0b10 = mark first path edge (tmp flag),
-   *    0b1 = mark path is conjugated (tmp flag)
+   * 0b10000 = mark flag used for mark-and-sweep garbage collection,
+   *  0b1000 = marks a reduced dm node,
+   *   0b100 = marks a dm (tmp flag),
+   *    0b10 = mark first path edge (tmp flag),
+   *     0b1 = mark path is conjugated (tmp flag)
    */
   std::uint16_t flags = 0;
 
+  /// Mark flag used for mark-and-sweep garbage collection
+  static constexpr std::uint16_t MARK_FLAG = 0b10000U;
+
+  /// @brief Whether a node is marked as used.
+  [[nodiscard]] bool isMarked() const noexcept {
+    return (flags & MARK_FLAG) != 0U;
+  }
+
+  /// @brief Mark the node as used.
+  void mark() noexcept { flags |= MARK_FLAG; }
+
+  /// @brief Unmark the node.
+  void unmark() noexcept { flags &= ~MARK_FLAG; }
+
   /// Getter for the next object.
   [[nodiscard]] NodeBase* next() const noexcept {
     // NOLINTNEXTLINE(cppcoreguidelines-pro-type-static-cast-downcast)
@@ -68,9 +80,12 @@ struct NodeBase : LLBase {
   static constexpr NodeBase* getTerminal() noexcept { return nullptr; }
 };
 
+static_assert(sizeof(NodeBase) == 16);
+static_assert(alignof(NodeBase) == 8);
+
 /**
  * @brief A vector DD node
- * @details Data Layout (8)|(4|2|2)|(24|24) = 64B
+ * @details Data Layout (8)|(2|2|4)|(24|24) = 64B
  */
 struct vNode final : NodeBase {       // NOLINT(readability-identifier-naming)
   std::array<Edge<vNode>, RADIX> e{}; // edges out of this node
@@ -89,7 +104,7 @@ using VectorDD = vEdge;
 
 /**
  * @brief A matrix DD node
- * @details Data Layout (8)|(4|2|2)|(24|24|24|24) = 112B
+ * @details Data Layout (8)|(2|2|4)|(24|24|24|24) = 112B
  */
 struct mNode final : NodeBase {       // NOLINT(readability-identifier-naming)
   std::array<Edge<mNode>, NEDGE> e{}; // edges out of this node
@@ -108,7 +123,7 @@ using MatrixDD = mEdge;
 
 /**
  * @brief A density matrix DD node
- * @details Data Layout (8)|(4|2|2)|(24|24|24|24) = 112B
+ * @details Data Layout (8)|(2|2|4)|(24|24|24|24) = 112B
  */
 struct dNode final : NodeBase {       // NOLINT(readability-identifier-naming)
   std::array<Edge<dNode>, NEDGE> e{}; // edges out of this node
@@ -205,42 +220,4 @@ static inline dEdge densityFromMatrixEdge(const mEdge& e) {
   return dEdge{reinterpret_cast<dNode*>(e.p), e.w};
 }
 
-/**
- * @brief Increment the reference count of a node.
- * @details This function increments the reference count of a node. If the
- * reference count has saturated (i.e. reached the maximum value of RefCount)
- * the reference count is not incremented.
- * @param p A pointer to the node 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 UniqueTable::incRef(Node*) function.
- */
-[[nodiscard]] static constexpr bool incRef(NodeBase* p) noexcept {
-  if (p == nullptr || p->ref == std::numeric_limits<RefCount>::max()) {
-    return false;
-  }
-  ++p->ref;
-  return true;
-}
-
-/**
- * @brief Decrement the reference count of a node.
- * @details This function decrements the reference count of a node. If the
- * reference count has saturated (i.e. reached the maximum value of RefCount)
- * the reference count is not decremented.
- * @param p A pointer to the node 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 UniqueTable::decRef(Node*) function.
- */
-[[nodiscard]] static constexpr bool decRef(NodeBase* p) noexcept {
-  if (p == nullptr || p->ref == std::numeric_limits<RefCount>::max()) {
-    return false;
-  }
-  assert(p->ref != 0 &&
-         "Reference count of Node must not be zero before decrement");
-  --p->ref;
-  return true;
-}
-
 } // namespace dd

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

@@ -204,6 +204,33 @@ applyClassicControlledOperation(const qc::ClassicControlledOperation& op,
                                 const std::vector<bool>& measurements,
                                 const qc::Permutation& permutation = {});
 
+/**
+ * @brief Check whether @p op is virtually executable.
+ *
+ * @param op The operation in question.
+ * @return Whether @p op is virtually executable.
+ */
+bool isExecutableVirtually(const qc::Operation& op) noexcept;
+
+/**
+ * @brief Apply virtual operation @p op.
+ *
+ * @param op The virtual operation to apply.
+ * @param permutation If suitable, the to be updated permutation.
+ */
+void applyVirtualOperation(const qc::Operation& op,
+                           qc::Permutation& permutation) noexcept;
+
+/**
+ * @brief Apply global phase to a given DD.
+ *
+ * @param in The input DD
+ * @param phase The phase to apply
+ * @param dd The DD package to use
+ * @return The output DD
+ */
+VectorDD applyGlobalPhase(VectorDD& in, const fp& phase, Package& dd);
+
 /**
  * @brief Change the permutation of a given DD.
  *

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>) {