✨ Add inv Modifier for MLIR Redesign (#1330)

## Description

Adds a `qc.inv` and `qco.inv` Op, similar to the existing `CtrlOp`.

**Example**:
QC:
```mlir
qc.inv {
  qc.s %q0 : !qc.qubit
}
```
QCO:
```mlir
%targets_out = qco.inv (%arg0 = %targets_in) {
    %targets_res = qco.s %arg0 : !qco.qubit -> !qco.qubit
    qco.yield %targets_res : !qco.qubit
} : {!qco.qubit} -> {!qco.qubit}
```

**Things to note:**
- The canonicalizations are currently in QCO (such as replacing known
gates with their inverse). Could happen already in QC or in both.
- QuantumComputing (which eagerly replaces gates by their inverse) is
not touched by this PR. Afaik, the QC and QCO dialects are not directly
used by QuantumComputing yet.
- Missing: Handling of invs of unknown gates, for example iSWAP (the
only standard gate for which there's no "trivial" inverse). `inv { iSWAP
}` will currently error on the translation to QIR. A reasonable tactic
could be to get the inverse unitary matrix and decompose it into native
gates. I think this is outside the scope of this PR, though.

Fixes #1130 

## Checklist:

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

---------

Signed-off-by: burgholzer <[email protected]>
Co-authored-by: burgholzer <[email protected]>

Author: Ectras

CHANGELOG.md

@@ -11,7 +11,9 @@ This project adheres to [Semantic Versioning], with the exception that minor rel
 
 ### Added
 
-- ✨ Add initial infrastructure for new QC and QCO MLIR dialects ([#1264], [#1402], [#1428], [#1430], [#1436], [#1443], [#1446], [#1464], [#1465], [#1470], [#1471], [#1472], [#1474], [#1475]) ([**@burgholzer**], [**@denialhaag**], [**@taminob**], [**@DRovara**], [**@li-mingbao**])
+- ✨ 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])
+  ([**@burgholzer**], [**@denialhaag**], [**@taminob**], [**@DRovara**], [**@li-mingbao**], [**@Ectras**])
 
 ### Changed
 
@@ -365,6 +367,7 @@ _📚 Refer to the [GitHub Release Notes](https://github.com/munich-quantum-tool
 [#1355]: https://github.com/munich-quantum-toolkit/core/pull/1355
 [#1338]: https://github.com/munich-quantum-toolkit/core/pull/1338
 [#1336]: https://github.com/munich-quantum-toolkit/core/pull/1336
+[#1330]: https://github.com/munich-quantum-toolkit/core/pull/1330
 [#1328]: https://github.com/munich-quantum-toolkit/core/pull/1328
 [#1327]: https://github.com/munich-quantum-toolkit/core/pull/1327
 [#1310]: https://github.com/munich-quantum-toolkit/core/pull/1310
@@ -502,6 +505,7 @@ _📚 Refer to the [GitHub Release Notes](https://github.com/munich-quantum-tool
 [**@lsschmid**]: https://github.com/lsschmid
 [**@marcelwa**]: https://github.com/marcelwa
 [**@lirem101**]: https://github.com/lirem101
+[**@Ectras**]: https://github.com/Ectras
 
 <!-- General links -->
 

cmake/SetupMLIR.cmake

@@ -33,8 +33,7 @@ set(LLVM_ENABLE_RTTI ON)
 set(LLVM_ENABLE_EH ON)
 include(HandleLLVMOptions)
 
-include_directories(${LLVM_INCLUDE_DIRS})
-include_directories(${MLIR_INCLUDE_DIRS})
+include_directories(SYSTEM ${LLVM_INCLUDE_DIRS} ${MLIR_INCLUDE_DIRS})
 include_directories(${MQT_MLIR_SOURCE_INCLUDE_DIR})
 include_directories(${MQT_MLIR_BUILD_INCLUDE_DIR})
 link_directories(${LLVM_BUILD_LIBRARY_DIR})

mlir/.clang-tidy

@@ -6,7 +6,8 @@ Checks: |
   llvm-prefer-static-over-anonymous-namespace,
   -misc-use-anonymous-namespace,
   llvm-twine-local,
-  -cppcoreguidelines-pro-bounds-avoid-unchecked-container-access
+  -cppcoreguidelines-pro-bounds-avoid-unchecked-container-access,
+  -*-const-correctness,
 
 CheckOptions:
   - key: misc-include-cleaner.IgnoreHeaders

mlir/include/mlir/Dialect/QC/Builder/QCProgramBuilder.h

@@ -844,6 +844,25 @@ class QCProgramBuilder final : public ImplicitLocOpBuilder {
   QCProgramBuilder& ctrl(ValueRange controls,
                          const std::function<void()>& body);
 
+  /**
+   * @brief Apply an inverse (i.e., adjoint) operation.
+   *
+   * @param body Function that builds the body containing the operation to
+   * invert
+   * @return Reference to this builder for method chaining
+   *
+   * @par Example:
+   * ```c++
+   * builder.inv([&] { builder.s(q0); });
+   * ```
+   * ```mlir
+   * qc.inv {
+   *   qc.s %q0 : !qc.qubit
+   * }
+   * ```
+   */
+  QCProgramBuilder& inv(const std::function<void()>& body);
+
   //===--------------------------------------------------------------------===//
   // Deallocation
   //===--------------------------------------------------------------------===//

mlir/include/mlir/Dialect/QC/IR/QCOps.td

@@ -973,4 +973,48 @@ def CtrlOp : QCOp<"ctrl",
     let hasVerifier = 1;
 }
 
+def InvOp : QCOp<"inv",
+            traits = [
+                UnitaryOpInterface,
+                SingleBlockImplicitTerminator<"::mlir::qc::YieldOp">,
+                RecursiveMemoryEffects
+            ]> {
+    let summary = "Invert a unitary operation";
+    let description = [{
+        A modifier operation that inverts the unitary operation defined in its body
+        region.
+
+        Example:
+        ```mlir
+        qc.inv {
+          qc.s %q0 : !qc.qubit
+        }
+        ```
+    }];
+
+    let regions = (region SizedRegion<1>:$region);
+    let assemblyFormat = "$region attr-dict";
+
+    let extraClassDeclaration = [{
+        [[nodiscard]] UnitaryOpInterface getBodyUnitary();
+        size_t getNumQubits();
+        size_t getNumTargets();
+        static size_t getNumControls();
+        Value getQubit(size_t i);
+        Value getTarget(size_t i);
+        static Value getControl(size_t i);
+        size_t getNumParams();
+        Value getParameter(size_t i);
+        static StringRef getBaseSymbol() { return "inv"; }
+    }];
+
+    let builders = [
+        OpBuilder<(ins "UnitaryOpInterface":$bodyUnitary)>,
+        OpBuilder<(ins "const std::function<void()>&":$bodyBuilder)>
+    ];
+
+    let hasCanonicalizer = 1;
+    let hasVerifier = 1;
+}
+
 #endif // QC_OPS

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

@@ -1005,6 +1005,31 @@ class QCOProgramBuilder final : public ImplicitLocOpBuilder {
   ctrl(ValueRange controls, ValueRange targets,
        llvm::function_ref<llvm::SmallVector<Value>(ValueRange)> body);
 
+  /**
+   * @brief Apply an inverse operation
+   *
+   * @param qubits Qubits involved in the operation
+   * @param body Function that builds the body containing the target operation
+   * @return Output qubits
+   *
+   * @par Example:
+   * ```c++
+   * qubits_out = builder.inv(q0_in,
+   *   [&](ValueRange qubits) -> llvm::SmallVector<Value> {
+   *     return {builder.s(qubits[0])};
+   *   }
+   * );
+   * ```
+   * ```mlir
+   * %qubits_out = qco.inv (%q = %q0_in) {
+   *   %q_res = qco.s %q : !qco.qubit -> !qco.qubit
+   *   qco.yield %q_res
+   * } : {!qco.qubit} -> {!qco.qubit}
+   * ```
+   */
+  ValueRange inv(ValueRange qubits,
+                 llvm::function_ref<llvm::SmallVector<Value>(ValueRange)> body);
+
   //===--------------------------------------------------------------------===//
   // Deallocation
   //===--------------------------------------------------------------------===//

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

@@ -1074,7 +1074,7 @@ def CtrlOp : QCOOp<"ctrl", traits =
                 AttrSizedResultSegments,
                 SameOperandsAndResultType,
                 SameOperandsAndResultShape,
-                SingleBlock,
+                SingleBlockImplicitTerminator<"::mlir::qco::YieldOp">,
                 RecursiveMemoryEffects
             ]> {
     let summary = "Add control qubits to a unitary operation";
@@ -1142,4 +1142,71 @@ def CtrlOp : QCOOp<"ctrl", traits =
     let hasVerifier = 1;
 }
 
+def InvOp : QCOOp<"inv", traits =
+            [
+                UnitaryOpInterface,
+                SameOperandsAndResultType,
+                SameOperandsAndResultShape,
+                SingleBlockImplicitTerminator<"::mlir::qco::YieldOp">,
+                RecursiveMemoryEffects
+            ]> {
+    let summary = "Invert a unitary operation";
+    let description = [{
+        A modifier operation that inverts the unitary operation defined in its body
+        region. The operation takes a variadic number of qubits as inputs and
+        produces corresponding output qubits.
+
+        Example:
+        ```mlir
+        %q_out = qco.inv (%q = %q_in) {
+            %q_1 = qco.s %q : !qco.qubit -> !qco.qubit
+            qco.yield %q_1
+        } : {!qco.qubit} -> {!qco.qubit}
+        ```
+    }];
+
+    let arguments = (ins Arg<Variadic<QubitType>, "the qubits involved in the operation", [MemRead]>:$qubits_in);
+    let results = (outs Variadic<QubitType>:$qubits_out);
+    let regions = (region SizedRegion<1>:$region);
+    let assemblyFormat = [{
+        custom<TargetAliasing>($region, $qubits_in)
+        attr-dict `:`
+        `{` type($qubits_in) `}`
+        `->`
+        `{` type($qubits_out) `}`
+    }];
+
+    let extraClassDeclaration = [{
+        UnitaryOpInterface getBodyUnitary();
+        size_t getNumQubits();
+        size_t getNumTargets();
+        static size_t getNumControls();
+        Value getInputQubit(size_t i);
+        OperandRange getInputQubits();
+        Value getOutputQubit(size_t i);
+        ResultRange getOutputQubits();
+        Value getInputTarget(size_t i);
+        Value getOutputTarget(size_t i);
+        static Value getInputControl(size_t i);
+        static Value getOutputControl(size_t i);
+        Value getInputForOutput(Value output);
+        Value getOutputForInput(Value input);
+        size_t getNumParams();
+        Value getParameter(size_t i);
+        [[nodiscard]] static StringRef getBaseSymbol() { return "inv"; }
+        [[nodiscard]] std::optional<Eigen::MatrixXcd> getUnitaryMatrix();
+    }];
+
+    let builders = [
+        OpBuilder<(ins "ValueRange":$qubits), [{
+           build($_builder, $_state, qubits.getTypes(), qubits);
+        }]>,
+        OpBuilder<(ins "ValueRange":$qubits, "UnitaryOpInterface":$bodyUnitary)>,
+        OpBuilder<(ins "ValueRange":$qubits, "llvm::function_ref<llvm::SmallVector<Value>(ValueRange)>":$bodyBuilder)>
+    ];
+
+    let hasCanonicalizer = 1;
+    let hasVerifier = 1;
+}
+
 #endif // QCOOPS

mlir/lib/Conversion/QCOToQC/QCOToQC.cpp

@@ -812,6 +812,68 @@ struct ConvertQCOCtrlOp final : OpConversionPattern<qco::CtrlOp> {
   }
 };
 
+/**
+ * @brief Converts qco.inv to qc.inv
+ *
+ * @par Example:
+ * ```mlir
+ * %q0_out = qco.inv (%q0 = %q0_in) {
+ *   %q0_res = qco.s %q0 : !qco.qubit -> !qco.qubit
+ *   qco.yield %q0_res
+ * } : {!qco.qubit} -> {!qco.qubit}
+ * ```
+ * is converted to
+ * ```mlir
+ * qc.inv {
+ *   qc.s %q0 : !qc.qubit
+ * }
+ * ```
+ */
+struct ConvertQCOInvOp final : OpConversionPattern<qco::InvOp> {
+  using OpConversionPattern::OpConversionPattern;
+
+  LogicalResult
+  matchAndRewrite(qco::InvOp op, OpAdaptor adaptor,
+                  ConversionPatternRewriter& rewriter) const override {
+    // Create qc.inv operation
+    auto qcOp = qc::InvOp::create(rewriter, op.getLoc());
+
+    // Clone body region from QCO to QC
+    auto& dstRegion = qcOp.getRegion();
+    rewriter.cloneRegionBefore(op.getRegion(), dstRegion, dstRegion.end());
+
+    auto& entryBlock = dstRegion.front();
+    const auto numArgs = entryBlock.getNumArguments();
+    if (adaptor.getQubitsIn().size() != numArgs) {
+      return op.emitOpError() << "qco.inv: entry block args (" << numArgs
+                              << ") must match number of target operands ("
+                              << adaptor.getQubitsIn().size() << ")";
+    }
+
+    // Remove all block arguments in the cloned region
+    rewriter.modifyOpInPlace(qcOp, [&] {
+      // 1. Replace uses (Must be done BEFORE erasing)
+      // We iterate 0..N using indices since the block args are still stable
+      // here.
+      for (auto i = 0UL; i < numArgs; ++i) {
+        entryBlock.getArgument(i).replaceAllUsesWith(adaptor.getQubitsIn()[i]);
+      }
+
+      // 2. Erase all block arguments
+      // Now that they have no uses, we can safely wipe them.
+      // We use a bulk erase for efficiency (start index 0, count N).
+      if (numArgs > 0) {
+        entryBlock.eraseArguments(0, numArgs);
+      }
+    });
+
+    // Replace the output qubits with the same QC references
+    rewriter.replaceOp(op, adaptor.getOperands());
+
+    return success();
+  }
+};
+
 /**
  * @brief Converts qco.yield to qc.yield
  *
@@ -865,6 +927,7 @@ struct ConvertQCOYieldOp final : OpConversionPattern<qco::YieldOp> {
 struct QCOToQC final : impl::QCOToQCBase<QCOToQC> {
   using QCOToQCBase::QCOToQCBase;
 
+protected:
   void runOnOperation() override {
     MLIRContext* context = &getContext();
     auto* module = getOperation();
@@ -879,18 +942,18 @@ struct QCOToQC final : impl::QCOToQCBase<QCOToQC> {
 
     // Register operation conversion patterns
     // Note: No state tracking needed - OpAdaptors handle type conversion
-    patterns.add<ConvertQCOAllocOp, ConvertQCODeallocOp, ConvertQCOStaticOp,
-                 ConvertQCOMeasureOp, ConvertQCOResetOp, ConvertQCOGPhaseOp,
-                 ConvertQCOIdOp, ConvertQCOXOp, ConvertQCOYOp, ConvertQCOZOp,
-                 ConvertQCOHOp, ConvertQCOSOp, ConvertQCOSdgOp, ConvertQCOTOp,
-                 ConvertQCOTdgOp, ConvertQCOSXOp, ConvertQCOSXdgOp,
-                 ConvertQCORXOp, ConvertQCORYOp, ConvertQCORZOp, ConvertQCOPOp,
-                 ConvertQCOROp, ConvertQCOU2Op, ConvertQCOUOp, ConvertQCOSWAPOp,
-                 ConvertQCOiSWAPOp, ConvertQCODCXOp, ConvertQCOECROp,
-                 ConvertQCORXXOp, ConvertQCORYYOp, ConvertQCORZXOp,
-                 ConvertQCORZZOp, ConvertQCOXXPlusYYOp, ConvertQCOXXMinusYYOp,
-                 ConvertQCOBarrierOp, ConvertQCOCtrlOp, ConvertQCOYieldOp>(
-        typeConverter, context);
+    patterns
+        .add<ConvertQCOAllocOp, ConvertQCODeallocOp, ConvertQCOStaticOp,
+             ConvertQCOMeasureOp, ConvertQCOResetOp, ConvertQCOGPhaseOp,
+             ConvertQCOIdOp, ConvertQCOXOp, ConvertQCOYOp, ConvertQCOZOp,
+             ConvertQCOHOp, ConvertQCOSOp, ConvertQCOSdgOp, ConvertQCOTOp,
+             ConvertQCOTdgOp, ConvertQCOSXOp, ConvertQCOSXdgOp, ConvertQCORXOp,
+             ConvertQCORYOp, ConvertQCORZOp, ConvertQCOPOp, ConvertQCOROp,
+             ConvertQCOU2Op, ConvertQCOUOp, ConvertQCOSWAPOp, ConvertQCOiSWAPOp,
+             ConvertQCODCXOp, ConvertQCOECROp, ConvertQCORXXOp, ConvertQCORYYOp,
+             ConvertQCORZXOp, ConvertQCORZZOp, ConvertQCOXXPlusYYOp,
+             ConvertQCOXXMinusYYOp, ConvertQCOBarrierOp, ConvertQCOCtrlOp,
+             ConvertQCOInvOp, ConvertQCOYieldOp>(typeConverter, context);
 
     // Conversion of qco types in func.func signatures
     // Note: This currently has limitations with signature changes