Move on_each to Gate, and deprecate SupportsOnEachGate (#4303)

Part of #4034. (See #4034 (comment)), moves the on_each functionality to cirq.Gate, and deprecates SupportsOnEachGate.

Note the tests that are deleted here had already been duplicated in raw_types_test.py by https://github.com/quantumlib/Cirq/pull/4281/files.

Author: daxfohl

cirq-core/cirq/ops/common_channels.py

@@ -246,7 +246,7 @@ def asymmetric_depolarize(
 
 
 @value.value_equality
-class DepolarizingChannel(gate_features.SupportsOnEachGate, raw_types.Gate):
+class DepolarizingChannel(raw_types.Gate):
     """A channel that depolarizes one or several qubits."""
 
     def __init__(self, p: float, n_qubits: int = 1) -> None:

cirq-core/cirq/ops/gate_features.py

@@ -18,8 +18,9 @@
 """
 
 import abc
-from typing import Union, Iterable, Any, List, Sequence
 
+from cirq import value, ops
+from cirq._compat import deprecated_class
 from cirq.ops import raw_types
 
 
@@ -31,57 +32,23 @@ def qubit_index_to_equivalence_group_key(self, index: int) -> int:
         return 0
 
 
-class SupportsOnEachGate(raw_types.Gate, metaclass=abc.ABCMeta):
-    """A gate that can be applied to exactly one qubit."""
-
-    def on_each(self, *targets: Union[raw_types.Qid, Iterable[Any]]) -> List[raw_types.Operation]:
-        """Returns a list of operations applying the gate to all targets.
-        Args:
-            *targets: The qubits to apply this gate to. For single-qubit gates
-            this can be provided as varargs or a combination of nested
-            iterables. For multi-qubit gates this must be provided as an
-            `Iterable[Sequence[Qid]]`, where each sequence has `num_qubits`
-            qubits.
-        Returns:
-            Operations applying this gate to the target qubits.
-        Raises:
-            ValueError if targets are not instances of Qid or Iterable[Qid].
-            ValueError if the gate qubit number is incompatible.
-        """
-        operations: List[raw_types.Operation] = []
-        if self._num_qubits_() > 1:
-            iterator: Iterable = targets
-            if len(targets) == 1:
-                if not isinstance(targets[0], Iterable):
-                    raise TypeError(f'{targets[0]} object is not iterable.')
-                t0 = list(targets[0])
-                iterator = [t0] if t0 and isinstance(t0[0], raw_types.Qid) else t0
-            for target in iterator:
-                if not isinstance(target, Sequence):
-                    raise ValueError(
-                        f'Inputs to multi-qubit gates must be Sequence[Qid].'
-                        f' Type: {type(target)}'
-                    )
-                if not all(isinstance(x, raw_types.Qid) for x in target):
-                    raise ValueError(f'All values in sequence should be Qids, but got {target}')
-                if len(target) != self._num_qubits_():
-                    raise ValueError(f'Expected {self._num_qubits_()} qubits, got {target}')
-                operations.append(self.on(*target))
-            return operations
-
-        for target in targets:
-            if isinstance(target, raw_types.Qid):
-                operations.append(self.on(target))
-            elif isinstance(target, Iterable) and not isinstance(target, str):
-                operations.extend(self.on_each(*target))
-            else:
-                raise ValueError(
-                    f'Gate was called with type different than Qid. Type: {type(target)}'
-                )
-        return operations
-
-
-class SingleQubitGate(SupportsOnEachGate, metaclass=abc.ABCMeta):
+class _SupportsOnEachGateMeta(value.ABCMetaImplementAnyOneOf):
+    def __instancecheck__(cls, instance):
+        return isinstance(instance, (SingleQubitGate, ops.DepolarizingChannel)) or issubclass(
+            type(instance), SupportsOnEachGate
+        )
+
+
+@deprecated_class(
+    deadline='v0.14',
+    fix='Remove `SupportsOnEachGate` from the list of parent classes. '
+    '`on_each` is now directly supported in the `Gate` base class.',
+)
+class SupportsOnEachGate(raw_types.Gate, metaclass=_SupportsOnEachGateMeta):
+    pass
+
+
+class SingleQubitGate(raw_types.Gate, metaclass=abc.ABCMeta):
     """A gate that must be applied to exactly one qubit."""
 
     def _num_qubits_(self) -> int:

cirq-core/cirq/ops/gate_features_test.py

@@ -12,12 +12,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from collections.abc import Iterator
-from typing import Any
-
 import pytest
 
 import cirq
+from cirq.testing import assert_deprecated
 
 
 def test_single_qubit_gate_validate_args():
@@ -137,41 +135,6 @@ def matrix(self):
         g.validate_args([a, b, c, d])
 
 
-def test_on_each():
-    class CustomGate(cirq.SingleQubitGate):
-        pass
-
-    a = cirq.NamedQubit('a')
-    b = cirq.NamedQubit('b')
-    c = CustomGate()
-
-    assert c.on_each() == []
-    assert c.on_each(a) == [c(a)]
-    assert c.on_each(a, b) == [c(a), c(b)]
-    assert c.on_each(b, a) == [c(b), c(a)]
-
-    assert c.on_each([]) == []
-    assert c.on_each([a]) == [c(a)]
-    assert c.on_each([a, b]) == [c(a), c(b)]
-    assert c.on_each([b, a]) == [c(b), c(a)]
-    assert c.on_each([a, [b, a], b]) == [c(a), c(b), c(a), c(b)]
-
-    with pytest.raises(ValueError):
-        c.on_each('abcd')
-    with pytest.raises(ValueError):
-        c.on_each(['abcd'])
-    with pytest.raises(ValueError):
-        c.on_each([a, 'abcd'])
-
-    def iterator(qubits):
-        for i in range(len(qubits)):
-            yield qubits[i]
-
-    qubit_iterator = iterator([a, b, a, b])
-    assert isinstance(qubit_iterator, Iterator)
-    assert c.on_each(qubit_iterator) == [c(a), c(b), c(a), c(b)]
-
-
 def test_qasm_output_args_validate():
     args = cirq.QasmArgs(version='2.0')
     args.validate_version('2.0')
@@ -231,16 +194,40 @@ def __init__(self, num_qubits):
         g.validate_args([a, b, c, d])
 
 
-def test_on_each_iterable_qid():
-    class QidIter(cirq.Qid):
-        @property
-        def dimension(self) -> int:
-            return 2
+def test_supports_on_each_inheritance_shim():
+    class NotOnEach(cirq.Gate):
+        def num_qubits(self):
+            return 1  # coverage: ignore
+
+    class OnEach(cirq.ops.gate_features.SupportsOnEachGate):
+        def num_qubits(self):
+            return 1  # coverage: ignore
+
+    class SingleQ(cirq.SingleQubitGate):
+        pass
+
+    class TwoQ(cirq.TwoQubitGate):
+        pass
+
+    not_on_each = NotOnEach()
+    single_q = SingleQ()
+    two_q = TwoQ()
+    with assert_deprecated(deadline="v0.14"):
+        on_each = OnEach()
+
+    assert not isinstance(not_on_each, cirq.ops.gate_features.SupportsOnEachGate)
+    assert isinstance(on_each, cirq.ops.gate_features.SupportsOnEachGate)
+    assert isinstance(single_q, cirq.ops.gate_features.SupportsOnEachGate)
+    assert not isinstance(two_q, cirq.ops.gate_features.SupportsOnEachGate)
+    assert isinstance(cirq.X, cirq.ops.gate_features.SupportsOnEachGate)
+    assert not isinstance(cirq.CX, cirq.ops.gate_features.SupportsOnEachGate)
+    assert isinstance(cirq.DepolarizingChannel(0.01), cirq.ops.gate_features.SupportsOnEachGate)
 
-        def _comparison_key(self) -> Any:
-            return 1
 
-        def __iter__(self):
-            raise NotImplementedError()
+def test_supports_on_each_deprecation():
+    class CustomGate(cirq.ops.gate_features.SupportsOnEachGate):
+        def num_qubits(self):
+            return 1  # coverage: ignore
 
-    assert cirq.H.on_each(QidIter())[0] == cirq.H.on(QidIter())
+    with assert_deprecated(deadline="v0.14"):
+        assert isinstance(CustomGate(), cirq.ops.gate_features.SupportsOnEachGate)

cirq-core/cirq/ops/identity.py

@@ -20,14 +20,14 @@
 
 from cirq import protocols, value
 from cirq._doc import document
-from cirq.ops import gate_features, raw_types
+from cirq.ops import raw_types
 
 if TYPE_CHECKING:
     import cirq
 
 
 @value.value_equality
-class IdentityGate(gate_features.SupportsOnEachGate, raw_types.Gate):
+class IdentityGate(raw_types.Gate):
     """A Gate that perform no operation on qubits.
 
     The unitary matrix of this gate is a diagonal matrix with all 1s on the

cirq-core/cirq/ops/raw_types.py

@@ -23,6 +23,8 @@
     Collection,
     Dict,
     Hashable,
+    Iterable,
+    List,
     Optional,
     Sequence,
     Tuple,
@@ -211,6 +213,52 @@ def on(self, *qubits: Qid) -> 'Operation':
 
         return gate_operation.GateOperation(self, list(qubits))
 
+    def on_each(self, *targets: Union[Qid, Iterable[Any]]) -> List['cirq.Operation']:
+        """Returns a list of operations applying the gate to all targets.
+        Args:
+            *targets: The qubits to apply this gate to. For single-qubit gates
+            this can be provided as varargs or a combination of nested
+            iterables. For multi-qubit gates this must be provided as an
+            `Iterable[Sequence[Qid]]`, where each sequence has `num_qubits`
+            qubits.
+        Returns:
+            Operations applying this gate to the target qubits.
+        Raises:
+            ValueError if targets are not instances of Qid or Iterable[Qid].
+            ValueError if the gate qubit number is incompatible.
+        """
+        operations: List['cirq.Operation'] = []
+        if self._num_qubits_() > 1:
+            iterator: Iterable = targets
+            if len(targets) == 1:
+                if not isinstance(targets[0], Iterable):
+                    raise TypeError(f'{targets[0]} object is not iterable.')
+                t0 = list(targets[0])
+                iterator = [t0] if t0 and isinstance(t0[0], Qid) else t0
+            for target in iterator:
+                if not isinstance(target, Sequence):
+                    raise ValueError(
+                        f'Inputs to multi-qubit gates must be Sequence[Qid].'
+                        f' Type: {type(target)}'
+                    )
+                if not all(isinstance(x, Qid) for x in target):
+                    raise ValueError(f'All values in sequence should be Qids, but got {target}')
+                if len(target) != self._num_qubits_():
+                    raise ValueError(f'Expected {self._num_qubits_()} qubits, got {target}')
+                operations.append(self.on(*target))
+            return operations
+
+        for target in targets:
+            if isinstance(target, Qid):
+                operations.append(self.on(target))
+            elif isinstance(target, Iterable) and not isinstance(target, str):
+                operations.extend(self.on_each(*target))
+            else:
+                raise ValueError(
+                    f'Gate was called with type different than Qid. Type: {type(target)}'
+                )
+        return operations
+
     def wrap_in_linear_combination(
         self, coefficient: Union[complex, float, int] = 1
     ) -> 'cirq.LinearCombinationOfGates':

cirq-core/cirq/ops/raw_types_test.py

@@ -801,7 +801,7 @@ class CustomGate(cirq.SingleQubitGate):
 
 
 def test_on_each_two_qubits():
-    class CustomGate(cirq.ops.gate_features.SupportsOnEachGate, cirq.TwoQubitGate):
+    class CustomGate(cirq.TwoQubitGate):
         pass
 
     a = cirq.NamedQubit('a')
@@ -855,7 +855,7 @@ class CustomGate(cirq.ops.gate_features.SupportsOnEachGate, cirq.TwoQubitGate):
 
 
 def test_on_each_three_qubits():
-    class CustomGate(cirq.ops.gate_features.SupportsOnEachGate, cirq.ThreeQubitGate):
+    class CustomGate(cirq.ThreeQubitGate):
         pass
 
     a = cirq.NamedQubit('a')