✨ Heuristic Mapping Pass (#1537)

## Description

This pull request reimplements the heuristic mapping pass of the old
mqtopt dialect. Similarly to #1510 the mapping pass ignores structured
control flow (for now). I've copied the CMake setup of #1206.

A key difference between the implementations is that here I avoid
building the "fat" Layout object (which keeps track of the SSA values)
and use the `WireIterator`s and the "lightweight" Layout instead.
Moreover, just because I wanted to highlight how cool the `WireIterator`
is, this pull request adds LightSABRE-like back and forth traversal to
find a better initial layout.

Lastly, I think it should be possible to use the ideas implemented here
for a unitized IR also.

## Checklist:

<!---
This checklist serves as a reminder of a couple of things that ensure
your pull request will be merged swiftly.
-->

- [x] The pull request only contains commits that are focused and
relevant to this change.
- [x] I have added appropriate tests that cover the new/changed
functionality.
- [x] I have updated the documentation to reflect these changes.
- [x] I have added entries to the changelog for any noteworthy
additions, changes, fixes, or removals.
- [x] I have added migration instructions to the upgrade guide (if
needed).
- [x] The changes follow the project's style guidelines and introduce no
new warnings.
- [x] The changes are fully tested and pass the CI checks.
- [x] I have reviewed my own code changes.

---------

Signed-off-by: burgholzer <burgholzer@me.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: burgholzer <burgholzer@me.com>

Author: 3 people

CHANGELOG.md

@@ -11,6 +11,7 @@ This project adheres to [Semantic Versioning], with the exception that minor rel
 
 ### Added
 
+- ✨ Add a `place-and-route` pass for mapping circuits to architectures with restricted topologies ([#1537]) ([**@MatthiasReumann**])
 - ✨ Add initial infrastructure for new QC and QCO MLIR dialects
   ([#1264], [#1330], [#1402], [#1428], [#1430], [#1436], [#1443], [#1446], [#1464], [#1465], [#1470], [#1471], [#1472], [#1474], [#1475], [#1506], [#1510], [#1513], [#1521])
   ([**@burgholzer**], [**@denialhaag**], [**@taminob**], [**@DRovara**], [**@li-mingbao**], [**@Ectras**], [**@MatthiasReumann**])
@@ -327,6 +328,7 @@ _📚 Refer to the [GitHub Release Notes](https://github.com/munich-quantum-tool
 
 <!-- PR links -->
 
+[#1537]: https://github.com/munich-quantum-toolkit/core/pull/1537
 [#1521]: https://github.com/munich-quantum-toolkit/core/pull/1521
 [#1513]: https://github.com/munich-quantum-toolkit/core/pull/1513
 [#1510]: https://github.com/munich-quantum-toolkit/core/pull/1510

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,91 @@
+/*
+ * 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 <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 <cstddef>
+#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,65 @@
+// 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 MappingPass : Pass<"place-and-route", "mlir::ModuleOp"> {
+  let dependentDialects = ["mlir::qco::QCODialect"];
+  let summary = "This pass ensures that a program meets the connectivity constraints of a target architecture.";
+  let description = [{
+    This pass maps the dynamically allocated qubits in a quantum program to the static qubits of a target architecture.
+    The pass performs both placement and routing of the qubits to ensure that all two-qubit operations in the program
+    can be executed on the target architecture.
+
+    First, the pass assigns static qubits to the dynamically allocated ones by creating an initial dynamic-to-static
+    mapping, which is referred to as the initial layout. Then, it traverses the circuit and inserts `SWAP` operations to
+    ensure that all two-qubit operations are executable on the target architecture, a process known as routing.
+
+    For routing, the pass first divides the circuit into layers. A layer is a set of independently executable (sequences
+    or blocks of) two-qubit operations. Subsequently, the pass performs an A* search for each layer to find and insert a
+    sequence of `SWAP` operations that makes these two-qubit operations executable. The A* search also considers
+    subsequent layers, which are determined by the `nlookahead` parameter.
+
+    The cost function of the A* search is defined as follows:
+
+    * `f(n) = g(n) + h(n)`
+    * `g(n) = alpha * depth(n)`
+    * `h(n) = sum(pow(lambda, i) * h(L, p) for [i, L] in enumerate(layers))`
+
+    Where:
+    * `p` is the dynamic-to-static mapping associated with search node `n`.
+    * `layers` is an array of layers with size `1 + nlookahead`.
+    * `depth(n)` returns the distance from the node `n` to the root node.
+    * `dist(i, j)` returns the distance between the qubits `i` and `j` on the target's coupling graph.
+    * `h(L, p) := sum(dist(p[gate.first], p[gate.second]) for gate in L)`
+
+    To iteratively refine the mapping, the pass performs multiple forward and backward traversals of the circuit. In
+    each traversal, the pass routes the circuit and updates the dynamic-to-static mapping based on the routing decisions
+    made during that traversal. By performing multiple traversals, the pass can iteratively refine the mapping and
+    potentially find a more optimal solution. This is behavior is controlled by the `niterations` parameter.
+  }];
+  let options = [
+    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. Must be > 0.">,
+    Option<"lambda", "lambda", "float", "0.5F",
+           "The lambda factor in the cost function.">,
+    Option<"niterations", "niterations", "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/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,74 @@
+/*
+ * 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 <llvm/Support/ErrorHandling.h>
+#include <mlir/Support/LLVM.h>
+
+#include <cstddef>
+#include <cstdint>
+#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);
+  }
+}