🐛 Fix and simplify QCO decomposition

[simon1hofmann]

🤖 AI text below 🤖

Description

Fix decomposition and fusion on valid QCO IR, and remove repeated work without adding pass-local IR verification or relaxing numerical tolerances.

• Count all participating qubits in single-qubit fusion, including controlled global phases.
• Make numerical Weyl failure recoverable: optional fusion leaves the affected run unchanged, while required native synthesis reports failure before emitting its replacement.
• Run optional generic two-qubit fusion only for unrestricted targets or targets with a usable two-qubit synthesis basis. Already-native CX-only and U+DCX programs remain compilable.
• Preserve small rotations with stable quaternion-to-Euler extraction. Use sparse ZYZ products and direct RX/RY-to-R synthesis without combining input half angles or changing phase accounting.
• Reuse embedded matrix kernels and cache pending one-qubit matrices. Flatten SP22 planning and remove unreachable HP24 alternatives, identity maps, and redundant basis-count selection work.
• Retain semantic, phase, wire-order, and gate-cost regressions while removing redundant test scaffolding.

Updated against main at 4c5e45855, including #2464 and the target-environment API. Its centralized modifier-matrix handling is retained unchanged at the getters; this PR optimizes the shared composer while preserving full-width, idle-target, zero-target, ordered-yield, and width-limit behavior. The duplicate getter fix was dropped. The update keeps the parameterless target pass factories and adapts the affected regression tests to the typed target environment. Numerical-failure documentation remains in the pass definition.

C++ API note: decomposeUnitary2QWeyl now returns an optional result. TwoQubitWeylDecomposition::tryCreate provides the recoverable path; create retains its success-required contract. Related decomposition work in #2467 and #2468 is not duplicated.

No new dependencies. Detailed audit notes and standalone experimental probes are excluded from the PR.

Validation

• Release rebuild with LLVM/MLIR 23.1.0: 1,374 tests passed across decomposition (242), native synthesis (52), optimizations (197), QCO IR (512), QCO utilities (190), and compiler (181).
• uvx nox -s lint: passed.
• Whole-file uvx nox -s cpp-lint: passed across all 15 changed C++ implementation/test files, with zero findings.
• mlir-doc generation: passed.
• Historical implementation validation: the Python reference script ran all 18 cases. Independent probes confirmed zero SWAP error and a small-angle error reduction from approximately 7.1e-9 to 2.5e-17 before integration with main; the native regression suites were rerun for this update. The standalone probes were not rerun.

Local clang-tidy is 23.0.0git, not CI's 23.1.1. Hosted CI must rerun on the updated head. Local coverage, Python binding tests, and a full Sphinx build were not rerun for this update; results from the previous head are not claimed for the new commit.

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.
• Changelog entries: not applicable to this unreleased v4 functionality, per repository policy.
• Upgrade guide: no standalone entry for unreleased functionality; the C++ API contract is documented in its header.
• The changes follow the project's style guidelines and introduce no new warnings in local checks.
• The changes are fully tested and pass the CI checks. Local checks passed; hosted CI pending.
• I have reviewed my own code changes. Independent agent review completed; personal human review remains to be confirmed.

AI assistance: Codex assisted with the audit, implementation, tests, independent review, and PR preparation. A human must review the contribution before accepting or merging it.

• Any agent that created, edited, or submitted GitHub content was explicitly authorized for that scope, as required by the 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.

[codecov]

Codecov Report

❌ Patch coverage is 94.88372% with 11 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
.../lib/Dialect/QCO/Transforms/Decomposition/Weyl.cpp	84.4%	7 Missing ⚠️
mlir/lib/Dialect/QCO/IR/QCOUtils.cpp	85.7%	4 Missing ⚠️

📢 Thoughts on this report? Let us know!