Simpler definitions for standard gates #14180

alexanderivrii · 2025-04-06T04:21:31Z

Summary

This PR slightly modernizes the definitions for standard gates:

By using discrete gates instead of parametric gates whenever possible. For example, instances of U1(-pi/4) have been replaced by Tdg(), instances of RZ(pi/2) have been replaced by S() with an update to the global phase, and so on.
The only definition that changed substantially is the one for ECRGate, following Jake's basis-constructor. In particular, ECR is now defined using 1 rather than 4 CX-gates.
U1 gates are replaced by Phase gates, U2 and U3 gates are replaced by U gates, CU1 gates.

This is in the spirit of Jake's "complexity" classes for standard gates (Paulis < 1q Cliffords < 1q Cliffords + T/Tdg < parametric 1q gates). In particular, the definitions for Clifford standard gates are now in terms of simpler Clifford gates (e.g. for RC3X).

Update 1: Apparently we have CI tests that Rust-side definitions are essentially the same as Python-side definitions, so I have also changed the Python-side definitions.

Update 2: Apparently we have CI tests that Python-side definitions are included into the equivalence library, so some of the equivalences in the equivalence library are now updated (and in some cases a new equivalence is added).

Details and comments

Question: can we eventually change the Python-side definitions to just return Rust-based definitions?

Question: are there potential problems with backward compatibility? Personally I think that we should be free to change definitions / synthesis methods and always aim to provide the best decompositions available, however what if there are users that expect that a definition for the ECRGate will contain a pair of RZX gates?

qiskit-bot · 2025-04-06T04:21:35Z

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

@Qiskit/terra-core

ShellyGarion · 2025-04-06T04:34:42Z

Since U1Gate is going to be deprecated sometime, it's better to use PhaseGate instead of U1Gate and CPhaseGate instead of CU1Gate (these gates have exactly the same definition), see e.g.#12977.

We have explicit Rust tests that make sure that Python-side and Rust-side definitions are identical.

qiskit/circuit/_add_control.py

crates/circuit/src/operations.rs

test/python/circuit/test_rust_equivalence.py

test/python/qasm3/test_export.py

coveralls · 2025-04-07T12:25:25Z

Pull Request Test Coverage Report for Build 15296780896

Details

182 of 182 (100.0%) changed or added relevant lines in 29 files are covered.
15 unchanged lines in 5 files lost coverage.
Overall coverage decreased (-0.05%) to 87.807%

Files with Coverage Reduction	New Missed Lines	%
crates/qasm2/src/expr.rs	1	94.23%
qiskit/circuit/_add_control.py	1	97.08%
crates/circuit/src/symbol_expr.rs	3	75.16%
crates/qasm2/src/lex.rs	4	91.98%
crates/qasm2/src/parse.rs	6	97.61%

Totals
Change from base Build 15296293022:	-0.05%
Covered Lines:	79457
Relevant Lines:	90491

💛 - Coveralls

…finitions for SX and SXdg in Rust

We can have a subclass of say XGate that sets _standard_gate = None, yet we expect the definition of XGate

crates/circuit/src/operations.rs

ShellyGarion

Looks great! thanks for doing all this effort!
I have a few minor comments.

crates/circuit/src/operations.rs

qiskit/circuit/library/standard_gates/r.py

qiskit/circuit/library/standard_gates/ecr.py

ShellyGarion · 2025-04-27T10:16:01Z

qiskit/circuit/library/standard_gates/rx.py

+        # q_0: ───────■───────────────────■───────────────────
+        #      ┌───┐┌─┴─┐┌─────────────┐┌─┴─┐┌───────────────┐
+        # q_1: ┤ S ├┤ X ├┤ U(-θ/2,0,0) ├┤ X ├┤ U(θ/2,-π/2,0) ├
+        #      └───┘└───┘└─────────────┘└───┘└───────────────┘


perhaps this definition could be simplified? I will look into it

the equivalence library also has this definition:

# CRXGate # # q_0: ────■──── q_0: ───────■────────────────■──────────────────── # ┌───┴───┐ ≡ ┌───┐┌─┴─┐┌──────────┐┌─┴─┐┌─────────┐┌─────┐ # q_1: ┤ Rx(ϴ) ├ q_1: ┤ S ├┤ X ├┤ Ry(-ϴ/2) ├┤ X ├┤ Ry(ϴ/2) ├┤ Sdg ├ # └───────┘ └───┘└───┘└──────────┘└───┘└─────────┘└─────┘

Good point, this definition is a bit simpler and a bit more powerful than the other one (in the sense that is uses single-parameter RY-gates instead of the more general U-gates). I will update the (default) definition.

In the above picture it still uses U and not Ry (but the definition should be correct now?)

ShellyGarion · 2025-04-27T10:19:08Z

qiskit/circuit/library/standard_gates/x.py

-        self.definition = qc
+        self.definition = QuantumCircuit._from_circuit_data(
+            StandardGate.C3SX._get_definition(self.params), add_regs=True, name=self.name
+        )


maybe add an image of the circuit?

The definitions for the 3-controlled circuits are quite large and don't git on a single page. This is why I have provided the definitions for almost all circuits but not the very large ones.

ShellyGarion · 2025-04-27T10:19:37Z

qiskit/circuit/library/standard_gates/x.py

-        self.definition = qc
+        self.definition = QuantumCircuit._from_circuit_data(
+            StandardGate.C3X._get_definition(self.params), add_regs=True, name=self.name
+        )


maybe add an image of the circuit?

Please see the answer above.

ShellyGarion · 2025-04-27T10:19:56Z

qiskit/circuit/library/standard_gates/x.py

-        self.definition = qc
+        self.definition = QuantumCircuit._from_circuit_data(
+            StandardGate.RC3X._get_definition(self.params), add_regs=True, name=self.name
+        )


maybe add an image of the circuit?

Please see the answer above.

ShellyGarion · 2025-04-27T10:20:29Z

qiskit/circuit/library/standard_gates/x.py


+        # This is not a standard gate in Rust


maybe add an image of the circuit?

Please see the answer above.

alexanderivrii · 2025-05-25T12:10:05Z

Thanks @ShellyGarion, I have addressed your comments modulo adding images for circuits with many gates: such circuits do not nicely fit on one screen and (imho) are not very illuminating. Can you please take another look?

ShellyGarion

Amazing work! A few last comments and I think it's ready to go.

ShellyGarion · 2025-05-27T14:12:08Z

qiskit/circuit/library/standard_gates/rx.py

+        # q_0: ───────■───────────────────■───────────────────
+        #      ┌───┐┌─┴─┐┌─────────────┐┌─┴─┐┌───────────────┐
+        # q_1: ┤ S ├┤ X ├┤ U(-θ/2,0,0) ├┤ X ├┤ U(θ/2,-π/2,0) ├
+        #      └───┘└───┘└─────────────┘└───┘└───────────────┘


In the above picture it still uses U and not Ry (but the definition should be correct now?)

ShellyGarion · 2025-05-27T14:16:52Z

releasenotes/notes/improve-standard-gate-definitions-1be3d27996cf15b6.yaml

+    * When available, a definition using Clifford gates is preferred over
+      one that includes non-Clifford gates.
+    * The use of ``PhaseGate`` is preferred over ``U1Gate``.
+    * The use of ``UGate`` is preferred over ``U3Gate``.


also over U2Gate, right?

Also using T/Tdg is preferable over PhaseGate

…ition

ShellyGarion

LGTM. tnx!

* ECR * CRX * CS * CSdg * CSX * RYY * XX-YY * XX+YY * RCCX * RC3X * Changing Python-side definitions as well. We have explicit Rust tests that make sure that Python-side and Rust-side definitions are identical. * u1 -> phase, cu1 -> cphase, etc. * lint * fixing tests * Bug fix * undoing changes to a test * remove stray prints and blank lines * reno * docs * Replacing Python definition by Rust definition; fixing problematic definitions for SX and SXdg in Rust * updating python definitions We can have a subclass of say XGate that sets _standard_gate = None, yet we expect the definition of XGate * Adding visualization for definition circuits * addressing review comments * improving release notes * Changing the picture for RCX gate to be consistent with the new definition * improving release notes

alexanderivrii added 10 commits April 5, 2025 09:19

ECR

5a6ead5

CRX

a02601c

CS

ae47dee

CSdg

a059b3d

CSX

1501947

RYY

e8db857

XX-YY

96af96a

XX+YY

5773fe7

RCCX

4c70e24

RC3X

72f7ddd

alexanderivrii requested a review from a team as a code owner April 6, 2025 04:21

alexanderivrii added this to the 2.1.0 milestone Apr 6, 2025

alexanderivrii added 6 commits April 6, 2025 11:04

Changing Python-side definitions as well.

bebbb41

We have explicit Rust tests that make sure that Python-side and Rust-side definitions are identical.

u1 -> phase, cu1 -> cphase, etc.

cbbb732

lint

36b7573

fixing tests

c72bb69

Bug fix

f397e4e

undoing changes to a test

4adcd3a

alexanderivrii commented Apr 6, 2025

View reviewed changes

qiskit/circuit/_add_control.py Show resolved Hide resolved

alexanderivrii commented Apr 6, 2025

View reviewed changes

crates/circuit/src/operations.rs Show resolved Hide resolved

alexanderivrii commented Apr 6, 2025

View reviewed changes

test/python/circuit/test_rust_equivalence.py Show resolved Hide resolved

remove stray prints and blank lines

8f1e1db

alexanderivrii commented Apr 6, 2025

View reviewed changes

test/python/qasm3/test_export.py Show resolved Hide resolved

alexanderivrii added 2 commits April 6, 2025 16:39

reno

d9c7b55

docs

31ef546

alexanderivrii added 2 commits April 19, 2025 13:09

Replacing Python definition by Rust definition; fixing problematic de…

75b7c74

…finitions for SX and SXdg in Rust

updating python definitions

4590692

We can have a subclass of say XGate that sets _standard_gate = None, yet we expect the definition of XGate

Adding visualization for definition circuits

9b6449f

alexanderivrii commented Apr 19, 2025

View reviewed changes

crates/circuit/src/operations.rs Show resolved Hide resolved

alexanderivrii mentioned this pull request Apr 20, 2025

Clifford+T transpiler pipeline #14225

Merged

eliarbel assigned ShellyGarion Apr 21, 2025

ShellyGarion reviewed Apr 27, 2025

View reviewed changes

ShellyGarion mentioned this pull request Apr 27, 2025

Porting some of the MCX synthesis methods to Rust #13929

Merged

alexanderivrii added 3 commits May 25, 2025 13:37

Merge branch 'main' into simpler-defs

625bd28

addressing review comments

b63f5aa

improving release notes

9647605

alexanderivrii requested a review from ShellyGarion May 25, 2025 12:08

ShellyGarion reviewed May 27, 2025

View reviewed changes

alexanderivrii added 3 commits May 28, 2025 12:16

Merge branch 'main' into simpler-defs

8c01539

Changing the picture for RCX gate to be consistent with the new defin…

a2d1dda

…ition

improving release notes

613d03a

alexanderivrii requested a review from ShellyGarion May 28, 2025 09:37

ShellyGarion approved these changes May 28, 2025

View reviewed changes

ShellyGarion added this pull request to the merge queue May 28, 2025

ShellyGarion added Changelog: New Feature Include in the "Added" section of the changelog mod: circuit Related to the core of the `QuantumCircuit` class or the circuit library labels May 28, 2025

Merged via the queue into Qiskit:main with commit 1cbef64 May 28, 2025
26 checks passed

mtreinish mentioned this pull request Jun 11, 2025

FoldRzzGate does not work properly with XXPlusYYGate Qiskit/qiskit-ibm-runtime#2256

Open

Simpler definitions for standard gates #14180

Simpler definitions for standard gates #14180

Uh oh!

Conversation

alexanderivrii commented Apr 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Details and comments

Uh oh!

qiskit-bot commented Apr 6, 2025

Uh oh!

ShellyGarion commented Apr 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

coveralls commented Apr 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull Request Test Coverage Report for Build 15296780896

Details

💛 - Coveralls

Uh oh!

Uh oh!

ShellyGarion left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

alexanderivrii May 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

alexanderivrii commented May 25, 2025

Uh oh!

ShellyGarion left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ShellyGarion left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

alexanderivrii commented Apr 6, 2025 •

edited

Loading

ShellyGarion commented Apr 6, 2025 •

edited

Loading

coveralls commented Apr 7, 2025 •

edited

Loading

alexanderivrii May 25, 2025 •

edited

Loading