✨ Improve Mapping Pass

CHANGELOG.md

@@ -13,7 +13,7 @@ This project adheres to [Semantic Versioning], with the exception that minor rel
 
 - ✨ Add a `merge-single-qubit-rotation-gates` pass for merging consecutive rotation gates using quaternions ([#1407]) ([**@J4MMlE**])
 - ✨ Add conversions between `jeff` and QCO ([#1479], [#1548], [#1565], [#1637]) ([**@denialhaag**])
-- ✨ Add a `place-and-route` pass for mapping circuits to architectures with restricted topologies ([#1537], [#1547], [#1568], [#1581], [#1583], [#1588], [#1664]) ([**@MatthiasReumann**], [**@burgholzer**])
+- ✨ Add a `place-and-route` pass for mapping circuits to architectures with restricted topologies ([#1537], [#1547], [#1568], [#1581], [#1583], [#1588], [#1600], [#1664]) ([**@MatthiasReumann**], [**@burgholzer**])
 - ✨ 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], [#1542], [#1548], [#1550], [#1554], [#1567], [#1569], [#1570], [#1572], [#1573], [#1580], [#1602], [#1620], [#1623], [#1624], [#1626], [#1627], [#1635], [#1673])
   ([**@burgholzer**], [**@denialhaag**], [**@taminob**], [**@DRovara**], [**@li-mingbao**], [**@Ectras**], [**@MatthiasReumann**], [**@simon1hofmann**])
@@ -373,6 +373,7 @@ _📚 Refer to the [GitHub Release Notes](https://github.com/munich-quantum-tool
 [#1623]: https://github.com/munich-quantum-toolkit/core/pull/1623
 [#1620]: https://github.com/munich-quantum-toolkit/core/pull/1620
 [#1602]: https://github.com/munich-quantum-toolkit/core/pull/1602
+[#1600]: https://github.com/munich-quantum-toolkit/core/pull/1600
 [#1596]: https://github.com/munich-quantum-toolkit/core/pull/1596
 [#1593]: https://github.com/munich-quantum-toolkit/core/pull/1593
 [#1588]: https://github.com/munich-quantum-toolkit/core/pull/1588

mlir/include/mlir/Dialect/QCO/Transforms/Mapping/Architecture.h

@@ -10,6 +10,7 @@
 
 #pragma once
 
+#include <llvm/ADT/ArrayRef.h>
 #include <llvm/ADT/DenseSet.h>
 #include <llvm/ADT/SmallVector.h>
 #include <mlir/Support/LLVM.h>
@@ -32,8 +33,8 @@ class [[nodiscard]] Architecture {
                         CouplingSet couplingSet)
       : name_(std::move(name)), nqubits_(nqubits),
         couplingSet_(std::move(couplingSet)), neighbours_(nqubits),
-        dist_(nqubits, SmallVector<size_t>(nqubits, UINT64_MAX)),
-        prev_(nqubits, SmallVector<size_t>(nqubits, UINT64_MAX)) {
+        dist_(nqubits, SmallVector<std::size_t>(nqubits, UINT64_MAX)),
+        prev_(nqubits, SmallVector<std::size_t>(nqubits, UINT64_MAX)) {
     floydWarshallWithPathReconstruction();
     collectNeighbours();
   }
@@ -61,7 +62,7 @@ class [[nodiscard]] Architecture {
   /**
    * @brief Collect all neighbours of @p u.
    */
-  [[nodiscard]] SmallVector<std::size_t, 4> neighboursOf(std::size_t u) const;
+  [[nodiscard]] ArrayRef<std::size_t> neighboursOf(std::size_t u) const;
 
   /**
    * @brief Return the maximum degree (connectivity) of any qubit in the
@@ -72,6 +73,9 @@ class [[nodiscard]] Architecture {
 private:
   using Matrix = SmallVector<SmallVector<std::size_t, 0>, 0>;
 
+  Architecture() : nqubits_(0) {}
+  friend Architecture getEmptyArchitecture();
+
   /**
    * @brief Find all shortest paths in the coupling map between two qubits.
    * @details Vertices are the qubits. Edges connected two qubits. Has a time
@@ -95,4 +99,9 @@ class [[nodiscard]] Architecture {
   Matrix prev_;
 };
 
+/**
+ * @brief Return an empty architecture with no qubits and no coupling.
+ */
+[[nodiscard]] Architecture getEmptyArchitecture();
+
 } // namespace mlir::qco

mlir/include/mlir/Dialect/QCO/Transforms/Mapping/Mapping.h

@@ -0,0 +1,40 @@
+/*
+ * 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/Transforms/Passes.h"
+
+#include <llvm/Support/LogicalResult.h>
+#include <mlir/IR/Region.h>
+#include <mlir/Pass/Pass.h>
+
+#include <memory>
+
+namespace mlir::qco {
+
+// Forward declaration
+class Architecture;
+
+/**
+ * @brief Verifies if all two-qubit gates within the region are executable on
+ * the targeted architecture. Expects static qubits only.
+ * @returns llvm::success() if executable, llvm::failure() otherwise.
+ */
+LogicalResult isExecutable(Region& region, const Architecture& arch);
+
+/**
+ * @brief Create a mapping pass instance with the given target architecture.
+ * @returns a pass object.
+ */
+std::unique_ptr<Pass>
+createMappingPass(std::shared_ptr<Architecture> arch,
+                  MappingPassOptions options = MappingPassOptions{});
+} // namespace mlir::qco

mlir/include/mlir/Dialect/QCO/Transforms/Passes.td

@@ -89,9 +89,9 @@ def MappingPass : Pass<"place-and-route", "mlir::ModuleOp"> {
                         "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",
+                 Option<"niterations", "niterations", "std::size_t", "1",
                         "The number of forwards and backwards traversal to "
-                        "improve the initial layout.">,
+                        "improve the initial layout. Must be > 0.">,
                  Option<"ntrials", "ntrials", "std::size_t", "4",
                         "The number of (possibly parallel) random trials of "
                         "the forwards and backwards mechanism. Must be > 0.">,

mlir/include/mlir/Dialect/QCO/Utils/Drivers.h

@@ -17,11 +17,14 @@
 #include "mlir/Dialect/QCO/Utils/WireIterator.h"
 #include "mlir/Dialect/QTensor/IR/QTensorOps.h"
 
+#include <llvm/ADT/ADL.h>
+#include <llvm/ADT/STLExtras.h>
 #include <llvm/ADT/TypeSwitch.h>
 #include <mlir/IR/Region.h>
 #include <mlir/IR/Value.h>
 #include <mlir/IR/Visitors.h>
 #include <mlir/Support/LLVM.h>
+#include <mlir/Support/WalkResult.h>
 
 #include <cstddef>
 #include <functional>

mlir/include/mlir/Dialect/QCO/Utils/Qubits.h

@@ -57,6 +57,11 @@ class Qubits {
    */
   [[nodiscard]] TypedValue<QubitType> getHardwareQubit(std::size_t index) const;
 
+  /**
+   * @returns the index assigned to the qubit value.
+   */
+  [[nodiscard]] std::size_t getIndex(TypedValue<QubitType> q) const;
+
 private:
   DenseMap<std::size_t, TypedValue<QubitType>> programToValue_;
   DenseMap<std::size_t, TypedValue<QubitType>> hardwareToValue_;

mlir/lib/Dialect/QCO/Transforms/Mapping/Architecture.cpp

@@ -10,7 +10,6 @@
 
 #include "mlir/Dialect/QCO/Transforms/Mapping/Architecture.h"
 
-#include <llvm/ADT/SmallVector.h>
 #include <llvm/ADT/Twine.h>
 #include <llvm/Support/ErrorHandling.h>
 #include <mlir/Support/LLVM.h>
@@ -24,6 +23,8 @@
 using namespace mlir;
 using namespace mlir::qco;
 
+Architecture mlir::qco::getEmptyArchitecture() { return {}; }
+
 std::string_view Architecture::name() const { return name_; }
 
 std::size_t Architecture::nqubits() const { return nqubits_; }
@@ -41,8 +42,7 @@ std::size_t Architecture::distanceBetween(std::size_t u, std::size_t v) const {
   return dist_[u][v];
 }
 
-SmallVector<std::size_t, 4>
-Architecture::neighboursOf(const std::size_t u) const {
+ArrayRef<std::size_t> Architecture::neighboursOf(std::size_t u) const {
   return neighbours_[u];
 }