Rename givens rotation factory (#2519)

Partially implements #2508 and #1681.

cirq/__init__.py

@@ -190,6 +190,7 @@
     GateOperation,
     generalized_amplitude_damp,
     GeneralizedAmplitudeDampingChannel,
+    givens,
     GivensRotation,
     GlobalPhaseOperation,
     H,

cirq/ops/__init__.py

@@ -184,6 +184,7 @@
     PauliStringGateOperation,)
 
 from cirq.ops.phased_iswap_gate import (
+    givens,
     GivensRotation,
     PhasedISwapPowGate,
 )

cirq/ops/phased_iswap_gate.py

@@ -20,7 +20,7 @@
 
 import cirq
 from cirq import linalg, protocols, value
-from cirq._compat import proper_repr
+from cirq._compat import deprecated, proper_repr
 from cirq.ops import eigen_gate, op_tree, gate_features, raw_types, swap_gates
 
 
@@ -182,7 +182,7 @@ def __repr__(self):
         return f'cirq.PhasedISwapPowGate({arg_string})'
 
 
-def GivensRotation(angle_rads: value.TParamVal) -> PhasedISwapPowGate:
+def givens(angle_rads: value.TParamVal) -> PhasedISwapPowGate:
     """Returns gate with matrix exp(-i angle_rads (Y⊗X - X⊗Y) / 2).
 
     In numerical linear algebra Givens rotation is any linear transformation
@@ -191,7 +191,7 @@ def GivensRotation(angle_rads: value.TParamVal) -> PhasedISwapPowGate:
     subspace spanned by two basis vectors. In quantum computational chemistry
     the term is used to refer to the two-qubit gate defined as
 
-        GivensRotation(a) ≡ exp(-i a (Y⊗X - X⊗Y) / 2)
+        givens(a) ≡ exp(-i a (Y⊗X - X⊗Y) / 2)
 
     with the matrix
 
@@ -219,3 +219,8 @@ def GivensRotation(angle_rads: value.TParamVal) -> PhasedISwapPowGate:
     """
     pi = sympy.pi if protocols.is_parameterized(angle_rads) else np.pi
     return PhasedISwapPowGate()**(2 * angle_rads / pi)
+
+
+@deprecated(deadline='v0.8.0', fix='Use cirq.givens, instead.')
+def GivensRotation(angle_rads: value.TParamVal) -> PhasedISwapPowGate:
+    return givens(angle_rads)

cirq/ops/phased_iswap_gate_test.py

@@ -128,7 +128,7 @@ def test_diagram():
 
 @pytest.mark.parametrize('angle_rads', (-np.pi, -np.pi / 3, -0.1, np.pi / 5))
 def test_givens_rotation_unitary(angle_rads):
-    actual = cirq.unitary(cirq.GivensRotation(angle_rads))
+    actual = cirq.unitary(cirq.givens(angle_rads))
     c = np.cos(angle_rads)
     s = np.sin(angle_rads)
     # yapf: disable
@@ -142,7 +142,7 @@ def test_givens_rotation_unitary(angle_rads):
 
 @pytest.mark.parametrize('angle_rads', (-2 * np.pi / 3, -0.2, 0.4, np.pi / 4))
 def test_givens_rotation_hamiltonian(angle_rads):
-    actual = cirq.unitary(cirq.GivensRotation(angle_rads))
+    actual = cirq.unitary(cirq.givens(angle_rads))
     x = np.array([[0, 1], [1, 0]])
     y = np.array([[0, -1j], [1j, 0]])
     yx = np.kron(y, x)
@@ -154,7 +154,7 @@ def test_givens_rotation_hamiltonian(angle_rads):
 def test_givens_rotation_equivalent_circuit():
     angle_rads = 3 * np.pi / 7
     t = 2 * angle_rads / np.pi
-    gate = cirq.GivensRotation(angle_rads)
+    gate = cirq.givens(angle_rads)
     q0, q1 = cirq.LineQubit.range(2)
     equivalent_circuit = cirq.Circuit([
         cirq.T(q0),
@@ -169,4 +169,11 @@ def test_givens_rotation_equivalent_circuit():
 @pytest.mark.parametrize('angle_rads', (-np.pi / 5, 0.4, 2, np.pi))
 def test_givens_rotation_has_consistent_protocols(angle_rads):
     cirq.testing.assert_implements_consistent_protocols(
-        cirq.GivensRotation(angle_rads), ignoring_global_phase=False)
+        cirq.givens(angle_rads), ignoring_global_phase=False)
+
+
+@pytest.mark.parametrize('angle_rads', (-1, -0.3, 0.1, 1))
+def test_deprecated_givens_rotation(angle_rads):
+    assert np.all(
+        cirq.unitary(cirq.GivensRotation(angle_rads)) == cirq.unitary(
+            cirq.givens(angle_rads)))

docs/api.rst

@@ -65,6 +65,7 @@ Unitary effects that can be applied to one or more qubits.
     cirq.QFT
     cirq.SWAP
     cirq.TOFFOLI
+    cirq.givens
     cirq.identity_each
     cirq.riswap
     cirq.CCXPowGate