✨ Add fuse-two-qubit-unitary-runs pass

[simon1hofmann]

Description

Add a fuse-two-qubit-unitary-runs MLIR pass that fuses compile-time two-qubit unitary windows and resynthesizes them to a native gateset via Weyl/KAK decomposition.

AI Assistance

Used Composer 2.5 via Cursor for parts of this change. I reviewed the full
diff and take responsibility for everything in this PR.

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.53782% with 13 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...sforms/NativeSynthesis/FuseTwoQubitUnitaryRuns.cpp	93.4%	13 Missing ⚠️

📢 Thoughts on this report? Let us know!

[simon1hofmann]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 210dee2b-5ed1-4421-879a-e7a8cdff085f

📥 Commits

Reviewing files that changed from the base of the PR and between 0b7922d and c4e0969.

📒 Files selected for processing (3)

• mlir/include/mlir/Dialect/QCO/Transforms/Passes.td
• mlir/lib/Dialect/QCO/Transforms/NativeSynthesis/FuseTwoQubitUnitaryRuns.cpp
• mlir/unittests/Dialect/QCO/Transforms/NativeSynthesis/test_fuse_two_qubit_unitary_runs.cpp

---

📝 Walkthrough

Summary by CodeRabbit

• New Features
  • Added fuse-two-qubit-unitary-runs transpilation pass to fuse two-qubit unitary runs and lower to a user-selected native gate menu.
  • Added configurable native-gates option (empty/whitespace-only input results in a no-op).
• Bug Fixes
  • Improved handling of controlled bodies, barriers, and global-phase operations during fusion/lowering.
  • Added stronger validation to ensure no unsupported ≤2-qubit unitary shells remain after the pass.
• Tests
  • Added comprehensive unit tests for correctness, native-gate compliance, edge cases, and deterministic behavior.

Walkthrough

Adds a new MLIR QCO pass that fuses two-qubit unitary runs, resynthesizes them to a native gateset, and validates the result. Also adds a NativeGateset::allowsOp API, refactors single-qubit fusion pattern registration, wires tests, and updates the changelog.

Changes

Two-Qubit Unitary Fusion Pass

Layer / File(s)	Summary
NativeGateset allowsOp API mlir/include/.../NativeGateset.h, mlir/lib/.../NativeGateset.cpp, mlir/unittests/.../test_weyl_decomposition.cpp	Adds allowsOp(Operation*) to NativeGateset, implements gate and entangler classification, and updates tests to call the new member API.
Single-qubit fusion pattern refactor mlir/include/.../Euler.h, mlir/lib/.../FuseSingleQubitUnitaryRuns.cpp	Adds populateFuseSingleQubitUnitaryRunsPatterns, threads skipControlledBodies, and routes the existing pass through the helper.
Pass definition and options mlir/include/.../Passes.td	Registers FuseTwoQubitUnitaryRuns with the native-gates option and documented pass behavior.
Run detection, composition, and rewrite patterns mlir/lib/.../FuseTwoQubitUnitaryRuns.cpp	Implements two-qubit run scanning, Weyl resynthesis, off-gateset lowering, orchestration helpers, and final convergence checks.
Unit tests and build wiring mlir/unittests/.../NativeSynthesis/*, mlir/unittests/.../CMakeLists.txt	Adds a new unit test target and pass tests for native compliance, unitary equivalence, window behavior, and edge cases.
Changelog entry CHANGELOG.md	Adds the new pass entry and PR reference.

Estimated code review effort: 4 (Complex) | ~60 minutes

Possibly related PRs

• munich-quantum-toolkit/core#1672: Introduces the single-qubit fusion helper refactor that this PR extends with skipControlledBodies.
• munich-quantum-toolkit/core#1803: Adds the Weyl/basis decomposition machinery used by the new two-qubit resynthesis pass.

Suggested labels: feature

Suggested reviewers: burgholzer

Poem

I hopped through qubits, two by two,
Then Weyl-made runs in native hue.
🐰✨
The gates grew neat, the paths aligned,
And unitary tunes were gently signed.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise, specific, and accurately describes the main change: adding the fuse-two-qubit-unitary-runs pass.
Description check	✅ Passed	The description covers the change summary, motivation, AI disclosure, and checklist items required by the template.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.

✨ Finishing Touches

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch feat/fuse-two-qubit-unitary-runs

---

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: 4

🤖 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/include/mlir/Dialect/QCO/Transforms/Passes.td`:
- Around line 88-89: The gate-set docs in Passes.td are advertising the
unsupported `p` alias even though `parseGateToken` only recognizes `rz`, so
update the `QCO` pass descriptions to match the parser by either adding `p`
handling in `parseGateToken` or removing `p` from the documented token list and
any related examples/comments. Make sure the wording around the gate tokens in
the pass definitions stays consistent with the actual accepted syntax.

In `@mlir/lib/Dialect/QCO/Transforms/NativeSynthesis/FuseTwoQubitUnitaryRuns.cpp`:
- Around line 248-250: The comparison in the `FuseTwoQubitUnitaryRuns` scan is
unsafe because `uniqueUnitaryUser()` does not guarantee `nextOnA` and `nextOnB`
are in the same block, so `isBeforeInBlock` can trip MLIR preconditions when the
run spans blocks or regions. Update the logic around the `aSingle`/`bSingle`
check to first verify both successors are in the same block, and if not, stop
the scan before calling `isBeforeInBlock`; use the existing `nextOnA`,
`nextOnB`, and `sameOp` flow in `FuseTwoQubitUnitaryRuns.cpp` to place this
guard.

In `@mlir/unittests/Dialect/QCO/Transforms/NativeSynthesis/CMakeLists.txt`:
- Around line 12-26: The NativeSynthesis test target is missing the MemRef
dialect dependency even though the test registers memref::MemRefDialect in the
related test source. Update the target_link_libraries list for the test target
to include MLIRMemRefDialect alongside the existing MLIR dialect libraries,
matching the pattern used by other QCO test targets such as test_qc_ir.cpp and
test_qc_to_qco.cpp.

In
`@mlir/unittests/Dialect/QCO/Transforms/NativeSynthesis/test_fuse_two_qubit_unitary_runs.cpp`:
- Around line 388-390: The boundary comment in the test is stale and contradicts
the current pass behavior: in the scenario around the entangler and the
three-qubit gate, the wider gate should be described as stopping the run scan
and being left untouched, not “for the pass to reject.” Update the comment near
the affected test case in test_fuse_two_qubit_unitary_runs.cpp so it matches the
contract exercised by the surrounding test and the NativeSynthesis pass
behavior.

🪄 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: dbd760f5-f291-4778-bbd7-825ed27db900

📥 Commits

Reviewing files that changed from the base of the PR and between 5a1ea9d and 0b7922d.

📒 Files selected for processing (11)

• CHANGELOG.md
• mlir/include/mlir/Dialect/QCO/Transforms/Decomposition/Euler.h
• mlir/include/mlir/Dialect/QCO/Transforms/Decomposition/NativeGateset.h
• mlir/include/mlir/Dialect/QCO/Transforms/Passes.td
• mlir/lib/Dialect/QCO/Transforms/Decomposition/NativeGateset.cpp
• mlir/lib/Dialect/QCO/Transforms/NativeSynthesis/FuseSingleQubitUnitaryRuns.cpp
• mlir/lib/Dialect/QCO/Transforms/NativeSynthesis/FuseTwoQubitUnitaryRuns.cpp
• mlir/unittests/Dialect/QCO/Transforms/CMakeLists.txt
• mlir/unittests/Dialect/QCO/Transforms/Decomposition/test_weyl_decomposition.cpp
• mlir/unittests/Dialect/QCO/Transforms/NativeSynthesis/CMakeLists.txt
• mlir/unittests/Dialect/QCO/Transforms/NativeSynthesis/test_fuse_two_qubit_unitary_runs.cpp

[simon1hofmann]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.