Skip to content

Commit

Permalink
Fix one qubit gate docstrings to single standard, start gate zoo (qua…
Browse files Browse the repository at this point in the history 
…ntumlib#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.
  • Loading branch information
@dabacon @rht
dabacon authored and rht committed May 1, 2023
1 parent 81c4c6f commit b9d5fa6
Show file tree
Hide file tree
Showing 5 changed files with 380 additions and 115 deletions.
206 changes: 110 additions & 96 deletions cirq-core/cirq/ops/common_gates.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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):
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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):
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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):
Expand Down Expand Up @@ -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`.
"""
Expand Down Expand Up @@ -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],
Expand Down Expand Up @@ -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}
$$
""",
)

Expand Down
39 changes: 27 additions & 12 deletions cirq-core/cirq/ops/pauli_gates.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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}
$$
""",
)

Expand Down
16 changes: 15 additions & 1 deletion cirq-core/cirq/ops/phased_x_gate.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
Loading

0 comments on commit b9d5fa6

Please sign in to comment.