✨Implement Unitized Routing Passes (#1301)

## Description

This pull request implements an "unit"-ized approach to route
quantum-classical programs. Furthermore, it solves the issue that the
def-use and textual (program) operation order is not _that_ compatible.

### Unit

An Unit divides a quantum-classical program into routable sections:

```
┌─────┐
│unit |
└─────┘
---------------- divider (`scf.for`)
┃ ┌─────┐
┃ |unit | // loop-body
┃ └─────┘ <-- `restore=true` 
┌─────┐
│unit |
└─────┘
---------------- divider (`scf.if`)
┃ ┌─────┐
┃ |unit | // then-body
┃ └─────┘<-- `restore=true` 
┣
┃ ┌─────┐
┃ │unit | // else-body
┃ └─────┘<-- `restore=true` 
┌─────┐
│unit |
└─────┘
```

Each unit is routed separately. This PR introduces two modes of
traversal for such units:
- `SequentialUnit`: Traverses the ops in the unit sequentially (Naive
Routing)
- `LayeredUnit`: Traverses the ops layer-by-layer (A* Routing) 

## Changes
- Split naive (`--route-naive-sc`) from A* routing pass
(`--route-astar-sc`): This makes sense from a logical as well as a pass
option perspective. The pass options for the A* routing pass belong to
the A* routing pass. If we were to implement another method, let's say
SABRE, its options would again reside in a separate pass.
- Implement `SequentialUnit` and `LayeredUnit`.
- Refactor A* and Naive routing passes to use the respective unit
implementation.
- Fix SSA Dominance Issues by implementing the reordering strategy
discussed below.
- Use `SequentialUnit` also for verification 


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

[^1]: Switching the custom stack for recursive function calls can
probably also be applied to the placement and verification pass.
Something for a future PR.

---------

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

Author: 3 people

CHANGELOG.md

@@ -20,6 +20,7 @@ This project adheres to [Semantic Versioning], with the exception that minor rel
 
 ### Changed
 
+- ♻️ Group circuit operations into scheduling units for MLIR routing ([#1301]) ([**@MatthiasReumann**])
 - 👷 Use `munich-quantum-software/setup-mlir` to set up MLIR ([#1294]) ([**@denialhaag**])
 - ♻️ Preserve tuple structure and improve site type clarity of the MQT NA Default QDMI Device ([#1299]) ([**@marcelwa**])
 - ♻️ Move DD package evaluation module to standalone script ([#1327]) ([**@burgholzer**])
@@ -266,6 +267,7 @@ _📚 Refer to the [GitHub Release Notes](https://github.com/munich-quantum-tool
 [#1336]: https://github.com/munich-quantum-toolkit/core/pull/1336
 [#1327]: https://github.com/munich-quantum-toolkit/core/pull/1327
 [#1310]: https://github.com/munich-quantum-toolkit/core/pull/1310
+[#1301]: https://github.com/munich-quantum-toolkit/core/pull/1301
 [#1300]: https://github.com/munich-quantum-toolkit/core/pull/1300
 [#1299]: https://github.com/munich-quantum-toolkit/core/pull/1299
 [#1294]: https://github.com/munich-quantum-toolkit/core/pull/1294

mlir/include/mlir/Dialect/MQTOpt/Transforms/Passes.h

@@ -29,7 +29,6 @@ class RewritePatternSet;
 namespace mqt::ir::opt {
 
 enum class PlacementStrategy : std::uint8_t { Random, Identity };
-enum class RoutingMethod : std::uint8_t { Naive, AStar };
 
 #define GEN_PASS_DECL
 #include "mlir/Dialect/MQTOpt/Transforms/Passes.h.inc" // IWYU pragma: export

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

@@ -113,7 +113,7 @@ def ReuseQubitsPass : Pass<"reuse-qubits", "mlir::ModuleOp"> {
 //===----------------------------------------------------------------------===//
 
 def PlacementPassSC : Pass<"placement-sc", "mlir::ModuleOp"> {
-  let summary = "This pass maps dynamic qubits to static qubits on superconducting quantum devices using initial placement strategies.";
+  let summary = "This pass maps program qubits to hardware qubits on superconducting quantum devices using initial placement strategies.";
   let options = [
     Option<"strategy", "strategy", "PlacementStrategy", "PlacementStrategy::Random",
            "The initial placement strategy to use.", [{llvm::cl::values(
@@ -124,16 +124,27 @@ def PlacementPassSC : Pass<"placement-sc", "mlir::ModuleOp"> {
   ];
 }
 
-def RoutingPassSC : Pass<"route-sc", "mlir::ModuleOp"> {
-  let summary = "This pass ensures that a program meets the connectivity constraints of a given architecture.";
+def NaiveRoutingPassSC : Pass<"route-naive-sc", "mlir::ModuleOp"> {
+  let summary = "This pass ensures that all two-qubit gates are executable on the target architecture.";
   let description = [{
-    This pass inserts SWAP operations to ensure two-qubit gates are executable on a given target architecture.
+    Simple pre-order traversal of the IR that routes any non-executable gates by inserting SWAPs along the shortest path.
+  }];
+  let options = [
+    Option<"archName", "arch", "std::string", "",
+           "The name of the targeted architecture.">,
+  ];
+  let statistics = [
+    Statistic<"numSwaps", "num-additional-swaps", "The number of additional SWAPs">
+  ];
+}
+
+def AStarRoutingPassSC : Pass<"route-astar-sc", "mlir::ModuleOp"> {
+  let summary = "This pass ensures that all two-qubit gates are executable on the target architecture.";
+  let description = [{
+    Routes the program by dividing the circuit into layers of parallel two-qubit gates and iteratively searches and
+    inserts SWAPs for each layer using A*-search.
   }];
   let options = [
-    Option<"method", "method", "RoutingMethod", "RoutingMethod::AStar",
-           "The routing method to use.", [{llvm::cl::values(
-             clEnumValN(RoutingMethod::Naive, "naive", "Swap along shortest paths"),
-             clEnumValN(RoutingMethod::AStar, "astar", "A*-search-based routing algorithm"))}]>,
     Option<"archName", "arch", "std::string", "",
            "The name of the targeted architecture.">,
     Option<"nlookahead", "nlookahead", "std::size_t", "1",
@@ -149,7 +160,7 @@ def RoutingPassSC : Pass<"route-sc", "mlir::ModuleOp"> {
 }
 
 def RoutingVerificationSCPass : Pass<"verify-routing-sc", "mlir::ModuleOp"> {
-  let summary = "This pass verifies that a program meets the connectivity constraints of a given architecture.";
+  let summary = "This pass verifies that all two-qubit gates are executable on the target architecture.";
   let description = [{
     This pass ensures that all two-qubit gates are executable on the target's architecture.
   }];

mlir/include/mlir/Dialect/MQTOpt/Transforms/Transpilation/Architecture.h

@@ -10,16 +10,20 @@
 
 #pragma once
 
-#include "mlir/Dialect/MQTOpt/Transforms/Transpilation/Common.h"
+#include "mlir/Dialect/MQTOpt/IR/MQTOptDialect.h"
+#include "mlir/Dialect/MQTOpt/Transforms/Transpilation/Layout.h"
 
 #include <cstddef>
 #include <cstdint>
+#include <llvm/ADT/DenseMapInfo.h>
 #include <llvm/ADT/DenseSet.h>
 #include <llvm/ADT/SmallVector.h>
 #include <llvm/ADT/StringRef.h>
 #include <memory>
+#include <mlir/Support/LLVM.h>
 #include <string>
 #include <string_view>
+#include <utility>
 
 namespace mqt::ir::opt {
 
@@ -29,8 +33,8 @@ namespace mqt::ir::opt {
  */
 class Architecture {
 public:
-  using CouplingSet = mlir::DenseSet<std::pair<QubitIndex, QubitIndex>>;
-  using NeighbourVector = mlir::SmallVector<mlir::SmallVector<QubitIndex, 4>>;
+  using CouplingSet = mlir::DenseSet<std::pair<uint32_t, uint32_t>>;
+  using NeighbourVector = mlir::SmallVector<mlir::SmallVector<uint32_t, 4>>;
 
   explicit Architecture(std::string name, std::size_t nqubits,
                         CouplingSet couplingSet)
@@ -55,27 +59,33 @@ class Architecture {
   /**
    * @brief Return true if @p u and @p v are adjacent.
    */
-  [[nodiscard]] bool areAdjacent(QubitIndex u, QubitIndex v) const {
+  [[nodiscard]] bool areAdjacent(uint32_t u, uint32_t v) const {
     return couplingSet_.contains({u, v});
   }
 
   /**
-   * @brief Collect the shortest path between @p u and @p v.
-   * @returns The path from the destination (v) to source (u) qubit.
+   * @brief Collect the shortest SWAP sequence to make @p u and @p v adjacent.
+   * @returns The SWAP sequence from the destination (v) to source (u) qubit.
    */
-  [[nodiscard]] llvm::SmallVector<std::size_t>
-  shortestPathBetween(QubitIndex u, QubitIndex v) const;
+  [[nodiscard]] llvm::SmallVector<std::pair<uint32_t, uint32_t>>
+  shortestSWAPsBetween(uint32_t u, uint32_t v) const;
 
   /**
    * @brief Return the length of the shortest path between @p u and @p v.
    */
-  [[nodiscard]] std::size_t distanceBetween(QubitIndex u, QubitIndex v) const;
+  [[nodiscard]] std::size_t distanceBetween(uint32_t u, uint32_t v) const;
 
   /**
    * @brief Collect all neighbours of @p u.
    */
-  [[nodiscard]] llvm::SmallVector<QubitIndex, 4>
-  neighboursOf(QubitIndex u) const;
+  [[nodiscard]] llvm::SmallVector<uint32_t, 4> neighboursOf(uint32_t u) const;
+
+  /**
+   * @brief Validate if a two-qubit op is executable on the architecture for a
+   * given layout.
+   */
+  [[nodiscard]] bool isExecutable(UnitaryInterface op,
+                                  const Layout& layout) const;
 
 private:
   using Matrix = llvm::SmallVector<llvm::SmallVector<std::size_t>>;

mlir/include/mlir/Dialect/MQTOpt/Transforms/Transpilation/Common.h

@@ -11,29 +11,20 @@
 #pragma once
 
 #include "mlir/Dialect/MQTOpt/IR/MQTOptDialect.h"
+#include "mlir/Dialect/MQTOpt/Transforms/Transpilation/Layout.h"
 
+#include <concepts>
 #include <cstddef>
+#include <cstdint>
 #include <llvm/ADT/StringRef.h>
 #include <mlir/Dialect/Func/IR/FuncOps.h>
 #include <mlir/IR/BuiltinAttributes.h>
+#include <mlir/IR/PatternMatch.h>
 #include <mlir/IR/Value.h>
+#include <ranges>
 #include <utility>
 
 namespace mqt::ir::opt {
-/**
- * @brief 'For' pushes once onto the stack, hence the parent is at depth one.
- */
-constexpr std::size_t FOR_PARENT_DEPTH = 1UL;
-
-/**
- * @brief 'If' pushes twice onto the stack, hence the parent is at depth two.
- */
-constexpr std::size_t IF_PARENT_DEPTH = 2UL;
-
-/**
- * @brief Type alias for qubit indices.
- */
-using QubitIndex = uint32_t;
 
 /**
  * @brief A pair of SSA Values.
@@ -43,7 +34,7 @@ using ValuePair = std::pair<mlir::Value, mlir::Value>;
 /**
  * @brief Represents a pair of qubit indices.
  */
-using QubitIndexPair = std::pair<QubitIndex, QubitIndex>;
+using QubitIndexPair = std::pair<uint32_t, uint32_t>;
 
 /**
  * @brief Return true if the function contains "entry_point" in the passthrough
@@ -80,4 +71,66 @@ using QubitIndexPair = std::pair<QubitIndex, QubitIndex>;
  */
 [[nodiscard]] mlir::Operation* getUserInRegion(mlir::Value v,
                                                mlir::Region* region);
+
+/**
+ * @brief Create and return SWAPOp for two qubits.
+ *
+ * Expects the rewriter to be set to the correct position.
+ *
+ * @param location The Location to attach to the created op.
+ * @param in0 First input qubit SSA value.
+ * @param in1 Second input qubit SSA value.
+ * @param rewriter A PatternRewriter.
+ * @return The created SWAPOp.
+ */
+[[nodiscard]] SWAPOp createSwap(mlir::Location location, mlir::Value in0,
+                                mlir::Value in1,
+                                mlir::PatternRewriter& rewriter);
+
+/**
+ * @brief Replace all uses of a value within a region and its nested regions,
+ * except for a specific operation.
+ *
+ * @param oldValue The value to replace.
+ * @param newValue The new value to use.
+ * @param region The region in which to perform replacements.
+ * @param exceptOp Operation to exclude from replacements.
+ * @param rewriter The pattern rewriter.
+ */
+void replaceAllUsesInRegionAndChildrenExcept(mlir::Value oldValue,
+                                             mlir::Value newValue,
+                                             mlir::Region* region,
+                                             mlir::Operation* exceptOp,
+                                             mlir::PatternRewriter& rewriter);
+
+/**
+ * @brief Insert SWAP ops at the rewriter's insertion point.
+ *
+ * @param loc The location of the inserted SWAP ops.
+ * @param swaps A range of hardware indices for the SWAPs.
+ * @param layout The current layout.
+ * @param rewriter The pattern rewriter.
+ */
+template <typename Range>
+  requires std::same_as<std::ranges::range_value_t<Range>, QubitIndexPair>
+void insertSWAPs(mlir::Location loc, Range&& swaps, Layout& layout,
+                 mlir::PatternRewriter& rewriter) {
+  for (const auto [hw0, hw1] : std::forward<Range>(swaps)) {
+    const mlir::Value in0 = layout.lookupHardwareValue(hw0);
+    const mlir::Value in1 = layout.lookupHardwareValue(hw1);
+
+    auto swap = createSwap(loc, in0, in1, rewriter);
+
+    rewriter.setInsertionPointAfter(swap);
+
+    mlir::Region* region = swap->getParentRegion();
+    mlir::Value out0 = swap.getOutQubits()[0];
+    mlir::Value out1 = swap.getOutQubits()[1];
+
+    replaceAllUsesInRegionAndChildrenExcept(in0, out1, region, swap, rewriter);
+    replaceAllUsesInRegionAndChildrenExcept(in1, out0, region, swap, rewriter);
+
+    layout.remap(swap);
+  }
+}
 } // namespace mqt::ir::opt

mlir/include/mlir/Dialect/MQTOpt/Transforms/Transpilation/LayeredUnit.h

@@ -0,0 +1,70 @@
+/*
+ * 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 "mlir/Dialect/MQTOpt/Transforms/Transpilation/Common.h"
+#include "mlir/Dialect/MQTOpt/Transforms/Transpilation/Layout.h"
+#include "mlir/Dialect/MQTOpt/Transforms/Transpilation/Unit.h"
+
+#include <cstddef>
+#include <llvm/ADT/STLExtras.h>
+#include <llvm/Support/Debug.h>
+#include <mlir/Support/LLVM.h>
+
+namespace mqt::ir::opt {
+
+struct Layer {
+  /// @brief All (zero, one, two-qubit) ops contained inside this layer.
+  mlir::SmallVector<mlir::Operation*, 64> ops;
+  /// @brief The program index pairs of all two-qubit ops.
+  mlir::SmallVector<QubitIndexPair, 16> twoQubitProgs;
+  /// @brief The first op in ops in textual IR order.
+  mlir::Operation* anchor{};
+
+  /// @brief Add op to ops and reset anchor if necessary.
+  void addOp(mlir::Operation* op) {
+    ops.emplace_back(op);
+    if (anchor == nullptr || op->isBeforeInBlock(anchor)) {
+      anchor = op;
+    }
+  }
+  /// @returns true iff. there are no ops in this layer.
+  [[nodiscard]] bool hasZeroOps() const { return ops.empty(); }
+  /// @returns true iff. there are no two-qubit ops in this layer.
+  [[nodiscard]] bool hasZero2QOps() const { return twoQubitProgs.empty(); }
+};
+
+/// @brief A LayeredUnit traverses a program layer-by-layer.
+class LayeredUnit : public Unit {
+public:
+  using Layers = mlir::SmallVector<Layer, 0>;
+
+  [[nodiscard]] static LayeredUnit
+  fromEntryPointFunction(mlir::func::FuncOp func, std::size_t nqubits);
+
+  LayeredUnit(Layout layout, mlir::Region* region, bool restore = false);
+
+  [[nodiscard]] mlir::SmallVector<LayeredUnit, 3> next();
+  [[nodiscard]] Layers::const_iterator begin() const { return layers_.begin(); }
+  [[nodiscard]] Layers::const_iterator end() const { return layers_.end(); }
+  [[nodiscard]] const Layer& operator[](std::size_t i) const {
+    return layers_[i];
+  }
+  [[nodiscard]] std::size_t size() const { return layers_.size(); }
+
+#ifndef NDEBUG
+  LLVM_DUMP_METHOD void dump(llvm::raw_ostream& os = llvm::dbgs()) const;
+#endif
+
+private:
+  Layers layers_;
+};
+} // namespace mqt::ir::opt