Move two/three qubit decompositions from optimizers/ to transformers/analytical_decompositions (#4809)

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

- two_qubit_decompositions.py --> two_qubit_to_cz.py
- two_qubit_to_fsim.py
- two_qubit_to_sqrt_iswap.py
- three_qubit_decomposition.py

Part of #4722

Author: tanujkhattar

cirq-core/cirq/__init__.py

@@ -329,7 +329,6 @@
     AlignLeft,
     AlignRight,
     ConvertToCzAndSingleGates,
-    decompose_two_qubit_interaction_into_four_fsim_gates,
     DropEmptyMoments,
     DropNegligible,
     EjectPhasedPaulis,
@@ -342,10 +341,6 @@
     MergeSingleQubitGates,
     stratified_circuit,
     SynchronizeTerminalMeasurements,
-    two_qubit_matrix_to_operations,
-    two_qubit_matrix_to_diagonal_and_operations,
-    two_qubit_matrix_to_sqrt_iswap_operations,
-    three_qubit_matrix_to_operations,
 )
 
 from cirq.transformers import (
@@ -354,6 +349,7 @@
     decompose_cphase_into_two_fsim,
     decompose_multi_controlled_x,
     decompose_multi_controlled_rotation,
+    decompose_two_qubit_interaction_into_four_fsim_gates,
     is_negligible_turn,
     map_moments,
     map_operations,
@@ -367,6 +363,10 @@
     single_qubit_matrix_to_phased_x_z,
     single_qubit_matrix_to_phxz,
     single_qubit_op_to_framed_phase_form,
+    three_qubit_matrix_to_operations,
+    two_qubit_matrix_to_diagonal_and_operations,
+    two_qubit_matrix_to_operations,
+    two_qubit_matrix_to_sqrt_iswap_operations,
     unroll_circuit_op,
     unroll_circuit_op_greedy_earliest,
     unroll_circuit_op_greedy_frontier,

cirq-core/cirq/neutral_atoms/convert_to_neutral_atom_gates.py

@@ -19,7 +19,7 @@
     PointOptimizer,
 )
 from cirq.neutral_atoms import neutral_atom_devices
-from cirq import optimizers, transformers
+from cirq import transformers
 
 if TYPE_CHECKING:
     import cirq
@@ -60,7 +60,7 @@ def _convert_one(self, op: ops.Operation) -> ops.OP_TREE:
             gates = transformers.single_qubit_matrix_to_phased_x_z(mat)
             return [g.on(op.qubits[0]) for g in gates]
         if mat is not None and len(op.qubits) == 2:
-            return optimizers.two_qubit_matrix_to_operations(
+            return transformers.two_qubit_matrix_to_operations(
                 op.qubits[0], op.qubits[1], mat, allow_partial_czs=False, clean_operations=True
             )
 

cirq-core/cirq/optimizers/__init__.py

@@ -63,28 +63,11 @@
 from cirq.optimizers.stratify import (
     stratified_circuit,
 )
+
 from cirq.optimizers.synchronize_terminal_measurements import (
     SynchronizeTerminalMeasurements,
 )
 
-from cirq.optimizers.three_qubit_decomposition import (
-    three_qubit_matrix_to_operations,
-)
-
-from cirq.optimizers.two_qubit_decompositions import (
-    two_qubit_matrix_to_operations,
-    two_qubit_matrix_to_diagonal_and_operations,
-)
-
-
-from cirq.optimizers.two_qubit_to_sqrt_iswap import (
-    two_qubit_matrix_to_sqrt_iswap_operations,
-)
-
-from cirq.optimizers.two_qubit_to_fsim import (
-    decompose_two_qubit_interaction_into_four_fsim_gates,
-)
-
 from cirq import _compat
 
 _compat.deprecated_submodule(
@@ -118,3 +101,37 @@
     deadline="v0.16",
     create_attribute=True,
 )
+
+_compat.deprecated_submodule(
+    new_module_name="cirq.transformers.analytical_decompositions.three_qubit_decomposition",
+    old_parent="cirq.optimizers",
+    old_child="three_qubit_decomposition",
+    deadline="v0.16",
+    create_attribute=True,
+)
+
+_compat.deprecated_submodule(
+    new_module_name="cirq.transformers.analytical_decompositions.two_qubit_to_cz",
+    old_parent="cirq.optimizers",
+    old_child="two_qubit_decompositions",
+    deadline="v0.16",
+    create_attribute=True,
+)
+
+
+_compat.deprecated_submodule(
+    new_module_name="cirq.transformers.analytical_decompositions.two_qubit_to_fsim",
+    old_parent="cirq.optimizers",
+    old_child="two_qubit_to_fsim",
+    deadline="v0.16",
+    create_attribute=True,
+)
+
+
+_compat.deprecated_submodule(
+    new_module_name="cirq.transformers.analytical_decompositions.two_qubit_to_sqrt_iswap",
+    old_parent="cirq.optimizers",
+    old_child="two_qubit_to_sqrt_iswap",
+    deadline="v0.16",
+    create_attribute=True,
+)

cirq-core/cirq/optimizers/convert_to_cz_and_single_gates.py

@@ -15,7 +15,7 @@
 from typing import Optional
 
 from cirq import circuits, ops, protocols
-from cirq.optimizers import two_qubit_decompositions
+from cirq.transformers.analytical_decompositions import two_qubit_to_cz
 
 
 class ConvertToCzAndSingleGates(circuits.PointOptimizer):
@@ -55,7 +55,7 @@ def _decompose_two_qubit_unitaries(self, op: ops.Operation) -> ops.OP_TREE:
         if len(op.qubits) == 2:
             mat = protocols.unitary(op, None)
             if mat is not None:
-                return two_qubit_decompositions.two_qubit_matrix_to_operations(
+                return two_qubit_to_cz.two_qubit_matrix_to_operations(
                     op.qubits[0], op.qubits[1], mat, allow_partial_czs=self.allow_partial_czs
                 )
         return NotImplemented

cirq-core/cirq/optimizers/merge_interactions.py

@@ -20,7 +20,7 @@
 import numpy as np
 
 from cirq import circuits, ops, protocols
-from cirq.optimizers import two_qubit_decompositions
+from cirq.transformers.analytical_decompositions import two_qubit_to_cz
 
 if TYPE_CHECKING:
     import cirq
@@ -257,6 +257,6 @@ def _two_qubit_matrix_to_operations(
         Returns:
             A list of operations implementing the matrix.
         """
-        return two_qubit_decompositions.two_qubit_matrix_to_operations(
+        return two_qubit_to_cz.two_qubit_matrix_to_operations(
             q0, q1, mat, self.allow_partial_czs, self.tolerance, False
         )

cirq-core/cirq/optimizers/merge_interactions_to_sqrt_iswap.py

@@ -20,7 +20,8 @@
 import numpy as np
 
 from cirq import ops
-from cirq.optimizers import two_qubit_to_sqrt_iswap, merge_interactions
+from cirq.optimizers import merge_interactions
+from cirq.transformers.analytical_decompositions import two_qubit_to_sqrt_iswap
 
 if TYPE_CHECKING:
     import cirq

cirq-core/cirq/transformers/__init__.py

@@ -20,6 +20,7 @@
     decompose_clifford_tableau_to_operations,
     decompose_multi_controlled_x,
     decompose_multi_controlled_rotation,
+    decompose_two_qubit_interaction_into_four_fsim_gates,
     is_negligible_turn,
     prepare_two_qubit_state_using_cz,
     prepare_two_qubit_state_using_sqrt_iswap,
@@ -28,6 +29,10 @@
     single_qubit_matrix_to_phased_x_z,
     single_qubit_matrix_to_phxz,
     single_qubit_op_to_framed_phase_form,
+    three_qubit_matrix_to_operations,
+    two_qubit_matrix_to_diagonal_and_operations,
+    two_qubit_matrix_to_operations,
+    two_qubit_matrix_to_sqrt_iswap_operations,
 )
 
 from cirq.transformers.transformer_primitives import (

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

@@ -37,6 +37,23 @@
     single_qubit_op_to_framed_phase_form,
 )
 
+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_operations,
+    two_qubit_matrix_to_diagonal_and_operations,
+)
+
+from cirq.transformers.analytical_decompositions.two_qubit_to_fsim import (
+    decompose_two_qubit_interaction_into_four_fsim_gates,
+)
+
+from cirq.transformers.analytical_decompositions.two_qubit_to_sqrt_iswap import (
+    two_qubit_matrix_to_sqrt_iswap_operations,
+)
+
 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/three_qubit_decomposition.py renamed to cirq-core/cirq/transformers/analytical_decompositions/three_qubit_decomposition.py

@@ -12,13 +12,15 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""Utility methods for decomposing three-qubit unitaries."""
+
 from typing import Union, Tuple, Sequence, List, Optional
 
 import numpy as np
 
 import cirq
 from cirq import ops
-from cirq import optimizers as opt
+from cirq import transformers as opt
 
 
 def three_qubit_matrix_to_operations(

cirq-core/cirq/optimizers/three_qubit_decomposition_test.py renamed to cirq-core/cirq/transformers/analytical_decompositions/three_qubit_decomposition_test.py

@@ -21,13 +21,23 @@
 from scipy.linalg import block_diag
 
 import cirq
-from cirq.optimizers.three_qubit_decomposition import (
+from cirq.transformers.analytical_decompositions.three_qubit_decomposition import (
     _multiplexed_angles,
     _cs_to_ops,
     _middle_multiplexor_to_ops,
     _two_qubit_multiplexor_to_ops,
 )
 
+ALLOW_DEPRECATION_IN_TEST = 'ALLOW_DEPRECATION_IN_TEST'
+
+
+def test_deprecated_submodule():
+    with cirq.testing.assert_deprecated(
+        "Use cirq.transformers.analytical_decompositions.three_qubit_decomposition instead",
+        deadline="v0.16",
+    ):
+        _ = cirq.optimizers.three_qubit_decomposition.three_qubit_matrix_to_operations
+
 
 def _skip_if_scipy(*, version_is_greater_than_1_5_0: bool) -> Callable[[Callable], Callable]:
     def decorator(func):

cirq-core/cirq/optimizers/two_qubit_decompositions.py renamed to cirq-core/cirq/transformers/analytical_decompositions/two_qubit_to_cz.py

@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Utility methods related to optimizing quantum circuits."""
+"""Utility methods for decomposing two-qubit unitaries into CZ gates."""
 
 from typing import Iterable, List, Sequence, Tuple, Optional, cast, TYPE_CHECKING
 

cirq-core/cirq/optimizers/two_qubit_decompositions_test.py renamed to cirq-core/cirq/transformers/analytical_decompositions/two_qubit_to_cz_test.py

@@ -20,13 +20,22 @@
 
 import cirq
 from cirq import value
-from cirq.optimizers.two_qubit_decompositions import (
+from cirq.transformers.analytical_decompositions.two_qubit_to_cz import (
     _parity_interaction,
     _is_trivial_angle,
     two_qubit_matrix_to_diagonal_and_operations,
 )
 from cirq.testing import random_two_qubit_circuit_with_czs
 
+ALLOW_DEPRECATION_IN_TEST = 'ALLOW_DEPRECATION_IN_TEST'
+
+
+def test_deprecated_submodule():
+    with cirq.testing.assert_deprecated(
+        "Use cirq.transformers.analytical_decompositions.two_qubit_to_cz instead", deadline="v0.16"
+    ):
+        _ = cirq.optimizers.two_qubit_decompositions.two_qubit_matrix_to_operations
+
 
 @pytest.mark.parametrize(
     'rad,expected',

cirq-core/cirq/optimizers/two_qubit_to_fsim.py renamed to cirq-core/cirq/transformers/analytical_decompositions/two_qubit_to_fsim.py

@@ -1,4 +1,19 @@
-# pylint: disable=wrong-or-nonexistent-copyright-notice
+# Copyright 2022 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.
+
+"""Utility methods for decomposing two-qubit unitaries into FSim gates."""
+
 from typing import (
     Sequence,
     Union,

cirq-core/cirq/optimizers/two_qubit_to_fsim_test.py renamed to cirq-core/cirq/transformers/analytical_decompositions/two_qubit_to_fsim_test.py

@@ -1,4 +1,17 @@
-# pylint: disable=wrong-or-nonexistent-copyright-notice
+# Copyright 2022 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.
+
 import itertools
 import random
 from typing import Any
@@ -7,13 +20,24 @@
 import pytest
 
 import cirq
-from cirq.optimizers.two_qubit_to_fsim import (
+from cirq.transformers.analytical_decompositions.two_qubit_to_fsim import (
     _decompose_two_qubit_interaction_into_two_b_gates,
     _decompose_xx_yy_into_two_fsims_ignoring_single_qubit_ops,
     _sticky_0_to_1,
     _B,
 )
 
+ALLOW_DEPRECATION_IN_TEST = 'ALLOW_DEPRECATION_IN_TEST'
+
+
+def test_deprecated_submodule():
+    with cirq.testing.assert_deprecated(
+        "Use cirq.transformers.analytical_decompositions.two_qubit_to_fsim instead",
+        deadline="v0.16",
+    ):
+        _ = cirq.optimizers.two_qubit_to_fsim.decompose_two_qubit_interaction_into_four_fsim_gates
+
+
 UNITARY_OBJS = [
     cirq.IdentityGate(2),
     cirq.XX ** 0.25,

cirq-core/cirq/optimizers/two_qubit_to_sqrt_iswap.py renamed to cirq-core/cirq/transformers/analytical_decompositions/two_qubit_to_sqrt_iswap.py

@@ -1,4 +1,17 @@
-# pylint: disable=wrong-or-nonexistent-copyright-notice
+# Copyright 2022 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.
+
 """Utility methods for decomposing two-qubit unitaries into sqrt-iSWAP gates.
 
 References: