Skip to content

Commit

Permalink
Improve common_gates docstrings (quantumlib#5722)
Browse files Browse the repository at this point in the history 
Bundle of minor fixes for docstrings in `common_gates.py`.
  • Loading branch information
@95-martin-orion @rht
95-martin-orion authored and rht committed May 1, 2023
1 parent 507057b commit a3d68e2
Show file tree
Hide file tree
Showing 2 changed files with 116 additions and 29 deletions.
139 changes: 111 additions & 28 deletions cirq-core/cirq/ops/common_gates.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -197,13 +197,14 @@ def controlled(
this is possible.
The conditions for the override to occur are:
* The `global_shift` of the `XPowGate` is 0.
* The `control_values` and `control_qid_shape` are compatible with
the `CXPowGate`:
* The last value of `control_qid_shape` is a qubit.
* The last value of `control_values` corresponds to the
control being satisfied if that last qubit is 1 and
not satisfied if the last qubit is 0.
* The `global_shift` of the `XPowGate` is 0.
* The `control_values` and `control_qid_shape` are compatible with
the `CXPowGate`:
* The last value of `control_qid_shape` is a qubit.
* The last value of `control_values` corresponds to the
control being satisfied if that last qubit is 1 and
not satisfied if the last qubit is 0.
If these conditions are met, then the returned object is a `CXPowGate`
or, in the case that there is more than one controlled qudit, a
Expand All @@ -215,6 +216,22 @@ def controlled(
If the above conditions are not met, a `ControlledGate` of this
gate will be returned.
Args:
num_controls: Total number of control qubits.
control_values: Which control computational basis state to apply the
sub gate. A sequence of length `num_controls` where each
entry is an integer (or set of integers) corresponding to the
computational basis state (or set of possible values) where that
control is enabled. When all controls are enabled, the sub gate is
applied. If unspecified, control values default to 1.
control_qid_shape: The qid shape of the controls. A tuple of the
expected dimension of each control qid. Defaults to
`(2,) * num_controls`. Specify this argument when using qudits.
Returns:
A `cirq.ControlledGate` (or `cirq.CXPowGate` if possible) representing
`self` controlled by the given control values and qubits.
"""
result = super().controlled(num_controls, control_values, control_qid_shape)
if (
Expand Down Expand Up @@ -309,6 +326,11 @@ class Rx(XPowGate):
"""

def __init__(self, *, rads: value.TParamVal):
"""Initialize an Rx (`cirq.XPowGate`).
Args:
rads: Radians to rotate about the X axis of the Bloch sphere.
"""
self._rads = rads
super().__init__(exponent=rads / _pi(rads), global_shift=-0.5)

Expand Down Expand Up @@ -478,6 +500,11 @@ class Ry(YPowGate):
"""

def __init__(self, *, rads: value.TParamVal):
"""Initialize an Ry (`cirq.YPowGate`).
Args:
rads: Radians to rotate about the Y axis of the Bloch sphere.
"""
self._rads = rads
super().__init__(exponent=rads / _pi(rads), global_shift=-0.5)

Expand Down Expand Up @@ -617,13 +644,14 @@ def controlled(
this is possible.
The conditions for the override to occur are:
* The `global_shift` of the `ZPowGate` is 0.
* The `control_values` and `control_qid_shape` are compatible with
the `CZPowGate`:
* The last value of `control_qid_shape` is a qubit.
* The last value of `control_values` corresponds to the
control being satisfied if that last qubit is 1 and
not satisfied if the last qubit is 0.
* The `global_shift` of the `ZPowGate` is 0.
* The `control_values` and `control_qid_shape` are compatible with
the `CZPowGate`:
* The last value of `control_qid_shape` is a qubit.
* The last value of `control_values` corresponds to the
control being satisfied if that last qubit is 1 and
not satisfied if the last qubit is 0.
If these conditions are met, then the returned object is a `CZPowGate`
or, in the case that there is more than one controlled qudit, a
Expand All @@ -635,6 +663,22 @@ def controlled(
If the above conditions are not met, a `ControlledGate` of this
gate will be returned.
Args:
num_controls: Total number of control qubits.
control_values: Which control computational basis state to apply the
sub gate. A sequence of length `num_controls` where each
entry is an integer (or set of integers) corresponding to the
computational basis state (or set of possible values) where that
control is enabled. When all controls are enabled, the sub gate is
applied. If unspecified, control values default to 1.
control_qid_shape: The qid shape of the controls. A tuple of the
expected dimension of each control qid. Defaults to
`(2,) * num_controls`. Specify this argument when using qudits.
Returns:
A `cirq.ControlledGate` (or `cirq.CZPowGate` if possible) representing
`self` controlled by the given control values and qubits.
"""
result = super().controlled(num_controls, control_values, control_qid_shape)
if (
Expand Down Expand Up @@ -783,6 +827,11 @@ class Rz(ZPowGate):
"""

def __init__(self, *, rads: value.TParamVal):
"""Initialize an Rz (`cirq.ZPowGate`).
Args:
rads: Radians to rotate about the Z axis of the Bloch sphere.
"""
self._rads = rads
super().__init__(exponent=rads / _pi(rads), global_shift=-0.5)

Expand Down Expand Up @@ -1031,13 +1080,14 @@ def controlled(
this is possible.
The conditions for the override to occur are:
* The `global_shift` of the `CZPowGate` is 0.
* The `control_values` and `control_qid_shape` are compatible with
the `CCZPowGate`:
* The last value of `control_qid_shape` is a qubit.
* The last value of `control_values` corresponds to the
control being satisfied if that last qubit is 1 and
not satisfied if the last qubit is 0.
* The `global_shift` of the `CZPowGate` is 0.
* The `control_values` and `control_qid_shape` are compatible with
the `CCZPowGate`:
* The last value of `control_qid_shape` is a qubit.
* The last value of `control_values` corresponds to the
control being satisfied if that last qubit is 1 and
not satisfied if the last qubit is 0.
If these conditions are met, then the returned object is a `CCZPowGate`
or, in the case that there is more than one controlled qudit, a
Expand All @@ -1049,6 +1099,22 @@ def controlled(
If the above conditions are not met, a `ControlledGate` of this
gate will be returned.
Args:
num_controls: Total number of control qubits.
control_values: Which control computational basis state to apply the
sub gate. A sequence of length `num_controls` where each
entry is an integer (or set of integers) corresponding to the
computational basis state (or set of possible values) where that
control is enabled. When all controls are enabled, the sub gate is
applied. If unspecified, control values default to 1.
control_qid_shape: The qid shape of the controls. A tuple of the
expected dimension of each control qid. Defaults to
`(2,) * num_controls`. Specify this argument when using qudits.
Returns:
A `cirq.ControlledGate` (or `cirq.CCZPowGate` if possible) representing
`self` controlled by the given control values and qubits.
"""
result = super().controlled(num_controls, control_values, control_qid_shape)
if (
Expand Down Expand Up @@ -1213,13 +1279,14 @@ def controlled(
this is possible.
The conditions for the override to occur are:
* The `global_shift` of the `CXPowGate` is 0.
* The `control_values` and `control_qid_shape` are compatible with
the `CCXPowGate`:
* The last value of `control_qid_shape` is a qubit.
* The last value of `control_values` corresponds to the
control being satisfied if that last qubit is 1 and
not satisfied if the last qubit is 0.
* The `global_shift` of the `CXPowGate` is 0.
* The `control_values` and `control_qid_shape` are compatible with
the `CCXPowGate`:
* The last value of `control_qid_shape` is a qubit.
* The last value of `control_values` corresponds to the
control being satisfied if that last qubit is 1 and
not satisfied if the last qubit is 0.
If these conditions are met, then the returned object is a `CCXPowGate`
or, in the case that there is more than one controlled qudit, a
Expand All @@ -1231,6 +1298,22 @@ def controlled(
If the above conditions are not met, a `ControlledGate` of this
gate will be returned.
Args:
num_controls: Total number of control qubits.
control_values: Which control computational basis state to apply the
sub gate. A sequence of length `num_controls` where each
entry is an integer (or set of integers) corresponding to the
computational basis state (or set of possible values) where that
control is enabled. When all controls are enabled, the sub gate is
applied. If unspecified, control values default to 1.
control_qid_shape: The qid shape of the controls. A tuple of the
expected dimension of each control qid. Defaults to
`(2,) * num_controls`. Specify this argument when using qudits.
Returns:
A `cirq.ControlledGate` (or `cirq.CCXPowGate` if possible) representing
`self` controlled by the given control values and qubits.
"""
result = super().controlled(num_controls, control_values, control_qid_shape)
if (
Expand Down
6 changes: 5 additions & 1 deletion cirq-core/cirq/ops/raw_types.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -367,7 +367,6 @@ def controlled(
"""Returns a controlled version of this gate. If no arguments are
specified, defaults to a single qubit control.
Args:
num_controls: Total number of control qubits.
control_values: Which control computational basis state to apply the
Expand All @@ -379,6 +378,11 @@ def controlled(
control_qid_shape: The qid shape of the controls. A tuple of the
expected dimension of each control qid. Defaults to
`(2,) * num_controls`. Specify this argument when using qudits.
Returns:
A `cirq.Gate` representing `self` controlled by the given control values
and qubits. This is a `cirq.ControlledGate` in the base
implementation, but subclasses may return a different gate type.
"""

if num_controls == 0:
Expand Down

0 comments on commit a3d68e2

Please sign in to comment.