mqt-core 3.3.2__cp314-cp314t-macosx_11_0_x86_64.whl

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

@@ -0,0 +1,57 @@
+/*
+ * 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 <cstddef>
+#include <vector>
+
+namespace qc {
+/**
+ * @brief Symmetric matrix class with same number of rows and columns that
+ * allows access by row and column but uses less memory than a full matrix
+ */
+template <typename T> class SymmetricMatrix {
+  std::vector<std::vector<T>> data;
+
+public:
+  // Constructors
+  SymmetricMatrix() = default;
+  explicit SymmetricMatrix(const size_t size) {
+    data.resize(size);
+    for (size_t i = 0; i < size; ++i) {
+      data[i].resize(i + 1);
+    }
+  }
+
+  SymmetricMatrix(const size_t size, const T& value) {
+    data.resize(size);
+    for (size_t i = 0; i < size; ++i) {
+      data[i].resize(i + 1, value);
+    }
+  }
+
+  [[nodiscard]] const T& operator()(const size_t row, const size_t col) const {
+    if (row < col) {
+      return data[col][row];
+    }
+    return data[row][col];
+  }
+
+  [[nodiscard]] T& operator()(const size_t row, const size_t col) {
+    if (row < col) {
+      return data[col][row];
+    }
+    return data[row][col];
+  }
+
+  [[nodiscard]] size_t size() const { return data.size(); }
+};
+} // namespace qc

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

@@ -0,0 +1,227 @@
+/*
+ * 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 "ir/Definitions.hpp"
+
+#include <cstddef>
+#include <functional>
+#include <numeric>
+#include <optional>
+#include <ostream>
+#include <sstream>
+#include <stdexcept>
+#include <string>
+#include <unordered_map>
+#include <unordered_set>
+#include <utility>
+#include <vector>
+
+namespace qc {
+
+/// Pairs do not provide a hash function by default, this is the replacement
+template <class T, class U> struct PairHash {
+  size_t operator()(const std::pair<T, U>& x) const {
+    return combineHash(std::hash<T>{}(x.first), std::hash<U>{}(x.second));
+  }
+};
+
+/**
+ * Class representing generic undirected directed graphs.
+ *
+ * @tparam V the type of the vertices in the graph. Must implement `operator<<`.
+ */
+template <class V, class E> class UndirectedGraph final {
+  static_assert(std::is_same_v<decltype(std::declval<std::ostream&>()
+                                        << std::declval<V>()),
+                               std::ostream&>,
+                "V must support `operator<<`.");
+
+protected:
+  // the adjecency matrix works with indices
+  std::vector<std::vector<std::optional<E>>> adjacencyMatrix{};
+  // the mapping of vertices to indices in the graph are stored in a map
+  std::unordered_map<V, std::size_t> mapping;
+  // the inverse mapping is used to get the vertex from the index
+  std::vector<V> invMapping;
+  // the number of vertices in the graph
+  std::size_t nVertices = 0;
+  // the number of edges in the graph
+  std::size_t nEdges = 0;
+  // the degrees of the vertices in the graph
+  std::vector<std::size_t> degrees;
+
+public:
+  auto addVertex(const V& v) -> void {
+    // check whether the vertex is already in the graph, if so do nothing
+    if (!mapping.contains(v)) {
+      mapping[v] = nVertices;
+      invMapping.emplace_back(v);
+      ++nVertices;
+      for (auto& row : adjacencyMatrix) {
+        row.emplace_back(std::nullopt);
+      }
+      // the first param must be a 1 not nVertices since we are using an upper
+      // triangular matrix as adjacency matrix instead of a square matrix
+      adjacencyMatrix.emplace_back(1, std::nullopt);
+      degrees.emplace_back(0);
+    } else {
+      std::stringstream ss;
+      ss << "The vertex " << v << " is already in the graph.";
+      throw std::invalid_argument(ss.str());
+    }
+  }
+  auto addEdge(const V& u, const V& v, const E& e) -> void {
+    if (!mapping.contains(u)) {
+      addVertex(u);
+    }
+    if (!mapping.contains(v)) {
+      addVertex(v);
+    }
+    const auto i = mapping.at(u);
+    const auto j = mapping.at(v);
+    if (i < j) {
+      if (adjacencyMatrix[i][j - i] == std::nullopt) {
+        ++degrees[i];
+        if (i != j) {
+          ++degrees[j];
+        }
+        ++nEdges;
+        adjacencyMatrix[i][j - i] = e;
+      } else {
+        std::stringstream ss;
+        ss << "The edge (" << i << ", " << j << ") is already in the graph.";
+        throw std::invalid_argument(ss.str());
+      }
+    } else {
+      if (adjacencyMatrix[j][i - j] == std::nullopt) {
+        ++degrees[i];
+        if (i != j) {
+          ++degrees[j];
+        }
+        ++nEdges;
+        adjacencyMatrix[j][i - j] = e;
+      } else {
+        std::stringstream ss;
+        ss << "The edge (" << j << ", " << i << ") is already in the graph.";
+        throw std::invalid_argument(ss.str());
+      }
+    }
+  }
+  [[nodiscard]] auto getNVertices() const -> std::size_t { return nVertices; }
+  [[nodiscard]] auto getNEdges() const -> std::size_t { return nEdges; }
+  [[nodiscard]] auto getEdge(const V& v, const V& u) const -> E {
+    const auto i = mapping.at(v);
+    const auto j = mapping.at(u);
+    if (i < j ? adjacencyMatrix[i][j - i] != std::nullopt
+              : adjacencyMatrix[j][i - j] != std::nullopt) {
+      return i < j ? adjacencyMatrix[i][j - i].value()
+                   : adjacencyMatrix[j][i - j].value();
+    }
+    std::stringstream ss;
+    ss << "The edge (" << v << ", " << u << ") does not exist.";
+    throw std::invalid_argument(ss.str());
+  }
+  [[nodiscard]] auto getAdjacentEdges(const V& v) const
+      -> std::unordered_set<std::pair<V, V>, PairHash<V, V>> {
+    if (!mapping.contains(v)) {
+      std::stringstream ss;
+      ss << "The vertex " << v << " is not in the graph.";
+      throw std::invalid_argument(ss.str());
+    }
+    const auto i = mapping.at(v);
+    std::unordered_set<std::pair<V, V>, PairHash<V, V>> result;
+    for (std::size_t j = 0; j < nVertices; ++j) {
+      if (i < j ? adjacencyMatrix[i][j - i] != std::nullopt
+                : adjacencyMatrix[j][i - j] != std::nullopt) {
+        const auto u = invMapping.at(j);
+        result.emplace(std::make_pair(v, u));
+      }
+    }
+    return result;
+  }
+  [[nodiscard]] auto getNeighbours(const V& v) const -> std::unordered_set<V> {
+    if (!mapping.contains(v)) {
+      std::stringstream ss;
+      ss << "The vertex " << v << " is not in the graph.";
+      throw std::invalid_argument(ss.str());
+    }
+    const auto i = mapping.at(v);
+    std::unordered_set<V> result;
+    for (std::size_t j = 0; j < nVertices; ++j) {
+      if (i < j ? adjacencyMatrix[i][j - i] != std::nullopt
+                : adjacencyMatrix[j][i - j] != std::nullopt) {
+        result.emplace(invMapping.at(j));
+      }
+    }
+    return result;
+  }
+  [[nodiscard]] auto getDegree(const V& v) const -> std::size_t {
+    if (!mapping.contains(v)) {
+      std::stringstream ss;
+      ss << "The vertex " << v << " is not in the graph.";
+      throw std::invalid_argument(ss.str());
+    }
+    const auto i = mapping.at(v);
+    return degrees[i];
+  }
+  [[nodiscard]] auto getVertices() const -> std::unordered_set<V> {
+    return std::accumulate(mapping.cbegin(), mapping.cend(),
+                           std::unordered_set<V>(),
+                           [](auto acc, const auto& v) {
+                             acc.emplace(v.first);
+                             return acc;
+                           });
+  }
+  [[nodiscard]] auto isAdjacent(const V& u, const V& v) const -> bool {
+    if (!mapping.contains(u)) {
+      std::stringstream ss;
+      ss << "The vertex " << u << " is not in the graph.";
+      throw std::invalid_argument(ss.str());
+    }
+    if (!mapping.contains(v)) {
+      std::stringstream ss;
+      ss << "The vertex " << v << " is not in the graph.";
+      throw std::invalid_argument(ss.str());
+    }
+    const auto i = mapping.at(u);
+    const auto j = mapping.at(v);
+    return (i < j && adjacencyMatrix[i][j - i] != std::nullopt) or
+           (j < i && adjacencyMatrix[j][i - j] != std::nullopt);
+  }
+  [[nodiscard]] static auto isAdjacentEdge(const std::pair<V, V>& e,
+                                           const std::pair<V, V>& f) -> bool {
+    return e.first == f.first || e.first == f.second || e.second == f.first ||
+           e.second == f.second;
+  }
+  /// Outputs a string representation of the graph in the DOT format
+  [[nodiscard]] auto toString() const -> std::string {
+    std::stringstream ss;
+    ss << "graph {\n";
+    for (const auto& [v, i] : mapping) {
+      ss << "  " << i << " [label=\"" << v << "\"];\n";
+    }
+    for (std::size_t i = 0; i < nVertices; ++i) {
+      for (std::size_t j = i + 1; j < nVertices; ++j) {
+        if (adjacencyMatrix[i][j - i] != std::nullopt) {
+          ss << "  " << i << " -- " << j << ";\n";
+        }
+      }
+    }
+    ss << "}\n";
+    return ss.str();
+  }
+  friend auto operator<<(std::ostream& os, const UndirectedGraph& g)
+      -> std::ostream& {
+    return os << g.toString(); // Using toString() method
+  }
+};
+} // namespace qc

mqt/core/include/mqt-core/datastructures/mqt_core_ds_export.h

@@ -0,0 +1,43 @@
+
+#ifndef MQT_CORE_DS_EXPORT_H
+#define MQT_CORE_DS_EXPORT_H
+
+#ifdef MQT_CORE_DS_STATIC_DEFINE
+#  define MQT_CORE_DS_EXPORT
+#  define MQT_CORE_DS_NO_EXPORT
+#else
+#  ifndef MQT_CORE_DS_EXPORT
+#    ifdef mqt_core_ds_EXPORTS
+        /* We are building this library */
+#      define MQT_CORE_DS_EXPORT __attribute__((visibility("default")))
+#    else
+        /* We are using this library */
+#      define MQT_CORE_DS_EXPORT __attribute__((visibility("default")))
+#    endif
+#  endif
+
+#  ifndef MQT_CORE_DS_NO_EXPORT
+#    define MQT_CORE_DS_NO_EXPORT __attribute__((visibility("hidden")))
+#  endif
+#endif
+
+#ifndef MQT_CORE_DS_DEPRECATED
+#  define MQT_CORE_DS_DEPRECATED __attribute__ ((__deprecated__))
+#endif
+
+#ifndef MQT_CORE_DS_DEPRECATED_EXPORT
+#  define MQT_CORE_DS_DEPRECATED_EXPORT MQT_CORE_DS_EXPORT MQT_CORE_DS_DEPRECATED
+#endif
+
+#ifndef MQT_CORE_DS_DEPRECATED_NO_EXPORT
+#  define MQT_CORE_DS_DEPRECATED_NO_EXPORT MQT_CORE_DS_NO_EXPORT MQT_CORE_DS_DEPRECATED
+#endif
+
+/* NOLINTNEXTLINE(readability-avoid-unconditional-preprocessor-if) */
+#if 0 /* DEFINE_NO_DEPRECATED */
+#  ifndef MQT_CORE_DS_NO_DEPRECATED
+#    define MQT_CORE_DS_NO_DEPRECATED
+#  endif
+#endif
+
+#endif /* MQT_CORE_DS_EXPORT_H */

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/CachedEdge.hpp

@@ -0,0 +1,174 @@
+/*
+ * 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/Complex.hpp"
+#include "dd/ComplexValue.hpp"
+#include "dd/DDDefinitions.hpp"
+
+#include <array>
+#include <complex>
+#include <cstddef>
+#include <functional>
+#include <type_traits>
+
+namespace dd {
+
+struct vNode; // NOLINT(readability-identifier-naming)
+struct mNode; // NOLINT(readability-identifier-naming)
+struct dNode; // NOLINT(readability-identifier-naming)
+class ComplexNumbers;
+class MemoryManager;
+
+template <typename T>
+using isVector = std::enable_if_t<std::is_same_v<T, vNode>, bool>;
+template <typename T>
+using isMatrix = std::enable_if_t<std::is_same_v<T, mNode>, bool>;
+template <typename T>
+using isMatrixVariant =
+    std::enable_if_t<std::is_same_v<T, mNode> || std::is_same_v<T, dNode>,
+                     bool>;
+
+/**
+ * @brief A DD node with a cached edge weight
+ * @details Some DD operations create intermediate results that are not part of
+ * the final result. To avoid storing these intermediate results in the unique
+ * table, they are represented via cached numbers.
+ * @tparam Node Type of the DD node
+ */
+template <typename Node> struct CachedEdge {
+  Node* p{};
+  ComplexValue w;
+
+  CachedEdge() = default;
+  CachedEdge(Node* n, const ComplexValue& v) : p(n), w(v) {}
+  CachedEdge(Node* n, const Complex& c)
+      : p(n), w(static_cast<ComplexValue>(c)) {}
+
+  /// Comparing two DD edges with another involves comparing the respective
+  /// pointers and checking whether the corresponding weights are "close enough"
+  /// according to a given tolerance this notion of equivalence is chosen to
+  /// counter floating point inaccuracies
+  bool operator==(const CachedEdge& other) const {
+    return p == other.p && w.approximatelyEquals(other.w);
+  }
+  bool operator!=(const CachedEdge& other) const { return !operator==(other); }
+
+  /**
+   * @brief Create a terminal edge with the given weight.
+   * @param w The weight of the terminal edge.
+   * @return A terminal edge with the given weight.
+   */
+  [[nodiscard]] static constexpr CachedEdge terminal(const ComplexValue& w) {
+    return CachedEdge{Node::getTerminal(), w};
+  }
+
+  /**
+   * @brief Create a terminal edge with the given weight.
+   * @param w The weight of the terminal edge.
+   * @return A terminal edge with the given weight.
+   */
+  [[nodiscard]] static constexpr CachedEdge
+  terminal(const std::complex<fp>& w) {
+    return CachedEdge{Node::getTerminal(), static_cast<ComplexValue>(w)};
+  }
+
+  /**
+   * @brief Create a terminal edge with the given weight.
+   * @param w The weight of the terminal edge.
+   * @return A terminal edge with the given weight.
+   */
+  [[nodiscard]] static constexpr CachedEdge terminal(const Complex& w) {
+    return terminal(static_cast<ComplexValue>(w));
+  }
+
+  /**
+   * @brief Create a zero terminal edge.
+   * @return A zero terminal edge.
+   */
+  [[nodiscard]] static constexpr CachedEdge zero() {
+    return terminal(ComplexValue(0.));
+  }
+
+  /**
+   * @brief Create a one terminal edge.
+   * @return A one terminal edge.
+   */
+  [[nodiscard]] static constexpr CachedEdge one() {
+    return terminal(ComplexValue(1.));
+  }
+
+  /**
+   * @brief Check whether this is a terminal.
+   * @return whether this is a terminal
+   */
+  [[nodiscard]] constexpr bool isTerminal() const {
+    return Node::isTerminal(p);
+  }
+
+  /**
+   * @brief Get a normalized vector DD from a fresh node and a list of edges.
+   * @tparam T template parameter to enable this method only for vNode
+   * @param p the fresh node
+   * @param e the list of edges that form the successor nodes
+   * @param mm a reference to the memory manager (for returning unused nodes)
+   * @param cn a reference to the complex number manager (for adding new
+   * complex numbers)
+   * @return the normalized vector DD
+   */
+  template <typename T = Node, isVector<T> = true>
+  static auto normalize(Node* p, const std::array<CachedEdge, RADIX>& e,
+                        MemoryManager& mm, ComplexNumbers& cn) -> CachedEdge;
+
+  /**
+   * @brief Get a normalized (density) matrix) DD from a fresh node and a list
+   * of edges.
+   * @tparam T template parameter to enable this method only for matrix nodes
+   * @param p the fresh node
+   * @param e the list of edges that form the successor nodes
+   * @param mm a reference to the memory manager (for returning unused nodes)
+   * @param cn a reference to the complex number manager (for adding new
+   * complex numbers)
+   * @return the normalized (density) matrix DD
+   */
+  template <typename T = Node, isMatrixVariant<T> = true>
+  static auto normalize(Node* p, const std::array<CachedEdge, NEDGE>& e,
+                        MemoryManager& mm, ComplexNumbers& cn) -> CachedEdge;
+
+  /**
+   * @brief Check whether the matrix represented by the DD is the identity.
+   * @tparam T template parameter to enable this function only for matrix nodes
+   * @return whether the matrix is the identity
+   */
+  template <typename T = Node, isMatrixVariant<T> = true>
+  [[nodiscard]] bool isIdentity(const bool upToGlobalPhase = true) const {
+    if (!isTerminal()) {
+      return false;
+    }
+    if (upToGlobalPhase) {
+      return !w.exactlyZero();
+    }
+    return w.exactlyOne();
+  }
+};
+
+// Deduction guide for constructor: CachedEdge(Node*, const ComplexValue&)
+template <class Node>
+CachedEdge(Node*, const ComplexValue&) -> CachedEdge<Node>;
+
+// Deduction guide for constructor: CachedEdge(Node*, const Complex&)
+template <class Node> CachedEdge(Node*, const Complex&) -> CachedEdge<Node>;
+
+} // namespace dd
+
+template <class Node> struct std::hash<dd::CachedEdge<Node>> {
+  auto operator()(dd::CachedEdge<Node> const& e) const noexcept -> std::size_t;
+};