Part-2: Move analytical decompositions from cirq/optimizers/ to `ci…

…rq/transformers/analytical_decompositions/` (quantumlib#4785)

Moves the following files from `cirq/optimizers/` to `cirq/transformers/analytical_decompositions/` using `deprecated_submodule`:

- clifford_decomposition.py
- controlled_gate_decomposition.py
- cphase_to_fsim.py


Part of quantumlib#4722

cirq-core/cirq/__init__.py

@@ -328,12 +328,7 @@
 from cirq.optimizers import (
     AlignLeft,
     AlignRight,
-    compute_cphase_exponents_for_fsim_decomposition,
     ConvertToCzAndSingleGates,
-    decompose_clifford_tableau_to_operations,
-    decompose_cphase_into_two_fsim,
-    decompose_multi_controlled_x,
-    decompose_multi_controlled_rotation,
     decompose_two_qubit_interaction_into_four_fsim_gates,
     DropEmptyMoments,
     DropNegligible,
@@ -360,6 +355,11 @@
 )
 
 from cirq.transformers import (
+    compute_cphase_exponents_for_fsim_decomposition,
+    decompose_clifford_tableau_to_operations,
+    decompose_cphase_into_two_fsim,
+    decompose_multi_controlled_x,
+    decompose_multi_controlled_rotation,
     map_moments,
     map_operations,
     map_operations_and_unroll,

cirq-core/cirq/optimizers/__init__.py

@@ -22,18 +22,6 @@
     AlignRight,
 )
 
-from cirq.optimizers.clifford_decomposition import decompose_clifford_tableau_to_operations
-
-from cirq.optimizers.cphase_to_fsim import (
-    compute_cphase_exponents_for_fsim_decomposition,
-    decompose_cphase_into_two_fsim,
-)
-
-from cirq.optimizers.controlled_gate_decomposition import (
-    decompose_multi_controlled_x,
-    decompose_multi_controlled_rotation,
-)
-
 from cirq.optimizers.drop_empty_moments import (
     DropEmptyMoments,
 )
@@ -105,3 +93,29 @@
 from cirq.optimizers.two_qubit_to_fsim import (
     decompose_two_qubit_interaction_into_four_fsim_gates,
 )
+
+from cirq import _compat
+
+_compat.deprecated_submodule(
+    new_module_name="cirq.transformers.analytical_decompositions.clifford_decomposition",
+    old_parent="cirq.optimizers",
+    old_child="clifford_decomposition",
+    deadline="v0.16",
+    create_attribute=True,
+)
+
+_compat.deprecated_submodule(
+    new_module_name="cirq.transformers.analytical_decompositions.cphase_to_fsim",
+    old_parent="cirq.optimizers",
+    old_child="cphase_to_fsim",
+    deadline="v0.16",
+    create_attribute=True,
+)
+
+_compat.deprecated_submodule(
+    new_module_name="cirq.transformers.analytical_decompositions.controlled_gate_decomposition",
+    old_parent="cirq.optimizers",
+    old_child="controlled_gate_decomposition",
+    deadline="v0.16",
+    create_attribute=True,
+)

cirq-core/cirq/transformers/__init__.py

@@ -15,6 +15,11 @@
 """Circuit transformation utilities."""
 
 from cirq.transformers.analytical_decompositions import (
+    compute_cphase_exponents_for_fsim_decomposition,
+    decompose_cphase_into_two_fsim,
+    decompose_clifford_tableau_to_operations,
+    decompose_multi_controlled_x,
+    decompose_multi_controlled_rotation,
     prepare_two_qubit_state_using_cz,
     prepare_two_qubit_state_using_sqrt_iswap,
 )

cirq-core/cirq/transformers/analytical_decompositions/__init__.py

@@ -14,6 +14,20 @@
 
 """Utilities for analytical decomposition of cirq gates."""
 
+from cirq.transformers.analytical_decompositions.clifford_decomposition import (
+    decompose_clifford_tableau_to_operations,
+)
+
+from cirq.transformers.analytical_decompositions.controlled_gate_decomposition import (
+    decompose_multi_controlled_x,
+    decompose_multi_controlled_rotation,
+)
+
+from cirq.transformers.analytical_decompositions.cphase_to_fsim import (
+    compute_cphase_exponents_for_fsim_decomposition,
+    decompose_cphase_into_two_fsim,
+)
+
 from cirq.transformers.analytical_decompositions.two_qubit_state_preparation import (
     prepare_two_qubit_state_using_cz,
     prepare_two_qubit_state_using_sqrt_iswap,

cirq-core/cirq/optimizers/clifford_decomposition_test.py → cirq-core/cirq/transformers/analytical_decompositions/clifford_decomposition_test.py

@@ -18,6 +18,16 @@
 import cirq
 from cirq.testing import assert_allclose_up_to_global_phase
 
+ALLOW_DEPRECATION_IN_TEST = 'ALLOW_DEPRECATION_IN_TEST'
+
+
+def test_deprecated_submodule():
+    with cirq.testing.assert_deprecated(
+        "Use cirq.transformers.analytical_decompositions.clifford_decomposition instead",
+        deadline="v0.16",
+    ):
+        _ = cirq.optimizers.clifford_decomposition.decompose_clifford_tableau_to_operations
+
 
 def test_misaligned_qubits():
     qubits = cirq.LineQubit.range(1)

cirq-core/cirq/optimizers/controlled_gate_decomposition_test.py → cirq-core/cirq/transformers/analytical_decompositions/controlled_gate_decomposition_test.py

@@ -17,6 +17,16 @@
 
 import cirq
 
+ALLOW_DEPRECATION_IN_TEST = 'ALLOW_DEPRECATION_IN_TEST'
+
+
+def test_deprecated_submodule():
+    with cirq.testing.assert_deprecated(
+        "Use cirq.transformers.analytical_decompositions.controlled_gate_decomposition instead",
+        deadline="v0.16",
+    ):
+        _ = cirq.optimizers.controlled_gate_decomposition.decompose_multi_controlled_rotation
+
 
 def test_decompose_x():
     """Verifies correctness of multi-controlled X decomposition."""

cirq-core/cirq/optimizers/cphase_to_fsim.py → cirq-core/cirq/transformers/analytical_decompositions/cphase_to_fsim.py

@@ -1,4 +1,17 @@
-# pylint: disable=wrong-or-nonexistent-copyright-notice
+# Copyright 2021 The Cirq Developers
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# 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 typing import Optional, Sequence, Tuple, TYPE_CHECKING
 
 import numpy as np

cirq-core/cirq/optimizers/cphase_to_fsim_test.py → cirq-core/cirq/transformers/analytical_decompositions/cphase_to_fsim_test.py

@@ -1,4 +1,17 @@
-# pylint: disable=wrong-or-nonexistent-copyright-notice
+# Copyright 2021 The Cirq Developers
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# 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 typing import List, Sequence, Tuple
 
 import itertools
@@ -8,6 +21,15 @@
 
 import cirq
 
+ALLOW_DEPRECATION_IN_TEST = 'ALLOW_DEPRECATION_IN_TEST'
+
+
+def test_deprecated_submodule():
+    with cirq.testing.assert_deprecated(
+        "Use cirq.transformers.analytical_decompositions.cphase_to_fsim instead", deadline="v0.16"
+    ):
+        _ = cirq.optimizers.cphase_to_fsim.decompose_cphase_into_two_fsim
+
 
 class FakeSycamoreGate(cirq.FSimGate):
     def __init__(self):