Fix one qubit gate docstrings to single standard, start gate zoo (quantumlib#5246)

This PR updates the doc strings for single qubit gates.  These gates now all render correctly on quantumai.google.  

* This moves over to using LaTeX for the documentation. In some cases this makes the code doc string less readable, in some case it makes it is more readable.  It renders nicely on quantumai.google

This also starts quantumlib#852 for single qubit gates. Adding two and higher qubit gates will come in a follow up PR assuming the pattern in this PR is good.

Author: dabacon

Diff for: cirq-core/cirq/ops/common_gates.py

@@ -68,26 +68,23 @@ def _pi(rads):
 
 @value.value_equality
 class XPowGate(eigen_gate.EigenGate):
-    """A gate that rotates around the X axis of the Bloch sphere.
+    r"""A gate that rotates around the X axis of the Bloch sphere.
 
-    The unitary matrix of ``XPowGate(exponent=t)`` is:
-
-        [[g·c, -i·g·s],
-         [-i·g·s, g·c]]
-
-    where:
-
-        c = cos(π·t/2)
-        s = sin(π·t/2)
-        g = exp(i·π·t/2).
+    The unitary matrix of `cirq.XPowGate(exponent=t)` is:
+    $$
+    \begin{bmatrix}
+      e^{i \pi t /2} \cos(\pi t) & -i e^{i \pi t /2} \sin(\pi t) \\
+      -i e^{i \pi t /2} \sin(\pi t) & e^{i \pi t /2} \cos(\pi t)
+    \end{bmatrix}
+    $$
 
     Note in particular that this gate has a global phase factor of
-    e^{i·π·t/2} vs the traditionally defined rotation matrices
-    about the Pauli X axis. See `cirq.rx` for rotations without the global
+    $e^{i \pi t / 2}$ vs the traditionally defined rotation matrices
+    about the Pauli X axis. See `cirq.Rx` for rotations without the global
     phase. The global phase factor can be adjusted by using the `global_shift`
     parameter when initializing.
 
-    `cirq.X`, the Pauli X gate, is an instance of this gate at exponent=1.
+    `cirq.X`, the Pauli X gate, is an instance of this gate at `exponent=1`.
     """
 
     def _num_qubits_(self) -> int:
@@ -245,14 +242,18 @@ def __repr__(self) -> str:
 
 
 class Rx(XPowGate):
-    """A gate, with matrix e^{-i X rads/2}, that rotates around the X axis of the Bloch sphere.
-
-    The unitary matrix of ``Rx(rads=t)`` is:
-
-    exp(-i X t/2) =  [ cos(t/2)  -isin(t/2)]
-                     [-isin(t/2)  cos(t/2) ]
-
-    The gate corresponds to the traditionally defined rotation matrices about the Pauli X axis.
+    r"""A gate with matrix $e^{-i X t/2}$ that rotates around the X axis of the Bloch sphere by $t$.
+
+    The unitary matrix of `cirq.Rx(rads=t)` is:
+    $$
+    e^{-i X t /2} =
+        \begin{bmatrix}
+            \cos(t/2) & -i \sin(t/2) \\
+            -i \sin(t/2) & \cos(t/2)
+        \end{bmatrix}
+    $$
+
+    This gate corresponds to the traditionally defined rotation matrices about the Pauli X axis.
     """
 
     def __init__(self, *, rads: value.TParamVal):
@@ -286,26 +287,23 @@ def _from_json_dict_(cls, rads, **kwargs) -> 'Rx':
 
 @value.value_equality
 class YPowGate(eigen_gate.EigenGate):
-    """A gate that rotates around the Y axis of the Bloch sphere.
-
-    The unitary matrix of ``YPowGate(exponent=t)`` is:
+    r"""A gate that rotates around the Y axis of the Bloch sphere.
 
-        [[g·c, -g·s],
-         [g·s, g·c]]
-
-    where:
-
-        c = cos(π·t/2)
-        s = sin(π·t/2)
-        g = exp(i·π·t/2).
+    The unitary matrix of `cirq.YPowGate(exponent=t)` is:
+    $$
+        \begin{bmatrix}
+            e^{i \pi t /2} \cos(\pi t /2) & - e^{i \pi t /2} \sin(\pi t /2) \\
+            e^{i \pi t /2} \sin(\pi t /2) & e^{i \pi t /2} \cos(\pi t /2)
+        \end{bmatrix}
+    $$
 
     Note in particular that this gate has a global phase factor of
-    e^{i·π·t/2} vs the traditionally defined rotation matrices
+    $e^{i \pi t / 2}$ vs the traditionally defined rotation matrices
     about the Pauli Y axis. See `cirq.Ry` for rotations without the global
     phase. The global phase factor can be adjusted by using the `global_shift`
     parameter when initializing.
 
-    `cirq.Y`, the Pauli Y gate, is an instance of this gate at exponent=1.
+    `cirq.Y`, the Pauli Y gate, is an instance of this gate at `exponent=1`.
     """
 
     def _num_qubits_(self) -> int:
@@ -416,14 +414,18 @@ def __repr__(self) -> str:
 
 
 class Ry(YPowGate):
-    """A gate, with matrix e^{-i Y rads/2}, that rotates around the Y axis of the Bloch sphere.
-
-    The unitary matrix of ``Ry(rads=t)`` is:
-
-    exp(-i Y t/2) =  [cos(t/2)  -sin(t/2)]
-                     [sin(t/2)  cos(t/2) ]
-
-    The gate corresponds to the traditionally defined rotation matrices about the Pauli Y axis.
+    r"""A gate with matrix $e^{-i Y t/2}$ that rotates around the Y axis of the Bloch sphere by $t$.
+
+    The unitary matrix of `cirq.Ry(rads=t)` is:
+    $$
+    e^{-i Y t / 2} =
+        \begin{bmatrix}
+            \cos(t/2) & -\sin(t/2) \\
+            \sin(t/2) & \cos(t/2)
+        \end{bmatrix}
+    $$
+
+    This gate corresponds to the traditionally defined rotation matrices about the Pauli Y axis.
     """
 
     def __init__(self, *, rads: value.TParamVal):
@@ -457,24 +459,23 @@ def _from_json_dict_(cls, rads, **kwargs) -> 'Ry':
 
 @value.value_equality
 class ZPowGate(eigen_gate.EigenGate):
-    """A gate that rotates around the Z axis of the Bloch sphere.
-
-    The unitary matrix of ``ZPowGate(exponent=t)`` is:
+    r"""A gate that rotates around the Z axis of the Bloch sphere.
 
-        [[1, 0],
-         [0, g]]
-
-    where:
-
-        g = exp(i·π·t).
+    The unitary matrix of `cirq.ZPowGate(exponent=t)` is:
+    $$
+        \begin{bmatrix}
+            1 & 0 \\
+            0 & e^{i \pi t}
+        \end{bmatrix}
+    $$
 
     Note in particular that this gate has a global phase factor of
-    e^{i·π·t/2} vs the traditionally defined rotation matrices
+    $e^{i\pi t/2}$ vs the traditionally defined rotation matrices
     about the Pauli Z axis. See `cirq.Rz` for rotations without the global
     phase. The global phase factor can be adjusted by using the `global_shift`
     parameter when initializing.
 
-    `cirq.Z`, the Pauli Z gate, is an instance of this gate at exponent=1.
+    `cirq.Z`, the Pauli Z gate, is an instance of this gate at `exponent=1`.
     """
 
     def _num_qubits_(self) -> int:
@@ -658,14 +659,18 @@ def _commutes_on_qids_(
 
 
 class Rz(ZPowGate):
-    """A gate, with matrix e^{-i Z rads/2}, that rotates around the Z axis of the Bloch sphere.
-
-    The unitary matrix of ``Rz(rads=t)`` is:
-
-    exp(-i Z t/2) =  [ e^(-it/2)     0   ]
-                     [    0      e^(it/2)]
-
-    The gate corresponds to the traditionally defined rotation matrices about the Pauli Z axis.
+    r"""A gate with matrix $e^{-i Z t/2}$ that rotates around the Z axis of the Bloch sphere by $t$.
+
+    The unitary matrix of `cirq.Rz(rads=t)` is:
+    $$
+    e^{-i Z t /2} =
+        \begin{bmatrix}
+            e^{-it/2} & 0 \\
+            0 & e^{it/2}
+        \end{bmatrix}
+    $$
+
+    This gate corresponds to the traditionally defined rotation matrices about the Pauli Z axis.
     """
 
     def __init__(self, *, rads: value.TParamVal):
@@ -698,20 +703,24 @@ def _from_json_dict_(cls, rads, **kwargs) -> 'Rz':
 
 
 class HPowGate(eigen_gate.EigenGate):
-    """A Gate that performs a rotation around the X+Z axis of the Bloch sphere.
-
-    The unitary matrix of ``HPowGate(exponent=t)`` is:
-
-        [[g·(c-i·s/sqrt(2)), -i·g·s/sqrt(2)],
-        [-i·g·s/sqrt(2)], g·(c+i·s/sqrt(2))]]
-
-    where
-
-        c = cos(π·t/2)
-        s = sin(π·t/2)
-        g = exp(i·π·t/2).
-
-    Note in particular that for `t=1`, this gives the Hadamard matrix.
+    r"""A Gate that performs a rotation around the X+Z axis of the Bloch sphere.
+
+    The unitary matrix of `cirq.HPowGate(exponent=t)` is:
+    $$
+        \begin{bmatrix}
+            e^{i\pi t/2} \left(\cos(\pi t/2) - i \frac{\sin (\pi t /2)}{\sqrt{2}}\right)
+                && -i e^{i\pi t/2} \frac{\sin(\pi t /2)}{\sqrt{2}} \\
+            -i e^{i\pi t/2} \frac{\sin(\pi t /2)}{\sqrt{2}}
+                && e^{i\pi t/2} \left(\cos(\pi t/2) + i \frac{\sin (\pi t /2)}{\sqrt{2}}\right)
+        \end{bmatrix}
+    $$
+    Note in particular that for $t=1$, this gives the Hadamard matrix
+    $$
+        \begin{bmatrix}
+            \frac{1}{\sqrt{2}} & \frac{1}{\sqrt{2}} \\
+            \frac{1}{\sqrt{2}} & -\frac{1}{\sqrt{2}}
+        \end{bmatrix}
+    $$
 
     `cirq.H`, the Hadamard gate, is an instance of this gate at `exponent=1`.
     """
@@ -1001,7 +1010,7 @@ class CXPowGate(eigen_gate.EigenGate):
     or named arguments CNOT(control=q1, target=q2).
     (Mixing the two is not permitted.)
 
-    The unitary matrix of `CXPowGate(exponent=t)` is:
+    The unitary matrix of `cirq.CXPowGate(exponent=t)` is:
 
         [[1, 0, 0, 0],
          [0, 1, 0, 0],
@@ -1197,46 +1206,51 @@ def cphase(rads: value.TParamVal) -> CZPowGate:
 H = HPowGate()
 document(
     H,
-    """The Hadamard gate.
+    r"""The Hadamard gate.
 
     The `exponent=1` instance of `cirq.HPowGate`.
 
-    Matrix:
-    ```
-        [[s, s],
-         [s, -s]]
-    ```
-        where s = sqrt(0.5).
+    The unitary matrix of `cirq.H` is:
+    $$
+    \begin{bmatrix}
+        \frac{1}{\sqrt{2}} & \frac{1}{\sqrt{2}} \\
+        \frac{1}{\sqrt{2}} & -\frac{1}{\sqrt{2}}
+    \end{bmatrix}
+    $$
     """,
 )
 
 S = ZPowGate(exponent=0.5)
 document(
     S,
-    """The Clifford S gate.
+    r"""The Clifford S gate.
 
     The `exponent=0.5` instance of `cirq.ZPowGate`.
 
-    Matrix:
-    ```
-        [[1, 0],
-         [0, i]]
-    ```
+    The unitary matrix of `cirq.S` is:
+    $$
+    \begin{bmatrix}
+        1 & 0 \\
+        0 & i
+    \end{bmatrix}
+    $$
     """,
 )
 
 T = ZPowGate(exponent=0.25)
 document(
     T,
-    """The non-Clifford T gate.
+    r"""The non-Clifford T gate.
 
     The `exponent=0.25` instance of `cirq.ZPowGate`.
 
-    Matrix:
-    ```
-        [[1, 0]
-         [0, exp(i pi / 4)]]
-    ```
+    The unitary matrix of `cirq.T` is
+    $$
+    \begin{bmatrix}
+        1 & 0 \\
+        0 & e^{i \pi /4}
+    \end{bmatrix}
+    $$
     """,
 )
 

Diff for: cirq-core/cirq/ops/pauli_gates.py

@@ -182,36 +182,51 @@ def basis(self: '_PauliZ') -> Dict[int, '_ZEigenState']:
 X = _PauliX()
 document(
     X,
-    """The Pauli X gate.
+    r"""The Pauli X gate.
 
-    Matrix:
+    This is the `exponent=1` instance of the `cirq.XPowGate`.
 
-        [[0, 1],
-         [1, 0]]
+    The untary matrix of `cirq.X` is:
+    $$
+    \begin{bmatrix}
+        0 & 1 \\
+        1 & 0
+    \end{bmatrix}
+    $$
     """,
 )
 
 Y = _PauliY()
 document(
     Y,
-    """The Pauli Y gate.
+    r"""The Pauli Y gate.
 
-    Matrix:
+    This is the `exponent=1` instance of the `cirq.YPowGate`.
 
-        [[0, -i],
-         [i, 0]]
+    The unitary matrix of `cirq.Y` is:
+    $$
+    \begin{bmatrix}
+        0 & -i \\
+        i & 0
+    \end{bmatrix}
+    $$
     """,
 )
 
 Z = _PauliZ()
 document(
     Z,
-    """The Pauli Z gate.
+    r"""The Pauli Z gate.
 
-    Matrix:
+    This is the `exponent=1` instance of the `cirq.ZPowGate`.
 
-        [[1, 0],
-         [0, -1]]
+    The unitary matrix of `cirq.Z` is:
+    $$
+    \begin{bmatrix}
+        1 & 0 \\
+        0 & -1
+    \end{bmatrix}
+    $$
     """,
 )
 

Diff for: cirq-core/cirq/ops/phased_x_gate.py

@@ -27,7 +27,21 @@
 
 @value.value_equality(manual_cls=True, approximate=True)
 class PhasedXPowGate(raw_types.Gate):
-    """A gate equivalent to the circuit ───Z^-p───X^t───Z^p───."""
+    r"""A gate equivalent to $Z^{p} X^t Z^{-p}$.
+
+    The unitary matrix of `cirq.PhasedXPowGate(exponent=t, phase_exponent=p)` is:
+    $$
+        \begin{bmatrix}
+            e^{i \pi t /2} \cos(\pi t/2) & -i e^{i \pi (t /2 - p)} \sin(\pi t /2) \\
+            -i e^{i \pi (t /2 + p)} \sin(\pi t /2) & e^{i \pi t /2} \cos(\pi t/2)
+        \end{bmatrix}
+    $$
+
+    This gate is like an `cirq.XPowGate`, but which has been "phased",
+    by applying a `cirq.ZPowGate` before and after this gate. In the language
+    of the Bloch sphere, $p$ determines the axis in the XY plane about which
+    a rotation of amount determined by $t$ occurs.
+    """
 
     def __init__(
         self,