Decompose multi-controlled single-qubit gates during transpilation

[luffy-orf]

Summary

This PR fixes #1843: multi-controlled single-qubit gates (e.g. RY, RX, H, U3) were not fully transpiled when produced as intermediate gates during decomposition of larger gates like controlled GIVENS.

Before: circuit.decompose() could leave multi-controlled rotation gates in the circuit.

After: gates with two or more controls on a single qubit are synthesized into elementary gates (CNOT, H, RX, RY, RZ, SX, etc.) using techniques from Vale et al. (2023).

What changed

Gate.decompose() - second pass

After the existing flow (decompose base gate → re-apply controls via control mask), a new pass expands any remaining multi-controlled single-qubit gates (≥2 controls) into elementary gates. Singly-controlled gates (CH, internals of controlled RBS, etc.) are unchanged.

New module: src/qibo/transpiler/multi_controlled_su2.py

Independent implementation (not copied from qclib), aligned with the maintainer design discussed in the issue:

Path	Use case	Reference
_decompose_multi_controlled_su2_real	Real-diagonal SU(2) (MCRX, MCRY, MCRZ, etc.)	Vale et al., Theorem 2
_decompose_multi_controlled_su2	Generic SU(2) via eigen-decomposition when needed	Vale et al., Theorem 1
_decompose_multi_controlled_u2	Non-SU(2) gates (e.g. multi-controlled H, det ≠ 1)	Ldmcu-style decomposition

Core building blocks include multi-controlled X via dirty-ancilla vchain (Iten et al.) and linear-depth multi-controlled SU(2) synthesis (Vale et al.).

Gate._base_decompose()

Routes directly to the new synthesis when a gate already has ≥2 controls.

decompositions.py

Re-exports the protected synthesis helpers for use elsewhere in the transpiler stack.

Example (issue reproduction)

from qibo import Circuit, gates

circuit = Circuit(4)
circuit.add(gates.GIVENS(2, 3, 0.1).controlled_by(0, 1))
decomposed = circuit.decompose()

Checklist:

• Reviewers confirm new code works as expected.
• Tests are passing.
• Coverage does not decrease.
• Documentation is updated.

[codecov]

Codecov Report

❌ Patch coverage is 73.25103% with 65 lines in your changes missing coverage. Please review.
✅ Project coverage is 99.05%. Comparing base (56a9c11) to head (2ac953b).
⚠️ Report is 131 commits behind head on master.

Files with missing lines	Patch %	Lines
src/qibo/transpiler/multi_controlled_su2.py	73.41%	63 Missing ⚠️
src/qibo/gates/abstract.py	60.00%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1859      +/-   ##
==========================================
- Coverage   99.50%   99.05%   -0.46%     
==========================================
  Files          78       79       +1     
  Lines       13886    14128     +242     
==========================================
+ Hits        13817    13994     +177     
- Misses         69      134      +65     

Flag	Coverage Δ
unittests	99.05% <73.25%> (-0.46%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.