loom.eka.block

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.block.Block(*args, **kwargs)

Bases: object

Block describing one or multiple logical qubits. It is defined by a code type, a list of stabilizers, two logical operators per logical qubit and a unique label. The block also contains information about how its syndromes are measured.

Parameters:

• stabilizers (tuple[Stabilizer, ...]) – The stabilizers that define the block.

• logical_x_operators (tuple[PauliOperator, ...]) – The logical X operators associated to the block.

• logical_z_operators (tuple[PauliOperator, ...]) – The logical Z operators associated to the block.

• syndrome_circuits (tuple[SyndromeCircuit, ...]) – The syndrome circuits with which the stabilizers of this block are measured. NOTE: Block does not have a check for distinct Syndrome Circuits(s)

• stabilizer_to_circuit (dict[str, str]) – A dictionary mapping stabilizer uuids to the uuids of the syndrome circuits that measure them.

• unique_label (str, optional) – Label for the block. It must be unique among all blocks in the initial Eka. If no label is provided, a unique label is generated automatically using the uuid module.

• skip_validation (bool, optional) –

  Boolean that allows to skip some validation of the Block. Default is False. The validation skipped are the following:

  • The qubits coordinates have the same dimension.

  • The stabilizers commute with each other.

  • The logical operators commute with each other.

  • The stabilizers commute with the logical operators.

  • The logical X and Z operators anti-commute at the same index and commute at different indices.

  • The number of qubits and stabilizers in the Block is compatible with the number of logical qubits.

• uuid (str, optional) – Unique identifier for the block. If no uuid is provided, a unique uuid is generated automatically using the uuid module.

__version__

Version of the Block class implementation.

Type:

str

property ancilla_qubits: tuple[tuple[int, ...], ...]

Return the set of all ancilla qubits in the block.

Returns:

A tuple of coordinates representing the ancilla qubits.

Return type:

tuple[tuple[int, …], …]

static blocks_no_overlap(blocks)

Check that blocks do no overlap, meaning that no blocks should be defined on the same data or ancilla qubits.

NOTE: We do not check that logical operators are not overlapping. In the Block class there is a validation checking that logical operators are defined on the same qubits as the stabilizers.

Return type:

tuple[Block, ...]

property bookkeeping: ndarray

Return the bookkeeping array of the reduced stabilizer array.

property bookkeeping_inv: ndarray

Return the inverted bookkeeping array of the reduced stabilizer array.

property data_qubits: tuple[tuple[int, ...], ...]

Return the set of all data qubits in the block.

Returns:

A tuple of coordinates representing the data qubits.

Return type:

tuple[tuple[int, …], …]

property destabarray: StabArray

Return the destabilizer array of the block. The operators in the destabarray anti-commute with exactly one stabilizer of the block each. In particular, the one with a matching index. They also commute with all of the logical operators. Note that the destabilizer is calculated using the reduced stabilizer array and not the original one.

classmethod from_blocks(blocks)

Combine multiple blocks into a single block. The blocks must not overlap with each other. The output block will be of code type “custom”.

Parameters:

blocks (tuple[Block, ...]) – The blocks to be combined.

Returns:

The combined block.

Return type:

Block

get_stabilizer_label(stabilizer_uuid)

Get the labels of a stabilizer, specified by its uuid.

Parameters:

stabilizer_uuid (str) – uuid of the stabilizer.

Returns:

Labels of the stabilizer.

Return type:

dict[str, tuple[int, …]]

logical_x_operators: tuple[PauliOperator, ...]

logical_z_operators: tuple[PauliOperator, ...]

property n_data_qubits: int

Return the number of data qubits in the block.

property n_irreducible_stabs: int

Return the number of irreducible stabilizers in the embedding, i.e. the minimum number of stabilizers needed to generate the code space.

property n_logical_qubits: int

Return the number of logical qubits in the block.

property original_stabarray: StabArray

Return the stabilizer array of the block as defined by the stabilizers.

property pauli_charges: dict[tuple[int, ...], str]

Calculate Pauli charges for all data qubits in the given Block. The Pauli charges are calculated from the stabilizers of the Block. For every data qubit, one counts how often the data qubit is included in stabilizers in the X, Y, and Z basis respectively. If it is included in an odd number of X, Y, or Z stabilizers, the data qubit has a Pauli charge of X, Y, or Z respectively. We only report a single Pauli charge where multiple charges are combined into one charge according to the product of Pauli matrices. E.g. if a data qubit has a Pauli charge of both X and Z, the combined Pauli charge is Y since Y=iXZ.

E.g. for a d=5 rotated surface code, plotting the Pauli charges on top of the data qubits would look like this (where we omitted plotting data qubits with no Pauli charge):

Y -- X -- X -- X -- Y
|    |    |    |    |
Z --   --   --   -- Z
|    |    |    |    |
Z --   --   --   -- Z
|    |    |    |    |
Z --   --   --   -- Z
|    |    |    |    |
Y -- X -- X -- X -- Y

In this example of the rotated surface code, the four logical corners have Pauli charge Y, and there are two boundaries with Pauli charge X and two with Pauli charge Z. The bulk data qubits have no Pauli charge. No Pauli charge is represented by “_” in the output of this function but we omitted plotting these in the example above.

Returns:

Dict mapping data qubits to their pauli charges (“_”, “X”, “Y”, or “Z”)

Return type:

dict[tuple[int, …], str]

property qubits: tuple[tuple[int, ...], ...]

Return the set of all qubits in the block.

Returns:

A tuple of coordinates representing all qubits in the block.

Return type:

tuple[tuple[int, …], …]

property reduced_bookkeeping: ndarray

Return the reduced bookkeeping array of the reduced stabilizer array. This entails slicing out the last rows of the bookkeeping array that should cancel out and give a zero row.

property reduced_bookkeeping_inv: ndarray

Return the inverted reduced bookkeeping array of the reduced stabilizer array. This entails slicing out the last trivial columns of the inverted bookkeeping array that correspond to the zero rows of the reduced StabArray.

property reduced_stabarray: StabArray

Return the reduced stabilizer array of the embedding.

property reduced_stabarray_with_bookkeeping: tuple[StabArray, ndarray]

Return the reduced stabilizer array of the embedding with bookkeeping.

rename(name)

Return a copy of the Block with the new name.

Return type:

Block

shift(position, new_label=None)

Return a copy of the Block where all qubit coordinates are shifted by a given position.

Parameters:

• position (tuple[int, ...]) – Vector by which the block should be shifted

• new_label (str | None, optional) – New label for the block. If None, the same label is used.

Returns:

A new Block with the shifted qubit coordinates.

Return type:

Block

skip_validation: bool = False

stabilizer_to_circuit: dict[str, str] = FieldInfo(annotation=dict[str, str], required=False, default_factory=dict, validate_default=True)

stabilizers: tuple[Stabilizer, ...]

property stabilizers_labels: dict[str, dict[str, tuple[int, ...]]]

Builds a dictionary associating stabilizers, via their uuid, with a set of labels defined through a dictionary. Inside Block, this is generically populated with the space coordinates of the stabilizer check, corresponding to the ancilla which measures each stabilizer.

This functionality can be leveraged to later provide these labels to Syndromes and Detectors associated with a given Stabilizer.

Returns:

Dictionary associating stabilizer uuids with their labels.

Return type:

dict[str, dict[str, tuple[int, …]]]

syndrome_circuits: tuple[SyndromeCircuit, ...] = FieldInfo(annotation=tuple[SyndromeCircuit, ...], required=False, default_factory=tuple, validate_default=True)

unique_label: str = FieldInfo(annotation=str, required=False, default_factory=<lambda>)

uuid: str = FieldInfo(annotation=str, required=False, default_factory=<lambda>, validate_default=True)

property x_log_stabarray: StabArray

Return the X stabilizer array of the logical operator set.

property z_log_stabarray: StabArray

Return the Z stabilizer array of the logical operator set.