diff --git a/cirq/ops/common_gates.py b/cirq/ops/common_gates.py index bbb7b630006..3b837b819a9 100644 --- a/cirq/ops/common_gates.py +++ b/cirq/ops/common_gates.py @@ -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 + 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) @@ -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 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) @@ -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) @@ -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 + 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)