mqt-core 3.3.2__cp312-cp312-win_amd64.whl

mqt/core/include/mqt-core/circuit_optimizer/CircuitOptimizer.hpp

@@ -0,0 +1,119 @@
+/*
+ * 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/QuantumComputation.hpp"
+#include "ir/operations/OpType.hpp"
+#include "ir/operations/Operation.hpp"
+
+#include <cstddef>
+#include <deque>
+#include <memory>
+#include <unordered_set>
+#include <vector>
+
+namespace qc {
+
+class CircuitOptimizer {
+public:
+  CircuitOptimizer() = default;
+
+  using DAG = std::vector<std::deque<std::unique_ptr<Operation>*>>;
+  using DAGIterator = std::deque<std::unique_ptr<Operation>*>::iterator;
+  using DAGReverseIterator =
+      std::deque<std::unique_ptr<Operation>*>::reverse_iterator;
+  using DAGIterators = std::vector<DAGIterator>;
+  using DAGReverseIterators = std::vector<DAGReverseIterator>;
+
+  static DAG constructDAG(QuantumComputation& qc);
+
+  static void swapReconstruction(QuantumComputation& qc);
+
+  static void singleQubitGateFusion(QuantumComputation& qc);
+
+  static void removeIdentities(QuantumComputation& qc);
+
+  static void removeOperation(QuantumComputation& qc,
+                              const std::unordered_set<OpType>& opTypes,
+                              size_t opSize);
+
+  static void removeDiagonalGatesBeforeMeasure(QuantumComputation& qc);
+
+  static void removeFinalMeasurements(QuantumComputation& qc);
+
+  static void decomposeSWAP(QuantumComputation& qc,
+                            bool isDirectedArchitecture);
+
+  static void eliminateResets(QuantumComputation& qc);
+
+  static void deferMeasurements(QuantumComputation& qc);
+
+  static void flattenOperations(QuantumComputation& qc,
+                                bool customGatesOnly = false);
+
+  static void cancelCNOTs(QuantumComputation& qc);
+
+  /**
+   * @brief Replaces all MCX gates with MCZ gates (and H gates surrounding the
+   * target qubit) in the given circuit.
+   * @param qc the quantum circuit
+   */
+  static void replaceMCXWithMCZ(QuantumComputation& qc);
+
+  /**
+   * @brief Backpropagates the output permutation through the circuit.
+   * @details Starts at the end of the circuit with a potentially incomplete
+   * output permutation and backpropagates it through the circuit until the
+   * beginning of the circuit is reached. The tracked permutation is updated
+   * with every SWAP gate and, eventually, the initial layout of the circuit is
+   * set to the tracked permutation. Any unassigned qubit in the initial layout
+   * is assigned to the first available position (favoring an identity mapping).
+   * @param qc the quantum circuit
+   */
+  static void backpropagateOutputPermutation(QuantumComputation& qc);
+
+  /**
+   * @brief Collects all operations in the circuit into blocks of a maximum
+   * size.
+   * @details The circuit is traversed and operations are collected into blocks
+   * of a maximum size. The blocks are then appended to the circuit in the order
+   * they were collected. Each block is realized as a compound operation.
+   * Light optimizations are applied to the blocks, such as removing identity
+   * gates and fusing single-qubit gates.
+   * @param qc the quantum circuit
+   * @param maxBlockSize the maximum size of a block
+   */
+  static void collectBlocks(QuantumComputation& qc, std::size_t maxBlockSize);
+
+  /**
+   * @brief Collects all Clifford blocks in the circuit.
+   * @details The circuit is traversed and all operations that are part of a
+   * Clifford block are collected into a compound operation with a certain
+   * maximum block size. All non-Clifford operations remain untouched.
+   * Light optimizations are applied to the blocks, such as removing identity
+   * gates.
+   * @param qc the quantum circuit
+   * @param maxBlockSize the maximum size of a block
+   */
+  static void collectCliffordBlocks(QuantumComputation& qc,
+                                    std::size_t maxBlockSize);
+
+  /**
+   * @brief Elide permutations by propagating them through the circuit.
+   * @details The circuit is traversed and any SWAP gate is eliminated by
+   * propagating the permutation through the circuit. The final layout of the
+   * circuit is updated accordingly. This pass works well together with the
+   * `swapReconstruction` pass.
+   * @param qc the quantum circuit
+   */
+  static void elidePermutations(QuantumComputation& qc);
+};
+} // namespace qc

mqt/core/include/mqt-core/circuit_optimizer/mqt_core_circuit_optimizer_export.h

@@ -0,0 +1,43 @@
+
+#ifndef MQT_CORE_CIRCUIT_OPTIMIZER_EXPORT_H
+#define MQT_CORE_CIRCUIT_OPTIMIZER_EXPORT_H
+
+#ifdef MQT_CORE_CIRCUIT_OPTIMIZER_STATIC_DEFINE
+#  define MQT_CORE_CIRCUIT_OPTIMIZER_EXPORT
+#  define MQT_CORE_CIRCUIT_OPTIMIZER_NO_EXPORT
+#else
+#  ifndef MQT_CORE_CIRCUIT_OPTIMIZER_EXPORT
+#    ifdef mqt_core_circuit_optimizer_EXPORTS
+        /* We are building this library */
+#      define MQT_CORE_CIRCUIT_OPTIMIZER_EXPORT __declspec(dllexport)
+#    else
+        /* We are using this library */
+#      define MQT_CORE_CIRCUIT_OPTIMIZER_EXPORT __declspec(dllimport)
+#    endif
+#  endif
+
+#  ifndef MQT_CORE_CIRCUIT_OPTIMIZER_NO_EXPORT
+#    define MQT_CORE_CIRCUIT_OPTIMIZER_NO_EXPORT 
+#  endif
+#endif
+
+#ifndef MQT_CORE_CIRCUIT_OPTIMIZER_DEPRECATED
+#  define MQT_CORE_CIRCUIT_OPTIMIZER_DEPRECATED __declspec(deprecated)
+#endif
+
+#ifndef MQT_CORE_CIRCUIT_OPTIMIZER_DEPRECATED_EXPORT
+#  define MQT_CORE_CIRCUIT_OPTIMIZER_DEPRECATED_EXPORT MQT_CORE_CIRCUIT_OPTIMIZER_EXPORT MQT_CORE_CIRCUIT_OPTIMIZER_DEPRECATED
+#endif
+
+#ifndef MQT_CORE_CIRCUIT_OPTIMIZER_DEPRECATED_NO_EXPORT
+#  define MQT_CORE_CIRCUIT_OPTIMIZER_DEPRECATED_NO_EXPORT MQT_CORE_CIRCUIT_OPTIMIZER_NO_EXPORT MQT_CORE_CIRCUIT_OPTIMIZER_DEPRECATED
+#endif
+
+/* NOLINTNEXTLINE(readability-avoid-unconditional-preprocessor-if) */
+#if 0 /* DEFINE_NO_DEPRECATED */
+#  ifndef MQT_CORE_CIRCUIT_OPTIMIZER_NO_DEPRECATED
+#    define MQT_CORE_CIRCUIT_OPTIMIZER_NO_DEPRECATED
+#  endif
+#endif
+
+#endif /* MQT_CORE_CIRCUIT_OPTIMIZER_EXPORT_H */

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

@@ -0,0 +1,117 @@
+/*
+ * 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 "DirectedGraph.hpp"
+
+#include <algorithm>
+#include <cassert>
+#include <cstddef>
+#include <sstream>
+#include <stack>
+#include <stdexcept>
+#include <vector>
+
+namespace qc {
+
+template <class V> class DirectedAcyclicGraph final : public DirectedGraph<V> {
+protected:
+  // transitive closure matrix to detect cycles
+  std::vector<std::vector<bool>> closureMatrix;
+
+public:
+  auto addVertex(const V& v) -> void override {
+    DirectedGraph<V>::addVertex(v);
+    for (auto& row : closureMatrix) {
+      row.emplace_back(false);
+    }
+    closureMatrix.emplace_back(this->nVertices, false);
+    const auto i = this->mapping.at(v);
+    closureMatrix[i][i] = true;
+  }
+  auto addEdge(const V& u, const V& v) -> void override {
+    if (!this->mapping.contains(u)) {
+      addVertex(u);
+    }
+    if (!this->mapping.contains(v)) {
+      addVertex(v);
+    }
+    std::size_t const i = this->mapping.at(u);
+    std::size_t const j = this->mapping.at(v);
+    if (closureMatrix[j][i]) {
+      std::ostringstream oss;
+      oss << "Adding edge (" << u << ", " << v << ") would create a cycle.";
+      throw std::logic_error(oss.str());
+    }
+    DirectedGraph<V>::addEdge(u, v);
+    for (std::size_t k = 0; k < this->nVertices; ++k) {
+      if (closureMatrix[k][i]) {
+        closureMatrix[k][j] = true;
+      }
+      if (closureMatrix[j][k]) {
+        closureMatrix[i][k] = true;
+      }
+    }
+  }
+  [[nodiscard]] auto isReachable(const V& u, const V& v) const -> bool {
+    if (!this->mapping.contains(u)) {
+      throw std::invalid_argument("Vertex u not in graph.");
+    }
+    if (!this->mapping.contains(v)) {
+      throw std::invalid_argument("Vertex v not in graph.");
+    }
+    return closureMatrix[this->mapping.at(u)][this->mapping.at(v)];
+  }
+  /// Perform a depth-first search on the graph and return the nodes in a
+  /// topological order
+  [[nodiscard]] auto orderTopologically() const -> std::vector<V> {
+    std::stack<std::size_t> stack{};
+    std::vector<std::size_t> result;
+    result.reserve(this->nVertices);
+    std::vector visited(this->nVertices, false);
+    // visitedInDegree is used to count the incoming edges that have been
+    // visited already such that the resulting order of the nodes is one that
+    // satisfies a topological ordering
+    std::vector<std::size_t> visitedInDegree(this->nVertices, 0);
+    // Push nodes with 0 indegree onto the stack
+    for (std::size_t k = 0; k < this->nVertices; ++k) {
+      if (this->inDegrees[k] == 0) {
+        stack.push(k);
+        visited[k] = true;
+      }
+    }
+    // Perform DFS
+    while (!stack.empty()) {
+      const auto u = stack.top();
+      stack.pop();
+      result.emplace_back(u);
+
+      for (std::size_t k = 0; k < this->nVertices; ++k) {
+        if (this->adjacencyMatrix[u][k]) {
+          if (!visited[k]) {
+            if (++visitedInDegree[k] == this->inDegrees[k]) {
+              stack.push(k);
+              visited[k] = true;
+            }
+          }
+        }
+      }
+    }
+    // Otherwise graph has a cycle
+    assert(result.size() == this->nVertices);
+    std::vector<V> vertices;
+    vertices.reserve(this->nVertices);
+    std::transform(result.cbegin(), result.cend(), std::back_inserter(vertices),
+                   [&](const auto i) { return this->invMapping.at(i); });
+    return vertices;
+  }
+};
+} // namespace qc

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

@@ -0,0 +1,158 @@
+/*
+ * 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 <numeric>
+#include <ostream>
+#include <sstream>
+#include <stdexcept>
+#include <string>
+#include <unordered_map>
+#include <unordered_set>
+#include <utility>
+#include <vector>
+
+namespace qc {
+
+/**
+ * Class representing generic directed graphs.
+ *
+ * @tparam V the type of the vertices in the graph. Must implement `operator<<`.
+ */
+template <class V> class DirectedGraph {
+  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<bool>> 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 in-degrees of the vertices in the graph
+  std::vector<std::size_t> inDegrees;
+  // the out-degrees of the vertices in the graph
+  std::vector<std::size_t> outDegrees;
+
+public:
+  DirectedGraph() = default;
+  DirectedGraph(const DirectedGraph&) = default;
+  DirectedGraph(DirectedGraph&&) = default;
+  DirectedGraph& operator=(const DirectedGraph&) = default;
+  DirectedGraph& operator=(DirectedGraph&&) = default;
+  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.contains(v)) {
+      std::stringstream ss;
+      ss << "The vertex " << v << " is already in the graph.";
+      throw std::invalid_argument(ss.str());
+    }
+    mapping[v] = nVertices;
+    invMapping.emplace_back(v);
+    ++nVertices;
+    for (auto& row : adjacencyMatrix) {
+      row.emplace_back(false);
+    }
+    adjacencyMatrix.emplace_back(nVertices, false);
+    inDegrees.emplace_back(0);
+    outDegrees.emplace_back(0);
+  }
+  virtual auto addEdge(const V& u, const V& v) -> 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 (!adjacencyMatrix[i][j]) {
+      adjacencyMatrix[i][j] = true;
+      ++outDegrees[i];
+      ++inDegrees[j];
+      ++nEdges;
+    }
+  }
+  [[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.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 inDegrees[i];
+  }
+  [[nodiscard]] auto getOutDegree(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 outDegrees[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 isEdge(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 adjacencyMatrix[i][j];
+  }
+  /// Outputs a string representation of the graph in the DOT format
+  [[nodiscard]] auto toString() const -> std::string {
+    std::stringstream ss;
+    ss << "digraph {\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 = 0; j < nVertices; ++j) {
+        if (adjacencyMatrix[i][j]) {
+          ss << "  " << i << " -> " << j << ";\n";
+        }
+      }
+    }
+    ss << "}\n";
+    return ss.str();
+  }
+  friend auto operator<<(std::ostream& os, const DirectedGraph& g)
+      -> std::ostream& {
+    return os << g.toString(); // Using toString() method
+  }
+};
+} // namespace qc

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

@@ -0,0 +1,50 @@
+/*
+ * 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 <algorithm>
+#include <cstddef>
+#include <unordered_map>
+
+namespace qc {
+template <class T> struct DisjointSet {
+  std::unordered_map<T, T> parent;
+  std::unordered_map<T, std::size_t> rank;
+
+  template <class Iterator>
+  explicit DisjointSet(const Iterator& begin, const Iterator& end) {
+    std::for_each(begin, end, [&](const auto& element) {
+      parent[element] = element;
+      rank[element] = 0;
+    });
+  }
+
+  T findSet(const T& v) {
+    if (parent[v] != v) {
+      parent[v] = findSet(parent[v]);
+    }
+    return parent[v];
+  }
+
+  void unionSet(const T& x, const T& y) {
+    const auto& xSet = findSet(x);
+    const auto& ySet = findSet(y);
+    if (rank[xSet] > rank[ySet]) {
+      parent[ySet] = xSet;
+    } else {
+      parent[xSet] = ySet;
+      if (rank[xSet] == rank[ySet]) {
+        ++rank[ySet];
+      }
+    }
+  }
+};
+} // namespace qc

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

@@ -0,0 +1,172 @@
+/*
+ * 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 "datastructures/UndirectedGraph.hpp"
+#include "ir/Definitions.hpp"
+#include "ir/QuantumComputation.hpp"
+#include "ir/operations/OpType.hpp"
+#include "ir/operations/Operation.hpp"
+
+#include <cassert>
+#include <cstddef>
+#include <cstdint>
+#include <memory>
+#include <stdexcept>
+#include <unordered_set>
+#include <vector>
+
+namespace qc {
+/**
+ * @brief Class to manage the creation of layers when traversing a quantum
+ * circuit.
+ * @details The class uses the DAG of the circuit to create layers of gates that
+ * can be executed at the same time. It can be used to create the front or look
+ * ahead layer.
+ */
+class Layer final {
+public:
+  class DAGVertex;
+  using ExecutableSet = std::unordered_set<std::shared_ptr<DAGVertex>>;
+  using InteractionGraph = UndirectedGraph<Qubit, std::shared_ptr<DAGVertex>>;
+
+  class DAGVertex : public std::enable_shared_from_this<DAGVertex> {
+  protected:
+    // if the executableCounter becomes equal to the executableThreshold the
+    // vertex becomes executable
+    std::int64_t executableThreshold = 0;
+    std::int64_t executableCounter = 0;
+    std::vector<std::shared_ptr<DAGVertex>> enabledSuccessors;
+    std::vector<std::shared_ptr<DAGVertex>> disabledSuccessors;
+    bool executed = false;
+    Operation* operation;
+    ExecutableSet* executableSet;
+
+    /**
+     * @brief Construct a new DAGVertex
+     * @details The constructor initializes the vertex with the given operation
+     * and the given executable set, which is shared among all vertices.
+     *
+     * @param op
+     * @param es
+     */
+    DAGVertex(Operation* op, ExecutableSet& es)
+        : operation(op), executableSet(&es) {}
+
+  public:
+    [[nodiscard]] static auto create(Operation* operation,
+                                     ExecutableSet& executableSet)
+        -> std::shared_ptr<DAGVertex> {
+      std::shared_ptr<DAGVertex> v(new DAGVertex(operation, executableSet));
+      v->updateExecutableSet();
+      return v;
+    }
+    [[nodiscard]] auto isExecutable() const {
+      assert(executableCounter <= executableThreshold);
+      return (!executed) && executableCounter == executableThreshold;
+    }
+    [[nodiscard]] auto isExecuted() const { return executed; }
+    [[nodiscard]] auto getOperation() const -> const Operation* {
+      return operation;
+    }
+
+  protected:
+    auto incExecutableCounter() {
+      executableCounter++;
+      updateExecutableSet();
+    }
+    auto decExecutableCounter() {
+      executableCounter--;
+      updateExecutableSet();
+    }
+    /**
+     * @brief Inserts or removes the vertex from the executable set.
+     * @warning May not be called from the constructor.
+     */
+    auto updateExecutableSet() -> void {
+      if (isExecutable()) {
+        if (const auto& it = executableSet->find(shared_from_this());
+            it == executableSet->end()) {
+          executableSet->insert(shared_from_this());
+        }
+      } else {
+        if (const auto& it = executableSet->find(shared_from_this());
+            it != executableSet->end()) {
+          executableSet->erase(it);
+        }
+      }
+    }
+
+  public:
+    auto execute() -> void {
+      if (isExecutable()) {
+        executed = true;
+        for (const auto& successor : disabledSuccessors) {
+          successor->decExecutableCounter();
+        }
+        for (const auto& successor : enabledSuccessors) {
+          successor->incExecutableCounter();
+        }
+        updateExecutableSet();
+      } else {
+        throw std::logic_error(
+            "The vertex is not executable and cannot be executed.");
+      }
+    }
+    auto addEnabledSuccessor(const std::shared_ptr<DAGVertex>& successor) {
+      enabledSuccessors.emplace_back(successor);
+      ++successor->executableThreshold;
+      successor->updateExecutableSet();
+    }
+    auto addDisabledSuccessor(const std::shared_ptr<DAGVertex>& successor) {
+      disabledSuccessors.emplace_back(successor);
+      --successor->executableThreshold;
+      successor->updateExecutableSet();
+    }
+  };
+
+protected:
+  ExecutableSet executableSet;
+  auto constructDAG(const QuantumComputation& qc, bool commutable) -> void;
+
+public:
+  Layer() = default;
+  Layer(const Layer&) = default;
+  Layer(Layer&&) = default;
+  Layer& operator=(const Layer&) = default;
+  Layer& operator=(Layer&&) = default;
+  ~Layer() = default;
+  /**
+   * @brief Constructs a new layer from the given quantum circuit.
+   * @details The layer contains all gates that are currently executable in a
+   * set of executable gates. When a gate is executed, this can enable other
+   * gates that are added to the set of executable sets then, or disable gates
+   * that are removed from the set of executable gates. The commutable flag can
+   * be used to specify whether commutation rules should be considered.
+   *
+   * @param qc         quantum circuit
+   * @param commutable true if commutation rules should be considered, false
+   * otherwise (default: true)
+   */
+  explicit Layer(const QuantumComputation& qc, bool commutable = true) {
+    constructDAG(qc, commutable);
+  }
+  [[nodiscard]] auto getExecutableSet() const -> const ExecutableSet& {
+    return executableSet;
+  }
+  [[nodiscard]] auto constructInteractionGraph(OpType opType,
+                                               std::size_t nControls) const
+      -> InteractionGraph;
+  [[nodiscard]] auto getExecutablesOfType(OpType opType,
+                                          std::size_t nControls) const
+      -> std::vector<std::shared_ptr<DAGVertex>>;
+};
+} // namespace qc