✨ Add native gate synthesis MLIR pass and decomposition stack

CHANGELOG.md

@@ -12,6 +12,9 @@ releases may include breaking changes.
 
 ### Added
 
+- ✨ Add a `fuse-two-qubit-unitary-runs` pass for fusing compile-time two-qubit
+  unitary windows via Weyl/KAK resynthesis ([#1865]) ([**@simon1hofmann**],
+  [**@burgholzer**])
 - ✨ Add Python bindings for the MQT Compiler Collection ([#1815])
   ([**@burgholzer**], [**@denialhaag**])
 - ✨ Add support for QDMI child devices to the driver and FoMaC libraries
@@ -22,10 +25,12 @@ releases may include breaking changes.
   ([#1887]) ([**@flowerthrower**], [**@burgholzer**])
 - ✨ Add QIR Output Schemas support to the QIR runtime ([#1877])
   ([**@rturrado**])
+- ✨ Add a `fuse-two-qubit-unitary-runs` pass for fusing compile-time two-qubit
+  unitary windows via Weyl/KAK resynthesis ([#1655]) ([**@simon1hofmann**])
 - ✨ Add support for IQM's `move` gate in the QDMI Qiskit backend converter
   ([#1844], [#1848]) ([**@burgholzer**], [**@marcelwa**])
 - 🚸 Add `const` version of the `CompoundOperation`'s `getOps()` function
-  ([#1826]) ([**@ystade])
+  ([#1826]) ([**@ystade**])
 - 🐳 Add dev container configuration for consistent local development
   environment ([#1786]) ([**@denialhaag**])
 - ✨ Add two-qubit Weyl (KAK) decomposition and native-gateset synthesis support
@@ -646,6 +651,7 @@ changelogs._
 [#1872]: https://github.com/munich-quantum-toolkit/core/pull/1872
 [#1870]: https://github.com/munich-quantum-toolkit/core/pull/1870
 [#1869]: https://github.com/munich-quantum-toolkit/core/pull/1869
+[#1865]: https://github.com/munich-quantum-toolkit/core/pull/1865
 [#1850]: https://github.com/munich-quantum-toolkit/core/pull/1850
 [#1849]: https://github.com/munich-quantum-toolkit/core/pull/1849
 [#1848]: https://github.com/munich-quantum-toolkit/core/pull/1848
@@ -704,6 +710,7 @@ changelogs._
 [#1664]: https://github.com/munich-quantum-toolkit/core/pull/1664
 [#1662]: https://github.com/munich-quantum-toolkit/core/pull/1662
 [#1660]: https://github.com/munich-quantum-toolkit/core/pull/1660
+[#1655]: https://github.com/munich-quantum-toolkit/core/pull/1655
 [#1652]: https://github.com/munich-quantum-toolkit/core/pull/1652
 [#1638]: https://github.com/munich-quantum-toolkit/core/pull/1638
 [#1637]: https://github.com/munich-quantum-toolkit/core/pull/1637

bindings/mlir/register_mlir.cpp

@@ -387,6 +387,11 @@ operations.)pb");
               &mlir::QCOProgram::fuseSingleQubitUnitaryRuns>::call,
           nb::kw_only(), "basis"_a = "zyz",
           "Fuse single-qubit unitary runs into the chosen decomposition basis.")
+      .def("fuse_two_qubit_unitary_runs",
+           &BooleanMemberAdapter<
+               &mlir::QCOProgram::fuseTwoQubitUnitaryRuns>::call,
+           nb::kw_only(), "native_gates"_a = "",
+           "Lower unitaries to a comma-separated native gate menu.")
       .def("unroll_quantum_loops",
            &BooleanMemberAdapter<&mlir::QCOProgram::unrollQuantumLoops>::call,
            nb::kw_only(), "unroll_factor"_a = -1,

mlir/include/mlir/Compiler/Programs.h

@@ -182,6 +182,14 @@ class QCOProgram final : public Program {
   /** @brief Fuse single-qubit unitary runs into the selected Euler basis. */
   [[nodiscard]] bool fuseSingleQubitUnitaryRuns(std::string_view basis = "zyz");
 
+  /**
+   * @brief Lower unitaries to a comma-separated native gate menu.
+   *
+   * @details An empty or whitespace-only menu is a no-op. Unrecognised tokens
+   * cause the pass to fail.
+   */
+  [[nodiscard]] bool fuseTwoQubitUnitaryRuns(std::string_view nativeGates = "");
+
   /** @brief Unroll loops containing quantum operations. */
   [[nodiscard]] bool unrollQuantumLoops(int64_t factor = -1);
 

mlir/include/mlir/Dialect/QCO/Transforms/Decomposition/Euler.h

@@ -20,6 +20,10 @@
 #include <cstdint>
 #include <optional>
 
+namespace mlir {
+class RewritePatternSet;
+} // namespace mlir
+
 namespace mlir::qco::decomposition {
 
 /**
@@ -99,4 +103,15 @@ synthesizeUnitary1QEuler(OpBuilder& builder, Location loc, Value qubit,
  */
 void emitGPhaseIfNeeded(OpBuilder& builder, Location loc, double phase);
 
+/**
+ * @brief Populates @p patterns with the single-qubit run fusion rewrite for
+ * @p basis (the reusable core of `fuse-single-qubit-unitary-runs`).
+ *
+ * @param skipControlledBodies When set, single-qubit gates nested in `qco.ctrl`
+ * bodies are left untouched.
+ */
+void populateFuseSingleQubitUnitaryRunsPatterns(
+    RewritePatternSet& patterns, EulerBasis basis,
+    bool skipControlledBodies = false);
+
 } // namespace mlir::qco::decomposition

mlir/include/mlir/Dialect/QCO/Transforms/Decomposition/NativeGateset.h

@@ -18,6 +18,10 @@
 #include <cstdint>
 #include <optional>
 
+namespace mlir {
+class Operation;
+} // namespace mlir
+
 namespace mlir::qco::decomposition {
 
 /**
@@ -63,6 +67,15 @@ struct NativeGateset {
    */
   [[nodiscard]] std::optional<TwoQubitNativeDecomposition>
   decomposeTarget(const Matrix4x4& target) const;
+
+  /**
+   * @brief Whether @p op is already on this native gateset.
+   *
+   * `qco.barrier` and `qco.gphase` are always allowed. Single-qubit primitives
+   * and single-target `qco.ctrl` shells (with an `X`/`Z` body) are checked
+   * against @p gates. All other ops are rejected.
+   */
+  [[nodiscard]] bool allowsOp(Operation* op) const;
 };
 
 } // namespace mlir::qco::decomposition

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

@@ -67,6 +67,57 @@ def FuseSingleQubitUnitaryRuns
       "Target Euler basis (zyz, zxz, xzx, xyx, u, zsxx, r).">];
 }
 
+def FuseTwoQubitUnitaryRuns
+    : Pass<"fuse-two-qubit-unitary-runs", "mlir::ModuleOp"> {
+  let dependentDialects = ["mlir::qco::QCODialect"];
+  let summary = "Lower QCO unitary gates to a user-specified native gate menu.";
+  let description = [{
+    Rewrites unitaries to match the comma-separated `native-gates` gateset.
+    `qco.barrier` and `qco.gphase` are preserved. A `qco.ctrl` is treated as a
+    two-qubit gate only when it has a single control and a single target; gates
+    acting on more than two qubits (e.g. multi-controlled `qco.ctrl`) are out of
+    scope and left untouched for a dedicated multi-controlled synthesis pass.
+
+    The gateset is a comma-separated list of gate tokens (order not
+    significant) from which the pass resolves a single-qubit Euler basis
+    (generic `qco.u` when `u` is present; IBM-style surface gates when all of
+    `x`, `sx`, and `rz` are present; IQM-style `qco.r` when `r` is present;
+    or a supported rotation pair chosen from `rx`, `ry`, `rz`) plus the
+    two-qubit entangler `cx` or `cz`.
+
+    Recognised tokens: `u`, `x`, `sx`, `rz`, `rx`, `ry`, `r`, `cx`,
+    `cz`. An empty or whitespace-only gateset is a no-op, which is the intended
+    pipeline default when synthesis is not needed. An unrecognised token causes
+    the pass to fail.
+
+    Example gatesets (each line is one illustrative gateset; pick either `cx`
+    or `cz` as the entangler, or list both if both are native):
+    - IBM: `x,sx,rz,cx` or `x,sx,rz,cz`
+    - Generic single-qubit U: `u,cx` or `u,cz`
+    - IQM default: `r,cz` (or `r,cx` if CX is the native entangler)
+    - Rotation pair + entangler: `rx,rz,cx`, `rx,ry,cz`, `ry,rz,cx`, etc.
+      Supported pairs are exactly `rx`+`rz`, `rx`+`ry`, and `ry`+`rz`.
+
+    Stages: fuse single-qubit runs (reusing `fuse-single-qubit-unitary-runs`,
+    which also lowers lone off-gateset single-qubit gates); fuse two-qubit runs
+    and lower any remaining off-gateset two-qubit ops via Weyl synthesis; fuse
+    the single-qubit seams introduced by that synthesis. The pass fails if any
+    single- or two-qubit op remains off the native gateset afterwards; gates on
+    more than two qubits are left untouched and do not cause a failure.
+
+    Lowering is deterministic: `cx` is preferred over `cz`, single-qubit
+    factors use the resolved Euler basis, and two-qubit run replacement uses
+    the minimal entangler count from the synthesizer.
+  }];
+  let options = [Option<
+      "nativeGates", "native-gates", "std::string", "\"\"",
+      "Comma-separated native gateset. Empty or whitespace-only is "
+      "a no-op. Tokens: u, x, sx, rz, rx, ry, r, cx, cz. "
+      "Examples: x,sx,rz,cx; u,cx; r,cz; rx,rz,cx.">];
+}
+
+//===----------------------------------------------------------------------===//
+
 def QuantumLoopUnroll
     : InterfacePass<"quantum-loop-unroll", "FunctionOpInterface"> {
   let dependentDialects = ["mlir::qco::QCODialect", "mlir::scf::SCFDialect"];

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

@@ -14,6 +14,7 @@
 #include <mlir/Support/LLVM.h>
 
 #include <array>
+#include <cmath>
 #include <complex>
 #include <concepts>
 #include <cstddef>
@@ -866,6 +867,32 @@ concept SupportedMatrix =
     std::same_as<T, Matrix1x1> || std::same_as<T, Matrix2x2> ||
     std::same_as<T, Matrix4x4> || std::same_as<T, DynamicMatrix>;
 
+/**
+ * @brief Checks whether two unitaries are equal up to a global phase.
+ *
+ * Uses `trace(rhs.adjoint() * lhs)` to infer a unit-modulus phase factor, then
+ * compares `lhs` to `factor * rhs` with @ref isApprox. A near-zero overlap
+ * (`|trace| <= tol`) is treated as not equivalent to avoid dividing by a tiny
+ * number.
+ *
+ * @tparam Matrix Any supported fixed- or dynamic-size matrix type.
+ * @param lhs Left-hand unitary.
+ * @param rhs Right-hand unitary.
+ * @param tol Absolute tolerance for overlap and entry-wise comparison.
+ * @return True when @p lhs and @p rhs differ only by a global phase.
+ */
+template <SupportedMatrix Matrix>
+[[nodiscard]] bool isEquivalentUpToGlobalPhase(const Matrix& lhs,
+                                               const Matrix& rhs,
+                                               double tol = MATRIX_TOLERANCE) {
+  const auto overlap = (rhs.adjoint() * lhs).trace();
+  if (std::abs(overlap) <= tol) {
+    return false;
+  }
+  const auto factor = overlap / std::abs(overlap);
+  return lhs.isApprox(factor * rhs, tol);
+}
+
 /// Scalar-on-the-left multiply `scalar * matrix` (commutes with the member
 /// `matrix * scalar`). Provided so generic code can scale a matrix from
 /// either side.

mlir/lib/Compiler/Programs.cpp

@@ -343,6 +343,17 @@ bool QCOProgram::fuseSingleQubitUnitaryRuns(const std::string_view basis) {
       "failed to fuse single-qubit unitary runs"));
 }
 
+bool QCOProgram::fuseTwoQubitUnitaryRuns(const std::string_view nativeGates) {
+  qco::FuseTwoQubitUnitaryRunsOptions options;
+  options.nativeGates = nativeGates;
+  return succeeded(runPasses(
+      module(),
+      [&options](OpPassManager& pm) {
+        pm.addPass(qco::createFuseTwoQubitUnitaryRuns(options));
+      },
+      "failed to fuse two-qubit unitary runs"));
+}
+
 bool QCOProgram::unrollQuantumLoops(const int64_t factor) {
   qco::QuantumLoopUnrollOptions options;
   options.unrollFactor = factor;

mlir/lib/Dialect/QCO/Transforms/CMakeLists.txt

@@ -24,11 +24,11 @@ add_mlir_library(
 
 mqt_mlir_target_use_project_options(MLIRQCOTransforms)
 
-# collect header files
-file(GLOB_RECURSE PASSES_HEADERS_SOURCE
-     ${MQT_MLIR_SOURCE_INCLUDE_DIR}/mlir/Dialect/QCO/Transforms/*.h)
-file(GLOB_RECURSE PASSES_HEADERS_BUILD
-     ${MQT_MLIR_BUILD_INCLUDE_DIR}/mlir/Dialect/QCO/Transforms/*.inc)
+# collect header files (subdirs: Decomposition/, …)
+file(GLOB_RECURSE PASSES_HEADERS_SOURCE CONFIGURE_DEPENDS
+     "${MQT_MLIR_SOURCE_INCLUDE_DIR}/mlir/Dialect/QCO/Transforms/*.h")
+file(GLOB_RECURSE PASSES_HEADERS_BUILD CONFIGURE_DEPENDS
+     "${MQT_MLIR_BUILD_INCLUDE_DIR}/mlir/Dialect/QCO/Transforms/*.inc")
 
 # add public headers using file sets
 target_sources(

mlir/lib/Dialect/QCO/Transforms/Decomposition/NativeGateset.cpp

@@ -10,12 +10,16 @@
 
 #include "mlir/Dialect/QCO/Transforms/Decomposition/NativeGateset.h"
 
+#include "mlir/Dialect/QCO/IR/QCOInterfaces.h"
+#include "mlir/Dialect/QCO/IR/QCOOps.h"
 #include "mlir/Dialect/QCO/Transforms/Decomposition/Euler.h"
 #include "mlir/Dialect/QCO/Transforms/Decomposition/Weyl.h"
 #include "mlir/Dialect/QCO/Utils/Matrix.h"
 
 #include <llvm/ADT/StringSwitch.h>
+#include <llvm/ADT/TypeSwitch.h>
 #include <llvm/Support/ErrorHandling.h>
+#include <mlir/IR/Operation.h>
 #include <mlir/Support/LLVM.h>
 
 #include <optional>
@@ -141,6 +145,48 @@ NativeGateset::decomposeTarget(const Matrix4x4& target) const {
   return cachedNativeBasisDecomposer(*entangler).decomposeTarget(target);
 }
 
+static std::optional<NativeGateKind> gateKindFor(UnitaryOpInterface op) {
+  return TypeSwitch<Operation*, std::optional<NativeGateKind>>(
+             op.getOperation())
+      .Case<UOp>([](UOp) { return NativeGateKind::U; })
+      .Case<XOp>([](XOp) { return NativeGateKind::X; })
+      .Case<SXOp>([](SXOp) { return NativeGateKind::SX; })
+      .Case<RZOp>([](RZOp) { return NativeGateKind::RZ; })
+      .Case<RXOp>([](RXOp) { return NativeGateKind::RX; })
+      .Case<RYOp>([](RYOp) { return NativeGateKind::RY; })
+      .Case<ROp>([](ROp) { return NativeGateKind::R; })
+      .Default([](Operation*) { return std::nullopt; });
+}
+
+static std::optional<NativeGateKind> entanglerKindFor(CtrlOp ctrl) {
+  if (ctrl.getNumControls() != 1 || ctrl.getNumTargets() != 1 ||
+      ctrl.getNumBodyUnitaries() != 1) {
+    return std::nullopt;
+  }
+  return TypeSwitch<Operation*, std::optional<NativeGateKind>>(
+             ctrl.getBodyUnitary(0).getOperation())
+      .Case<XOp>([](XOp) { return NativeGateKind::CX; })
+      .Case<ZOp>([](ZOp) { return NativeGateKind::CZ; })
+      .Default([](Operation*) { return std::nullopt; });
+}
+
+bool NativeGateset::allowsOp(Operation* op) const {
+  return TypeSwitch<Operation*, bool>(op)
+      .Case<BarrierOp, GPhaseOp>([](auto) { return true; })
+      .Case<CtrlOp>([&](CtrlOp ctrl) {
+        const auto kind = entanglerKindFor(ctrl);
+        return kind && gates.contains(*kind);
+      })
+      .Case<UnitaryOpInterface>([&](UnitaryOpInterface unitary) {
+        if (!unitary.isSingleQubit()) {
+          return false;
+        }
+        const auto gate = gateKindFor(unitary);
+        return gate && gates.contains(*gate);
+      })
+      .Default([](Operation*) { return false; });
+}
+
 std::optional<NativeGateset> NativeGateset::parse(StringRef nativeGates) {
   auto gates = parseGateSet(nativeGates);
   if (!gates) {

mlir/lib/Dialect/QCO/Transforms/NativeSynthesis/FuseSingleQubitUnitaryRuns.cpp

@@ -137,10 +137,13 @@ namespace {
 struct FuseSingleQubitUnitaryRunsPattern final
     : OpInterfaceRewritePattern<UnitaryOpInterface> {
   FuseSingleQubitUnitaryRunsPattern(MLIRContext* context,
-                                    const decomposition::EulerBasis basis)
-      : OpInterfaceRewritePattern(context), basis(basis) {}
+                                    const decomposition::EulerBasis basis,
+                                    const bool skipControlledBodies)
+      : OpInterfaceRewritePattern(context), basis(basis),
+        skipControlledBodies(skipControlledBodies) {}
 
   decomposition::EulerBasis basis;
+  bool skipControlledBodies;
 
   /**
    * @brief Whether `op` starts a run.
@@ -165,6 +168,10 @@ struct FuseSingleQubitUnitaryRunsPattern final
    */
   LogicalResult matchAndRewrite(UnitaryOpInterface op,
                                 PatternRewriter& rewriter) const override {
+    if (skipControlledBodies &&
+        (op.getOperation()->getParentOfType<CtrlOp>() != nullptr)) {
+      return failure();
+    }
     if (!isRunStart(op)) {
       return failure();
     }
@@ -208,8 +215,8 @@ struct FuseSingleQubitUnitaryRunsPass final
     }
 
     RewritePatternSet patterns(&getContext());
-    patterns.add<FuseSingleQubitUnitaryRunsPattern>(patterns.getContext(),
-                                                    *parsed);
+    decomposition::populateFuseSingleQubitUnitaryRunsPatterns(
+        patterns, *parsed, /*skipControlledBodies=*/false);
 
     if (failed(applyPatternsGreedily(module, std::move(patterns)))) {
       signalPassFailure();
@@ -220,3 +227,14 @@ struct FuseSingleQubitUnitaryRunsPass final
 } // namespace
 
 } // namespace mlir::qco
+
+namespace mlir::qco::decomposition {
+
+void populateFuseSingleQubitUnitaryRunsPatterns(
+    RewritePatternSet& patterns, const EulerBasis basis,
+    const bool skipControlledBodies) {
+  patterns.add<FuseSingleQubitUnitaryRunsPattern>(patterns.getContext(), basis,
+                                                  skipControlledBodies);
+}
+
+} // namespace mlir::qco::decomposition