cirq-core 1.5.0.dev20250409225226__py3-none-any.whl → 1.6.0__py3-none-any.whl

cirq/protocols/pow_protocol.py

@@ -12,7 +12,11 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from typing import Any, Callable, Optional, overload, TYPE_CHECKING, TypeVar, Union
+# ruff: noqa: A001
+
+from __future__ import annotations
+
+from typing import Any, Callable, overload, TYPE_CHECKING, TypeVar
 
 if TYPE_CHECKING:
     import cirq
@@ -24,31 +28,28 @@ RaiseTypeErrorIfNotProvided: Any = ([],)
 TDefault = TypeVar('TDefault')
 
 
-# pylint: disable=function-redefined, redefined-builtin
 @overload
-def pow(val: 'cirq.Gate', exponent: Any) -> 'cirq.Gate':
+def pow(val: cirq.Gate, exponent: Any) -> cirq.Gate:
     pass
 
 
 @overload
-def pow(val: 'cirq.Operation', exponent: Any) -> 'cirq.Operation':
+def pow(val: cirq.Operation, exponent: Any) -> cirq.Operation:
     pass
 
 
 @overload
-def pow(val: 'cirq.Gate', exponent: Any, default: TDefault) -> Union[TDefault, 'cirq.Gate']:
+def pow(val: cirq.Gate, exponent: Any, default: TDefault) -> TDefault | cirq.Gate:
     pass
 
 
 @overload
-def pow(
-    val: 'cirq.Operation', exponent: Any, default: TDefault
-) -> Union[TDefault, 'cirq.Operation']:
+def pow(val: cirq.Operation, exponent: Any, default: TDefault) -> TDefault | cirq.Operation:
     pass
 
 
 @overload
-def pow(val: 'cirq.Circuit', exponent: int, default: TDefault) -> Union[TDefault, 'cirq.Circuit']:
+def pow(val: cirq.Circuit, exponent: int, default: TDefault) -> TDefault | cirq.Circuit:
     pass
 
 
@@ -57,9 +58,6 @@ def pow(val: Any, exponent: Any, default: TDefault) -> Any:
     pass
 
 
-# pylint: enable=function-redefined
-
-
 def pow(val: Any, exponent: Any, default: Any = RaiseTypeErrorIfNotProvided) -> Any:
     """Returns `val**factor` of the given value, if defined.
 
@@ -84,7 +82,7 @@ def pow(val: Any, exponent: Any, default: Any = RaiseTypeErrorIfNotProvided) ->
         TypeError: `val` doesn't have a __pow__ method (or that method returned
             NotImplemented) and no `default` value was specified.
     """
-    raiser: Optional[Callable] = getattr(val, '__pow__', None)
+    raiser: Callable | None = getattr(val, '__pow__', None)
     result = NotImplemented if raiser is None else raiser(exponent)
     if result is not NotImplemented:
         return result
@@ -96,6 +94,3 @@ def pow(val: Any, exponent: Any, default: Any = RaiseTypeErrorIfNotProvided) ->
     raise TypeError(
         f"object of type '{type(val)}' does have a __pow__ method, but it returned NotImplemented."
     )
-
-
-# pylint: enable=redefined-builtin

cirq/protocols/pow_protocol_test.py

@@ -12,6 +12,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from __future__ import annotations
+
 import pytest
 
 import cirq

cirq/protocols/qasm.py

@@ -12,9 +12,11 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from __future__ import annotations
+
 import string
 from types import NotImplementedType
-from typing import Any, Dict, Iterable, Optional, Tuple, TYPE_CHECKING, TypeVar, Union
+from typing import Any, Iterable, Mapping, TYPE_CHECKING, TypeVar
 
 from typing_extensions import Protocol
 
@@ -36,9 +38,9 @@ class QasmArgs(string.Formatter):
         self,
         precision: int = 10,
         version: str = '2.0',
-        qubit_id_map: Optional[Dict['cirq.Qid', str]] = None,
-        meas_key_id_map: Optional[Dict[str, str]] = None,
-        meas_key_bitcount: Optional[Dict[str, int]] = None,
+        qubit_id_map: Mapping[cirq.Qid, str] | None = None,
+        meas_key_id_map: dict[str, str] | None = None,
+        meas_key_bitcount: dict[str, int] | None = None,
     ) -> None:
         """Inits QasmArgs.
 
@@ -62,7 +64,7 @@ class QasmArgs(string.Formatter):
     def _format_number(self, value) -> str:
         """OpenQASM 2.0 does not support '1e-5' and wants '1.0e-5'"""
         s = f'{value}'
-        if 'e' in s and not '.' in s:
+        if 'e' in s and '.' not in s:
             return s.replace('e', '.0e')
         return s
 
@@ -97,7 +99,7 @@ class SupportsQasm(Protocol):
     """
 
     @doc_private
-    def _qasm_(self) -> Union[None, NotImplementedType, str]:
+    def _qasm_(self) -> None | NotImplementedType | str:
         pass
 
 
@@ -110,7 +112,7 @@ class SupportsQasmWithArgs(Protocol):
     """
 
     @doc_private
-    def _qasm_(self, args: QasmArgs) -> Union[None, NotImplementedType, str]:
+    def _qasm_(self, args: QasmArgs) -> None | NotImplementedType | str:
         pass
 
 
@@ -123,20 +125,17 @@ class SupportsQasmWithArgsAndQubits(Protocol):
     """
 
     @doc_private
-    def _qasm_(
-        self, qubits: Tuple['cirq.Qid'], args: QasmArgs
-    ) -> Union[None, NotImplementedType, str]:
+    def _qasm_(self, qubits: tuple[cirq.Qid], args: QasmArgs) -> None | NotImplementedType | str:
         pass
 
 
-# pylint: disable=function-redefined
 def qasm(
     val: Any,
     *,
-    args: Optional[QasmArgs] = None,
-    qubits: Optional[Iterable['cirq.Qid']] = None,
+    args: QasmArgs | None = None,
+    qubits: Iterable[cirq.Qid] | None = None,
     default: TDefault = RaiseTypeErrorIfNotProvided,
-) -> Union[str, TDefault]:
+) -> str | TDefault:
     """Returns QASM code for the given value, if possible.
 
     Different values require different sets of arguments. The general rule of
@@ -169,10 +168,9 @@ def qasm(
     method = getattr(val, '_qasm_', None)
     result = NotImplemented
     if method is not None:
-        kwargs: Dict[str, Any] = {}
+        kwargs: dict[str, Any] = {}
         if args is not None:
             kwargs['args'] = args
-        # pylint: disable=not-callable
         if qubits is not None:
             kwargs['qubits'] = tuple(qubits)
         try:
@@ -182,7 +180,6 @@ def qasm(
                 "cirq.qasm does not expect qubits or args to be specified"
                 f"for the given value of type {type(val)}."
             ) from error
-        # pylint: enable=not-callable
     if result is not None and result is not NotImplemented:
         return result
 
@@ -194,6 +191,3 @@ def qasm(
         f"object of type '{type(val)}' does have a _qasm_ method, "
         "but it returned NotImplemented or None."
     )
-
-
-# pylint: enable=function-redefined

cirq/protocols/qasm_test.py

@@ -11,6 +11,9 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+
+from __future__ import annotations
+
 import pytest
 
 import cirq
@@ -40,7 +43,7 @@ class ExpectsArgsQubits:
         return 'text'
 
 
-def test_qasm():
+def test_qasm() -> None:
     assert cirq.qasm(NoMethod(), default=None) is None
     assert cirq.qasm(NoMethod(), default=5) == 5
     assert cirq.qasm(ReturnsText()) == 'text'
@@ -54,12 +57,12 @@ def test_qasm():
     assert cirq.qasm(ExpectsArgsQubits(), args=cirq.QasmArgs(), qubits=()) == 'text'
 
 
-def test_qasm_qubits_improperly_supplied():
+def test_qasm_qubits_improperly_supplied() -> None:
     with pytest.raises(TypeError, match="does not expect qubits or args to be specified"):
         _ = cirq.qasm(cirq.Circuit(), qubits=[cirq.LineQubit(1)])
 
 
-def test_qasm_args_formatting():
+def test_qasm_args_formatting() -> None:
     args = cirq.QasmArgs()
     assert args.format_field(0.01, '') == '0.01'
     assert args.format_field(0.01, 'half_turns') == 'pi*0.01'

cirq/protocols/qid_shape_protocol.py

@@ -12,8 +12,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from __future__ import annotations
+
 from types import NotImplementedType
-from typing import Any, Sequence, Tuple, TypeVar, Union
+from typing import Any, Sequence, TypeVar
 
 from typing_extensions import Protocol
 
@@ -22,7 +24,7 @@ from cirq._doc import doc_private, document
 
 # This is a special indicator value used by the methods to determine whether or
 # not the caller provided a 'default' argument. It must be of type
-# Tuple[int, ...] to ensure the method has the correct type signature in that
+# tuple[int, ...] to ensure the method has the correct type signature in that
 # case. It is checked for using `is`, so it won't have a false positive if the
 # user provides a different (0,) value.
 RaiseTypeErrorIfNotProvided: Any = (0,)
@@ -37,7 +39,7 @@ class SupportsExplicitQidShape(Protocol):
     number qubits/qudits/qids, each with a specific number of quantum levels."""
 
     @doc_private
-    def _qid_shape_(self) -> Union[Tuple[int, ...], NotImplementedType]:
+    def _qid_shape_(self) -> tuple[int, ...] | NotImplementedType:
         """A tuple specifying the number of quantum levels of each qid this
         object operates on, e.g. (2, 2, 2) for a three-qubit gate.
 
@@ -65,7 +67,7 @@ class SupportsExplicitNumQubits(Protocol):
     number of qubits."""
 
     @document
-    def _num_qubits_(self) -> Union[int, NotImplementedType]:
+    def _num_qubits_(self) -> int | NotImplementedType:
         """The number of qubits, qudits, or qids this object operates on.
 
         This method is used by the global `cirq.num_qubits` method (and by
@@ -80,7 +82,7 @@ class SupportsExplicitNumQubits(Protocol):
 
 def qid_shape(
     val: Any, default: TDefault = RaiseTypeErrorIfNotProvided
-) -> Union[Tuple[int, ...], TDefault]:
+) -> tuple[int, ...] | TDefault:
     """Returns a tuple describing the number of quantum levels of each
     qubit/qudit/qid `val` operates on.
 
@@ -134,9 +136,7 @@ def qid_shape(
     raise TypeError(f"object of type '{type(val)}' has no _num_qubits_ or _qid_shape_ methods.")
 
 
-def num_qubits(
-    val: Any, default: TDefault = RaiseTypeErrorIfNotProvidedInt
-) -> Union[int, TDefault]:
+def num_qubits(val: Any, default: TDefault = RaiseTypeErrorIfNotProvidedInt) -> int | TDefault:
     """Returns the number of qubits, qudits, or qids `val` operates on.
 
     Args:

cirq/protocols/qid_shape_protocol_test.py

@@ -12,12 +12,14 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from __future__ import annotations
+
 import pytest
 
 import cirq
 
 
-def test_qid_shape():
+def test_qid_shape() -> None:
     class ShapeObj:
         def _qid_shape_(self):
             return (1, 2, 3)

cirq/protocols/resolve_parameters.py

@@ -12,6 +12,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from __future__ import annotations
+
 import numbers
 from typing import AbstractSet, Any, cast, TYPE_CHECKING, TypeVar
 
@@ -48,7 +50,7 @@ class SupportsParameterization(Protocol):
         """
 
     @doc_private
-    def _resolve_parameters_(self, resolver: 'cirq.ParamResolver', recursive: bool) -> Self:
+    def _resolve_parameters_(self, resolver: cirq.ParamResolver, recursive: bool) -> Self:
         """Resolve the parameters in the effect."""
 
 
@@ -133,7 +135,7 @@ def parameter_symbols(val: Any) -> AbstractSet[sympy.Symbol]:
 
 
 def resolve_parameters(
-    val: T, param_resolver: 'cirq.ParamResolverOrSimilarType', recursive: bool = True
+    val: T, param_resolver: cirq.ParamResolverOrSimilarType, recursive: bool = True
 ) -> T:
     """Resolves symbol parameters in the effect using the param resolver.
 
@@ -195,6 +197,6 @@ def resolve_parameters(
         return val
 
 
-def resolve_parameters_once(val: Any, param_resolver: 'cirq.ParamResolverOrSimilarType'):
+def resolve_parameters_once(val: Any, param_resolver: cirq.ParamResolverOrSimilarType):
     """Performs a single parameter resolution step using the param resolver."""
     return resolve_parameters(val, param_resolver, False)

cirq/protocols/resolve_parameters_test.py

@@ -12,15 +12,16 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from __future__ import annotations
+
 import pytest
 import sympy
 
 import cirq
-from cirq.study import ParamResolver
 
 
 @pytest.mark.parametrize('resolve_fn', [cirq.resolve_parameters, cirq.resolve_parameters_once])
-def test_resolve_parameters(resolve_fn):
+def test_resolve_parameters(resolve_fn) -> None:
     class NoMethod:
         pass
 
@@ -38,7 +39,7 @@ def test_resolve_parameters(resolve_fn):
         def _is_parameterized_(self) -> bool:
             return self.parameter != 0
 
-        def _resolve_parameters_(self, resolver: ParamResolver, recursive: bool):
+        def _resolve_parameters_(self, resolver: cirq.ParamResolver, recursive: bool):
             self.parameter = resolver.value_of(self.parameter, recursive)
             return self
 
@@ -74,7 +75,7 @@ def test_resolve_parameters(resolve_fn):
     assert resolve_fn(1j, resolver) == 1j
 
 
-def test_is_parameterized():
+def test_is_parameterized() -> None:
     a, b = tuple(sympy.Symbol(l) for l in 'ab')
     x, y = 0, 4
     assert not cirq.is_parameterized((x, y))
@@ -90,7 +91,7 @@ def test_is_parameterized():
     assert not cirq.is_parameterized(1j)
 
 
-def test_parameter_names():
+def test_parameter_names() -> None:
     a, b, c = tuple(sympy.Symbol(l) for l in 'abc')
     x, y, z = 0, 4, 7
     assert cirq.parameter_names((a, b, c)) == {'a', 'b', 'c'}
@@ -105,7 +106,7 @@ def test_parameter_names():
 
 
 @pytest.mark.parametrize('resolve_fn', [cirq.resolve_parameters, cirq.resolve_parameters_once])
-def test_skips_empty_resolution(resolve_fn):
+def test_skips_empty_resolution(resolve_fn) -> None:
     class Tester:
         def _resolve_parameters_(self, resolver, recursive):
             return 5
@@ -115,7 +116,7 @@ def test_skips_empty_resolution(resolve_fn):
     assert resolve_fn(t, {'x': 2}) == 5
 
 
-def test_recursive_resolve():
+def test_recursive_resolve() -> None:
     a, b, c = [sympy.Symbol(l) for l in 'abc']
     resolver = cirq.ParamResolver({a: b + 3, b: c + 2, c: 1})
     assert cirq.resolve_parameters_once(a, resolver) == b + 3

cirq/protocols/trace_distance_bound.py

@@ -12,7 +12,9 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from typing import Any, Optional, Sequence, TypeVar, Union
+from __future__ import annotations
+
+from typing import Any, Sequence, TypeVar
 
 import numpy as np
 from typing_extensions import Protocol
@@ -79,7 +81,7 @@ def trace_distance_bound(val: Any) -> float:
     return 1.0
 
 
-def _strat_from_trace_distance_bound_method(val: Any) -> Optional[float]:
+def _strat_from_trace_distance_bound_method(val: Any) -> float | None:
     """Attempts to use a specialized method."""
     getter = getattr(val, '_trace_distance_bound_', None)
     result = NotImplemented if getter is None else getter()
@@ -93,7 +95,7 @@ def _strat_from_trace_distance_bound_method(val: Any) -> Optional[float]:
     return NotImplemented
 
 
-def _strat_distance_from_unitary(val: Any) -> Optional[float]:
+def _strat_distance_from_unitary(val: Any) -> float | None:
     """Attempts to compute a value's trace_distance_bound from its unitary."""
     u = unitary_protocol.unitary(val, default=None)
 
@@ -109,7 +111,7 @@ def _strat_distance_from_unitary(val: Any) -> Optional[float]:
     return trace_distance_from_angle_list(np.angle(np.linalg.eigvals(u)))
 
 
-def trace_distance_from_angle_list(angle_list: Union[Sequence[float], np.ndarray]) -> float:
+def trace_distance_from_angle_list(angle_list: Sequence[float] | np.ndarray) -> float:
     """Given a list of arguments of the eigenvalues of a unitary matrix,
     calculates the trace distance bound of the unitary effect.
 

cirq/protocols/trace_distance_bound_test.py

@@ -12,12 +12,14 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from __future__ import annotations
+
 import numpy as np
 
 import cirq
 
 
-def test_trace_distance_bound():
+def test_trace_distance_bound() -> None:
     class NoMethod:
         pass
 

cirq/protocols/unitary_protocol.py

@@ -12,12 +12,15 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from __future__ import annotations
+
 from types import NotImplementedType
-from typing import Any, Optional, TypeVar, Union
+from typing import Any, TypeVar
 
 import numpy as np
 from typing_extensions import Protocol
 
+from cirq import linalg
 from cirq._doc import doc_private
 from cirq.protocols import qid_shape_protocol
 from cirq.protocols.apply_unitary_protocol import apply_unitaries, ApplyUnitaryArgs
@@ -37,7 +40,7 @@ class SupportsUnitary(Protocol):
     """An object that may be describable by a unitary matrix."""
 
     @doc_private
-    def _unitary_(self) -> Union[np.ndarray, NotImplementedType]:
+    def _unitary_(self) -> np.ndarray | NotImplementedType:
         """A unitary matrix describing this value, e.g. the matrix of a gate.
 
         This method is used by the global `cirq.unitary` method. If this method
@@ -76,12 +79,13 @@ class SupportsUnitary(Protocol):
 
 
 def unitary(
-    val: Any, default: Union[np.ndarray, TDefault] = RaiseTypeErrorIfNotProvided
-) -> Union[np.ndarray, TDefault]:
+    val: Any, default: np.ndarray | TDefault = RaiseTypeErrorIfNotProvided
+) -> np.ndarray | TDefault:
     """Returns a unitary matrix describing the given value.
 
     The matrix is determined by any one of the following techniques:
 
+    - If the value is a numpy array, it is returned directly.
     - The value has a `_unitary_` method that returns something besides None or
         NotImplemented. The matrix is whatever the method returned.
     - The value has a `_decompose_` method that returns a list of operations,
@@ -108,7 +112,13 @@ def unitary(
     Raises:
         TypeError: `val` doesn't have a unitary effect and no default value was
             specified.
+        ValueError: `val` is a numpy array that is not unitary.
     """
+    if isinstance(val, np.ndarray):
+        if not linalg.is_unitary(val):
+            raise ValueError("The provided numpy array is not unitary.")
+        return val
+
     strats = [
         _strat_unitary_from_unitary,
         _strat_unitary_from_apply_unitary,
@@ -140,7 +150,7 @@ def unitary(
     )
 
 
-def _strat_unitary_from_unitary(val: Any) -> Optional[np.ndarray]:
+def _strat_unitary_from_unitary(val: Any) -> np.ndarray | None:
     """Attempts to compute a value's unitary via its _unitary_ method."""
     getter = getattr(val, '_unitary_', None)
     if getter is None:
@@ -148,7 +158,7 @@ def _strat_unitary_from_unitary(val: Any) -> Optional[np.ndarray]:
     return getter()
 
 
-def _strat_unitary_from_apply_unitary(val: Any) -> Optional[np.ndarray]:
+def _strat_unitary_from_apply_unitary(val: Any) -> np.ndarray | None:
     """Attempts to compute a value's unitary via its _apply_unitary_ method."""
     # Check for the magic method.
     method = getattr(val, '_apply_unitary_', None)
@@ -169,7 +179,7 @@ def _strat_unitary_from_apply_unitary(val: Any) -> Optional[np.ndarray]:
     return result.reshape((state_len, state_len))
 
 
-def _strat_unitary_from_decompose(val: Any) -> Optional[np.ndarray]:
+def _strat_unitary_from_decompose(val: Any) -> np.ndarray | None:
     """Attempts to compute a value's unitary via its _decompose_ method."""
     # Check if there's a decomposition.
     operations, qubits, val_qid_shape = _try_decompose_into_operations_and_qubits(val)

cirq/protocols/unitary_protocol_test.py

@@ -11,7 +11,8 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-from typing import Optional
+
+from __future__ import annotations
 
 import numpy as np
 import pytest
@@ -74,7 +75,7 @@ class FullyImplemented(cirq.Gate):
     def _has_unitary_(self) -> bool:
         return self.unitary_value
 
-    def _unitary_(self) -> Optional[np.ndarray]:
+    def _unitary_(self) -> np.ndarray | None:
         if not self.unitary_value:
             return None
         return m1
@@ -160,6 +161,15 @@ def test_unitary():
         _ = cirq.unitary(ReturnsNotImplemented())
     assert cirq.unitary(ReturnsMatrix()) is m1
 
+    # Test that numpy arrays are handled directly
+    test_matrix = np.array([[1, 0], [0, 1]])
+    assert cirq.unitary(test_matrix, NotImplemented) is test_matrix
+
+    # Test that non-unitary numpy arrays raise ValueError
+    non_unitary_matrix = np.array([[1, 1], [0, 1]])
+    with pytest.raises(ValueError, match="The provided numpy array is not unitary"):
+        _ = cirq.unitary(non_unitary_matrix)
+
     assert cirq.unitary(NoMethod(), None) is None
     assert cirq.unitary(ReturnsNotImplemented(), None) is None
     assert cirq.unitary(ReturnsMatrix(), None) is m1

cirq/qis/channels.py

@@ -11,7 +11,11 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+
 """Tools for analyzing and manipulating quantum channels."""
+
+from __future__ import annotations
+
 from typing import Sequence
 
 import numpy as np
@@ -280,7 +284,7 @@ def superoperator_to_choi(superoperator: np.ndarray) -> np.ndarray:
     return np.reshape(c, (d * d, d * d))
 
 
-def operation_to_choi(operation: 'protocols.SupportsKraus') -> np.ndarray:
+def operation_to_choi(operation: protocols.SupportsKraus) -> np.ndarray:
     r"""Returns the unique Choi matrix associated with an operation .
 
     Choi matrix J(E) of a linear map E: L(H1) -> L(H2) which takes linear operators
@@ -302,7 +306,7 @@ def operation_to_choi(operation: 'protocols.SupportsKraus') -> np.ndarray:
     return kraus_to_choi(protocols.kraus(operation))
 
 
-def operation_to_superoperator(operation: 'protocols.SupportsKraus') -> np.ndarray:
+def operation_to_superoperator(operation: protocols.SupportsKraus) -> np.ndarray:
     """Returns the matrix representation of an operation in standard basis.
 
     Let E: L(H1) -> L(H2) denote a linear map which takes linear operators on Hilbert space H1