Add get_check_qubits helper (#37)

* first pass

* Clean up docstrings in layout module

* dont filter 3rd party warnings

* Add a reno

* Clean up docstring

* Fix commentary in guide

Author: caleb-johnson

docs/guides/low_overhead_error_detection_using_spacetime_codes.ipynb

@@ -16,30 +16,64 @@
 
 from collections.abc import Sequence
 
+from qiskit.providers import BackendV2
 from qiskit.transpiler import CouplingMap
 
 
+def get_check_qubits(
+    backend: BackendV2 | CouplingMap, layout: Sequence[int]
+) -> tuple[list[int], list[int]]:
+    """Pair qubits in ``layout`` with neighboring ancillas.
+
+    Generate equal-length lists of target and ancilla qubits, such that
+    target qubit ``i`` is adjacent to ancilla qubit ``i``in the coupling map.
+    Target and ancilla qubits may appear at most one time in their
+    respective lists.
+
+    Args:
+        backend: The target backend, or a :class:`~qiskit.transpiler.CouplingMap`
+            describing its connectivity.
+        layout: A list of physical qubit indices.
+
+    Returns:
+        A length-2 tuple of lists, ``(target_qubits, ancilla_qubits)``. ``target_qubits[i]``
+        pairs with ``ancilla_qubits[i]``.
+    """
+    coupling_map = getattr(backend, "coupling_map", backend)
+    ancilla_to_payload = get_low_overhead_ancillas(coupling_map, layout)
+
+    # Give each ancilla its first not-yet-claimed neighbor, so every target and
+    # ancilla is used at most once. Sorting makes the choice deterministic.
+    matched: dict[int, int] = {}  # target qubit -> ancilla
+    for ancilla in sorted(ancilla_to_payload):
+        for target in sorted(ancilla_to_payload[ancilla]):
+            if target not in matched:
+                matched[target] = ancilla
+                break
+
+    targets = sorted(matched)
+    return [int(t) for t in targets], [int(matched[t]) for t in targets]
+
+
 def get_low_overhead_ancillas(
     coupling_map: CouplingMap, layout: Sequence[int]
 ) -> dict[int, list[int]]:
-    """Find ancilla qubits adjacent to the layout qubits in the coupling graph.
-
-    This function identifies physical qubits that are not in the layout but are
-    connected to one or more layout qubits via the coupling map.
+    """Create a mapping from ancillas to ``layout`` qubits to which they are adjacent.
 
     Args:
-        coupling_map: A qubit connectivity graph
-        layout: Physical qubit indices for which to find adjacent ancillas
+        coupling_map: A qubit connectivity graph.
+        layout: Physical qubit indices occupied by the payload circuit.
 
     Returns:
-        A dictionary mapping ancilla qubit indices to lists of layout qubit indices
-        to which it is adjacent.
+        A mapping from ancilla indices to the list of ``layout`` qubits to which it is
+        adjacent. An ancilla bordering several layout qubits maps to all of them, and
+        a layout qubit bordering several ancillas appears in each of their lists.
     """
     layout_set = set(layout)
     ancilla_targets: dict[int, list[int]] = {}
 
     for qubit in layout:
-        for neighbor in coupling_map.neighbors(qubit):
+        for neighbor in sorted(coupling_map.neighbors(qubit)):
             if neighbor not in layout_set:
                 if neighbor not in ancilla_targets:
                     ancilla_targets[neighbor] = []

python/qiskit_paulice/layout.py

@@ -0,0 +1,4 @@
+---
+features:
+  - |
+    Added new :func:`qiskit_paulice.layout.get_check_qubits` function, which provides a straightforward way to find target/ancilla qubit pairs, which can be used to implement spacetime Pauli checks.

releasenotes/notes/get-check-q-e1d6b058f89fc12e.yaml

@@ -17,7 +17,7 @@
 import unittest
 
 from qiskit.transpiler import CouplingMap
-from qiskit_paulice.layout import get_low_overhead_ancillas
+from qiskit_paulice.layout import get_check_qubits, get_low_overhead_ancillas
 
 
 class TestGetLowOverheadAncillas(unittest.TestCase):
@@ -58,3 +58,69 @@ def test_ancilla_shared_by_multiple_layout_qubits(self):
         self.assertEqual(list(result.keys()), [1])
         # Order tracks the layout iteration order.
         self.assertEqual(result[1], [0, 2])
+
+    def test_key_order_is_deterministic(self):
+        """Keys are sorted, so `neighbors` iteration instability can't leak out."""
+        # Edges added so a single layout qubit's neighbors are not in index order.
+        cm = CouplingMap([(5, 2), (5, 8), (5, 1), (1, 5), (2, 5), (8, 5)])
+        self.assertEqual(list(get_low_overhead_ancillas(cm, [5])), [1, 2, 8])
+
+
+class _FakeBackend:
+    """Minimal stand-in exposing the ``coupling_map`` attribute the wrapper reads."""
+
+    def __init__(self, coupling_map: CouplingMap):
+        self.coupling_map = coupling_map
+
+
+class TestGetCheckQubits(unittest.TestCase):
+    """Tests covering :func:`get_check_qubits`."""
+
+    def test_line_pairs_each_target_with_its_ancilla(self):
+        # Line 0-1-2-3-4, payload on the interior: 0 checks 1, 4 checks 3.
+        targets, ancillas = get_check_qubits(CouplingMap.from_line(5), [1, 2, 3])
+        self.assertEqual(targets, [1, 3])
+        self.assertEqual(ancillas, [0, 4])
+
+    def test_accepts_backend_like_object(self):
+        # Anything exposing `.coupling_map` works the same as passing the map.
+        cm = CouplingMap.from_line(5)
+        self.assertEqual(
+            get_check_qubits(_FakeBackend(cm), [1, 2, 3]),
+            get_check_qubits(cm, [1, 2, 3]),
+        )
+
+    def test_each_ancilla_takes_a_distinct_target(self):
+        # Ancilla 0 neighbors only target 1; ancilla 3 neighbors targets 1 and 2.
+        # Walking ancillas in order, 0 claims 1 and 3 falls through to 2, so both
+        # targets get a check rather than competing for target 1.
+        cm = CouplingMap([(0, 1), (1, 0), (3, 1), (1, 3), (3, 2), (2, 3)])
+        targets, ancillas = get_check_qubits(cm, [1, 2])
+        self.assertEqual(targets, [1, 2])
+        self.assertEqual(ancillas, [0, 3])
+
+    def test_pairs_are_valid_and_unique(self):
+        # Star centered on 2 plus a tail: every pair must use a distinct ancilla
+        # outside the layout that genuinely neighbors its target.
+        cm = CouplingMap.from_line(6)
+        layout = [1, 2, 3, 4]
+        targets, ancillas = get_check_qubits(cm, layout)
+        self.assertEqual(len(targets), len(ancillas))
+        self.assertEqual(len(set(targets)), len(targets))
+        self.assertEqual(len(set(ancillas)), len(ancillas))
+        for t, a in zip(targets, ancillas, strict=True):
+            self.assertIn(t, layout)
+            self.assertNotIn(a, layout)
+            self.assertIn(a, list(cm.neighbors(t)))
+
+    def test_ancilla_with_no_free_target_is_dropped(self):
+        # Ancillas 0 and 2 both border only target 1; the first claims it and the
+        # second is left unmatched, so only one pair comes back.
+        cm = CouplingMap([(0, 1), (1, 0), (2, 1), (1, 2)])
+        self.assertEqual(get_check_qubits(cm, [1]), ([1], [0]))
+
+    def test_empty_layout_returns_empty_lists(self):
+        self.assertEqual(get_check_qubits(CouplingMap.from_line(5), []), ([], []))
+
+    def test_full_layout_returns_empty_lists(self):
+        self.assertEqual(get_check_qubits(CouplingMap.from_line(5), list(range(5))), ([], []))