loom.eka.matrices

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.matrices.ClassicalParityCheckMatrix(matrix_input)[source]

Bases: object

Classical parity-check matrix for error-correcting codes.

The ClassicalParityCheckMatrix class stores a parity-check matrix faithfully describing a classical error-correcting code. This is a binary matrix, where each row describes a classical check and each column a classical bit.

The object can be instantiated from a numpy array, a list of lists, or a tuple of Stabilizers. For an array-like input, the matrix is verified to be valid and cleaned afterwards. We adopt the convention of removing repeated rows and empty rows. For a Stabilizers input, we require all of them to be of the same pauli type, i.e. either X or Z. The support of the matrix rows is then built from the qubit support of each stabilizer.

The ClassicalParityCheckMatrix object can also be casted as a list of Stabilizers.

Lastly the matrix, can also be generated from a ClassicalTannerGraph, where the connectivity of the check nodes is translated into the rows of the matrix.

Parameters:: input (np.ndarray | list[list[int]] | tuple[Stabilizer,...] | ClassicalTannerGraph) – Input to instantiate the ClassicalParityCheckMatrix object.

clean_matrix()[source]

Clean the parity-check matrix by removing repeated and empty rows and columns.

Return type:: None

static generate_matrix_from_graph(tanner_graph)[source]

Generate parity-check matrix from an input Tanner graph.

Parameters:: tanner_graph (graphs.ClassicalTannerGraph) – Tanner graph to generate the parity-check matrix from.
Returns:: h_matrix – Parity-check matrix generated from the Tanner graph.
Return type:: np.ndarray

static generate_matrix_from_stabilizers(stabilizers)[source]

Generate parity-check matrix from a set of stabilizers.

Parameters:: stabilizers (tuple[Stabilizer,...]) – Stabilizers to generate the parity-check matrix from.
Returns:: h_matrix – Parity-check matrix generated from the stabilizers.
Return type:: np.ndarray

to_stabilizers(pauli_type)[source]

Convert the parity-check matrix to a list of Stabilizers.

Parameters:: pauli_type (str) – Pauli type to assign to the stabilizers, either ‘X’ or ‘Z’.
Returns:: stabilizers – List of Stabilizers generated from the parity-check matrix.
Return type:: list[Stabilizer]

static verify_input(h_matrix)[source]

Verify the input parity-check matrix is valid. The matrix is required to be binary, two-dimensional, and non-empty.

Parameters:: h_matrix (np.ndarray) – Parity-check matrix to be verified.
Return type:: None

class loom.eka.matrices.ParityCheckMatrix(input)[source]

Bases: object

Parity-check matrix for quantum error-correcting codes.

The ParityCheckMatrix class stores a parity-check matrix faithfully describing a quantum error-correcting code. This is a binary matrix, where each row is associated with the symplectic representation of a stabilizer. Therefore, these matrices have twice the number of columns as the number of data qubits in the code, with the first half representing the X stabilizers and the second half representing the Z stabilizers. The number of rows is then equal to the number of stabilizers in the code. To represent a valid quantum code, these matrices must satisfy the vanishing symplectic product condition, i.e. the symplectic product of the matrix with itself must be zero. This corresponds to all the stabilizers commuting with each other.

The object can be instantiated from a numpy array or a list of lists, a TannerGraph object or a tuple containing Stabilizer objects. For an array-like input, the matrix is verified to be valid and cleaned afterwards. We adopt the convention of removing repeated rows and empty rows. For a TannerGraph input, the parity-check matrix is generated from the connectivity of bipartite graph. For a Stabilizer input, each ancilla and each data qubit are mapped into rows and columns of the matrix, respectively.

Parameters:: input (np.ndarray | list[list[int]] | TannerGraph | tuple[Stabilizer, ...]) – Input to instantiate the ParityCheckMatrix object.

property check_if_css: bool

Check if the parity-check matrix defines a CSS code. Commutativity is checked beforehand by verifying that the symplectic product of the full matrix.

Returns:: valid_css – True if the parity-check matrix defines a valid CSS code, False otherwise.
Return type:: bool

clean_matrix()[source]

Clean the parity-check matrix by removing repeated and empty rows and columns.

Return type:: None

static generate_matrix_from_graph(tanner_graph)[source]

Generate parity-check matrix from an input Tanner graph.

Parameters:: tanner_graph (TannerGraph) – Tanner graph object to generate the parity-check matrix from.
Returns:: h_matrix – Parity-check matrix generated from the Tanner graph as numpy array.
Return type:: np.ndarray

static generate_matrix_from_stabilizers(stabilizers)[source]

Generate parity-check matrix from a list of stabilizers. Each stabilizer is converted into a row of the matrix. For consistency, we sort the data qubits according to their coordinates and assign them a column index in the matrix.

Parameters:: stabilizers (tuple[Stabilizer,...]) – Stabilizers to generate the parity-check matrix from.
Returns:: h_matrix – Parity-check matrix generated from the stabilizers as numpy array.
Return type:: np.ndarray

get_components()[source]

Compute the X and Z components of the parity-check matrix, if possible.

Return type:

tuple[ClassicalParityCheckMatrix, ClassicalParityCheckMatrix]

Returns:

hx_matrix (ClassicalParityCheckMatrix) – The X component of the parity-check matrix, containing only X stabilizers.
hz_matrix (ClassicalParityCheckMatrix) – The Z component of the parity-check matrix, containing only Z stabilizers.

property hx_matrix: ClassicalParityCheckMatrix: Extract the X component of the parity-check matrix.

property hz_matrix: ClassicalParityCheckMatrix: Extract the Z component of the parity-check matrix.

property n_xstabs: int: Extract the number of X stabilizers.

property n_zstabs: int: Extract the number of Z stabilizers.

to_stabilizers()[source]

Converts the parity-check matrix to a list of Stabilizers. The stabilizers are generated by scanning each row of the matrix and extracting data qubits from the position of the non-zero elements. The data qubits are assigned coordinates in the form (index,0), where index is the column index of the data qubit in the symplectic representation of the matrix. The ancilla qubits are assigned coordinates in the form (index,1), where index is the row index of the stabilizer in the matrix.

Returns:: stabilizers – List of Stabilizers generated from the parity-check matrix.
Return type:: list[Stabilizer]

static verify_input(h_matrix)[source]

Verifies that parity-check matrix defines a valid quantum code, through structural checks and computing the symplectic product with itself.

Parameters:: h_matrix (np.ndarray) – A full parity-check matrix for a quantum code.
Return type:: None