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

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

@@ -0,0 +1,143 @@
+/*
+ * 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"
+
+#include <cstddef>
+#include <cstdint>
+#include <vector>
+
+namespace dd {
+/**
+ * @brief Construct the all-zero state \f$|0...0\rangle\f$
+ * @param n The number of qubits.
+ * @param dd The DD package to use for making the vector DD.
+ * @param start The starting qubit index. Default is 0.
+ * @throws `std::invalid_argument`, if `dd.qubits() < n`.
+ * @return A vector DD for the all-zero state.
+ */
+VectorDD makeZeroState(std::size_t n, Package& dd, 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 dd The DD package to use for making the vector DD.
+ * @param start The starting qubit index. Default is 0.
+ * @throws `std::invalid_argument`, if `dd.qubits() < n` or `size(state) < n`.
+ * @return A vector DD for the computational basis state.
+ */
+VectorDD makeBasisState(std::size_t n, const std::vector<bool>& state,
+                        Package& dd, 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 dd The DD package to use for making the vector DD.
+ * @param start The starting qubit index. Default is 0.
+ * @throws `std::invalid_argument`, if `dd.qubits() < n` or `size(state) < n`.
+ * @return A vector DD for the product state.
+ */
+VectorDD makeBasisState(std::size_t n, const std::vector<BasisStates>& state,
+                        Package& dd, std::size_t start = 0);
+
+/**
+ * @brief Construct a GHZ state \f$|0...0\rangle + |1...1\rangle\f$.
+ * @param n The number of qubits.
+ * @param dd The DD package to use for making the vector DD.
+ * @throws `std::invalid_argument`, if `dd.qubits() < n`.
+ * @return A vector DD for the GHZ state.
+ */
+VectorDD makeGHZState(std::size_t n, Package& dd);
+
+/**
+ * @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.
+ * @param dd The DD package to use for making the vector DD.
+ * @throws `std::invalid_argument`, if `dd.qubits() < n` or the number of qubits
+ * and currently set tolerance would lead to an underflow.
+ * @return A vector DD for the W state.
+ */
+VectorDD makeWState(std::size_t n, Package& dd);
+
+/**
+ * @brief Construct a decision diagram from an arbitrary state vector.
+ * @param vec The state vector to convert to a DD.
+ * @param dd The DD package to use for making the vector DD.
+ * @throws `std::invalid_argument`, if `vec.size()` is not a power of two or
+ * `dd.qubits() < log2(vec.size()) - 1`.
+ * @return A vector DD representing the state.
+ */
+VectorDD makeStateFromVector(const CVec& vec, Package& dd);
+
+/// @brief The strategy to wire two layers.
+enum GenerationWireStrategy : std::uint8_t {
+  ROUNDROBIN, // Choose nodes in the next layer in a round-robin fashion.
+  RANDOM      // Randomly choose nodes in the next layer.
+};
+
+/**
+ * @brief Generate exponentially large vector DD.
+ * @param levels The number of levels in the vector DD.
+ * @param dd The DD package to use for generating the vector DD.
+ * @throws `std::invalid_argument`, if `dd.qubits() < levels`.
+ * @return The exponentially large vector DD.
+ */
+VectorDD generateExponentialState(std::size_t levels, Package& dd);
+
+/**
+ * @brief Generate exponentially large vector DD. Use @p seed for randomization.
+ * @param levels The number of levels in the vector DD.
+ * @param dd The DD package to use for generating the vector DD.
+ * @param seed The seed used for randomization.
+ * @throws `std::invalid_argument`, if `dd.qubits() < levels`.
+ * @return The exponentially large vector DD.
+ */
+VectorDD generateExponentialState(std::size_t levels, Package& dd,
+                                  std::size_t seed);
+
+/**
+ * @brief Generate random vector DD.
+ * @param levels The number of levels in the vector DD.
+ * @param nodesPerLevel The number of nodes per level.
+ * @param strategy The strategy to wire two layers.
+ * @param dd The DD package to use for generating the vector DD.
+ * @throws `std::invalid_argument`, if `dd.qubits() < levels`.
+ * @return The random vector DD.
+ */
+VectorDD generateRandomState(std::size_t levels,
+                             const std::vector<std::size_t>& nodesPerLevel,
+                             GenerationWireStrategy strategy, Package& dd);
+
+/**
+ * @brief Generate random vector DD. Use @p seed for randomization.
+ * @param levels The number of levels in the vector DD.
+ * @param nodesPerLevel The number of nodes per level.
+ * @param strategy The strategy to wire two layers.
+ * @param dd The DD package to use for generating the vector DD.
+ * @param seed The seed used for randomization.
+ * @throws `std::invalid_argument`, if `dd.qubits() < levels`, `levels <= 0`, or
+ * `nodesPerLevel.size() != levels`.
+ * @return The random vector DD.
+ */
+VectorDD generateRandomState(std::size_t levels,
+                             const std::vector<std::size_t>& nodesPerLevel,
+                             GenerationWireStrategy strategy, Package& dd,
+                             std::size_t seed);
+}; // namespace dd

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

@@ -29,11 +29,13 @@ namespace dd {
  * @tparam OperandType type of the operation's operand
  * @tparam ResultType type of the operation's result
  */
-template <class OperandType, class ResultType, std::size_t NBUCKET = 32768>
-class UnaryComputeTable {
+template <class OperandType, class ResultType> class UnaryComputeTable {
 public:
+  /// Default number of buckets for the compute table
+  static constexpr std::size_t DEFAULT_NUM_BUCKETS = 32768U;
+
   /// Default constructor
-  explicit UnaryComputeTable(const size_t numBuckets = 32768U) {
+  explicit UnaryComputeTable(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.");
@@ -106,7 +108,7 @@ public:
    * @brief Clear the compute table
    * @details Sets all entries to invalid.
    */
-  void clear() { valid = std::vector(NBUCKET, false); }
+  void clear() { valid = std::vector(stats.numBuckets, false); }
 
 private:
   /// The actual table storing the entries

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

@@ -96,10 +96,8 @@ public:
     }
   }
 
-  // lookup a node in the unique table for the appropriate variable; insert it,
-  // if it has not been found NOTE: reference counting is to be adjusted by
-  // function invoking the table lookup and only normalized nodes shall be
-  // stored.
+  // Lookup a node in the unique table for the appropriate variable and insert
+  // it if it has not been found. Only normalized nodes shall be stored.
   template <class Node> [[nodiscard]] Node* lookup(Node* p) {
     static_assert(std::is_base_of_v<NodeBase, Node>,
                   "Node must be derived from NodeBase");
@@ -144,42 +142,19 @@ public:
   /// Get the total number of entries
   [[nodiscard]] std::size_t getNumEntries() const noexcept;
 
-  /// Get the total number of active entries
-  [[nodiscard]] std::size_t getNumActiveEntries() const noexcept;
+  /// Count the number of marked entries
+  [[nodiscard]] std::size_t countMarkedEntries() const noexcept;
 
-  /// Get the peak total number of active entries
-  [[nodiscard]] std::size_t getPeakNumActiveEntries() const noexcept;
-
-  /**
-   * @brief Increment the reference count of a node.
-   * @details This is a pass-through function that calls the increment function
-   * of the node. 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 p A pointer to the node to increase the reference count of.
-   * @returns Whether the reference count was increased.
-   * @see Node::incRef(Node*)
-   */
-  [[nodiscard]] bool incRef(NodeBase* p) noexcept;
   /**
-   * @brief Decrement the reference count of a node.
-   * @details This is a pass-through function that calls the decrement function
-   * of the node. 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 p A pointer to the node to decrease the reference count of.
-   * @returns Whether the reference count was decreased.
-   * @see Node::decRef(Node*)
+   * @brief Determine whether the table possibly requires garbage collection.
    */
-  [[nodiscard]] bool decRef(NodeBase* p) noexcept;
-
   [[nodiscard]] bool possiblyNeedsCollection() const;
 
   std::size_t garbageCollect(bool force = false);
 
   void clear();
 
-  template <class Node> void print() {
+  template <class Node> void print() const {
     static_assert(std::is_base_of_v<NodeBase, Node>,
                   "Node must be derived from NodeBase");
     auto q = cfg.nVars - 1U;
@@ -194,8 +169,8 @@ public:
         }
 
         while (p != nullptr) {
-          std::cout << "\t\t" << std::hex << reinterpret_cast<std::uintptr_t>(p)
-                    << std::dec << " " << p->ref << std::hex;
+          std::cout << "\t\t" << std::hex
+                    << reinterpret_cast<std::uintptr_t>(p);
           for (const auto& e : p->e) {
             std::cout << " p" << reinterpret_cast<std::uintptr_t>(e.p) << "(r"
                       << reinterpret_cast<std::uintptr_t>(e.w.r) << " i"
@@ -235,12 +210,11 @@ private:
   std::vector<UniqueTableStatistics> stats;
 
   /**
-  Searches for a node in the hash table with the given key.
-  @param p The node to search for.
-  @param key The hashed value used to search the table.
-  @return The Edge<Node> found in the hash table or Edge<Node>::zero if not
-  found.
-  **/
+   * @brief Search for a node in the hash table with the given key.
+   * @param p The node to search for.
+   * @param key The hashed value used to search the table.
+   * @returns A pointer to the node if found or Node::getTerminal() otherwise.
+   */
   template <class Node>
   [[nodiscard]] Node* searchTable(Node& p, const std::size_t& key) {
     static_assert(std::is_base_of_v<NodeBase, Node>,

mqt/core/include/mqt-core/dd/statistics/PackageStatistics.hpp

@@ -20,13 +20,14 @@ namespace dd {
 
 /**
  * @brief Computes an estimate for the memory usage of active DDs.
- * @details The estimate is based on the number of active entries in the
- * respective unique tables. It accounts for the memory used by DD nodes, DD
- * edges, and real numbers.
+ * @details The estimate is based on the number of active entries which are
+ * computed by temporarily marking all nodes reachable from the current root
+ * set and subsequently counting them in the unique tables. It accounts for the
+ * memory used by DD nodes, DD edges, and real numbers.
  * @param package The package instance
  * @return The estimated memory usage in MiB
  */
-[[nodiscard]] double computeActiveMemoryMiB(const Package& package);
+[[nodiscard]] double computeActiveMemoryMiB(Package& package);
 
 /**
  * @brief Computes an estimate for the peak memory usage of DDs.
@@ -39,7 +40,7 @@ namespace dd {
 [[nodiscard]] double computePeakMemoryMiB(const Package& package);
 
 [[nodiscard]] nlohmann::basic_json<>
-getStatistics(const Package& package, bool includeIndividualTables = false);
+getStatistics(Package& package, bool includeIndividualTables = false);
 
 /**
  * @brief Get some key statistics about data structures used by the DD package
@@ -47,8 +48,8 @@ getStatistics(const Package& package, bool includeIndividualTables = false);
  */
 [[nodiscard]] nlohmann::basic_json<> getDataStructureStatistics();
 
-[[nodiscard]] std::string getStatisticsString(const Package& package);
+[[nodiscard]] std::string getStatisticsString(Package& package);
 
-void printStatistics(const Package& package, std::ostream& os = std::cout);
+void printStatistics(Package& package, std::ostream& os = std::cout);
 
 } // namespace dd

mqt/core/include/mqt-core/dd/statistics/UniqueTableStatistics.hpp

@@ -18,19 +18,9 @@
 namespace dd {
 /// \brief A class for storing statistics of a unique table
 struct UniqueTableStatistics : public TableStatistics {
-  /**
-   * @brief The total number of active entries
-   * @details An entry is considered active if it has a non-zero reference count
-   */
-  std::size_t numActiveEntries = 0U;
-  /// The peak number of active entries in the table
-  std::size_t peakNumActiveEntries = 0U;
   /// The number of garbage collection runs
   std::size_t gcRuns = 0U;
 
-  /// Track a new active entry
-  void trackActiveEntry() noexcept;
-
   /// Reset all statistics (except for the peak values)
   void reset() noexcept override;
 

mqt/core/include/mqt-core/ir/QuantumComputation.hpp

@@ -124,6 +124,9 @@ public:
   [[nodiscard]] decltype(mt)& getGenerator() noexcept { return mt; }
 
   [[nodiscard]] fp getGlobalPhase() const noexcept { return globalPhase; }
+  [[nodiscard]] bool hasGlobalPhase() const noexcept {
+    return std::abs(getGlobalPhase()) > 0;
+  }
 
   [[nodiscard]] const std::unordered_set<sym::Variable>&
   getVariables() const noexcept {

mqt/core/include/mqt-core/ir/operations/CompoundOperation.hpp

@@ -48,6 +48,8 @@ public:
 
   [[nodiscard]] std::unique_ptr<Operation> clone() const override;
 
+  [[nodiscard]] size_t getNqubits() const override;
+
   [[nodiscard]] bool isCompoundOperation() const noexcept override;
 
   [[nodiscard]] bool isNonUnitaryOperation() const override;

mqt/core/include/mqt-core/ir/operations/Expression.hpp

@@ -210,7 +210,7 @@ public:
    */
   [[nodiscard]] bool
   totalAssignment(const VariableAssignment& assignment) const {
-    return assignment.find(getVar()) != assignment.end();
+    return assignment.contains(getVar());
   }
 
   /**

mqt/core/include/mqt-core/ir/operations/Operation.hpp

@@ -68,8 +68,8 @@ public:
   [[nodiscard]] virtual std::size_t getNcontrols() const {
     return controls.size();
   }
-  [[nodiscard]] std::size_t getNqubits() const {
-    return getUsedQubits().size();
+  [[nodiscard]] virtual std::size_t getNqubits() const {
+    return getNcontrols() + getNtargets();
   }
 
   [[nodiscard]] const std::vector<fp>& getParameter() const {