Port TwoQubitControlledUDecomposer to rust

[ShellyGarion]

Summary

close #12907

Details and comments

depends on #13168

Performance improvement:
Synthesizing 100 random 4x4 unitary matrices into each of the basis gates [RXX, RYY, RZZ, RZX, CRZ, CPhase] takes:
in Python: 20.57 sec
in Rust: 8.85

[qiskit-bot]

One or more of the following people are relevant to this code:

• @Qiskit/terra-core
• @levbishop

[coveralls]

Pull Request Test Coverage Report for Build 11379353519

Warning: This coverage report may be inaccurate.

This pull request's base commit is no longer the HEAD commit of its target branch. This means it includes changes from outside the original pull request, including, potentially, unrelated coverage changes.

• For more information on this, see Tracking coverage changes with pull request builds.
• To avoid this issue with future PRs, see these Recommended CI Configurations.
• For a quick fix, rebase this PR at GitHub. Your next report should be accurate.

Details

• 290 of 309 (93.85%) changed or added relevant lines in 2 files are covered.
• 668 unchanged lines in 27 files lost coverage.
• Overall coverage decreased (-0.2%) to 88.678%

---

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
qiskit/synthesis/two_qubit/two_qubit_decompose.py	6	7	85.71%
crates/accelerate/src/two_qubit_decompose.rs	284	302	94.04%

Files with Coverage Reduction	New Missed Lines	%
crates/qasm2/src/expr.rs	1	94.02%
crates/accelerate/src/elide_permutations.rs	1	97.06%
crates/accelerate/src/error_map.rs	1	85.42%
crates/accelerate/src/circuit_library/quantum_volume.rs	1	96.69%
qiskit/circuit/library/quantum_volume.py	2	95.45%
crates/accelerate/src/barrier_before_final_measurement.rs	2	97.33%
crates/circuit/src/lib.rs	2	96.15%
qiskit/transpiler/passes/synthesis/unitary_synthesis.py	2	88.19%
crates/circuit/src/bit_data.rs	2	94.62%
crates/accelerate/src/commutation_checker.rs	2	97.14%

Totals
Change from base Build 11241264267:	-0.2%
Covered Lines:	73411
Relevant Lines:	82784

---

💛 - Coveralls

[mtreinish]

Overall the code looks good, I left a few inline comments on how to simplify or optimize things a bit. The biggest concern I have right now though is the backwards incompatibility of the API. This PR restricts the gate objects that TwoQubitControlledUDecomposer class can work with to just standard gates defined in Qiskit. This wasn't a limitation before the rust rewrite and would be considered a breaking api change. However, I'm not sure the class is considered public, it's never been externally documented from what I can tell. I'm curious of your thoughts on this though because I'm not sure what you're thinking about making this class public or not.

[mtreinish]

Do you think we should treat this class as public at all? The python space definition wasn't limited to standard gates, it would support any python space Gate object including a custom defined gate. This will error in the case of a custom PyGate though.

[ShellyGarion]

Currently, rxx_equivalent_gate could be only a StandardGate since in the code we need to invert it, and there is currently no inverse function for other types, see these lines:

                let circ_c = self.to_rxx_gate(gamma)?;
                ...
                for gate in circ_c.gates.into_iter().rev() {
                    let (inv_gate_name, inv_gate_params, inv_gate_qubits) = invert_2q_gate(gate);

[ShellyGarion]

As for making this class public, I think that it may be useful. Should we do it now or only after it's added to the UnitarySynthesis transpiler pass #13320?

[mtreinish]

Is there a reason we can't return a CircuitData here? That way we're building the output circuit directly instead of this intermediate vec. This should speed up the python space class's __call__ function because we've built the circuit object in rust instead of in python.

[ShellyGarion]

Could you please explain how to convert TwoQubitGateSequence to CircuitData ?

[ElePT]

@ShellyGarion you can iterate over the gates in the sequence and push them to a new CircuitData object, there is an example in TwoQubitWeylDecomposition: https:/Qiskit/qiskit/blob/main/crates/accelerate/src/two_qubit_decompose.rs#L1151-L1170

[ShellyGarion]

thanks! how to convert gate.2 which is of type SmallVec<[u8; 2]> into Qubit ?

[ShellyGarion]

OK, I found a solution, in 02cd73e

[mtreinish]

This is potentially a breaking API change if we treat this class as public. I think we can probably get away with considering it private since as far as I can tell we've never documented it. If we wanted to support arbitrary gates it wouldn't be too hard this is why TwoQubitGateSequence has an Option<StandardGate> in it. We'd have to pass the other details to get the matrix from the parameter value to rust but then we can keep the arbitrary gate support and when we encounter None we use that.

That being said if we're ok (I'm not 100% convinced one way or the other) making this API change to the class because we consider this internal only, we should change this to do something like:

Suggested change

	self._inner_decomposition = two_qubit_decompose.TwoQubitControlledUDecomposer(
	rxx_equivalent_gate._standard_gate
	if (gate := rxx_equivalent_gate.getattr("_standard_gate", None)) is not None:
	self._inner_decomposition = two_qubit_decompose.TwoQubitControlledUDecomposer(
	rxx_equivalent_gate._standard_gate
	else:
	raise QiskitError("Must be initialized with a standard gate object")

so we raise a meaningful error if this is instantiated with a non-standard gate.

[ShellyGarion]

done in 3182838
I had to change the if line to
if rxx_equivalent_gate._standard_gate is not None:
otherwise the tests were failing.

[ShellyGarion]

Overall the code looks good, I left a few inline comments on how to simplify or optimize things a bit. The biggest concern I have right now though is the backwards incompatibility of the API. This PR restricts the gate objects that TwoQubitControlledUDecomposer class can work with to just standard gates defined in Qiskit. This wasn't a limitation before the rust rewrite and would be considered a breaking api change. However, I'm not sure the class is considered public, it's never been externally documented from what I can tell. I'm curious of your thoughts on this though because I'm not sure what you're thinking about making this class public or not.

I would appreciate @levbishop opinion regarding this question as he wrote the original Python code.
I agree that as far as I know this class has never been published as part of Qiskit API. We can make it public if we think it will be useful. perhaps after adding it to the UnitarySynthesis transpiler pass #13320.
In addition, in the tests we test only standard gates:

qiskit/test/python/synthesis/test_synthesis.py

Line 1429 in fbfe738

for gate in [RXXGate, RYYGate, RZZGate, RZXGate, CPhaseGate, CRZGate]:

So I wonder if this class was ever meant to be used with basic gates that are not standard gates.
Anyway, since the Pulse library is being deprecated in #13164, the users will not be able to calibrate their own basic gates with Qiskit and hence this code will be useful only for standard gates.