Added U1, U2 and U3 deprecation warnings into Circuit Library (#8391)

* Added U1, U2 and U3 deprecation warnings in Circuit Library

* corrected parentheses and removed cdots

* Remove cdots

Co-authored-by: Julien Gacon <gaconju@gmail.com>

* moved formulas to examples

* Add linebreak

Co-authored-by: Julien Gacon <gaconju@gmail.com>

* Fix sphinx identifier

* corrected global phases

Co-authored-by: Julien Gacon <gaconju@gmail.com>
Co-authored-by: Luciano Bello <bel@zurich.ibm.com>
Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>

qiskit/circuit/library/standard_gates/u1.py

@@ -27,6 +27,22 @@ class U1Gate(Gate):
     This is a diagonal gate. It can be implemented virtually in hardware
     via framechanges (i.e. at zero error and duration).
 
+    .. warning::
+
+       This gate is deprecated. Instead, the following replacements should be used
+
+       .. math::
+
+           U1(\lambda) = P(\lambda)= U(0,0,\lambda)
+
+       .. code-block:: python
+
+          circuit = QuantumCircuit(1)
+          circuit.p(lambda, 0) # or circuit.u(0, 0, lambda)
+
+
+
+
     **Circuit symbol:**
 
     .. parsed-literal::

qiskit/circuit/library/standard_gates/u2.py

@@ -26,8 +26,20 @@ class U2Gate(Gate):
 
     Implemented using one X90 pulse on IBM Quantum systems:
 
-    .. math::
-        U2(\phi, \lambda) = RZ(\phi).RY(\frac{\pi}{2}).RZ(\lambda)
+    .. warning::
+
+       This gate is deprecated. Instead, the following replacements should be used
+
+       .. math::
+
+           U2(\phi, \lambda) = U\left(\frac{\pi}{2}, \phi, \lambda\right)
+
+       .. code-block:: python
+
+          circuit = QuantumCircuit(1)
+          circuit.u(pi/2, phi, lambda)
+
+
 
     **Circuit symbol:**
 
@@ -49,11 +61,25 @@ class U2Gate(Gate):
 
     **Examples:**
 
+    .. math::
+
+        U2(\phi,\lambda) = e^{i \frac{\phi + \lambda}{2}}RZ(\phi)
+        RY\left(\frac{\pi}{2}\right) RZ(\lambda)
+        = e^{- i\frac{\pi}{4}} P\left(\frac{\pi}{2} + \phi\right)
+        \sqrt{X} P\left(\lambda- \frac{\pi}{2}\right)
+
     .. math::
 
         U2(0, \pi) = H
+
+    .. math::
+
         U2(0, 0) = RY(\pi/2)
+
+    .. math::
+
         U2(-\pi/2, \pi/2) = RX(\pi/2)
+
     .. seealso::
 
         :class:`~qiskit.circuit.library.standard_gates.U3Gate`:

qiskit/circuit/library/standard_gates/u3.py

@@ -24,6 +24,19 @@
 class U3Gate(Gate):
     r"""Generic single-qubit rotation gate with 3 Euler angles.
 
+    .. warning::
+
+       This gate is deprecated. Instead, the following replacements should be used
+
+       .. math::
+
+           U3(\theta, \phi, \lambda) =  U(\theta, \phi, \lambda)
+
+       .. code-block:: python
+
+          circuit = QuantumCircuit(1)
+          circuit.u(theta, phi, lambda)
+
     **Circuit symbol:**
 
     .. parsed-literal::
@@ -52,6 +65,11 @@ class U3Gate(Gate):
 
     **Examples:**
 
+    .. math::
+
+        U3(\theta, \phi, \lambda) = e^{-i \frac{\pi + \theta}{2}} P(\phi + \pi) \sqrt{X}
+        P(\theta + \pi) \sqrt{X} P(\lambda)
+
     .. math::
 
         U3\left(\theta, -\frac{\pi}{2}, \frac{\pi}{2}\right) = RX(\theta)