Document dimension of X/ZPowGate (quantumlib#5648)

As advertised. Everything except the "dimension" part is copied from the EigenGate constructor docstring.

Also opened quantumlib#5647 for adding similar functionality + docs to YPowGate.

cirq-core/cirq/ops/common_gates.py

@@ -70,8 +70,9 @@ def _pi(rads):
 class XPowGate(eigen_gate.EigenGate):
     r"""A gate that rotates around the X axis of the Bloch sphere.
 
-    The unitary matrix of `cirq.XPowGate(exponent=t)` is:
+    The unitary matrix of `cirq.XPowGate(exponent=t, global_shift=s)` is:
     $$
+    e^{i \pi s t}
     \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)
@@ -92,6 +93,30 @@ class XPowGate(eigen_gate.EigenGate):
     def __init__(
         self, *, exponent: value.TParamVal = 1.0, global_shift: float = 0.0, dimension: int = 2
     ):
+        """Initialize an XPowGate.
+
+        Args:
+            exponent: The t in gate**t. Determines how much the eigenvalues of
+                the gate are phased by. For example, eigenvectors phased by -1
+                when `gate**1` is applied will gain a relative phase of
+                e^{i pi exponent} when `gate**exponent` is applied (relative to
+                eigenvectors unaffected by `gate**1`).
+            global_shift: Offsets the eigenvalues of the gate at exponent=1.
+                In effect, this controls a global phase factor on the gate's
+                unitary matrix. The factor for global_shift=s is:
+
+                    exp(i * pi * s * t)
+
+                For example, `cirq.X**t` uses a `global_shift` of 0 but
+                `cirq.rx(t)` uses a `global_shift` of -0.5, which is why
+                `cirq.unitary(cirq.rx(pi))` equals -iX instead of X.
+            dimension: Qudit dimension of this gate. For qu*b*its (the default),
+                this is set to 2.
+
+        Raises:
+            ValueError: If the supplied exponent is a complex number with an
+                imaginary component.
+        """
         super().__init__(exponent=exponent, global_shift=global_shift)
         self._dimension = dimension
 
@@ -503,8 +528,9 @@ def _from_json_dict_(cls, rads, **kwargs) -> 'Ry':
 class ZPowGate(eigen_gate.EigenGate):
     r"""A gate that rotates around the Z axis of the Bloch sphere.
 
-    The unitary matrix of `cirq.ZPowGate(exponent=t)` is:
+    The unitary matrix of `cirq.ZPowGate(exponent=t, global_shift=s)` is:
     $$
+        e^{i \pi s t}
         \begin{bmatrix}
             1 & 0 \\
             0 & e^{i \pi t}
@@ -525,6 +551,30 @@ class ZPowGate(eigen_gate.EigenGate):
     def __init__(
         self, *, exponent: value.TParamVal = 1.0, global_shift: float = 0.0, dimension: int = 2
     ):
+        """Initialize a ZPowGate.
+
+        Args:
+            exponent: The t in gate**t. Determines how much the eigenvalues of
+                the gate are phased by. For example, eigenvectors phased by -1
+                when `gate**1` is applied will gain a relative phase of
+                e^{i pi exponent} when `gate**exponent` is applied (relative to
+                eigenvectors unaffected by `gate**1`).
+            global_shift: Offsets the eigenvalues of the gate at exponent=1.
+                In effect, this controls a global phase factor on the gate's
+                unitary matrix. The factor for global_shift=s is:
+
+                    exp(i * pi * s * t)
+
+                For example, `cirq.X**t` uses a `global_shift` of 0 but
+                `cirq.rx(t)` uses a `global_shift` of -0.5, which is why
+                `cirq.unitary(cirq.rx(pi))` equals -iX instead of X.
+            dimension: Qudit dimension of this gate. For qu*b*its (the default),
+                this is set to 2.
+
+        Raises:
+            ValueError: If the supplied exponent is a complex number with an
+                imaginary component.
+        """
         super().__init__(exponent=exponent, global_shift=global_shift)
         self._dimension = dimension
 

cirq-core/cirq/ops/eigen_gate.py

@@ -99,7 +99,7 @@ def __init__(
 
         Args:
             exponent: The t in gate**t. Determines how much the eigenvalues of
-                the gate are scaled by. For example, eigenvectors phased by -1
+                the gate are phased by. For example, eigenvectors phased by -1
                 when `gate**1` is applied will gain a relative phase of
                 e^{i pi exponent} when `gate**exponent` is applied (relative to
                 eigenvectors unaffected by `gate**1`).