Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 9 commits into from
Apr 26, 2022
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
391bfc5
initial work
dabacon Apr 7, 2022
b1fb0a6
Clean up single qubit docs, add gate zoo
dabacon Apr 12, 2022
8616aac
Merge branch 'master' into gatezoo
dabacon Apr 12, 2022
4bc6fb2
Fix format
dabacon Apr 12, 2022
6854411
line length
dabacon Apr 12, 2022
227e5d2
review comments
dabacon Apr 26, 2022
5a8a7fc
Merge master
dabacon Apr 26, 2022
804dda9
missing merges
dabacon Apr 26, 2022
785332a
format notebook
dabacon Apr 26, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
206 changes: 110 additions & 96 deletions cirq-core/cirq/ops/common_gates.py
View file
Open in desktop
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
Open in desktop
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
Open in desktop
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