From 7688adef6ffcea4f1d0f38ac495f4e9f3bf5a487 Mon Sep 17 00:00:00 2001 From: Orion Martin <40585662+95-martin-orion@users.noreply.github.com> Date: Mon, 11 Jul 2022 13:45:21 -0700 Subject: [PATCH 1/2] Minor improvements in common_gates docstrings --- cirq-core/cirq/ops/common_gates.py | 139 +++++++++++++++++++++++------ cirq-core/cirq/ops/raw_types.py | 6 +- 2 files changed, 116 insertions(+), 29 deletions(-) diff --git a/cirq-core/cirq/ops/common_gates.py b/cirq-core/cirq/ops/common_gates.py index b262f85b507..ff017dca30e 100644 --- a/cirq-core/cirq/ops/common_gates.py +++ b/cirq-core/cirq/ops/common_gates.py @@ -198,13 +198,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 @@ -216,6 +217,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 ( @@ -315,6 +332,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) @@ -489,6 +511,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) @@ -628,13 +655,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 @@ -646,6 +674,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 ( @@ -799,6 +843,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) @@ -1058,13 +1107,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 @@ -1076,6 +1126,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 ( @@ -1247,13 +1313,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 @@ -1265,6 +1332,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 ( diff --git a/cirq-core/cirq/ops/raw_types.py b/cirq-core/cirq/ops/raw_types.py index c1b8391c1c2..8ebcdcf83a7 100644 --- a/cirq-core/cirq/ops/raw_types.py +++ b/cirq-core/cirq/ops/raw_types.py @@ -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 @@ -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: From d401fa420384a2e41854edc90b34a4c0f486a307 Mon Sep 17 00:00:00 2001 From: Orion Martin <40585662+95-martin-orion@users.noreply.github.com> Date: Mon, 11 Jul 2022 14:04:48 -0700 Subject: [PATCH 2/2] no format-incremental in github.dev --- cirq-core/cirq/ops/common_gates.py | 8 ++++---- cirq-core/cirq/ops/raw_types.py | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/cirq-core/cirq/ops/common_gates.py b/cirq-core/cirq/ops/common_gates.py index ff017dca30e..634492f9b16 100644 --- a/cirq-core/cirq/ops/common_gates.py +++ b/cirq-core/cirq/ops/common_gates.py @@ -229,7 +229,7 @@ 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.ControlledGate` (or `cirq.CXPowGate` if possible) representing `self` controlled by the given control values and qubits. @@ -686,7 +686,7 @@ 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.ControlledGate` (or `cirq.CZPowGate` if possible) representing `self` controlled by the given control values and qubits. @@ -1138,7 +1138,7 @@ 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.ControlledGate` (or `cirq.CCZPowGate` if possible) representing `self` controlled by the given control values and qubits. @@ -1344,7 +1344,7 @@ 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.ControlledGate` (or `cirq.CCXPowGate` if possible) representing `self` controlled by the given control values and qubits. diff --git a/cirq-core/cirq/ops/raw_types.py b/cirq-core/cirq/ops/raw_types.py index 8ebcdcf83a7..eda6cf0a0b9 100644 --- a/cirq-core/cirq/ops/raw_types.py +++ b/cirq-core/cirq/ops/raw_types.py @@ -378,7 +378,7 @@ 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