Observables

requirements-dev.txt

@@ -6,4 +6,4 @@ myst-parser
 sphinx-rtd-theme
 pytest
 mypy
-pytest-cov
+pytest-cov

src/tqec/__init__.py

@@ -14,6 +14,7 @@
 from .enums import (
     CornerPositionEnum,
     PlaquetteOrientation,
+    TemplateOrientation,
     TemplateRelativePositionEnum,
 )
 from .exceptions import TQECException

src/tqec/circuit/circuit_test.py

@@ -21,7 +21,7 @@ def one_by_one_template() -> Template:
 
 def test_generate_initialisation_circuit_list(
     initialisation_plaquette: Plaquette, one_by_one_template
-):
+) -> None:
     circuit = generate_circuit(one_by_one_template, [initialisation_plaquette])
     assert circuit == cirq.Circuit(
         cirq.R(q.to_grid_qubit()) for q in initialisation_plaquette.qubits

src/tqec/circuit/observable_qubits.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+from typing import Mapping, Sequence
+
+import cirq
+
+from tqec.enums import TemplateOrientation
+from tqec.exceptions import TQECException
+from tqec.plaquette.plaquette import Plaquette
+from tqec.plaquette.qubit import PlaquetteQubit
+from tqec.templates.base import Template
+
+
+def observable_qubits_from_template(
+    template: Template,
+    plaquettes: Sequence[Plaquette] | Mapping[int, Plaquette],
+    orientation: TemplateOrientation = TemplateOrientation.HORIZONTAL,
+) -> Sequence[tuple[cirq.GridQubit, int]]:
+    """Return the default observable qubits for the given template and its plaquettes.
+
+    Args:
+        template: The template to get the default observable qubits from.
+        plaquettes: The plaquettes to use to get the acurate positions of the observable qubits.
+        orientation: Whether to get the observable qubits from
+            the horizontal or vertical midline. Defaults to horizontal.
+
+    Raises:
+        TQECException: If the number of plaquettes does not match the expected number.
+        TQECException: If the plaquettes are provided as a dictionary and 0 is in the keys.
+        TQECException: If the template does not have a definable midline.
+
+    Returns:
+        The sequence of qubits and offsets for the observable qubits.
+    """
+    if len(plaquettes) != template.expected_plaquettes_number:
+        raise TQECException(
+            f"{len(plaquettes)} plaquettes have been provided, but "
+            f"{template.expected_plaquettes_number} were expected."
+        )
+    if isinstance(plaquettes, Mapping) and 0 in plaquettes:
+        raise TQECException(
+            "If using a dictionary, the input plaquettes parameter should not "
+            f"contain the entry 0. Found a value ({plaquettes[0]}) at entry 0."
+        )
+
+    if isinstance(plaquettes, list):
+        plaquettes = {i + 1: plaquette for i, plaquette in enumerate(plaquettes)}
+
+    _indices = list(range(1, len(plaquettes) + 1))
+    template_plaquettes = template.instantiate(_indices)
+    increments = template.get_increments()
+
+    try:
+        midline_indices = template.get_midline_plaquettes(orientation)
+    except TQECException as e:
+        raise TQECException(
+            "The template does not have a midline. "
+            "The observable qubits cannot be defined."
+        ) from e
+
+    observable_qubits = []
+    for row_index, column_index in midline_indices:
+        plaquette_index = template_plaquettes[row_index][column_index]
+        if plaquette_index == 0:
+            continue
+        plaquette = plaquettes[plaquette_index]
+        # GridQubits are indexed as (row, col), so (y, x)
+        offset = (
+            row_index * increments.y + plaquette.origin.y,
+            column_index * increments.x + plaquette.origin.x,
+        )
+        observable_qubits += [
+            (qubit.to_grid_qubit() + offset, 0)
+            for qubit in plaquette.qubits.get_edge_qubits(orientation)
+        ]
+    return sorted(set(observable_qubits))

src/tqec/circuit/observable_qubits_test.py

@@ -0,0 +1,36 @@
+import cirq
+import pytest
+
+from tqec.circuit.observable_qubits import observable_qubits_from_template
+from tqec.plaquette.library import xxxx_memory_plaquette, zzzz_memory_plaquette
+from tqec.plaquette.plaquette import Plaquette
+from tqec.templates import RawRectangleTemplate
+
+
+@pytest.fixture
+def plaquettes() -> list[Plaquette]:
+    return [
+        xxxx_memory_plaquette([1, 2, 3, 4, 5, 6, 7, 8]),
+        zzzz_memory_plaquette([1, 3, 4, 5, 6, 8]),
+    ]
+
+
+def test_raw_rectangle_default_obserevable_qubits(plaquettes: list[Plaquette]):
+    template = RawRectangleTemplate(
+        [
+            [0, 1, 0, 1],
+            [1, 0, 1, 0],
+            [0, 1, 0, 1],
+            [1, 0, 1, 0],
+        ]
+    )
+
+    obs = observable_qubits_from_template(template, plaquettes)
+    result = [
+        (cirq.GridQubit(3, -1), 0),
+        (cirq.GridQubit(3, 1), 0),
+        (cirq.GridQubit(3, 3), 0),
+        (cirq.GridQubit(3, 5), 0),
+        (cirq.GridQubit(3, 7), 0),
+    ]
+    assert sorted(obs, key=lambda t: t[0].col) == result

src/tqec/circuit/operations/operation.py

@@ -7,6 +7,7 @@
 
 from tqec.exceptions import TQECException
 
+
 STIM_TAG = "STIM_OPERATION"
 
 
@@ -304,9 +305,11 @@ def make_detector(
         A :class:`Detector` operation with the `cirq.VirtualTag` tag.
     """
     relative_measurements_data = [
-        RelativeMeasurementData(*rm)
-        if not isinstance(rm, RelativeMeasurementData)
-        else rm
+        (
+            RelativeMeasurementData(*rm)
+            if not isinstance(rm, RelativeMeasurementData)
+            else rm
+        )
         for rm in relative_measurements
     ]
     return Detector(
@@ -343,9 +346,11 @@ def make_observable(
         A :class:`Observable` operation with the `cirq.VirtualTag` tag.
     """
     relative_measurements_data = [
-        RelativeMeasurementData(*rm)
-        if not isinstance(rm, RelativeMeasurementData)
-        else rm
+        (
+            RelativeMeasurementData(*rm)
+            if not isinstance(rm, RelativeMeasurementData)
+            else rm
+        )
         for rm in relative_measurements
     ]
     return Observable(

src/tqec/enums.py

@@ -60,3 +60,8 @@ class PlaquetteSide(Enum):
     LEFT = auto()
     DOWN = auto()
     UP = auto()
+
+class TemplateOrientation(Enum):
+    """Indicates the orientation of the midline."""
+    HORIZONTAL = auto()
+    VERTICAL = auto()

src/tqec/plaquette/qubit.py

@@ -5,7 +5,7 @@
 
 import cirq
 
-from tqec.enums import PlaquetteOrientation, PlaquetteSide
+from tqec.enums import PlaquetteOrientation, PlaquetteSide, TemplateOrientation
 from tqec.position import Position
 
 
@@ -57,6 +57,34 @@ def permute_data_qubits(self, permutation: ty.Sequence[int]) -> PlaquetteQubits:
             [self.data_qubits[i] for i in permutation], self.syndrome_qubits
         )
 
+    def get_edge_qubits(
+        self,
+        orientation: TemplateOrientation = TemplateOrientation.HORIZONTAL,
+    ) -> list[PlaquetteQubit]:
+        """Return the data qubits on the edge of the plaquette.
+        By convention, the edge is the one with the highest index in the relevant axis.
+
+        Args:
+            orientation (TemplateOrientation, optional): Wheter to use horizontal or
+                vertical orientation. Defaults to horizontal.
+        Returns:
+            list[PlaquetteQubit]: The qubits on the edge of the plaquette.
+        """
+
+        def _get_relevant_value(qubit: PlaquetteQubit) -> int:
+            return (
+                qubit.position.y
+                if orientation == TemplateOrientation.HORIZONTAL
+                else qubit.position.x
+            )
+
+        max_index = max(_get_relevant_value(q) for q in self.data_qubits)
+        return [
+            qubit
+            for qubit in self.data_qubits
+            if (_get_relevant_value(qubit) == max_index)
+        ]
+
 
 class SquarePlaquetteQubits(PlaquetteQubits):
     def __init__(self):

src/tqec/templates/atomic/rectangle.py

@@ -2,6 +2,7 @@
 
 import numpy
 from tqec.exceptions import TQECException
+from tqec.enums import TemplateOrientation
 from tqec.position import Shape2D
 from tqec.templates.base import Template
 from tqec.templates.scale import Dimension
@@ -90,6 +91,23 @@ def to_dict(self) -> dict[str, ty.Any]:
     def expected_plaquettes_number(self) -> int:
         return 2
 
+    def get_midline_plaquettes(
+        self, orientation: TemplateOrientation = TemplateOrientation.HORIZONTAL
+    ) -> list[tuple[int, int]]:
+        midline_shape, iteration_shape = self.shape.x, self.shape.y
+        if orientation == TemplateOrientation.VERTICAL:
+            midline_shape, iteration_shape = iteration_shape, midline_shape
+
+        if midline_shape % 2 == 1:
+            raise TQECException(
+                "Midline is not defined for odd "
+                + f"{'height' if orientation == TemplateOrientation.HORIZONTAL else 'width'}."
+            )
+        midline = midline_shape // 2 - 1
+        if orientation == TemplateOrientation.VERTICAL:
+            return [(row, midline) for row in range(iteration_shape)]
+        return [(midline, column) for column in range(iteration_shape)]
+
 
 @ty.final
 class RawRectangleTemplate(Template):
@@ -179,15 +197,15 @@ def instantiate(self, plaquette_indices: ty.Sequence[int]) -> numpy.ndarray:
             plaquette_indices_array = numpy.array(plaquette_indices, dtype=int)
             indices = numpy.array(self._indices, dtype=int)
             return plaquette_indices_array[indices]
-        except IndexError:
+        except IndexError as ex:
             raise TQECException(
                 "RawRectangleTemplate instances should be constructed with 2-dimensional arrays "
                 "that contain indices that will index the plaquette_indices provided to "
-                "this method. The bigest index you provided at this instance creation is "
+                "this method. The biggest index you provided at this instance creation is "
                 f"{max(max(index) for index in self._indices)} "
                 f"but you provided only {len(plaquette_indices)} plaquette indices "
                 "when calling this method."
-            )
+            ) from ex
 
     def scale_to(self, _: int) -> "RawRectangleTemplate":
         return self
@@ -202,3 +220,20 @@ def to_dict(self) -> dict[str, ty.Any]:
     @property
     def expected_plaquettes_number(self) -> int:
         return max(max(line) for line in self._indices) + 1
+
+    def get_midline_plaquettes(
+        self, orientation: TemplateOrientation = TemplateOrientation.HORIZONTAL
+    ) -> list[tuple[int, int]]:
+        midline_shape, iteration_shape = self.shape.x, self.shape.y
+        if orientation == TemplateOrientation.VERTICAL:
+            midline_shape, iteration_shape = iteration_shape, midline_shape
+
+        if midline_shape % 2 == 1:
+            raise TQECException(
+                "Midline is not defined for odd "
+                + f"{'height' if orientation == TemplateOrientation.HORIZONTAL else 'width'}."
+            )
+        midline = midline_shape // 2 - 1
+        if orientation == TemplateOrientation.VERTICAL:
+            return [(row, midline) for row in range(iteration_shape)]
+        return [(midline, column) for column in range(iteration_shape)]

src/tqec/templates/atomic/rectangle_test.py

@@ -1,5 +1,6 @@
 import numpy
 import pytest
+from tqec.enums import TemplateOrientation
 from tqec.exceptions import TQECException
 from tqec.templates.atomic.rectangle import (
     AlternatingRectangleTemplate,
@@ -28,6 +29,11 @@ def dim2():
     return FixedDimension(2)
 
 
+@pytest.fixture
+def dim2x3():
+    return Dimension(2, LinearFunction(3))
+
+
 def test_rectangle_template_init(dim2x2, dim3x2):
     AlternatingRectangleTemplate(dim2x2, dim3x2)
 
@@ -180,3 +186,54 @@ def test_raw_rectangle_with_noncontiguous_indices():
 def test_raw_rectangle_with_negative_index():
     with pytest.raises(TQECException, match="starting at 0"):
         RawRectangleTemplate([[-1]])
+
+
+def test_raw_rectangle_midline():
+    template = RawRectangleTemplate(
+        [
+            [0, 0, 0, 0],
+            [0, 0, 0, 0],
+            [0, 0, 0, 0],
+            [0, 0, 0, 0],
+            [0, 0, 0, 0],
+            [0, 0, 0, 0],
+        ]
+    )
+    midline = template.get_midline_plaquettes()
+    assert midline == [(1, 0), (1, 1), (1, 2), (1, 3), (1, 4), (1, 5)]
+    midline = template.get_midline_plaquettes(TemplateOrientation.VERTICAL)
+    assert midline == [(0, 2), (1, 2), (2, 2), (3, 2)]
+    template.scale_to(4)
+    midline = template.get_midline_plaquettes()
+    # shoudl be 4*3 elements
+    template = RawRectangleTemplate([[0]])
+    with pytest.raises(TQECException, match="Midline is not defined for odd height."):
+        template.get_midline_plaquettes()
+
+
+def test_rectangle_midline(dim2x2, dim2x3):
+    template = AlternatingRectangleTemplate(dim2x2, dim2x3)
+    midline = template.get_midline_plaquettes()
+    assert midline == [(1, 0), (1, 1), (1, 2), (1, 3), (1, 4), (1, 5)]
+    midline = template.get_midline_plaquettes(TemplateOrientation.VERTICAL)
+    assert midline == [(0, 2), (1, 2), (2, 2), (3, 2)]
+    template.scale_to(4)
+    midline = template.get_midline_plaquettes()
+    # shoudl be 4*3 elements
+    assert midline == [
+        (3, 0),
+        (3, 1),
+        (3, 2),
+        (3, 3),
+        (3, 4),
+        (3, 5),
+        (3, 6),
+        (3, 7),
+        (3, 8),
+        (3, 9),
+        (3, 10),
+        (3, 11),
+    ]
+    template.scale_to(3)
+    with pytest.raises(TQECException, match="Midline is not defined for odd width."):
+        template.get_midline_plaquettes(TemplateOrientation.VERTICAL)