hal.codes.tile_codes¶

Qubit ¶

Qubit(coord, qubit_type, parent_tile=None)

Representation of a qubit within a tile.

Attributes:

coord (tuple[int, int]) –

Absolute grid coordinate.
qubit_type (Literal['data', 'X', 'Z']) –

Type of the qubit (data or check basis).
parent_tile (Tile | None) –

Reference to the containing tile.
connected_qubits (list[Qubit]) –

Adjacency list of connected qubits.
id (int | None) –

Unique identifier assigned when generating parity-check matrices.

has_empty_support `property` ¶

has_empty_support

Return whether the check qubit has empty support.

is_data `property` ¶

is_data

Check if the qubit is a data qubit.

is_fully_checked `property` ¶

is_fully_checked

Check if the qubit is fully checked. A data qubit is fully checked if it has at least one z- and one x-check qubit connected to it. A check qubit is itself not checked. Print and return.

relative_coord `property` ¶

relative_coord

Get the relative coordinates of the qubit in the tile. The coordinates are represented as a tuple of (x, y).

Tile ¶

Tile(
    bounding_box,
    data_qubit_coords,
    basis,
    *,
    origin=(0, 0),
    check_qubit_coord=None,
    parent_tile_matrix=None,
    blocked_check_qubit_coords=None,
    enforce_max_nearest_neighbors=False,
    distance_metric="euclidean",
    tie_breaker="random"
)

Tile representing a single stabilizer with support on neighboring edges.

Attributes:

bounding_box (tuple[int, int]) –

Dimensions of the tile in edge coordinates.
data_qubit_coords (list[tuple[int, int]]) –

Relative grid coordinates of data qubits in the tile.
basis (Literal['X', 'Z']) –

Stabilizer basis.
origin (tuple[int, int]) –

Origin of the tile in grid coordinates within the tile matrix.
check_qubit_coord (tuple[int, int] | None) –

Relative coordinate of the check qubit; computed if not provided.
parent_tile_matrix (TileMatrix | None) –

Container matrix reference for shared qubit lists.
tile_grid_size (tuple[int, int]) –

Derived grid size for this tile (2× bounding_box).
check_qubit (Qubit) –

The check qubit instance created for this tile.
blocked_check_qubit_coords (list[tuple[int, int]]) –

List of blocked check qubit coordinates.
enforce_max_nearest_neighbors (bool) –

Whether to enforce a maximum number of nearest neighbors when choosing check qubit position.
distance_metric (Literal['euclidean', 'manhattan', 'random'] | None) –

The distance metric to use when choosing check qubit position.
tie_breaker (Literal['euclidean', 'manhattan', 'random'] | None) –

The tie breaker metric to use when choosing check qubit position.

absolute_data_qubit_coords `property` ¶

absolute_data_qubit_coords

Get the absolute coordinates of the data qubits in the tile. The coordinates are represented as a tuple of (x, y).

absolute_data_qubit_edge_coords `property` ¶

absolute_data_qubit_edge_coords

Get the absolute edge coordinates of the data qubits in the tile. The edge coordinates are represented as a tuple of (x, y, orientation). The orientation is either "h" or "v".

data_qubit_edge_coords `property` ¶

data_qubit_edge_coords

Get the edge coordinates of the data qubits in the tile. The edge coordinates are represented as a tuple of (x, y, orientation). The orientation is either "h" or "v".

get_optimal_check_qubit_coord `staticmethod` ¶

get_optimal_check_qubit_coord(
    tile_grid_size,
    data_qubit_coords,
    blocked_check_qubit_coords=None,
    enforce_max_nearest_neighbors=False,
    distance_metric="euclidean",
    tie_breaker="random",
)

Return the coordinate within the tile grid where a check qubit should be placed to minimize the distance to all data qubits. The distance is calculated using the specified distance metric.

Only coordinates with even (i + j) are considered valid. If there is a blocked check qubit coord, that entire sublattice (faces or vertices) is blocked. Coordinates where both numbers are odd lie on faces, coordinates where both numbers are even lie on vertices. It suffices to check either the x or y dimension.

print_self ¶

print_self()

Print the tile in a human-readable format. The tile is represented as a grid with data qubits marked by 'X' or 'Z'.

print_tile `staticmethod` ¶

print_tile(
    bounding_box,
    data_qubit_edge_coords,
    basis="X",
    check_qubit_coord=None,
)

Print the tile in a human-readable format. The tile is represented as a grid with data qubits marked by 'X' or 'Z'.

E.g.:

bounding_box = (4, 4) data_qubit_edge_coords: List[Edge] = [ (0, 0, "v"), (0, 0, "h"), (1, 0, "v"), (0, 1, "v"), (2, 1, "h") ]

print_tile(bounding_box, data_qubit_edge_coords, "Z")

| | | | _ _ _ _ | | | | _ _ _ _ Z | | | _ _ Z _ Z Z | | . Z _ _ _

transform_edge_to_grid_coord `staticmethod` ¶

transform_edge_to_grid_coord(edge_coord)

Transform an edge coordinate to a grid coordinate. The edge coordinate is represented as a tuple of (x, y, orientation). The orientation is either "h" or "v".

transform_edge_to_grid_coords `staticmethod` ¶

transform_edge_to_grid_coords(edge_coord_list)

Transform a list of edge coordinates to grid coordinates. The edge coordinates are represented as a tuple of (x, y, orientation). The orientation is either "h" or "v".

transform_grid_to_edge_coord `staticmethod` ¶

transform_grid_to_edge_coord(grid_coord)

Transform a grid coordinate to an edge coordinate. The edge coordinate is represented as a tuple of (x, y, orientation). The orientation is either "h" or "v".

transform_grid_to_edge_coords `staticmethod` ¶

transform_grid_to_edge_coords(grid_coord_list)

Transform the data qubit coordinates in the tile to edge coordinates. The edge coordinates are represented as a tuple of (x, y, orientation). The orientation is either "h" or "v".

transpose_tile `staticmethod` ¶

transpose_tile(bounding_box, data_qubit_edge_coords)

Translate the data qubit coordinates from X tile to Z tile.

TileCode ¶

TileCode(
    x_tile_params,
    matrix_size,
    *,
    x_check_qubit_coord=None,
    z_check_qubit_coord=None,
    blocked_check_qubit_coords=None,
    enforce_max_nearest_neighbors=False,
    distance_metric="euclidean",
    tie_breaker="random",
    top_bot_basis="X",
    timeout=1.0
)

Bases: TileMatrix

Tile code composed of a TileMatrix with derived properties and graphs.

Attributes:

Hx, Hz (ndarray) –

X/Z parity-check matrices.
Hxz (ndarray) –

vstack of (Hx, Hz).
tanner_graph (Graph) –

Tanner graph derived from Hx/Hz.
css_code (CSSCode) –

Underlying CSS code object used to compute distances.
n, k, d (int) –

Code length, dimension and distance (estimated).
pos_dict_bare, pos_dict_rich (dict) –

Node position maps used for layout and tanner visualization.
x_tile_params, z_tile_params (dict) –

Parameter dictionaries used to instantiate X/Z tiles.
matrix_size (tuple[int, int]) –

Number of tiles in X and Y directions.
x_check_qubit_coord (tuple[int, int] | None) –

Relative coordinate of the x check qubit; computed if not provided.
z_check_qubit_coord (tuple[int, int] | None) –

Relative coordinate of the z check qubit; computed if not provided.
blocked_check_qubit_coords (list[tuple[int, int]]) –

List of blocked check qubit coordinates.
enforce_max_nearest_neighbors (bool) –

Whether to enforce a maximum number of nearest neighbors when choosing check qubit position.
distance_metric (Literal['euclidean', 'manhattan', 'random'] | None) –

The distance metric to use when choosing check qubit position.
tie_breaker (Literal['euclidean', 'manhattan', 'random'] | None) –

The tie breaker metric to use when choosing check qubit position.

add_boundary_tiles ¶

add_boundary_tiles(top_bot_basis='X')

Add boundary tiles to the tile matrix. At each edge add B-1 layers of tiles, where B is the bounding box size. The top and bottom edges will have tiles with the given basis, while the left and right edges will have tiles with the opposite basis.

add_custom_tile ¶

add_custom_tile(coord, tile_params)

Add a custom tile to the tile matrix.

add_tile ¶

add_tile(coord, basis)

Add a tile of the given basis at the specified coordinate.

delete_data_qubit ¶

delete_data_qubit(coord, perform_print=True)

Delete a data qubit at the given coordinate. This will remove the data qubit from the adjacency list of its connected check qubits. It will also remove the data qubit from its tile's list of data qubit coordinates, and remove the corresponding bar from the print statement. Self.global_data_qubit_list will be updated with None to remove the deleted data qubit.

delete_tile ¶

delete_tile(coord, basis, perform_print=True)

Delete a tile of the given basis at the specified coordinate.

get_parity_check_matrices ¶

get_parity_check_matrices()

Get the parity check matrices for the tile matrix. The first matrix is the X parity check matrix, the second is the Z parity check matrix.

get_position_dict ¶

get_position_dict()

Get a dictionary that maps the qubit id to its position in the tile matrix. The keys are the qubit ids, and the values are the grid coordinates of the qubits.

get_tiles ¶

get_tiles(coord)

Get the tiles at the given coordinate.

init_from_generalized_toric `classmethod` ¶

init_from_generalized_toric(
    f_ab,
    g_ab,
    matrix_size,
    x_check_qubit_coord=None,
    z_check_qubit_coord=None,
    timeout=1.0,
)

Creates a tile code using the degrees shown in https://arxiv.org/pdf/2503.03827.

print_matrix ¶

print_matrix()

Print all tile origins. A single tile origin is represented by its basis, either "x" or "z". If two different bases overlap, it is prented as "b"

print_tiles ¶

print_tiles(tile_locators=None, print_all=False)

Print a full canvas. Add tiles on top that are provided as an argument.

prune_data_qubits ¶

prune_data_qubits()

Prune all data qubits that are not fully checked.

prune_tiles ¶

prune_tiles()

Prune all tile that have empty support.

update_code_properties ¶

update_code_properties(timeout=1.0)

Update the properties of the tile code, including the parity check matrices,

TileMatrix ¶

TileMatrix(
    x_tile_params,
    matrix_size,
    x_check_qubit_coord=None,
    z_check_qubit_coord=None,
    blocked_check_qubit_coords=None,
    enforce_max_nearest_neighbors=False,
    distance_metric="euclidean",
    tie_breaker="random",
)

Matrix of tiles composing a code layout.

Attributes:

x_tile_params, z_tile_params (dict) –

Parameter dictionaries used to instantiate X/Z tiles.
matrix_size (tuple[int, int]) –

Number of tiles in X and Y directions.
x_check_qubit_coord (tuple[int, int] | None) –

Relative coordinate of the x check qubit; computed if not provided.
z_check_qubit_coord (tuple[int, int] | None) –

Relative coordinate of the z check qubit; computed if not provided.
matrix_bounding_box (tuple[int, int]) –

Effective bounding box of the matrix in tile units.
matrix_grid_size (tuple[int, int]) –

Grid size in points (2× tile units plus overlap adjustments).
global_data_qubit_list (list[Qubit]) –

All data qubits across tiles (deduplicated by absolute coord).
global_check_qubit_list (list[Qubit]) –

All check qubits across tiles.
tiles_dict (dict[tuple[int, int], list[Tile]]) –

Mapping from matrix coordinates to tiles present there.
deleted_data_qubit_coords (list[tuple[int, int]]) –

Coordinates of pruned data qubits.
blocked_check_qubit_coords (list[tuple[int, int]]) –

List of blocked check qubit coordinates.
enforce_max_nearest_neighbors (bool) –

Whether to enforce a maximum number of nearest neighbors when choosing check qubit position.
distance_metric (Literal['euclidean', 'manhattan', 'random'] | None) –

The distance metric to use when choosing check qubit position.
tie_breaker (Literal['euclidean', 'manhattan', 'random'] | None) –

The tie breaker metric to use when choosing check qubit position.

add_boundary_tiles ¶

add_boundary_tiles(top_bot_basis='X')

Add boundary tiles to the tile matrix. At each edge add B-1 layers of tiles, where B is the bounding box size. The top and bottom edges will have tiles with the given basis, while the left and right edges will have tiles with the opposite basis.

add_custom_tile ¶

add_custom_tile(coord, tile_params)

Add a custom tile to the tile matrix.

add_tile ¶

add_tile(coord, basis)

Add a tile of the given basis at the specified coordinate.

delete_data_qubit ¶

delete_data_qubit(coord, perform_print=True)

Delete a data qubit at the given coordinate. This will remove the data qubit from the adjacency list of its connected check qubits. It will also remove the data qubit from its tile's list of data qubit coordinates, and remove the corresponding bar from the print statement. Self.global_data_qubit_list will be updated with None to remove the deleted data qubit.

delete_tile ¶

delete_tile(coord, basis, perform_print=True)

Delete a tile of the given basis at the specified coordinate.

get_parity_check_matrices ¶

get_parity_check_matrices()

Get the parity check matrices for the tile matrix. The first matrix is the X parity check matrix, the second is the Z parity check matrix.

get_position_dict ¶

get_position_dict()

Get a dictionary that maps the qubit id to its position in the tile matrix. The keys are the qubit ids, and the values are the grid coordinates of the qubits.

get_tiles ¶

get_tiles(coord)

Get the tiles at the given coordinate.

print_matrix ¶

print_matrix()

Print all tile origins. A single tile origin is represented by its basis, either "x" or "z". If two different bases overlap, it is prented as "b"

print_tiles ¶

print_tiles(tile_locators=None, print_all=False)

Print a full canvas. Add tiles on top that are provided as an argument.

prune_data_qubits ¶

prune_data_qubits()

Prune all data qubits that are not fully checked.

prune_tiles ¶

prune_tiles()

Prune all tile that have empty support.

hal.codes.tile_codes¶

Qubit ¶

has_empty_support property ¶

is_data property ¶

is_fully_checked property ¶

relative_coord property ¶

Tile ¶

absolute_data_qubit_coords property ¶

absolute_data_qubit_edge_coords property ¶

data_qubit_edge_coords property ¶

get_optimal_check_qubit_coord staticmethod ¶

print_self ¶

print_tile staticmethod ¶

transform_edge_to_grid_coord staticmethod ¶

transform_edge_to_grid_coords staticmethod ¶

transform_grid_to_edge_coord staticmethod ¶

transform_grid_to_edge_coords staticmethod ¶

transpose_tile staticmethod ¶

TileCode ¶

add_boundary_tiles ¶

add_custom_tile ¶

add_tile ¶

delete_data_qubit ¶

delete_tile ¶

get_parity_check_matrices ¶

get_position_dict ¶

get_tiles ¶

init_from_generalized_toric classmethod ¶

print_matrix ¶

print_tiles ¶

prune_data_qubits ¶

prune_tiles ¶

update_code_properties ¶

TileMatrix ¶

add_boundary_tiles ¶

add_custom_tile ¶

add_tile ¶

delete_data_qubit ¶

delete_tile ¶

get_parity_check_matrices ¶

get_position_dict ¶

get_tiles ¶

print_matrix ¶

print_tiles ¶

prune_data_qubits ¶

prune_tiles ¶

has_empty_support `property` ¶

is_data `property` ¶

is_fully_checked `property` ¶

relative_coord `property` ¶

absolute_data_qubit_coords `property` ¶

absolute_data_qubit_edge_coords `property` ¶

data_qubit_edge_coords `property` ¶

get_optimal_check_qubit_coord `staticmethod` ¶

print_tile `staticmethod` ¶

transform_edge_to_grid_coord `staticmethod` ¶

transform_edge_to_grid_coords `staticmethod` ¶

transform_grid_to_edge_coord `staticmethod` ¶

transform_grid_to_edge_coords `staticmethod` ¶

transpose_tile `staticmethod` ¶

init_from_generalized_toric `classmethod` ¶