✨ Improve Mapping Pass (#1600)

## Description

This pull request updates the mapping pass in various ways:
1) Use `walkProgramGraph` driver
    - Benefit: Code quality and code duplication
2) Compute layers on demand
    - Benefit: Memory
3) Use trials to improve initial layout and perform final "hot" routing
left-to-right pass
   - Benefit: Memory - No more auxiliary data structure for each trial.
4) Remove unnecessary overhead of `LayoutInfo` and simply use the
program-to-hardware vector as map key.
    - Benefit: Memory 
5) Injectable Architecture
    - Benefit: Easier benchmarking and testing.
6) Single `route` function for cold and hot routing 
    - Benefit: Code duplication and maintenance later on.
7) Optimized for "individual gates" strategy. 
- For "utility-scale" circuits finding solution for full layers is
impractical in terms of runtime.

## 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.

**If PR contains AI-assisted content:**

- [x] I have disclosed the use of AI tools in the PR description as per
our [AI Usage
Guidelines](https://github.com/munich-quantum-toolkit/core/blob/main/docs/ai_usage.md).
- [x] AI-assisted commits include an `Assisted-by: [Model Name] via
[Tool Name]` footer.
- [x] I confirm that I have personally reviewed and understood all
AI-generated content, and accept full responsibility for it.

Author: MatthiasReumann

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], [#1674]) ([**@J4MMlE**], [**@MatthiasReumann**])
 - ✨ 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], [#1675])
   ([**@burgholzer**], [**@denialhaag**], [**@taminob**], [**@DRovara**], [**@li-mingbao**], [**@Ectras**], [**@MatthiasReumann**], [**@simon1hofmann**])
@@ -375,6 +375,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>
@@ -28,6 +29,14 @@ class [[nodiscard]] Architecture {
   using CouplingSet = DenseSet<std::pair<std::size_t, std::size_t>>;
   using NeighbourVector = SmallVector<SmallVector<std::size_t, 4>>;
 
+  /**
+   * @brief Constructs an empty architecture.
+   */
+  Architecture() : nqubits_(0) {}
+
+  /**
+   * @brief Constructs a well-defined architecture.
+   */
   explicit Architecture(std::string name, std::size_t nqubits,
                         CouplingSet couplingSet)
       : name_(std::move(name)), nqubits_(nqubits),
@@ -61,7 +70,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
@@ -94,5 +103,4 @@ class [[nodiscard]] Architecture {
   Matrix dist_;
   Matrix prev_;
 };
-
 } // 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/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>
@@ -41,8 +40,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];
 }