Repository: Qiskit/qiskit

Issue:
u3 gate and global phase definition -  small inconsistency between matrix & gate defn.
<!-- ⚠️ If you do not respect this template, your issue will be closed -->
<!-- ⚠️ Make sure to browse the opened and closed issues to confirm this idea does not exist. -->

### What is the expected enhancement?

![image](https://user-images.githubusercontent.com/15937254/118651607-bb0aac80-b7b3-11eb-85e1-cf72aff09a3e.png)


The u3 gate as defined in terms of gates in its docstring,
$U3(\theta, \phi, \lambda) = RZ(\phi) RX(-\pi/2) RZ(\theta) RX(\pi/2) RZ(\lambda)$
and in terms of a matrix

    .. math::

        \newcommand{\th}{\frac{\theta}{2}}

        U3(\theta, \phi, \lambda) =
            \begin{pmatrix}
                \cos(\th)          & -e^{i\lambda}\sin(\th) \\
                e^{i\phi}\sin(\th) & e^{i(\phi+\lambda)}\cos(\th)
            \end{pmatrix}

does not appear to be consistent up to a global phase. The code representation uses the matrix form, but i think the gatedef uses the underlying gate form. 

Given the gate definition above, the relationship between the two is 
![image](https://user-images.githubusercontent.com/15937254/118651925-0b820a00-b7b4-11eb-8bf7-bc10d91a26c6.png)

I would suggest adding a note in the docstring about this for those who may get confused on the issue of phases and differences between the u and u3. 


Appendix:
![image](https://user-images.githubusercontent.com/15937254/118652081-366c5e00-b7b4-11eb-83cd-901f3e996e54.png)








Discussion:
Thanks @zlatko-minev , agree this is a bug in the documentation. The OpenQASM 2.0 doc uses `~` to denote equality up to a global phase, so maybe we can re-use that here with a note explaining the expected difference in global phase between a `U3` and it's implementation. 
Great, yes because I wonder if it then affects the controlled version of the gate? 

Sent from my iPhone

> On May 28, 2021, at 6:09 PM, Kevin Krsulich ***@***.***> wrote:
> 
> ﻿
> Thanks @zlatko-minev , agree this is a bug in the documentation. The OpenQASM 2.0 doc uses := to denote equality up to a global phase, so maybe we can re-use that here with a note explaining the expected difference in global phase between a U3 and it's implementation.
> 
> —
> You are receiving this because you were mentioned.
> Reply to this email directly, view it on GitHub, or unsubscribe.

I think the documentation and the actual matrix definition in the code should be exactly equal. 

For U this is correct:
<img width="411" alt="image" src="https://user-images.githubusercontent.com/8622381/122987298-70f68700-d36e-11eb-8239-cfe4f7b03efc.png">

For U3 this is correct:
<img width="389" alt="image" src="https://user-images.githubusercontent.com/8622381/122987475-a26f5280-d36e-11eb-8f62-46103fa360e4.png">

i.e. U3 =  U multiplied by a global phase of `exp(-(phi+lambda)/2)`
@ajavadia , right, you are correct. 

An enhancement for the beginner here could be to note that the sequence in the doc which states 
![image](https://user-images.githubusercontent.com/15937254/125827831-f5c800e0-dab4-4a63-9134-d3929e936bc1.png)
does not equal the matrix rep given below in the docs: 
![image](https://user-images.githubusercontent.com/15937254/125827861-4efe09d6-4e11-4eb1-ae62-01551112e51e.png)
but is instead only equal up to the global phase of  `exp(-(phi+lambda)/2)` as you say. 

For instance, it is not clear to me now, if the `to_matrix` method would include or not the global phase. This may matter if using it to construct a control operator I think from the matrix algebra. 
Hi, I've also run through this problem and have a few points to add:

1. I think that qiskit defines U3 and U as the same gate:
https://github.com/Qiskit/qiskit-terra/blob/265530145033bc31a92fc6989be1e5e20de92252/qiskit/circuit/library/standard_gates/u.py#L98-L110
https://github.com/Qiskit/qiskit-terra/blob/265530145033bc31a92fc6989be1e5e20de92252/qiskit/circuit/library/standard_gates/u3.py#L98-L110
The blocks above are the same - UGate and U3Gate have the same array.

2. u3 = U also in QASM:
https://github.com/Qiskit/qiskit-terra/blob/98130dd6158d1f1474e44dd5aeacbc619174ad63/qiskit/qasm/libs/qelib1.inc#L6-L7
However, this is different from the definition in [Qiskit/OpenQASM/examples/stdgates.inc](https://github.com/Qiskit/openqasm/blob/d4fae413cbb283faadd6226531c1e2f7ad0b04f1/examples/stdgates.inc#L75):
```gate u3(θ, φ, λ) q { gphase(-(φ+λ)/2); U(θ, φ, λ) q; }```

3. I agree with @zlatko-minev's last comment. The global phase is important in the case of a controlled operator, so it should be clear what is the exact definition of U3.
Thank you, @jond01 , this is well shown in your post. I would hope they are consistent as well to minimize down-the-road bugs in someone's code. 
This looks like it would be a simple fix. @ajavadia are we going to fix that for 0.20?

Resolving patch:
diff --git a/qiskit/circuit/library/standard_gates/u.py b/qiskit/circuit/library/standard_gates/u.py
--- a/qiskit/circuit/library/standard_gates/u.py
+++ b/qiskit/circuit/library/standard_gates/u.py
@@ -25,18 +25,6 @@
 class UGate(Gate):
     r"""Generic single-qubit rotation gate with 3 Euler angles.
 
-    Implemented using two X90 pulses on IBM Quantum systems:
-
-    .. math::
-        U(\theta, \phi, \lambda) =
-            RZ(\phi) RX(-\pi/2) RZ(\theta) RX(\pi/2) RZ(\lambda)
-
-    Equivalent simplified form:
-
-    .. math::
-        U(\theta, \phi, \lambda) =
-            RZ(\phi + \pi/2) RX(\theta) RZ(\lambda - \pi/2)
-
     **Circuit symbol:**
 
     .. parsed-literal::
@@ -57,6 +45,14 @@ class UGate(Gate):
                 e^{i\phi}\sin\left(\th\right) & e^{i(\phi+\lambda)}\cos\left(\th\right)
             \end{pmatrix}
 
+    .. note::
+
+        The matrix representation shown here is the same as in the `OpenQASM 3.0 specification
+        <https://openqasm.com/language/gates.html#built-in-gates>`_,
+        which differs from the `OpenQASM 2.0 specification
+        <https://doi.org/10.48550/arXiv.1707.03429>`_ by a global phase of
+        :math:`e^{i(\phi+\lambda)/2}`.
+
     **Examples:**
 
     .. math::
@@ -118,13 +114,12 @@ def control(
     def __array__(self, dtype=complex):
         """Return a numpy.array for the U gate."""
         theta, phi, lam = (float(param) for param in self.params)
+        cos = math.cos(theta / 2)
+        sin = math.sin(theta / 2)
         return numpy.array(
             [
-                [math.cos(theta / 2), -exp(1j * lam) * math.sin(theta / 2)],
-                [
-                    exp(1j * phi) * math.sin(theta / 2),
-                    exp(1j * (phi + lam)) * math.cos(theta / 2),
-                ],
+                [cos, -exp(1j * lam) * sin],
+                [exp(1j * phi) * sin, exp(1j * (phi + lam)) * cos],
             ],
             dtype=dtype,
         )
diff --git a/qiskit/circuit/library/standard_gates/u3.py b/qiskit/circuit/library/standard_gates/u3.py
--- a/qiskit/circuit/library/standard_gates/u3.py
+++ b/qiskit/circuit/library/standard_gates/u3.py
@@ -24,12 +24,6 @@
 class U3Gate(Gate):
     r"""Generic single-qubit rotation gate with 3 Euler angles.
 
-    Implemented using two X90 pulses on IBM Quantum systems:
-
-    .. math::
-        U3(\theta, \phi, \lambda) =
-            RZ(\phi) RX(-\pi/2) RZ(\theta) RX(\pi/2) RZ(\lambda)
-
     **Circuit symbol:**
 
     .. parsed-literal::
@@ -50,6 +44,12 @@ class U3Gate(Gate):
                 e^{i\phi}\sin\left(\th\right) & e^{i(\phi+\lambda)}\cos\left(\th\right)
             \end{pmatrix}
 
+    .. note::
+
+        The matrix representation shown here differs from the `OpenQASM 2.0 specification
+        <https://doi.org/10.48550/arXiv.1707.03429>`_ by a global phase of
+        :math:`e^{i(\phi+\lambda)/2}`.
+
     **Examples:**
 
     .. math::


Test patch: