✨ Add SCF Support to walkProgramGraph

[MatthiasReumann]

Changes

• ✨Add SCF op switch cases in Drivers.h and update unit tests

(Extracted from #1805 to decrease that PR size and ease reviewing)
(Depends on #1806)

Checklist

• The pull request only contains commits that are focused and relevant to this change.
• I have added appropriate tests that cover the new/changed functionality.
• 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).
• The changes follow the project's style guidelines and introduce no new warnings.
• The changes are fully tested and pass the CI checks.
• 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.
• 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.

[codecov]

Codecov Report

❌ Patch coverage is 94.87179% with 2 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
mlir/include/mlir/Dialect/QCO/Utils/Drivers.h	94.8%	2 Missing ⚠️

📢 Thoughts on this report? Let us know!

[MatthiasReumann]

@coderabbitai full review

[coderabbitai]

✅ Action performed

Full review finished.

[coderabbitai]

📝 Walkthrough

Summary by CodeRabbit

• New Features

  • Improved support for circuits with loops and conditional branches in graph traversal and wire iteration.

• Bug Fixes

  • Better handling of operations that span multiple wires, including clearer failure behavior when too few wires are provided.
  • More reliable traversal at the start and end of wire paths, including recursive and block-argument cases.

• Tests

  • Expanded test coverage for loop-based, conditional, and recursive wire traversal scenarios.

Walkthrough

WireIterator gains an isFinal_ state flag and isSinkLikeOperation/isSourceLikeOperation predicates, extending forward()/backward() traversal to cross scf::ForOp, scf::WhileOp, and qco::IfOp region boundaries via tied-init lookups. Drivers replaces UnitaryOpInterface-keyed ReleasedOps/PendingWiresMap with raw Operation* keys and introduces impl::getNumQubits. Tests are updated throughout to register scf::SCFDialect and exercise the new traversal paths.

Changes

QCO SCF region traversal and Drivers Operation* refactor

Layer / File(s)	Summary
WireIterator isFinal_ state and helper declarations mlir/include/mlir/Dialect/QCO/Utils/WireIterator.h	Adds mlir/IR/Value.h include, initializes isFinal_ to false in both constructors, declares private isSinkLikeOperation/isSourceLikeOperation static helpers, and adds bool isFinal_ member to the iterator state.
WireIterator sink/source predicates and forward/backward traversal mlir/lib/Dialect/QCO/Utils/WireIterator.cpp	Implements isSinkLikeOperation and isSourceLikeOperation; updates qubit() boundary detection; rewrites forward() with isFinal_ sentinel transition and scf::ForOp/scf::WhileOp/qco::IfOp TypeSwitch paths; rewrites backward() sentinel reactivation, block-argument early return, and tied-init stepping for loop and if constructs.
Drivers Operation* type aliases, getNumQubits, and IsReady mlir/include/mlir/Dialect/QCO/Utils/Drivers.h	Changes ReleasedOps to SmallVector<Operation*> and PendingWiresMap to DenseMap<Operation*, SmallVector<size_t>>; adds impl::getNumQubits(Operation*) via TypeSwitch; updates IsReady to use it; revises includes to add SCF and WalkResult headers.
walkProgramGraph traversal and release phase rewrite mlir/include/mlir/Dialect/QCO/Utils/Drivers.h	Rewrites active-operation loop to call impl::getNumQubits per op, advance wires for single-qubit ops, insert multi-qubit ops into pending by Operation* key with wire indices, fail on insufficient wires, and break at the first multi-qubit gate. Updates release phase to iterate Operation* entries and advance stored wire iterators.
Drivers tests: SCF dialect, TooFewWires, and scf.for circuit assertions mlir/unittests/Dialect/QCO/Utils/test_drivers.cpp	Adds SCF dialect registration; introduces ProgramGraphWalkTooFewWires failure test; refactors ProgramGraphWalk to build operations inside an scf.for loop; updates all forward/backward readyPerLayer assertions and adds a forward-walk starting from scf.for block arguments.
WireIterator tests: Traversal circuit and recursive block-argument test mlir/unittests/Dialect/QCO/Utils/test_wireiterator.cpp	Registers SCF dialect; replaces MixedUse test with Traversal using a circuit with scf.for and qco.if; updates forward/backward assertions; adds a recursive block-argument test exercising iterator behavior over loop-carried values including scf.yield and sentinel handling.
CHANGELOG entry CHANGELOG.md	Adds [#1808] to the Added entry for initial QCO/QCO MLIR dialect infrastructure and defines its reference link.

Sequence Diagram(s)

sequenceDiagram
  rect rgba(100, 149, 237, 0.5)
    Note over Caller,WireIterator: Forward traversal through scf.for / qco.if
  end
  participant Caller
  participant WireIterator
  participant TypeSwitch

  Caller->>WireIterator: ++it
  WireIterator->>WireIterator: isFinal_ set? → transition to sentinel
  WireIterator->>WireIterator: isSinkLikeOperation(op_)? → set isFinal_
  WireIterator->>WireIterator: isSourceLikeOperation(op_)? → early exit
  WireIterator->>TypeSwitch: dispatch current op_
  TypeSwitch-->>WireIterator: scf::ForOp/WhileOp → tied loop result value
  TypeSwitch-->>WireIterator: qco::IfOp → result at qubit index
  TypeSwitch-->>WireIterator: default gate op → next SSA user
  WireIterator-->>Caller: updated qubit_ / op_

  rect rgba(255, 140, 0, 0.5)
    Note over Caller,WireIterator: Backward traversal through qco.if / scf.for
  end
  Caller->>WireIterator: --it
  WireIterator->>WireIterator: isSentinel_? → isFinal_ = true, reactivate
  WireIterator->>WireIterator: op_ == nullptr? → block arg, early return
  WireIterator->>WireIterator: isSinkLikeOperation(op_)? → stop at boundary
  WireIterator->>TypeSwitch: dispatch current op_
  TypeSwitch-->>WireIterator: scf::ForOp/WhileOp → getTiedLoopInit operand
  TypeSwitch-->>WireIterator: qco::IfOp → find result index → input qubit
  TypeSwitch-->>WireIterator: default → defining op qubit
  WireIterator->>WireIterator: isFinal_ = false
  WireIterator-->>Caller: updated qubit_ / op_

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• munich-quantum-toolkit/core#1510: This PR's isFinal_, isSinkLikeOperation/isSourceLikeOperation additions and forward/backward traversal rewrites directly extend the WireIterator implementation introduced in that PR.
• munich-quantum-toolkit/core#1664: Both PRs modify walkProgramGraph-related types and traversal logic in Drivers.h (ReleasedOps/PendingWiresMap keying and the walk algorithm), so this PR builds directly on that driver.
• munich-quantum-toolkit/core#1506: The qco::IfOp qubit arity and tied-init handling added here in WireIterator and Drivers directly builds on the qco.if operation introduced in that PR.

Suggested labels

feature

Suggested reviewers

• burgholzer

🐇 Hoppity hop through loops and ifs,
The wires now know which region it is!
isFinal_ marks the end of the line,
scf.for and qco.if fall into line.
Forward, backward — the iterator's right,
Every qubit traversed with delight! 🌟

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 23.53% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise and accurately summarizes the main change: adding SCF support to walkProgramGraph.
Description check	✅ Passed	The description covers the change summary, dependency, and checklist, though it does not follow the template headings exactly.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch enh/scf-support-driver

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@mlir/unittests/Dialect/QCO/Utils/test_wireiterator.cpp`:
- Line 122: The WireIterator tests are dereferencing the first user directly and
assuming `getUsers().begin()` is stable, which is fragile if more uses appear.
In `test_wireiterator.cpp`, update the affected assertions around
`it.operation()`, `q06.getUsers()`, and the other similar sites to first check
`hasOneUse()` and then capture the user operation into a local variable before
comparing against it. Keep the assertions focused on the expected single-use
case rather than relying on iterator ordering.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: dabf446b-0def-4596-ad4f-cf01374adc75

📥 Commits

Reviewing files that changed from the base of the PR and between 4065349 and 1e9228a.

📒 Files selected for processing (6)

• CHANGELOG.md
• mlir/include/mlir/Dialect/QCO/Utils/Drivers.h
• mlir/include/mlir/Dialect/QCO/Utils/WireIterator.h
• mlir/lib/Dialect/QCO/Utils/WireIterator.cpp
• mlir/unittests/Dialect/QCO/Utils/test_drivers.cpp
• mlir/unittests/Dialect/QCO/Utils/test_wireiterator.cpp

[burgholzer]

Likely just me being too dense, but there are two things that do not quite make sense to me here.

[burgholzer]

This looks much more reasonable now 👍🏻