Rename _channel_ to _kraus_ (#4139)

Author: viathor

cirq-core/cirq/ops/common_channels.py

@@ -454,7 +454,7 @@ def __init__(self, p: float, gamma: float) -> None:
         self._gamma = value.validate_probability(gamma, 'gamma')
         self._p = value.validate_probability(p, 'p')
 
-    def _channel_(self) -> Iterable[np.ndarray]:
+    def _kraus_(self) -> Iterable[np.ndarray]:
         p0 = np.sqrt(self._p)
         p1 = np.sqrt(1.0 - self._p)
         sqrt_g = np.sqrt(self._gamma)
@@ -466,7 +466,7 @@ def _channel_(self) -> Iterable[np.ndarray]:
             p1 * np.array([[0.0, 0.0], [sqrt_g, 0.0]]),
         )
 
-    def _has_channel_(self) -> bool:
+    def _has_kraus_(self) -> bool:
         return True
 
     def _value_equality_values_(self):
@@ -597,12 +597,12 @@ def __init__(self, gamma: float) -> None:
         self._gamma = value.validate_probability(gamma, 'gamma')
         self._delegate = GeneralizedAmplitudeDampingChannel(1.0, self._gamma)
 
-    def _channel_(self) -> Iterable[np.ndarray]:
+    def _kraus_(self) -> Iterable[np.ndarray]:
         # just return first two kraus ops, we don't care about
         # the last two.
-        return list(self._delegate._channel_())[:2]
+        return list(self._delegate._kraus_())[:2]
 
-    def _has_channel_(self) -> bool:
+    def _has_kraus_(self) -> bool:
         return True
 
     def _value_equality_values_(self):
@@ -750,13 +750,13 @@ def _act_on_(self, args: Any):
 
         return NotImplemented
 
-    def _channel_(self) -> Iterable[np.ndarray]:
+    def _kraus_(self) -> Iterable[np.ndarray]:
         # The first axis is over the list of channel matrices
         channel = np.zeros((self._dimension,) * 3, dtype=np.complex64)
         channel[:, 0, :] = np.eye(self._dimension)
         return channel
 
-    def _has_channel_(self) -> bool:
+    def _has_kraus_(self) -> bool:
         return True
 
     def _value_equality_values_(self):
@@ -831,13 +831,13 @@ def __init__(self, gamma: float) -> None:
         """
         self._gamma = value.validate_probability(gamma, 'gamma')
 
-    def _channel_(self) -> Iterable[np.ndarray]:
+    def _kraus_(self) -> Iterable[np.ndarray]:
         return (
             np.array([[1.0, 0.0], [0.0, np.sqrt(1.0 - self._gamma)]]),
             np.array([[0.0, 0.0], [0.0, np.sqrt(self._gamma)]]),
         )
 
-    def _has_channel_(self) -> bool:
+    def _has_kraus_(self) -> bool:
         return True
 
     def _value_equality_values_(self):

cirq-core/cirq/ops/gate_operation.py

@@ -197,14 +197,14 @@ def _mixture_(self) -> Sequence[Tuple[float, Any]]:
             return getter()
         return NotImplemented
 
-    def _has_channel_(self) -> bool:
-        getter = getattr(self.gate, '_has_channel_', None)
+    def _has_kraus_(self) -> bool:
+        getter = getattr(self.gate, '_has_kraus_', None)
         if getter is not None:
             return getter()
         return NotImplemented
 
-    def _channel_(self) -> Union[Tuple[np.ndarray], NotImplementedType]:
-        getter = getattr(self.gate, '_channel_', None)
+    def _kraus_(self) -> Union[Tuple[np.ndarray], NotImplementedType]:
+        getter = getattr(self.gate, '_kraus_', None)
         if getter is not None:
             return getter()
         return NotImplemented

cirq-core/cirq/ops/measurement_gate.py

@@ -125,7 +125,7 @@ def full_invert_mask(self):
     def _measurement_key_(self):
         return self.key
 
-    def _channel_(self):
+    def _kraus_(self):
         size = np.prod(self._qid_shape, dtype=int)
 
         def delta(i):
@@ -135,7 +135,7 @@ def delta(i):
 
         return tuple(delta(i) for i in range(size))
 
-    def _has_channel_(self):
+    def _has_kraus_(self):
         return True
 
     def _circuit_diagram_info_(

cirq-core/cirq/ops/random_gate_channel.py

@@ -56,7 +56,7 @@ def _has_unitary_(self):
     def _has_mixture_(self):
         return not self._is_parameterized_() and protocols.has_mixture(self.sub_gate)
 
-    def _has_channel_(self):
+    def _has_kraus_(self):
         return not self._is_parameterized_() and protocols.has_channel(self.sub_gate)
 
     def _is_parameterized_(self) -> bool:
@@ -90,7 +90,7 @@ def _mixture_(self):
         result.append((1 - float(self.probability), do_nothing))
         return result
 
-    def _channel_(self):
+    def _kraus_(self):
         if self._is_parameterized_():
             return NotImplemented
 

cirq-core/cirq/ops/raw_types.py

@@ -655,10 +655,10 @@ def _has_mixture_(self) -> bool:
     def _mixture_(self) -> Sequence[Tuple[float, Any]]:
         return protocols.mixture(self.sub_operation, NotImplemented)
 
-    def _has_channel_(self) -> bool:
+    def _has_kraus_(self) -> bool:
         return protocols.has_channel(self.sub_operation)
 
-    def _channel_(self) -> Union[Tuple[np.ndarray], NotImplementedType]:
+    def _kraus_(self) -> Union[Tuple[np.ndarray], NotImplementedType]:
         return protocols.channel(self.sub_operation, NotImplemented)
 
     def _measurement_key_(self) -> str:

cirq-core/cirq/protocols/apply_channel_protocol.py

@@ -256,7 +256,7 @@ def err_str(buf_num_str):
     if result is not None:
         return result
 
-    # Fallback to using the object's `_channel_` matrices.
+    # Fallback to using the object's `_kraus_` matrices.
     kraus = channel(val, None)
     if kraus is not None:
         return _apply_kraus(kraus, args)
@@ -266,7 +266,7 @@ def err_str(buf_num_str):
         return default
     raise TypeError(
         "object of type '{}' has no _apply_channel_, _apply_unitary_, "
-        "_unitary_, or _channel_ methods (or they returned None or "
+        "_unitary_, or _kraus_ methods (or they returned None or "
         "NotImplemented).".format(type(val))
     )
 

cirq-core/cirq/protocols/apply_channel_protocol_test.py

@@ -143,7 +143,7 @@ def test_apply_channel_channel_fallback_simple():
     x = np.array([[0, 1], [1, 0]], dtype=np.complex128)
 
     class HasChannel:
-        def _channel_(self):
+        def _kraus_(self):
             return (np.sqrt(0.5) * np.eye(2, dtype=np.complex128), np.sqrt(0.5) * x)
 
     rho = np.copy(x)
@@ -161,7 +161,7 @@ def test_apply_channel_channel_fallback_one_qubit_random_on_qubit():
         expected = 0.5 * rho + 0.5 * np.dot(np.dot(u, rho), np.conjugate(np.transpose(u)))
 
         class HasChannel:
-            def _channel_(self):
+            def _kraus_(self):
                 return (np.sqrt(0.5) * np.eye(2, dtype=np.complex128), np.sqrt(0.5) * u)
 
         result = apply_channel(HasChannel(), rho, [0], [1], assert_result_is_out_buf=True)
@@ -183,7 +183,7 @@ def test_apply_channel_channel_fallback_one_qubit_random_on_two_qubits():
         expected.shape = (2, 2, 2, 2)
 
         class HasChannel:
-            def _channel_(self):
+            def _kraus_(self):
                 return (np.sqrt(0.5) * np.eye(2, dtype=np.complex128), np.sqrt(0.5) * u)
 
         result = apply_channel(HasChannel(), rho, [0], [2], assert_result_is_out_buf=True)
@@ -204,7 +204,7 @@ def test_apply_channel_channel_fallback_two_qubit_random():
         expected.shape = (2, 2, 2, 2)
 
         class HasChannel:
-            def _channel_(self):
+            def _kraus_(self):
                 return (np.sqrt(0.5) * np.eye(4, dtype=np.complex128), np.sqrt(0.5) * u)
 
         result = apply_channel(HasChannel(), rho, [0, 1], [2, 3], assert_result_is_out_buf=True)

cirq-core/cirq/protocols/channel.py

@@ -15,7 +15,7 @@
 """Protocol and methods for quantum channels."""
 
 from typing import Any, Sequence, Tuple, TypeVar, Union
-
+import warnings
 
 import numpy as np
 from typing_extensions import Protocol
@@ -45,8 +45,8 @@ class SupportsChannel(Protocol):
     """An object that may be describable as a quantum channel."""
 
     @doc_private
-    def _channel_(self) -> Union[Sequence[np.ndarray], NotImplementedType]:
-        r"""A list of matrices describing the quantum channel.
+    def _kraus_(self) -> Union[Sequence[np.ndarray], NotImplementedType]:
+        r"""A list of Kraus matrices describing the quantum channel.
 
         These matrices are the terms in the operator sum representation of a
         quantum channel. If the returned matrices are ${A_0,A_1,..., A_{r-1}}$,
@@ -81,8 +81,8 @@ def _channel_(self) -> Union[Sequence[np.ndarray], NotImplementedType]:
         """
 
     @doc_private
-    def _has_channel_(self) -> bool:
-        """Whether this value has a channel representation.
+    def _has_kraus_(self) -> bool:
+        """Whether this value has a Kraus representation.
 
         This method is used by the global `cirq.has_channel` method.  If this
         method is not present, or returns NotImplemented, it will fallback
@@ -121,7 +121,7 @@ def channel(
             default is set to a value, that value is returned.
 
     Returns:
-        If `val` has a `_channel_` method and its result is not NotImplemented,
+        If `val` has a `_kraus_` method and its result is not NotImplemented,
         that result is returned. Otherwise, if `val` has a `_mixture_` method
         and its results is not NotImplement a tuple made up of channel
         corresponding to that mixture being a probabilistic mixture of unitaries
@@ -131,14 +131,21 @@ def channel(
         value is returned.
 
     Raises:
-        TypeError: `val` doesn't have a _channel_ or _unitary_ method (or that
+        TypeError: `val` doesn't have a _kraus_ or _unitary_ method (or that
             method returned NotImplemented) and also no default value was
             specified.
     """
     channel_getter = getattr(val, '_channel_', None)
-    channel_result = NotImplemented if channel_getter is None else channel_getter()
-    if channel_result is not NotImplemented:
-        return tuple(channel_result)
+    if channel_getter is not None:
+        warnings.warn(
+            '_channel_ is deprecated and will be removed in cirq 0.13, rename to _kraus_',
+            DeprecationWarning,
+        )
+
+    kraus_getter = getattr(val, '_kraus_', None)
+    kraus_result = NotImplemented if kraus_getter is None else kraus_getter()
+    if kraus_result is not NotImplemented:
+        return tuple(kraus_result)
 
     mixture_getter = getattr(val, '_mixture_', None)
     mixture_result = NotImplemented if mixture_getter is None else mixture_getter()
@@ -150,16 +157,21 @@ def channel(
     if unitary_result is not NotImplemented and unitary_result is not None:
         return (unitary_result,)
 
+    channel_result = NotImplemented if channel_getter is None else channel_getter()
+    if channel_result is not NotImplemented:
+        return tuple(channel_result)
+
     if default is not RaiseTypeErrorIfNotProvided:
         return default
 
-    if channel_getter is None and unitary_getter is None and mixture_getter is None:
+    if kraus_getter is None and unitary_getter is None and mixture_getter is None:
         raise TypeError(
-            "object of type '{}' has no _channel_ or _mixture_ or "
+            "object of type '{}' has no _kraus_ or _mixture_ or "
             "_unitary_ method.".format(type(val))
         )
+
     raise TypeError(
-        "object of type '{}' does have a _channel_, _mixture_ or "
+        "object of type '{}' does have a _kraus_, _mixture_ or "
         "_unitary_ method, but it returned NotImplemented.".format(type(val))
     )
 
@@ -178,29 +190,39 @@ def has_channel(val: Any, *, allow_decompose: bool = True) -> bool:
             the result is skipped.
 
     Returns:
-        If `val` has a `_has_channel_` method and its result is not
+        If `val` has a `_has_kraus_` method and its result is not
         NotImplemented, that result is returned. Otherwise, if `val` has a
         `_has_mixture_` method and its result is not NotImplemented, that
         result is returned. Otherwise if `val` has a `_has_unitary_` method
         and its results is not NotImplemented, that result is returned.
-        Otherwise, if the value has a _channel_ method return if that
+        Otherwise, if the value has a _kraus_ method return if that
         has a non-default value. Returns False if none of these functions
         exists.
     """
     channel_getter = getattr(val, '_has_channel_', None)
-    result = NotImplemented if channel_getter is None else channel_getter()
+    if channel_getter is not None:
+        warnings.warn(
+            '_has_channel_ is deprecated and will be removed in cirq 0.13, rename to _has_kraus_',
+            DeprecationWarning,
+        )
 
+    kraus_getter = getattr(val, '_has_kraus_', None)
+    result = NotImplemented if kraus_getter is None else kraus_getter()
     if result is not NotImplemented:
         return result
 
     result = has_mixture(val, allow_decompose=False)
     if result is not NotImplemented and result:
         return result
 
+    result = NotImplemented if channel_getter is None else channel_getter()
+    if result is not NotImplemented:
+        return result
+
     if allow_decompose:
         operations, _, _ = _try_decompose_into_operations_and_qubits(val)
         if operations is not None:
             return all(has_channel(val) for val in operations)
 
-    # No has methods, use `_channel_` or delegates instead.
+    # No has methods, use `_kraus_` or delegates instead.
     return channel(val, None) is not None

cirq-core/cirq/protocols/channel_test.py

@@ -29,7 +29,7 @@ def test_channel_no_methods():
     class NoMethod:
         pass
 
-    with pytest.raises(TypeError, match='no _channel_ or _mixture_ or _unitary_ method'):
+    with pytest.raises(TypeError, match='no _kraus_ or _mixture_ or _unitary_ method'):
         _ = cirq.channel(NoMethod())
 
     assert cirq.channel(NoMethod(), None) is None
@@ -52,14 +52,31 @@ def assert_not_implemented(val):
     assert not cirq.has_channel(val)
 
 
-def test_channel_returns_not_implemented():
+def test_kraus_returns_not_implemented():
     class ReturnsNotImplemented:
-        def _channel_(self):
+        def _kraus_(self):
             return NotImplemented
 
     assert_not_implemented(ReturnsNotImplemented())
 
 
+def test_channel_generates_deprecation_warning():
+    class UsesDeprecatedChannelMethod:
+        def _has_channel_(self):
+            return True
+
+        def _channel_(self):
+            return (np.eye(2),)
+
+    val = UsesDeprecatedChannelMethod()
+    with pytest.warns(DeprecationWarning, match='_has_kraus_'):
+        assert cirq.has_channel(val)
+    with pytest.warns(DeprecationWarning, match='_kraus_'):
+        ks = cirq.channel(val)
+        assert len(ks) == 1
+        assert np.all(ks[0] == np.eye(2))
+
+
 def test_mixture_returns_not_implemented():
     class ReturnsNotImplemented:
         def _mixture_(self):
@@ -87,7 +104,7 @@ def test_channel():
     c = (a0, a1)
 
     class ReturnsChannel:
-        def _channel_(self) -> Sequence[np.ndarray]:
+        def _kraus_(self) -> Sequence[np.ndarray]:
             return c
 
     assert cirq.channel(ReturnsChannel()) is c
@@ -138,7 +155,7 @@ def _unitary_(self) -> np.ndarray:
 
 
 class HasChannel(cirq.SingleQubitGate):
-    def _has_channel_(self) -> bool:
+    def _has_kraus_(self) -> bool:
         return True