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

cirq/ops/linear_combinations.py

@@ -12,27 +12,14 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from __future__ import annotations
+
 import numbers
 from collections import defaultdict
-from typing import (
-    AbstractSet,
-    Any,
-    DefaultDict,
-    Dict,
-    FrozenSet,
-    Iterable,
-    List,
-    Mapping,
-    Optional,
-    Tuple,
-    TYPE_CHECKING,
-    Union,
-)
+from typing import AbstractSet, Any, Iterable, Mapping, TYPE_CHECKING, Union
 
 import numpy as np
-from scipy.sparse import csr_matrix
-from sympy.core.expr import Expr
-from sympy.core.symbol import Symbol
+import sympy
 from sympy.logic.boolalg import And, Not, Or, Xor
 
 from cirq import linalg, protocols, qis, value
@@ -44,9 +31,11 @@ from cirq.ops.projector import ProjectorString
 from cirq.value.linear_dict import _format_terms
 
 if TYPE_CHECKING:
+    from scipy.sparse import csr_matrix
+
     import cirq
 
-UnitPauliStringT = FrozenSet[Tuple[raw_types.Qid, pauli_gates.Pauli]]
+UnitPauliStringT = frozenset[tuple[raw_types.Qid, pauli_gates.Pauli]]
 PauliSumLike = Union[
     complex, PauliString, 'PauliSum', pauli_string.SingleQubitPauliStringGateOperation
 ]
@@ -81,7 +70,7 @@ class LinearCombinationOfGates(value.LinearDict[raw_types.Gate]):
         2 * cirq.X - 2 * cirq.Z
     """
 
-    def __init__(self, terms: Mapping[raw_types.Gate, 'cirq.TParamValComplex']) -> None:
+    def __init__(self, terms: Mapping[raw_types.Gate, cirq.TParamValComplex]) -> None:
         """Initializes linear combination from a collection of terms.
 
         Args:
@@ -90,45 +79,41 @@ class LinearCombinationOfGates(value.LinearDict[raw_types.Gate]):
         """
         super().__init__(terms, validator=self._is_compatible)
 
-    def num_qubits(self) -> Optional[int]:
+    def num_qubits(self) -> int | None:
         """Returns number of qubits in the domain if known, None if unknown."""
         if not self:
             return None
         any_gate = next(iter(self))
         return any_gate.num_qubits()
 
-    def _is_compatible(self, gate: 'cirq.Gate') -> bool:
+    def _is_compatible(self, gate: cirq.Gate) -> bool:
         return self.num_qubits() is None or self.num_qubits() == gate.num_qubits()
 
-    def __add__(
-        self, other: Union[raw_types.Gate, 'LinearCombinationOfGates']
-    ) -> 'LinearCombinationOfGates':
+    def __add__(self, other: raw_types.Gate | LinearCombinationOfGates) -> LinearCombinationOfGates:
         if not isinstance(other, LinearCombinationOfGates):
             other = other.wrap_in_linear_combination()
         return super().__add__(other)
 
     def __iadd__(
-        self, other: Union[raw_types.Gate, 'LinearCombinationOfGates']
-    ) -> 'LinearCombinationOfGates':
+        self, other: raw_types.Gate | LinearCombinationOfGates
+    ) -> LinearCombinationOfGates:
         if not isinstance(other, LinearCombinationOfGates):
             other = other.wrap_in_linear_combination()
         return super().__iadd__(other)
 
-    def __sub__(
-        self, other: Union[raw_types.Gate, 'LinearCombinationOfGates']
-    ) -> 'LinearCombinationOfGates':
+    def __sub__(self, other: raw_types.Gate | LinearCombinationOfGates) -> LinearCombinationOfGates:
         if not isinstance(other, LinearCombinationOfGates):
             other = other.wrap_in_linear_combination()
         return super().__sub__(other)
 
     def __isub__(
-        self, other: Union[raw_types.Gate, 'LinearCombinationOfGates']
-    ) -> 'LinearCombinationOfGates':
+        self, other: raw_types.Gate | LinearCombinationOfGates
+    ) -> LinearCombinationOfGates:
         if not isinstance(other, LinearCombinationOfGates):
             other = other.wrap_in_linear_combination()
         return super().__isub__(other)
 
-    def __pow__(self, exponent: int) -> 'LinearCombinationOfGates':
+    def __pow__(self, exponent: int) -> LinearCombinationOfGates:
         if not isinstance(exponent, int):
             return NotImplemented
         if exponent < 0:
@@ -155,8 +140,8 @@ class LinearCombinationOfGates(value.LinearDict[raw_types.Gate]):
         return {name for item in self.items() for name in protocols.parameter_names(item)}
 
     def _resolve_parameters_(
-        self, resolver: 'cirq.ParamResolver', recursive: bool
-    ) -> 'LinearCombinationOfGates':
+        self, resolver: cirq.ParamResolver, recursive: bool
+    ) -> LinearCombinationOfGates:
         return self.__class__(
             {
                 protocols.resolve_parameters(
@@ -224,7 +209,7 @@ class LinearCombinationOfOperations(value.LinearDict[raw_types.Operation]):
     by the identity operator. Note that A may not be unitary or even normal.
     """
 
-    def __init__(self, terms: Mapping[raw_types.Operation, 'cirq.TParamValComplex']) -> None:
+    def __init__(self, terms: Mapping[raw_types.Operation, cirq.TParamValComplex]) -> None:
         """Initializes linear combination from a collection of terms.
 
         Args:
@@ -233,11 +218,11 @@ class LinearCombinationOfOperations(value.LinearDict[raw_types.Operation]):
         """
         super().__init__(terms, validator=self._is_compatible)
 
-    def _is_compatible(self, operation: 'cirq.Operation') -> bool:
+    def _is_compatible(self, operation: cirq.Operation) -> bool:
         return isinstance(operation, raw_types.Operation)
 
     @property
-    def qubits(self) -> Tuple[raw_types.Qid, ...]:
+    def qubits(self) -> tuple[raw_types.Qid, ...]:
         """Returns qubits acted on self."""
         if not self:
             return ()
@@ -245,7 +230,7 @@ class LinearCombinationOfOperations(value.LinearDict[raw_types.Operation]):
         all_qubits = set.union(*qubit_sets)
         return tuple(sorted(all_qubits))
 
-    def __pow__(self, exponent: int) -> 'LinearCombinationOfOperations':
+    def __pow__(self, exponent: int) -> LinearCombinationOfOperations:
         if not isinstance(exponent, int):
             return NotImplemented
         if exponent < 0:
@@ -272,8 +257,8 @@ class LinearCombinationOfOperations(value.LinearDict[raw_types.Operation]):
         return {name for item in self.items() for name in protocols.parameter_names(item)}
 
     def _resolve_parameters_(
-        self, resolver: 'cirq.ParamResolver', recursive: bool
-    ) -> 'LinearCombinationOfOperations':
+        self, resolver: cirq.ParamResolver, recursive: bool
+    ) -> LinearCombinationOfOperations:
         return self.__class__(
             {
                 protocols.resolve_parameters(op, resolver, recursive): protocols.resolve_parameters(
@@ -300,7 +285,7 @@ class LinearCombinationOfOperations(value.LinearDict[raw_types.Operation]):
             workspace = np.empty_like(identity)
             axes = tuple(qubit_to_axis[q] for q in op.qubits)
             u = protocols.apply_unitary(op, protocols.ApplyUnitaryArgs(identity, workspace, axes))
-            result += coefficient * u
+            result += complex(coefficient) * u
         return result.reshape((num_dim, num_dim))
 
     def _has_unitary_(self) -> bool:
@@ -317,7 +302,7 @@ class LinearCombinationOfOperations(value.LinearDict[raw_types.Operation]):
         """Computes Pauli expansion of self from Pauli expansions of terms."""
 
         def extend_term(
-            pauli_names: str, qubits: Tuple['cirq.Qid', ...], all_qubits: Tuple['cirq.Qid', ...]
+            pauli_names: str, qubits: tuple[cirq.Qid, ...], all_qubits: tuple[cirq.Qid, ...]
         ) -> str:
             """Extends Pauli product on qubits to product on all_qubits."""
             assert len(pauli_names) == len(qubits)
@@ -326,8 +311,8 @@ class LinearCombinationOfOperations(value.LinearDict[raw_types.Operation]):
 
         def extend(
             expansion: value.LinearDict[str],
-            qubits: Tuple['cirq.Qid', ...],
-            all_qubits: Tuple['cirq.Qid', ...],
+            qubits: tuple[cirq.Qid, ...],
+            all_qubits: tuple[cirq.Qid, ...],
         ) -> value.LinearDict[str]:
             """Extends Pauli expansion on qubits to expansion on all_qubits."""
             return value.LinearDict(
@@ -358,7 +343,7 @@ def _is_linear_dict_of_unit_pauli_string(linear_dict: value.LinearDict[UnitPauli
 
 
 def _pauli_string_from_unit(
-    unit: UnitPauliStringT, coefficient: Union[int, float, 'cirq.TParamValComplex'] = 1
+    unit: UnitPauliStringT, coefficient: int | float | cirq.TParamValComplex = 1
 ):
     return PauliString(qubit_pauli_map=dict(unit), coefficient=coefficient)
 
@@ -416,7 +401,7 @@ class PauliSum:
     4.0+0.0j
     """
 
-    def __init__(self, linear_dict: Optional[value.LinearDict[UnitPauliStringT]] = None):
+    def __init__(self, linear_dict: value.LinearDict[UnitPauliStringT] | None = None):
         """Construct a PauliSum from a linear dictionary.
 
         Note, the preferred method of constructing PauliSum objects is either implicitly
@@ -444,7 +429,7 @@ class PauliSum:
         return self._linear_dict
 
     @staticmethod
-    def wrap(val: PauliSumLike) -> 'PauliSum':
+    def wrap(val: PauliSumLike) -> PauliSum:
         """Convert a `cirq.PauliSumLike` object to a PauliSum
 
         Attempts to convert an existing int, float, complex, `cirq.PauliString`,
@@ -468,7 +453,7 @@ class PauliSum:
         return PauliSum() + val
 
     @classmethod
-    def from_pauli_strings(cls, terms: Union[PauliString, List[PauliString]]) -> 'PauliSum':
+    def from_pauli_strings(cls, terms: PauliString | list[PauliString]) -> PauliSum:
         """Returns a PauliSum by combining `cirq.PauliString` terms.
 
         Args:
@@ -480,7 +465,7 @@ class PauliSum:
         """
         if isinstance(terms, PauliString):
             terms = [terms]
-        termdict: DefaultDict[UnitPauliStringT, value.Scalar] = defaultdict(lambda: 0)
+        termdict: defaultdict[UnitPauliStringT, value.Scalar] = defaultdict(lambda: 0)
         for pstring in terms:
             key = frozenset(pstring._qubit_pauli_map.items())
             termdict[key] += pstring.coefficient
@@ -488,8 +473,8 @@ class PauliSum:
 
     @classmethod
     def from_boolean_expression(
-        cls, boolean_expr: Expr, qubit_map: Dict[str, 'cirq.Qid']
-    ) -> 'PauliSum':
+        cls, boolean_expr: sympy.Expr, qubit_map: dict[str, cirq.Qid]
+    ) -> PauliSum:
         """Builds the Hamiltonian representation of a Boolean expression.
 
         This is based on "On the representation of Boolean and real functions as Hamiltonians for
@@ -505,7 +490,7 @@ class PauliSum:
         Raises:
             ValueError: If `boolean_expr` is of an unsupported type.
         """
-        if isinstance(boolean_expr, Symbol):
+        if isinstance(boolean_expr, sympy.Symbol):
             # In table 1, the entry for 'x' is '1/2.I - 1/2.Z'
             return cls.from_pauli_strings(
                 [
@@ -540,12 +525,12 @@ class PauliSum:
         raise ValueError(f'Unsupported type: {type(boolean_expr)}')
 
     @property
-    def qubits(self) -> Tuple[raw_types.Qid, ...]:
+    def qubits(self) -> tuple[raw_types.Qid, ...]:
         """The sorted list of qubits used in this PauliSum."""
         qs = {q for k in self._linear_dict.keys() for q, _ in k}
         return tuple(sorted(qs))
 
-    def with_qubits(self, *new_qubits: 'cirq.Qid') -> 'PauliSum':
+    def with_qubits(self, *new_qubits: cirq.Qid) -> PauliSum:
         """Return a new PauliSum on `new_qubits`.
 
         Args:
@@ -569,7 +554,7 @@ class PauliSum:
             new_pauli_strings.append(pauli_string.map_qubits(qubit_map))
         return PauliSum.from_pauli_strings(new_pauli_strings)
 
-    def copy(self) -> 'PauliSum':
+    def copy(self) -> PauliSum:
         """Return a copy of this PauliSum.
 
         Returns: A copy of this PauliSum.
@@ -577,7 +562,7 @@ class PauliSum:
         factory = type(self)
         return factory(self._linear_dict.copy())
 
-    def matrix(self, qubits: Optional[Iterable[raw_types.Qid]] = None) -> np.ndarray:
+    def matrix(self, qubits: Iterable[raw_types.Qid] | None = None) -> np.ndarray:
         """Returns the matrix of this PauliSum in computational basis of qubits.
 
         Args:
@@ -761,6 +746,10 @@ class PauliSum:
             other = PauliSum.from_pauli_strings([PauliString(coefficient=other)])
         elif isinstance(other, PauliString):
             other = PauliSum.from_pauli_strings([other])
+        elif isinstance(other, raw_types.Operation) and isinstance(
+            other.gate, identity.IdentityGate
+        ):
+            other = PauliSum.from_pauli_strings([PauliString()])
 
         if not isinstance(other, PauliSum):
             return NotImplemented
@@ -769,11 +758,8 @@ class PauliSum:
         return self
 
     def __add__(self, other):
-        if not isinstance(other, (numbers.Complex, PauliString, PauliSum)):
-            if hasattr(other, 'gate') and isinstance(other.gate, identity.IdentityGate):
-                other = PauliString(other)
-            else:
-                return NotImplemented
+        if not isinstance(other, (numbers.Complex, PauliString, PauliSum, raw_types.Operation)):
+            return NotImplemented
         result = self.copy()
         result += other
         return result
@@ -787,8 +773,12 @@ class PauliSum:
     def __isub__(self, other):
         if isinstance(other, numbers.Complex):
             other = PauliSum.from_pauli_strings([PauliString(coefficient=other)])
-        if isinstance(other, PauliString):
+        elif isinstance(other, PauliString):
             other = PauliSum.from_pauli_strings([other])
+        elif isinstance(other, raw_types.Operation) and isinstance(
+            other.gate, identity.IdentityGate
+        ):
+            other = PauliSum.from_pauli_strings([PauliString()])
 
         if not isinstance(other, PauliSum):
             return NotImplemented
@@ -797,7 +787,7 @@ class PauliSum:
         return self
 
     def __sub__(self, other):
-        if not isinstance(other, (numbers.Complex, PauliString, PauliSum)):
+        if not isinstance(other, (numbers.Complex, PauliString, PauliSum, raw_types.Operation)):
             return NotImplemented
         result = self.copy()
         result -= other
@@ -881,7 +871,7 @@ class ProjectorSum:
     """List of mappings representing a sum of projector operators."""
 
     def __init__(
-        self, linear_dict: Optional[value.LinearDict[FrozenSet[Tuple[raw_types.Qid, int]]]] = None
+        self, linear_dict: value.LinearDict[frozenset[tuple[raw_types.Qid, int]]] | None = None
     ):
         """Constructor for ProjectorSum
 
@@ -890,7 +880,7 @@ class ProjectorSum:
                 number. The tuple is a projector onto the qubit and the complex number is the
                 weight of these projections.
         """
-        self._linear_dict: value.LinearDict[FrozenSet[Tuple[raw_types.Qid, int]]] = (
+        self._linear_dict: value.LinearDict[frozenset[tuple[raw_types.Qid, int]]] = (
             linear_dict if linear_dict is not None else value.LinearDict({})
         )
 
@@ -898,11 +888,11 @@ class ProjectorSum:
         return self._linear_dict
 
     @property
-    def qubits(self) -> Tuple[raw_types.Qid, ...]:
+    def qubits(self) -> tuple[raw_types.Qid, ...]:
         qs = {q for k in self._linear_dict.keys() for q, _ in k}
         return tuple(sorted(qs))
 
-    def _json_dict_(self) -> Dict[str, Any]:
+    def _json_dict_(self) -> dict[str, Any]:
         linear_dict = []
         for projector_dict, scalar in dict(self._linear_dict).items():
             key = [[k, v] for k, v in dict(projector_dict).items()]
@@ -920,9 +910,7 @@ class ProjectorSum:
         return cls(linear_dict=value.LinearDict(converted_dict))
 
     @classmethod
-    def from_projector_strings(
-        cls, terms: Union[ProjectorString, List[ProjectorString]]
-    ) -> 'ProjectorSum':
+    def from_projector_strings(cls, terms: ProjectorString | list[ProjectorString]) -> ProjectorSum:
         """Builds a ProjectorSum from one or more ProjectorString(s).
 
         Args:
@@ -933,7 +921,7 @@ class ProjectorSum:
         """
         if isinstance(terms, ProjectorString):
             terms = [terms]
-        termdict: DefaultDict[FrozenSet[Tuple[raw_types.Qid, int]], value.Scalar] = defaultdict(
+        termdict: defaultdict[frozenset[tuple[raw_types.Qid, int]], value.Scalar] = defaultdict(
             lambda: 0.0
         )
         for pstring in terms:
@@ -941,10 +929,10 @@ class ProjectorSum:
             termdict[key] += pstring.coefficient
         return cls(linear_dict=value.LinearDict(termdict))
 
-    def copy(self) -> 'ProjectorSum':
+    def copy(self) -> ProjectorSum:
         return ProjectorSum(self._linear_dict.copy())
 
-    def matrix(self, projector_qids: Optional[Iterable[raw_types.Qid]] = None) -> csr_matrix:
+    def matrix(self, projector_qids: Iterable[raw_types.Qid] | None = None) -> csr_matrix:
         """Returns the matrix of self in computational basis of qubits.
 
         Args:
@@ -1022,7 +1010,7 @@ class ProjectorSum:
     def __bool__(self) -> bool:
         return bool(self._linear_dict)
 
-    def __iadd__(self, other: Union['ProjectorString', 'ProjectorSum']):
+    def __iadd__(self, other: ProjectorString | ProjectorSum):
         if isinstance(other, ProjectorString):
             other = ProjectorSum.from_projector_strings(other)
         elif not isinstance(other, ProjectorSum):
@@ -1030,7 +1018,7 @@ class ProjectorSum:
         self._linear_dict += other._linear_dict
         return self
 
-    def __add__(self, other: Union['ProjectorString', 'ProjectorSum']):
+    def __add__(self, other: ProjectorString | ProjectorSum):
         if isinstance(other, ProjectorString):
             other = ProjectorSum.from_projector_strings(other)
         elif not isinstance(other, ProjectorSum):
@@ -1039,7 +1027,7 @@ class ProjectorSum:
         result += other
         return result
 
-    def __isub__(self, other: Union['ProjectorString', 'ProjectorSum']):
+    def __isub__(self, other: ProjectorString | ProjectorSum):
         if isinstance(other, ProjectorString):
             other = ProjectorSum.from_projector_strings(other)
         elif not isinstance(other, ProjectorSum):
@@ -1047,7 +1035,7 @@ class ProjectorSum:
         self._linear_dict -= other._linear_dict
         return self
 
-    def __sub__(self, other: Union['ProjectorString', 'ProjectorSum']):
+    def __sub__(self, other: ProjectorString | ProjectorSum):
         if isinstance(other, ProjectorString):
             other = ProjectorSum.from_projector_strings(other)
         elif not isinstance(other, ProjectorSum):

cirq/ops/linear_combinations_test.py

@@ -12,8 +12,9 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from __future__ import annotations
+
 import collections
-from typing import Union
 
 import numpy as np
 import pytest
@@ -228,12 +229,12 @@ def test_parameterized_linear_combination_of_gates(
 
 
 def get_matrix(
-    operator: Union[
-        cirq.Gate,
-        cirq.GateOperation,
-        cirq.LinearCombinationOfGates,
-        cirq.LinearCombinationOfOperations,
-    ],
+    operator: (
+        cirq.Gate
+        | cirq.GateOperation
+        | cirq.LinearCombinationOfGates
+        | cirq.LinearCombinationOfOperations
+    ),
 ) -> np.ndarray:
     if isinstance(operator, (cirq.LinearCombinationOfGates, cirq.LinearCombinationOfOperations)):
         return operator.matrix()
@@ -241,8 +242,8 @@ def get_matrix(
 
 
 def assert_linear_combinations_are_equal(
-    actual: Union[cirq.LinearCombinationOfGates, cirq.LinearCombinationOfOperations],
-    expected: Union[cirq.LinearCombinationOfGates, cirq.LinearCombinationOfOperations],
+    actual: cirq.LinearCombinationOfGates | cirq.LinearCombinationOfOperations,
+    expected: cirq.LinearCombinationOfGates | cirq.LinearCombinationOfOperations,
 ) -> None:
     if not actual and not expected:
         assert len(actual) == 0
@@ -970,6 +971,10 @@ def test_paulisum_validation():
     ps += cirq.I(cirq.LineQubit(0))
     assert ps == cirq.PauliSum(cirq.LinearDict({frozenset(): complex(1)}))
 
+    ps = cirq.PauliSum()
+    ps -= cirq.I(cirq.LineQubit(0))
+    assert ps == cirq.PauliSum(cirq.LinearDict({frozenset(): complex(-1)}))
+
 
 def test_add_number_paulisum():
     q = cirq.LineQubit.range(2)

cirq/ops/matrix_gates.py

@@ -14,13 +14,15 @@
 
 """Quantum gates defined by a matrix."""
 
-from typing import Any, Dict, Iterable, List, Optional, Tuple, TYPE_CHECKING
+from __future__ import annotations
+
+from typing import Any, Iterable, TYPE_CHECKING
 
 import numpy as np
 
 from cirq import _import, linalg, protocols
 from cirq._compat import proper_repr
-from cirq.ops import global_phase_op, identity, phased_x_z_gate, raw_types
+from cirq.ops import global_phase_op, phased_x_z_gate, raw_types
 
 if TYPE_CHECKING:
     import cirq
@@ -53,8 +55,8 @@ class MatrixGate(raw_types.Gate):
         self,
         matrix: np.ndarray,
         *,
-        name: Optional[str] = None,
-        qid_shape: Optional[Iterable[int]] = None,
+        name: str | None = None,
+        qid_shape: Iterable[int] | None = None,
         unitary_check: bool = True,
         unitary_check_rtol: float = 1e-5,
         unitary_check_atol: float = 1e-8,
@@ -109,11 +111,11 @@ class MatrixGate(raw_types.Gate):
         ):
             raise ValueError(f'Not a unitary matrix: {matrix}')
 
-    def with_name(self, name: str) -> 'MatrixGate':
+    def with_name(self, name: str) -> MatrixGate:
         """Creates a new MatrixGate with the same matrix and a new name."""
         return MatrixGate(self._matrix, name=name, qid_shape=self._qid_shape, unitary_check=False)
 
-    def _json_dict_(self) -> Dict[str, Any]:
+    def _json_dict_(self) -> dict[str, Any]:
         return {
             'matrix': self._matrix.tolist(),
             'qid_shape': self._qid_shape,
@@ -124,16 +126,16 @@ class MatrixGate(raw_types.Gate):
     def _from_json_dict_(cls, matrix, qid_shape, name=None, **kwargs):
         return cls(matrix=np.array(matrix), qid_shape=qid_shape, name=name)
 
-    def _qid_shape_(self) -> Tuple[int, ...]:
+    def _qid_shape_(self) -> tuple[int, ...]:
         return self._qid_shape
 
-    def __pow__(self, exponent: Any) -> 'MatrixGate':
+    def __pow__(self, exponent: Any) -> MatrixGate:
         if not isinstance(exponent, (int, float)):
             return NotImplemented
         new_mat = linalg.map_eigenvalues(self._matrix, lambda b: b**exponent)
         return MatrixGate(new_mat, qid_shape=self._qid_shape)
 
-    def _phase_by_(self, phase_turns: float, qubit_index: int) -> 'MatrixGate':
+    def _phase_by_(self, phase_turns: float, qubit_index: int) -> MatrixGate:
         if not isinstance(phase_turns, (int, float)):
             return NotImplemented
         if self._qid_shape[qubit_index] != 2:
@@ -147,10 +149,10 @@ class MatrixGate(raw_types.Gate):
         result[linalg.slice_for_qubits_equal_to([j], 1)] *= np.conj(p)
         return MatrixGate(matrix=result.reshape(self._matrix.shape), qid_shape=self._qid_shape)
 
-    def _decompose_(self, qubits: Tuple['cirq.Qid', ...]) -> 'cirq.OP_TREE':
+    def _decompose_(self, qubits: tuple[cirq.Qid, ...]) -> cirq.OP_TREE:
         from cirq.circuits import Circuit
 
-        decomposed: List['cirq.Operation'] = NotImplemented
+        decomposed: list[cirq.Operation] = NotImplemented
         if self._qid_shape == (2,):
             decomposed = [
                 g.on(qubits[0])
@@ -168,8 +170,8 @@ class MatrixGate(raw_types.Gate):
             return NotImplemented
         # The above algorithms ignore phase, but phase is important to maintain if the gate is
         # controlled. Here, we add it back in with a global phase op.
-        ident = identity.IdentityGate(qid_shape=self._qid_shape).on(*qubits)  # Preserve qid order
-        u = protocols.unitary(Circuit(ident, *decomposed)).reshape(self._matrix.shape)
+        circuit = Circuit(*decomposed)
+        u = circuit.unitary(qubit_order=qubits, qubits_that_should_be_present=qubits)
         phase_delta = linalg.phase_delta(u, self._matrix)
         # Phase delta is on the complex unit circle, so if real(phase_delta) >= 1, that means
         # no phase delta. (>1 is rounding error).
@@ -183,10 +185,11 @@ class MatrixGate(raw_types.Gate):
     def _unitary_(self) -> np.ndarray:
         return np.copy(self._matrix)
 
-    def _circuit_diagram_info_(
-        self, args: 'cirq.CircuitDiagramInfoArgs'
-    ) -> 'cirq.CircuitDiagramInfo':
+    def _circuit_diagram_info_(self, args: cirq.CircuitDiagramInfoArgs) -> cirq.CircuitDiagramInfo:
         n_qubits = len(self._qid_shape)
+        # No diagram for zero-qubit gates; let fallback handle it
+        if n_qubits == 0:
+            return NotImplemented
         if self._name is not None:
             symbols = (
                 [self._name] if n_qubits == 1 else [f'{self._name}[{i+1}]' for i in range(n_qubits)]
@@ -196,7 +199,7 @@ class MatrixGate(raw_types.Gate):
         rest = [f'#{i+1}' for i in range(1, n_qubits)]
         return protocols.CircuitDiagramInfo(wire_symbols=[main, *rest])
 
-    def _qasm_(self, args: 'cirq.QasmArgs', qubits: Tuple['cirq.Qid', ...]) -> Optional[str]:
+    def _qasm_(self, args: cirq.QasmArgs, qubits: tuple[cirq.Qid, ...]) -> str | None:
         args.validate_version('2.0', '3.0')
         if self._qid_shape == (2,):
             return protocols.qasm(
@@ -230,7 +233,7 @@ class MatrixGate(raw_types.Gate):
         return str(self._matrix.round(3))
 
 
-def _matrix_to_diagram_symbol(matrix: np.ndarray, args: 'protocols.CircuitDiagramInfoArgs') -> str:
+def _matrix_to_diagram_symbol(matrix: np.ndarray, args: protocols.CircuitDiagramInfoArgs) -> str:
     if args.precision is not None:
         matrix = matrix.round(args.precision)
     result = str(matrix)

cirq/ops/matrix_gates_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 re
 
 import numpy as np
@@ -410,3 +413,16 @@ def test_matrixgate_name_serialization():
     gate_after_serialization3 = cirq.read_json(json_text=cirq.to_json(gate3))
     assert gate3._name == ''
     assert gate_after_serialization3._name == ''
+
+
+def test_decompose_when_qubits_not_in_ascending_order():
+    # Previous code for preserving global phase would misorder qubits
+    q0, q1 = cirq.LineQubit.range(2)
+    circuit1 = cirq.Circuit()
+    matrix = cirq.testing.random_unitary(4, random_state=0)
+    circuit1.append(cirq.MatrixGate(matrix).on(q1, q0))
+    u1 = cirq.unitary(circuit1)
+    decomposed = cirq.decompose(circuit1)
+    circuit2 = cirq.Circuit(decomposed)
+    u2 = cirq.unitary(circuit2)
+    np.testing.assert_allclose(u1, u2, atol=1e-14)