cirq-core 1.7.0.dev20250825174419__py3-none-any.whl → 1.7.0.dev20251203004401__py3-none-any.whl

cirq/experiments/ghz_2d.py

@@ -0,0 +1,150 @@
+# Copyright 2025 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.
+
+"""Functions for generating and transforming 2D GHZ circuits."""
+
+import networkx as nx
+import numpy as np
+
+import cirq.circuits as circuits
+import cirq.devices as devices
+import cirq.ops as ops
+import cirq.protocols as protocols
+import cirq.transformers as transformers
+
+
+def _transform_circuit(circuit: circuits.Circuit) -> circuits.Circuit:
+    """Transforms a Cirq circuit by applying a series of modifications.
+
+    This is an internal helper function used exclusively by
+    `generate_2d_ghz_circuit` when `add_dd_and_align_right` is True.
+
+    The transformations for a circuit include:
+    1. Adding a measurement to all qubits with a key 'm'.
+       It serves as a stopping gate for the DD operation.
+    2. Aligning the circuit and merging single-qubit gates.
+    3. Stratifying the operations based on qubit count
+    (1-qubit and 2-qubit gates).
+    4. Applying dynamical decoupling to mitigate noise.
+    5. Removing the final measurement operation to yield
+       the state preparation circuit.
+
+    Args:
+        circuit: A cirq.Circuit object.
+
+    Returns:
+        The modified cirq.Circuit object.
+    """
+    qubits = list(circuit.all_qubits())
+    circuit = circuit + circuits.Circuit(ops.measure(*qubits, key="m"))
+    circuit = transformers.align_right(transformers.merge_single_qubit_gates_to_phxz(circuit))
+    circuit = transformers.stratified_circuit(
+        circuit[::-1], categories=[lambda op: protocols.num_qubits(op) == k for k in (1, 2)]
+    )[::-1]
+    circuit = transformers.add_dynamical_decoupling(circuit)
+    circuit = circuits.Circuit(circuit[:-1])
+    return circuit
+
+
+def generate_2d_ghz_circuit(
+    center: devices.GridQubit,
+    graph: nx.Graph,
+    num_qubits: int,
+    randomized: bool = False,
+    rng_or_seed: int | np.random.Generator | None = None,
+    add_dd_and_align_right: bool = False,
+) -> circuits.Circuit:
+    """Generates a 2D GHZ state circuit with 'num_qubits' qubits using BFS.
+
+    The circuit is constructed by connecting qubits
+    sequentially based on graph connectivity,
+    starting from the 'center' qubit.
+    The GHZ state is built using a series of H-CZ-H
+    gate sequences.
+
+
+    Args:
+        center: The starting qubit for the GHZ state.
+        graph: The connectivity graph of the qubits.
+        num_qubits:  The number of qubits for the final
+                     GHZ state. Must be greater than 0,
+                     and less than or equal to
+                     the total number of qubits
+                     on the processor.
+        randomized:  If True, neighbors are
+                     added to the circuit in a random order.
+                     If False, they are
+                     added by distance from the center.
+        rng_or_seed: An optional seed or numpy random number
+                     generator. Used only when randomized is True
+        add_dd_and_align_right: If True, adds dynamical
+                                decoupling and aligns right.
+
+    Returns:
+        A cirq.Circuit object for the GHZ state.
+
+    Raises:
+        ValueError: If num_qubits is non-positive or exceeds the total
+                    number of qubits on the processor.
+    """
+    if num_qubits <= 0:
+        raise ValueError("num_qubits must be a positive integer.")
+
+    if num_qubits > len(graph.nodes):
+        raise ValueError("num_qubits cannot exceed the total number of qubits on the processor.")
+
+    if randomized:
+        rng = (
+            rng_or_seed
+            if isinstance(rng_or_seed, np.random.Generator)
+            else np.random.default_rng(rng_or_seed)
+        )
+
+        def sort_neighbors_fn(neighbors: list) -> list:
+            """If 'randomized' is True, sort the neighbors randomly."""
+            neighbors = list(neighbors)
+            rng.shuffle(neighbors)
+            return neighbors
+
+    else:
+
+        def sort_neighbors_fn(neighbors: list) -> list:
+            """If 'randomized' is False, sort the neighbors as per
+            distance from the center.
+            """
+            return sorted(
+                neighbors, key=lambda q: (q.row - center.row) ** 2 + (q.col - center.col) ** 2
+            )
+
+    bfs_tree = nx.bfs_tree(graph, center, sort_neighbors=sort_neighbors_fn)
+    qubits_to_include = list(bfs_tree.nodes)[:num_qubits]
+    final_tree = bfs_tree.subgraph(qubits_to_include)
+
+    ghz_ops = []
+
+    for node in nx.topological_sort(final_tree):
+        # Handling the center qubit first
+        if node == center:
+            ghz_ops.append(ops.H(node))
+            continue
+
+        for parent in final_tree.predecessors(node):
+            ghz_ops.extend([ops.H(node), ops.CZ(parent, node), ops.H(node)])
+
+    circuit = circuits.Circuit(ghz_ops)
+
+    if add_dd_and_align_right:
+        return _transform_circuit(circuit)
+    else:
+        return circuit

cirq/experiments/ghz_2d_test.py

@@ -0,0 +1,155 @@
+# Copyright 2025 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.
+
+"""Tests for generating and validating 2D GHZ state circuits."""
+
+from typing import cast
+
+import networkx as nx
+import numpy as np
+import pytest
+
+import cirq
+import cirq.experiments.ghz_2d as ghz_2d
+
+
+def _create_mock_graph():
+    qubits = cirq.GridQubit.rect(6, 6)
+    g = nx.Graph()
+    for q in qubits:
+        g.add_node(q)
+        if q.col + 1 < 6:
+            g.add_edge(q, cirq.GridQubit(q.row, q.col + 1))
+        if q.row + 1 < 6:
+            g.add_edge(q, cirq.GridQubit(q.row + 1, q.col))
+    return g, cirq.GridQubit(3, 3)
+
+
+graph, center_qubit = _create_mock_graph()
+
+
+@pytest.mark.parametrize("num_qubits", list(range(1, len(graph.nodes) + 1)))
+@pytest.mark.parametrize("randomized", [True, False])
+@pytest.mark.parametrize("add_dd_and_align_right", [True, False])
+def test_ghz_circuits_size(num_qubits: int, randomized: bool, add_dd_and_align_right: bool) -> None:
+    """Tests the size of the GHZ circuits."""
+    circuit = ghz_2d.generate_2d_ghz_circuit(
+        center_qubit,
+        graph,
+        num_qubits=num_qubits,
+        randomized=randomized,
+        add_dd_and_align_right=add_dd_and_align_right,
+    )
+    assert len(circuit.all_qubits()) == num_qubits
+
+
+@pytest.mark.parametrize("num_qubits", [2, 3, 4, 5, 6, 8, 10])
+@pytest.mark.parametrize("randomized", [True, False])
+@pytest.mark.parametrize("add_dd_and_align_right", [True, False])  # , True
+def test_ghz_circuits_state(
+    num_qubits: int, randomized: bool, add_dd_and_align_right: bool
+) -> None:
+    """Tests the state vector form of the GHZ circuits."""
+
+    circuit = ghz_2d.generate_2d_ghz_circuit(
+        center_qubit,
+        graph,
+        num_qubits=num_qubits,
+        randomized=randomized,
+        add_dd_and_align_right=add_dd_and_align_right,
+    )
+
+    simulator = cirq.Simulator()
+    result = simulator.simulate(circuit)
+    state = result.final_state_vector
+
+    np.testing.assert_allclose(np.abs(state[0]), 1 / np.sqrt(2), atol=1e-7)
+    np.testing.assert_allclose(np.abs(state[-1]), 1 / np.sqrt(2), atol=1e-7)
+
+    if num_qubits > 1:
+        np.testing.assert_allclose(state[1:-1], 0)
+
+
+def test_transform_circuit_properties() -> None:
+    """Tests that _transform_circuit preserves circuit properties."""
+    circuit = ghz_2d.generate_2d_ghz_circuit(
+        center_qubit, graph, num_qubits=9, randomized=False, add_dd_and_align_right=False
+    )
+    transformed_circuit = ghz_2d._transform_circuit(circuit)
+
+    assert transformed_circuit.all_qubits() == circuit.all_qubits()
+
+    assert len(transformed_circuit) >= len(circuit)
+
+    final_moment = transformed_circuit[-1]
+    assert not any(isinstance(op.gate, cirq.MeasurementGate) for op in final_moment)
+
+    assert cirq.equal_up_to_global_phase(circuit.unitary(), transformed_circuit.unitary())
+
+
+def manhattan_distance(q1: cirq.GridQubit, q2: cirq.GridQubit) -> int:
+    """Calculates the Manhattan distance between two GridQubits."""
+    return abs(q1.row - q2.row) + abs(q1.col - q2.col)
+
+
+@pytest.mark.parametrize("num_qubits", [2, 4, 9, 15, 20])
+def test_ghz_circuits_bfs_order(num_qubits: int) -> None:
+    """Verifies that the circuit construction maintains BFS order"""
+
+    circuit = ghz_2d.generate_2d_ghz_circuit(
+        center_qubit,
+        graph,
+        num_qubits=num_qubits,
+        randomized=False,  # Test must run on the deterministic BFS order
+        add_dd_and_align_right=False,  # Test must run on the raw circuit
+    )
+
+    max_dist_seen = 0
+
+    for moment in circuit:
+        for op in moment:
+            if isinstance(op.gate, cirq.CZPowGate):
+                qubits = op.qubits
+
+                dist_q0 = manhattan_distance(center_qubit, cast(cirq.GridQubit, qubits[0]))
+                dist_q1 = manhattan_distance(center_qubit, cast(cirq.GridQubit, qubits[1]))
+
+                child_qubit_distance = max(dist_q0, dist_q1)
+
+                if child_qubit_distance > max_dist_seen:
+                    assert child_qubit_distance == max_dist_seen + 1
+                    max_dist_seen = child_qubit_distance
+
+                assert child_qubit_distance <= max_dist_seen
+
+    included_qubits = circuit.all_qubits()
+    if included_qubits:
+        max_dist_required = max(
+            manhattan_distance(center_qubit, cast(cirq.GridQubit, q)) for q in included_qubits
+        )
+        assert max_dist_seen == max_dist_required
+
+
+def test_ghz_invalid_inputs():
+    """Tests that the function raises errors for invalid inputs."""
+
+    with pytest.raises(ValueError, match="num_qubits must be a positive integer."):
+        ghz_2d.generate_2d_ghz_circuit(center_qubit, graph, num_qubits=0)  # invalid
+
+    with pytest.raises(
+        ValueError, match="num_qubits cannot exceed the total number of qubits on the processor."
+    ):
+        ghz_2d.generate_2d_ghz_circuit(
+            center_qubit, graph, num_qubits=len(graph.nodes) + 1  # invalid
+        )

cirq/experiments/n_qubit_tomography.py

@@ -20,7 +20,8 @@ so that occurs outside of the StateTomographyExperiment class.
 
 from __future__ import annotations
 
-from typing import Sequence, TYPE_CHECKING
+from collections.abc import Sequence
+from typing import TYPE_CHECKING
 
 import numpy as np
 import sympy

cirq/experiments/n_qubit_tomography_test.py

@@ -14,7 +14,7 @@
 
 from __future__ import annotations
 
-from typing import Sequence
+from collections.abc import Sequence
 
 import numpy as np
 import pytest

cirq/experiments/purity_estimation.py

@@ -14,7 +14,7 @@
 
 from __future__ import annotations
 
-from typing import Sequence
+from collections.abc import Sequence
 
 import numpy as np
 

cirq/experiments/qubit_characterizations.py

@@ -18,7 +18,8 @@ import dataclasses
 import functools
 import itertools
 import uuid
-from typing import Any, cast, Iterator, Mapping, Sequence, TYPE_CHECKING
+from collections.abc import Iterator, Mapping, Sequence
+from typing import Any, cast, Optional, TYPE_CHECKING
 
 import attrs
 import numpy as np
@@ -73,7 +74,12 @@ class Cliffords:
 class RandomizedBenchMarkResult:
     """Results from a randomized benchmarking experiment."""
 
-    def __init__(self, num_cliffords: Sequence[int], ground_state_probabilities: Sequence[float]):
+    def __init__(
+        self,
+        num_cliffords: Sequence[int],
+        ground_state_probabilities: Sequence[float],
+        ground_state_probabilities_std: Optional[Sequence[float]] | None = None,
+    ):
         """Inits RandomizedBenchMarkResult.
 
         Args:
@@ -81,9 +87,20 @@ class RandomizedBenchMarkResult:
                 study.
             ground_state_probabilities: The corresponding average ground state
                 probabilities.
+            ground_state_probabilities_std: The standard deviation of the probabilities.
         """
         self._num_cfds_seq = num_cliffords
         self._gnd_state_probs = ground_state_probabilities
+        if ground_state_probabilities_std is None or np.all(
+            np.isclose(ground_state_probabilities_std, 0)
+        ):
+            self._gnd_state_probs_std = None
+        else:
+            self._gnd_state_probs_std = np.array(ground_state_probabilities_std)
+            zeros = np.isclose(self._gnd_state_probs_std, 0)
+            self._gnd_state_probs_std[zeros] = self._gnd_state_probs_std[
+                np.logical_not(zeros)
+            ].min()
 
     @property
     def data(self) -> Sequence[tuple[int, float]]:
@@ -142,6 +159,7 @@ class RandomizedBenchMarkResult:
             f=exp_fit,
             xdata=self._num_cfds_seq,
             ydata=self._gnd_state_probs,
+            sigma=self._gnd_state_probs_std,
             p0=[0.5, 0.5, 1.0 - 1e-3],
             bounds=([0, -1, 0], [1, 1, 1]),
         )
@@ -534,6 +552,7 @@ def parallel_single_qubit_rb(
     # run circuits
     results = sampler.run_batch(circuits_all, repetitions=parameters.repetitions)
     gnd_probs: dict = {q: [] for q in qubits}
+    gnd_probs_std: dict = {q: [] for q in qubits}
     idx = 0
     for num_cliffords in parameters.num_clifford_range:
         excited_probs: dict[cirq.Qid, list[float]] = {q: [] for q in qubits}
@@ -544,9 +563,17 @@ def parallel_single_qubit_rb(
             idx += 1
         for qubit in qubits:
             gnd_probs[qubit].append(1.0 - np.mean(excited_probs[qubit]))
+            gnd_probs_std[qubit].append(
+                np.std(excited_probs[qubit]) / np.sqrt(parameters.repetitions)
+            )
 
     return ParallelRandomizedBenchmarkingResult(
-        {q: RandomizedBenchMarkResult(parameters.num_clifford_range, gnd_probs[q]) for q in qubits}
+        {
+            q: RandomizedBenchMarkResult(
+                parameters.num_clifford_range, gnd_probs[q], gnd_probs_std[q]
+            )
+            for q in qubits
+        }
     )
 
 
@@ -595,6 +622,7 @@ def two_qubit_randomized_benchmarking(
     cliffords = _single_qubit_cliffords()
     cfd_matrices = _two_qubit_clifford_matrices(first_qubit, second_qubit, cliffords)
     gnd_probs = []
+    gnd_probs_std = []
     for num_cfds in num_clifford_range:
         gnd_probs_l = []
         for _ in range(num_circuits):
@@ -606,8 +634,9 @@ def two_qubit_randomized_benchmarking(
             gnds = [(not r[0] and not r[1]) for r in results.measurements['z']]
             gnd_probs_l.append(np.mean(gnds))
         gnd_probs.append(float(np.mean(gnd_probs_l)))
+        gnd_probs_std.append(float(np.std(gnd_probs_l) / np.sqrt(repetitions)))
 
-    return RandomizedBenchMarkResult(num_clifford_range, gnd_probs)
+    return RandomizedBenchMarkResult(num_clifford_range, gnd_probs, gnd_probs_std)
 
 
 def single_qubit_state_tomography(

cirq/experiments/qubit_characterizations_test.py

@@ -140,6 +140,22 @@ def test_parallel_single_qubit_parallel_single_qubit_randomized_benchmarking() -
     _ = results.plot_integrated_histogram()
 
 
+@mock.patch.dict(os.environ, clear='CIRQ_TESTING')
+def test_parallel_single_qubit_randomized_benchmarking_with_noise() -> None:
+    simulator = sim.Simulator(noise=cirq.depolarize(1e-3), seed=0)
+    qubits = (GridQubit(0, 0), GridQubit(0, 1))
+    num_cfds = range(5, 7, 1)
+    results = parallel_single_qubit_randomized_benchmarking(
+        simulator, num_clifford_range=num_cfds, repetitions=10, qubits=qubits
+    )
+    for qubit in qubits:
+        g_pops = np.asarray(results.results_dictionary[qubit].data)[:, 1]
+        assert np.isclose(np.mean(g_pops), 0.99, atol=1e-2)
+        _ = results.plot_single_qubit(qubit)
+    pauli_errors = results.pauli_error()
+    assert len(pauli_errors) == len(qubits)
+
+
 def test_two_qubit_randomized_benchmarking() -> None:
     # Check that the ground state population at the end of the Clifford
     # sequences is always unity.

cirq/experiments/random_quantum_circuit_generation.py

@@ -17,7 +17,8 @@ from __future__ import annotations
 
 import dataclasses
 import itertools
-from typing import Any, Callable, Container, Iterable, Iterator, Sequence, TYPE_CHECKING
+from collections.abc import Callable, Container, Iterable, Iterator, Sequence
+from typing import Any, TYPE_CHECKING
 
 import numpy as np
 

cirq/experiments/random_quantum_circuit_generation_test.py

@@ -15,7 +15,8 @@
 from __future__ import annotations
 
 import itertools
-from typing import Callable, cast, Iterable, Sequence
+from collections.abc import Callable, Iterable, Sequence
+from typing import cast
 
 import networkx as nx
 import numpy as np

cirq/experiments/readout_confusion_matrix.py

@@ -17,7 +17,8 @@
 from __future__ import annotations
 
 import time
-from typing import Any, cast, Sequence, TYPE_CHECKING
+from collections.abc import Sequence
+from typing import Any, cast, TYPE_CHECKING
 
 import numpy as np
 import scipy.optimize

cirq/experiments/readout_confusion_matrix_test.py

@@ -14,7 +14,7 @@
 
 from __future__ import annotations
 
-from typing import Sequence
+from collections.abc import Sequence
 
 import numpy as np
 import pytest

cirq/experiments/single_qubit_readout_calibration.py

@@ -18,7 +18,8 @@ from __future__ import annotations
 
 import dataclasses
 import time
-from typing import Any, cast, Iterable, TYPE_CHECKING
+from collections.abc import Iterable
+from typing import Any, cast, TYPE_CHECKING
 
 import matplotlib.pyplot as plt
 import numpy as np

cirq/experiments/single_qubit_readout_calibration_test.py

@@ -14,7 +14,7 @@
 
 from __future__ import annotations
 
-from typing import Sequence
+from collections.abc import Sequence
 
 import numpy as np
 import pytest

cirq/experiments/t1_decay_experiment.py

@@ -15,7 +15,8 @@
 from __future__ import annotations
 
 import warnings
-from typing import Any, cast, Sequence, TYPE_CHECKING
+from collections.abc import Sequence
+from typing import Any, cast, TYPE_CHECKING
 
 import numpy as np
 import pandas as pd

cirq/experiments/two_qubit_xeb.py

@@ -18,9 +18,10 @@ from __future__ import annotations
 
 import functools
 import itertools
+from collections.abc import Mapping, Sequence
 from dataclasses import dataclass
 from types import MappingProxyType
-from typing import Any, cast, Mapping, Sequence, TYPE_CHECKING
+from typing import Any, cast, TYPE_CHECKING
 
 import networkx as nx
 import numpy as np

cirq/experiments/two_qubit_xeb_test.py

@@ -18,7 +18,7 @@ from __future__ import annotations
 
 import io
 import itertools
-from typing import Sequence
+from collections.abc import Sequence
 
 import matplotlib.pyplot as plt
 import networkx as nx

cirq/experiments/xeb_fitting.py

@@ -18,7 +18,8 @@ from __future__ import annotations
 
 import dataclasses
 from abc import ABC, abstractmethod
-from typing import Iterable, Sequence, TYPE_CHECKING
+from collections.abc import Iterable, Sequence
+from typing import TYPE_CHECKING
 
 import numpy as np
 import pandas as pd

cirq/experiments/xeb_fitting_test.py

@@ -16,7 +16,7 @@ from __future__ import annotations
 
 import itertools
 import multiprocessing
-from typing import Iterable, Iterator, Sequence
+from collections.abc import Iterable, Iterator, Sequence
 
 import networkx as nx
 import numpy as np

cirq/experiments/xeb_sampling.py

@@ -19,8 +19,10 @@ from __future__ import annotations
 import os
 import time
 import uuid
+from collections.abc import Callable, Sequence
+from contextlib import AbstractContextManager
 from dataclasses import dataclass
-from typing import Any, Callable, ContextManager, Sequence, TYPE_CHECKING
+from typing import Any, TYPE_CHECKING
 
 import numpy as np
 import pandas as pd
@@ -257,7 +259,7 @@ def _execute_sample_2q_xeb_tasks_in_batches(
     combinations_by_layer: list[CircuitLibraryCombination],
     repetitions: int,
     batch_size: int,
-    progress_bar: Callable[..., ContextManager],
+    progress_bar: Callable[..., AbstractContextManager],
     dataset_directory: str | None = None,
 ) -> list[dict[str, Any]]:
     """Helper function used in `sample_2q_xeb_circuits` to batch and execute sampling tasks."""
@@ -287,7 +289,7 @@ def sample_2q_xeb_circuits(
     *,
     repetitions: int = 10_000,
     batch_size: int = 9,
-    progress_bar: Callable[..., ContextManager] | None = tqdm.tqdm,
+    progress_bar: Callable[..., AbstractContextManager] | None = tqdm.tqdm,
     combinations_by_layer: list[CircuitLibraryCombination] | None = None,
     shuffle: cirq.RANDOM_STATE_OR_SEED_LIKE | None = None,
     dataset_directory: str | None = None,

cirq/experiments/xeb_sampling_test.py

@@ -16,7 +16,7 @@ from __future__ import annotations
 
 import glob
 import itertools
-from typing import Iterable
+from collections.abc import Iterable
 
 import networkx as nx
 import numpy as np

cirq/experiments/xeb_simulation.py

@@ -16,8 +16,9 @@
 
 from __future__ import annotations
 
+from collections.abc import Sequence
 from dataclasses import dataclass
-from typing import Any, Sequence, TYPE_CHECKING
+from typing import Any, TYPE_CHECKING
 
 import numpy as np
 import pandas as pd

cirq/experiments/xeb_simulation_test.py

@@ -15,7 +15,8 @@
 from __future__ import annotations
 
 import multiprocessing
-from typing import Any, Iterator, Sequence
+from collections.abc import Iterator, Sequence
+from typing import Any
 
 import numpy as np
 import pandas as pd

cirq/experiments/z_phase_calibration.py

@@ -18,7 +18,8 @@ from __future__ import annotations
 
 import multiprocessing
 import multiprocessing.pool
-from typing import Any, Sequence, TYPE_CHECKING
+from collections.abc import Sequence
+from typing import Any, TYPE_CHECKING
 
 import matplotlib.pyplot as plt
 import numpy as np