Deprecate Two/ThreeQubitGate (#4207)

Closes #2164

Copies `Two/ThreeQubitGate` to cirq.testing due to its convenience there, and deprecates the originals.

BREAKING CHANGE: @balopat @95-martin-orion @tanujkhattar During the deprecation period, `isinstance(TwoQubitGate)` has been shimmed such that it will now return True iff _num_qubits_() returns 2, regardless of whether it's actually part of the class hierarchy (and same for ThreeQubitGate). It's not expected that this will cause real-world breakages, but possible.

This can go before or after #4236, as they are disjoint problems.

Author: daxfohl

cirq-core/cirq/circuits/circuit_test.py

@@ -2227,7 +2227,7 @@ def test_to_text_diagram_multi_qubit_gate(circuit_cls):
 
 @pytest.mark.parametrize('circuit_cls', [cirq.Circuit, cirq.FrozenCircuit])
 def test_to_text_diagram_many_qubits_gate_but_multiple_wire_symbols(circuit_cls):
-    class BadGate(cirq.ThreeQubitGate):
+    class BadGate(cirq.testing.ThreeQubitGate):
         def _circuit_diagram_info_(self, args: cirq.CircuitDiagramInfoArgs) -> Tuple[str, str]:
             return 'a', 'a'
 
@@ -2547,7 +2547,7 @@ def test_circuit_to_unitary_matrix(circuit_cls):
         _ = c.unitary()
 
     # Gates without matrix or decomposition raise exception
-    class MysteryGate(cirq.TwoQubitGate):
+    class MysteryGate(cirq.testing.TwoQubitGate):
         pass
 
     c = circuit_cls(MysteryGate()(a, b))
@@ -2615,7 +2615,7 @@ def test_simple_circuits_to_unitary_matrix(circuit_cls):
     # 2-qubit matrix matches when qubits in order.
     for expected in [np.diag([1, 1j, -1, -1j]), cirq.unitary(cirq.CNOT)]:
 
-        class Passthrough(cirq.TwoQubitGate):
+        class Passthrough(cirq.testing.TwoQubitGate):
             def _unitary_(self) -> np.ndarray:
                 return expected
 
@@ -2626,7 +2626,7 @@ def _unitary_(self) -> np.ndarray:
 
 @pytest.mark.parametrize('circuit_cls', [cirq.Circuit, cirq.FrozenCircuit])
 def test_composite_gate_to_unitary_matrix(circuit_cls):
-    class CnotComposite(cirq.TwoQubitGate):
+    class CnotComposite(cirq.testing.TwoQubitGate):
         def _decompose_(self, qubits):
             q0, q1 = qubits
             return cirq.Y(q1) ** -0.5, cirq.CZ(q0, q1), cirq.Y(q1) ** 0.5

cirq-core/cirq/circuits/qasm_output.py

@@ -85,7 +85,7 @@ def _value_equality_values_(self):
 
 
 @value.value_equality
-class QasmTwoQubitGate(ops.TwoQubitGate):
+class QasmTwoQubitGate(ops.Gate):
     def __init__(self, kak: linalg.KakDecomposition) -> None:
         """A two qubit gate represented in QASM by the KAK decomposition.
 
@@ -97,6 +97,9 @@ def __init__(self, kak: linalg.KakDecomposition) -> None:
         """
         self.kak = kak
 
+    def _num_qubits_(self) -> int:
+        return 2
+
     def _value_equality_values_(self):
         return self.kak
 

cirq-core/cirq/circuits/qasm_output_test.py

@@ -322,7 +322,7 @@ def test_output_unitary_same_as_qiskit():
 
 
 def test_fails_on_big_unknowns():
-    class UnrecognizedGate(cirq.ThreeQubitGate):
+    class UnrecognizedGate(cirq.testing.ThreeQubitGate):
         pass
 
     c = cirq.Circuit(UnrecognizedGate().on(*cirq.LineQubit.range(3)))

cirq-core/cirq/circuits/quil_output.py

@@ -56,7 +56,7 @@ def _value_equality_values_(self):
 
 
 @value.value_equality(approximate=True)
-class QuilTwoQubitGate(ops.TwoQubitGate):
+class QuilTwoQubitGate(ops.Gate):
     """A two qubit gate represented in QUIL with a DEFGATE and it's 4x4
     unitary matrix.
     """
@@ -69,6 +69,9 @@ def __init__(self, matrix: np.ndarray) -> None:
         """
         self.matrix = matrix
 
+    def _num_qubits_(self) -> int:
+        return 2
+
     def _value_equality_values_(self):
         return self.matrix
 

cirq-core/cirq/circuits/quil_output_test.py

@@ -373,7 +373,7 @@ def _all_operations(q0, q1, q2, q3, q4, include_measurements=True):
 
 
 def test_fails_on_big_unknowns():
-    class UnrecognizedGate(cirq.ThreeQubitGate):
+    class UnrecognizedGate(cirq.testing.ThreeQubitGate):
         pass
 
     c = cirq.Circuit(UnrecognizedGate().on(*cirq.LineQubit.range(3)))

cirq-core/cirq/contrib/paulistring/convert_to_clifford_gates_test.py

@@ -73,7 +73,7 @@ def test_already_converted():
 
 
 def test_convert_composite():
-    class CompositeDummy(cirq.TwoQubitGate):
+    class CompositeDummy(cirq.testing.TwoQubitGate):
         def _decompose_(self, qubits):
             q0, q1 = qubits
             yield cirq.X(q0)
@@ -100,7 +100,7 @@ def _decompose_(self, qubits):
 
 
 def test_ignore_unsupported_gate():
-    class UnsupportedDummy(cirq.TwoQubitGate):
+    class UnsupportedDummy(cirq.testing.TwoQubitGate):
         pass
 
     q0, q1 = cirq.LineQubit.range(2)
@@ -114,7 +114,7 @@ class UnsupportedDummy(cirq.TwoQubitGate):
 
 
 def test_fail_unsupported_gate():
-    class UnsupportedDummy(cirq.TwoQubitGate):
+    class UnsupportedDummy(cirq.testing.TwoQubitGate):
         pass
 
     q0, q1 = cirq.LineQubit.range(2)

cirq-core/cirq/contrib/paulistring/convert_to_pauli_string_phasors_test.py

@@ -72,7 +72,7 @@ def test_already_converted():
 
 
 def test_ignore_unsupported_gate():
-    class UnsupportedDummy(cirq.TwoQubitGate):
+    class UnsupportedDummy(cirq.testing.TwoQubitGate):
         pass
 
     q0, q1 = cirq.LineQubit.range(2)
@@ -86,7 +86,7 @@ class UnsupportedDummy(cirq.TwoQubitGate):
 
 
 def test_fail_unsupported_gate():
-    class UnsupportedDummy(cirq.TwoQubitGate):
+    class UnsupportedDummy(cirq.testing.TwoQubitGate):
         pass
 
     q0, q1 = cirq.LineQubit.range(2)

cirq-core/cirq/contrib/qasm_import/_parser_test.py

@@ -835,7 +835,7 @@ def test_standard_gates_wrong_params_error(qasm_gate: str, num_params: int):
 
 
 @pytest.mark.parametrize('qasm_gate,cirq_gate', two_qubit_gates)
-def test_two_qubit_gates(qasm_gate: str, cirq_gate: cirq.TwoQubitGate):
+def test_two_qubit_gates(qasm_gate: str, cirq_gate: cirq.testing.TwoQubitGate):
     qasm = """
      OPENQASM 2.0;   
      include "qelib1.inc";       
@@ -911,7 +911,7 @@ def test_two_qubit_gates_with_too_much_parameters(qasm_gate: str):
 
 
 @pytest.mark.parametrize('qasm_gate,cirq_gate', three_qubit_gates)
-def test_three_qubit_gates(qasm_gate: str, cirq_gate: cirq.TwoQubitGate):
+def test_three_qubit_gates(qasm_gate: str, cirq_gate: cirq.testing.TwoQubitGate):
     qasm = """
      OPENQASM 2.0;
      include "qelib1.inc";       

cirq-core/cirq/contrib/qcircuit/qcircuit_test.py

@@ -48,7 +48,7 @@ def assert_has_qcircuit_diagram(actual: cirq.Circuit, desired: str, **kwargs) ->
 
 
 def test_fallback_diagram():
-    class MagicGate(cirq.ThreeQubitGate):
+    class MagicGate(cirq.testing.ThreeQubitGate):
         def __str__(self):
             return 'MagicGate'
 

cirq-core/cirq/experiments/cross_entropy_benchmarking.py

@@ -418,7 +418,7 @@ def cross_entropy_benchmarking(
 
 
 def build_entangling_layers(
-    qubits: Sequence[devices.GridQubit], two_qubit_gate: ops.TwoQubitGate
+    qubits: Sequence[devices.GridQubit], two_qubit_gate: ops.Gate
 ) -> List[ops.Moment]:
     """Builds a sequence of gates that entangle all pairs of qubits on a grid.
 
@@ -465,7 +465,12 @@ def build_entangling_layers(
     Returns:
         A list of ops.Moment, with a maximum length of 4. Each ops.Moment
         includes two-qubit gates which can be performed at the same time.
+
+    Raises:
+        ValueError: two-qubit gate is not used.
     """
+    if protocols.num_qubits(two_qubit_gate) != 2:
+        raise ValueError('Input must be a two-qubit gate')
     interaction_sequence = _default_interaction_sequence(qubits)
     return [
         ops.Moment([two_qubit_gate(q_a, q_b) for (q_a, q_b) in pairs])

cirq-core/cirq/experiments/cross_entropy_benchmarking_test.py

@@ -33,6 +33,10 @@ def test_cross_entropy_benchmarking():
     simulator = cirq.Simulator()
     qubits = cirq.GridQubit.square(2)
 
+    # Sanity check single-qubit-gate causes error
+    with pytest.raises(ValueError):
+        build_entangling_layers(qubits, cirq.Z ** 0.91)
+
     # Build a sequence of CZ gates.
     interleaved_ops = build_entangling_layers(qubits, cirq.CZ ** 0.91)
 

cirq-core/cirq/ion/convert_to_ion_gates_test.py

@@ -28,7 +28,7 @@ class NoUnitary(cirq.SingleQubitGate):
     pass
 
 
-class OtherCNOT(cirq.TwoQubitGate):
+class OtherCNOT(cirq.testing.TwoQubitGate):
     def _unitary_(self) -> np.ndarray:
         return np.array([[1, 0, 0, 0], [0, 1, 0, 0], [0, 0, 0, 1], [0, 0, 1, 0]])
 

cirq-core/cirq/neutral_atoms/convert_to_neutral_atom_gates_test.py

@@ -12,16 +12,16 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-import pytest
 import numpy as np
+import pytest
 
 import cirq
 from cirq import ops
 
 
 def test_coverage():
     q = cirq.LineQubit.range(3)
-    g = cirq.ThreeQubitGate()
+    g = cirq.testing.ThreeQubitGate()
 
     class FakeOperation(ops.Operation):
         def __init__(self, gate, qubits):
@@ -64,11 +64,11 @@ def _decompose_(self, qubits):
 
 
 def test_avoids_decompose_fallback_when_matrix_available_two_qubit():
-    class OtherCZ(cirq.TwoQubitGate):
+    class OtherCZ(cirq.testing.TwoQubitGate):
         def _unitary_(self) -> np.ndarray:
             return np.array([[1, 0, 0, 0], [0, 1, 0, 0], [0, 0, 1, 0], [0, 0, 0, -1]])
 
-    class OtherOtherCZ(cirq.TwoQubitGate):
+    class OtherOtherCZ(cirq.testing.TwoQubitGate):
         def _decompose_(self, qubits):
             return OtherCZ().on(*qubits)
 

cirq-core/cirq/ops/common_gates.py

@@ -1009,9 +1009,7 @@ def __repr__(self) -> str:
         )
 
 
-class CZPowGate(
-    eigen_gate.EigenGate, gate_features.TwoQubitGate, gate_features.InterchangeableQubitsGate
-):
+class CZPowGate(gate_features.InterchangeableQubitsGate, eigen_gate.EigenGate):
     """A gate that applies a phase to the |11⟩ state of two qubits.
 
     The unitary matrix of `CZPowGate(exponent=t)` is:
@@ -1029,6 +1027,9 @@ class CZPowGate(
     `exponent=1`.
     """
 
+    def _num_qubits_(self) -> int:
+        return 2
+
     def _decompose_into_clifford_with_qubits_(self, qubits):
         from cirq.ops.pauli_interaction_gate import PauliInteractionGate
 
@@ -1216,7 +1217,7 @@ def __repr__(self) -> str:
         )
 
 
-class CXPowGate(eigen_gate.EigenGate, gate_features.TwoQubitGate):
+class CXPowGate(eigen_gate.EigenGate):
     """A gate that applies a controlled power of an X gate.
 
     When applying CNOT (controlled-not) to qubits, you can either use
@@ -1241,6 +1242,9 @@ class CXPowGate(eigen_gate.EigenGate, gate_features.TwoQubitGate):
     `exponent=1`.
     """
 
+    def _num_qubits_(self) -> int:
+        return 2
+
     def _decompose_into_clifford_with_qubits_(self, qubits):
         from cirq.ops.pauli_interaction_gate import PauliInteractionGate
 

cirq-core/cirq/ops/controlled_gate_test.py

@@ -482,7 +482,7 @@ def test_circuit_diagram():
     )
 
 
-class MockGate(cirq.TwoQubitGate):
+class MockGate(cirq.testing.TwoQubitGate):
     def _circuit_diagram_info_(self, args: cirq.CircuitDiagramInfoArgs) -> cirq.CircuitDiagramInfo:
         self.captured_diagram_args = args
         return cirq.CircuitDiagramInfo(wire_symbols=tuple(['MOCK']), exponent=1, connected=True)

cirq-core/cirq/ops/controlled_operation_test.py

@@ -246,7 +246,7 @@ def test_circuit_diagram():
     )
 
 
-class MockGate(cirq.TwoQubitGate):
+class MockGate(cirq.testing.TwoQubitGate):
     def _circuit_diagram_info_(
         self, args: protocols.CircuitDiagramInfoArgs
     ) -> protocols.CircuitDiagramInfo:

cirq-core/cirq/ops/eigen_gate_test.py

@@ -24,7 +24,7 @@
 from cirq.testing import assert_has_consistent_trace_distance_bound
 
 
-class CExpZinGate(cirq.EigenGate, cirq.TwoQubitGate):
+class CExpZinGate(cirq.EigenGate, cirq.testing.TwoQubitGate):
     """Two-qubit gate for the following matrix:
     [1  0  0  0]
     [0  1  0  0]
@@ -50,7 +50,7 @@ def _eigen_components(self) -> List[Tuple[float, np.ndarray]]:
         ]
 
 
-class ZGateDef(cirq.EigenGate, cirq.TwoQubitGate):
+class ZGateDef(cirq.EigenGate, cirq.testing.TwoQubitGate):
     @property
     def exponent(self):
         return self._exponent
@@ -148,7 +148,7 @@ def test_approx_eq_periodic():
 
 
 def test_period():
-    class Components(cirq.EigenGate, cirq.TwoQubitGate):
+    class Components(cirq.EigenGate, cirq.testing.TwoQubitGate):
         def __init__(self, a, b, c, d):
             super().__init__()
             self.a = a

cirq-core/cirq/ops/fsim_gate.py

@@ -31,7 +31,7 @@
 import cirq
 from cirq import protocols, value
 from cirq._compat import proper_repr
-from cirq.ops import gate_features
+from cirq.ops import gate_features, raw_types
 
 
 def _canonicalize(value: Union[float, sympy.Basic]) -> Union[float, sympy.Basic]:
@@ -53,7 +53,7 @@ def _half_pi_mod_pi(param: Union[float, sympy.Basic]) -> bool:
 
 
 @value.value_equality(approximate=True)
-class FSimGate(gate_features.TwoQubitGate, gate_features.InterchangeableQubitsGate):
+class FSimGate(gate_features.InterchangeableQubitsGate, raw_types.Gate):
     """Fermionic simulation gate family.
 
     Contains all two qubit interactions that preserve excitations, up to
@@ -93,6 +93,9 @@ def __init__(self, theta: float, phi: float) -> None:
         self.theta = _canonicalize(theta)
         self.phi = _canonicalize(phi)
 
+    def _num_qubits_(self) -> int:
+        return 2
+
     def _value_equality_values_(self) -> Any:
         return self.theta, self.phi
 
@@ -188,7 +191,7 @@ def _json_dict_(self) -> Dict[str, Any]:
 
 
 @value.value_equality(approximate=True)
-class PhasedFSimGate(gate_features.TwoQubitGate, gate_features.InterchangeableQubitsGate):
+class PhasedFSimGate(gate_features.InterchangeableQubitsGate, raw_types.Gate):
     """General excitation-preserving two-qubit gate.
 
     The unitary matrix of PhasedFSimGate(θ, ζ, χ, γ, φ) is:
@@ -448,3 +451,6 @@ def __repr__(self) -> str:
 
     def _json_dict_(self) -> Dict[str, Any]:
         return protocols.obj_to_dict_helper(self, ['theta', 'zeta', 'chi', 'gamma', 'phi'])
+
+    def _num_qubits_(self) -> int:
+        return 2