cirq-core 1.7.0.dev20250924231107__py3-none-any.whl → 1.7.0.dev20251203004401__py3-none-any.whl

cirq/ops/raw_types.py

@@ -18,20 +18,9 @@ from __future__ import annotations
 
 import abc
 import functools
+from collections.abc import Callable, Collection, Hashable, Iterable, Mapping, Sequence, Set
 from types import NotImplementedType
-from typing import (
-    AbstractSet,
-    Any,
-    Callable,
-    cast,
-    Collection,
-    Hashable,
-    Iterable,
-    Mapping,
-    overload,
-    Sequence,
-    TYPE_CHECKING,
-)
+from typing import Any, cast, overload, TYPE_CHECKING
 
 import numpy as np
 
@@ -528,6 +517,9 @@ class Operation(metaclass=abc.ABCMeta):
     def _qid_shape_(self) -> tuple[int, ...]:
         return protocols.qid_shape(self.qubits)
 
+    def __pow__(self, exponent: Any) -> Operation:
+        return NotImplemented  # pragma: no cover
+
     @abc.abstractmethod
     def with_qubits(self, *new_qubits: cirq.Qid) -> cirq.Operation:
         """Returns the same operation, but applied to different qubits.
@@ -909,7 +901,7 @@ class TaggedOperation(Operation):
         return NotImplemented
 
     @cached_method
-    def _parameter_names_(self) -> AbstractSet[str]:
+    def _parameter_names_(self) -> Set[str]:
         tag_params = {name for tag in self.tags for name in protocols.parameter_names(tag)}
         return protocols.parameter_names(self.sub_operation) | tag_params
 
@@ -1023,7 +1015,7 @@ class _InverseCompositeGate(Gate):
         return protocols.is_parameterized(self._original)
 
     @cached_method
-    def _parameter_names_(self) -> AbstractSet[str]:
+    def _parameter_names_(self) -> Set[str]:
         return protocols.parameter_names(self._original)
 
     def _resolve_parameters_(

cirq/ops/raw_types_test.py

@@ -14,7 +14,8 @@
 
 from __future__ import annotations
 
-from typing import AbstractSet, Any, cast, Iterator
+from collections.abc import Iterator, Set
+from typing import Any, cast
 
 import numpy as np
 import pytest
@@ -739,7 +740,7 @@ class ParameterizableTag:
     def _is_parameterized_(self) -> bool:
         return cirq.is_parameterized(self.value)
 
-    def _parameter_names_(self) -> AbstractSet[str]:
+    def _parameter_names_(self) -> Set[str]:
         return cirq.parameter_names(self.value)
 
     def _resolve_parameters_(
@@ -781,7 +782,7 @@ def test_inverse_composite_standards() -> None:
         def _value_equality_values_(self):
             return (self._param,)
 
-        def _parameter_names_(self) -> AbstractSet[str]:
+        def _parameter_names_(self) -> Set[str]:
             return cirq.parameter_names(self._param)
 
         def _is_parameterized_(self) -> bool:

cirq/ops/state_preparation_channel.py

@@ -16,7 +16,8 @@
 
 from __future__ import annotations
 
-from typing import Any, Iterable, TYPE_CHECKING
+from collections.abc import Iterable
+from typing import Any, TYPE_CHECKING
 
 import numpy as np
 

cirq/ops/three_qubit_gates.py

@@ -16,7 +16,8 @@
 
 from __future__ import annotations
 
-from typing import AbstractSet, Any, Collection, Iterator, Sequence, TYPE_CHECKING
+from collections.abc import Collection, Iterator, Sequence, Set
+from typing import Any, TYPE_CHECKING
 
 import numpy as np
 import sympy
@@ -224,7 +225,7 @@ class ThreeQubitDiagonalGate(raw_types.Gate):
     def _is_parameterized_(self) -> bool:
         return any(protocols.is_parameterized(angle) for angle in self._diag_angles_radians)
 
-    def _parameter_names_(self) -> AbstractSet[str]:
+    def _parameter_names_(self) -> Set[str]:
         return {
             name for angle in self._diag_angles_radians for name in protocols.parameter_names(angle)
         }

cirq/ops/two_qubit_diagonal_gate.py

@@ -20,7 +20,8 @@ passed as a list.
 
 from __future__ import annotations
 
-from typing import AbstractSet, Any, Iterator, Sequence, TYPE_CHECKING
+from collections.abc import Iterator, Sequence, Set
+from typing import Any, TYPE_CHECKING
 
 import numpy as np
 import sympy
@@ -76,7 +77,7 @@ class TwoQubitDiagonalGate(raw_types.Gate):
     def _is_parameterized_(self) -> bool:
         return any(protocols.is_parameterized(angle) for angle in self._diag_angles_radians)
 
-    def _parameter_names_(self) -> AbstractSet[str]:
+    def _parameter_names_(self) -> Set[str]:
         return {
             name for angle in self._diag_angles_radians for name in protocols.parameter_names(angle)
         }

cirq/ops/uniform_superposition_gate.py

@@ -14,7 +14,8 @@
 
 from __future__ import annotations
 
-from typing import Any, Iterator, Sequence, TYPE_CHECKING
+from collections.abc import Iterator, Sequence
+from typing import Any, TYPE_CHECKING
 
 import numpy as np
 

cirq/ops/wait_gate.py

@@ -14,7 +14,10 @@
 
 from __future__ import annotations
 
-from typing import AbstractSet, Any, TYPE_CHECKING
+from collections.abc import Set
+from typing import Any, TYPE_CHECKING
+
+import sympy
 
 from cirq import protocols, value
 from cirq.ops import raw_types
@@ -51,8 +54,11 @@ class WaitGate(raw_types.Gate):
             ValueError: If the `qid_shape` provided is empty or `num_qubits` contradicts
                 `qid_shape`.
         """
-        self._duration = value.Duration(duration)
-        if not protocols.is_parameterized(self.duration) and self.duration < 0:
+        self._duration = (
+            duration if isinstance(duration, value.Duration) else value.Duration(duration)
+        )
+        total_picos = self.duration.total_picos()
+        if not isinstance(total_picos, sympy.Basic) and total_picos < 0:
             raise ValueError('duration < 0')
         if qid_shape is None:
             if num_qubits is None:
@@ -75,7 +81,7 @@ class WaitGate(raw_types.Gate):
     def _is_parameterized_(self) -> bool:
         return protocols.is_parameterized(self.duration)
 
-    def _parameter_names_(self) -> AbstractSet[str]:
+    def _parameter_names_(self) -> Set[str]:
         return protocols.parameter_names(self.duration)
 
     def _resolve_parameters_(self, resolver: cirq.ParamResolver, recursive: bool) -> WaitGate:

cirq/protocols/act_on_protocol.py

@@ -14,8 +14,9 @@
 
 from __future__ import annotations
 
+from collections.abc import Sequence
 from types import NotImplementedType
-from typing import Any, Protocol, Sequence, TYPE_CHECKING
+from typing import Any, Protocol, TYPE_CHECKING
 
 from cirq import ops
 from cirq._doc import doc_private

cirq/protocols/act_on_protocol_test.py

@@ -14,7 +14,8 @@
 
 from __future__ import annotations
 
-from typing import Any, Self, Sequence
+from collections.abc import Sequence
+from typing import Any, Self
 
 import numpy as np
 import pytest

cirq/protocols/apply_channel_protocol.py

@@ -16,8 +16,9 @@
 
 from __future__ import annotations
 
+from collections.abc import Iterable, Sequence
 from types import NotImplementedType
-from typing import Any, Iterable, Protocol, Sequence, TypeVar
+from typing import Any, Protocol, TypeVar
 
 import numpy as np
 

cirq/protocols/apply_mixture_protocol.py

@@ -16,8 +16,9 @@
 
 from __future__ import annotations
 
+from collections.abc import Iterable
 from types import NotImplementedType
-from typing import Any, cast, Iterable, Protocol, TypeVar
+from typing import Any, cast, Protocol, TypeVar
 
 import numpy as np
 

cirq/protocols/apply_mixture_protocol_test.py

@@ -13,7 +13,8 @@
 # limitations under the License.
 from __future__ import annotations
 
-from typing import Any, cast, Iterable
+from collections.abc import Iterable
+from typing import Any, cast
 
 import numpy as np
 import pytest

cirq/protocols/apply_unitary_protocol.py

@@ -17,8 +17,9 @@
 from __future__ import annotations
 
 import warnings
+from collections.abc import Iterable, Sequence
 from types import EllipsisType, NotImplementedType
-from typing import Any, cast, Iterable, Protocol, Sequence, TYPE_CHECKING, TypeVar
+from typing import Any, cast, Protocol, TYPE_CHECKING, TypeVar
 
 import numpy as np
 

cirq/protocols/apply_unitary_protocol_test.py

@@ -240,6 +240,7 @@ def test_apply_unitary_args_tensor_manipulation() -> None:
             op_indices, tuple(qid_shape[i] for i in op_indices)
         )
         sub_result = val._apply_unitary_(sub_args)
+        assert isinstance(sub_result, np.ndarray)
         result = _incorporate_result_into_target(args, sub_args, sub_result)
         np.testing.assert_allclose(result, expected, atol=1e-8)
 
@@ -258,6 +259,7 @@ def test_apply_unitary_args_tensor_manipulation() -> None:
             op_indices, tuple(qid_shape[i] for i in op_indices)
         )
         sub_result = val._apply_unitary_(sub_args)
+        assert isinstance(sub_result, np.ndarray)
         result = _incorporate_result_into_target(args, sub_args, sub_result)
         np.testing.assert_allclose(result, expected, atol=1e-8, verbose=True)
 

cirq/protocols/approximate_equality_protocol.py

@@ -15,9 +15,10 @@
 from __future__ import annotations
 
 import numbers
+from collections.abc import Iterable
 from decimal import Decimal
 from fractions import Fraction
-from typing import Any, Iterable, Protocol
+from typing import Any, Protocol
 
 import numpy as np
 import sympy

cirq/protocols/circuit_diagram_info_protocol.py

@@ -15,8 +15,9 @@
 from __future__ import annotations
 
 import re
+from collections.abc import Iterable, Sequence
 from fractions import Fraction
-from typing import Any, Iterable, overload, Protocol, Self, Sequence, TYPE_CHECKING, TypeVar, Union
+from typing import Any, overload, Protocol, Self, TYPE_CHECKING, TypeVar, Union
 
 import numpy as np
 import sympy

cirq/protocols/decompose_protocol.py

@@ -18,19 +18,9 @@ import dataclasses
 import inspect
 import itertools
 from collections import defaultdict
+from collections.abc import Callable, Iterable, Iterator, Sequence
 from types import NotImplementedType
-from typing import (
-    Any,
-    Callable,
-    Iterable,
-    Iterator,
-    overload,
-    Protocol,
-    Sequence,
-    TYPE_CHECKING,
-    TypeVar,
-    Union,
-)
+from typing import Any, overload, Protocol, TYPE_CHECKING, TypeVar, Union
 
 from cirq import devices, ops
 from cirq._doc import doc_private

cirq/protocols/has_stabilizer_effect_protocol.py

@@ -97,7 +97,7 @@ def _strat_has_stabilizer_effect_from_unitary(val: Any) -> bool | None:
             ps = DensePauliString(pauli_string)
             p = ps._unitary_()
             if not pauli_string_decomposition.unitary_to_pauli_string(
-                (unitary @ p @ unitary.T.conj())
+                unitary @ p @ unitary.T.conj()
             ):
                 return False
     return True

cirq/protocols/hash_from_pickle_test.py

@@ -18,8 +18,8 @@ import multiprocessing
 import os
 import pathlib
 import pickle
-from collections.abc import Iterator
-from typing import Any, Hashable
+from collections.abc import Hashable, Iterator
+from typing import Any
 
 import pytest
 

cirq/protocols/inverse_protocol.py

@@ -14,7 +14,8 @@
 
 from __future__ import annotations
 
-from typing import Any, Iterable, overload, TYPE_CHECKING, TypeVar
+from collections.abc import Iterable
+from typing import Any, overload, TYPE_CHECKING, TypeVar
 
 from cirq import ops
 

cirq/protocols/json_serialization.py

@@ -20,8 +20,9 @@ import gzip
 import json
 import numbers
 import pathlib
+from collections.abc import Callable, Iterable, Sequence
 from types import NotImplementedType
-from typing import Any, Callable, cast, IO, Iterable, overload, Protocol, Sequence
+from typing import Any, cast, IO, overload, Protocol
 
 import attrs
 import numpy as np

cirq/protocols/kraus_protocol.py

@@ -17,8 +17,9 @@
 from __future__ import annotations
 
 import warnings
+from collections.abc import Iterable
 from types import NotImplementedType
-from typing import Any, Protocol, Sequence, TypeVar
+from typing import Any, Protocol, TypeVar
 
 import numpy as np
 
@@ -31,7 +32,7 @@ from cirq.protocols.unitary_protocol import unitary
 
 # This is a special indicator value used by the channel method to determine
 # whether or not the caller provided a 'default' argument. It must be of type
-# Sequence[np.ndarray] to ensure the method has the correct type signature in
+# Iterable[np.ndarray] 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 (np.array([]),) value.
 RaiseTypeErrorIfNotProvided: tuple[np.ndarray] = (np.array([]),)
@@ -44,7 +45,7 @@ class SupportsKraus(Protocol):
     """An object that may be describable as a quantum channel."""
 
     @doc_private
-    def _kraus_(self) -> Sequence[np.ndarray] | NotImplementedType:
+    def _kraus_(self) -> Iterable[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

cirq/protocols/kraus_protocol_test.py

@@ -16,7 +16,7 @@
 
 from __future__ import annotations
 
-from typing import Iterable, Sequence
+from collections.abc import Iterable
 
 import numpy as np
 import pytest
@@ -89,7 +89,7 @@ def test_explicit_kraus() -> None:
     c = (a0, a1)
 
     class ReturnsKraus:
-        def _kraus_(self) -> Sequence[np.ndarray]:
+        def _kraus_(self) -> Iterable[np.ndarray]:
             return c
 
     assert cirq.kraus(ReturnsKraus()) is c

cirq/protocols/measurement_key_protocol.py

@@ -16,8 +16,9 @@
 
 from __future__ import annotations
 
+from collections.abc import Mapping
 from types import NotImplementedType
-from typing import Any, Mapping, overload, Protocol, TYPE_CHECKING, TypeVar
+from typing import Any, overload, Protocol, TYPE_CHECKING, TypeVar
 
 from cirq import value
 from cirq._doc import doc_private

cirq/protocols/mixture_protocol.py

@@ -16,8 +16,9 @@
 
 from __future__ import annotations
 
+from collections.abc import Sequence
 from types import NotImplementedType
-from typing import Any, Protocol, Sequence
+from typing import Any, Protocol
 
 import numpy as np
 

cirq/protocols/pow_protocol.py

@@ -16,7 +16,8 @@
 
 from __future__ import annotations
 
-from typing import Any, Callable, overload, TYPE_CHECKING, TypeVar
+from collections.abc import Callable
+from typing import Any, overload, TYPE_CHECKING, TypeVar
 
 if TYPE_CHECKING:
     import cirq

cirq/protocols/qasm.py

@@ -15,8 +15,9 @@
 from __future__ import annotations
 
 import string
+from collections.abc import Iterable, Mapping
 from types import NotImplementedType
-from typing import Any, Iterable, Mapping, Protocol, TYPE_CHECKING, TypeVar
+from typing import Any, Protocol, TYPE_CHECKING, TypeVar
 
 from cirq import ops
 from cirq._doc import doc_private

cirq/protocols/qid_shape_protocol.py

@@ -14,8 +14,9 @@
 
 from __future__ import annotations
 
+from collections.abc import Sequence
 from types import NotImplementedType
-from typing import Any, Protocol, Sequence, TypeVar
+from typing import Any, Protocol, TypeVar
 
 from cirq import ops
 from cirq._doc import doc_private, document

cirq/protocols/resolve_parameters.py

@@ -15,7 +15,8 @@
 from __future__ import annotations
 
 import numbers
-from typing import AbstractSet, Any, cast, Protocol, Self, TYPE_CHECKING, TypeVar
+from collections.abc import Set
+from typing import Any, cast, Protocol, Self, TYPE_CHECKING, TypeVar
 
 import sympy
 
@@ -40,7 +41,7 @@ class SupportsParameterization(Protocol):
         and False otherwise."""
 
     @doc_private
-    def _parameter_names_(self) -> AbstractSet[str]:
+    def _parameter_names_(self) -> Set[str]:
         """Returns a collection of string names of parameters that require
         resolution. If _is_parameterized_ is False, the collection is empty.
         The converse is not necessarily true, because some objects may report
@@ -92,7 +93,7 @@ def is_parameterized(val: Any) -> bool:
     return bool(parameter_names(val))
 
 
-def parameter_names(val: Any) -> AbstractSet[str]:
+def parameter_names(val: Any) -> Set[str]:
     """Returns parameter names for this object.
 
     Args:
@@ -119,7 +120,7 @@ def parameter_names(val: Any) -> AbstractSet[str]:
     return set()
 
 
-def parameter_symbols(val: Any) -> AbstractSet[sympy.Symbol]:
+def parameter_symbols(val: Any) -> Set[sympy.Symbol]:
     """Returns parameter symbols for this object.
 
     Args:
@@ -169,14 +170,8 @@ def resolve_parameters(
         return val
 
     # Ensure it is a dictionary wrapped in a ParamResolver.
-    param_resolver = study.ParamResolver(param_resolver)
-
-    # Handle special cases for sympy expressions and sequences.
-    # These may not in fact preserve types, but we pretend they do by casting.
-    if isinstance(val, sympy.Expr):
-        return cast(T, param_resolver.value_of(val, recursive))
-    if isinstance(val, (list, tuple)):
-        return cast(T, type(val)(resolve_parameters(e, param_resolver, recursive) for e in val))
+    if not isinstance(param_resolver, study.ParamResolver):
+        param_resolver = study.ParamResolver(param_resolver)
 
     is_parameterized = (
         val._is_parameterized_() if hasattr(val, '_is_parameterized_') else NotImplemented
@@ -192,8 +187,15 @@ def resolve_parameters(
 
     if result is not NotImplemented:
         return result
-    else:
-        return val
+
+    # Handle special cases for sympy expressions and sequences.
+    # These may not in fact preserve types, but we pretend they do by casting.
+    if isinstance(val, sympy.Expr):
+        return cast(T, param_resolver.value_of(val, recursive))
+    if isinstance(val, (list, tuple)):
+        return cast(T, type(val)(resolve_parameters(e, param_resolver, recursive) for e in val))
+
+    return val
 
 
 def resolve_parameters_once(val: T, param_resolver: cirq.ParamResolverOrSimilarType) -> T:

cirq/protocols/trace_distance_bound.py

@@ -14,7 +14,8 @@
 
 from __future__ import annotations
 
-from typing import Any, Protocol, Sequence, TypeVar
+from collections.abc import Sequence
+from typing import Any, Protocol, TypeVar
 
 import numpy as np
 

cirq/protocols/unitary_protocol.py

@@ -24,7 +24,7 @@ from cirq.protocols import qid_shape_protocol
 from cirq.protocols.apply_unitary_protocol import apply_unitaries, ApplyUnitaryArgs
 from cirq.protocols.decompose_protocol import _try_decompose_into_operations_and_qubits
 
-# This is a special indicator value used by the unitary method to determine
+# This is a special indicator value used by the function unitary() to determine
 # whether or not the caller provided a 'default' argument. It must be of type
 # np.ndarray 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
@@ -38,23 +38,23 @@ class SupportsUnitary(Protocol):
     """An object that may be describable by a unitary matrix."""
 
     @doc_private
-    def _unitary_(self) -> np.ndarray | NotImplementedType:
+    def _unitary_(self) -> np.ndarray | NotImplementedType | None:
         """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
         is not present, or returns NotImplemented, it is assumed that the
         receiving object doesn't have a unitary matrix (resulting in a TypeError
-        or default result when calling `cirq.unitary` on it). (The ability to
+        or default result when calling `cirq.unitary` on it). The ability to
         return NotImplemented is useful when a class cannot know if it has a
-        matrix until runtime, e.g. cirq.X**c normally has a matrix but
-        cirq.X**sympy.Symbol('a') doesn't.)
+        matrix until runtime; e.g., `cirq.X**c` normally has a matrix but
+        `cirq.X**sympy.Symbol('a')` doesn't.
 
         The order of cells in the matrix is always implicit with respect to the
-        object being called. For example, for gates the matrix must be ordered
+        object being called. For example, for gates, the matrix must be ordered
         with respect to the list of qubits that the gate is applied to. For
         operations, the matrix is ordered to match the list returned by its
         `qubits` attribute. The qubit-to-amplitude order mapping matches the
-        ordering of numpy.kron(A, B), where A is a qubit earlier in the list
+        ordering of `numpy.kron(A, B)`, where A is a qubit earlier in the list
         than the qubit B.
 
         Returns:
@@ -68,7 +68,7 @@ class SupportsUnitary(Protocol):
 
         This method is used by the global `cirq.has_unitary` method.  If this
         method is not present, or returns NotImplemented, it will fallback
-        to using _unitary_ with a default value, or False if neither exist.
+        to using `_unitary_()` with a default value, or False if neither exist.
 
         Returns:
             True if the value has a unitary matrix representation, False
@@ -81,17 +81,17 @@ def unitary(
 ) -> np.ndarray | TDefault:
     """Returns a unitary matrix describing the given value.
 
-    The matrix is determined by any one of the following techniques:
+    The matrix is determined by the first of these strategies that succeeds:
 
-    - 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.
+    - 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 an `_apply_unitary_` method, and it returns something
+        besides `None` or `NotImplemented`. The matrix is created by applying
+        `_apply_unitary_` to an identity matrix.
     - The value has a `_decompose_` method that returns a list of operations,
         and each operation in the list has a unitary effect. The matrix is
         created by aggregating the sub-operations' unitary effects.
-    - The value has an `_apply_unitary_` method, and it returns something
-        besides None or NotImplemented. The matrix is created by applying
-        `_apply_unitary_` to an identity matrix.
 
     If none of these techniques succeeds, it is assumed that `val` doesn't have
     a unitary effect. The order in which techniques are attempted is
@@ -100,8 +100,8 @@ def unitary(
     Args:
         val: The value to describe with a unitary matrix.
         default: Determines the fallback behavior when `val` doesn't have
-            a unitary effect. If `default` is not set, a TypeError is raised. If
-            `default` is set to a value, that value is returned.
+            a unitary effect. If `default` is not set, a `TypeError` is raised.
+            If `default` is set to a value, that value is returned.
 
     Returns:
         If `val` has a unitary effect, the corresponding unitary matrix.
@@ -135,13 +135,13 @@ def unitary(
         f"type: {type(val)}\n"
         f"value: {val!r}\n"
         "\n"
-        "The value failed to satisfy any of the following criteria:\n"
+        "The given value failed to satisfy any of the following criteria:\n"
         "- A `_unitary_(self)` method that returned a value "
-        "besides None or NotImplemented.\n"
+        "besides `None` or `NotImplemented`.\n"
         "- A `_decompose_(self)` method that returned a "
         "list of unitary operations.\n"
-        "- An `_apply_unitary_(self, args) method that returned a value "
-        "besides None or NotImplemented."
+        "- An `_apply_unitary_(self, args)` method that returned a value "
+        "besides `None` or `NotImplemented`."
     )
 
 

cirq/qis/channels.py

@@ -16,7 +16,7 @@
 
 from __future__ import annotations
 
-from typing import Sequence
+from collections.abc import Sequence
 
 import numpy as np