✨ Add native gate synthesis MLIR pass and decomposition stack

[simon1hofmann]

Description

Introduces a native-gate-synthesis transform on QCO modules that lowers arbitrary supported unitaries to a comma-separated native gate menu, with scoring over two-qubit count, single-qubit count, and local depth.

User-visible behavior
--native-gates=<menu> on mqt-cc (empty menu = no-op), aligned with pass options documented in Passes.td (native-gates, score-weight-twoq, score-weight-oneq, score-weight-depth).

Fixes #(issue)

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

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

📢 Thoughts on this report? Let us know!

[github-actions]

Cpp-Linter Report ⚠️

Some files did not pass the configured checks!

clang-tidy (v22.1.8) reports: 4 concern(s)

• mlir/lib/Dialect/QCO/Transforms/NativeSynthesis/FuseTwoQubitUnitaryRuns.cpp:49:31: warning: [llvm-prefer-static-over-anonymous-namespace]

  function 'nativeGateKindFor' is declared in an anonymous namespace; prefer using 'static' for restricting visibility

     49 | std::optional<NativeGateKind> nativeGateKindFor(UnitaryOpInterface op) {
        |                               ^

• mlir/lib/Dialect/QCO/Transforms/NativeSynthesis/FuseTwoQubitUnitaryRuns.cpp:62:31: warning: [llvm-prefer-static-over-anonymous-namespace]

  function 'nativeEntanglerKindFor' is declared in an anonymous namespace; prefer using 'static' for restricting visibility

     62 | std::optional<NativeGateKind> nativeEntanglerKindFor(CtrlOp ctrl) {
        |                               ^

• mlir/lib/Dialect/QCO/Transforms/NativeSynthesis/FuseTwoQubitUnitaryRuns.cpp:79:6: warning: [llvm-prefer-static-over-anonymous-namespace]

  function 'allowsOp' is declared in an anonymous namespace; prefer using 'static' for restricting visibility

     79 | bool allowsOp(Operation* op, const NativeGateset& spec) {
        |      ^

• mlir/unittests/Dialect/QCO/Transforms/NativeSynthesis/test_fuse_two_qubit_unitary_runs.cpp:11:1: warning: [misc-include-cleaner]

  included header TestCaseUtils.h is not used directly

     11 | #include "TestCaseUtils.h"
        | ^~~~~~~~~~~~~~~~~~~~~~~~~~
     12 | #include "mlir/Conversion/QCToQCO/QCToQCO.h"

Have any feedback or feature suggestions? Share it here.