Document dimension of X/ZPowGate

cirq-core/cirq/ops/common_gates.py

@@ -92,6 +92,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 scaled 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 is:
+
+                    exp(i * pi * global_shift * exponent)
+
+                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
 
@@ -523,6 +547,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 scaled 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 is:
+
+                    exp(i * pi * global_shift * exponent)
+
+                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