loom.validator.circuit_validation

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.

loom.validator.circuit_validation.find_final_swaps(input_all_qubit_to_channel_map, output_data_qubit_to_channel_map)[source]

Find the SWAP operations to bring the final qubits into the correct position.

Parameters:

  • input_all_qubit_to_channel_map (dict[int, Channel]) – A dictionary matching all qubit indices with their Channel at the beginning of the circuit

  • output_data_qubit_to_channel_map (dict[int, Channel]) – A dictionary matching data qubit indices with their Channel at the end of the circuit.

Returns:

A list of SWAP operations to bring the final qubits into the correct position.

Return type:

list[SWAP]

loom.validator.circuit_validation.get_validator_cliffordsim_operations(circuit, input_block, output_block)[source]

Generate a list of cliffordsim operations from a circuit and some input and output data qubit to channel maps. The qubit channels of the circuit that are not in the input map are considered to be auxiliary qubits and initialized in state \(\ket{0}\). The qubit channels of the output are swapped into the correct position as dictated by the output map. The qubit channels that are not in the output map are deleted at the end of the circuit.

Parameters:

  • circuit (Circuit) – The base circuit to be converted to cliffordsim instructions.

  • input_block (Block) – The Block object containing the input stabilizers and logical operators.

  • output_block (Block) – The Block object containing the output stabilizers and logical operators.

Returns:

A tuple of cliffordsim operations to be executed.

Return type:

tuple[loom.cliffordsim.operations.base_operation.Operation, …]

loom.validator.circuit_validation.is_circuit_valid(circuit, input_block, output_block, output_stabilizers_parity, output_stabilizers_with_any_value, logical_state_transformations_with_parity, logical_state_transformations, measurement_to_input_stabilizer_map, seed=None)[source]

Tests if a QEC circuit is valid, ie if it meets the criteria:

  • The input code is transformed into the output code

    • If any generators are allowed to have any value, positive or negative, the output_stabilizers_with_any_value list should contain them

    • If the generators are not allowed to have any value, but their parity is specified, the output_stabilizers_parity list should contain the classical channels and integer constant flips(0 or 1) that are applied to them.

  • The logical_state_transformations_with_parity dictionary should contain:

    • The input logical state as the key

    • A tuple as the value where:

      • The first element is the output logical state

      • The second is a dictionary where:

        • The keys are the logical operator indices

        • The values are lists of strings or integers (0 or 1) that represent the classical channels and parity flips applied to the logical operators.

  • The input code stabilizers are measured correctly

Parameters:

  • circuit (Circuit) – The QEC circuit.

  • input_block (Block | tuple[Block, ...]) – The input Block object(s) corresponding to the input code.

  • output_block (Block | tuple[Block, ...]) – The output Block object(s) corresponding to the output code.

  • output_stabilizers_parity (dict[Stabilizer, tuple[str | int, ...]]) – Dictionary where the keys are output stabilizers and the value is the expected parity. The parity is represented as a tuple of strings and integers (0 or 1), where the strings are the labels of the classical bits where a result is stored at runtime, and the integers are the constant parity changes. The final parity is calculated by XORing the values of all of these bits.

  • output_stabilizers_with_any_value (list[Stabilizer]) – List of output code generators that are allowed to have any value in the end of the circuit.

  • logical_state_transformations_with_parity (dict[) – LogicalState, tuple[LogicalState, dict[int, tuple[str | int, …]]],

  • ] – Dictionary where the keys are the input logical states and the values are tuples containing the output logical state and a dictionary of parity flips that correspond to each logical operator. The keys of the dictionary are the logical operator indices, and the values are lists of strings or integers (0 or 1) that represent the classical channels and parity flips applied to the logical operators.

  • logical_state_transformations (list[tuple[LogicalState, tuple[LogicalState, ...]]])

  • list[tuple[LogicalState – List of tuples where each tuple contains the transformation of the logical operators from the input state to the output state(s) that will be checked.

  • tuple[LogicalState – List of tuples where each tuple contains the transformation of the logical operators from the input state to the output state(s) that will be checked.

  • ...]]] – List of tuples where each tuple contains the transformation of the logical operators from the input state to the output state(s) that will be checked.

  • measurement_to_input_stabilizer_map (dict[str, Stabilizer]) – Dictionary matching the classical channel name of a measurement operation with a stabilizer in the input code.

  • seed (int, optional) – The seed for the cliffordsim engine, by default None. None means that the cliffordsim engine will not be seeded and will use a random seed.

Returns:

The result of the checks.

Return type:

DebugData

loom.validator.circuit_validation.validate_logical_state_transformations(input_block, output_block, logical_state_transformations)[source]

Validate the logical_state_transformations input and raise an appropriate error if invalid.

Parameters:

  • input_block (Block) – The input Block object corresponding to the input code.

  • output_block (Block) – The output Block object corresponding to the output code.

  • logical_state_transformations (list[tuple[LogicalState, tuple[LogicalState, ...]]]) – List of tuples where each tuple contains the transformation of the logical operators from the input state to the output state(s) that will be checked.

Return type:

None

loom.validator.circuit_validation.validate_logical_state_transformations_with_parity(circuit, input_block, output_block, logical_state_transformations_with_parity)[source]

Validate the logical_state_transformations_with_parity input and raise an appropriate error if invalid.

Parameters:

  • circuit (Circuit) – The QEC circuit.

  • input_block (Block) – The input Block object corresponding to the input code.

  • output_block (Block) – The output Block object corresponding to the output code.

  • logical_state_transformations_with_parity (dict[) – LogicalState, tuple[LogicalState, dict[int, tuple[str | int, …] | list[str | int]]],

  • ] – Dictionary where the keys are the input logical states and the values are tuples containing the output logical state and a dictionary of parity flips that correspond to each logical operator. The keys of the dictionary are the logical operator indices, and the values are lists of strings or integers (0 or 1) that represent the classical channels and parity flips applied to the logical operators.

Return type:

None

loom.validator.circuit_validation.validate_measurement_to_input_stabilizer_map(circuit, input_block, measurement_to_input_stabilizer_map)[source]

Validate the measurement_to_input_stabilizer_map input and raise an appropriate error if invalid.

Parameters:

  • circuit (Circuit) – The QEC circuit.

  • input_block (Block) – The input Block object corresponding to the input code.

  • measurement_to_input_stabilizer_map (dict[str, Stabilizer]) – Dictionary matching the classical channel name of a measurement operation with a stabilizer in the input code.

Return type:

None

loom.validator.circuit_validation.validate_output_stabilizers_parity(circuit, output_block, output_stabilizers_parity)[source]

Validate the output_stabilizers_parity input and raise an appropriate error if invalid.

Parameters:

  • circuit (Circuit) – The QEC circuit.

  • output_block (Block) – The output Block object corresponding to the output code.

  • output_stabilizers_parity (dict[Stabilizer, tuple[str | int, ...]]) – Dictionary where the keys are output stabilizers and the value is the expected parity. The parity is represented as a tuple of strings and integers (0 or 1), where the strings are the labels of the classical bits where a result is stored at runtime, and the integers are the constant parity changes. The final parity is calculated by XORing the values of all of these bits.

Return type:

None

loom.validator.circuit_validation.validate_output_stabilizers_with_any_value(output_block, output_stabilizers_with_any_value)[source]

Validate the output_stabilizers_with_any_value input and raise an appropriate error if invalid.

Parameters:

  • output_block (Block) – The output Block object corresponding to the output code.

  • output_stabilizers_with_any_value (list[Stabilizer]) – List of output code generators that are allowed to have any value in the end of the circuit.

Return type:

None