loom.eka.tanner_graphs

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.tanner_graphs.ClassicalTannerGraph(input)[source]

Bases: object

Classical Tanner Graph representation.

The Classical Tanner Graph class stores a bipartite graph representation of a classical error-correcting code. The graph is bipartite, with data nodes on one partition and check nodes on the other. The check nodes can be labelled with either ‘X’ or ‘Z’ if the code is to be related with quantum error properties, or it can be generically labelled as “check”. If a networkx.Graph is given as input, the graph will go through a set of verifications to ensure its validity to represent the classical code. The input can also be a tuple of stabilizers, which need to be of the same time pauli type, and the graph will be generated from them. The graph can be converted into a list of stabilizers. The check type of the Tanner graph can be modified using the set_check_type method. Lastly, the class can also be instantiated from ClassicalParityCheckMatrix object, where the matrix is mapped to a Tanner graph and the check nodes are labeled as ‘check’.

Parameters:: input (nx.Graph | tuple[Stabilizer,...] | ClassicalParityCheckMatrix) – Input graph, tuple of stabilizers, or ClassicalParityCheckMatrix to build the Classical Tanner graph.

generate_graph_from_matrix(h_matrix)[source]

Generate Tanner graph from a ClassicalParityCheckMatrix object.

Parameters:: h_matrix (matrices.ClassicalParityCheckMatrix) – Parity-check matrix to generate the Tanner graph.
Returns:: g – Classical Tanner graph, as a networkx object generated from the input parity-check matrix.
Return type:: nx.Graph

generate_graph_from_stabilizers(stabilizers)[source]

Generate a Classical Tanner graph from a tuple of stabilizers.

Parameters:: stabilizers (tuple[Stabilizer]) – Tuple of stabilizers to generate the Classical Tanner graph. All must be of the same pauli type.
Returns:: t_graph – Classical Tanner graph, as a networkx object generated from the input stabilizers.
Return type:: nx.Graph

relabelled_graph()[source]

Relabel a Classical Tanner graph to identify nodes with tuples of integers which can later be converted into Stabilizers. The nodes are a assigned a single-element tuple with an integer index. The data nodes are counted first, followed by the check nodes. The old node labels are stored in the node attributes under the key ‘original_node’.

Returns:: relabelled_tanner – Relabelled Classical Tanner graph.
Return type:: ClassicalTannerGraph

set_check_type(new_check_type)[source]

Modify the check type of the Tanner graph.

Parameters:: new_check_type (str) – New check type to be assigned to the Tanner graph. Must be either ‘X’, ‘Z’ or ‘check’.
Return type:: None

to_stabilizers(pauli_type=None)[source]

Convert the Classical Tanner graph to a list of stabilizers. Input pauli_type is required if check nodes have not been assigned a check_type. If check nodes have been assigned a check_type, the input pauli_type will override the assignment.

Parameters:: pauli_type (str | None) – Pauli type of the stabilizers, either ‘X’ or ‘Z’. If None, the check_type of the Tanner graph will be used. Default is None.
Returns:: stabilizers – List of stabilizers generated from the Classical Tanner graph.
Return type:: list[Stabilizer]

verify_input_graph(graph)[source]

Verify the input graph is a faithful representation of a Classical Tanner graph.

Parameters:: graph (nx.Graph) – Input graph to be verified.
Return type:: None

class loom.eka.tanner_graphs.TannerGraph(input)[source]

Bases: object

A class representing a Tanner graph.

The TannerGraph class stores a bipartite graph representation of a quantum CSS code. The graph is bipartite, with data nodes on one partition and check nodes on the other. The check nodes can be labelled with either ‘X’ or ‘Z’, associated with the type of stabilizers they represent and type of errors they check for, e.g. Z check nodes check for X errors and vice versa. If a networkx.Graph is given as input, the graph will go through a set of verifications to ensure its validity to represent the code. The input can also be a tuple of stabilizers, which need to satisfy the CSS condition, i.e. all must be either X- or Z-type, and the graph will be generated from them.

Parameters:: input (nx.Graph | tuple[Stabilizer] | ParityCheckMatrix) – Input graph or tuple of stabilizers to build the Tanner graph.

generate_graph_from_matrix(h_matrix)[source]

Generate Tanner graph from an input parity-check matrix. Note that, given our definition of TannerGraph, we only allow for ParityCheckMatrix objects describing CSS codes.

Parameters:: h_matrix (ParityCheckMatrix) – Parity-check matrix to generate the Tanner graph. Must be a CSS code.
Returns:: g – Tanner graph describing the code, as a networkx graph.
Return type:: nx.Graph

generate_graph_from_stabilizers(stabilizers)[source]

Generate Tanner graph from a tuple of stabilizers.

Parameters:: stabilizers (tuple[Stabilizer,...]) – Stabilizers to generate the Tanner graph.
Return type:: Graph

get_components()[source]

Compute the X and Z components of the Tanner graph, associated with X and Z stabilizers, respectively.

If the code contains only one type of stabilizer, the component of missing type will return None. The two of them cannot be None simultaneously.

Returns:: t_graph_x, t_graph_z – Tuple containing the X and Z tanner graphs induced by the data nodes and the respective set of check nodes.
Return type:: tuple[ClassicalTannerGraph | None, ClassicalTannerGraph | None]

relabelled_graph()[source]

Relabel a Tanner graph to identify nodes with tuples of integers which can later be converted into Stabilizers. The nodes are a assigned a single-element tuple with an integer index. The data nodes are counted first, followed by the X check nodes and the Z check nodes. The old node labels are stored in the node attributes under the key ‘original_node’.

The relabelled graph is guaranteed to allow for conversion into Stabilizers through the to_stabilizers() method.

Returns:: relabelled_tanner – Relabelled Tanner graph.
Return type:: TannerGraph

to_stabilizers()[source]

Convert Tanner graph to a list of stabilizers.

Return type:: list[Stabilizer]

verify_input_graph(graph)[source]

Verify the input graph is bipartite and that nodes are correctly labelled.

Parameters:: graph (nx.Graph) – Input graph to be verified.
Return type:: None

loom.eka.tanner_graphs.cartesian_product_tanner_graphs(t_graph_1, t_graph_2)[source]

Computes the Cartesian product of two ClassicalTannerGraphs Gi(Vi,Ci,Ei), where Vi is the set of data nodes, Ci is the set of check nodes and Ei is the set of edges. Each ClassicalTannerGraph is associated with a classical code. See arXiv:2109.14609 for a detailed description of the construction.

The cartesian product yields a TannerGraph G(V,C,E) describing a quantum CSS code. The nodes of the product TannerGraph are labelled via two coordinates (v1,v2), each inherited from each classical code. The set of data nodes V is built out of the union of the nodes resulting from the product of the data nodes (v1,v2) and of the check nodes (c1,c2) of each classical code. The set of check nodes C follows from the product of check and data nodes from each classical codes, i.e. (c1,v2) and (v1,c2). We assign X check nodes to be the first partition of check nodes and Z checks to be the second one. Edges are drawn between nodes (a1,a2) and (b1,b2), if either a2=b2 and G1 contains the edge (a1,b1) or a1=b1 and G2 contains the edge (a2,b2). The edges of product Tanner graphs are decorated with a cardinality label {N,`S`,`E`,`W`} according to the definitions introduced in arXiv:2109.14609.

Note that we assign the first and second input ClassicalTannerGraphs to X and Z checks respectively, regardless of their associated check_type attribute. Furthermore, we impose a single integer labelling of the nodes, of the form (i,) in the input ClassicalTannerGraphs. If the any of the inputs does not satisfy this requirement, we build a relabelled graph using the relabelled_graph() method of the ClassicalTannerGraph class. While this constraint is fundamental from the cartesian product perspective, it is required in order to decorate the edges with cardinal labels.

Parameters:

t_graph_1 (ClassicalTannerGraph) – Tanner graph of the first classical code.
t_graph_2 (ClassicalTannerGraph) – Tanner graph of the second classical code.

Returns:

tanner_product – Tanner graph from cartesian product of t_graph_1 and t_graph_2, describing the full HGP code.

Return type:

TannerGraph

loom.eka.tanner_graphs.verify_css_code_stabilizers(stabilizers)[source]

Verifies that the list of stabilizers define a valid CSS code.

Parameters:: stabilizers (list[Stabilizer] | tuple[Stabilizer]) – List of stabilizers defining a quantum CSS code.
Returns:: valid – If True, the stabilizers define a valid CSS code.
Return type:: bool