cirq-core 1.3.0.dev20231201141002__py3-none-any.whl → 1.4.0__py3-none-any.whl

cirq/ops/raw_types_test.py

@@ -490,17 +490,17 @@ def test_cannot_remap_non_measurement_gate():
 
 def test_circuit_diagram():
     class TaggyTag:
-        """Tag with a custom repr function to test circuit diagrams."""
+        """Tag with a custom str function to test circuit diagrams."""
 
-        def __repr__(self):
-            return 'TaggyTag()'
+        def __str__(self):
+            return '<taggy>'
 
     h = cirq.H(cirq.GridQubit(1, 1))
     tagged_h = h.with_tags('tag1')
     non_string_tag_h = h.with_tags(TaggyTag())
 
     expected = cirq.CircuitDiagramInfo(
-        wire_symbols=("H['tag1']",),
+        wire_symbols=("H[tag1]",),
         exponent=1.0,
         connected=True,
         exponent_qubit_index=None,
@@ -511,14 +511,14 @@ def test_circuit_diagram():
     assert cirq.circuit_diagram_info(tagged_h, args) == cirq.circuit_diagram_info(h)
 
     c = cirq.Circuit(tagged_h)
-    diagram_with_tags = "(1, 1): ───H['tag1']───"
+    diagram_with_tags = "(1, 1): ───H[tag1]───"
     diagram_without_tags = "(1, 1): ───H───"
     assert str(cirq.Circuit(tagged_h)) == diagram_with_tags
     assert c.to_text_diagram() == diagram_with_tags
     assert c.to_text_diagram(include_tags=False) == diagram_without_tags
 
     c = cirq.Circuit(non_string_tag_h)
-    diagram_with_non_string_tag = "(1, 1): ───H[TaggyTag()]───"
+    diagram_with_non_string_tag = "(1, 1): ───H[<taggy>]───"
     assert c.to_text_diagram() == diagram_with_non_string_tag
     assert c.to_text_diagram(include_tags=False) == diagram_without_tags
 
@@ -531,7 +531,7 @@ def test_circuit_diagram_tagged_global_phase():
     # Just global phase in a circuit
     assert cirq.circuit_diagram_info(global_phase, default='default') == 'default'
     cirq.testing.assert_has_diagram(
-        cirq.Circuit(global_phase), "\n\nglobal phase:   π['tag0']", use_unicode_characters=True
+        cirq.Circuit(global_phase), "\n\nglobal phase:   π[tag0]", use_unicode_characters=True
     )
     cirq.testing.assert_has_diagram(
         cirq.Circuit(global_phase),
@@ -558,9 +558,7 @@ def test_circuit_diagram_tagged_global_phase():
     no_wire_symbol_op = NoWireSymbols(coefficient=-1.0)().with_tags('tag0')
     assert cirq.circuit_diagram_info(no_wire_symbol_op, default='default') == expected
     cirq.testing.assert_has_diagram(
-        cirq.Circuit(no_wire_symbol_op),
-        "\n\nglobal phase:   π['tag0']",
-        use_unicode_characters=True,
+        cirq.Circuit(no_wire_symbol_op), "\n\nglobal phase:   π[tag0]", use_unicode_characters=True
     )
 
     # Two global phases in one moment
@@ -570,9 +568,9 @@ def test_circuit_diagram_tagged_global_phase():
     cirq.testing.assert_has_diagram(
         c,
         """\
-a: ─────────────X───────────────────
+a: ─────────────X───────────────
 
-global phase:   π['tag1', 'tag2']""",
+global phase:   π[tag1, tag2]""",
         use_unicode_characters=True,
         precision=2,
     )
@@ -583,9 +581,9 @@ global phase:   π['tag1', 'tag2']""",
     cirq.testing.assert_has_diagram(
         c,
         """\
-a: ─────────────X['x_tag']─────X──────────────
+a: ─────────────X[x_tag]─────X────────────
 
-global phase:   0.5π['tag1']   0.5π['tag2']
+global phase:   0.5π[tag1]   0.5π[tag2]
 """,
         use_unicode_characters=True,
         include_tags=True,
@@ -603,7 +601,7 @@ def test_circuit_diagram_no_circuit_diagram():
     q = cirq.GridQubit(1, 1)
     expected = "(1, 1): ───guess-i-will-repr───"
     assert cirq.Circuit(NoCircuitDiagram()(q)).to_text_diagram() == expected
-    expected = "(1, 1): ───guess-i-will-repr['taggy']───"
+    expected = "(1, 1): ───guess-i-will-repr[taggy]───"
     assert cirq.Circuit(NoCircuitDiagram()(q).with_tags('taggy')).to_text_diagram() == expected
 
 
@@ -761,6 +759,7 @@ def test_inverse_composite_standards():
     assert cirq.parameter_names(g) == {'a'}
     assert cirq.resolve_parameters(g, {a: 0}) == Gate(0) ** -1
     cirq.testing.assert_implements_consistent_protocols(g, global_vals={'C': Gate, 'a': a})
+    assert str(g) == 'C(a)†'
 
 
 def test_tagged_act_on():

cirq/ops/uniform_superposition_gate.py

@@ -0,0 +1,123 @@
+# Copyright 2024 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 Sequence, Any, Dict, TYPE_CHECKING
+
+import numpy as np
+from cirq.ops.common_gates import H, ry
+from cirq.ops.pauli_gates import X
+from cirq.ops import raw_types
+
+
+if TYPE_CHECKING:
+    import cirq
+
+
+class UniformSuperpositionGate(raw_types.Gate):
+    r"""Creates a uniform superposition state on the states $[0, M)$
+    The gate creates the state $\frac{1}{\sqrt{M}}\sum_{j=0}^{M-1}\ket{j}$
+    (where $1\leq M \leq 2^n$), using n qubits, according to the Shukla-Vedula algorithm [SV24].
+    References:
+        [SV24]
+        [An efficient quantum algorithm for preparation of uniform quantum superposition
+        states](https://arxiv.org/abs/2306.11747)
+    """
+
+    def __init__(self, m_value: int, num_qubits: int) -> None:
+        """Initializes UniformSuperpositionGate.
+
+        Args:
+            m_value: The number of computational basis states.
+            num_qubits: The number of qubits used.
+
+        Raises:
+            ValueError: If `m_value` is not a positive integer, or
+                if `num_qubits` is not an integer greater than or equal to log2(m_value).
+        """
+        if not (isinstance(m_value, int) and (m_value > 0)):
+            raise ValueError("m_value must be a positive integer.")
+        log_two_m_value = m_value.bit_length()
+
+        if (m_value & (m_value - 1)) == 0:
+            log_two_m_value = log_two_m_value - 1
+        if not (isinstance(num_qubits, int) and (num_qubits >= log_two_m_value)):
+            raise ValueError(
+                "num_qubits must be an integer greater than or equal to log2(m_value)."
+            )
+        self._m_value = m_value
+        self._num_qubits = num_qubits
+
+    def _decompose_(self, qubits: Sequence["cirq.Qid"]) -> "cirq.OP_TREE":
+        """Decomposes the gate into a sequence of standard gates.
+        Implements the construction from https://arxiv.org/pdf/2306.11747.
+        """
+        qreg = list(qubits)
+        qreg.reverse()
+
+        if self._m_value == 1:  #  if m_value is 1, do nothing
+            return
+        if (self._m_value & (self._m_value - 1)) == 0:  # if m_value is an integer power of 2
+            m = self._m_value.bit_length() - 1
+            yield H.on_each(qreg[:m])
+            return
+        k = self._m_value.bit_length()
+        l_value = []
+        for i in range(self._m_value.bit_length()):
+            if (self._m_value >> i) & 1:
+                l_value.append(i)  # Locations of '1's
+
+        yield X.on_each(qreg[q_bit] for q_bit in l_value[1:k])
+        m_current = 2 ** (l_value[0])
+        theta = -2 * np.arccos(np.sqrt(m_current / self._m_value))
+        if l_value[0] > 0:  # if m_value is even
+            yield H.on_each(qreg[: l_value[0]])
+
+        yield ry(theta).on(qreg[l_value[1]])
+
+        for i in range(l_value[0], l_value[1]):
+            yield H(qreg[i]).controlled_by(qreg[l_value[1]], control_values=[False])
+
+        for m in range(1, len(l_value) - 1):
+            theta = -2 * np.arccos(np.sqrt(2 ** l_value[m] / (self._m_value - m_current)))
+            yield ry(theta).on(qreg[l_value[m + 1]]).controlled_by(
+                qreg[l_value[m]], control_values=[0]
+            )
+            for i in range(l_value[m], l_value[m + 1]):
+                yield H.on(qreg[i]).controlled_by(qreg[l_value[m + 1]], control_values=[0])
+
+            m_current = m_current + 2 ** (l_value[m])
+
+    def num_qubits(self) -> int:
+        return self._num_qubits
+
+    @property
+    def m_value(self) -> int:
+        return self._m_value
+
+    def __eq__(self, other):
+        if isinstance(other, UniformSuperpositionGate):
+            return (self._m_value == other._m_value) and (self._num_qubits == other._num_qubits)
+        return False
+
+    def __repr__(self) -> str:
+        return f'UniformSuperpositionGate(m_value={self._m_value}, num_qubits={self._num_qubits})'
+
+    def _json_dict_(self) -> Dict[str, Any]:
+        d = {}
+        d['m_value'] = self._m_value
+        d['num_qubits'] = self._num_qubits
+        return d
+
+    def __str__(self) -> str:
+        return f'UniformSuperpositionGate(m_value={self._m_value}, num_qubits={self._num_qubits})'

cirq/ops/uniform_superposition_gate_test.py

@@ -0,0 +1,94 @@
+# Copyright 2024 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 numpy as np
+import pytest
+import cirq
+
+
+@pytest.mark.parametrize(
+    ["m", "n"],
+    [[int(m), n] for n in range(3, 7) for m in np.random.randint(1, 1 << n, size=3)]
+    + [(1, 2), (4, 2), (6, 3), (7, 3)],
+)
+def test_generated_unitary_is_uniform(m: int, n: int) -> None:
+    r"""The code checks that the unitary matrix corresponds to the generated uniform superposition
+    states (see uniform_superposition_gate.py). It is enough to check that the
+    first colum of the unitary matrix (which corresponds to the action of the gate on
+    $\ket{0}^n$ is $\frac{1}{\sqrt{M}} [1 1  \cdots 1 0 \cdots 0]^T$, where the first $M$
+    entries are all "1"s (excluding the normalization factor of $\frac{1}{\sqrt{M}}$ and the
+    remaining $2^n-M$ entries are all "0"s.
+    """
+    gate = cirq.UniformSuperpositionGate(m, n)
+    matrix = np.array(cirq.unitary(gate))
+    np.testing.assert_allclose(
+        matrix[:, 0], (1 / np.sqrt(m)) * np.array([1] * m + [0] * (2**n - m)), atol=1e-8
+    )
+
+
+@pytest.mark.parametrize(["m", "n"], [(1, 1), (-2, 1), (-3.1, 2), (6, -4), (5, 6.1)])
+def test_incompatible_m_value_and_qubit_args(m: int, n: int) -> None:
+    r"""The code checks that test errors are raised if the arguments m (number of
+    superposition states and n (number of qubits) are positive integers and are compatible
+     (i.e., n >= log2(m)).
+    """
+
+    if not (isinstance(m, int)):
+        with pytest.raises(ValueError, match="m_value must be a positive integer."):
+            cirq.UniformSuperpositionGate(m, n)
+    elif not (isinstance(n, int)):
+        with pytest.raises(
+            ValueError,
+            match="num_qubits must be an integer greater than or equal to log2\\(m_value\\).",
+        ):
+            cirq.UniformSuperpositionGate(m, n)
+    elif m < 1:
+        with pytest.raises(ValueError, match="m_value must be a positive integer."):
+            cirq.UniformSuperpositionGate(int(m), int(n))
+    elif n < np.log2(m):
+        with pytest.raises(
+            ValueError,
+            match="num_qubits must be an integer greater than or equal to log2\\(m_value\\).",
+        ):
+            cirq.UniformSuperpositionGate(m, n)
+
+
+def test_repr():
+    assert (
+        repr(cirq.UniformSuperpositionGate(7, 3))
+        == 'UniformSuperpositionGate(m_value=7, num_qubits=3)'
+    )
+
+
+def test_uniform_superposition_gate_json_dict():
+    assert cirq.UniformSuperpositionGate(7, 3)._json_dict_() == {'m_value': 7, 'num_qubits': 3}
+
+
+def test_str():
+    assert (
+        str(cirq.UniformSuperpositionGate(7, 3))
+        == 'UniformSuperpositionGate(m_value=7, num_qubits=3)'
+    )
+
+
+@pytest.mark.parametrize(["m", "n"], [(5, 3), (10, 4)])
+def test_eq(m: int, n: int) -> None:
+    a = cirq.UniformSuperpositionGate(m, n)
+    b = cirq.UniformSuperpositionGate(m, n)
+    c = cirq.UniformSuperpositionGate(m + 1, n)
+    d = cirq.X
+    assert a.m_value == b.m_value
+    assert a.__eq__(b)
+    assert not (a.__eq__(c))
+    assert not (a.__eq__(d))

cirq/protocols/approximate_equality_protocol_test.py

@@ -47,11 +47,11 @@ def test_approx_eq_mixed_primitives():
 
 def test_numpy_dtype_compatibility():
     i_a, i_b, i_c = 0, 1, 2
-    i_types = [np.intc, np.intp, np.int0, np.int8, np.int16, np.int32, np.int64]
+    i_types = [np.intc, np.intp, np.int8, np.int16, np.int32, np.int64]
     for i_type in i_types:
         assert cirq.approx_eq(i_type(i_a), i_type(i_b), atol=1)
         assert not cirq.approx_eq(i_type(i_a), i_type(i_c), atol=1)
-    u_types = [np.uint, np.uint0, np.uint8, np.uint16, np.uint32, np.uint64]
+    u_types = [np.uint, np.uintp, np.uint8, np.uint16, np.uint32, np.uint64]
     for u_type in u_types:
         assert cirq.approx_eq(u_type(i_a), u_type(i_b), atol=1)
         assert not cirq.approx_eq(u_type(i_a), u_type(i_c), atol=1)

cirq/protocols/circuit_diagram_info_protocol.py

@@ -221,9 +221,11 @@ class CircuitDiagramInfoArgs:
             self.known_qubit_count,
             self.use_unicode_characters,
             self.precision,
-            None
-            if self.label_map is None
-            else tuple(sorted(self.label_map.items(), key=lambda e: e[0])),
+            (
+                None
+                if self.label_map is None
+                else tuple(sorted(self.label_map.items(), key=lambda e: e[0]))
+            ),
             self.include_tags,
             self.transpose,
         )
@@ -354,7 +356,7 @@ def _op_info_with_fallback(
 
     # Add tags onto the representation, if they exist
     if op.tags:
-        name += f'{list(op.tags)}'
+        name += f"[{', '.join(map(str, op.tags))}]"
 
     # Include ordering in the qubit labels.
     symbols = (name,) + tuple(f'#{i + 1}' for i in range(1, len(op.qubits)))

cirq/protocols/commutes_protocol.py

@@ -74,15 +74,13 @@ class SupportsCommutes(Protocol):
 
 
 @overload
-def commutes(v1: Any, v2: Any, *, atol: Union[int, float] = 1e-8) -> bool:
-    ...
+def commutes(v1: Any, v2: Any, *, atol: Union[int, float] = 1e-8) -> bool: ...
 
 
 @overload
 def commutes(
     v1: Any, v2: Any, *, atol: Union[int, float] = 1e-8, default: TDefault
-) -> Union[bool, TDefault]:
-    ...
+) -> Union[bool, TDefault]: ...
 
 
 def commutes(

cirq/protocols/decompose_protocol.py

@@ -57,8 +57,7 @@ _CONTEXT_COUNTER = itertools.count()  # Use _reset_context_counter() to reset th
 class OpDecomposerWithContext(Protocol):
     def __call__(
         self, __op: 'cirq.Operation', *, context: Optional['cirq.DecompositionContext'] = None
-    ) -> DecomposeResult:
-        ...
+    ) -> DecomposeResult: ...
 
 
 OpDecomposer = Union[Callable[['cirq.Operation'], DecomposeResult], OpDecomposerWithContext]
@@ -93,16 +92,12 @@ class SupportsDecompose(Protocol):
     """An object that can be decomposed into simpler operations.
 
     All decomposition methods should ultimately terminate on basic 1-qubit and
-    2-qubit gates included by default in Cirq. Cirq does not make any guarantees
-    about what the final gate set is. Currently, decompositions within Cirq
-    happen to converge towards the X, Y, Z, CZ, PhasedX, specified-matrix gates,
-    and others. This set will vary from release to release. Because of this
-    variability, it is important for consumers of decomposition to look for
-    generic properties of gates, such as "two qubit gate with a unitary matrix",
-    instead of specific gate types such as CZ gates (though a consumer is
-    of course free to handle CZ gates in a special way, and consumers can
-    give an `intercepting_decomposer` to `cirq.decompose` that attempts to
-    target a specific gate set).
+    2-qubit gates included by default in Cirq. If a custom decomposition is not
+    specified, Cirq will decompose all operations to XPow/YPow/ZPow/CZPow/Measurement
+    + Global phase gateset. However, the default decomposition in Cirq should be a last resort
+    fallback and it is recommended for consumers of decomposition to either not depend
+    upon a specific target gateset, or give an `intercepting_decomposer` to `cirq.decompose`
+    that attempts to target a specific gate set.
 
     For example, `cirq.TOFFOLI` has a `_decompose_` method that returns a pair
     of Hadamard gates surrounding a `cirq.CCZ`. Although `cirq.CCZ` is not a

cirq/protocols/decompose_protocol_test.py

@@ -346,9 +346,13 @@ class RecursiveDecompose(cirq.Gate):
 
     def _decompose_impl(self, qubits, mock_qm: mock.Mock):
         mock_qm.qalloc(self.recurse)
-        yield RecursiveDecompose(
-            recurse=False, mock_qm=self.mock_qm, with_context=self.with_context
-        ).on(*qubits) if self.recurse else cirq.Z.on_each(*qubits)
+        yield (
+            RecursiveDecompose(
+                recurse=False, mock_qm=self.mock_qm, with_context=self.with_context
+            ).on(*qubits)
+            if self.recurse
+            else cirq.Z.on_each(*qubits)
+        )
         mock_qm.qfree(self.recurse)
 
     def _decompose_(self, qubits):

cirq/protocols/has_stabilizer_effect_protocol.py

@@ -102,11 +102,7 @@ def _strat_has_stabilizer_effect_from_unitary(val: Any) -> Optional[bool]:
 
 
 def _strat_has_stabilizer_effect_from_decompose(val: Any) -> Optional[bool]:
-    qid_shape = qid_shape_protocol.qid_shape(val, default=None)
-    if qid_shape is None or len(qid_shape) <= 3:
-        return None
-
-    decomposition = decompose_protocol.decompose_once(val, default=None)
+    decomposition, _, _ = decompose_protocol._try_decompose_into_operations_and_qubits(val)
     if decomposition is None:
         return None
     for op in decomposition:

cirq/protocols/has_stabilizer_effect_protocol_test.py

@@ -41,15 +41,15 @@ class Yes:
         return True
 
 
-q = cirq.LineQubit(0)
-
-
 class EmptyOp(cirq.Operation):
     """A trivial operation."""
 
+    def __init__(self, q: cirq.Qid = cirq.LineQubit(0)):
+        self.q = q
+
     @property
     def qubits(self):
-        return (q,)
+        return (self.q,)
 
     def with_qubits(self, *new_qubits):  # pragma: no cover
         return self
@@ -97,6 +97,14 @@ class OpWithUnitary(EmptyOp):
         return cirq.LineQubit.range(self.unitary.shape[0].bit_length() - 1)
 
 
+class GateDecomposes(cirq.Gate):
+    def _num_qubits_(self):
+        return 1
+
+    def _decompose_(self, qubits):
+        yield YesOp(*qubits)
+
+
 def test_inconclusive():
     assert not cirq.has_stabilizer_effect(object())
     assert not cirq.has_stabilizer_effect('boo')
@@ -146,3 +154,4 @@ def test_via_decompose():
     assert not cirq.has_stabilizer_effect(
         OpWithUnitary(cirq.unitary(cirq.Circuit(cirq.T.on_each(cirq.LineQubit.range(4)))))
     )
+    assert cirq.has_stabilizer_effect(GateDecomposes())