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

cirq/transformers/analytical_decompositions/two_qubit_to_sqrt_iswap_test.py

@@ -15,6 +15,7 @@
 from __future__ import annotations
 
 import itertools
+from collections.abc import Iterator
 
 import numpy as np
 import pytest
@@ -23,11 +24,11 @@ import sympy
 import cirq
 
 
-def random_unitary(seed):
+def random_unitary(seed: cirq.RANDOM_STATE_OR_SEED_LIKE) -> np.ndarray:
     return cirq.testing.random_unitary(4, random_state=seed)
 
 
-def random_locals(x, y, z, seed=None):
+def random_locals(x: float, y: float, z: float, seed=None) -> np.ndarray:
     rng = np.random.RandomState(seed)
     a0 = cirq.testing.random_unitary(2, random_state=rng)
     a1 = cirq.testing.random_unitary(2, random_state=rng)
@@ -42,15 +43,14 @@ def random_locals(x, y, z, seed=None):
     )
 
 
-def perturbations_unitary(u, amount=1e-10):
+def perturbations_unitary(u: np.ndarray, amount=1e-10) -> Iterator[np.ndarray]:
     """Returns several unitaries in the neighborhood of u to test for numerical
     corner cases near critical values."""
     kak = cirq.kak_decomposition(u)
     yield u
     for i in range(3):
         for neg in (-1, 1):
-            perturb_xyz = list(kak.interaction_coefficients)
-            perturb_xyz[i] += neg * amount
+            perturb_xyz = tuple(c + neg * amount for c in kak.interaction_coefficients)
             yield cirq.unitary(
                 cirq.KakDecomposition(
                     global_phase=kak.global_phase,
@@ -61,11 +61,11 @@ def perturbations_unitary(u, amount=1e-10):
             )
 
 
-def perturbations_gate(gate, amount=1e-10):
+def perturbations_gate(gate: cirq.SupportsUnitary, amount=1e-10) -> Iterator[np.ndarray]:
     return perturbations_unitary(cirq.unitary(gate), amount)
 
 
-def perturbations_weyl(x, y, z, amount=1e-10):
+def perturbations_weyl(x: float, y: float, z: float, amount: float = 1e-10) -> Iterator[np.ndarray]:
     return perturbations_gate(cirq.KakDecomposition(interaction_coefficients=(x, y, z)), amount)
 
 
@@ -211,7 +211,7 @@ def assert_valid_decomp(
     atol=1e-6,
     rtol=0,
     qubit_order=cirq.LineQubit.range(2),
-):
+) -> None:
     # Check expected gates
     for op in operations:
         if len(op.qubits) == 0 and isinstance(op.gate, cirq.GlobalPhaseGate):
@@ -242,7 +242,7 @@ def assert_valid_decomp(
         )
 
 
-def assert_specific_sqrt_iswap_count(operations, count):
+def assert_specific_sqrt_iswap_count(operations, count) -> None:
     actual = sum(len(op.qubits) == 2 for op in operations)
     assert actual == count, f'Incorrect sqrt-iSWAP count.  Expected {count} but got {actual}.'
 
@@ -255,7 +255,7 @@ def assert_specific_sqrt_iswap_count(operations, count):
         cirq.CZPowGate(exponent=sympy.Symbol('t')),
     ],
 )
-def test_two_qubit_gates_with_symbols(gate: cirq.Gate):
+def test_two_qubit_gates_with_symbols(gate: cirq.Gate) -> None:
     op = gate(*cirq.LineQubit.range(2))
     c_new_sqrt_iswap = cirq.Circuit(
         cirq.parameterized_2q_op_to_sqrt_iswap_operations(op)  # type: ignore
@@ -279,12 +279,14 @@ def test_two_qubit_gates_with_symbols(gate: cirq.Gate):
         )
 
 
-def test_fsim_gate_with_symbols():
+def test_fsim_gate_with_symbols() -> None:
     theta, phi = sympy.symbols(['theta', 'phi'])
     op = cirq.FSimGate(theta=theta, phi=phi).on(*cirq.LineQubit.range(2))
-    c_new_sqrt_iswap = cirq.Circuit(cirq.parameterized_2q_op_to_sqrt_iswap_operations(op))
+    c_new_sqrt_iswap = cirq.Circuit(
+        cirq.parameterized_2q_op_to_sqrt_iswap_operations(op)  # type: ignore[arg-type]
+    )
     c_new_sqrt_iswap_inv = cirq.Circuit(
-        cirq.parameterized_2q_op_to_sqrt_iswap_operations(op, use_sqrt_iswap_inv=True)
+        cirq.parameterized_2q_op_to_sqrt_iswap_operations(op, use_sqrt_iswap_inv=True)  # type: ignore[arg-type]
     )
     for theta_val in np.linspace(0, 2 * np.pi, 4):
         for phi_val in np.linspace(0, 2 * np.pi, 6):
@@ -307,7 +309,7 @@ def test_fsim_gate_with_symbols():
 
 
 @pytest.mark.parametrize('cnt', [-1, 4, 10])
-def test_invalid_required_sqrt_iswap_count(cnt):
+def test_invalid_required_sqrt_iswap_count(cnt) -> None:
     u = TWO_SQRT_ISWAP_UNITARIES[0]
     q0, q1 = cirq.LineQubit.range(2)
     with pytest.raises(ValueError, match='required_sqrt_iswap_count'):
@@ -315,7 +317,7 @@ def test_invalid_required_sqrt_iswap_count(cnt):
 
 
 @pytest.mark.parametrize('u', ZERO_UNITARIES)
-def test_decomp0(u):
+def test_decomp0(u) -> None:
     # Decompose unitaries into zero sqrt-iSWAP gates
     q0, q1 = cirq.LineQubit.range(2)
     ops = cirq.two_qubit_matrix_to_sqrt_iswap_operations(q0, q1, u, required_sqrt_iswap_count=0)
@@ -326,7 +328,7 @@ def test_decomp0(u):
 @pytest.mark.parametrize(
     'u', ONE_SQRT_ISWAP_UNITARIES + TWO_SQRT_ISWAP_UNITARIES + THREE_SQRT_ISWAP_UNITARIES
 )
-def test_decomp0_invalid(u):
+def test_decomp0_invalid(u) -> None:
     # Attempt to decompose other unitaries into zero SQRT_ISWAP gates
     q0, q1 = cirq.LineQubit.range(2)
     with pytest.raises(ValueError, match='cannot be decomposed into exactly 0 sqrt-iSWAP gates'):
@@ -334,7 +336,7 @@ def test_decomp0_invalid(u):
 
 
 @pytest.mark.parametrize('u', ONE_SQRT_ISWAP_UNITARIES)
-def test_decomp1(u):
+def test_decomp1(u) -> None:
     q0, q1 = cirq.LineQubit.range(2)
     ops = cirq.two_qubit_matrix_to_sqrt_iswap_operations(q0, q1, u, required_sqrt_iswap_count=1)
     assert_valid_decomp(u, ops)
@@ -344,14 +346,14 @@ def test_decomp1(u):
 @pytest.mark.parametrize(
     'u', ZERO_UNITARIES + TWO_SQRT_ISWAP_UNITARIES + THREE_SQRT_ISWAP_UNITARIES
 )
-def test_decomp1_invalid(u):
+def test_decomp1_invalid(u) -> None:
     q0, q1 = cirq.LineQubit.range(2)
     with pytest.raises(ValueError, match='cannot be decomposed into exactly 1 sqrt-iSWAP gates'):
         cirq.two_qubit_matrix_to_sqrt_iswap_operations(q0, q1, u, required_sqrt_iswap_count=1)
 
 
 @pytest.mark.parametrize('u', ZERO_UNITARIES + ONE_SQRT_ISWAP_UNITARIES + TWO_SQRT_ISWAP_UNITARIES)
-def test_decomp2(u):
+def test_decomp2(u) -> None:
     q0, q1 = cirq.LineQubit.range(2)
     ops = cirq.two_qubit_matrix_to_sqrt_iswap_operations(q0, q1, u, required_sqrt_iswap_count=2)
     assert_valid_decomp(u, ops)
@@ -359,7 +361,7 @@ def test_decomp2(u):
 
 
 @pytest.mark.parametrize('u', THREE_SQRT_ISWAP_UNITARIES)
-def test_decomp2_invalid(u):
+def test_decomp2_invalid(u) -> None:
     q0, q1 = cirq.LineQubit.range(2)
     with pytest.raises(ValueError, match='cannot be decomposed into exactly 2 sqrt-iSWAP gates'):
         cirq.two_qubit_matrix_to_sqrt_iswap_operations(q0, q1, u, required_sqrt_iswap_count=2)
@@ -372,14 +374,14 @@ def test_decomp2_invalid(u):
     + TWO_SQRT_ISWAP_UNITARIES
     + THREE_SQRT_ISWAP_UNITARIES,
 )
-def test_decomp3(u):
+def test_decomp3(u) -> None:
     q0, q1 = cirq.LineQubit.range(2)
     ops = cirq.two_qubit_matrix_to_sqrt_iswap_operations(q0, q1, u, required_sqrt_iswap_count=3)
     assert_valid_decomp(u, ops)
     assert_specific_sqrt_iswap_count(ops, 3)
 
 
-def test_decomp3_invalid():
+def test_decomp3_invalid() -> None:
     # All two-qubit gates can be synthesized with three SQRT_ISWAP gates
     u = cirq.unitary(cirq.X**0.2)  # Pass an invalid size unitary
     q0, q1 = cirq.LineQubit.range(2)
@@ -388,7 +390,7 @@ def test_decomp3_invalid():
 
 
 @pytest.mark.parametrize('u', TWO_SQRT_ISWAP_UNITARIES[:1])
-def test_qubit_order(u):
+def test_qubit_order(u) -> None:
     q0, q1 = cirq.LineQubit.range(2)
     ops = cirq.two_qubit_matrix_to_sqrt_iswap_operations(q1, q0, u, required_sqrt_iswap_count=2)
     assert_valid_decomp(u, ops, qubit_order=(q1, q0))
@@ -396,7 +398,7 @@ def test_qubit_order(u):
 
 
 @pytest.mark.parametrize('u', ZERO_UNITARIES)
-def test_decomp_optimal0(u):
+def test_decomp_optimal0(u) -> None:
     q0, q1 = cirq.LineQubit.range(2)
     ops = cirq.two_qubit_matrix_to_sqrt_iswap_operations(q0, q1, u)
     assert_valid_decomp(u, ops)
@@ -404,7 +406,7 @@ def test_decomp_optimal0(u):
 
 
 @pytest.mark.parametrize('u', ONE_SQRT_ISWAP_UNITARIES)
-def test_decomp_optimal1(u):
+def test_decomp_optimal1(u) -> None:
     q0, q1 = cirq.LineQubit.range(2)
     ops = cirq.two_qubit_matrix_to_sqrt_iswap_operations(q0, q1, u)
     assert_valid_decomp(u, ops)
@@ -412,7 +414,7 @@ def test_decomp_optimal1(u):
 
 
 @pytest.mark.parametrize('u', TWO_SQRT_ISWAP_UNITARIES)
-def test_decomp_optimal2(u):
+def test_decomp_optimal2(u) -> None:
     q0, q1 = cirq.LineQubit.range(2)
     ops = cirq.two_qubit_matrix_to_sqrt_iswap_operations(q0, q1, u)
     assert_valid_decomp(u, ops)
@@ -420,7 +422,7 @@ def test_decomp_optimal2(u):
 
 
 @pytest.mark.parametrize('u', THREE_SQRT_ISWAP_UNITARIES)
-def test_decomp_optimal3(u):
+def test_decomp_optimal3(u) -> None:
     q0, q1 = cirq.LineQubit.range(2)
     ops = cirq.two_qubit_matrix_to_sqrt_iswap_operations(q0, q1, u)
     assert_valid_decomp(u, ops)
@@ -428,7 +430,7 @@ def test_decomp_optimal3(u):
 
 
 @pytest.mark.parametrize('u', ALL_REGION_UNITARIES)
-def test_all_weyl_regions(u):
+def test_all_weyl_regions(u) -> None:
     q0, q1 = cirq.LineQubit.range(2)
     ops = cirq.two_qubit_matrix_to_sqrt_iswap_operations(q0, q1, u, clean_operations=True)
     assert_valid_decomp(u, ops, single_qubit_gate_types=(cirq.PhasedXZGate,))
@@ -445,13 +447,13 @@ def test_all_weyl_regions(u):
         THREE_SQRT_ISWAP_UNITARIES[0],
     ],
 )
-def test_decomp_sqrt_iswap_inv(u):
+def test_decomp_sqrt_iswap_inv(u) -> None:
     q0, q1 = cirq.LineQubit.range(2)
     ops = cirq.two_qubit_matrix_to_sqrt_iswap_operations(q0, q1, u, use_sqrt_iswap_inv=True)
     assert_valid_decomp(u, ops, two_qubit_gate=cirq.SQRT_ISWAP_INV)
 
 
-def test_valid_check_raises():
+def test_valid_check_raises() -> None:
     q0 = cirq.LineQubit(0)
     with pytest.raises(AssertionError, match='Unitaries are completely different'):
         assert_valid_decomp(np.eye(4), [cirq.X(q0)], single_qubit_gate_types=(cirq.XPowGate,))

cirq/transformers/drop_negligible_operations_test.py

@@ -19,13 +19,13 @@ import cirq
 NO_COMPILE_TAG = "no_compile_tag"
 
 
-def test_leaves_big():
+def test_leaves_big() -> None:
     a = cirq.NamedQubit('a')
     circuit = cirq.Circuit(cirq.Moment(cirq.Z(a) ** 0.1))
     cirq.testing.assert_same_circuits(cirq.drop_negligible_operations(circuit, atol=0.001), circuit)
 
 
-def test_clears_small():
+def test_clears_small() -> None:
     a = cirq.NamedQubit('a')
     circuit = cirq.Circuit(cirq.Moment(cirq.Z(a) ** 0.000001))
     cirq.testing.assert_same_circuits(
@@ -33,7 +33,7 @@ def test_clears_small():
     )
 
 
-def test_does_not_clear_small_no_compile():
+def test_does_not_clear_small_no_compile() -> None:
     a = cirq.NamedQubit('a')
     circuit = cirq.Circuit(cirq.Moment((cirq.Z(a) ** 0.000001).with_tags(NO_COMPILE_TAG)))
     cirq.testing.assert_same_circuits(
@@ -44,7 +44,7 @@ def test_does_not_clear_small_no_compile():
     )
 
 
-def test_clears_known_empties_even_at_zero_tolerance():
+def test_clears_known_empties_even_at_zero_tolerance() -> None:
     a, b = cirq.LineQubit.range(2)
     circuit = cirq.Circuit(
         cirq.Z(a) ** 0, cirq.Y(a) ** 0.0000001, cirq.X(a) ** -0.0000001, cirq.CZ(a, b) ** 0
@@ -63,7 +63,7 @@ def test_clears_known_empties_even_at_zero_tolerance():
     )
 
 
-def test_recursively_runs_inside_circuit_ops_deep():
+def test_recursively_runs_inside_circuit_ops_deep() -> None:
     a = cirq.NamedQubit('a')
     small_op = cirq.Z(a) ** 0.000001
     nested_circuit = cirq.FrozenCircuit(
@@ -92,13 +92,13 @@ def test_recursively_runs_inside_circuit_ops_deep():
         ),
         cirq.Moment(),
     )
-    context = cirq.TransformerContext(tags_to_ignore=[NO_COMPILE_TAG], deep=True)
+    context = cirq.TransformerContext(tags_to_ignore=(NO_COMPILE_TAG,), deep=True)
     cirq.testing.assert_same_circuits(
         cirq.drop_negligible_operations(c_orig, context=context, atol=0.001), c_expected
     )
 
 
-def test_ignores_large_ops():
+def test_ignores_large_ops() -> None:
     qnum = 20
     qubits = cirq.LineQubit.range(qnum)
     subcircuit = cirq.FrozenCircuit(cirq.X.on_each(*qubits))

cirq/transformers/dynamical_decoupling.py

@@ -16,11 +16,13 @@
 
 from __future__ import annotations
 
+from enum import Enum
 from functools import reduce
 from itertools import cycle
 from typing import TYPE_CHECKING
 
 import numpy as np
+from attrs import frozen
 
 from cirq import ops, protocols
 from cirq.circuits import Circuit, FrozenCircuit, Moment
@@ -133,10 +135,6 @@ def _calc_busy_moment_range_of_each_qubit(circuit: FrozenCircuit) -> dict[ops.Qi
     return busy_moment_range_by_qubit
 
 
-def _is_insertable_moment(moment: Moment, single_qubit_gate_moments_only: bool) -> bool:
-    return not single_qubit_gate_moments_only or _is_single_qubit_gate_moment(moment)
-
-
 def _merge_single_qubit_ops_to_phxz(
     q: ops.Qid, operations: tuple[ops.Operation, ...]
 ) -> ops.Operation:
@@ -149,34 +147,162 @@ def _merge_single_qubit_ops_to_phxz(
     return gate.on(q)
 
 
-def _calc_pulled_through(moment: Moment, input_pauli_ops: ops.PauliString) -> ops.PauliString:
-    """Calculates the pulled_through such that circuit(input_pauli_ops, moment.clifford_ops) is
-    equivalent to circuit(moment.clifford_ops, pulled_through).
+def _backward_set_stopping_slots(
+    q: ops.Qid,
+    from_mid: int,
+    mergable: dict[ops.Qid, dict[int, bool]],
+    need_to_stop: dict[ops.Qid, dict[int, bool]],
+    gate_types: dict[ops.Qid, dict[int, _CellType]],
+    circuit: FrozenCircuit,
+):
+    """Sets stopping slots for dynamical decoupling insertion.
+
+    This function traverses backward from a given moment `from_mid` for a specific qubit `q`.
+    It identifies moments where a dynamical decoupling sequence needs to be "stopped".
+
+    Args:
+        q: The qubit for which to set stopping slots.
+        from_mid: The moment ID to start the backward traversal from.
+        mergable: A dictionary indicating if a single-qubit Clifford gate at (qubit, moment_id)
+            can be merged with a Pauli gate.
+        need_to_stop: A dictionary to mark moments where a DD sequence must be stopped.
+        gate_types: A dictionary indicating the type of gate at each (qubit, moment_id).
+        circuit: The original frozen circuit.
     """
-    clifford_ops_in_moment: list[ops.Operation] = [
-        op for op in moment.operations if _is_clifford_op(op)
-    ]
-    return input_pauli_ops.after(clifford_ops_in_moment)
+    affected_qubits: set[ops.Qid] = {q}
+    for back_mid in range(from_mid, -1, -1):
+        for back_q in set(affected_qubits):
+            if gate_types[back_q][back_mid] == _CellType.WALL:
+                affected_qubits.remove(back_q)
+                continue
+            if mergable[back_q][back_mid]:
+                need_to_stop[back_q][back_mid] = True
+                affected_qubits.remove(back_q)
+                continue
+            op_at_q = circuit[back_mid].operation_at(back_q) or ops.I(q)
+            affected_qubits.update(op_at_q.qubits)
+        if not affected_qubits:
+            break
+
+
+class _CellType(Enum):
+    UNKNOWN = '?'
+    # Non-insertable gates that cannot be pulled through
+    WALL = 'w'
+    # Clifford gates where Pauli Gates can be pulled through
+    DOOR = 'd'
+    # An empty gate can be used to insert Pauli gates from the dd sequence
+    INSERTABLE = 'i'
+
+
+@frozen
+class _Grid:
+    """A grid representation of the circuit where each gate position is labeled for
+      dynamical decoupling.
+
+    With this representation, a DD sequence can be automatically navigated in a
+    forward-only process. This avoids issues where a partially inserted DD
+    sequence encounters a "wall" and a new moment must be inserted because the
+    remaining DD sequence cannot be absorbed by nearby gates.
+
+    This labeled representation pre-calculates where DD pulses can be inserted
+    and where leftover DD sequences must be merged, avoiding the need for
+    backtracking.
+
+    An example labeled circuit is shown below:
+         |  0  |  1  |  2  |  3  |  4  |
+    -----+-----+-----+-----+-----+-----+
+    q(0) |  d  |  i  | i,s |  d  |  w  |
+    q(1) |  d  |  i  | d,s |  w  |  w  |
+    q(2) |  d  |  d  | d,s |  w  |  w  |
+    where `w`=WALL, `d`=DOOR, `i`=INSERTABLE. `s` represents a stop gate,
+    meaning that any unfinished DD sequences must be merged at this gate.
+    """
+
+    gate_types: dict[ops.Qid, dict[int, _CellType]]
+    need_to_stop: dict[ops.Qid, dict[int, bool]]
+    circuit: FrozenCircuit
+
+    @classmethod
+    def from_circuit(
+        cls, circuit: cirq.FrozenCircuit, single_qubit_gate_moments_only: bool
+    ) -> _Grid:
+        gate_types: dict[ops.Qid, dict[int, _CellType]] = {
+            q: {mid: _CellType.UNKNOWN for mid in range(len(circuit))} for q in circuit.all_qubits()
+        }
+        mergable: dict[ops.Qid, dict[int, bool]] = {
+            q: {mid: False for mid in range(len(circuit))} for q in circuit.all_qubits()
+        }
+        busy_moment_range_by_qubit = _calc_busy_moment_range_of_each_qubit(circuit)
+
+        # Set gate types for each (q, mid)
+        for mid, moment in enumerate(circuit):
+            is_insertable_moment = (
+                not single_qubit_gate_moments_only or _is_single_qubit_gate_moment(moment)
+            )
+            for q in circuit.all_qubits():
+                if mid < busy_moment_range_by_qubit[q][0] or mid > busy_moment_range_by_qubit[q][1]:
+                    gate_types[q][mid] = _CellType.WALL
+                    continue
+                op_at_q = moment.operation_at(q)
+                if op_at_q is None:
+                    if is_insertable_moment:
+                        gate_types[q][mid] = _CellType.INSERTABLE
+                        mergable[q][mid] = True
+                    else:
+                        gate_types[q][mid] = _CellType.DOOR
+                else:
+                    if _is_clifford_op(op_at_q):
+                        gate_types[q][mid] = _CellType.DOOR
+                        mergable[q][mid] = _is_single_qubit_operation(op_at_q)
+                    else:
+                        gate_types[q][mid] = _CellType.WALL
+
+        need_to_stop: dict[ops.Qid, dict[int, bool]] = {
+            q: {mid: False for mid in range(len(circuit))} for q in circuit.all_qubits()
+        }
+        # Reversely find the last mergeable gate of each qubit, set them as need_to_stop.
+        for q in circuit.all_qubits():
+            _backward_set_stopping_slots(
+                q, len(circuit) - 1, mergable, need_to_stop, gate_types, circuit
+            )
+        # Reversely check for each wall gate, mark the closest mergeable gate as need_to_stop.
+        for mid in range(len(circuit)):
+            for q in circuit.all_qubits():
+                if gate_types[q][mid] == _CellType.WALL:
+                    _backward_set_stopping_slots(
+                        q, mid - 1, mergable, need_to_stop, gate_types, circuit
+                    )
+        return cls(circuit=circuit, gate_types=gate_types, need_to_stop=need_to_stop)
 
+    def __str__(self) -> str:
+        if not self.gate_types:
+            return "Grid(empty)"
 
-def _get_stop_qubits(moment: Moment) -> set[ops.Qid]:
-    stop_pulling_through_qubits: set[ops.Qid] = set()
-    for op in moment:
-        if (not _is_clifford_op(op) and not _is_single_qubit_operation(op)) or not has_unitary(
-            op
-        ):  # multi-qubit clifford op or non-mergable op.
-            stop_pulling_through_qubits.update(op.qubits)
-    return stop_pulling_through_qubits
+        qubits = sorted(list(self.gate_types.keys()))
+        num_moments = len(self.gate_types[qubits[0]])
 
+        max_qubit_len = max(len(str(q)) for q in qubits) if qubits else 0
 
-def _need_merge_pulled_through(op_at_q: ops.Operation, is_at_last_busy_moment: bool) -> bool:
-    """With a pulling through pauli gate before op_at_q, need to merge with the
-    pauli in the conditions below."""
-    # The op must be mergable and single-qubit
-    if not (_is_single_qubit_operation(op_at_q) and has_unitary(op_at_q)):
-        return False
-    # Either non-Clifford or at the last busy moment
-    return is_at_last_busy_moment or not _is_clifford_op(op_at_q)
+        header = f"{'':>{max_qubit_len}} |"
+        for i in range(num_moments):
+            header += f" {i:^3} |"
+
+        separator = f"{'-' * max_qubit_len}-+"
+        separator += '-----+' * num_moments
+
+        lines = ["Grid Repr:", header, separator]
+
+        for q in qubits:
+            row_str = f"{str(q):>{max_qubit_len}} |"
+            for mid in range(num_moments):
+                gate_type = self.gate_types[q][mid].value
+                stop = self.need_to_stop[q][mid]
+                cell = f"{gate_type},s" if stop else f" {gate_type} "
+                row_str += f" {cell} |"
+            lines.append(row_str)
+
+        return "\n".join(lines)
 
 
 @transformer_api.transformer
@@ -188,7 +314,7 @@ def add_dynamical_decoupling(
     single_qubit_gate_moments_only: bool = True,
 ) -> cirq.Circuit:
     """Adds dynamical decoupling gate operations to a given circuit.
-    This transformer might add new moments and thus change the structure of the original circuit.
+    This transformer preserves the structure of the original circuit.
 
     Args:
           circuit: Input circuit to transform.
@@ -202,11 +328,18 @@ def add_dynamical_decoupling(
     Returns:
           A copy of the input circuit with dynamical decoupling operations.
     """
-    base_dd_sequence, pauli_map = _parse_dd_sequence(schema)
+
+    if context is not None and context.deep:
+        raise ValueError("Deep transformation is not supported.")
+
     orig_circuit = circuit.freeze()
 
-    busy_moment_range_by_qubit = _calc_busy_moment_range_of_each_qubit(orig_circuit)
+    grid = _Grid.from_circuit(orig_circuit, single_qubit_gate_moments_only)
+
+    if context is not None and context.logger is not None:
+        context.logger.log("Preprocessed input circuit grid repr:\n%s", str(grid))
 
+    base_dd_sequence, pauli_map = _parse_dd_sequence(schema)
     # Stores all the moments of the output circuit chronologically.
     transformed_moments: list[Moment] = []
     # A PauliString stores the result of 'pulling' Pauli gates past each operations
@@ -215,90 +348,30 @@ def add_dynamical_decoupling(
     # Iterator of gate to be used in dd sequence for each qubit.
     dd_iter_by_qubits = {q: cycle(base_dd_sequence) for q in circuit.all_qubits()}
 
-    def _update_pulled_through(q: ops.Qid, insert_gate: ops.Gate) -> ops.Operation:
-        nonlocal pulled_through, pauli_map
-        pulled_through *= pauli_map[insert_gate].on(q)
-        return insert_gate.on(q)
-
-    # Insert and pull remaining Pauli ops through the whole circuit.
-    # General ideas are
-    #   * Pull through Clifford gates.
-    #   * Stop at multi-qubit non-Clifford ops (and other non-mergable ops).
-    #   * Merge to single-qubit non-Clifford ops.
-    #   * Insert a new moment if necessary.
-    # After pulling through pulled_through at `moment`, we expect a transformation of
-    #  (pulled_through, moment) -> (updated_moment, updated_pulled_through) or
-    #  (pulled_through, moment) -> (new_moment, updated_moment, updated_pulled_through)
-    # Moments structure changes are split into 3 steps:
-    #   1, (..., last_moment, pulled_through1, moment, ...)
-    #        -> (..., last_moment, new_moment or None, pulled_through2, moment, ...)
-    #   2, (..., pulled_through2, moment, ...)  -> (..., pulled_through3, updated_moment, ...)
-    #   3, (..., pulled_through3, updated_moment, ...)
-    #        -> (..., updated_moment, pulled_through4, ...)
     for moment_id, moment in enumerate(orig_circuit.moments):
-        # Step 1, insert new_moment if necessary.
-        # In detail: stop pulling through for multi-qubit non-Clifford ops or gates without
-        # unitary representation (e.g., measure gates). If there are remaining pulled through ops,
-        # insert into a new moment before current moment.
-        stop_pulling_through_qubits: set[ops.Qid] = _get_stop_qubits(moment)
-        new_moment_ops: list[ops.Operation] = []
-        for q in stop_pulling_through_qubits:
-            # Insert the remaining pulled_through
-            remaining_pulled_through_gate = pulled_through.get(q)
-            if remaining_pulled_through_gate is not None:
-                new_moment_ops.append(_update_pulled_through(q, remaining_pulled_through_gate))
-            # Reset dd sequence
-            dd_iter_by_qubits[q] = cycle(base_dd_sequence)
-        # Need to insert a new moment before current moment
-        if new_moment_ops:
-            # Fill insertable idle moments in the new moment using dd sequence
-            for q in orig_circuit.all_qubits() - stop_pulling_through_qubits:
-                if busy_moment_range_by_qubit[q][0] < moment_id <= busy_moment_range_by_qubit[q][1]:
-                    new_moment_ops.append(_update_pulled_through(q, next(dd_iter_by_qubits[q])))
-            transformed_moments.append(Moment(new_moment_ops))
-
-        # Step 2, calc updated_moment with insertions / merges.
         updated_moment_ops: set[cirq.Operation] = set()
         for q in orig_circuit.all_qubits():
-            op_at_q = moment.operation_at(q)
-            remaining_pulled_through_gate = pulled_through.get(q)
-            updated_op = op_at_q
-            if op_at_q is None:  # insert into idle op
-                if not _is_insertable_moment(moment, single_qubit_gate_moments_only):
-                    continue
-                if (
-                    busy_moment_range_by_qubit[q][0] < moment_id < busy_moment_range_by_qubit[q][1]
-                ):  # insert next pauli gate in the dd sequence
-                    updated_op = _update_pulled_through(q, next(dd_iter_by_qubits[q]))
-                elif (  # insert the remaining pulled through if beyond the ending busy moment
-                    moment_id > busy_moment_range_by_qubit[q][1]
-                    and remaining_pulled_through_gate is not None
-                ):
-                    updated_op = _update_pulled_through(q, remaining_pulled_through_gate)
-            elif (
-                remaining_pulled_through_gate is not None
-            ):  # merge pulled-through of q to op_at_q if needed
-                if _need_merge_pulled_through(
-                    op_at_q, moment_id == busy_moment_range_by_qubit[q][1]
-                ):
-                    remaining_op = _update_pulled_through(q, remaining_pulled_through_gate)
-                    updated_op = _merge_single_qubit_ops_to_phxz(q, (remaining_op, op_at_q))
-            if updated_op is not None:
-                updated_moment_ops.add(updated_op)
-
-        if updated_moment_ops:
-            updated_moment = Moment(updated_moment_ops)
-            transformed_moments.append(updated_moment)
-
-            # Step 3, update pulled through.
-            # In detail: pulling current `pulled_through` through updated_moment.
-            pulled_through = _calc_pulled_through(updated_moment, pulled_through)
-
-    # Insert a new moment if there are remaining pulled-through operations.
-    ending_moment_ops = []
-    for affected_q, combined_op_in_pauli in pulled_through.items():
-        ending_moment_ops.append(combined_op_in_pauli.on(affected_q))
-    if ending_moment_ops:
-        transformed_moments.append(Moment(ending_moment_ops))
+            new_op_at_q = moment.operation_at(q)
+            if grid.gate_types[q][moment_id] == _CellType.INSERTABLE:
+                new_gate = next(dd_iter_by_qubits[q])
+                new_op_at_q = new_gate.on(q)
+                pulled_through *= pauli_map[new_gate].on(q)
+            if grid.need_to_stop[q][moment_id]:
+                to_be_merged = pulled_through.get(q)
+                if to_be_merged is not None:
+                    new_op_at_q = _merge_single_qubit_ops_to_phxz(
+                        q, (to_be_merged.on(q), new_op_at_q or ops.I(q))
+                    )
+                    pulled_through *= to_be_merged.on(q)
+            if new_op_at_q is not None:
+                updated_moment_ops.add(new_op_at_q)
+
+        updated_moment = Moment(updated_moment_ops)
+        clifford_ops = [op for op in updated_moment if _is_clifford_op(op)]
+        pulled_through = pulled_through.after(clifford_ops)
+        transformed_moments.append(updated_moment)
+
+    if len(pulled_through) > 0:
+        raise RuntimeError("Expect empty remaining Paulis after the dd insertion.")
 
     return Circuit.from_moments(*transformed_moments)