✨ Add decompose-multi-controlled pass for multi-controlled X/Z decomposition

CHANGELOG.md

@@ -16,10 +16,12 @@ releases may include breaking changes.
   ([#1887]) ([**@flowerthrower**], [**@burgholzer**])
 - ✨ Add QIR Output Schemas support to the QIR runtime ([#1877])
   ([**@rturrado**])
+- ✨ Add a `decompose-multi-controlled` pass for decomposing multi-controlled X
+  and Z gates into one- and two-qubit gates ([#1810]) ([**@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
@@ -648,6 +650,7 @@ changelogs._
 [#1823]: https://github.com/munich-quantum-toolkit/core/pull/1823
 [#1817]: https://github.com/munich-quantum-toolkit/core/pull/1817
 [#1814]: https://github.com/munich-quantum-toolkit/core/pull/1814
+[#1810]: https://github.com/munich-quantum-toolkit/core/pull/1810
 [#1809]: https://github.com/munich-quantum-toolkit/core/pull/1809
 [#1808]: https://github.com/munich-quantum-toolkit/core/pull/1808
 [#1807]: https://github.com/munich-quantum-toolkit/core/pull/1807

mlir/include/mlir/Compiler/CompilerPipeline.h

@@ -13,6 +13,7 @@
 #include <mlir/Pass/PassManager.h>
 #include <mlir/Support/LogicalResult.h>
 
+#include <cstdint>
 #include <string>
 
 namespace mlir {
@@ -49,6 +50,20 @@ struct QuantumCompilerConfig {
 
   /// Enable Hadamard lifting
   bool enableHadamardLifting = false;
+
+  /// Decompose multi-controlled X/Z/phase gates through the full pass chain:
+  /// @c decompose-multi-controlled (k &ge; 4), @c decompose-three-controlled
+  /// (k = 3), and @c decompose-two-controlled (k = 2 and `qco.rccx`). @ref
+  /// decomposeMultiControlledMinControls governs when HP24 retains two- and
+  /// three-control building blocks versus expanding them inline. When enabled,
+  /// @ref decomposeMultiControlledMinControls must be at least 2; the pipeline
+  /// rejects smaller values before running any passes.
+  bool enableDecomposeMultiControlled = false;
+
+  /// Minimum control count for @ref enableDecomposeMultiControlled (default 2).
+  /// Must be at least 2 when decomposition is enabled; values below 2 cause
+  /// @ref QuantumCompilerPipeline::runPipeline to fail.
+  std::uint64_t decomposeMultiControlledMinControls = 2;
 };
 
 /**

mlir/include/mlir/Dialect/QCO/Builder/QCOProgramBuilder.h

@@ -1151,6 +1151,17 @@ class QCOProgramBuilder final : public ImplicitLocOpBuilder {
 
 #undef DECLARE_TWO_TARGET_TWO_PARAMETER
 
+  /**
+   * @brief Apply a relative-phase CCX (`RCCX`) gate to three qubits.
+   *
+   * @param qubit0 First control qubit (must be valid/unconsumed)
+   * @param qubit1 Second control qubit (must be valid/unconsumed)
+   * @param qubit2 Target qubit (must be valid/unconsumed)
+   * @return Output qubits `(qubit0, qubit1, qubit2)`
+   */
+  std::tuple<Value, Value, Value> rccx(Value qubit0, Value qubit1,
+                                       Value qubit2);
+
   // BarrierOp
 
   /**

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

@@ -175,6 +175,7 @@ def OneTargetThreeParameter : TargetAndParameterArityTrait<1, 3>;
 def TwoTargetZeroParameter : TargetAndParameterArityTrait<2, 0>;
 def TwoTargetOneParameter : TargetAndParameterArityTrait<2, 1>;
 def TwoTargetTwoParameter : TargetAndParameterArityTrait<2, 2>;
+def ThreeTargetZeroParameter : TargetAndParameterArityTrait<3, 0>;
 
 //===----------------------------------------------------------------------===//
 // Unitary Operations
@@ -784,6 +785,42 @@ def DCXOp : QCOOp<"dcx",
   let hasCanonicalizer = 1;
 }
 
+def RCCXOp
+    : QCOOp<"rccx", traits = [UnitaryOpInterface, ThreeTargetZeroParameter]> {
+  let summary = "Apply a relative-phase CCX gate to three qubits";
+  let description = [{
+        Applies a relative-phase Toffoli (`RCCX`) to three qubits and returns the
+        transformed qubits. The gate acts as a controlled @f$X@f$ on @f$q_2@f$
+        when @f$q_0@f$ and @f$q_1@f$ are @f$|1\rangle@f$, but may introduce a
+        non-trivial phase on @f$|111\rangle@f$ relative to a standard `CCX`.
+        This matches the `rccx` gate in OpenQASM 3 `qelib1.inc` and is commonly
+        used as a building block in multi-controlled @f$X@f$ decompositions.
+
+        Example:
+        ```mlir
+        %c0_out, %c1_out, %t_out = qco.rccx %c0_in, %c1_in, %t_in
+            : !qco.qubit, !qco.qubit, !qco.qubit
+            -> !qco.qubit, !qco.qubit, !qco.qubit
+        ```
+    }];
+
+  let arguments =
+      (ins Arg<QubitType, "the first control qubit", [MemRead]>:$qubit0_in,
+          Arg<QubitType, "the second control qubit", [MemRead]>:$qubit1_in,
+          Arg<QubitType, "the target qubit", [MemRead]>:$qubit2_in);
+  let results = (outs QubitType:$qubit0_out, QubitType:$qubit1_out,
+      QubitType:$qubit2_out);
+  let assemblyFormat =
+      "$qubit0_in `,` $qubit1_in `,` $qubit2_in attr-dict `:` type($qubit0_in) "
+      "`,` type($qubit1_in) `,` type($qubit2_in) `->` type($qubit0_out) `,` "
+      "type($qubit1_out) `,` type($qubit2_out)";
+
+  let extraClassDeclaration = [{
+        [[nodiscard]] static StringRef getBaseSymbol() { return "rccx"; }
+        [[nodiscard]] static DynamicMatrix getUnitaryMatrix();
+    }];
+}
+
 def ECROp : QCOOp<"ecr",
                   traits = [UnitaryOpInterface, TwoTargetZeroParameter, Pure]> {
   let summary = "Apply an ECR gate to two qubits";

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

@@ -0,0 +1,146 @@
+/*
+ * 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/IR/Value.h>
+#include <mlir/Support/LLVM.h>
+
+#include <cstdint>
+#include <optional>
+
+namespace mlir::qco::decomposition {
+
+/// Target Pauli or phase gate inside a multi-controlled `qco.ctrl` body.
+enum class ControlledTarget : std::uint8_t { X, Z, Phase };
+
+/**
+ * @brief Synthesizes a two-controlled Pauli-X, Pauli-Z, or phase gate.
+ *
+ * @param builder Builder positioned at the desired insertion point.
+ * @param loc Location attached to the emitted operations.
+ * @param control0 First control qubit (MSB).
+ * @param control1 Second control qubit.
+ * @param target Target qubit (LSB).
+ * @param gate Target gate type (`CCX`, `CCZ`, or `CCPhase`).
+ * @param theta Phase angle in radians when @p gate is
+ * `ControlledTarget::Phase`.
+ * @return The updated SSA values `[control0, control1, target]`.
+ */
+[[nodiscard]] SmallVector<Value>
+synthesizeTwoControlled(OpBuilder& builder, Location loc, Value control0,
+                        Value control1, Value target, ControlledTarget gate,
+                        std::optional<double> theta = std::nullopt);
+
+/**
+ * @brief Synthesizes a compile-time-known two-controlled unitary.
+ *
+ * @details Dispatches to @ref synthesizeTwoControlled when the unitary matches
+ * two-controlled @f$X@f$ or two-controlled phase patterns.
+ *
+ * @param builder Builder positioned at the desired insertion point.
+ * @param loc Location attached to the emitted operations.
+ * @param control0 First control qubit (MSB).
+ * @param control1 Second control qubit.
+ * @param target Target qubit (LSB).
+ * @param unitary Compile-time-known @f$8 \times 8@f$ unitary matrix.
+ * @return The updated SSA values `[control0, control1, target]`.
+ *
+ * @pre @p unitary must be @f$8 \times 8@f$.
+ */
+[[nodiscard]] SmallVector<Value>
+synthesizeTwoControlled(OpBuilder& builder, Location loc, Value control0,
+                        Value control1, Value target,
+                        const DynamicMatrix& unitary);
+
+/**
+ * @brief Emits an elementary-gate decomposition of a relative-phase CCX
+ * (`RCCX`).
+ *
+ * @param builder Builder positioned at the desired insertion point.
+ * @param loc Location attached to the emitted operations.
+ * @param control0 First control qubit.
+ * @param control1 Second control qubit.
+ * @param target Target qubit.
+ * @return The updated SSA values `[control0, control1, target]`.
+ */
+[[nodiscard]] SmallVector<Value> synthesizeRCCX(OpBuilder& builder,
+                                                Location loc, Value control0,
+                                                Value control1, Value target);
+
+/**
+ * @brief Synthesizes a three-controlled Pauli-X, Pauli-Z, or phase gate.
+ *
+ * @param builder Builder positioned at the desired insertion point.
+ * @param loc Location attached to the emitted operations.
+ * @param controls Exactly three control qubits.
+ * @param target Target qubit.
+ * @param gate Target gate type (`CCCX`, `CCCZ`, or `CCCPhase`).
+ * @param theta Phase angle in radians when @p gate is
+ * `ControlledTarget::Phase`.
+ * @return The updated SSA values, ordered as `[controls..., target]`.
+ *
+ * @pre @p controls must contain exactly three qubits.
+ */
+[[nodiscard]] SmallVector<Value>
+synthesizeThreeControlled(OpBuilder& builder, Location loc, ValueRange controls,
+                          Value target, ControlledTarget gate,
+                          std::optional<double> theta = std::nullopt);
+
+/**
+ * @brief Emits a decomposition of a multi-controlled Pauli-X, Pauli-Z, or
+ * phase gate.
+ *
+ * @details For exactly three controls, dispatches to @ref
+ * synthesizeThreeControlled (used by @c decompose-three-controlled). For four
+ * or more controls, applies the Huang-Palsberg (PLDI 2024) no-ancilla MCX core
+ * (with target Hadamard bookends for Pauli-X). Subcircuits with two or three
+ * controls are expanded via @ref synthesizeTwoControlled and @ref
+ * synthesizeThreeControlled when @p minControls is at most the subcircuit
+ * control count; otherwise the corresponding `qco.ctrl` building blocks are
+ * retained for subsequent passes.
+ *
+ * @note Adapted from ``synth_mcx_noaux_hp24`` and ``synth_mcx_n_dirty_i15`` in
+ *       the IBM Qiskit framework.
+ *       (C) Copyright IBM 2025
+ *
+ *       This code is licensed under the Apache License, Version 2.0. You may
+ *       obtain a copy of this license in the LICENSE.txt file in the root
+ *       directory of this source tree or at
+ *       https://www.apache.org/licenses/LICENSE-2.0.
+ *
+ *       Any modifications or derivative works of this code must retain this
+ *       copyright notice, and modified files need to carry a notice
+ *       indicating that they have been altered from the originals.
+ *
+ * @param builder Builder positioned at the desired insertion point.
+ * @param loc Location attached to the emitted operations.
+ * @param controls Control qubits (at least three).
+ * @param target Target qubit.
+ * @param minControls Minimum control count for which subcircuits are expanded
+ * rather than retained as building-block `qco.ctrl` operations.
+ * @param gate Target gate type.
+ * @param theta Phase angle when @p gate is `ControlledTarget::Phase`.
+ * @return The updated SSA values, ordered as `[controls..., target]`.
+ *
+ * @pre @p controls must contain at least three qubits. The HP24 core is used
+ * only when @p controls has four or more elements.
+ */
+[[nodiscard]] SmallVector<Value>
+synthesizeMultiControlled(OpBuilder& builder, Location loc, ValueRange controls,
+                          Value target, std::uint64_t minControls,
+                          ControlledTarget gate,
+                          std::optional<double> theta = std::nullopt);
+
+} // namespace mlir::qco::decomposition

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

@@ -201,4 +201,75 @@ def HadamardLifting : Pass<"hadamard-lifting", "mlir::ModuleOp"> {
   }];
 }
 
+//===----------------------------------------------------------------------===//
+// Decomposition Passes
+//===----------------------------------------------------------------------===//
+
+def DecomposeMultiControlled
+    : Pass<"decompose-multi-controlled", "mlir::ModuleOp"> {
+  let dependentDialects = ["mlir::qco::QCODialect",
+                           "::mlir::arith::ArithDialect"];
+  let summary =
+      "Decompose four-or-more-controlled gates via Huang-Palsberg synthesis";
+  let description = [{
+    Decomposes multi-controlled Pauli-X, Pauli-Z, and phase gates (`qco.ctrl`
+    with `qco.x`, `qco.z`, or `qco.p` body) with at least four controls via
+    @ref mlir::qco::decomposition::synthesizeMultiControlled.
+
+    Gates with exactly three controls are handled by
+    @c decompose-three-controlled. Subcircuits with two or three controls are
+    expanded inline when `min-controls` is at most the subcircuit control count;
+    otherwise the corresponding `qco.ctrl` building blocks are retained for
+    subsequent @c decompose-three-controlled and @c decompose-two-controlled
+    passes.
+
+    The pass matches `qco.ctrl` operations with at least `min-controls` and at
+    least four control qubits.
+  }];
+  let options = [Option<
+      "minControls", "min-controls", "uint64_t", "2",
+      "Minimum control count for decomposing a top-level gate (must be at "
+      "least 4). Controlled gates with fewer than four controls are left to "
+      "@c decompose-three-controlled or @c decompose-two-controlled. Must be "
+      "at least 2.">];
+}
+
+def DecomposeThreeControlled
+    : Pass<"decompose-three-controlled", "mlir::ModuleOp"> {
+  let dependentDialects = ["mlir::qco::QCODialect",
+                           "::mlir::arith::ArithDialect"];
+  let summary =
+      "Decompose three-control CCCX/CCCZ/CCCP gates via three-controlled "
+      "synthesis";
+  let description = [{
+    Decomposes three-control building-block gates (`CCCX`, `CCCZ`, and
+    `CCCPhase`) via @ref mlir::qco::decomposition::synthesizeThreeControlled.
+
+    Pauli-X and Pauli-Z gates are expanded to elementary one- and two-qubit
+    gates. Phase gates are lowered to a three-control `qco.ctrl` with a
+    `qco.p` body for subsequent passes.
+
+    The pass matches `qco.ctrl` operations with exactly three controls and a
+    single `qco.x`, `qco.z`, or `qco.p` body on one target. Gates with fewer
+    than three controls (e.g. `CX`, `CCX`) are left unchanged.
+  }];
+}
+
+def DecomposeTwoControlled
+    : Pass<"decompose-two-controlled", "mlir::ModuleOp"> {
+  let dependentDialects = ["mlir::qco::QCODialect",
+                           "::mlir::arith::ArithDialect"];
+  let summary = "Decompose two-control CCX/CCZ/CCPhase and RCCX gates via "
+                "two-controlled synthesis";
+  let description = [{
+    Decomposes two-control building-block gates (`CCX`, `CCZ`, `CCPhase`) via
+    @ref mlir::qco::decomposition::synthesizeTwoControlled and standalone
+    `qco.rccx` gates via @ref mlir::qco::decomposition::synthesizeRCCX.
+
+    The pass matches `qco.ctrl` operations with exactly two controls and a
+    single `qco.x`, `qco.z`, or `qco.p` body on one target. Single-control
+    gates (e.g. `CX`, `CP`) are left unchanged.
+  }];
+}
+
 #endif // MLIR_DIALECT_QCO_TRANSFORMS_PASSES_TD

mlir/lib/Compiler/CompilerPipeline.cpp

@@ -77,6 +77,13 @@ QuantumCompilerPipeline::runPipeline(ModuleOp module,
                     "enabled and the record pointer to be non-null.\n";
     return failure();
   }
+  if (config_.enableDecomposeMultiControlled &&
+      config_.decomposeMultiControlledMinControls < 2) {
+    llvm::errs()
+        << "decomposeMultiControlledMinControls must be at least 2 when "
+           "enableDecomposeMultiControlled is enabled.\n";
+    return failure();
+  }
 
   auto runStage = [&](auto&& populatePasses) -> LogicalResult {
     PassManager pm(module.getContext());
@@ -147,6 +154,13 @@ QuantumCompilerPipeline::runPipeline(ModuleOp module,
   }
   // Stage 5: Optimization passes
   if (failed(runStage([&](PassManager& pm) {
+        if (config_.enableDecomposeMultiControlled) {
+          qco::DecomposeMultiControlledOptions options;
+          options.minControls = config_.decomposeMultiControlledMinControls;
+          pm.addPass(qco::createDecomposeMultiControlled(options));
+          pm.addPass(qco::createDecomposeThreeControlled());
+          pm.addPass(qco::createDecomposeTwoControlled());
+        }
         if (!config_.disableMergeSingleQubitRotationGates) {
           pm.addPass(qco::createMergeSingleQubitRotationGates());
         }

mlir/lib/Dialect/QCO/Builder/QCOProgramBuilder.cpp

@@ -39,6 +39,7 @@
 #include <cstddef>
 #include <cstdint>
 #include <string>
+#include <tuple>
 #include <utility>
 #include <variant>
 
@@ -795,6 +796,16 @@ DEFINE_TWO_TARGET_TWO_PARAMETER(XXMinusYYOp, xx_minus_yy, theta, beta)
 
 #undef DEFINE_TWO_TARGET_TWO_PARAMETER
 
+std::tuple<Value, Value, Value>
+QCOProgramBuilder::rccx(Value qubit0, Value qubit1, Value qubit2) {
+  checkFinalized();
+  auto op = RCCXOp::create(*this, qubit0, qubit1, qubit2);
+  updateQubitTracking(qubit0, op.getQubit0Out());
+  updateQubitTracking(qubit1, op.getQubit1Out());
+  updateQubitTracking(qubit2, op.getQubit2Out());
+  return {op.getQubit0Out(), op.getQubit1Out(), op.getQubit2Out()};
+}
+
 // BarrierOp
 
 ValueRange QCOProgramBuilder::barrier(ValueRange qubits) {