✨ Add optimal square-root iSWAP synthesis

[simon1hofmann]

🤖 AI text below 🤖

Description

Add sqrt_iswap as a fixed two-qubit compiler target capability and expose CompilerTarget.GateKind.SQRT_ISWAP in Python. A supplied numeric 4x4 unitary uses the minimum of zero to three square-root iSWAP gates within the Weyl interaction tolerance, preserving single-qubit factors and global phase. The compiler emits xx_plus_yy(-pi/2, 0) and checks fixed parameters and ordered site placements. Existing entangler preferences are preserved.

Use the analytic three-gate prefix instead of searching twelve candidates. Stable beta extraction preserves small interactions, while the existing CNOT boundary handling remains intact. Reuse the operation matrix and reconstruction helper; attach one-gate local factors directly. Constant-zero beta permits native operand reversal without requiring a single-qubit synthesis basis.

Optimality applies to one supplied unitary, not a whole program. The target pipeline skips generic CX/CZ-cost fusion when square-root iSWAP is the selected entangler: otherwise a circuit containing four native gates can grow to six. A full-pipeline regression protects this limit.

Reviewed #2478 before making these changes. Shared recoverable Weyl failures, quaternion/Euler stability, matrix caching, and the no-synthesis-basis fusion guard remain in that PR. This PR does not copy them or depend on its unmerged commits. Tests use current main's target-environment API. When the two PRs are combined, preserve #2478's recoverable-result contract and both fusion guards.

Validation

• Rebased onto main 4c5e45855e5bb50c42b68ddbf4f9a4dababb8737; all rewritten commits and the fix commit are signed and verified.
• Clang 23 / LLVM-MLIR 23.1.0 native release with ThinLTO: 476 tests passed (242 decomposition, 53 native synthesis, 181 compiler).
• uvx nox -s lint and git diff --check: passed.
• uvx nox -s cpp-lint -- 4c5e45855e5bb50c42b68ddbf4f9a4dababb8737: passed on the complete changed C++ files.
• uvx nox -s stubs: passed; regenerated stubs match the PR. Python smoke checks confirm the enum, recognized capability, and selected synthesis basis.
• The review's isolated three-gate microbenchmark improved from 432 ms to 111 ms median per 10,000 decompositions after replacing only the prefix search. This is not an end-to-end compiler speedup.
• Fresh hosted CI must validate this pushed revision; previous green checks do not validate the rebase.

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:

• Any agent that created, edited, or submitted GitHub content was explicitly authorized for that scope, as required by our AI Usage Guidelines.
• Every agent-authored or agent-edited public text body begins with the visible disclosure 🤖 *AI text below* 🤖 (titles are exempt).
• I have disclosed AI assistance in the PR description.
• I confirm that I have personally reviewed and understood all AI-generated content, and accept full responsibility for it.

[simon1hofmann]

@coderabbitai full review

[coderabbitai]

✅ Action performed

Full review finished.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Advanced

Run ID: dac595f3-6857-484d-a09f-8b8698f0070f

📥 Commits

Reviewing files that changed from the base of the PR and between ec799da and 23adda3.

📒 Files selected for processing (10)

• CHANGELOG.md
• bindings/mlir/register_mlir.cpp
• mlir/include/mlir/Compiler/Target.h
• mlir/include/mlir/Dialect/QCO/Transforms/Decomposition/Weyl.h
• mlir/lib/Compiler/Target.cpp
• mlir/lib/Dialect/QCO/Transforms/Decomposition/Weyl.cpp
• mlir/unittests/Compiler/test_compiler_target.cpp
• mlir/unittests/Dialect/QCO/Transforms/Decomposition/test_weyl_decomposition.cpp
• mlir/unittests/Dialect/QCO/Transforms/NativeSynthesis/test_target_synthesis.cpp
• python/mqt/core/mlir.pyi

Included review availability: Your plan provides up to 2 included reviews per hour; 1 remains after this review.

---

📝 Summary

Summary by CodeRabbit

• New Features

  • Added √iSWAP as a supported two-qubit gate for compiler targets.
  • Added √iSWAP decomposition and native synthesis support, including circuits using one to three √iSWAP gates.
  • Exposed √iSWAP in the Python compiler target API.

• Bug Fixes

  • Improved target capability checks for fixed √iSWAP parameters and qubit placement.

• Tests

  • Added coverage for decomposition, synthesis, gate support, parameter validation, and placement.

Walkthrough

The compiler adds SQRTISWAP as a native gate capability. Weyl decomposition supports zero- through three-gate √iSWAP circuits. Target-native synthesis validates minimality, parameter matching, placement, and equivalence.

Changes

√iSWAP native gate support

Layer / File(s)	Summary
Target gate contract mlir/include/mlir/Compiler/Target.h, mlir/lib/Compiler/Target.cpp, bindings/mlir/register_mlir.cpp, python/mqt/core/mlir.pyi, mlir/unittests/Compiler/test_compiler_target.cpp	Adds SQRTISWAP to the target gate enum, specifications, bindings, Python declarations, preference order, and support checks.
√iSWAP Weyl decomposition mlir/include/mlir/Dialect/QCO/Transforms/Decomposition/Weyl.h, mlir/lib/Dialect/QCO/Transforms/Decomposition/Weyl.cpp, mlir/unittests/Dialect/QCO/Transforms/Decomposition/test_weyl_decomposition.cpp	Adds decomposeSqrtISwap, zero- through three-gate synthesis, operation emission, and reconstruction tests for chamber grids, boundaries, and random interactions.
Native synthesis validation mlir/unittests/Dialect/QCO/Transforms/NativeSynthesis/test_target_synthesis.cpp, CHANGELOG.md	Tests minimal native synthesis, fixed parameters, placement, equivalence, and records the change in the unreleased changelog.

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

Merge Risk: ⚪ Minimal · up to 23add

The √iSWAP target support is internally consistent and no actionable merge-blocking risk is established.

Sequence Diagram(s)

sequenceDiagram
  participant Target as CompilerTarget
  participant Weyl as Weyl decomposition
  participant Synthesis as Target-native synthesis
  participant QCO as QCO operations
  Target->>Target: Recognize sqrt_iswap capability
  Synthesis->>Weyl: Decompose two-qubit unitary with SQRTISWAP
  Weyl->>QCO: Emit XXPlusYY(-pi/2, 0)
  Synthesis->>Target: Check parameters and placement
  Target-->>Synthesis: Return support result

Loading

Suggested reviewers: burgholzer, denialhaag

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 12.50% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 24 functions across 9 files. (1 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
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.
Title check	✅ Passed	The title clearly summarizes the main change: adding optimal square-root iSWAP synthesis.
Description check	✅ Passed	The description is complete and relevant. It explains the implementation, motivation, validation, tests, AI disclosure, and checklist status. No issue number or explicit dependency list is provided, b…

Full details: Docstring Coverage

Explanation

Docstring coverage is 12.50% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 24 functions across 9 files. (1 skipped: 1 unsupported.)

---

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

_{A rabbit reviews the gates tonight
√iSWAP hops through circuits bright
Three small leaps, then phase aligns
Tests guard boundaries and designs
The compiler blooms with quantum light}

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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[burgholzer]

Pushed some very small adjustments here. Let's get this in 👍🏼