Deprecate QuantumCircuit.u1/2/3

[Cryoris]

Summary

Continues on #4106.

Deprecate the methods u1, u2 and u3 of the circuit class. These gates are specific to the IBM hardware and are more commonly known as U-gate, instead of U3, and Phase-gate, instead of U1. The U2 gate has no standard equivalent but is easily created as special case of the U-gate. See below for a list of equivalences.

While the circuit methods are being deprecated the gate objects remain such that it is still possible to transpile down to U1/U2/U3 and retrieve old jobs that use these gates.

Details and comments

Equivalences of the circuit methods:

u1(lam) = p(lam)
u2(phi, lam) = u(phi, lam, pi/2)
u3(theta, phi, lam) = u(theta, phi, lam)

cu1(lam) = cp(lam)
cu3(theta, phi, lam) = cu(theta, phi, lam, 0)  # cu has a 4th parameter for the global phase of the controlled u-gate

mcu1(lam) = mcp(lam)

WIP because the tests still use the methods and are still being updated.

[nkanazawa1989]

Please keep a consistency with pulse builder module.
We can write pulse.u1 in the builder context (u2, u3 as well).
https://github.com/Qiskit/qiskit-terra/blob/56a42ce851d2f53cf88fec07d5460cd3c2a589e8/qiskit/pulse/builder.py#L1971-L2049

[ajavadia]

The reason U1/U2/U3 existed was to have gates corresponding to 0-pulse, 1-pulse, and 2-pulse single-qubit gates. So you have some sense of the cost associated with your circuit.

Now we can do this explicitly with Phase, sqrt(X) and U. So the replacements are:

U1(theta) ---> Phase(theta)  [0 pulse]
U2(phi, lam) ---> Phase(pi/2 + phi) -- sqrt(X) -- Phase(pi/2 + lam)   [1 pulse]
U3(theta, phi, lam)  ---> U(theta, phi, lam)  --->  Phase(phi) -- sqrt(X) -- Phase(theta) -- sqrt(X) -- Phase(lam)  [2 pulse]

Can you make sure to include these decompositions so people know how to transition while keeping the pulse numbers as they were?