loom.eka.lattice

Copyright (c) Entropica Labs Pte Ltd 2025.

Use, distribution and reproduction of this program in its source or compiled form is prohibited without the express written consent of Entropica Labs Pte Ltd.

class loom.eka.lattice.Lattice(*args, **kwargs)

Bases: object

A lattice object contains information about the lattice structure. The lattice defines the indexing system of qubits, since qubits are indexed by their coordinates in terms of the lattice and basis vectors.

Note that this lattice on which stabilizers, logical qubit blocks, and lattice surgery operations are defined, is a priori only an abstract lattice which makes defining all these things and handling qubit indices convenient. It does not have to be the actual lattice of the physical hardware.

Qubit indices have the form (x_0, …, x_{n-1}, b) where x_0, …, x_{n-1} denote the unit cell with n the dimension of the lattice and b denotes which qubit in the unit cell it is.

E.g. for a 2D lattice with a 2-qubit unit cell, the qubit indices are (x, y, b) which means that it is the x-th unit cell along the first lattice vector, the y-th unit cell along the second lattice vector, and the b-th qubit in the unit cell (b is either 0 or 1 in the case of a 2-qubit unit cell).

Parameters:

• basis_vectors (tuple[tuple[float, ...], ...]) – Tuple of basis vectors that define the unit cell. If there is more than one qubit in the unit cell, one has to specify their position inside the unit cell using the basis vectors.

• lattice_vectors (tuple[tuple[float, ...], ...]) – Tuple of lattice vectors that define the lattice. The whole lattice is obtained by translating the unit cell along these lattice vectors by integer amounts.

• size (tuple[int, ...] | None) – The size of the lattice in each dimension. If set to None, the lattice is assumed to be infinitely large.

• lattice_type (LatticeType) – Type of the lattice. This is useful for storing the lattice as well as for some function such as Block creation which behave differently for different lattice types. Default is LatticeType.CUSTOM which means the lattice is created by the user.

all_qubits(size=None, force_including_basis=False)

Get a list of qubits in the lattice inside the region specified by size.

Parameters:

• size (tuple[int | None, ...] | None, optional) – If only a part of the lattice is needed, the size of the wanted section can be specified. If None is provided, all qubits of the lattice will be returned. If the lattice has infinite size, the size parameter must be provided.

• force_including_basis (bool, optional) – By default, the basis parameter is included in the qubit indices only if size > 1. To force it to appear for size == 1, set this boolean to True.

Returns:

List of all qubits inside the specified region.

Return type:

list[tuple[int, …]]

all_unit_cells(size=None)

Get a list of all unit cells of the lattice. They are given in terms of the lattice vectors.

Parameters:

size (tuple[int | None, ...] | None, optional) – If only a part of the lattice is needed, the size of the wanted section can be specified. If None is provided, all unit cells of the lattice will be returned. If the lattice has infinite size, the size parameter must be provided.

Returns:

Unit cells of the lattice for the given dimensions. They are given as a list of tuples where each tuple contains the coordinates of the unit cell in terms of the lattice vectors.

Return type:

list[tuple[int, …]]

basis_vectors: tuple[tuple[float, ...], ...]

classmethod basis_vectors_same_length(basis_vectors)

Validate that all basis vectors have the same length.

classmethod cairo_pent_2d(lattice_size=None)

Generates a catalan pentagonal lattice which is a regular tiling of the plane. Although there are an infinite number of ways to tile the plane with pentagons, this implementation uses a bilaterally symmetric pentagon with 4 long edges and 1 short edge in the ratio of 1 : sqrt(3) - 1. The angles of this pentagon (starting from top and moving clockwise) are 120, 90, 120, 120, and 90 degrees.

Each unit cell contains 6 points. The first 5 points are the vertices of a pentagon, and the 6th point is a point on another pentagon that is adjacent to the first one. The points are arranged such that they tile the plane via the lattice vectors, though the tiling will not be intuitive due to the current unit cell definition. :returns: A Lattice object representing the catalan pentagonal lattice. :rtype: Lattice

classmethod cube_3d(lattice_size=None)

Generates a cubic lattice in 3D. The lattice is defined by three lattice vectors that are orthogonal to each other tiling the 3D space in a cubic pattern.

Parameters:

lattice_size (tuple[int, int, int] | None, optional) – The size of the lattice in terms of unit cells. If None, the lattice is assumed to be infinitely large.

Returns:

A Lattice object representing the cubic lattice.

Return type:

Lattice

classmethod format_basis_vectors(basis_vectors)

Format the basis_vector input to also accept [] for 1-qubit unit cells.

classmethod hex_2d(lattice_size=None)

Generates a hexagonal lattice in 2D. The lattice tiles the plane, and is defined by two lattice vectors that are 60 degrees to each other. The unit cell contains 2 points (2 qubits) arranged in a downwards sloping line. The lattice vectors tile the plane in a hexagonal pattern.

Parameters:

lattice_size (tuple[int, int] | None, optional) – The size of the lattice in terms of unit cells. If None, the lattice is assumed to be infinitely large.

Returns:

A Lattice object representing the hexagonal lattice.

Return type:

Lattice

lattice_type: LatticeType = 'custom'

lattice_vectors: tuple[tuple[float, ...], ...]

classmethod lattice_vectors_same_length(lattice_vectors)

Validate that all lattice vectors have the same length.

classmethod linear(lattice_size=None)

Generates a linear lattice in 1D. The lattice is defined by a single lattice vector that is parallel to the x-axis. The unit cell is defined by set of two basis vectors. The unit cell contains 2 points (1 qubit, 1 ancilla) arranged on a straight line. The lattice vector tiles the plane in a linear pattern.

Parameters:

lattice_size (tuple[int] | None, optional) – The size of the lattice in terms of unit cells. If None, the lattice is assumed to be infinitely large.

Returns:

A Lattice object representing the linear lattice.

Return type:

Lattice

property n_dimensions: int

The dimension of the lattice, i.e. the number of lattice vectors.

classmethod oct_2d(lattice_size=None, r=0.5, anc=0)

Generates a semi-regular octagonal lattice with a specified radius r for the points on the circle. The lattice tiles the plane. Spaces between adjacent octagons are tiled by squares.

Each unit cell contains 8 qubits + 4 sets of ancilla. The number of ancilla in each set is determined by the anc parameter, and is 0 by default. The data qubits are placed on a circle of radius r. The ancilla qubits are placed on a circle that is 1 / 2 the radius of the squares.

First set with indices [88 + anc]:

Ancilla for primary octagon. Placed on a circle of radius r * sin(pi / 8) / 2.

Second set with indices [8 + anc8 + 2 * anc]:

Ancilla for square below primary octagon. Placed on a circle of the same radius, shifted by half the distance between adjacent unit cells in the y-direction.

Third set with indices [8 + 2 * anc8 + 3 * anc]:

Ancilla for square to right of primary octagon. Placed on a circle of the same radius, shifted by half the distance between adjacent unit cells in the y-direction.

Fourth set with indices [8 + 3 * anc8 + 4 * anc]:

Ancilla for secondary octagon, diagonal down from primary octagon. Placed on a circle of the same radius, shifted by half the distance between adjacent unit cells in both the x and y directions.

Parameters:

• lattice_size (tuple[int, int] | None, optional) – The size of the lattice in terms of unit cells. If None, the lattice is assumed to be infinitely large.

• r (float, optional) – The radius of the circle on which the points are placed. Default is 0.5.

• anc (int, optional) – The number of ancilla qubits in the unit cell. Default is 0. If anc is set to 1, ancilla will be placed at the centre of each octagonal and square tiles.

Returns:

A Lattice object representing the octagonal lattice.

Return type:

Lattice

classmethod poly_2d(lattice_size=None, n=None, poly_radius=0.5, poly_offset=-1.5707963267948966, cell_dist_factor=np.float64(2.732050807568877), anc=1, anc_radius=0.2, anc_offset=-1.5707963267948966, anc_disp=(0, 0))

Generates a lattice of n-sided polygons. The points are placed on a circle of radius poly_radius and arranged in a polygonal pattern. The lattice does not tile the plane, but is useful for certain applications where polygonal symmetry is desired.

Lattice vectors are defined such that the distance between adjacent unit cells is poly_radius * cell_dist_factor. Each unit cell contains n + anc points (n qubits, anc ancilla). The anc points are placed on a circle of radius anc_radius. If anc is set to 1, ancilla will be placed at the center of the polygon.

Parameters:

• lattice_size (tuple[int, int] | None, optional) – The size of the lattice in terms of unit cells. If None, the lattice is assumed to be infinitely large.

• n (int, optional) – The number of sides of the polygon. Default is 5 (pentagon).

• poly_radius (float | int, optional) – The radius of the circle on which the points are placed. Default is 0.5.

• poly_offset (float | int, optional) – The offset to be applied to the angle of the points on the circle. This is useful for placing the first point at a specific angle. Default is -0.5 * np.pi (top of circle).

• cell_dist_factor (float | int, optional) – The factor by which the distance between adjacent unit cells is multiplied. This is useful for adjusting the distance between the polygons. Default is (1 + np.sqrt(3)) as a purely aesthetic choice to ensure that the polygons are not too close together.

• anc (int, optional) – The number of ancilla qubits in the unit cell. Default is 1. If anc is set to 1, ancilla will be placed at the center of the polygon and at the center of the edges of the polygon.

• anc_radius (float | int, optional) – The radius of the circle on which the ancilla points are placed. Default is 0.2.

• anc_offset (float | int, optional) – The offset to be applied to the angle of the ancilla points on the circle. This is useful for placing the first ancilla point at a specific angle. Default is -0.5 * np.pi (top of circle).

• anc_disp (tuple[int | float, int | float], optional) – The displacement of the ancilla points from the center of the circle. This is useful for placing the ancilla points at a specific position in the 2D plane. Default is (0, 0).

Returns:

A Lattice object representing the polygonal lattice.

Return type:

Lattice

size: tuple[int, ...] | None = None

classmethod size_not_negative(size)

Validate that size is not negative.

classmethod size_right_dimension(size, values)

Validate that size has the right dimension, i.e. the size of the tuple has to be equal to the number of lattice vectors.

classmethod square_2d(lattice_size=None)

Generates a square lattice in 2D. The lattice tiles the plane, and is defined by two lattice vectors that are orthogonal to each other. The unit cell is defined by a set of two basis vectors. The unit cell contains 2 points (1 qubits, 1 ancilla) arranged in a downwards sloping line. The lattice vectors tile the plane in a square pattern.

Basis vector 0 represents the data qubit, and basis vector 1 represents the ancilla qubit.

Parameters:

lattice_size (tuple[int, int] | None, optional) – The size of the lattice in terms of unit cells. If None, the lattice is assumed to be infinitely large.

Returns:

A Lattice object representing the square lattice.

Return type:

Lattice

classmethod square_2d_0anc(lattice_size=None)

Generates a square lattice in 2D. The lattice tiles the plane, and is defined by two lattice vectors that are orthogonal to each other. The unit cell is defined by one basis vector. The unit cell contains 1 point (1 qubit). The lattice vectors tile the plane in a square pattern.

Basis vector 0 represents the data qubit.

NOTE: This lattice was defined for the specific use of the HGP code class, because the product structure automatically allocates two dimensional coordinates to all qubits in the code block (both datas and checks)

Parameters:

lattice_size (tuple[int, int] | None, optional) – The size of the lattice in terms of unit cells. If None, the lattice is assumed to be infinitely large.

Returns:

A Lattice object representing the square lattice.

Return type:

Lattice

classmethod square_2d_2anc(lattice_size=None, shift=0.15)

Generates a square lattice in 2D. The lattice tiles the plane, and is defined by two lattice vectors that are orthogonal to each other. The unit cell is defined by a set of two basis vectors. The unit cell contains 3 points (1 qubits, 2 ancilla) arranged such that the ancillas lie on the same line, but with a slight separation. The lattice vectors tile the plane in a square pattern. Basis vector 0 represents the data qubit, and basis vectors 1 and 2 represent the first ancilla and second ancilla qubit.

NOTE: This lattice was defined for the specific use of the 488 Color code, where the ancillas are arranged to be slightly shifted from the center of a polygon and where the datas are placed at the vertices of the given polygon.

Parameters:

• lattice_size (tuple[int, int] | None, optional) – The size of the lattice in terms of unit cells. If None, the lattice is assumed to be infinitely large.

• shift (float, optional) – The shift of the ancilla qubits from the center of the unit cell. Default is 0.15.

Returns:

A Lattice object representing the square lattice.

Return type:

Lattice

classmethod triangle_2d(lattice_size=None)

Generates a triangular lattice in 2D. The lattice tiles the plane, and is defined by two lattice vectors that are 60 degrees to each other. The unit cell is defined by a set of three basis vectors. The unit cell contains 3 points (1 qubits, 2 ancilla) arranged in a downwards sloping line. The lattice vectors tile the plane in a triangular pattern.

Basis vector 0 represents the data qubit. Basis vector 1 represents ancilla qubit for triangles with vertices pointing downwards, and basis vector 2 represents ancilla qubit for triangles with vertices pointing upwards.

Parameters:

lattice_size (tuple[int, int] | None, optional) – The size of the lattice in terms of unit cells. If None, the lattice is assumed to be infinitely large.

Returns:

A Lattice object representing the triangular lattice.

Return type:

Lattice

property unit_cell_size: int

The size of the unit cell, i.e. the number of basis vectors.

class loom.eka.lattice.LatticeType(*values)

Bases: str, Enum

Defines the types of lattices available.

CAIRO_PENT_2D = 'cairo_pent_2d'

CUBE_3D = 'cube_3d'

CUSTOM = 'custom'

HEX_2D = 'hex_2d'

LINEAR = 'linear'

OCT_2D = 'oct_2d'

POLY_2D = 'poly_2D'

SQUARE_2D = 'square_2d'

SQUARE_2D_0ANC = 'square_2d_0anc'

SQUARE_2D_2ANC = 'square_2d_2anc'

TRIANGLE_2D = 'triangle_2d'