mqt-core 3.3.2__cp314-cp314t-macosx_11_0_x86_64.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/StochasticNoiseOperationTable.hpp

@@ -0,0 +1,88 @@
+/*
+ * 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
+ */
+
+/**
+ * @file StochasticNoiseOperationTable.hpp
+ * @brief Data structure for caching computed results of stochastic operations
+ */
+
+#pragma once
+
+#include "dd/statistics/TableStatistics.hpp"
+#include "ir/Definitions.hpp"
+#include "ir/operations/OpType.hpp"
+
+#include <cassert>
+#include <cstddef>
+#include <cstdint>
+#include <vector>
+
+namespace dd {
+template <class Edge> class StochasticNoiseOperationTable {
+public:
+  explicit StochasticNoiseOperationTable(
+      const std::size_t nv,
+      const size_t numberOfStochasticOperations = qc::OpType::OpTypeEnd)
+      : nvars(nv), numberOfStochasticOperations_(numberOfStochasticOperations),
+        table(nv, std::vector<Edge>(numberOfStochasticOperations)) {
+    stats.entrySize = sizeof(Edge);
+    stats.numBuckets = nv * numberOfStochasticOperations;
+  }
+
+  /// Get a reference to the table
+  [[nodiscard]] const auto& getTable() const { return table; }
+
+  /// Get a reference to the statistics
+  [[nodiscard]] const auto& getStats() const noexcept { return stats; }
+
+  void resize(const std::size_t nq) {
+    nvars = nq;
+    table.resize(nvars, std::vector<Edge>(numberOfStochasticOperations_));
+  }
+
+  void insert(std::uint8_t kind, qc::Qubit target, const Edge& r) {
+    assert(kind <
+           numberOfStochasticOperations_); // There are new operations in
+                                           // OpType. Increase the value of
+                                           // numberOfOperations accordingly
+    table.at(target).at(kind) = r;
+    stats.trackInsert();
+  }
+
+  Edge* lookup(std::uint8_t kind, qc::Qubit target) {
+    assert(kind <
+           numberOfStochasticOperations_); // There are new operations in
+                                           // OpType. Increase the value of
+                                           // numberOfOperations accordingly
+    ++stats.lookups;
+    auto& entry = table.at(target).at(kind);
+    if (entry.w.r == nullptr) {
+      return nullptr;
+    }
+    ++stats.hits;
+    return &entry;
+  }
+
+  void clear() {
+    if (stats.numEntries > 0) {
+      for (auto& t : table) {
+        std::fill(t.begin(), t.end(), Edge{});
+      }
+      stats.numEntries = 0;
+    }
+  }
+
+private:
+  std::size_t nvars;
+  size_t numberOfStochasticOperations_;
+  std::vector<std::vector<Edge>> table;
+  TableStatistics stats{};
+};
+} // namespace dd

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

@@ -0,0 +1,121 @@
+/*
+ * 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
+ */
+
+/**
+ * @file UnaryComputeTable.hpp
+ * @brief Data structure for caching computed results of unary operations
+ */
+
+#pragma once
+
+#include "dd/statistics/TableStatistics.hpp"
+
+#include <cstddef>
+#include <functional>
+#include <stdexcept>
+#include <vector>
+
+namespace dd {
+
+/**
+ * @brief Data structure for caching computed results of unary operations
+ * @tparam OperandType type of the operation's operand
+ * @tparam ResultType type of the operation's result
+ */
+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 = 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.");
+    }
+    stats.entrySize = sizeof(Entry);
+    stats.numBuckets = numBuckets;
+    valid = std::vector(numBuckets, false);
+    table = std::vector<Entry>(numBuckets);
+  }
+
+  /// An entry in the compute table
+  struct Entry {
+    OperandType operand;
+    ResultType result;
+  };
+
+  /// Get a reference to the underlying table
+  [[nodiscard]] const auto& getTable() const { return table; }
+
+  /// Get a reference to the statistics
+  [[nodiscard]] const auto& getStats() const noexcept { return stats; }
+
+  /// Compute the hash value for a given operand
+  [[nodiscard]] std::size_t hash(const OperandType& a) const {
+    const auto mask = stats.numBuckets - 1;
+    return std::hash<OperandType>{}(a)&mask;
+  }
+
+  /**
+   * @brief Insert a new entry into the compute table
+   * @details Any existing entry for the resulting hash value will be replaced.
+   * @param operand The operand
+   * @param result The result of the operation
+   */
+  void insert(const OperandType& operand, const ResultType& result) {
+    const auto key = hash(operand);
+    if (valid[key]) {
+      ++stats.collisions;
+    } else {
+      stats.trackInsert();
+      valid[key] = true;
+    }
+    table[key] = {operand, result};
+  }
+
+  /**
+   * @brief Look up a result in the compute table
+   * @param operand The operand
+   * @return A pointer to the result if it is found, otherwise nullptr.
+   */
+  ResultType* lookup(const OperandType& operand) {
+    ResultType* result = nullptr;
+    ++stats.lookups;
+    const auto key = hash(operand);
+
+    if (!valid[key]) {
+      return result;
+    }
+
+    auto& entry = table[key];
+    if (entry.operand != operand) {
+      return result;
+    }
+
+    ++stats.hits;
+    return &entry.result;
+  }
+
+  /**
+   * @brief Clear the compute table
+   * @details Sets all entries to invalid.
+   */
+  void clear() { valid = std::vector(stats.numBuckets, false); }
+
+private:
+  /// The actual table storing the entries
+  std::vector<Entry> table;
+  /// Dynamic bitset to mark valid entries
+  std::vector<bool> valid;
+  /// Statistics of the compute table
+  TableStatistics stats{};
+};
+} // namespace dd

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

@@ -0,0 +1,243 @@
+/*
+ * 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
+ */
+
+/**
+ * @file UniqueTable.hpp
+ * @brief Data structure for uniquely storing DD nodes
+ */
+
+#pragma once
+
+#include "dd/Edge.hpp"
+#include "dd/MemoryManager.hpp"
+#include "dd/Node.hpp"
+#include "dd/statistics/UniqueTableStatistics.hpp"
+#include "ir/Definitions.hpp"
+
+#include <cstddef>
+#include <cstdint>
+#include <functional>
+#include <iostream>
+#include <nlohmann/json.hpp>
+#include <type_traits>
+#include <vector>
+
+namespace dd {
+
+/**
+ * @brief Data structure for uniquely storing DD nodes
+ */
+class UniqueTable {
+public:
+  /**
+   * @brief The initial garbage collection limit.
+   * @details The initial garbage collection limit is the number of entries that
+   * must be present in the table before garbage collection is triggered.
+   * Increasing this number reduces the number of garbage collections, but
+   * increases the memory usage.
+   */
+  static constexpr std::size_t INITIAL_GC_LIMIT = 131072U;
+
+  struct UniqueTableConfig {
+    /// The number of variables
+    std::size_t nVars = 0U;
+
+    /// The number of hash buckets to use (has to be a power of two)
+    std::size_t nBuckets = 32768;
+
+    /// The initial garbage collection limit
+    std::size_t initialGCLimit = INITIAL_GC_LIMIT;
+  };
+
+  /**
+   * @brief The default constructor
+   * @param manager The memory manager to use
+   * @param config The configuration for the unique table
+   * @details The MemoryManager shall be constructed from the same type that the
+   * unique table is then used for in the lookup method.
+   */
+  UniqueTable(MemoryManager& manager, const UniqueTableConfig& config);
+
+  void resize(std::size_t nVars);
+
+  /**
+   * @brief The hash function for the hash table.
+   * @details The hash function just combines the hashes of the edges of the
+   * node. The hash value is masked to ensure that it is in the range
+   * [0, nBuckets - 1].
+   * @param p The node to hash.
+   * @returns The hash value of the node.
+   */
+  template <class Node> [[nodiscard]] std::size_t hash(const Node& p) const {
+    static_assert(std::is_base_of_v<NodeBase, Node>,
+                  "Node must be derived from NodeBase");
+    const std::size_t mask = cfg.nBuckets - 1;
+    std::size_t key = 0U;
+    for (const auto& succ : p.e) {
+      qc::hashCombine(key, std::hash<Edge<Node>>{}(succ));
+    }
+    key &= mask;
+    return key;
+  }
+
+  template <class Node>
+  [[nodiscard]] static bool nodesAreEqual(const Node& p, const Node& q) {
+    if constexpr (std::is_same_v<Node, dNode>) {
+      return (p.e == q.e && (p.flags == q.flags));
+    } else {
+      return p.e == q.e;
+    }
+  }
+
+  // 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");
+    // there are unique terminal nodes
+    if (NodeBase::isTerminal(p)) {
+      return p;
+    }
+
+    const auto key = hash(*p);
+    const auto v = p->v;
+    ++stats[v].lookups;
+
+    // search bucket in table corresponding to hashed value for the given node
+    // and return it if found.
+    if (auto* hashedNode = searchTable(*p, key);
+        !Node::isTerminal(hashedNode)) {
+      return hashedNode;
+    }
+
+    // if node not found -> add it to front of unique table bucket
+    p->setNext(tables[v][key]);
+    tables[v][key] = p;
+    stats[v].trackInsert();
+
+    return p;
+  }
+
+  /// Get a reference to the table
+  [[nodiscard]] const auto& getTables() const { return tables; }
+
+  /// Get a reference to the statistics
+  [[nodiscard]] const auto& getStats() const noexcept { return stats; }
+
+  /// Get a reference to individual statistics
+  [[nodiscard]] const UniqueTableStatistics&
+  getStats(std::size_t idx) const noexcept;
+
+  /// Get a JSON object with the statistics
+  [[nodiscard]] nlohmann::basic_json<>
+  getStatsJson(bool includeIndividualTables = false) const;
+
+  /// Get the total number of entries
+  [[nodiscard]] std::size_t getNumEntries() const noexcept;
+
+  /// Count the number of marked entries
+  [[nodiscard]] std::size_t countMarkedEntries() const noexcept;
+
+  /**
+   * @brief Determine whether the table possibly requires garbage collection.
+   */
+  [[nodiscard]] bool possiblyNeedsCollection() const;
+
+  std::size_t garbageCollect(bool force = false);
+
+  void clear();
+
+  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;
+    for (auto it = tables.rbegin(); it != tables.rend(); ++it) {
+      auto& table = *it;
+      std::cout << "\tq" << q << ":"
+                << "\n";
+      for (std::size_t key = 0; key < table.size(); ++key) {
+        auto* p = static_cast<Node*>(table[key]);
+        if (p != nullptr) {
+          std::cout << "\tkey=" << key << ": ";
+        }
+
+        while (p != nullptr) {
+          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"
+                      << reinterpret_cast<std::uintptr_t>(e.w.i) << ")";
+          }
+          std::cout << std::dec << "\n";
+          p = p->next();
+        }
+      }
+      --q;
+    }
+  }
+
+private:
+  /// Typedef for a bucket in the table
+  using Bucket = NodeBase*;
+  /// Typedef for the table
+  using Table = std::vector<Bucket>;
+
+  UniqueTableConfig cfg;
+
+  /// The current garbage collection limit
+  std::size_t gcLimit;
+
+  /// A pointer to the memory manager for the nodes stored in the table.
+  MemoryManager* memoryManager;
+
+  /**
+   * @brief The actual tables (one for each variable)
+   * @details Each hash table is an array of buckets. Each bucket is a linked
+   * list of entries. The linked list is implemented by using the next pointer
+   * of the entries.
+   */
+  std::vector<Table> tables;
+
+  /// A collection of statistics
+  std::vector<UniqueTableStatistics> stats;
+
+  /**
+   * @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>,
+                  "Node must be derived from NodeBase");
+    const auto v = p.v;
+    Node* bucket = static_cast<Node*>(tables[v][key]);
+    while (bucket != nullptr) {
+      if (nodesAreEqual(p, *bucket)) {
+        // Match found
+        if (&p != bucket) {
+          // put node pointed to by p on available chain
+          memoryManager->returnEntry(p);
+        }
+        ++stats[v].hits;
+        return bucket;
+      }
+      ++stats[v].collisions;
+      bucket = bucket->next();
+    }
+
+    // Node not found in bucket
+    return Node::getTerminal();
+  }
+};
+
+} // namespace dd

mqt/core/include/mqt-core/dd/mqt_core_dd_export.h

@@ -0,0 +1,43 @@
+
+#ifndef MQT_CORE_DD_EXPORT_H
+#define MQT_CORE_DD_EXPORT_H
+
+#ifdef MQT_CORE_DD_STATIC_DEFINE
+#  define MQT_CORE_DD_EXPORT
+#  define MQT_CORE_DD_NO_EXPORT
+#else
+#  ifndef MQT_CORE_DD_EXPORT
+#    ifdef mqt_core_dd_EXPORTS
+        /* We are building this library */
+#      define MQT_CORE_DD_EXPORT __attribute__((visibility("default")))
+#    else
+        /* We are using this library */
+#      define MQT_CORE_DD_EXPORT __attribute__((visibility("default")))
+#    endif
+#  endif
+
+#  ifndef MQT_CORE_DD_NO_EXPORT
+#    define MQT_CORE_DD_NO_EXPORT __attribute__((visibility("hidden")))
+#  endif
+#endif
+
+#ifndef MQT_CORE_DD_DEPRECATED
+#  define MQT_CORE_DD_DEPRECATED __attribute__ ((__deprecated__))
+#endif
+
+#ifndef MQT_CORE_DD_DEPRECATED_EXPORT
+#  define MQT_CORE_DD_DEPRECATED_EXPORT MQT_CORE_DD_EXPORT MQT_CORE_DD_DEPRECATED
+#endif
+
+#ifndef MQT_CORE_DD_DEPRECATED_NO_EXPORT
+#  define MQT_CORE_DD_DEPRECATED_NO_EXPORT MQT_CORE_DD_NO_EXPORT MQT_CORE_DD_DEPRECATED
+#endif
+
+/* NOLINTNEXTLINE(readability-avoid-unconditional-preprocessor-if) */
+#if 0 /* DEFINE_NO_DEPRECATED */
+#  ifndef MQT_CORE_DD_NO_DEPRECATED
+#    define MQT_CORE_DD_NO_DEPRECATED
+#  endif
+#endif
+
+#endif /* MQT_CORE_DD_EXPORT_H */