Skip to content

Improve common_gates docstrings #5722

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 4 commits into from
Jul 11, 2022
Merged

Improve common_gates docstrings #5722

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
7688ade
Minor improvements in common_gates docstrings
95-martin-orion Jul 11, 2022
d401fa4
no format-incremental in github.dev
95-martin-orion Jul 11, 2022
c41eeb6
Merge branch 'master' into common-gate-polish
CirqBot Jul 11, 2022
7cc830f
Merge branch 'master' into common-gate-polish
dabacon Jul 11, 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
139 changes: 111 additions & 28 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 @@ -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
Open in desktop
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