✨ Add QCO Euler synthesis and fuse-single-qubit-unitary-runs pass (#1672)

## Description
- Consolidate Euler decomposition into `Euler.h` / `Euler.cpp` (angle
extraction + `synthesizeUnitary1QEuler` IR emission), replacing the
previous `EulerDecomposition` / `GateSequence` / `Helpers` /
`UnitaryMatrices` split.
- Add the `fuse-single-qubit-unitary-runs` MLIR pass: fuse maximal runs
of constant single-qubit unitaries on a wire by composing 2×2 matrices
and resynthesizing in a configurable Euler basis (`zyz`, `zxz`, `xzx`,
`xyx`, `u`, `zsxx`), with `gphase` for exact global phase.

Split up and refactored from #1665.

## AI Assistance
Used Composer via Cursor for parts of this change. I reviewed the full
diff and take responsibility for everything in this PR.

## 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.
- [ ] 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).
- [ ] 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.

---------

Signed-off-by: simon1hofmann <119581649+simon1hofmann@users.noreply.github.com>
Signed-off-by: burgholzer <burgholzer@me.com>
Signed-off-by: Lukas Burgholzer <burgholzer@me.com>
Co-authored-by: Tamino Bauknecht <dev@tb6.eu>
Co-authored-by: Daniel Haag <121057143+denialhaag@users.noreply.github.com>
Co-authored-by: Copilot <copilot@github.com>
Co-authored-by: burgholzer <burgholzer@me.com>

Author: 5 people

CHANGELOG.md

@@ -12,6 +12,9 @@ with the exception that minor releases may include breaking changes.
 
 ### Added
 
+- ✨ Add a `fuse-single-qubit-unitary-runs` pass
+  for fusing compile-time single-qubit unitary runs via Euler resynthesis
+  ([#1672]) ([**@simon1hofmann**], [**@burgholzer**])
 - ✨ Add QIR program format support to the DDSIM QDMI Device ([#1766])
   ([**@rturrado**])
 - 🚸 Add [CMake presets] to provide a standardized
@@ -621,6 +624,7 @@ changelogs._
 [#1675]: https://github.com/munich-quantum-toolkit/core/pull/1675
 [#1674]: https://github.com/munich-quantum-toolkit/core/pull/1674
 [#1673]: https://github.com/munich-quantum-toolkit/core/pull/1673
+[#1672]: https://github.com/munich-quantum-toolkit/core/pull/1672
 [#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

mlir/include/mlir/Dialect/QCO/IR/QCODialect.h

@@ -10,6 +10,8 @@
 
 #pragma once
 
+#include "mlir/Dialect/Utils/Utils.h"
+
 #include <llvm/ADT/STLExtras.h>
 #include <mlir/Dialect/Func/IR/FuncOps.h>
 #include <mlir/IR/Attributes.h>
@@ -127,6 +129,16 @@ template <size_t T, size_t P> class TargetAndParameterArityTrait {
       llvm::reportFatalUsageError(
           "Given qubit is not an input of the operation");
     }
+
+    [[nodiscard]] bool hasCompileTimeKnownUnitaryMatrix() {
+      if constexpr (P == 0) {
+        return true;
+      } else {
+        return llvm::all_of(this->getParameters(), [](Value param) {
+          return utils::valueToDouble(param).has_value();
+        });
+      }
+    }
   };
 };
 
@@ -151,8 +163,9 @@ inline func::FuncOp getEntryPoint(ModuleOp op) {
   };
 
   for (auto func : op.getOps<func::FuncOp>()) {
-    const auto passthrough = func->getAttrOfType<ArrayAttr>(PASSTHROUGH_LABEL);
-    if (passthrough && llvm::any_of(passthrough, isEntry)) {
+    if (const auto passthrough =
+            func->getAttrOfType<ArrayAttr>(PASSTHROUGH_LABEL);
+        passthrough && llvm::any_of(passthrough, isEntry)) {
       return func;
     }
   }

mlir/include/mlir/Dialect/QCO/IR/QCOInterfaces.td

@@ -39,6 +39,11 @@ def UnitaryOpInterface : OpInterface<"UnitaryOpInterface"> {
             return true;
           }
           return false;
+        } else if constexpr (std::is_same_v<ValueT, DynamicMatrix>) {
+          if (auto matrix = $_op.getUnitaryMatrix()) {
+            return out.assignFrom(*matrix);
+          }
+          return false;
         } else {
           return false;
         }
@@ -63,6 +68,11 @@ def UnitaryOpInterface : OpInterface<"UnitaryOpInterface"> {
             return true;
           }
           return false;
+        } else if constexpr (std::is_same_v<ValueT, DynamicMatrix>) {
+          if (auto matrix = $_op.getUnitaryMatrix()) {
+            return out.assignFrom(*matrix);
+          }
+          return false;
         } else {
           return false;
         }
@@ -87,6 +97,11 @@ def UnitaryOpInterface : OpInterface<"UnitaryOpInterface"> {
             return true;
           }
           return false;
+        } else if constexpr (std::is_same_v<ValueT, DynamicMatrix>) {
+          if (auto matrix = $_op.getUnitaryMatrix()) {
+            return out.assignFrom(*matrix);
+          }
+          return false;
         } else {
           return false;
         }
@@ -188,6 +203,9 @@ def UnitaryOpInterface : OpInterface<"UnitaryOpInterface"> {
                       "StringRef", "getBaseSymbol", (ins)>,
 
       // Unitary matrix helpers
+      InterfaceMethod<"Returns true if the operation has a compile-time known "
+                      "unitary matrix representation, false otherwise.",
+                      "bool", "hasCompileTimeKnownUnitaryMatrix", (ins)>,
       InterfaceMethod<"Populates the given 1x1 unitary matrix if possible.",
                       "bool", "getUnitaryMatrix1x1", (ins "Matrix1x1&":$out),
                       unitaryMatrix1x1MethodBody>,

mlir/include/mlir/Dialect/QCO/IR/QCOOps.td

@@ -1030,6 +1030,8 @@ def BarrierOp : QCOOp<"barrier", traits = [UnitaryOpInterface]> {
         static Value getParameter(size_t i) { llvm::reportFatalUsageError("BarrierOp has no parameters"); }
         static OperandRange getParameters() { return {nullptr, 0}; }
         [[nodiscard]] static StringRef getBaseSymbol() { return "barrier"; }
+        [[nodiscard]] bool hasCompileTimeKnownUnitaryMatrix() const { return true; }
+        [[nodiscard]] DynamicMatrix getUnitaryMatrix();
     }];
 
   let builders = [OpBuilder<(ins "ValueRange":$qubits)>];
@@ -1126,6 +1128,7 @@ def CtrlOp : QCOOp<"ctrl",
         Value getParameter(size_t i) { llvm::reportFatalUsageError("CtrlOp does not have parameters"); }
         OperandRange getParameters() { return {nullptr, 0}; }
         [[nodiscard]] static StringRef getBaseSymbol() { return "ctrl"; }
+        [[nodiscard]] bool hasCompileTimeKnownUnitaryMatrix();
         [[nodiscard]] std::optional<DynamicMatrix> getUnitaryMatrix();
     }];
 
@@ -1199,6 +1202,7 @@ def InvOp : QCOOp<"inv", traits = [UnitaryOpInterface,
         Value getParameter(size_t i) { llvm::reportFatalUsageError("InvOp does not have parameters"); }
         OperandRange getParameters() { return {nullptr, 0}; }
         [[nodiscard]] static StringRef getBaseSymbol() { return "inv"; }
+        [[nodiscard]] bool hasCompileTimeKnownUnitaryMatrix();
         [[nodiscard]] std::optional<DynamicMatrix> getUnitaryMatrix();
     }];
 

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

@@ -0,0 +1,66 @@
+/*
+ * 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/Utils/Matrix.h"
+
+#include <mlir/IR/Builders.h>
+#include <mlir/IR/Location.h>
+#include <mlir/Support/LLVM.h>
+
+#include <cstddef>
+#include <cstdint>
+#include <optional>
+
+namespace mlir::qco::decomposition {
+
+/**
+ * @brief Native gate sets for single-qubit Euler synthesis.
+ */
+enum class EulerBasis : std::uint8_t {
+  ZYZ = 0,  ///< `RZ(phi) * RY(theta) * RZ(lambda)`.
+  ZXZ = 1,  ///< `RZ(phi) * RX(theta) * RZ(lambda)`.
+  XZX = 2,  ///< `RX(phi) * RZ(theta) * RX(lambda)`.
+  XYX = 3,  ///< `RX(phi) * RY(theta) * RX(lambda)`.
+  U = 4,    ///< `U(theta, phi, lambda)`.
+  ZSXX = 5, ///< `RZ` / `SX` / `X` synthesis via ZYZ decomposition.
+};
+
+/**
+ * @brief Parses a basis name (e.g. `zyz`, `zsxx`; case-insensitive).
+ *
+ * @param basis The basis name.
+ * @return The parsed basis, or `std::nullopt` if unrecognized.
+ */
+[[nodiscard]] std::optional<EulerBasis> parseEulerBasis(StringRef basis);
+
+/**
+ * @brief Synthesizes a composed single-qubit unitary as gates in @p basis.
+ *
+ * Returns `std::nullopt` when @p hasNonBasisGate is false and resynthesis
+ * would not shorten a run of @p runSize gates; otherwise emits gates
+ * (including `qco.gphase` when needed).
+ *
+ * @param builder Builder for the emitted operations.
+ * @param loc Location for the emitted operations.
+ * @param qubit Input qubit value.
+ * @param composed Composed unitary to synthesize.
+ * @param runSize Number of gates in the run.
+ * @param hasNonBasisGate Whether the run contains a gate outside @p basis.
+ * @param basis The target Euler basis.
+ * @return The synthesized qubit, or `std::nullopt` if synthesis is skipped.
+ */
+[[nodiscard]] std::optional<Value>
+synthesizeUnitary1QEuler(OpBuilder& builder, Location loc, Value qubit,
+                         const Matrix2x2& composed, std::size_t runSize,
+                         bool hasNonBasisGate, EulerBasis basis);
+
+} // namespace mlir::qco::decomposition

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

@@ -40,6 +40,32 @@ def MergeSingleQubitRotationGates
   }];
 }
 
+def FuseSingleQubitUnitaryRuns
+    : Pass<"fuse-single-qubit-unitary-runs", "mlir::ModuleOp"> {
+  let dependentDialects = ["mlir::qco::QCODialect",
+                           "::mlir::arith::ArithDialect",
+                           "::mlir::qtensor::QTensorDialect"];
+  let summary = "Fuse single-qubit unitary runs using Euler resynthesis";
+  let description = [{
+    Matches maximal runs of consecutive single-qubit unitary operations on the
+    same qubit wire (anchored at each run head), composes their constant unitary
+    matrices, and replaces a run with an equivalent sequence of basis gates when
+    beneficial: when the run contains a gate outside the target `basis`, or when
+    Euler resynthesis would shorten it (`synthesizeUnitary1QEuler`). Runs that are
+    already in the target `basis` and no shorter than the canonical synthesis
+    length are left unchanged.
+
+    The emitted basis is controlled via the `basis` option (e.g. `zyz`, `zsxx`).
+    A `gphase` correction is inserted when needed so the rewritten sequence
+    matches the composed matrix exactly (not only up to global phase).
+
+    Currently, only operations whose unitary matrix can be obtained at compile
+    time are fused.
+  }];
+  let options = [Option<"basis", "basis", "std::string", "\"zyz\"",
+                        "Target Euler basis (zyz, zxz, xzx, xyx, u, zsxx).">];
+}
+
 def QuantumLoopUnroll
     : InterfacePass<"quantum-loop-unroll", "FunctionOpInterface"> {
   let dependentDialects = ["mlir::qco::QCODialect", "mlir::scf::SCFDialect"];