mqt-core 3.3.2__cp314-cp314t-macosx_11_0_arm64.whl

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

@@ -0,0 +1,438 @@
+/*
+ * 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/DDDefinitions.hpp"
+#include "dd/Edge.hpp"
+#include "dd/Node.hpp"
+#include "dd/RealNumber.hpp"
+
+#include <cstdint>
+#include <cstdlib>
+#include <fstream>
+#include <iostream>
+#include <queue>
+#include <sstream>
+#include <stdexcept>
+#include <string>
+#include <unordered_map>
+#include <unordered_set>
+#include <vector>
+
+namespace dd {
+
+std::string colorFromPhase(const Complex& a);
+
+fp thicknessFromMagnitude(const Complex& a);
+
+void printPhaseFormatted(std::ostream& os, fp r);
+
+std::string conditionalFormat(const Complex& a, bool formatAsPolar = true);
+
+template <class Node>
+static std::ostream& header(const Edge<Node>& e, std::ostream& os,
+                            bool edgeLabels, bool formatAsPolar = true) {
+  os << "digraph \"DD\" {graph[];node[shape=plain];edge[arrowhead=none]\n";
+  os << "root [label=\"\",shape=point,style=invis]\n";
+  os << "t [label=<<font "
+        "point-size=\"20\">1</"
+        "font>>,shape=box,tooltip=\"1\",width=0.3,height=0.3]\n";
+  auto toplabel = (reinterpret_cast<std::uintptr_t>(e.p) & 0x001fffffU) >> 1U;
+  os << "root->";
+  if (e.isTerminal()) {
+    os << "t";
+  } else {
+    os << toplabel;
+  }
+  os << "[penwidth=\"" << thicknessFromMagnitude(e.w) << "\",tooltip=\""
+     << conditionalFormat(e.w, formatAsPolar) << "\"";
+  if (!e.w.exactlyOne()) {
+    os << ",style=dashed";
+  }
+  if (edgeLabels) {
+    os << ",label=<<font point-size=\"8\">&nbsp;"
+       << conditionalFormat(e.w, formatAsPolar) << "</font>>";
+  }
+
+  os << "]\n";
+
+  return os;
+}
+template <class Node>
+static std::ostream& coloredHeader(const Edge<Node>& e, std::ostream& os,
+                                   bool edgeLabels, bool formatAsPolar = true) {
+  os << "digraph \"DD\" {graph[];node[shape=plain];edge[arrowhead=none]\n";
+  os << "root [label=\"\",shape=point,style=invis]\n";
+  os << "t [label=<<font "
+        "point-size=\"20\">1</"
+        "font>>,shape=box,tooltip=\"1\",width=0.3,height=0.3]\n";
+
+  auto toplabel = (reinterpret_cast<std::uintptr_t>(e.p) & 0x001fffffU) >> 1U;
+  auto mag = thicknessFromMagnitude(e.w);
+  auto color = colorFromPhase(e.w);
+  os << "root->";
+  if (e.isTerminal()) {
+    os << "t";
+  } else {
+    os << toplabel;
+  }
+  os << "[penwidth=\"" << mag << "\",tooltip=\""
+     << conditionalFormat(e.w, formatAsPolar) << "\",color=\"" << color << "\"";
+  if (edgeLabels) {
+    os << ",label=<<font point-size=\"8\">&nbsp;"
+       << conditionalFormat(e.w, formatAsPolar) << "</font>>";
+  }
+  os << "]\n";
+  return os;
+}
+template <class Node>
+static std::ostream& memoryHeader(const Edge<Node>& e, std::ostream& os,
+                                  bool edgeLabels) {
+  os << "digraph \"DD\" {graph[];node[shape=plain];edge[arrowhead=none]\n";
+  os << "root [label=\"\",shape=point,style=invis]\n";
+  os << "t [label=<<font "
+        "point-size=\"20\">1</"
+        "font>>,shape=box,tooltip=\"1\",width=0.3,height=0.3]\n";
+
+  auto toplabel = (reinterpret_cast<std::uintptr_t>(e.p) & 0x001fffffU) >> 1U;
+  auto mag = thicknessFromMagnitude(e.w);
+  auto color = colorFromPhase(e.w);
+  os << "root->";
+  if (e.isTerminal()) {
+    os << "t";
+  } else {
+    os << toplabel;
+  }
+  os << "[penwidth=\"" << mag << "\",tooltip=\"" << e.w.toString(false, 4)
+     << "\" color=\"" << color << "\"";
+  if (edgeLabels) {
+    os << ",label=<<font point-size=\"8\">&nbsp;[";
+    if (e.w.exactlyZero()) {
+      os << "0";
+    } else if (e.w.exactlyOne()) {
+      os << "1";
+    } else {
+      if (RealNumber::exactlyZero(e.w.r)) {
+        os << "0";
+      } else if (RealNumber::exactlySqrt2over2(e.w.r)) {
+        os << "\xe2\x88\x9a\xc2\xbd";
+      } else if (RealNumber::exactlyOne(e.w.r)) {
+        os << "1";
+      } else {
+        os << std::hex << reinterpret_cast<std::uintptr_t>(e.w.r) << std::dec;
+      }
+      os << " ";
+      if (RealNumber::exactlyZero(e.w.i)) {
+        os << "0";
+      } else if (RealNumber::exactlySqrt2over2(e.w.i)) {
+        os << "\xe2\x88\x9a\xc2\xbd";
+      } else if (RealNumber::exactlyOne(e.w.i)) {
+        os << "1";
+      } else {
+        os << std::hex << reinterpret_cast<std::uintptr_t>(e.w.i) << std::dec;
+      }
+    }
+    os << "]</font>>";
+  }
+  os << "]\n";
+  return os;
+}
+
+std::ostream& modernNode(const mEdge& e, std::ostream& os,
+                         bool formatAsPolar = true);
+std::ostream& modernNode(const vEdge& e, std::ostream& os,
+                         bool formatAsPolar = true);
+std::ostream& classicNode(const mEdge& e, std::ostream& os,
+                          bool formatAsPolar = true);
+std::ostream& classicNode(const vEdge& e, std::ostream& os,
+                          bool formatAsPolar = true);
+template <class Node>
+static std::ostream& memoryNode(const Edge<Node>& e, std::ostream& os) {
+  constexpr std::size_t n = std::tuple_size_v<decltype(e.p->e)>;
+  auto nodelabel = (reinterpret_cast<std::uintptr_t>(e.p) & 0x001fffffU) >>
+                   1U; // this allows for 2^20 (roughly 1e6) unique nodes
+  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 << "</td></tr>";
+  os << "<tr>";
+  for (std::size_t i = 0; i < n; ++i) {
+    os << "<td port=\"" << i << R"(" href="javascript:;" border="0" tooltip=")"
+       << e.p->e[i].w.toString(false, 4) << "\">";
+    if (e.p->e[i].isZeroTerminal()) {
+      os << "&nbsp;0 "
+            "";
+    } else {
+      os << "<font color=\"white\">&nbsp;0 </font>";
+    }
+    os << "</td>";
+  }
+  os << "</tr>";
+  os << "</table></font>>,tooltip=\"" << std::hex
+     << reinterpret_cast<std::uintptr_t>(e.p) << "\"]\n"
+     << std::dec;
+  return os;
+}
+
+std::ostream& bwEdge(const mEdge& from, const mEdge& to, std::uint16_t idx,
+                     std::ostream& os, bool edgeLabels = false,
+                     bool classic = false, bool formatAsPolar = true);
+std::ostream& bwEdge(const vEdge& from, const vEdge& to, std::uint16_t idx,
+                     std::ostream& os, bool edgeLabels = false,
+                     bool classic = false, bool formatAsPolar = true);
+std::ostream& coloredEdge(const mEdge& from, const mEdge& to, std::uint16_t idx,
+                          std::ostream& os, bool edgeLabels = false,
+                          bool classic = false, bool formatAsPolar = true);
+std::ostream& coloredEdge(const vEdge& from, const vEdge& to, std::uint16_t idx,
+                          std::ostream& os, bool edgeLabels = false,
+                          bool classic = false, bool formatAsPolar = true);
+template <class Node>
+static std::ostream& memoryEdge(const Edge<Node>& from, const Edge<Node>& to,
+                                std::uint16_t idx, std::ostream& os,
+                                bool edgeLabels = false) {
+  auto fromlabel =
+      (reinterpret_cast<std::uintptr_t>(from.p) & 0x001fffffU) >> 1U;
+  auto tolabel = (reinterpret_cast<std::uintptr_t>(to.p) & 0x001fffffU) >> 1U;
+
+  os << fromlabel << ":" << idx << ":s->";
+  if (to.isTerminal()) {
+    os << "t";
+  } else {
+    os << tolabel;
+  }
+
+  auto mag = thicknessFromMagnitude(to.w);
+  auto color = colorFromPhase(to.w);
+  os << "[penwidth=\"" << mag << "\",tooltip=\"" << to.w.toString(false, 4)
+     << "\" color=\"" << color << "\"";
+  if (edgeLabels) {
+    os << ",label=<<font point-size=\"8\">&nbsp;[";
+    if (to.w.exactlyOne()) {
+      os << "1";
+    } else {
+      if (RealNumber::exactlyZero(to.w.r)) {
+        os << "0";
+      } else if (RealNumber::exactlySqrt2over2(to.w.r)) {
+        os << "\xe2\x88\x9a\xc2\xbd";
+      } else if (RealNumber::exactlyOne(to.w.r)) {
+        os << "1";
+      } else {
+        os << std::hex << reinterpret_cast<std::uintptr_t>(to.w.r) << std::dec;
+      }
+      os << " ";
+      if (RealNumber::exactlyZero(to.w.i)) {
+        os << "0";
+      } else if (RealNumber::exactlySqrt2over2(to.w.i)) {
+        os << "\xe2\x88\x9a\xc2\xbd";
+      } else if (RealNumber::exactlyOne(to.w.i)) {
+        os << "1";
+      } else {
+        os << std::hex << reinterpret_cast<std::uintptr_t>(to.w.i) << std::dec;
+      }
+    }
+    os << "]</font>>";
+  }
+  os << "]\n";
+
+  return os;
+}
+
+template <class Node>
+static void toDot(const Edge<Node>& e, std::ostream& os, bool colored = true,
+                  bool edgeLabels = false, bool classic = false,
+                  bool memory = false, bool formatAsPolar = true) {
+  std::ostringstream oss{};
+  // header, root and terminal declaration
+
+  if (memory) {
+    memoryHeader(e, oss, edgeLabels);
+  } else if (colored) {
+    coloredHeader(e, oss, edgeLabels, formatAsPolar);
+  } else {
+    header(e, oss, edgeLabels, formatAsPolar);
+  }
+
+  std::unordered_set<decltype(e.p)> nodes{};
+
+  auto priocmp = [](const Edge<Node>* left, const Edge<Node>* right) {
+    if (left->p == nullptr) {
+      return right->p != nullptr;
+    }
+    if (right->p == nullptr) {
+      return false;
+    }
+    return left->p->v < right->p->v;
+  };
+
+  std::priority_queue<const Edge<Node>*, std::vector<const Edge<Node>*>,
+                      decltype(priocmp)>
+      q(priocmp);
+  q.push(&e);
+
+  // bfs until finished
+  while (!q.empty()) {
+    auto node = q.top();
+    q.pop();
+
+    // base case
+    if (node->isTerminal()) {
+      continue;
+    }
+
+    // check if node has already been processed
+    auto ret = nodes.emplace(node->p);
+    if (!ret.second) {
+      continue;
+    }
+
+    // node definition as HTML-like label (href="javascript:;" is used as
+    // workaround to make tooltips work)
+    if (memory) {
+      memoryNode(*node, oss);
+    } else if (classic) {
+      classicNode(*node, oss, formatAsPolar);
+    } else {
+      modernNode(*node, oss, formatAsPolar);
+    }
+
+    // iterate over edges in reverse to guarantee correct processing order
+    for (auto i = static_cast<std::int16_t>(node->p->e.size() - 1); i >= 0;
+         --i) {
+      auto& edge = node->p->e[static_cast<std::size_t>(i)];
+      if ((!memory && edge.w.approximatelyZero()) || edge.w.exactlyZero()) {
+        // potentially add zero stubs here
+        continue;
+      }
+
+      // non-zero edge to be included
+      q.push(&edge);
+
+      if (memory) {
+        memoryEdge(*node, edge, static_cast<std::uint16_t>(i), oss, edgeLabels);
+      } else if (colored) {
+        coloredEdge(*node, edge, static_cast<std::uint16_t>(i), oss, edgeLabels,
+                    classic, formatAsPolar);
+      } else {
+        bwEdge(*node, edge, static_cast<std::uint16_t>(i), oss, edgeLabels,
+               classic, formatAsPolar);
+      }
+    }
+  }
+  oss << "}\n";
+
+  os << oss.str() << std::flush;
+}
+
+template <class Node>
+[[maybe_unused]] static void
+export2Dot(Edge<Node> basic, const std::string& outputFilename,
+           bool colored = true, bool edgeLabels = false, bool classic = false,
+           bool memory = false, bool show = true, bool formatAsPolar = true) {
+  std::ofstream init(outputFilename);
+  toDot(basic, init, colored, edgeLabels, classic, memory, formatAsPolar);
+  init.close();
+
+  if (show) {
+    std::ostringstream oss;
+    oss << "dot -Tsvg " << outputFilename << " -o "
+        << outputFilename.substr(0, outputFilename.find_last_of('.')) << ".svg";
+    const auto str =
+        oss.str(); // required to avoid immediate deallocation of temporary
+    const auto exitCode = std::system(str.c_str());
+    if (exitCode != 0) {
+      std::cerr << "Error: dot returned with exit code " << exitCode << "\n";
+    }
+  }
+}
+
+///
+/// Serialization
+/// Note: do not rely on the binary format being portable across different
+/// architectures/platforms
+///
+
+void serialize(const vEdge& basic, std::ostream& os, bool writeBinary = false);
+
+void serializeMatrix(const mEdge& basic, std::int64_t& idx,
+                     std::unordered_map<mNode*, std::int64_t>& nodeIndex,
+                     std::unordered_set<mNode*>& visited, std::ostream& os,
+                     bool writeBinary = false);
+void serialize(const mEdge& basic, std::ostream& os, bool writeBinary = false);
+template <class Node>
+static void serialize(const Edge<Node>& basic,
+                      const std::string& outputFilename,
+                      bool writeBinary = false) {
+  std::ofstream ofs = std::ofstream(outputFilename, std::ios::binary);
+
+  if (!ofs.good()) {
+    throw std::invalid_argument("Cannot open file: " + outputFilename);
+  }
+
+  serialize(basic, ofs, writeBinary);
+}
+
+template <typename Node>
+static void exportEdgeWeights(const Edge<Node>& edge, std::ostream& stream) {
+  struct Priocmp {
+    bool operator()(const Edge<Node>* left, const Edge<Node>* right) {
+      if (left->p == nullptr) {
+        return right->p != nullptr;
+      }
+      if (right->p == nullptr) {
+        return false;
+      }
+      return left->p->v < right->p->v;
+    }
+  };
+  stream << std::showpos << RealNumber::val(edge.w.r)
+         << RealNumber::val(edge.w.i) << std::noshowpos << "i\n";
+
+  std::unordered_set<decltype(edge.p)> nodes{};
+
+  std::priority_queue<const Edge<Node>*, std::vector<const Edge<Node>*>,
+                      Priocmp>
+      q;
+  q.push(&edge);
+
+  // bfs until finished
+  while (!q.empty()) {
+    auto edgePtr = q.top();
+    q.pop();
+
+    // base case
+    if (edgePtr->isTerminal()) {
+      continue;
+    }
+
+    // check if edgePtr has already been processed
+    if (auto ret = nodes.emplace(edgePtr->p); !ret.second) {
+      continue;
+    }
+
+    // iterate over edges in reverse to guarantee correct processing order
+    for (auto i = static_cast<std::int16_t>(edgePtr->p->e.size() - 1); i >= 0;
+         --i) {
+      auto& child = edgePtr->p->e[static_cast<std::size_t>(i)];
+      if (child.w.approximatelyZero()) {
+        // potentially add zero stubs here
+        continue;
+      }
+
+      // non-zero child to be included
+      q.push(&child);
+      stream << std::showpos << RealNumber::val(child.w.r)
+             << RealNumber::val(child.w.i) << std::noshowpos << "i\n";
+    }
+  }
+}
+
+} // namespace dd

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

@@ -0,0 +1,75 @@
+/*
+ * 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/Package_fwd.hpp"
+
+namespace qc {
+class QuantumComputation;
+}
+
+namespace dd {
+/**
+ * @brief Sequentially build a decision diagram representation for the
+ * functionality of a purely-quantum @ref qc::QuantumComputation.
+ *
+ * @details For a circuit \f$G\f$ with \f$|G|\f$ gates
+ * \f$g_0, g_1, \ldots, g_{|G|-1}\f$, the functionality of \f$G\f$ is defined as
+ * the unitary matrix \f$U\f$ such that
+ * \f[
+ * U = U_{|G|-1}) \cdot U_{|G|-2} \cdot \ldots \cdot U_1 \cdot U_0,
+ * \f]
+ * where \f$U_i\f$ is the unitary matrix corresponding to gate \f$g_i\f$.
+ * For an \f$n\f$-qubit quantum computation, \f$U\f$ is a \f$2^n \times 2^n\f$
+ * matrix.
+ *
+ * By representing every single operation in the circuit as a decision diagram
+ * instead of a unitary matrix and performing the matrix multiplication directly
+ * using decision diagrams, a representation of the functionality of a quantum
+ * computation can oftentimes be computed more efficiently in terms of memory
+ * and runtime.
+ *
+ * This function effectively computes
+ * \f[
+ * DD(U) = DD(g_{|G|-1}) \otimes DD(g_{|G|-2}) \otimes \ldots \otimes DD(g_0)
+ * \f]
+ * by sequentially applying the decision diagrams of the gates in the circuit to
+ * the current decision diagram representing the functionality of the quantum
+ * computation.
+ *
+ * @param qc The quantum computation to construct the functionality for
+ * @param dd The DD package to use for the construction
+ * @return The matrix diagram representing the functionality of the quantum
+ * computation
+ */
+MatrixDD buildFunctionality(const qc::QuantumComputation& qc, Package& dd);
+
+/**
+ * @brief Recursively build a decision diagram representation for the
+ * functionality of a purely-quantum @ref qc::QuantumComputation.
+ *
+ * @see buildFunctionality
+ * @details Instead of sequentially applying the decision diagrams of the gates
+ * in the circuit, this function builds a binary computation tree out of the
+ * decision diagrams of the gates in the circuit.
+ * This results in a recursive pairwise grouping that can be more memory and
+ * runtime efficient compared to the sequential approach.
+ * @see https://arxiv.org/abs/2103.08281
+ *
+ * @param qc The quantum computation to construct the functionality for
+ * @param dd The DD package to use for the construction
+ * @return The matrix diagram representing the functionality of the quantum
+ * computation
+ */
+MatrixDD buildFunctionalityRecursive(const qc::QuantumComputation& qc,
+                                     Package& dd);
+
+} // namespace dd

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

@@ -0,0 +1,43 @@
+/*
+ * 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/DDDefinitions.hpp"
+#include "ir/operations/OpType.hpp"
+
+#include <vector>
+
+namespace dd {
+
+/// Single-qubit gate matrix for collapsing a qubit to the |0> state
+constexpr GateMatrix MEAS_ZERO_MAT{1, 0, 0, 0};
+/// Single-qubit gate matrix for collapsing a qubit to the |1> state
+constexpr GateMatrix MEAS_ONE_MAT{0, 0, 0, 1};
+
+/**
+ * @brief Converts a given quantum operation to a single-qubit gate matrix
+ * @param t The quantum operation to convert
+ * @param params The parameters of the quantum operation
+ * @return The single-qubit gate matrix representation of the quantum operation
+ */
+GateMatrix opToSingleQubitGateMatrix(qc::OpType t,
+                                     const std::vector<fp>& params = {});
+
+/**
+ * @brief Converts a given quantum operation to a two-qubit gate matrix
+ * @param t The quantum operation to convert
+ * @param params The parameters of the quantum operation
+ * @return The two-qubit gate matrix representation of the quantum operation
+ */
+TwoQubitGateMatrix opToTwoQubitGateMatrix(qc::OpType t,
+                                          const std::vector<fp>& params = {});
+
+} // namespace dd

mqt/core/include/mqt-core/dd/LinkedListBase.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
+ */
+
+/** @file
+ * @brief Linked list functionality required for UniqueTable and MemoryManager.
+ */
+
+#pragma once
+
+namespace dd {
+
+/**
+ * @brief A class to provide a base for linked list objects
+ */
+struct LLBase {
+  /**
+   * @brief The pointer to the next object
+   * @details The next pointer is used to form linked lists of objects.
+   * Classes used in a linked list must solely inherit from this class.
+   * Other code in mqt-core relies on the assumption that all objects in a
+   * linked list are of the same type.
+   */
+  LLBase* next_ = nullptr;
+
+  /**
+   * @brief Default getter for the next object
+   * @details Classes that inherit from LLBase should implement their own next()
+   * method to return the next object in the list with a specialized return
+   * type.
+   * @return LLBase*
+   */
+  [[nodiscard]] LLBase* next() const noexcept { return next_; }
+
+  /// Setter for the next object
+  void setNext(LLBase* n) noexcept { next_ = n; }
+};
+
+} // namespace dd