Skip to content

Improve docstrings for controlled common gate overrides #3117

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 6 commits into from
Jul 6, 2020
Merged

Improve docstrings for controlled common gate overrides #3117

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
c159064
Better controlled override docstrings
dabacon Jul 1, 2020
7e745ef
cleanup
dabacon Jul 1, 2020
16f27f1
top string
dabacon Jul 6, 2020
63274a1
Merge branch 'master' into docstrings
dabacon Jul 6, 2020
b0150ae
typos
dabacon Jul 6, 2020
81b7bc8
Merge branch 'master' into docstrings
dabacon Jul 6, 2020
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
172 changes: 104 additions & 68 deletions cirq/ops/common_gates.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -122,23 +122,32 @@ def controlled(self,
control_qid_shape: Optional[Tuple[int, ...]] = None
) -> raw_types.Gate:
"""
Constructs CXPowGate from controlled XPowGate when applicable.

This method is a specialized controlled method for XPowGate. It
overrides the default behavior of returning a ControlledGate by
transforming the underlying controlled gate to a CXPowGate and
removing the last specified control qubit (which acts first
semantically). If this is a gate with multiple control qubits, it will
now be a ControlledGate with one less control.

This behavior only occurs when the last control qubit is a default-type
control qubit. A default-type control qubit is one with shape of 2 (not
a generic qudit) and where the control is satisfied by the qubit being
ON, as opposed to OFF. Note also that this only transforms into a
CXPowGate (or controlled version of that gate) if the global shift on
the XPowGate is 0, otherwise it produces a normal ControlledGate.

(Note that a CXPowGate is, by definition, a controlled-XPowGate.)
Returns a controlled `XPowGate`, using a `CXPowGate` where possible.

The `controlled` method of the `Gate` class, of which this class is a
child, returns a `ControlledGate`. This method overrides this behavior
to return a `CXPowGate` or a `ControlledGate` of a `CXPowGate`, when
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.

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
`ControlledGate` with the `Gate` being a `CXPowGate`. In the

This comment was marked as resolved.

Sign in to view

latter case the `ControlledGate` is controlled by one less qudit
than specified in `control_values` and `control_qid_shape` (since
one of these, the last qubit, is used as the control for the
`CXPowGate`).

If the above conditions are not met, a `ControlledGate` of this
gate will be returned.
"""
result = super().controlled(num_controls, control_values,
control_qid_shape)
Expand Down Expand Up @@ -443,23 +452,32 @@ def controlled(self,
control_qid_shape: Optional[Tuple[int, ...]] = None
) -> raw_types.Gate:
"""
Constructs CZPowGate from controlled ZPowGate when applicable.

This method is a specialized controlled method for ZPowGate. It
overrides the default behavior of returning a ControlledGate by
transforming the underlying controlled gate to a CZPowGate and
removing the last specified control qubit (which acts first
semantically). If this is a gate with multiple control qubits, it will
now be a ControlledGate with one less control.

This behavior only occurs when the last control qubit is a default-type
control qubit. A default-type control qubit is one with shape of 2 (not
a generic qudit) and where the control is satisfied by the qubit being
ON, as opposed to OFF. Note also that this only transforms into a
CZPowGate (or controlled version of that gate) if the global shift of
the ZPowGate is 0, otherwise it produces a normal ControlledGate.

(Note that a CZPowGate is, by definition, a controlled-ZPowGate.)
Returns a controlled `ZPowGate`, using a `CZPowGate` where possible.

The `controlled` method of the `Gate` class, of which this class is a
child, returns a `ControlledGate`. This method overrides this behavior
to return a `CZPowGate` or a `ControlledGate` of a `CZPowGate`, when

This comment was marked as resolved.

Sign in to view

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.

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
`ControlledGate` with the `Gate` being a `CZPowGate`. In the
latter case the `ControlledGate` is controlled by one less qudit
than specified in `control_values` and `control_qid_shape` (since
one of these, the last qubit, is used as the control for the
`CZPowGate`).

If the above conditions are not met, a `ControlledGate` of this
gate will be returned.
"""
result = super().controlled(num_controls, control_values,
control_qid_shape)
Expand Down Expand Up @@ -797,23 +815,32 @@ def controlled(self,
control_qid_shape: Optional[Tuple[int, ...]] = None
) -> raw_types.Gate:
"""
Constructs CCZPowGate from controlled CZPowGate when applicable.

This method is a specialized controlled method for CZPowGate. It
overrides the default behavior of returning a ControlledGate by
transforming the underlying controlled gate to a CCZPowGate and
removing the last specified control qubit (which acts first
semantically). If this is a gate with multiple control qubits, it will
now be a ControlledGate with one less control.

This behavior only occurs when the last control qubit is a default-type
control qubit. A default-type control qubit is one with shape of 2 (not
a generic qudit) and where the control is satisfied by the qubit being
ON, as opposed to OFF. Note also that this only transforms into a
CCZPowGate (or controlled version of that gate) if the global shift of
the CZPowGate is 0, otherwise it produces a normal ControlledGate.

(Note that a CCZPowGate is, by definition, a controlled-CZPowGate.)
Returns a controlled `CZPowGate`, using a `CCZPowGate` where possible.

The `controlled` method of the `Gate` class, of which this class is a
child, returns a `ControlledGate`. This method overrides this behavior
to return a `CCZPowGate` or a `ControlledGate` of a `CCZPowGate`, when
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.

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
`ControlledGate` with the `Gate` being a `CCZPowGate`. In the
latter case the `ControlledGate` is controlled by one less qudit
than specified in `control_values` and `control_qid_shape` (since
one of these, the last qubit, is used as the control for the
`CCZPowGate`).

If the above conditions are not met, a `ControlledGate` of this
gate will be returned.
"""
result = super().controlled(num_controls, control_values,
control_qid_shape)
Expand Down Expand Up @@ -966,23 +993,32 @@ def controlled(self,
control_qid_shape: Optional[Tuple[int, ...]] = None
) -> raw_types.Gate:
"""
Constructs CCXPowGate from controlled CXPowGate when applicable.

This method is a specialized controlled method for CXPowGate. It
overrides the default behavior of returning a ControlledGate by
transforming the underlying controlled gate to a CCXPowGate and
removing the last specified control qubit (which acts first
semantically). If this is a gate with multiple control qubits, it will
now be a ControlledGate with one less control.

This behavior only occurs when the last control qubit is a default-type
control qubit. A default-type control qubit is one with shape of 2 (not
a generic qudit) and where the control is satisfied by the qubit being
ON, as opposed to OFF. Note also that this only transforms into a
CCXPowGate (or controlled version of that gate) if the global shift of
the CXPowGate is 0, otherwise it produces a normal ControlledGate.

(Note that a CCXPowGate is, by definition, a controlled-CXPowGate.)
Returns a controlled `CXPowGate`, using a `CCXPowGate` where possible.

The `controlled` method of the `Gate` class, of which this class is a
child, returns a `ControlledGate`. This method overrides this behavior
to return a `CCXPowGate` or a `ControlledGate` of a `CCXPowGate`, when
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.

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
`ControlledGate` with the `Gate` being a `CCXPowGate`. In the

This comment was marked as resolved.

Sign in to view

latter case the `ControlledGate` is controlled by one less qudit
than specified in `control_values` and `control_qid_shape` (since
one of these, the last qubit, is used as the control for the
`CCXPowGate`).

If the above conditions are not met, a `ControlledGate` of this
gate will be returned.
"""
result = super().controlled(num_controls, control_values,
control_qid_shape)
Expand Down