mqt-core 3.0.2__cp313-cp313-win_amd64.whl → 3.2.0__cp313-cp313-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_11_0():
     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_11_0()
+del _delvewheel_patch_1_11_0
 # 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.2.0'
+__version_tuple__ = version_tuple = (3, 2, 0)

mqt/core/dd.pyi

@@ -9,7 +9,8 @@
 """MQT Core DD - The MQT Decision Diagram Package."""
 
 from collections.abc import Iterable
-from typing import Any, ClassVar
+from enum import Enum
+from typing import Any
 
 import numpy as np
 import numpy.typing as npt
@@ -954,36 +955,22 @@ class MatrixDD:
             format_as_polar: Whether to format the edge weights in polar coordinates.
         """
 
-class BasisStates:
+class BasisStates(Enum):
     """Enumeration of basis states."""
 
-    __members__: ClassVar[dict[str, BasisStates]]
-    zero: ClassVar[BasisStates]
+    zero = ...
     r"""The computational basis state :math:`|0\rangle`."""
-    one: ClassVar[BasisStates]
+    one = ...
     r"""The computational basis state :math:`|1\rangle`."""
-    plus: ClassVar[BasisStates]
+    plus = ...
     r"""The superposition state :math:`|+\rangle = \frac{1}{\sqrt{2}}(|0\rangle + |1\rangle)`."""
-    minus: ClassVar[BasisStates]
+    minus = ...
     r"""The superposition state :math:`|-\rangle = \frac{1}{\sqrt{2}}(|0\rangle - |1\rangle)`."""
-    left: ClassVar[BasisStates]
+    left = ...
     r"""The rotational superposition state :math:`|L\rangle = \frac{1}{\sqrt{2}}(|0\rangle + i|1\rangle)`."""
-    right: ClassVar[BasisStates]
+    right = ...
     r"""The rotational superposition state :math:`|R\rangle = \frac{1}{\sqrt{2}}(|0\rangle - i|1\rangle)`."""
 
-    def __eq__(self, other: object) -> bool: ...
-    def __getstate__(self) -> int: ...
-    def __hash__(self) -> int: ...
-    def __index__(self) -> int: ...
-    def __init__(self, value: int) -> None: ...
-    def __int__(self) -> int: ...
-    def __ne__(self, other: object) -> bool: ...
-    def __setstate__(self, state: int) -> None: ...
-    @property
-    def name(self) -> str: ...
-    @property
-    def value(self) -> int: ...
-
 class Vector:
     """A class representing a vector of complex numbers.
 

mqt/core/include/mqt-core/datastructures/DirectedAcyclicGraph.hpp

@@ -38,10 +38,10 @@ public:
     closureMatrix[i][i] = true;
   }
   auto addEdge(const V& u, const V& v) -> void override {
-    if (this->mapping.find(u) == this->mapping.end()) {
+    if (!this->mapping.contains(u)) {
       addVertex(u);
     }
-    if (this->mapping.find(v) == this->mapping.end()) {
+    if (!this->mapping.contains(v)) {
       addVertex(v);
     }
     std::size_t const i = this->mapping.at(u);
@@ -62,10 +62,10 @@ public:
     }
   }
   [[nodiscard]] auto isReachable(const V& u, const V& v) const -> bool {
-    if (this->mapping.find(u) == this->mapping.end()) {
+    if (!this->mapping.contains(u)) {
       throw std::invalid_argument("Vertex u not in graph.");
     }
-    if (this->mapping.find(v) == this->mapping.end()) {
+    if (!this->mapping.contains(v)) {
       throw std::invalid_argument("Vertex v not in graph.");
     }
     return closureMatrix[this->mapping.at(u)][this->mapping.at(v)];

mqt/core/include/mqt-core/datastructures/DirectedGraph.hpp

@@ -59,7 +59,7 @@ public:
   virtual ~DirectedGraph() = default;
   virtual auto addVertex(const V& v) -> void {
     // check whether the vertex is already in the graph, if so do nothing
-    if (mapping.find(v) != mapping.end()) {
+    if (mapping.contains(v)) {
       std::stringstream ss;
       ss << "The vertex " << v << " is already in the graph.";
       throw std::invalid_argument(ss.str());
@@ -75,10 +75,10 @@ public:
     outDegrees.emplace_back(0);
   }
   virtual auto addEdge(const V& u, const V& v) -> void {
-    if (mapping.find(u) == mapping.end()) {
+    if (!mapping.contains(u)) {
       addVertex(u);
     }
-    if (mapping.find(v) == mapping.end()) {
+    if (!mapping.contains(v)) {
       addVertex(v);
     }
     const auto i = mapping.at(u);
@@ -93,7 +93,7 @@ public:
   [[nodiscard]] auto getNVertices() const -> std::size_t { return nVertices; }
   [[nodiscard]] auto getNEdges() const -> std::size_t { return nEdges; }
   [[nodiscard]] auto getInDegree(const V& v) const -> std::size_t {
-    if (mapping.find(v) == mapping.end()) {
+    if (!mapping.contains(v)) {
       std::stringstream ss;
       ss << "The vertex " << v << " is not in the graph.";
       throw std::invalid_argument(ss.str());
@@ -102,7 +102,7 @@ public:
     return inDegrees[i];
   }
   [[nodiscard]] auto getOutDegree(const V& v) const -> std::size_t {
-    if (mapping.find(v) == mapping.end()) {
+    if (!mapping.contains(v)) {
       std::stringstream ss;
       ss << "The vertex " << v << " is not in the graph.";
       throw std::invalid_argument(ss.str());
@@ -119,12 +119,12 @@ public:
                            });
   }
   [[nodiscard]] auto isEdge(const V& u, const V& v) const -> bool {
-    if (mapping.find(u) == mapping.end()) {
+    if (!mapping.contains(u)) {
       std::stringstream ss;
       ss << "The vertex " << u << " is not in the graph.";
       throw std::invalid_argument(ss.str());
     }
-    if (mapping.find(v) == mapping.end()) {
+    if (!mapping.contains(v)) {
       std::stringstream ss;
       ss << "The vertex " << v << " is not in the graph.";
       throw std::invalid_argument(ss.str());

mqt/core/include/mqt-core/datastructures/UndirectedGraph.hpp

@@ -62,7 +62,7 @@ protected:
 public:
   auto addVertex(const V& v) -> void {
     // check whether the vertex is already in the graph, if so do nothing
-    if (mapping.find(v) == mapping.end()) {
+    if (!mapping.contains(v)) {
       mapping[v] = nVertices;
       invMapping.emplace_back(v);
       ++nVertices;
@@ -80,10 +80,10 @@ public:
     }
   }
   auto addEdge(const V& u, const V& v, const E& e) -> void {
-    if (mapping.find(u) == mapping.end()) {
+    if (!mapping.contains(u)) {
       addVertex(u);
     }
-    if (mapping.find(v) == mapping.end()) {
+    if (!mapping.contains(v)) {
       addVertex(v);
     }
     const auto i = mapping.at(u);
@@ -132,7 +132,7 @@ public:
   }
   [[nodiscard]] auto getAdjacentEdges(const V& v) const
       -> std::unordered_set<std::pair<V, V>, PairHash<V, V>> {
-    if (mapping.find(v) == mapping.end()) {
+    if (!mapping.contains(v)) {
       std::stringstream ss;
       ss << "The vertex " << v << " is not in the graph.";
       throw std::invalid_argument(ss.str());
@@ -149,7 +149,7 @@ public:
     return result;
   }
   [[nodiscard]] auto getNeighbours(const V& v) const -> std::unordered_set<V> {
-    if (mapping.find(v) == mapping.end()) {
+    if (!mapping.contains(v)) {
       std::stringstream ss;
       ss << "The vertex " << v << " is not in the graph.";
       throw std::invalid_argument(ss.str());
@@ -165,7 +165,7 @@ public:
     return result;
   }
   [[nodiscard]] auto getDegree(const V& v) const -> std::size_t {
-    if (mapping.find(v) == mapping.end()) {
+    if (!mapping.contains(v)) {
       std::stringstream ss;
       ss << "The vertex " << v << " is not in the graph.";
       throw std::invalid_argument(ss.str());
@@ -182,12 +182,12 @@ public:
                            });
   }
   [[nodiscard]] auto isAdjacent(const V& u, const V& v) const -> bool {
-    if (mapping.find(u) == mapping.end()) {
+    if (!mapping.contains(u)) {
       std::stringstream ss;
       ss << "The vertex " << u << " is not in the graph.";
       throw std::invalid_argument(ss.str());
     }
-    if (mapping.find(v) == mapping.end()) {
+    if (!mapping.contains(v)) {
       std::stringstream ss;
       ss << "The vertex " << v << " is not in the graph.";
       throw std::invalid_argument(ss.str());

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 &= static_cast<uint16_t>(~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.
  *