✨ Improve Static Qubit Handling (#1569)

## Description

Based on #1585.

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

- [ ] 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.
- [ ] 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>
Co-authored-by: Lukas Burgholzer <burgholzer@me.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: 3 people

CHANGELOG.md

@@ -15,7 +15,7 @@ This project adheres to [Semantic Versioning], with the exception that minor rel
 - ✨ Add conversions between Jeff and QCO ([#1479], [#1548], [#1565]) ([**@denialhaag**])
 - ✨ Add a `place-and-route` pass for mapping circuits to architectures with restricted topologies ([#1537], [#1547], [#1568], [#1581], [#1583], [#1588]) ([**@MatthiasReumann**])
 - ✨ 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], [#1506], [#1510], [#1513], [#1521], [#1542], [#1548], [#1550], [#1554], [#1570], [#1572], [#1573])
+  ([#1264], [#1330], [#1402], [#1428], [#1430], [#1436], [#1443], [#1446], [#1464], [#1465], [#1470], [#1471], [#1472], [#1474], [#1475], [#1506], [#1510], [#1513], [#1521], [#1542], [#1548], [#1550], [#1554], [#1569], [#1570], [#1572], [#1573])
   ([**@burgholzer**], [**@denialhaag**], [**@taminob**], [**@DRovara**], [**@li-mingbao**], [**@Ectras**], [**@MatthiasReumann**], [**@simon1hofmann**])
 
 ### Changed
@@ -344,6 +344,7 @@ _📚 Refer to the [GitHub Release Notes](https://github.com/munich-quantum-tool
 [#1572]: https://github.com/munich-quantum-toolkit/core/pull/1572
 [#1571]: https://github.com/munich-quantum-toolkit/core/pull/1571
 [#1570]: https://github.com/munich-quantum-toolkit/core/pull/1570
+[#1569]: https://github.com/munich-quantum-toolkit/core/pull/1569
 [#1568]: https://github.com/munich-quantum-toolkit/core/pull/1568
 [#1565]: https://github.com/munich-quantum-toolkit/core/pull/1565
 [#1564]: https://github.com/munich-quantum-toolkit/core/pull/1564

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

@@ -110,7 +110,7 @@ class QCProgramBuilder final : public ImplicitLocOpBuilder {
 
   /**
    * @brief Get a static qubit by index
-   * @param index The qubit index (must be non-negative)
+   * @param index The qubit index
    * @return A qubit reference
    *
    * @par Example:
@@ -121,7 +121,7 @@ class QCProgramBuilder final : public ImplicitLocOpBuilder {
    * %q0 = qc.static 0 : !qc.qubit
    * ```
    */
-  Value staticQubit(int64_t index);
+  Value staticQubit(uint64_t index);
 
   /**
    * @brief Allocate a qubit register

mlir/include/mlir/Dialect/QC/IR/QCDialect.h

@@ -52,6 +52,7 @@ template <size_t T, size_t P> class TargetAndParameterArityTrait {
     static size_t getNumQubits() { return T; }
     static size_t getNumTargets() { return T; }
     static size_t getNumControls() { return 0; }
+    static ValueRange getControls() { return {}; }
 
     Value getQubit(size_t i) {
       if constexpr (T == 0) {
@@ -71,6 +72,9 @@ template <size_t T, size_t P> class TargetAndParameterArityTrait {
       }
       return this->getOperation()->getOperand(i);
     }
+    ValueRange getTargets() {
+      return this->getOperation()->getOperands().slice(0, T);
+    }
 
     static Value getControl([[maybe_unused]] size_t i) {
       llvm::reportFatalUsageError("Operation does not have controls");
@@ -84,6 +88,10 @@ template <size_t T, size_t P> class TargetAndParameterArityTrait {
       }
       return this->getOperation()->getOperand(T + i);
     }
+
+    ValueRange getParameters() {
+      return this->getOperation()->getOperands().slice(T, P);
+    }
   };
 };
 

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

@@ -44,12 +44,18 @@ def UnitaryOpInterface : OpInterface<"UnitaryOpInterface"> {
                       (ins "size_t":$i)>,
       InterfaceMethod<"Returns the i-th control qubit.", "Value", "getControl",
                       (ins "size_t":$i)>,
+      InterfaceMethod<"Returns a range of all target qubits.", "ValueRange",
+                      "getTargets", (ins)>,
+      InterfaceMethod<"Returns a range of all control qubits.", "ValueRange",
+                      "getControls", (ins)>,
 
       // Parameter handling
       InterfaceMethod<"Returns the number of parameters.", "size_t",
                       "getNumParams", (ins)>,
       InterfaceMethod<"Returns the i-th parameter.", "Value", "getParameter",
                       (ins "size_t":$i)>,
+      InterfaceMethod<"Returns a range of all parameters.", "ValueRange",
+                      "getParameters", (ins)>,
 
       // Convenience methods
       InterfaceMethod<"Returns true if the operation has any control qubits, "

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

@@ -110,6 +110,10 @@ def StaticOp : QCOp<"static", [Pure]> {
   let arguments = (ins ConfinedAttr<I64Attr, [IntNonNegative]>:$index);
   let results = (outs QubitType:$qubit);
   let assemblyFormat = "$index attr-dict `:` type($qubit)";
+
+  let builders = [OpBuilder<(ins "uint64_t":$index), [{
+          build($_builder, $_state, QubitType::get($_builder.getContext()), index);
+      }]>];
 }
 
 //===----------------------------------------------------------------------===//
@@ -910,11 +914,14 @@ def BarrierOp : QCOp<"barrier", traits = [UnitaryOpInterface]> {
         size_t getNumQubits() { return getNumTargets(); }
         size_t getNumTargets() { return getQubits().size(); }
         static size_t getNumControls() { return 0; }
+        static ValueRange getControls() { return {}; }
         Value getQubit(size_t i) { return getTarget(i); }
         Value getTarget(size_t i);
+        ValueRange getTargets() { return getQubits(); }
         static Value getControl(size_t i) { llvm::reportFatalUsageError("BarrierOp cannot be controlled"); }
         static size_t getNumParams() { return 0; }
         static Value getParameter(size_t i) { llvm::reportFatalUsageError("BarrierOp does not have parameters"); }
+        static ValueRange getParameters() { return {}; }
         static StringRef getBaseSymbol() { return "barrier"; }
     }];
 }
@@ -969,9 +976,11 @@ def CtrlOp
         size_t getNumControls() { return getControls().size(); }
         Value getQubit(size_t i);
         Value getTarget(size_t i) { return getBodyUnitary().getTarget(i); }
+        ValueRange getTargets() { return getBodyUnitary().getTargets(); }
         Value getControl(size_t i);
         size_t getNumParams() { return getBodyUnitary().getNumParams(); }
         Value getParameter(size_t i) { return getBodyUnitary().getParameter(i); }
+        ValueRange getParameters() { return getBodyUnitary().getParameters(); }
         static StringRef getBaseSymbol() { return "ctrl"; }
     }];
 
@@ -1005,13 +1014,16 @@ def InvOp : QCOp<"inv",
   let extraClassDeclaration = [{
         [[nodiscard]] UnitaryOpInterface getBodyUnitary();
         size_t getNumQubits() { return getBodyUnitary().getNumQubits(); }
-        size_t getNumTargets() { return getNumQubits(); }
-        static size_t getNumControls() { return 0; }
+        size_t getNumTargets() { return getBodyUnitary().getNumTargets(); }
+        size_t getNumControls() { return getBodyUnitary().getNumControls(); }
         Value getQubit(size_t i) { return getBodyUnitary().getQubit(i); }
-        Value getTarget(size_t i) { return getQubit(i); }
-        static Value getControl(size_t i) { llvm::reportFatalUsageError("Operation does not have controls"); }
+        Value getTarget(size_t i) { return getBodyUnitary().getTarget(i); }
+        ValueRange getTargets() { return getBodyUnitary().getTargets(); }
+        Value getControl(size_t i) { return getBodyUnitary().getControl(i); }
+        ValueRange getControls() { return getBodyUnitary().getControls(); }
         size_t getNumParams() { return getBodyUnitary().getNumParams(); }
         Value getParameter(size_t i) { return getBodyUnitary().getParameter(i); }
+        ValueRange getParameters() { return getBodyUnitary().getParameters(); }
         static StringRef getBaseSymbol() { return "inv"; }
     }];
 

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

@@ -118,7 +118,7 @@ class QCOProgramBuilder final : public ImplicitLocOpBuilder {
 
   /**
    * @brief Get a static qubit by index
-   * @param index The qubit index (must be non-negative)
+   * @param index The qubit index
    * @return A tracked, valid qubit SSA value
    *
    * @par Example:
@@ -129,7 +129,7 @@ class QCOProgramBuilder final : public ImplicitLocOpBuilder {
    * %q0 = qco.static 0 : !qco.qubit
    * ```
    */
-  Value staticQubit(int64_t index);
+  Value staticQubit(uint64_t index);
 
   /**
    * @brief Allocate a qubit register
@@ -1228,24 +1228,24 @@ class QCOProgramBuilder final : public ImplicitLocOpBuilder {
   //===--------------------------------------------------------------------===//
 
   /**
-   * @brief Explicitly deallocate a qubit
+   * @brief Consume a qubit value (end of lifetime)
    *
    * @details
    * Validates and removes the qubit from tracking. Optional; `finalize()`
-   * automatically deallocates all remaining qubits.
+   * automatically sinks all remaining qubits.
    *
-   * @param qubit Qubit to deallocate (must be valid/unconsumed)
+   * @param qubit Qubit to sink (must be valid/unconsumed)
    * @return Reference to this builder for method chaining
    *
    * @par Example:
    * ```c++
-   * builder.dealloc(q);
+   * builder.sink(q);
    * ```
    * ```mlir
-   * qco.dealloc %q : !qco.qubit
+   * qco.sink %q : !qco.qubit
    * ```
    */
-  QCOProgramBuilder& dealloc(Value qubit);
+  QCOProgramBuilder& sink(Value qubit);
 
   //===--------------------------------------------------------------------===//
   // SCF operations

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

@@ -77,14 +77,20 @@ def AllocOp : QCOOp<"alloc", [MemoryEffects<[MemAlloc]>]> {
   let hasVerifier = 1;
 }
 
-def DeallocOp : QCOOp<"dealloc", [MemoryEffects<[MemFree]>]> {
-  let summary = "Deallocate a qubit";
+def SinkOp : QCOOp<"sink", [MemoryEffects<[MemFree]>]> {
+  let summary = "Consume a qubit value (end of lifetime)";
   let description = [{
-        Deallocates a qubit, releasing its resources.
+        Consumes a qubit SSA value and marks the end of its lifetime.
+
+        This operation is the canonical "sink" for QCO's linear/value semantics:
+        every qubit value must be consumed exactly once on all paths.
+
+        When converting back to QC (reference semantics), sinks corresponding to
+        static qubits may be erased.
 
         Example:
         ```mlir
-        qco.dealloc %q : !qco.qubit
+        qco.sink %q : !qco.qubit
         ```
     }];
 

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

@@ -104,8 +104,8 @@ template <typename Fn> void walkUnit(Region& region, Fn&& fn) {
         .template Case<MeasureOp>([&](MeasureOp op) {
           qubits.remap(op.getQubitIn(), op.getQubitOut());
         })
-        .template Case<DeallocOp>(
-            [&](DeallocOp op) { qubits.remove(op.getQubit()); });
+        .template Case<SinkOp>(
+            [&](SinkOp op) { qubits.remove(op.getQubit()); });
   }
 }
 } // namespace mlir::qco

mlir/lib/Conversion/JeffToQCO/JeffToQCO.cpp

@@ -406,7 +406,7 @@ struct ConvertJeffQubitAllocOpToQCO final
 };
 
 /**
- * @brief Converts jeff.qubit_free to qco.reset + qco.dealloc
+ * @brief Converts jeff.qubit_free to qco.reset + qco.sink
  *
  * @par Example:
  * ```mlir
@@ -415,7 +415,7 @@ struct ConvertJeffQubitAllocOpToQCO final
  * is converted to
  * ```mlir
  * %q_out = qco.reset %q_in : !qco.qubit
- * qco.dealloc %q_out : !qco.qubit
+ * qco.sink %q_out : !qco.qubit
  * ```
  */
 struct ConvertJeffQubitFreeOpToQCO final
@@ -427,21 +427,21 @@ struct ConvertJeffQubitFreeOpToQCO final
                   ConversionPatternRewriter& rewriter) const override {
     auto resetOp =
         qco::ResetOp::create(rewriter, op.getLoc(), adaptor.getInQubit());
-    rewriter.replaceOpWithNewOp<qco::DeallocOp>(op, resetOp.getQubitOut());
+    rewriter.replaceOpWithNewOp<qco::SinkOp>(op, resetOp.getQubitOut());
     return success();
   }
 };
 
 /**
- * @brief Converts jeff.qubit_free_zero to qco.dealloc
+ * @brief Converts jeff.qubit_free_zero to qco.sink
  *
  * @par Example:
  * ```mlir
  * jeff.qubit_free_zero %q : !jeff.qubit
  * ```
  * is converted to
  * ```mlir
- * qco.dealloc %q : !qco.qubit
+ * qco.sink %q : !qco.qubit
  * ```
  */
 struct ConvertJeffQubitFreeZeroOpToQCO final
@@ -451,13 +451,13 @@ struct ConvertJeffQubitFreeZeroOpToQCO final
   LogicalResult
   matchAndRewrite(jeff::QubitFreeZeroOp op, OpAdaptor adaptor,
                   ConversionPatternRewriter& rewriter) const override {
-    rewriter.replaceOpWithNewOp<qco::DeallocOp>(op, adaptor.getInQubit());
+    rewriter.replaceOpWithNewOp<qco::SinkOp>(op, adaptor.getInQubit());
     return success();
   }
 };
 
 /**
- * @brief Converts jeff.qubit_measure to qco.measure + qco.dealloc
+ * @brief Converts jeff.qubit_measure to qco.measure + qco.sink
  *
  * @par Example:
  * ```mlir
@@ -466,7 +466,7 @@ struct ConvertJeffQubitFreeZeroOpToQCO final
  * is converted to
  * ```mlir
  * %q_out, %result = qco.measure %q_in : !qco.qubit
- * qco.dealloc %q_out : !qco.qubit
+ * qco.sink %q_out : !qco.qubit
  * ```
  */
 struct ConvertJeffQubitMeasureOpToQCO final
@@ -479,7 +479,7 @@ struct ConvertJeffQubitMeasureOpToQCO final
     auto loc = op.getLoc();
     auto measureOp =
         qco::MeasureOp::create(rewriter, loc, adaptor.getInQubit());
-    qco::DeallocOp::create(rewriter, loc, measureOp.getQubitOut());
+    qco::SinkOp::create(rewriter, loc, measureOp.getQubitOut());
     rewriter.replaceOp(op, measureOp.getResult());
     return success();
   }

mlir/lib/Conversion/QCOToJeff/QCOToJeff.cpp

@@ -269,23 +269,22 @@ struct ConvertQCOAllocOpToJeff final
 };
 
 /**
- * @brief Converts qco.dealloc to jeff.qubit_free_zero
+ * @brief Converts qco.sink to jeff.qubit_free_zero
  *
  * @par Example:
  * ```mlir
- * qco.dealloc %q : !qco.qubit
+ * qco.sink %q : !qco.qubit
  * ```
  * is converted to
  * ```mlir
  * jeff.qubit_free_zero %q : !jeff.qubit
  * ```
  */
-struct ConvertQCODeallocOpToJeff final
-    : StatefulOpConversionPattern<qco::DeallocOp> {
+struct ConvertQCOSinkOpToJeff final : StatefulOpConversionPattern<qco::SinkOp> {
   using StatefulOpConversionPattern::StatefulOpConversionPattern;
 
   LogicalResult
-  matchAndRewrite(qco::DeallocOp op, OpAdaptor adaptor,
+  matchAndRewrite(qco::SinkOp op, OpAdaptor adaptor,
                   ConversionPatternRewriter& rewriter) const override {
     rewriter.replaceOpWithNewOp<jeff::QubitFreeZeroOp>(op, adaptor.getQubit());
     return success();
@@ -1364,7 +1363,7 @@ struct QCOToJeff final : impl::QCOToJeffBase<QCOToJeff> {
     // Register operation conversion patterns
     jeff::populateNativeToJeffConversionPatterns(patterns);
     patterns.add<
-        ConvertQCOAllocOpToJeff, ConvertQCODeallocOpToJeff,
+        ConvertQCOAllocOpToJeff, ConvertQCOSinkOpToJeff,
         ConvertQCOMeasureOpToJeff, ConvertQCOResetOpToJeff,
         ConvertQCOGPhaseOpToJeff,
         ConvertQCOOneTargetZeroParameterToJeff<qco::IdOp, jeff::IOp, false>,