✨ Heuristic Mapping Pass

mlir/include/mlir/CMakeLists.txt

@@ -6,5 +6,6 @@
 #
 # Licensed under the MIT License
 
-add_subdirectory(Dialect)
 add_subdirectory(Conversion)
+add_subdirectory(Dialect)
+add_subdirectory(Passes)

mlir/include/mlir/Passes/CMakeLists.txt

@@ -0,0 +1,12 @@
+# Copyright (c) 2023 - 2026 Chair for Design Automation, TUM
+# Copyright (c) 2025 - 2026 Munich Quantum Software Company GmbH
+# All rights reserved.
+#
+# SPDX-License-Identifier: MIT
+#
+# Licensed under the MIT License
+
+set(LLVM_TARGET_DEFINITIONS Passes.td)
+mlir_tablegen(Passes.h.inc -gen-pass-decls -name QCO)
+add_public_tablegen_target(QcoPassesIncGen)
+add_mlir_doc(Passes QcoPasses Passes/ -gen-pass-doc)

mlir/include/mlir/Passes/Mapping/Architecture.h

@@ -0,0 +1,90 @@
+/*
+ * Copyright (c) 2023 - 2026 Chair for Design Automation, TUM
+ * Copyright (c) 2025 - 2026 Munich Quantum Software Company GmbH
+ * All rights reserved.
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * Licensed under the MIT License
+ */
+
+#pragma once
+
+#include <cstddef>
+#include <llvm/ADT/DenseSet.h>
+#include <llvm/ADT/SmallVector.h>
+#include <llvm/ADT/Twine.h>
+#include <llvm/Support/ErrorHandling.h>
+#include <mlir/Support/LLVM.h>
+#include <string>
+#include <utility>
+
+/**
+ * @brief A quantum accelerator's architecture.
+ */
+class [[nodiscard]] Architecture {
+public:
+  using CouplingSet = mlir::DenseSet<std::pair<std::size_t, std::size_t>>;
+  using NeighbourVector = mlir::SmallVector<mlir::SmallVector<std::size_t, 4>>;
+
+  explicit Architecture(std::string name, std::size_t nqubits,
+                        CouplingSet couplingSet)
+      : name_(std::move(name)), nqubits_(nqubits),
+        couplingSet_(std::move(couplingSet)), neighbours_(nqubits),
+        dist_(nqubits, mlir::SmallVector<std::size_t>(nqubits, UINT64_MAX)),
+        prev_(nqubits, mlir::SmallVector<std::size_t>(nqubits, UINT64_MAX)) {
+    floydWarshallWithPathReconstruction();
+    collectNeighbours();
+  }
+
+  /**
+   * @brief Return the architecture's name.
+   */
+  [[nodiscard]] std::string_view name() const;
+
+  /**
+   * @brief Return the architecture's number of qubits.
+   */
+  [[nodiscard]] std::size_t nqubits() const;
+
+  /**
+   * @brief Return true if @p u and @p v are adjacent.
+   */
+  [[nodiscard]] bool areAdjacent(std::size_t u, std::size_t v) const;
+
+  /**
+   * @brief Return the length of the shortest path between @p u and @p v.
+   */
+  [[nodiscard]] std::size_t distanceBetween(std::size_t u, std::size_t v) const;
+
+  /**
+   * @brief Collect all neighbours of @p u.
+   */
+  [[nodiscard]] mlir::SmallVector<std::size_t, 4>
+  neighboursOf(std::size_t u) const;
+
+private:
+  using Matrix = mlir::SmallVector<mlir::SmallVector<std::size_t, 0>, 0>;
+
+  /**
+   * @brief Find all shortest paths in the coupling map between two qubits.
+   * @details Vertices are the qubits. Edges connected two qubits. Has a time
+   * and memory complexity of O(nqubits^3) and O(nqubits^2), respectively.
+   * @link Adapted from https://en.wikipedia.org/wiki/Floyd–Warshall_algorithm
+   */
+  void floydWarshallWithPathReconstruction();
+
+  /**
+   * @brief Collect the neighbours of all qubits.
+   * @details Has a time complexity of O(nqubits)
+   */
+  void collectNeighbours();
+
+  std::string name_;
+  std::size_t nqubits_;
+  CouplingSet couplingSet_;
+  NeighbourVector neighbours_;
+
+  Matrix dist_;
+  Matrix prev_;
+};

mlir/include/mlir/Passes/Passes.h

@@ -0,0 +1,32 @@
+/*
+ * Copyright (c) 2023 - 2026 Chair for Design Automation, TUM
+ * Copyright (c) 2025 - 2026 Munich Quantum Software Company GmbH
+ * All rights reserved.
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * Licensed under the MIT License
+ */
+
+#pragma once
+
+#include "mlir/Dialect/QCO/IR/QCODialect.h"
+
+#include <mlir/Dialect/Arith/IR/Arith.h>
+#include <mlir/Pass/Pass.h>
+#include <mlir/Pass/PassRegistry.h>
+
+namespace mlir::qco {
+
+#define GEN_PASS_DECL
+#include "mlir/Passes/Passes.h.inc" // IWYU pragma: export
+
+//===----------------------------------------------------------------------===//
+// Registration
+//===----------------------------------------------------------------------===//
+
+/// Generate the code for registering passes.
+#define GEN_PASS_REGISTRATION
+#include "mlir/Passes/Passes.h.inc" // IWYU pragma: export
+
+} // namespace mlir::qco

mlir/include/mlir/Passes/Passes.td

@@ -0,0 +1,38 @@
+// Copyright (c) 2023 - 2026 Chair for Design Automation, TUM
+// Copyright (c) 2025 - 2026 Munich Quantum Software Company GmbH
+// All rights reserved.
+//
+// SPDX-License-Identifier: MIT
+//
+// Licensed under the MIT License
+
+#ifndef QCO_PASSES
+#define QCO_PASSES
+
+include "mlir/Pass/PassBase.td"
+
+//===----------------------------------------------------------------------===//
+// Transpilation Passes
+//===----------------------------------------------------------------------===//
+
+def HeuristicMappingPass : Pass<"map", "mlir::ModuleOp"> {
+  let dependentDialects = ["mlir::qco::QCODialect"];
+  let summary = "This pass ensures that a program meets the connectivity constraints of a given architecture.";
+  let description = [{
+    This pass inserts SWAP operations to ensure two-qubit gates are executable on a given target architecture.
+  }];
+  let options = [
+    Option<"archName", "arch", "std::string", "",
+           "The name of the targeted architecture.">,
+    Option<"nlookahead", "nlookahead", "std::size_t", "1",
+           "The number of lookahead steps.">,
+    Option<"alpha", "alpha", "float", "1.0F",
+           "The alpha factor in the cost function.">,
+    Option<"lambda", "lambda", "float", "0.5F",
+           "The lambda factor in the cost function.">,
+    Option<"repeats", "repeats", "std::size_t", "2",
+           "The number of forwards and backwards traversal to improve the initial layout.">
+  ];
+}
+
+#endif // QCO_PASSES

mlir/lib/CMakeLists.txt

@@ -6,7 +6,8 @@
 #
 # Licensed under the MIT License
 
-add_subdirectory(Dialect)
 add_subdirectory(Conversion)
 add_subdirectory(Compiler)
+add_subdirectory(Dialect)
+add_subdirectory(Passes)
 add_subdirectory(Support)

mlir/lib/Compiler/CMakeLists.txt

@@ -20,6 +20,7 @@ add_mlir_library(
   QCToQCO
   QCOToQC
   QCToQIR
+  QcoPasses
   MQT::MLIRSupport
   DISABLE_INSTALL)
 

mlir/lib/Passes/CMakeLists.txt

@@ -0,0 +1,41 @@
+# Copyright (c) 2023 - 2026 Chair for Design Automation, TUM
+# Copyright (c) 2025 - 2026 Munich Quantum Software Company GmbH
+# All rights reserved.
+#
+# SPDX-License-Identifier: MIT
+#
+# Licensed under the MIT License
+
+file(GLOB_RECURSE PASSES_SOURCES *.cpp)
+
+get_property(dialect_libs GLOBAL PROPERTY MLIR_DIALECT_LIBS)
+
+add_mlir_library(
+  QcoPasses
+  ${PASSES_SOURCES}
+  LINK_LIBS
+  PUBLIC
+  PRIVATE
+  ${dialect_libs}
+  DEPENDS
+  QcoPassesIncGen)
+
+# collect header files
+file(GLOB_RECURSE PASSES_HEADERS_SOURCE ${MQT_MLIR_SOURCE_INCLUDE_DIR}/mlir/Passes/*.h)
+file(GLOB_RECURSE PASSES_HEADERS_BUILD ${MQT_MLIR_BUILD_INCLUDE_DIR}/mlir/Passes/*.inc)
+
+# add public headers using file sets
+target_sources(
+  QcoPasses
+  PUBLIC FILE_SET
+         HEADERS
+         BASE_DIRS
+         ${MQT_MLIR_SOURCE_INCLUDE_DIR}
+         FILES
+         ${PASSES_HEADERS_SOURCE}
+         FILE_SET
+         HEADERS
+         BASE_DIRS
+         ${MQT_MLIR_BUILD_INCLUDE_DIR}
+         FILES
+         ${PASSES_HEADERS_BUILD})

mlir/lib/Passes/Mapping/Architecture.cpp

@@ -0,0 +1,73 @@
+/*
+ * Copyright (c) 2023 - 2026 Chair for Design Automation, TUM
+ * Copyright (c) 2025 - 2026 Munich Quantum Software Company GmbH
+ * All rights reserved.
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * Licensed under the MIT License
+ */
+
+#include "mlir/Passes/Mapping/Architecture.h"
+
+#include <cstddef>
+#include <cstdint>
+#include <llvm/Support/ErrorHandling.h>
+#include <mlir/Support/LLVM.h>
+#include <string_view>
+#include <utility>
+
+using namespace mlir;
+
+std::string_view Architecture::name() const { return name_; }
+
+std::size_t Architecture::nqubits() const { return nqubits_; }
+
+bool Architecture::areAdjacent(std::size_t u, std::size_t v) const {
+  return couplingSet_.contains(std::make_pair(u, v));
+}
+
+std::size_t Architecture::distanceBetween(std::size_t u, std::size_t v) const {
+  if (dist_[u][v] == UINT64_MAX) {
+    report_fatal_error("Floyd-warshall failed to compute the distance "
+                       "between qubits " +
+                       Twine(u) + " and " + Twine(v));
+  }
+  return dist_[u][v];
+}
+
+SmallVector<std::size_t, 4> Architecture::neighboursOf(std::size_t u) const {
+  return neighbours_[u];
+}
+
+void Architecture::floydWarshallWithPathReconstruction() {
+  for (const auto& [u, v] : couplingSet_) {
+    dist_[u][v] = 1;
+    prev_[u][v] = u;
+  }
+  for (std::size_t v = 0; v < nqubits(); ++v) {
+    dist_[v][v] = 0;
+    prev_[v][v] = v;
+  }
+
+  for (std::size_t k = 0; k < nqubits(); ++k) {
+    for (std::size_t i = 0; i < nqubits(); ++i) {
+      for (std::size_t j = 0; j < nqubits(); ++j) {
+        if (dist_[i][k] == UINT64_MAX || dist_[k][j] == UINT64_MAX) {
+          continue; // Avoid overflow with "infinite" distances.
+        }
+        const std::size_t sum = dist_[i][k] + dist_[k][j];
+        if (dist_[i][j] > sum) {
+          dist_[i][j] = sum;
+          prev_[i][j] = prev_[k][j];
+        }
+      }
+    }
+  }
+}
+
+void Architecture::collectNeighbours() {
+  for (const auto& [u, v] : couplingSet_) {
+    neighbours_[u].push_back(v);
+  }
+}