Add 2q fractional gates to the `UnitarySynthesis` tranpiler pass #13568

ShellyGarion · 2024-12-16T11:06:40Z

Summary

With the introduction of new 2q-fractional gates, such as RZZGate as part of the QPU, we add them to the UnitarySynthesis transpiler pass.
https://www.ibm.com/quantum/blog/fractional-gates

Details and comments

qiskit-bot · 2024-12-16T11:06:45Z

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

@Qiskit/terra-core
@levbishop

coveralls · 2024-12-16T13:24:13Z

Pull Request Test Coverage Report for Build 12927458790

Details

135 of 136 (99.26%) changed or added relevant lines in 4 files are covered.
6 unchanged lines in 3 files lost coverage.
Overall coverage increased (+0.03%) to 88.972%

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
crates/accelerate/src/unitary_synthesis.rs	89	90	98.89%

Files with Coverage Reduction	New Missed Lines	%
crates/accelerate/src/two_qubit_decompose.rs	1	92.08%
crates/accelerate/src/unitary_synthesis.rs	2	93.48%
crates/qasm2/src/lex.rs	3	92.48%

Totals
Change from base Build 12913135837:	0.03%
Covered Lines:	79528
Relevant Lines:	89385

💛 - Coveralls

qiskit/transpiler/passes/synthesis/unitary_synthesis.py

ElePT

Hi @ShellyGarion! thanks for opening the PR, I left a couple of preliminary comments. I hope they make sense :)

qiskit/transpiler/passes/synthesis/unitary_synthesis.py

qiskit/synthesis/two_qubit/two_qubit_decompose.py

ElePT · 2024-12-17T13:44:10Z

qiskit/transpiler/passes/synthesis/unitary_synthesis.py

+    # if isinstance(kak_gate, RZXGate):
+    #    backup_optimizer = TwoQubitBasisDecomposer(
+    #        CXGate(),
+    #        basis_fidelity=basis_fidelity,
+    #        euler_basis=euler_basis,
+    #        pulse_optimize=pulse_optimize,
+    #    )
+    #    decomposer2q = XXDecomposer(euler_basis=euler_basis, backup_optimizer=backup_optimizer)
+
+    if kak_gate in KAK_GATE_PARAM_NAMES.values():
+        decomposer2q = TwoQubitControlledUDecomposer(kak_gate)


Double checking our discussion from earlier in the week: for the target-aware code we discussed adding a third check (apart from is_controlled or is_supercontrolled) to differentiate cases for the 3 available decomposers: TwoQubitDecomposer, XXDecomposer, and TwoQubitControlledUDecomposer. However, for the Python code (just basis gates), it looks like we are simply substituting the XXDecomposer for the TwoQubitControlledUDecomposer. Is this the plan?

In the case of basis gates, I'm not sure if we can have 3 options or only 2 (this is why this code is only commented out and not removed yet).
If a user provides the basis gates [rzz, rz, ry] how can we tell if they want an RZZGate with an arbitrary angle or an RZZGate with a fixed angle (and if so - which fixed value)?

Another comment: I ran the tests in qiskit/test/python/transpiler/test_unitary_synthesis.py (main branch), and couldn't find any test that goes into the following "if" statement (lines 181-188 above), so I wonder if the XXDecomposer here has ever been used.

I am not surprised, the coverage of these tests is not good because a lot of the tests are in the synthesis folder and not testing the transpilation pipeline, but calling the synthesis methods directly. Maybe this is a good opportunity to do some test refactoring before merging this PR. During the Rust migration I also noticed there weren't any tests for the UnitarySynthesis class that used the QSD method with a target and had to add a couple of them. I think it would make sense to ensure that we have a couple of tests per decomposer, and that there are sufficient tests for the target (HW-aware) path (this I could do in a separate PR because I didn't have time to look more into it during the Rust migration).

If a user provides the basis gates [rzz, rz, ry] how can we tell if they want an RZZGate with an arbitrary angle or an RZZGate with a fixed angle?

I think this is up to us to decide and document the behavior change. I am not sure how many users actually rely or expect the fixed angle?

FYI, I started the test cleanup with this PR: #13582, that is not much but I think can be helpful for future development. Let me know if you have any thoughts on it!

Another question is what to expect when given a parametrized gate in the target? see e.g this test.

Currently, we replace the parametrized gates by gates with a constant angle, without even checking if this angle is actually calibrated in the target:

qiskit/qiskit/transpiler/passes/synthesis/unitary_synthesis.py

Line 801 in 079f69f

def _replace_parameterized_gate(op):

Again, I could not find any test that checks the XXDecomposer with a given target, namely the tests don't go into here.

It seems that _decomposer_2q_from_target is not being tested at all, since the tests for UnitarySynthesis pass for the target use the rust code.
Should this function be removed or updated to include TwoQubitControlledUDecomposer ? (and then some tests should be added).

Since the function _decomposer_2q_from_target is part of the DefaultUnitarySynthesis plugin we don't update it as part of this PR. We should consider porting this code to rust in a follow-up PR.

crates/accelerate/src/unitary_synthesis.rs

ShellyGarion · 2025-01-20T12:40:57Z

qiskit/synthesis/two_qubit/two_qubit_decompose.py

@@ -270,32 +270,46 @@ class TwoQubitControlledUDecomposer:
    :math:`U \sim U_d(\alpha, 0, 0) \sim \text{Ctrl-U}`
    gate that is locally equivalent to an :class:`.RXXGate`."""

-    def __init__(self, rxx_equivalent_gate: Type[Gate]):
+    def __init__(self, rxx_equivalent_gate: Type[Gate], euler_basis: str = "ZYZ"):
        r"""Initialize the KAK decomposition.


should we replace the default value to "ZXZ" to match the current fractional gates rx and rz ?
(If so, we should do this more generally in other places of the code in this file)

I replaced "ZYZ" to "ZXZ". Should we also do it in other classes ?

Mmm I don't really know what motivated the original choice of default gates, maybe it was done on purpose not to match the current fractional gates? @mtreinish do you have any insight?

ShellyGarion · 2025-01-20T12:41:51Z

crates/accelerate/src/two_qubit_decompose.rs

    ///  Raises:
    ///      QiskitError: If the gate is not locally equivalent to an :class:`.RXXGate`.
    #[new]
-    #[pyo3(signature=(rxx_equivalent_gate))]
-    pub fn new(py: Python, rxx_equivalent_gate: RXXEquivalent) -> PyResult<Self> {
+    #[pyo3(signature=(rxx_equivalent_gate, euler_basis="ZYZ"))]


should we replace the default value here to "ZXZ"? If so, we should better do this in other places of this file.

I replaced the default to "ZXZ". Should we do it in other classes as well?

t-imamichi · 2025-01-21T13:14:31Z

I think this closes #13428. How about adding a test case of consecutive RZZ (RXX, and RYY) gates?

ElePT

Hi @ShellyGarion, thanks for your PR!! I think that this is a very good start, I left some comments that are mostly non-crucial improvements, as well as one important question on the check_parametrized_gate function. I will make sure to review the new unit tests when you add them, and feel free to reach out if you have any question (or objection) :)

crates/accelerate/src/two_qubit_decompose.rs

ElePT · 2025-01-21T13:40:39Z

crates/accelerate/src/two_qubit_decompose.rs

+    /// Initialize the KAK decomposition.
+    pub fn new_inner(
+        py: Python,
+        rxx_equivalent_gate: RXXEquivalent,
+        euler_basis: &str,
+    ) -> PyResult<Self> {
        let atol = DEFAULT_ATOL;


I know we discussed the addition of a new_inner class, but the current implementation doesn't seem to add (or remove) anything to the existing new class, so I would just keep and use new in the rust code.

the new function is pyo3 method -- isn't the new_inner function faster? if not, I can change it back.

I managed to remove the need of py in 231af7f
by replacing it with gil, as suggested by Matthew in #13419.
I still think we need both functions new and new_inner since one of them is in pure rust and the other is pyo3.

Yes, let's keep them.

crates/accelerate/src/two_qubit_decompose.rs

ElePT · 2025-01-21T13:44:53Z

crates/accelerate/src/unitary_synthesis.rs

+                let scoring_info =
+                    sequence
+                        .gate_sequence
+                        .gates()
+                        .iter()
+                        .map(|(gate, params, qubit_ids)| {
+                            let inst_qubits =
+                                qubit_ids.iter().map(|q| ref_qubits[*q as usize]).collect();
+                            match gate {
+                                Some(gate) => (
+                                    gate.name().to_string(),
+                                    Some(params.iter().map(|p| Param::Float(*p)).collect()),
+                                    inst_qubits,
+                                ),
+                                None => (
+                                    sequence
+                                        .decomp_gate
+                                        .operation
+                                        .standard_gate()
+                                        .name()
+                                        .to_string(),
+                                    Some(params.iter().map(|p| Param::Float(*p)).collect()),
+                                    inst_qubits,
+                                ),
+                            }
+                        });
+                let synth_error_from_target = synth_error(py, scoring_info, target);
+                synth_errors_sequence.push((sequence, synth_error_from_target));


I should have come up with a nicer solution at the time, but back when we only had 2 decomposer types and the code for the scoring_info was slightly different, I was relatively ok with the code duplication. Now that two of the three arms look almost exactly the same, I wonder if we could abstract the code in a smarter way to avoid so much repetition. I don't think this will affect performance so it can also be left to a follow-up.

ElePT · 2025-01-21T13:51:14Z

crates/accelerate/src/unitary_synthesis.rs

+            if PARAM_SET.contains(&std_gate.name()) {
+                if let Param::ParameterExpression(_) = op.params[0] {
+                    return true;


I think we might be missing out a group of gates here. As far as I understand it, the TwoQubitControlledUDecomposer works not only for standard gates (the ones defined in PARAM_SET), but should also be at least a candidate for user-defined parametrized unitary gates that match the input conditions. In that case, we should probably not check PARAM_SET.contains(&std_gate.name()), and instead consider any 2q unitary parametrized gate for the "available_2q_param_basis".

Note that not any parametrized gate can fit here, only certain parametrized gates which are equivalent (up to single qubit gates) to an RXXGate. The TwoQubitControlledUDecomposer works for such gates if the user was able to calibrate them somehow. Should the UnitarySynthesis transpiler pass fit any calibrated gates?
So I'm not sure what exactly should be checked here. See the function TwoQubitControlledUDecomposer.to_rxx_gate

We currently support non-standard gates too, so the pass should work if there is a non-standard gate that meets the condition of rxx equivalence. TwoQubitControlledUDecomposer::new already checks if the gate is rxx equivalent:

qiskit/crates/accelerate/src/two_qubit_decompose.rs

Lines 2777 to 2822 in e9ccd3f

let test_angles = [0.2, 0.3, PI2];

let scales: PyResult<Vec<f64>> = test_angles

.into_iter()

.map(|test_angle| {

match &rxx_equivalent_gate {

RXXEquivalent::Standard(gate) => {

if gate.num_params() != 1 {

return Err(QiskitError::new_err(

"Equivalent gate needs to take exactly 1 angle parameter.",

));

}

}

RXXEquivalent::CustomPython(gate_cls) => {

if gate_cls.bind(py).call1((test_angle,)).ok().is_none() {

return Err(QiskitError::new_err(

"Equivalent gate needs to take exactly 1 angle parameter.",

));

}

}

};

let mat = rxx_equivalent_gate.matrix(py, test_angle)?;

let decomp =

TwoQubitWeylDecomposition::new_inner(mat.view(), Some(DEFAULT_FIDELITY), None)?;

let mat_rxx = StandardGate::RXXGate

.matrix(&[Param::Float(test_angle)])

.unwrap();

let decomposer_rxx = TwoQubitWeylDecomposition::new_inner(

mat_rxx.view(),

None,

Some(Specialization::ControlledEquiv),

)?;

let decomposer_equiv = TwoQubitWeylDecomposition::new_inner(

mat.view(),

Some(DEFAULT_FIDELITY),

Some(Specialization::ControlledEquiv),

)?;

let scale_a = decomposer_rxx.a / decomposer_equiv.a;

if (decomp.a * 2.0 - test_angle / scale_a).abs() > atol {

return Err(QiskitError::new_err(

"The provided gate is not equivalent to an RXXGate.",

));

}

Ok(scale_a)

})

.collect();

So I was thinking that we could abstract that logic and add a check to UnitarySynthesis similar to is_controlled or is_supercontrolled, but in this case it could be called is_rxx_equivalent(for example). The idea for the check is to filter out the non-rxx-equivalent gates.

crates/accelerate/src/unitary_synthesis.rs

ElePT · 2025-01-21T13:53:44Z

qiskit/synthesis/two_qubit/two_qubit_decompose.py

@@ -270,32 +270,46 @@ class TwoQubitControlledUDecomposer:
    :math:`U \sim U_d(\alpha, 0, 0) \sim \text{Ctrl-U}`
    gate that is locally equivalent to an :class:`.RXXGate`."""

-    def __init__(self, rxx_equivalent_gate: Type[Gate]):
+    def __init__(self, rxx_equivalent_gate: Type[Gate], euler_basis: str = "ZYZ"):
        r"""Initialize the KAK decomposition.


Mmm I don't really know what motivated the original choice of default gates, maybe it was done on purpose not to match the current fractional gates? @mtreinish do you have any insight?

crates/accelerate/src/unitary_synthesis.rs

ShellyGarion · 2025-01-23T06:58:13Z

I think this closes #13428. How about adding a test case of consecutive RZZ (RXX, and RYY) gates?

@t-imamichi - unfortunately this PR does not close #13428 yet, since the ConsolidateBlocks transpiler pass does not consolidate the consecutive RZZ gates into a single unitary.
This should be fixed in #13419.
I will therefore transfer your comment there.

ElePT

Thanks for the tests! I took a look and they look good to me.

ElePT · 2025-01-24T13:28:02Z

test/python/transpiler/test_unitary_synthesis.py

-        """Test synthesis with parameterized RXX gate."""
+    @data(True, False)
+    def test_parameterized_basis_gate_in_target(self, is_random):
+        """Test synthesis with parameterized RZZ gate."""


Would it make sense to keep both the test for RXX and RZZ? Given that we used to have it...

ElePT · 2025-01-24T13:29:13Z

test/python/transpiler/test_unitary_synthesis.py

+    )
+    def test_parameterized_backend(self, basis_gates):
+        """Test synthesis with parameterized backend."""
+        backend = GenericBackendV2(3, basis_gates=basis_gates)


I don't think this will have a big effect on this particular test, but as a good practice, I recommend always setting the seed of the generic backend to make sure the errors and durations are always the same (this affects especially the routing tests)

Suggested change

backend = GenericBackendV2(3, basis_gates=basis_gates)

backend = GenericBackendV2(3, basis_gates=basis_gates, seed=0)

TwoQubitControlledUDecomposer to _decomposer_2q_from_basis_gates

89ca81e

ShellyGarion added the mod: transpiler Issues and PRs related to Transpiler label Dec 16, 2024

ShellyGarion added this to the 2.0.0 milestone Dec 16, 2024

ShellyGarion requested a review from ElePT December 16, 2024 11:06

ShellyGarion requested review from alexanderivrii and a team as code owners December 16, 2024 11:06

ElePT self-assigned this Dec 16, 2024

update (temporarily) basis gates in test

077ecb9

gadial reviewed Dec 17, 2024

View reviewed changes

qiskit/transpiler/passes/synthesis/unitary_synthesis.py Show resolved Hide resolved

ElePT reviewed Dec 17, 2024

View reviewed changes

minor fix

18b20f6

ElePT mentioned this pull request Dec 19, 2024

Small refactoring of unitary synthesis tests #13582

Merged

ShellyGarion and others added 13 commits December 19, 2024 06:49

add EulerBasis as a parameter to TwoQubitControlledUDecomposer

967da13

fix global_phase calculation in TwoQubitContolledUDecomposer

3bb10fd

add TwoQubitControlledUDecomposer to the docs

14c7aac

make the choice of kak_gate deterministic

eeff4cd

Merge branch 'main' into unitary_synth

043a795

remove XXDecomposer from _decomposer_2q_from_basis_gates

b94070a

make call_inner pub, add Clone, Debug

0a1644b

add TwoQubitControlledUDecomposer to unitary_synthesis.rs

48fec9b

merge main branch, fix conflict

009d87e

Fix exit condition for GOODBYE_SET and PARAM_SET

85e2962

fix conflict with main branch

c5d0c97

make DEFAULT_ATOL public

d7b84e9

add TwoQubitControlledUDecomposer to synth_su4_sequence

ea9a2d0

ShellyGarion commented Jan 16, 2025

View reviewed changes

crates/accelerate/src/unitary_synthesis.rs Outdated Show resolved Hide resolved

ShellyGarion commented Jan 16, 2025

View reviewed changes

crates/accelerate/src/unitary_synthesis.rs Outdated Show resolved Hide resolved

ShellyGarion commented Jan 16, 2025

View reviewed changes

crates/accelerate/src/unitary_synthesis.rs Outdated Show resolved Hide resolved

ShellyGarion commented Jan 16, 2025

View reviewed changes

crates/accelerate/src/unitary_synthesis.rs Outdated Show resolved Hide resolved

Add support for parametrized decomposer gate in apply_synth_sequence

132a44f

ShellyGarion commented Jan 20, 2025

View reviewed changes

ShellyGarion added 4 commits January 20, 2025 07:51

change DecomposerType enum to fix clippy error

b1cb5a0

add a random unitary test to test_parametrized_basis_gate_in_target

9cdf2da

add public new_inner for TwoQubitControlledUDecomposer

1be749d

replace default 'ZYZ' by 'ZXZ' in TwoQubitControlledUDecomposer

1495781

ShellyGarion changed the title ~~[WIP] Add 2q fractional gates to the UnitarySynthesis tranpiler pass~~ Add 2q fractional gates to the UnitarySynthesis tranpiler pass Jan 21, 2025

ShellyGarion requested a review from mtreinish January 21, 2025 08:48

ShellyGarion added the synthesis label Jan 21, 2025

ElePT mentioned this pull request Jan 21, 2025

Oxidize UnitarySynthesis path using basis_gates #13704

Draft

ElePT reviewed Jan 21, 2025

View reviewed changes

ElePT mentioned this pull request Jan 21, 2025

Remove use of BackendProperties (BackendV1) in UnitarySynthesis pass #13706

Open

ShellyGarion mentioned this pull request Jan 23, 2025

[WIP] Add new multithreaded TwoQubitPeepholeOptimization pass #13419

Draft

6 tasks

ShellyGarion added 6 commits January 23, 2025 02:25

remove using py in rust functions

231af7f

minor update to test

bb874c1

make atol optional

c2a9ad4

fix conflict with main branch

d39c005

add a test with fractional gates in the backend

106ae4a

add release notes

9131e3d

ElePT reviewed Jan 24, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add 2q fractional gates to the `UnitarySynthesis` tranpiler pass #13568

Add 2q fractional gates to the `UnitarySynthesis` tranpiler pass #13568

ShellyGarion commented Dec 16, 2024

qiskit-bot commented Dec 16, 2024

coveralls commented Dec 16, 2024 •

edited

Loading

ElePT left a comment

ElePT Dec 17, 2024

ShellyGarion Dec 17, 2024 •

edited

Loading

ShellyGarion Dec 18, 2024

ElePT Dec 18, 2024 •

edited

Loading

ElePT Dec 18, 2024

ElePT Dec 19, 2024

ShellyGarion Dec 23, 2024

ShellyGarion Jan 13, 2025

ShellyGarion Jan 20, 2025 •

edited

Loading

ShellyGarion Jan 20, 2025

ShellyGarion Jan 21, 2025

ElePT Jan 21, 2025

ShellyGarion Jan 20, 2025 •

edited

Loading

ShellyGarion Jan 21, 2025

t-imamichi commented Jan 21, 2025

ElePT left a comment

ElePT Jan 21, 2025

ShellyGarion Jan 21, 2025 •

edited

Loading

ShellyGarion Jan 23, 2025

ElePT Jan 24, 2025

ElePT Jan 21, 2025

ElePT Jan 21, 2025

ShellyGarion Jan 21, 2025

ElePT Jan 23, 2025

ElePT Jan 21, 2025

ShellyGarion commented Jan 23, 2025 •

edited

Loading

ElePT left a comment

ElePT Jan 24, 2025

ElePT Jan 24, 2025

	let test_angles = [0.2, 0.3, PI2];

	let scales: PyResult<Vec<f64>> = test_angles
	.into_iter()
	.map(\|test_angle\| {
	match &rxx_equivalent_gate {
	RXXEquivalent::Standard(gate) => {
	if gate.num_params() != 1 {
	return Err(QiskitError::new_err(
	"Equivalent gate needs to take exactly 1 angle parameter.",
	));
	}
	}
	RXXEquivalent::CustomPython(gate_cls) => {
	if gate_cls.bind(py).call1((test_angle,)).ok().is_none() {
	return Err(QiskitError::new_err(
	"Equivalent gate needs to take exactly 1 angle parameter.",
	));
	}
	}
	};
	let mat = rxx_equivalent_gate.matrix(py, test_angle)?;
	let decomp =
	TwoQubitWeylDecomposition::new_inner(mat.view(), Some(DEFAULT_FIDELITY), None)?;
	let mat_rxx = StandardGate::RXXGate
	.matrix(&[Param::Float(test_angle)])
	.unwrap();
	let decomposer_rxx = TwoQubitWeylDecomposition::new_inner(
	mat_rxx.view(),
	None,
	Some(Specialization::ControlledEquiv),
	)?;
	let decomposer_equiv = TwoQubitWeylDecomposition::new_inner(
	mat.view(),
	Some(DEFAULT_FIDELITY),
	Some(Specialization::ControlledEquiv),
	)?;
	let scale_a = decomposer_rxx.a / decomposer_equiv.a;
	if (decomp.a * 2.0 - test_angle / scale_a).abs() > atol {
	return Err(QiskitError::new_err(
	"The provided gate is not equivalent to an RXXGate.",
	));
	}
	Ok(scale_a)
	})
	.collect();

	backend = GenericBackendV2(3, basis_gates=basis_gates)
	backend = GenericBackendV2(3, basis_gates=basis_gates, seed=0)

Add 2q fractional gates to the UnitarySynthesis tranpiler pass #13568

Are you sure you want to change the base?

Add 2q fractional gates to the UnitarySynthesis tranpiler pass #13568

Conversation

ShellyGarion commented Dec 16, 2024

Summary

Details and comments

qiskit-bot commented Dec 16, 2024

coveralls commented Dec 16, 2024 • edited Loading

Pull Request Test Coverage Report for Build 12927458790

Details

💛 - Coveralls

ElePT left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ShellyGarion Dec 17, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ElePT Dec 18, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ShellyGarion Jan 20, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ShellyGarion Jan 20, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

t-imamichi commented Jan 21, 2025

ElePT left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ShellyGarion Jan 21, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ShellyGarion commented Jan 23, 2025 • edited Loading

ElePT left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Add 2q fractional gates to the `UnitarySynthesis` tranpiler pass #13568

Add 2q fractional gates to the `UnitarySynthesis` tranpiler pass #13568

coveralls commented Dec 16, 2024 •

edited

Loading

ShellyGarion Dec 17, 2024 •

edited

Loading

ElePT Dec 18, 2024 •

edited

Loading

ShellyGarion Jan 20, 2025 •

edited

Loading

ShellyGarion Jan 20, 2025 •

edited

Loading

ShellyGarion Jan 21, 2025 •

edited

Loading

ShellyGarion commented Jan 23, 2025 •

edited

Loading