Address comments, add docstrings, add tests

Author: cduck

cirq-core/cirq/optimizers/merge_interactions.py

@@ -35,6 +35,14 @@ def __init__(
         tolerance: float = 1e-8,
         post_clean_up: Callable[[Sequence[ops.Operation]], ops.OP_TREE] = lambda op_list: op_list,
     ) -> None:
+        """
+        Args:
+            tolerance: A limit on the amount of absolute error introduced by the
+                construction.
+            post_clean_up: This function is called on each set of optimized
+                operations before they are put into the circuit to replace the
+                old operations.
+        """
         super().__init__(post_clean_up=post_clean_up)
         self.tolerance = tolerance
 
@@ -62,7 +70,7 @@ def optimization_at(
         if not switch_to_new and old_interaction_count <= 1:
             return None
 
-        # Find a max-3-cz construction.
+        # Find a (possibly ideal) decomposition of the merged operations.
         new_operations = self._two_qubit_matrix_to_operations(op.qubits[0], op.qubits[1], matrix)
         new_interaction_count = len(
             [new_op for new_op in new_operations if len(new_op.qubits) == 2]
@@ -207,6 +215,15 @@ def __init__(
         allow_partial_czs: bool = True,
         post_clean_up: Callable[[Sequence[ops.Operation]], ops.OP_TREE] = lambda op_list: op_list,
     ) -> None:
+        """
+        Args:
+            tolerance: A limit on the amount of absolute error introduced by the
+                construction.
+            allow_partial_czs: Enables the use of Partial-CZ gates.
+            post_clean_up: This function is called on each set of optimized
+                operations before they are put into the circuit to replace the
+                old operations.
+        """
         super().__init__(tolerance=tolerance, post_clean_up=post_clean_up)
         self.allow_partial_czs = allow_partial_czs
 

cirq-core/cirq/optimizers/merge_interactions_to_sqrt_iswap.py

@@ -1,4 +1,4 @@
-# Copyright 2018 The Cirq Developers
+# 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.
@@ -15,7 +15,7 @@
 """An optimization pass that combines adjacent series of gates on two qubits and
 outputs a circuit with SQRT_ISWAP or SQRT_ISWAP_INV gates."""
 
-from typing import Callable, Sequence, TYPE_CHECKING
+from typing import Callable, Optional, Sequence, TYPE_CHECKING
 
 import numpy as np
 
@@ -29,22 +29,51 @@
 class MergeInteractionsToSqrtIswap(merge_interactions.MergeInteractionsAbc):
     """Combines series of adjacent one and two-qubit gates operating on a pair
     of qubits and replaces each series with the minimum number of SQRT_ISWAP
-    gates."""
+    gates.
+
+    See also: ``two_qubit_matrix_to_sqrt_iswap_operations``
+    """
 
     def __init__(
         self,
         tolerance: float = 1e-8,
-        require_three_sqrt_iswap: bool = False,
+        *,
+        required_sqrt_iswap_count: Optional[int] = None,
         use_sqrt_iswap_inv: bool = False,
         post_clean_up: Callable[[Sequence[ops.Operation]], ops.OP_TREE] = lambda op_list: op_list,
     ) -> None:
+        """
+        Args:
+            tolerance: A limit on the amount of absolute error introduced by the
+                construction.
+            required_sqrt_iswap_count: When specified, each merged group of
+                two-qubit gates will be decomposed into exactly this many
+                sqrt-iSWAP gates even if fewer is possible (maximum 3).  Circuit
+                optimization will raise a ``ValueError`` if this number is 2 or
+                lower and synthesis of any set of merged interactions requires
+                more.
+            use_sqrt_iswap_inv: If True, optimizes circuits using
+                ``SQRT_ISWAP_INV`` gates instead of ``SQRT_ISWAP``.
+            post_clean_up: This function is called on each set of optimized
+                operations before they are put into the circuit to replace the
+                old operations.
+
+        Raises:
+            ValueError:
+                If ``required_sqrt_iswap_count`` is not one of the supported
+                values 0, 1, 2, or 3.
+        """
+        if required_sqrt_iswap_count is not None and not 0 <= required_sqrt_iswap_count <= 3:
+            raise ValueError('the argument `required_sqrt_iswap_count` must be 0, 1, 2, or 3.')
         super().__init__(tolerance=tolerance, post_clean_up=post_clean_up)
-        self.require_three_sqrt_iswap = require_three_sqrt_iswap
+        self.required_sqrt_iswap_count = required_sqrt_iswap_count
         self.use_sqrt_iswap_inv = use_sqrt_iswap_inv
 
     def _may_keep_old_op(self, old_op: 'cirq.Operation') -> bool:
         """Returns True if the old two-qubit operation may be left unchanged
         without decomposition."""
+        if self.use_sqrt_iswap_inv:
+            return isinstance(old_op.gate, ops.ISwapPowGate) and old_op.gate.exponent == -0.5
         return isinstance(old_op.gate, ops.ISwapPowGate) and old_op.gate.exponent == 0.5
 
     def _two_qubit_matrix_to_operations(
@@ -68,7 +97,7 @@ def _two_qubit_matrix_to_operations(
             q0,
             q1,
             mat,
-            required_sqrt_iswap_count=3 if self.require_three_sqrt_iswap else None,
+            required_sqrt_iswap_count=self.required_sqrt_iswap_count,
             use_sqrt_iswap_inv=self.use_sqrt_iswap_inv,
             atol=self.tolerance,
             check_preconditions=False,

cirq-core/cirq/optimizers/merge_interactions_to_sqrt_iswap_test.py

@@ -1,10 +1,38 @@
+# 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 Callable, List
 
+import pytest
+
 import cirq
 
 
 def assert_optimizes(before: cirq.Circuit, expected: cirq.Circuit, **kwargs):
-    actual = cirq.Circuit(before)
+    """Check that optimizing the circuit ``before`` produces the circuit ``expected``.
+
+    The optimized circuit is cleaned up with follow up optimizations to make the
+    comparison more robust to extra moments or extra gates nearly equal to
+    identity that don't matter.
+
+    Args:
+        before: The input circuit to optimize.
+        expected: The expected result of optimization to compare against.
+        kwargs: Any extra arguments to pass to the
+            ``MergeInteractionsToSqrtIswap`` constructor.
+    """
+    actual = before.copy()
     opt = cirq.MergeInteractionsToSqrtIswap(**kwargs)
     opt.optimize_circuit(actual)
 
@@ -23,21 +51,21 @@ def assert_optimizes(before: cirq.Circuit, expected: cirq.Circuit, **kwargs):
     assert actual == expected, f'ACTUAL {actual} : EXPECTED {expected}'
 
 
-def assert_optimization_not_broken(circuit: cirq.Circuit):
+def assert_optimization_not_broken(circuit: cirq.Circuit, **kwargs):
     """Check that the unitary matrix for the input circuit is the same (up to
     global phase and rounding error) as the unitary matrix of the optimized
     circuit."""
     u_before = circuit.unitary()
     c_sqrt_iswap = circuit.copy()
-    cirq.MergeInteractionsToSqrtIswap().optimize_circuit(c_sqrt_iswap)
-    u_after = c_sqrt_iswap.unitary()
+    cirq.MergeInteractionsToSqrtIswap(**kwargs).optimize_circuit(c_sqrt_iswap)
+    u_after = c_sqrt_iswap.unitary(circuit.all_qubits())
 
     cirq.testing.assert_allclose_up_to_global_phase(u_before, u_after, atol=2e-8)
 
     # Also test optimization with SQRT_ISWAP_INV
     c_sqrt_iswap_inv = circuit.copy()
     cirq.MergeInteractionsToSqrtIswap(use_sqrt_iswap_inv=True).optimize_circuit(c_sqrt_iswap_inv)
-    u_after2 = c_sqrt_iswap_inv.unitary()
+    u_after2 = c_sqrt_iswap_inv.unitary(circuit.all_qubits())
 
     cirq.testing.assert_allclose_up_to_global_phase(u_before, u_after2, atol=2e-8)
 
@@ -106,6 +134,57 @@ def test_simplifies_sqrt_iswap_inv():
     )
 
 
+def test_works_with_tags():
+    a, b = cirq.LineQubit.range(2)
+    assert_optimizes(
+        before=cirq.Circuit(
+            [
+                cirq.Moment([cirq.SQRT_ISWAP(a, b).with_tags('mytag1')]),
+                cirq.Moment([cirq.SQRT_ISWAP(a, b).with_tags('mytag2')]),
+                cirq.Moment([cirq.SQRT_ISWAP_INV(a, b).with_tags('mytag3')]),
+            ]
+        ),
+        expected=cirq.Circuit(
+            [
+                cirq.Moment([cirq.SQRT_ISWAP(a, b)]),
+            ]
+        ),
+    )
+
+
+def test_no_touch_single_sqrt_iswap():
+    a, b = cirq.LineQubit.range(2)
+    assert_optimizes(
+        before=cirq.Circuit(
+            [
+                cirq.Moment([cirq.SQRT_ISWAP(a, b).with_tags('mytag')]),
+            ]
+        ),
+        expected=cirq.Circuit(
+            [
+                cirq.Moment([cirq.SQRT_ISWAP(a, b).with_tags('mytag')]),
+            ]
+        ),
+    )
+
+
+def test_no_touch_single_sqrt_iswap_inv():
+    a, b = cirq.LineQubit.range(2)
+    assert_optimizes(
+        use_sqrt_iswap_inv=True,
+        before=cirq.Circuit(
+            [
+                cirq.Moment([cirq.SQRT_ISWAP_INV(a, b).with_tags('mytag')]),
+            ]
+        ),
+        expected=cirq.Circuit(
+            [
+                cirq.Moment([cirq.SQRT_ISWAP_INV(a, b).with_tags('mytag')]),
+            ]
+        ),
+    )
+
+
 def test_cnots_separated_by_single_gates_correct():
     a, b = cirq.LineQubit.range(2)
     assert_optimization_not_broken(
@@ -165,23 +244,73 @@ def test_optimizes_single_iswap():
 
 def test_optimizes_single_inv_sqrt_iswap():
     a, b = cirq.LineQubit.range(2)
-    c = cirq.Circuit(cirq.SQRT_ISWAP(a, b) ** -1)
+    c = cirq.Circuit(cirq.SQRT_ISWAP_INV(a, b))
     assert_optimization_not_broken(c)
     cirq.MergeInteractionsToSqrtIswap().optimize_circuit(c)
     assert len([1 for op in c.all_operations() if len(op.qubits) == 2]) == 1
 
 
+def test_init_raises():
+    with pytest.raises(ValueError, match='must be 0, 1, 2, or 3'):
+        cirq.MergeInteractionsToSqrtIswap(required_sqrt_iswap_count=4)
+
+
+def test_optimizes_single_iswap_require0():
+    a, b = cirq.LineQubit.range(2)
+    c = cirq.Circuit(cirq.CNOT(a, b), cirq.CNOT(a, b))  # Minimum 0 sqrt-iSWAP
+    assert_optimization_not_broken(c, required_sqrt_iswap_count=0)
+    cirq.MergeInteractionsToSqrtIswap(required_sqrt_iswap_count=0).optimize_circuit(c)
+    assert len([1 for op in c.all_operations() if len(op.qubits) == 2]) == 0
+
+
+def test_optimizes_single_iswap_require0_raises():
+    a, b = cirq.LineQubit.range(2)
+    c = cirq.Circuit(cirq.CNOT(a, b))  # Minimum 2 sqrt-iSWAP
+    with pytest.raises(ValueError, match='cannot be decomposed into exactly 0 sqrt-iSWAP gates'):
+        cirq.MergeInteractionsToSqrtIswap(required_sqrt_iswap_count=0).optimize_circuit(c)
+
+
+def test_optimizes_single_iswap_require1():
+    a, b = cirq.LineQubit.range(2)
+    c = cirq.Circuit(cirq.SQRT_ISWAP_INV(a, b))  # Minimum 1 sqrt-iSWAP
+    assert_optimization_not_broken(c, required_sqrt_iswap_count=1)
+    cirq.MergeInteractionsToSqrtIswap(required_sqrt_iswap_count=1).optimize_circuit(c)
+    assert len([1 for op in c.all_operations() if len(op.qubits) == 2]) == 1
+
+
+def test_optimizes_single_iswap_require1_raises():
+    a, b = cirq.LineQubit.range(2)
+    c = cirq.Circuit(cirq.CNOT(a, b))  # Minimum 2 sqrt-iSWAP
+    with pytest.raises(ValueError, match='cannot be decomposed into exactly 1 sqrt-iSWAP gates'):
+        cirq.MergeInteractionsToSqrtIswap(required_sqrt_iswap_count=1).optimize_circuit(c)
+
+
+def test_optimizes_single_iswap_require2():
+    a, b = cirq.LineQubit.range(2)
+    c = cirq.Circuit(cirq.SQRT_ISWAP_INV(a, b))  # Minimum 1 sqrt-iSWAP but 2 possible
+    assert_optimization_not_broken(c, required_sqrt_iswap_count=2)
+    cirq.MergeInteractionsToSqrtIswap(required_sqrt_iswap_count=2).optimize_circuit(c)
+    assert len([1 for op in c.all_operations() if len(op.qubits) == 2]) == 2
+
+
+def test_optimizes_single_iswap_require2_raises():
+    a, b = cirq.LineQubit.range(2)
+    c = cirq.Circuit(cirq.SWAP(a, b))  # Minimum 3 sqrt-iSWAP
+    with pytest.raises(ValueError, match='cannot be decomposed into exactly 2 sqrt-iSWAP gates'):
+        cirq.MergeInteractionsToSqrtIswap(required_sqrt_iswap_count=2).optimize_circuit(c)
+
+
 def test_optimizes_single_iswap_require3():
     a, b = cirq.LineQubit.range(2)
-    c = cirq.Circuit(cirq.ISWAP(a, b))
-    assert_optimization_not_broken(c)
-    cirq.MergeInteractionsToSqrtIswap(require_three_sqrt_iswap=True).optimize_circuit(c)
+    c = cirq.Circuit(cirq.ISWAP(a, b))  # Minimum 2 sqrt-iSWAP but 3 possible
+    assert_optimization_not_broken(c, required_sqrt_iswap_count=3)
+    cirq.MergeInteractionsToSqrtIswap(required_sqrt_iswap_count=3).optimize_circuit(c)
     assert len([1 for op in c.all_operations() if len(op.qubits) == 2]) == 3
 
 
 def test_optimizes_single_inv_sqrt_iswap_require3():
     a, b = cirq.LineQubit.range(2)
-    c = cirq.Circuit(cirq.SQRT_ISWAP(a, b) ** -1)
-    assert_optimization_not_broken(c)
-    cirq.MergeInteractionsToSqrtIswap(require_three_sqrt_iswap=True).optimize_circuit(c)
+    c = cirq.Circuit(cirq.SQRT_ISWAP_INV(a, b))
+    assert_optimization_not_broken(c, required_sqrt_iswap_count=3)
+    cirq.MergeInteractionsToSqrtIswap(required_sqrt_iswap_count=3).optimize_circuit(c)
     assert len([1 for op in c.all_operations() if len(op.qubits) == 2]) == 3