QEC graph-state builder

graphqomb.qeccode provides the stabilizer-code representation and the Type I and Type II graph-state builders used by the QEC helper workflow.

Coordinate tuples are retained without restricting their dimensionality. The graph-state builder uses the first two qubit-coordinate components for the data plane and the first three explicitly supplied stabilizer-coordinate components for ancilla placement. An ancilla without an explicit coordinate is placed at the centroid of its connected data nodes. If that centroid’s XY projection is already occupied, the ancilla is moved in the data plane to a nearby candidate position with clearance from existing nodes. The clearance scales with the XY coordinate span so that it remains visible for large coordinate ranges; the temporal coordinate is left unchanged.

With data_as_io=True, the stabilizer-measurement unit has a separate, unmeasured output layer. Type I therefore has two measured data layers followed by an output layer. Type II uses three Y-measured layers for qubits with Y support, followed by an output layer; qubits without Y support retain the Type I two-measurement-layer layout. Ancilla support edges only touch measurement layers, and the output of one composed unit becomes the input of the next.

Both foliation variants use the local stabilizer-interaction order Z -> Y -> X on each shared data qubit. For a pair of stabilizers, the builder adds a CZ edge between their ancillas when an odd number of shared data-qubit pairs reverse that order: one qubit applies stabilizer a before b while the other applies b before a. Equal-Pauli overlaps have no strict order and do not contribute. The builder tracks only the parity of the two directions and considers only stabilizer pairs that share a data qubit, so sparse codes do not require an all-pairs stabilizer scan.

QEC Code object.

This module provides:

class graphqomb.qeccode.YFoliation[source]

Bases: Enum

Y-foliation graph-state builder variant.

class graphqomb.qeccode.StabilizerCode[source]

Bases: object

A stabilizer code.

__init__(stabilizer_matrix, *, stabilizer_coords=None, qubit_coords=None)[source]
property num_stabilizers: int

Number of stabilizers.

property num_qubits: int

Number of qubits.

class graphqomb.qeccode.StabilizerGraphStateBuildResult[source]

Bases: NamedTuple

Result of building a graph state from a stabilizer code.

graph is the constructed graph state with data and ancilla nodes, edges, coordinates, and measurement bases. data_nodes maps each (physical_qubit, data_layer) pair to its graph node id. ancilla_nodes maps each stabilizer row index to its ancilla graph node id.

graph: GraphState

Alias for field number 0

data_nodes: dict[tuple[int, int], int]

Alias for field number 1

ancilla_nodes: dict[int, int]

Alias for field number 2

static __new__(_cls, graph, data_nodes, ancilla_nodes)

Create new instance of StabilizerGraphStateBuildResult(graph, data_nodes, ancilla_nodes)

graphqomb.qeccode.build_graph_state(code, z_base=0, *, y_foliation=YFoliation.TYPE_I, data_as_io=False, qubit_indices=None)[source]

Build a graph-state unit from a stabilizer code.

Parameters:

  • code (StabilizerCode) – Stabilizer code to convert. The X support is connected to the upper data layer and the Z support is connected to the lower data layer.

  • z_base (int, optional) – Lower stabilizer-measurement data-layer index, by default 0. Type I uses two measurement layers; Type II uses three for Y support. When data_as_io is enabled, a separate output layer is appended.

  • y_foliation (YFoliation, optional) – Foliation variant. Type I measures each stabilizer ancilla in X when its row has an even number of Y supports, including zero, and in Y when the number is odd. Type II uses a three-node Y-measured data chain only for qubits that have an Hx=Hz=1 support in at least one stabilizer row. Both variants add a CZ between stabilizer ancillas when an odd number of shared-data-qubit pairs have opposite local interaction order under Z-before-Y-before-X ordering.

  • data_as_io (bool, optional) – Whether to register the first stabilizer-measurement data nodes as inputs and append separate unmeasured output nodes, by default False.

  • qubit_indices (collections.abc.Mapping[int, int] | None, optional) – Mapping from stabilizer-code qubit columns to graph qindices when data_as_io is enabled. If omitted, code qubit columns are used.

Returns:

Graph state and maps from stabilizer/data indices to graph nodes.

Return type:

StabilizerGraphStateBuildResult

Raises:

  • TypeError – If z_base is not an integer.

  • ValueError – If qubit_indices is invalid for the requested data I/O layout.