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

cirq/transformers/analytical_decompositions/quantum_shannon_decomposition.py

@@ -12,36 +12,43 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-
 """Utility methods for decomposing arbitrary n-qubit (2^n x 2^n) unitary.
 
 Based on:
 Synthesis of Quantum Logic Circuits. Tech. rep. 2006,
 https://arxiv.org/abs/quant-ph/0406176
 """
-from typing import Callable, Iterable, List, TYPE_CHECKING
+
+from __future__ import annotations
+
+from typing import Callable, cast, Iterable, TYPE_CHECKING
 
 import numpy as np
+from attr import define
 from scipy.linalg import cossin
 
 from cirq import ops
 from cirq.circuits.frozen_circuit import FrozenCircuit
 from cirq.linalg import decompositions, predicates
 from cirq.protocols import unitary_protocol
-from cirq.transformers.analytical_decompositions.three_qubit_decomposition import (
-    three_qubit_matrix_to_operations,
-)
 from cirq.transformers.analytical_decompositions.two_qubit_to_cz import (
     two_qubit_matrix_to_cz_operations,
+    two_qubit_matrix_to_diagonal_and_cz_operations,
 )
 
 if TYPE_CHECKING:
     import cirq
 
 
+@define
+class _TwoQubitGate:
+    location: int
+    matrix: np.ndarray
+
+
 def quantum_shannon_decomposition(
-    qubits: 'List[cirq.Qid]', u: np.ndarray, atol: float = 1e-8
-) -> Iterable['cirq.Operation']:
+    qubits: list[cirq.Qid], u: np.ndarray, atol: float = 1e-8
+) -> Iterable[cirq.Operation]:
     """Decomposes n-qubit unitary 1-q, 2-q and GlobalPhase gates, preserving global phase.
 
     The gates used are CX/YPow/ZPow/CNOT/GlobalPhase/CZ/PhasedXZGate/PhasedXPowGate.
@@ -65,14 +72,12 @@ def quantum_shannon_decomposition(
         1. _single_qubit_decomposition
             OR
         (Recursive Case)
-        1. _msb_demuxer
-        2. _multiplexed_cossin
-        3. _msb_demuxer
+        1. _recursive_decomposition
 
     Yields:
         A single 2-qubit or 1-qubit operations from OP TREE
         composed from the set
-           { CNOT, rz, ry, ZPowGate }
+           { CNOT, CZ, rz, ry, ZPowGate }
 
     Raises:
         ValueError: If the u matrix is non-unitary
@@ -96,30 +101,92 @@ def quantum_shannon_decomposition(
         yield from _single_qubit_decomposition(qubits[0], u)
         return
 
-    if n == 4:
-        operations = tuple(
-            two_qubit_matrix_to_cz_operations(
-                qubits[0], qubits[1], u, allow_partial_czs=True, clean_operations=True, atol=atol
-            )
+    # Collect all operations from the recursive decomposition
+    shannon_decomp: list[cirq.Operation | list[cirq.Operation]] = [
+        *_recursive_decomposition(qubits, u)
+    ]
+    # Separate all 2-qubit generic gates while keeping track of location
+    two_qubit_gates = [
+        _TwoQubitGate(location=loc, matrix=unitary_protocol.unitary(o))
+        for loc, o in enumerate(cast(list[ops.Operation], shannon_decomp))
+        if isinstance(o.gate, ops.MatrixGate)
+    ]
+    # Apply case A.2 from Shende et al.
+    q0 = qubits[-2]
+    q1 = qubits[-1]
+    for idx in range(len(two_qubit_gates) - 1, 0, -1):
+        diagonal, operations = two_qubit_matrix_to_diagonal_and_cz_operations(
+            q0,
+            q1,
+            two_qubit_gates[idx].matrix,
+            allow_partial_czs=True,
+            clean_operations=True,
+            atol=atol,
         )
-        yield from operations
-        i, j = np.unravel_index(np.argmax(np.abs(u)), u.shape)
-        new_unitary = unitary_protocol.unitary(FrozenCircuit.from_moments(*operations))
-        global_phase = np.angle(u[i, j]) - np.angle(new_unitary[i, j])
-        if np.abs(global_phase) > 1e-9:
-            yield ops.global_phase_operation(np.exp(1j * global_phase))
-        return
+        global_phase = _global_phase_difference(
+            two_qubit_gates[idx].matrix, [ops.MatrixGate(diagonal)(q0, q1), *operations]
+        )
+        if not np.isclose(global_phase, 0, atol=atol):
+            operations.append(ops.global_phase_operation(np.exp(1j * global_phase)))
+        # Replace the generic gate with ops from OP TREE
+        shannon_decomp[two_qubit_gates[idx].location] = operations
+        # Join the diagonal with the unitary to be decomposed in the next step
+        two_qubit_gates[idx - 1].matrix = diagonal @ two_qubit_gates[idx - 1].matrix
+    if len(two_qubit_gates) > 0:
+        operations = two_qubit_matrix_to_cz_operations(
+            q0,
+            q1,
+            two_qubit_gates[0].matrix,
+            allow_partial_czs=True,
+            clean_operations=True,
+            atol=atol,
+        )
+        global_phase = _global_phase_difference(two_qubit_gates[0].matrix, operations)
+        if not np.isclose(global_phase, 0, atol=atol):
+            operations.append(ops.global_phase_operation(np.exp(1j * global_phase)))
+        shannon_decomp[two_qubit_gates[0].location] = operations
+    # Yield the final operations in order
+    yield from cast(Iterable[ops.Operation], ops.flatten_op_tree(shannon_decomp))
+
+
+def _recursive_decomposition(qubits: list[cirq.Qid], u: np.ndarray) -> Iterable[cirq.Operation]:
+    """Recursive step in the quantum shannon decomposition.
 
-    if n == 8:
-        operations = tuple(
-            three_qubit_matrix_to_operations(qubits[0], qubits[1], qubits[2], u, atol=atol)
+    Decomposes n-qubit unitary into generic 2-qubit gates, CNOT, CZ and 1-qubit gates.
+    All generic 2-qubit gates are applied to the two least significant qubits and
+    are not decomposed further here.
+
+    Args:
+        qubits: List of qubits in order of significance
+        u: Numpy array for unitary matrix representing gate to be decomposed
+
+    Calls:
+        1. _msb_demuxer
+        2. _multiplexed_cossin
+        3. _msb_demuxer
+
+    Yields:
+        Generic 2-qubit gates or operations from {ry,rz,CNOT,CZ}.
+
+    Raises:
+        ValueError: If the u matrix is not of shape (2^n,2^n)
+        ValueError: If the u matrix is not of size at least 4
+    """
+    n = u.shape[0]
+    if n & (n - 1):
+        raise ValueError(
+            f"Expected input matrix u to be a (2^n x 2^n) shaped numpy array, \
+                but instead got shape {u.shape}"
+        )
+
+    if n <= 2:
+        raise ValueError(
+            f"Expected input matrix u for recursive step to have size at least 4, \
+                but it has size {n}"
         )
-        yield from operations
-        i, j = np.unravel_index(np.argmax(np.abs(u)), u.shape)
-        new_unitary = unitary_protocol.unitary(FrozenCircuit.from_moments(*operations))
-        global_phase = np.angle(u[i, j]) - np.angle(new_unitary[i, j])
-        if np.abs(global_phase) > 1e-9:
-            yield ops.global_phase_operation(np.exp(1j * global_phase))
+
+    if n == 4:
+        yield ops.MatrixGate(u).on(*qubits)
         return
 
     # Perform a cosine-sine (linalg) decomposition on u
@@ -135,11 +202,31 @@ def quantum_shannon_decomposition(
     # Yield ops from multiplexed Ry part
     yield from _multiplexed_cossin(qubits, theta, ops.ry)
 
+    # Optimization A.1 in Shende et al. - the last CZ gate in the multiplexed Ry part
+    # is merged into the generic multiplexor (u1, u2)
+    # This gate is CZ(qubits[1], qubits[0]) = CZ(qubits[0], qubits[1])
+    # as CZ is symmetric.
+    # For the u1⊕u2 multiplexor operator:
+    # as u1 is the operator in case qubits[0] = |0>,
+    # and u2 is the operator in case qubits[0] = |1>
+    # we can represent the merge by phasing u2 with Z ⊗ I
+    cz_diag = np.concatenate((np.ones(n >> 2), np.full(n >> 2, -1)))
+    u2 = u2 @ np.diag(cz_diag)
+
     # Yield ops from decomposition of multiplexed u1/u2 part
     yield from _msb_demuxer(qubits, u1, u2)
 
 
-def _single_qubit_decomposition(qubit: 'cirq.Qid', u: np.ndarray) -> Iterable['cirq.Operation']:
+def _global_phase_difference(u: np.ndarray, ops: list[cirq.Operation]) -> float:
+    """Returns the difference in global phase between unitary u and
+    a list of operations computing u.
+    """
+    i, j = np.unravel_index(np.argmax(np.abs(u)), u.shape)
+    new_unitary = unitary_protocol.unitary(FrozenCircuit.from_moments(*ops))
+    return np.angle(u[i, j]) - np.angle(new_unitary[i, j])
+
+
+def _single_qubit_decomposition(qubit: cirq.Qid, u: np.ndarray) -> Iterable[cirq.Operation]:
     """Decomposes single-qubit gate, and returns list of operations, keeping phase invariant.
 
     Args:
@@ -183,8 +270,8 @@ def _single_qubit_decomposition(qubit: 'cirq.Qid', u: np.ndarray) -> Iterable['c
 
 
 def _msb_demuxer(
-    demux_qubits: 'List[cirq.Qid]', u1: np.ndarray, u2: np.ndarray
-) -> Iterable['cirq.Operation']:
+    demux_qubits: list[cirq.Qid], u1: np.ndarray, u2: np.ndarray
+) -> Iterable[cirq.Operation]:
     """Demultiplexes a unitary matrix that is multiplexed in its most-significant-qubit.
 
     Decomposition structure:
@@ -200,11 +287,14 @@ def _msb_demuxer(
         u2: Lower-right quadrant of total unitary to be decomposed (see diagram)
 
     Calls:
-        1. quantum_shannon_decomposition
+        1. _recursive_decomposition
         2. _multiplexed_cossin
-        3. quantum_shannon_decomposition
+        3. _recursive_decomposition
 
-    Yields: Single operation from OP TREE of 2-qubit and 1-qubit operations
+    Yields:
+        Generic 2-qubit gates on the two least significant qubits,
+        CNOT gates with the target not on the two least significant qubits,
+        ry or rz
     """
     # Perform a diagonalization to find values
     u1 = u1.astype(np.complex128)
@@ -229,7 +319,7 @@ def _msb_demuxer(
     # Last term is given by ( I ⊗ W ), demultiplexed
     # Remove most-significant (demuxed) control-qubit
     # Yield operations for QSD on W
-    yield from quantum_shannon_decomposition(demux_qubits[1:], W, atol=1e-6)
+    yield from _recursive_decomposition(demux_qubits[1:], W)
 
     # Use complex phase of d_i to give theta_i (so d_i* gives -theta_i)
     # Observe that middle part looks like Σ_i( Rz(theta_i)⊗|i><i| )
@@ -237,7 +327,7 @@ def _msb_demuxer(
     yield from _multiplexed_cossin(demux_qubits, -np.angle(d), ops.rz)
 
     # Yield operations for QSD on V
-    yield from quantum_shannon_decomposition(demux_qubits[1:], V, atol=1e-6)
+    yield from _recursive_decomposition(demux_qubits[1:], V)
 
 
 def _nth_gray(n: int) -> int:
@@ -246,8 +336,8 @@ def _nth_gray(n: int) -> int:
 
 
 def _multiplexed_cossin(
-    cossin_qubits: 'List[cirq.Qid]', angles: List[float], rot_func: Callable = ops.ry
-) -> Iterable['cirq.Operation']:
+    cossin_qubits: list[cirq.Qid], angles: list[float], rot_func: Callable = ops.ry
+) -> Iterable[cirq.Operation]:
     """Performs a multiplexed rotation over all qubits in this unitary matrix,
 
     Uses ry and rz multiplexing for quantum shannon decomposition
@@ -261,7 +351,7 @@ def _multiplexed_cossin(
     Calls:
         No major calls
 
-    Yields: Single operation from OP TREE from set 1- and 2-qubit gates: {ry,rz,CNOT}
+    Yields: Single operation from OP TREE from set 1- and 2-qubit gates: {ry,rz,CNOT,CZ}
     """
     # Most significant qubit is main qubit with rotation function applied
     main_qubit = cossin_qubits[0]
@@ -302,4 +392,11 @@ def _multiplexed_cossin(
             yield rot_func(rotation).on(main_qubit)
 
         # Add a CNOT from the select qubit to the main qubit
-        yield ops.CNOT(control_qubits[select_qubit], main_qubit)
+        # Optimization A.1 in Shende et al. - use CZ instead of CNOT for ry rotations
+        if rot_func == ops.ry:
+            # Don't emit the last gate, as it will be merged into the generic multiplexor
+            # in the cosine-sine decomposition
+            if j < len(angles) - 1:
+                yield ops.CZ(control_qubits[select_qubit], main_qubit)
+        else:
+            yield ops.CNOT(control_qubits[select_qubit], main_qubit)

cirq/transformers/analytical_decompositions/quantum_shannon_decomposition_test.py

@@ -12,16 +12,20 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from __future__ import annotations
+
 import numpy as np
 import pytest
 from scipy.stats import unitary_group
 
 import cirq
 from cirq.ops import common_gates
+from cirq.testing import random_two_qubit_circuit_with_czs
 from cirq.transformers.analytical_decompositions.quantum_shannon_decomposition import (
     _msb_demuxer,
     _multiplexed_cossin,
     _nth_gray,
+    _recursive_decomposition,
     _single_qubit_decomposition,
     quantum_shannon_decomposition,
 )
@@ -47,6 +51,14 @@ def test_qsd_n_qubit_errors():
         cirq.Circuit(quantum_shannon_decomposition(qubits, np.ones((8, 8))))
 
 
+def test_recursive_decomposition_n_qubit_errors():
+    qubits = [cirq.NamedQubit(f'q{i}') for i in range(3)]
+    with pytest.raises(ValueError, match="shaped numpy array"):
+        cirq.Circuit(_recursive_decomposition(qubits, np.eye(9)))
+    with pytest.raises(ValueError, match="size at least 4"):
+        cirq.Circuit(_recursive_decomposition(qubits, np.eye(2)))
+
+
 def test_random_single_qubit_decomposition():
     U = unitary_group.rvs(2)
     qubit = cirq.NamedQubit('q0')
@@ -78,10 +90,18 @@ def test_multiplexed_cossin():
     multiplexed_ry = np.array(multiplexed_ry)
     qubits = [cirq.NamedQubit(f'q{i}') for i in range(2)]
     circuit = cirq.Circuit(_multiplexed_cossin(qubits, [angle_1, angle_2]))
+    # Add back the CZ gate removed by the A.1 optimization
+    circuit += cirq.CZ(qubits[1], qubits[0])
     # Test return is equal to inital unitary
     assert cirq.approx_eq(multiplexed_ry, circuit.unitary(), atol=1e-9)
     # Test all operations in gate set
-    gates = (common_gates.Rz, common_gates.Ry, common_gates.ZPowGate, common_gates.CXPowGate)
+    gates = (
+        common_gates.Rz,
+        common_gates.Ry,
+        common_gates.ZPowGate,
+        common_gates.CXPowGate,
+        common_gates.CZPowGate,
+    )
     assert all(isinstance(op.gate, gates) for op in circuit.all_operations())
 
 
@@ -201,3 +221,17 @@ def test_qft5():
     )
     new_unitary = cirq.unitary(shannon_circuit)
     np.testing.assert_allclose(new_unitary, desired_unitary, atol=1e-6)
+
+
+def test_random_circuit_decomposition():
+    qubits = cirq.LineQubit.range(3)
+    test_circuit = (
+        random_two_qubit_circuit_with_czs(3, qubits[0], qubits[1])
+        + random_two_qubit_circuit_with_czs(3, qubits[1], qubits[2])
+        + random_two_qubit_circuit_with_czs(3, qubits[0], qubits[2])
+    )
+    circuit = cirq.Circuit(quantum_shannon_decomposition(qubits, test_circuit.unitary()))
+    # Test return is equal to initial unitary
+    assert cirq.approx_eq(test_circuit.unitary(), circuit.unitary(), atol=1e-9)
+    # Test all operations have at most 2 qubits.
+    assert all(cirq.num_qubits(op) <= 2 for op in circuit.all_operations())

cirq/transformers/analytical_decompositions/single_qubit_decompositions.py

@@ -14,8 +14,9 @@
 
 """Utility methods related to optimizing quantum circuits."""
 
+from __future__ import annotations
+
 import math
-from typing import List, Optional, Tuple
 
 import numpy as np
 import sympy
@@ -39,7 +40,7 @@ def _signed_mod_1(x: float) -> float:
 
 def single_qubit_matrix_to_pauli_rotations(
     mat: np.ndarray, atol: float = 0
-) -> List[Tuple[ops.Pauli, float]]:
+) -> list[tuple[ops.Pauli, float]]:
     """Implements a single-qubit operation with few rotations.
 
     Args:
@@ -98,7 +99,7 @@ def single_qubit_matrix_to_pauli_rotations(
     return [(pauli, ht) for pauli, ht in rotation_list if not is_no_turn(ht)]
 
 
-def single_qubit_matrix_to_gates(mat: np.ndarray, tolerance: float = 0) -> List[ops.Gate]:
+def single_qubit_matrix_to_gates(mat: np.ndarray, tolerance: float = 0) -> list[ops.Gate]:
     """Implements a single-qubit operation with few gates.
 
     Args:
@@ -114,7 +115,7 @@ def single_qubit_matrix_to_gates(mat: np.ndarray, tolerance: float = 0) -> List[
     return [pauli**ht for pauli, ht in rotations]
 
 
-def single_qubit_op_to_framed_phase_form(mat: np.ndarray) -> Tuple[np.ndarray, complex, complex]:
+def single_qubit_op_to_framed_phase_form(mat: np.ndarray) -> tuple[np.ndarray, complex, complex]:
     """Decomposes a 2x2 unitary M into U^-1 * diag(1, r) * U * diag(g, g).
 
     U translates the rotation axis of M to the Z axis.
@@ -141,7 +142,7 @@ def single_qubit_op_to_framed_phase_form(mat: np.ndarray) -> Tuple[np.ndarray, c
     return u, r, g
 
 
-def _deconstruct_single_qubit_matrix_into_gate_turns(mat: np.ndarray) -> Tuple[float, float, float]:
+def _deconstruct_single_qubit_matrix_into_gate_turns(mat: np.ndarray) -> tuple[float, float, float]:
     """Breaks down a 2x2 unitary into gate parameters.
 
     Args:
@@ -165,7 +166,7 @@ def _deconstruct_single_qubit_matrix_into_gate_turns(mat: np.ndarray) -> Tuple[f
     return (_signed_mod_1(xy_turn), _signed_mod_1(xy_phase_turn), _signed_mod_1(total_z_turn))
 
 
-def single_qubit_matrix_to_phased_x_z(mat: np.ndarray, atol: float = 0) -> List[ops.Gate]:
+def single_qubit_matrix_to_phased_x_z(mat: np.ndarray, atol: float = 0) -> list[ops.Gate]:
     """Implements a single-qubit operation with a PhasedX and Z gate.
 
     If one of the gates isn't needed, it will be omitted.
@@ -196,7 +197,7 @@ def single_qubit_matrix_to_phased_x_z(mat: np.ndarray, atol: float = 0) -> List[
     return result
 
 
-def single_qubit_matrix_to_phxz(mat: np.ndarray, atol: float = 0) -> Optional[ops.PhasedXZGate]:
+def single_qubit_matrix_to_phxz(mat: np.ndarray, atol: float = 0) -> ops.PhasedXZGate | None:
     """Implements a single-qubit operation with a PhasedXZ gate.
 
     Under the hood, this uses deconstruct_single_qubit_matrix_into_angles which

cirq/transformers/analytical_decompositions/single_qubit_decompositions_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 random
 from typing import Sequence
 

cirq/transformers/analytical_decompositions/single_to_two_qubit_isometry.py

@@ -13,7 +13,10 @@
 # limitations under the License.
 
 """Analytical decompositions for 2-qubit unitaries when one input qubit is in the |0> state."""
-from typing import List, TYPE_CHECKING
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
 
 import numpy as np
 
@@ -25,13 +28,13 @@ if TYPE_CHECKING:
 
 
 def two_qubit_matrix_to_cz_isometry(
-    q0: 'cirq.Qid',
-    q1: 'cirq.Qid',
+    q0: cirq.Qid,
+    q1: cirq.Qid,
     mat: np.ndarray,
     allow_partial_czs: bool = False,
     atol: float = 1e-8,
     clean_operations: bool = True,
-) -> List['cirq.Operation']:
+) -> list[cirq.Operation]:
     """Decomposes a 2q operation into at-most 2 CZs + 1q rotations; assuming `q0` is initially |0>.
 
     The method implements isometry from one to two qubits; assuming qubit `q0` is always in the |0>

cirq/transformers/analytical_decompositions/single_to_two_qubit_isometry_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 numpy as np
 import pytest
 

cirq/transformers/analytical_decompositions/three_qubit_decomposition.py

@@ -14,9 +14,12 @@
 
 """Utility methods for decomposing three-qubit unitaries."""
 
-from typing import List, Optional, Sequence, Tuple, Union
+from __future__ import annotations
+
+from typing import Sequence
 
 import numpy as np
+import scipy.linalg
 
 import cirq
 from cirq import ops, transformers as opt
@@ -24,7 +27,7 @@ from cirq import ops, transformers as opt
 
 def three_qubit_matrix_to_operations(
     q0: ops.Qid, q1: ops.Qid, q2: ops.Qid, u: np.ndarray, atol: float = 1e-8
-) -> List[ops.Operation]:
+) -> list[ops.Operation]:
     """Returns operations for a 3 qubit unitary.
 
     The algorithm is described in Shende et al.:
@@ -45,24 +48,13 @@ def three_qubit_matrix_to_operations(
 
     Raises:
         ValueError: If the u matrix is non-unitary or not of shape (8,8).
-        ImportError: If the decomposition cannot be done because the SciPy version is less than
-            1.5.0 and so does not contain the required `cossin` method.
     """
     if np.shape(u) != (8, 8):
         raise ValueError(f"Expected unitary matrix with shape (8,8) got {np.shape(u)}")
     if not cirq.is_unitary(u, atol=atol):
         raise ValueError(f"Matrix is not unitary: {u}")
 
-    try:
-        from scipy.linalg import cossin
-    except ImportError:  # pragma: no cover
-        raise ImportError(
-            "cirq.three_qubit_unitary_to_operations requires "
-            "SciPy 1.5.0+, as it uses the cossin function. Please"
-            " upgrade scipy in your environment to use this "
-            "function!"
-        )
-    (u1, u2), theta, (v1h, v2h) = cossin(u, 4, 4, separate=True)
+    (u1, u2), theta, (v1h, v2h) = scipy.linalg.cossin(u, 4, 4, separate=True)
 
     cs_ops = _cs_to_ops(q0, q1, q2, theta)
     if len(cs_ops) > 0 and cs_ops[-1] == cirq.CZ(q2, q0):
@@ -85,7 +77,7 @@ def three_qubit_matrix_to_operations(
     return list(cirq.Circuit(vdh_ops + cs_ops + ud_ops).all_operations())
 
 
-def _cs_to_ops(q0: ops.Qid, q1: ops.Qid, q2: ops.Qid, theta: np.ndarray) -> List[ops.Operation]:
+def _cs_to_ops(q0: ops.Qid, q1: ops.Qid, q2: ops.Qid, theta: np.ndarray) -> list[ops.Operation]:
     """Converts theta angles based Cosine Sine matrix to operations.
 
     Using the optimization as per Appendix A.1, it uses CZ gates instead of
@@ -124,9 +116,9 @@ def _two_qubit_multiplexor_to_ops(
     u1: np.ndarray,
     u2: np.ndarray,
     shift_left: bool = True,
-    diagonal: Optional[np.ndarray] = None,
+    diagonal: np.ndarray | None = None,
     atol: float = 1e-8,
-) -> Tuple[Optional[np.ndarray], List[ops.Operation]]:
+) -> tuple[np.ndarray | None, list[ops.Operation]]:
     r"""Converts a two qubit double multiplexor to circuit.
     Input: U_1 ⊕ U_2, with select qubit a (i.e. a = |0> => U_1(b,c),
     a = |1> => U_2(b,c).
@@ -185,7 +177,7 @@ def _two_qubit_multiplexor_to_ops(
 
     w = d_v @ w
 
-    d_w: Optional[np.ndarray]
+    d_w: np.ndarray | None
 
     # if it's interesting to extract the diagonal then let's do it
     if shift_left:
@@ -258,7 +250,7 @@ def _middle_multiplexor_to_ops(q0: ops.Qid, q1: ops.Qid, q2: ops.Qid, eigvals: n
     return _optimize_multiplexed_angles_circuit(ops)
 
 
-def _multiplexed_angles(theta: Union[Sequence[float], np.ndarray]) -> np.ndarray:
+def _multiplexed_angles(theta: Sequence[float] | np.ndarray) -> np.ndarray:
     """Calculates the angles for a 4-way multiplexed rotation.
 
     For example, if we want rz(theta[i]) if the select qubits are in state

cirq/transformers/analytical_decompositions/three_qubit_decomposition_test.py

@@ -12,8 +12,9 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from __future__ import annotations
+
 from random import random
-from typing import Callable
 
 import numpy as np
 import pytest
@@ -29,20 +30,6 @@ from cirq.transformers.analytical_decompositions.three_qubit_decomposition impor
 )
 
 
-def _skip_if_scipy(*, version_is_greater_than_1_5_0: bool) -> Callable[[Callable], Callable]:
-    def decorator(func):  # pragma: no cover
-        try:
-            # pylint: disable=unused-import
-            from scipy.linalg import cossin
-
-            return None if version_is_greater_than_1_5_0 else func
-        except ImportError:
-            return func if version_is_greater_than_1_5_0 else None
-
-    return decorator
-
-
-@_skip_if_scipy(version_is_greater_than_1_5_0=False)
 @pytest.mark.parametrize(
     "u",
     [
@@ -52,7 +39,7 @@ def _skip_if_scipy(*, version_is_greater_than_1_5_0: bool) -> Callable[[Callable
         cirq.CCX._unitary_(),
     ],
 )
-def test_three_qubit_matrix_to_operations(u):
+def test_three_qubit_matrix_to_operations(u) -> None:
     a, b, c = cirq.LineQubit.range(3)
     operations = cirq.three_qubit_matrix_to_operations(a, b, c, u)
     final_circuit = cirq.Circuit(operations)
@@ -68,8 +55,7 @@ def test_three_qubit_matrix_to_operations(u):
     assert num_two_qubit_gates <= 20, f"expected at most 20 CZ/CNOTs got {num_two_qubit_gates}"
 
 
-@_skip_if_scipy(version_is_greater_than_1_5_0=False)
-def test_three_qubit_matrix_to_operations_errors():
+def test_three_qubit_matrix_to_operations_errors() -> None:
     a, b, c = cirq.LineQubit.range(3)
     with pytest.raises(ValueError, match="(8,8)"):
         cirq.three_qubit_matrix_to_operations(a, b, c, np.eye(2))
@@ -77,17 +63,6 @@ def test_three_qubit_matrix_to_operations_errors():
         cirq.three_qubit_matrix_to_operations(a, b, c, cirq.unitary(cirq.CCX) * 2)
 
 
-# on environments with scipy <1.5.0 this will not be sufficient to cover the
-# full three_qubit_matrix_to_operations method. In case we ever introduce a CI
-# environment like that, we'll need to ignore the coverage somehow conditionally on
-# the scipy version.
-@_skip_if_scipy(version_is_greater_than_1_5_0=True)
-def test_three_qubit_matrix_to_operations_scipy_error():  # pragma: no cover
-    a, b, c = cirq.LineQubit.range(3)
-    with pytest.raises(ImportError, match="three_qubit.*1.5.0+"):
-        cirq.three_qubit_matrix_to_operations(a, b, c, np.eye(8))
-
-
 @pytest.mark.parametrize(
     ["theta", "num_czs"],
     [
@@ -100,7 +75,7 @@ def test_three_qubit_matrix_to_operations_scipy_error():  # pragma: no cover
         (np.array([0.3, 0.3, -0.3, -0.3]), 2),
     ],
 )
-def test_cs_to_ops(theta, num_czs):
+def test_cs_to_ops(theta, num_czs) -> None:
     a, b, c = cirq.LineQubit.range(3)
     cs = _theta_to_cs(theta)
     circuit_cs = cirq.Circuit(_cs_to_ops(a, b, c, theta))
@@ -126,7 +101,7 @@ def _theta_to_cs(theta: np.ndarray) -> np.ndarray:
     return np.block([[c, -s], [s, c]])
 
 
-def test_multiplexed_angles():
+def test_multiplexed_angles() -> None:
     theta = [random() * np.pi, random() * np.pi, random() * np.pi, random() * np.pi]
 
     angles = _multiplexed_angles(theta)
@@ -190,7 +165,7 @@ def test_multiplexed_angles():
         [([-0.3, 0.3, -0.3, -0.3]), 4],
     ],
 )
-def test_middle_multiplexor(angles, num_cnots):
+def test_middle_multiplexor(angles, num_cnots) -> None:
     a, b, c = cirq.LineQubit.range(3)
     eigvals = np.exp(np.array(angles) * np.pi * 1j)
     d = np.diag(np.sqrt(eigvals))
@@ -212,7 +187,7 @@ def test_middle_multiplexor(angles, num_cnots):
 
 
 @pytest.mark.parametrize("shift_left", [True, False])
-def test_two_qubit_multiplexor_to_circuit(shift_left):
+def test_two_qubit_multiplexor_to_circuit(shift_left) -> None:
     a, b, c = cirq.LineQubit.range(3)
     u1 = cirq.testing.random_unitary(4)
     u2 = cirq.testing.random_unitary(4)