Add WireIterator for the QCO Dialect

CHANGELOG.md

@@ -12,8 +12,8 @@ This project adheres to [Semantic Versioning], with the exception that minor rel
 ### Added
 
 - ✨ 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], [#1513], [#1521])
-  ([**@burgholzer**], [**@denialhaag**], [**@taminob**], [**@DRovara**], [**@li-mingbao**], [**@Ectras**])
+  ([#1264], [#1330], [#1402], [#1428], [#1430], [#1436], [#1443], [#1446], [#1464], [#1465], [#1470], [#1471], [#1472], [#1474], [#1475], [#1510], [#1513], [#1521])
+  ([**@burgholzer**], [**@denialhaag**], [**@taminob**], [**@DRovara**], [**@li-mingbao**], [**@Ectras**], [**@MatthiasReumann**])
 
 ### Changed
 
@@ -329,6 +329,7 @@ _📚 Refer to the [GitHub Release Notes](https://github.com/munich-quantum-tool
 
 [#1521]: https://github.com/munich-quantum-toolkit/core/pull/1521
 [#1513]: https://github.com/munich-quantum-toolkit/core/pull/1513
+[#1510]: https://github.com/munich-quantum-toolkit/core/pull/1510
 [#1481]: https://github.com/munich-quantum-toolkit/core/pull/1481
 [#1475]: https://github.com/munich-quantum-toolkit/core/pull/1475
 [#1474]: https://github.com/munich-quantum-toolkit/core/pull/1474

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

@@ -0,0 +1,85 @@
+/*
+ * 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 <iterator>
+#include <mlir/IR/Operation.h>
+
+namespace mlir::qco {
+
+/**
+ * @brief A bidirectional_iterator traversing the def-use chain of a qubit wire.
+ *
+ * The iterator follows the flow of a qubit through a sequence of quantum
+ * operations while respecting the semantics of the respective operation.
+ **/
+class [[nodiscard]] WireIterator {
+public:
+  using iterator_category = std::bidirectional_iterator_tag;
+  using difference_type = std::ptrdiff_t;
+  using value_type = mlir::Operation*;
+
+  WireIterator() : op_(nullptr), qubit_(nullptr), isSentinel_(false) {}
+  explicit WireIterator(mlir::Value qubit)
+      : op_(qubit.getDefiningOp()), qubit_(qubit), isSentinel_(false) {}
+
+  /// @returns the operation the iterator points to.
+  [[nodiscard]] mlir::Operation* operation() const { return op_; }
+
+  /// @returns the operation the iterator points to.
+  [[nodiscard]] mlir::Operation* operator*() const { return operation(); }
+
+  /// @returns the qubit the iterator points to.
+  [[nodiscard]] mlir::Value qubit() const;
+
+  WireIterator& operator++() {
+    forward();
+    return *this;
+  }
+
+  WireIterator operator++(int) {
+    auto tmp = *this;
+    operator++();
+    return tmp;
+  }
+
+  WireIterator& operator--() {
+    backward();
+    return *this;
+  }
+
+  WireIterator operator--(int) {
+    auto tmp = *this;
+    operator--();
+    return tmp;
+  }
+
+  bool operator==(const WireIterator& other) const {
+    return other.qubit_ == qubit_ && other.op_ == op_ &&
+           other.isSentinel_ == isSentinel_;
+  }
+
+  bool operator==([[maybe_unused]] std::default_sentinel_t s) const {
+    return isSentinel_;
+  }
+
+private:
+  /// @brief Move to the next operation on the qubit wire.
+  void forward();
+
+  /// @brief Move to the previous operation on the qubit wire.
+  void backward();
+
+  mlir::Operation* op_;
+  mlir::Value qubit_;
+  bool isSentinel_;
+};
+} // namespace mlir::qco

mlir/lib/Dialect/QCO/CMakeLists.txt

@@ -8,3 +8,4 @@
 
 add_subdirectory(Builder)
 add_subdirectory(IR)
+add_subdirectory(Utils)

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

@@ -0,0 +1,44 @@
+# 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
+
+file(GLOB_RECURSE UTILS_CPP "${CMAKE_CURRENT_SOURCE_DIR}/*.cpp")
+
+add_mlir_dialect_library(
+  MLIRQCOUtils
+  ${UTILS_CPP}
+  ADDITIONAL_HEADER_DIRS
+  ${PROJECT_SOURCE_DIR}/mlir/include/mlir/Dialect/QCO
+  DEPENDS
+  MLIRQCOOpsIncGen
+  MLIRQCOInterfacesIncGen
+  LINK_LIBS
+  PUBLIC
+  MLIRQCODialect
+  DISABLE_INSTALL)
+
+mqt_mlir_target_use_project_options(MLIRQCOUtils)
+
+# collect header files
+file(GLOB_RECURSE UTILS_HEADERS_SOURCE "${MQT_MLIR_SOURCE_INCLUDE_DIR}/mlir/Dialect/QCO/Utils/*.h")
+file(GLOB_RECURSE UTILS_HEADERS_BUILD "${MQT_MLIR_BUILD_INCLUDE_DIR}/mlir/Dialect/QCO/Utils/*.inc")
+
+# add public headers using file sets
+target_sources(
+  MLIRQCOUtils
+  PUBLIC FILE_SET
+         HEADERS
+         BASE_DIRS
+         ${MQT_MLIR_SOURCE_INCLUDE_DIR}
+         FILES
+         ${UTILS_HEADERS_SOURCE}
+         FILE_SET
+         HEADERS
+         BASE_DIRS
+         ${MQT_MLIR_BUILD_INCLUDE_DIR}
+         FILES
+         ${UTILS_HEADERS_BUILD})

mlir/lib/Dialect/QCO/Utils/WireIterator.cpp

@@ -0,0 +1,105 @@
+/*
+ * 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
+ */
+
+#include "mlir/Dialect/QCO/Utils/WireIterator.h"
+
+#include "mlir/Dialect/QCO/IR/QCOInterfaces.h"
+#include "mlir/Dialect/QCO/IR/QCOOps.h"
+
+#include <cassert>
+#include <iterator>
+#include <llvm/ADT/TypeSwitch.h>
+#include <llvm/Support/ErrorHandling.h>
+#include <mlir/IR/Operation.h>
+#include <mlir/IR/Value.h>
+#include <mlir/Support/LLVM.h>
+
+namespace mlir::qco {
+mlir::Value WireIterator::qubit() const {
+  // A deallocation doesn't have an OpResult.
+  if (op_ != nullptr && mlir::isa<DeallocOp>(op_)) {
+    return nullptr;
+  }
+  return qubit_;
+}
+
+void WireIterator::forward() {
+  // If the iterator is a sentinel already, there is nothing to do.
+  if (isSentinel_) {
+    return;
+  }
+
+  // Find the user-operation of the qubit SSA value.
+  assert(qubit_.getNumUses() == 1 && "expected linear typing");
+  op_ = *(qubit_.getUsers().begin());
+
+  // A deallocation op defines the end of the qubit wire (dynamic and static).
+  if (mlir::isa<DeallocOp>(op_)) {
+    isSentinel_ = true;
+    return;
+  }
+
+  if (!(mlir::isa<AllocOp, StaticOp>(op_))) {
+    // Find the output from the input qubit SSA value.
+    mlir::TypeSwitch<mlir::Operation*>(op_)
+        .Case<UnitaryOpInterface>([&](UnitaryOpInterface op) {
+          qubit_ = op.getOutputForInput(qubit_);
+        })
+        .Case<MeasureOp>([&](MeasureOp op) { qubit_ = op.getQubitOut(); })
+        .Case<ResetOp>([&](ResetOp op) { qubit_ = op.getQubitOut(); })
+        .Default([&](mlir::Operation* op) {
+          report_fatal_error("unknown op in def-use chain: " +
+                             op->getName().getStringRef());
+        });
+  }
+}
+
+void WireIterator::backward() {
+  // If the iterator is a sentinel, reactivate the iterator.
+  if (isSentinel_) {
+    isSentinel_ = false;
+    return;
+  }
+
+  // For deallocations, qubit_ is an OpOperand. Hence, only get the def-op.
+  if (mlir::isa<DeallocOp>(op_)) {
+    op_ = qubit_.getDefiningOp();
+    return;
+  }
+
+  // Allocations or static definitions define the start of the qubit wire.
+  // Consequently, stop and early exit.
+  if (mlir::isa<AllocOp, StaticOp>(op_)) {
+    return;
+  }
+
+  // Find the input from the output qubit SSA value.
+  mlir::TypeSwitch<mlir::Operation*>(op_)
+      .Case<UnitaryOpInterface>(
+          [&](UnitaryOpInterface op) { qubit_ = op.getInputForOutput(qubit_); })
+      .Case<MeasureOp>([&](MeasureOp op) { qubit_ = op.getQubitIn(); })
+      .Case<ResetOp>([&](ResetOp op) { qubit_ = op.getQubitIn(); })
+      .Default([&](mlir::Operation* op) {
+        report_fatal_error("unknown op in def-use chain: " +
+                           op->getName().getStringRef());
+      });
+
+  // Get the operation that produces the qubit value.
+  // If the current qubit SSA value is a BlockArgument (no defining op), stop.
+  op_ = qubit_.getDefiningOp();
+  if (op_ == nullptr) {
+    return;
+  }
+}
+
+static_assert(std::bidirectional_iterator<WireIterator>);
+static_assert(std::sentinel_for<std::default_sentinel_t, WireIterator>,
+              "std::default_sentinel_t must be a sentinel for WireIterator.");
+} // namespace mlir::qco

mlir/unittests/Dialect/QCO/CMakeLists.txt

@@ -7,3 +7,4 @@
 # Licensed under the MIT License
 
 add_subdirectory(IR)
+add_subdirectory(Utils)

mlir/unittests/Dialect/QCO/Utils/CMakeLists.txt

@@ -0,0 +1,15 @@
+# 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
+
+set(qco_utils_target mqt-core-mlir-unittest-qco-utils)
+add_executable(${qco_utils_target} test_wireiterator.cpp)
+target_link_libraries(${qco_utils_target} PRIVATE GTest::gtest_main MLIRQCODialect MLIRQCOUtils
+                                                  MLIRQCOProgramBuilder)
+mqt_mlir_configure_unittest_target(${qco_utils_target})
+
+gtest_discover_tests(${qco_utils_target} PROPERTIES LABELS mqt-mlir-unittests DISCOVERY_TIMEOUT 60)