Complete gate zoo and fix gate docs (quantumlib#5344)

Author: dabacon

cirq/ops/boolean_hamiltonian.py

@@ -16,7 +16,7 @@
 
 References:
 [1] On the representation of Boolean and real functions as Hamiltonians for quantum computing
-    by Stuart Hadfield, https://arxiv.org/pdf/1804.09130.pdf
+    by Stuart Hadfield, https://arxiv.org/abs/1804.09130
 [2] https://www.youtube.com/watch?v=AOKM9BkweVU is a useful intro
 [3] https://github.com/rsln-s/IEEE_QW_2020/blob/master/Slides.pdf
 [4] Efficient Quantum Circuits for Diagonal Unitaries Without Ancillas by Jonathan Welch, Daniel
@@ -36,7 +36,20 @@
 
 @value.value_equality
 class BooleanHamiltonianGate(raw_types.Gate):
-    """A gate that represents a Hamiltonian from a set of Boolean functions."""
+    r"""A gate that represents evolution due to a Hamiltonian from a set of Boolean functions.
+
+    This gate constructs a diagonal gate in the computational basis that encodes in its
+    phases classical functions.
+
+    The gate is specified by a list of parameters, $[x_0, x_1, \dots, x_{n-1}]$, a
+    list of boolean expressions that are functions of these parameters,
+    $[f_0(x_0,\dots,x_{n-1}), f_1(x_0,\dots,x_{n-1}), \dots f_{p-1}(x_0,\dots,x_{n-1})]$
+    and an angle $t$. For these parameters the gate is
+
+    $$
+    \sum_{x=0}^{2^n-1} e^{i \frac{t}{2} \sum_{k=0}^{p-1}f_k(x_0,\dots,x_{n-1})} |x\rangle\langle x|
+    $$
+    """
 
     def __init__(self, parameter_names: Sequence[str], boolean_strs: Sequence[str], theta: float):
         """Builds a BooleanHamiltonianGate.

cirq/ops/common_gates.py

@@ -906,18 +906,18 @@ def __repr__(self) -> str:
 
 
 class CZPowGate(gate_features.InterchangeableQubitsGate, eigen_gate.EigenGate):
-    """A gate that applies a phase to the |11⟩ state of two qubits.
+    r"""A gate that applies a phase to the |11⟩ state of two qubits.
 
     The unitary matrix of `CZPowGate(exponent=t)` is:
 
-        [[1, 0, 0, 0],
-         [0, 1, 0, 0],
-         [0, 0, 1, 0],
-         [0, 0, 0, g]]
-
-    where:
-
-        g = exp(i·π·t).
+    $$
+    \begin{bmatrix}
+        1 & 0 & 0 & 0 \\
+        0 & 1 & 0 & 0 \\
+        0 & 0 & 1 & 0 \\
+        0 & 0 & 0 & e^{i \pi t} \\
+    \end{bmatrix}
+    $$
 
     `cirq.CZ`, the controlled Z gate, is an instance of this gate at
     `exponent=1`.
@@ -1065,7 +1065,7 @@ def __repr__(self) -> str:
 
 
 class CXPowGate(eigen_gate.EigenGate):
-    """A gate that applies a controlled power of an X gate.
+    r"""A gate that applies a controlled power of an X gate.
 
     When applying CNOT (controlled-not) to qubits, you can either use
     positional arguments CNOT(q1, q2), where q2 is toggled when q1 is on,
@@ -1074,16 +1074,26 @@ class CXPowGate(eigen_gate.EigenGate):
 
     The unitary matrix of `cirq.CXPowGate(exponent=t)` is:
 
-        [[1, 0, 0, 0],
-         [0, 1, 0, 0],
-         [0, 0, g·c, -i·g·s],
-         [0, 0, -i·g·s, g·c]]
+    $$
+    \begin{bmatrix}
+        1 & 0 & 0 & 0 \\
+        0 & 1 & 0 & 0 \\
+        0 & 0 & g c & -i g s \\
+        0 & 0 & -i g s & g c
+    \end{bmatrix}
+    $$
 
     where:
 
-        c = cos(π·t/2)
-        s = sin(π·t/2)
-        g = exp(i·π·t/2).
+    $$
+    c = \cos\left(\frac{\pi t}{2}\right)
+    $$
+    $$
+    s = \sin\left(\frac{\pi t}{2}\right)
+    $$
+    $$
+    g = e^{\frac{i \pi t}{2}}
+    $$
 
     `cirq.CNOT`, the controlled NOT gate, is an instance of this gate at
     `exponent=1`.
@@ -1322,34 +1332,40 @@ def cphase(rads: value.TParamVal) -> CZPowGate:
 CZ = CZPowGate()
 document(
     CZ,
-    """The controlled Z gate.
+    r"""The controlled Z gate.
 
-    The `exponent=1` instance of `cirq.CZPowGate`.
+    This is the `exponent=1` instance of `cirq.CZPowGate`.
 
-    Matrix:
-    ```
-        [[1 . . .],
-         [. 1 . .],
-         [. . 1 .],
-         [. . . -1]]
-    ```
+    The unitary matrix of this gate is (empty elements are $0$):
+    $$
+        \begin{bmatrix}
+            1 & & & \\
+            & 1 & & \\
+            & & 1 & \\
+            & & & -1
+        \end{bmatrix}
+    $$
     """,
 )
 
 CNotPowGate = CXPowGate
 CNOT = CX = CNotPowGate()
 document(
     CNOT,
-    """The controlled NOT gate.
+    r"""The controlled NOT gate.
+
+    This is the `exponent=1` instance of `cirq.CXPowGate`.
 
-    The `exponent=1` instance of `cirq.CXPowGate`.
+    Alternative name: `cirq.CNOT`.
 
-    Matrix:
-    ```
-        [[1 . . .],
-         [. 1 . .],
-         [. . . 1],
-         [. . 1 .]]
-    ```
+    The unitary matrix of this gate is (empty elements are $0$):
+    $$
+        \begin{bmatrix}
+            1 & 0 & 0 & 0 \\
+            0 & 1 & 0 & 0 \\
+            0 & 0 & 0 & 1 \\
+            0 & 0 & 1 & 0
+        \end{bmatrix}
+    $$
     """,
 )

cirq/ops/dense_pauli_string.py

@@ -390,6 +390,21 @@ def copy(
 
 
 class DensePauliString(BaseDensePauliString):
+    """An immutable string of Paulis, like `XIXY`, with a coefficient.
+
+    This represents a Pauli operator acting on qubits.
+
+    For example, `cirq.MutableDensePauliString("XXY")` represents a
+    three qubit operation that acts with `X` on the first two qubits, and
+    `Y` on the last.
+
+    This can optionally take a coefficient, for example,
+    `cirq.MutableDensePauliString("XX", 3)`, which represents 3 times
+    the operator acting on X on two qubits.
+
+    If the coefficient has magnitude of 1, then this is also a `cirq.Gate`.
+    """
+
     def frozen(self) -> 'DensePauliString':
         return self
 
@@ -408,6 +423,21 @@ def copy(
 
 @value.value_equality(unhashable=True, approximate=True)
 class MutableDensePauliString(BaseDensePauliString):
+    """A mutable string of Paulis, like `XIXY`, with a coefficient.
+
+    This represents a Pauli operator acting on qubits.
+
+    For example, `cirq.MutableDensePauliString("XXY")` represents a
+    three qubit operation that acts with `X` on the first two qubits, and
+    `Y` on the last.
+
+    This can optionally take a coefficient, for example,
+    `cirq.MutableDensePauliString("XX", 3)`, which represents 3 times
+    the operator acting on X on two qubits.
+
+    If the coefficient has magnitude of 1, then this is also a `cirq.Gate`.
+    """
+
     def __setitem__(self, key, value):
         if isinstance(key, int):
             self.pauli_mask[key] = _pauli_index(value)

cirq/ops/diagonal_gate.py

@@ -64,12 +64,16 @@ def _gen_gray_code(n: int) -> Iterator[Tuple[int, int]]:
 
 @value.value_equality()
 class DiagonalGate(raw_types.Gate):
-    """A gate given by a diagonal (2^n)\\times(2^n) matrix."""
+    r"""An n qubit gate which acts as phases on computational basis states.
+
+    This gate's off-diagonal elements are zero and its on-diagonal elements are
+    all phases.
+    """
 
     def __init__(self, diag_angles_radians: Sequence['cirq.TParamVal']) -> None:
         r"""A n-qubit gate with only diagonal elements.
 
-        This gate's off-diagonal elements are zero and it's on diagonal
+        This gate's off-diagonal elements are zero and its on-diagonal
         elements are all phases.
 
         Args:

cirq/ops/fourier_transform.py

@@ -24,7 +24,19 @@
 
 @value.value_equality
 class QuantumFourierTransformGate(raw_types.Gate):
-    """Switches from the computational basis to the frequency basis."""
+    r"""Switches from the computational basis to the frequency basis.
+
+    This gate has the unitary
+
+    $$
+    \frac{1}{2^{n/2}}\sum_{x,y=0}^{2^n-1} \omega^{xy} |x\rangle\langle y|
+    $$
+
+    where
+    $$
+    \omega = e^{\frac{2\pi i}{2^n}}
+    $$
+    """
 
     def __init__(self, num_qubits: int, *, without_reverse: bool = False):
         """Inits QuantumFourierTransformGate.
@@ -86,7 +98,19 @@ def _circuit_diagram_info_(
 
 @value.value_equality
 class PhaseGradientGate(raw_types.Gate):
-    """Phases each state |k⟩ out of n by e^(2*pi*i*k/n*exponent)."""
+    r"""Phases all computational basis states proportional to the integer value of the state.
+
+    The gate `cirq.PhaseGradientGate(n, t)` has the unitary
+    $$
+    \sum_{x=0}^{2^n-1} \omega^x |x\rangle \langle x|
+    $$
+    where
+    $$
+    \omega=e^{2 \pi i/2^n}
+    $$
+
+    This gate makes up a portion of the quantum fourier transform.
+    """
 
     def __init__(self, *, num_qubits: int, exponent: Union[float, sympy.Basic]):
         self._num_qubits = num_qubits

cirq/ops/fsim_gate.py

@@ -54,28 +54,40 @@ def _half_pi_mod_pi(param: 'cirq.TParamVal') -> bool:
 
 @value.value_equality(approximate=True)
 class FSimGate(gate_features.InterchangeableQubitsGate, raw_types.Gate):
-    """Fermionic simulation gate family.
+    r"""Fermionic simulation gate family.
 
     Contains all two qubit interactions that preserve excitations, up to
     single-qubit rotations and global phase.
 
     The unitary matrix of this gate is:
 
-        [[1, 0, 0, 0],
-         [0, a, b, 0],
-         [0, b, a, 0],
-         [0, 0, 0, c]]
+    $$
+    \begin{bmatrix}
+        1 & 0 & 0 & 0 \\
+        0 & a & b & 0 \\
+        0 & b & a & 0 \\
+        0 & 0 & 0 & c
+    \end{bmatrix}
+    $$
 
     where:
 
-        a = cos(theta)
-        b = -i·sin(theta)
-        c = exp(-i·phi)
+    $$
+    a = \cos(\theta)
+    $$
+
+    $$
+    b = -i \sin(\theta)
+    $$
+
+    $$
+    c = e^{i \phi}
+    $$
 
     Note the difference in sign conventions between FSimGate and the
     ISWAP and CZPowGate:
 
-        FSimGate(θ, φ) = ISWAP**(-2θ/π) CZPowGate(exponent=-φ/π)
+    FSimGate(θ, φ) = ISWAP**(-2θ/π) CZPowGate(exponent=-φ/π)
     """
 
     def __init__(self, theta: 'cirq.TParamVal', phi: 'cirq.TParamVal') -> None:
@@ -202,20 +214,24 @@ def _json_dict_(self) -> Dict[str, Any]:
 
 @value.value_equality(approximate=True)
 class PhasedFSimGate(gate_features.InterchangeableQubitsGate, raw_types.Gate):
-    """General excitation-preserving two-qubit gate.
+    r"""General excitation-preserving two-qubit gate.
 
     The unitary matrix of PhasedFSimGate(θ, ζ, χ, γ, φ) is:
 
-        [[1,                       0,                       0,            0],
-         [0,    exp(-iγ - iζ) cos(θ), -i exp(-iγ + iχ) sin(θ),            0],
-         [0, -i exp(-iγ - iχ) sin(θ),    exp(-iγ + iζ) cos(θ),            0],
-         [0,                       0,                       0, exp(-2iγ-iφ)]].
+    $$
+    \begin{bmatrix}
+        1 & 0 & 0 & 0 \\
+        0 & e^{-i \gamma - i \zeta} & -i e^{-i \gamma + i\chi} & 0 \\
+        0 & -i e^{-i \gamma - i \chi} & e^{-i \gamma + i \zeta} & 0 \\
+        0 & 0 & 0 & e^{-2i \gamma - i \phi}
+    \end{bmatrix}
+    $$
 
     This parametrization follows eq (18) in https://arxiv.org/abs/2010.07965.
     See also eq (43) in https://arxiv.org/abs/1910.11333 for an older variant
-    which uses the same θ and φ parameters, but its three phase angles have
-    different names and opposite sign. Specifically, ∆+ angle corresponds to
-    -γ, ∆- corresponds to -ζ and ∆-,off corresponds to -χ.
+    which uses the same θ and φ parameters, but has three phase angles that
+    have different names and opposite sign. Specifically, ∆+ angle corresponds
+    to -γ, ∆- corresponds to -ζ and ∆-,off corresponds to -χ.
 
     Another useful parametrization of PhasedFSimGate is based on the fact that
     the gate is equivalent up to global phase to the following circuit:

cirq/ops/matrix_gates.py

@@ -37,7 +37,17 @@
 
 
 class MatrixGate(raw_types.Gate):
-    """A unitary qubit or qudit gate defined entirely by its matrix."""
+    r"""A unitary qubit or qudit gate defined entirely by its numpy matrix.
+
+    For example `cirq.MatrixGate(np.array([[0, 1j], [1, 0]]))` has the unitary matrix:
+
+    $$
+    \begin{bmatrix}
+        0 & i \\
+        1 & 0
+    \end{bmatrix}
+    $$
+    """
 
     def __init__(
         self,

cirq/ops/measurement_gate.py

@@ -29,6 +29,9 @@ class MeasurementGate(raw_types.Gate):
 
     The measurement gate contains a key that is used to identify results
     of measurements.
+
+    Instead of constructing this directly, consider using the `cirq.measure`
+    helper method.
     """
 
     def __init__(