iqm.error_reduction_tools.utils.circuit_utils.TwirledCircuit

class iqm.error_reduction_tools.utils.circuit_utils.TwirledCircuit(operations)

Bases: object

A quantum circuit wrapper that supports readout twirling and gate randomization.

This class serves as a mutable working representation for building and manipulating quantum circuits. It tracks single-qubit gates, measurements, and readout twirling state. Use to_circuit(name) to convert to the immutable Circuit.

Note

We intentionally do not store a Circuit internally. Circuit.instructions is an immutable tuple, which would be rebuilt on every append_operation call. Instead, operations is kept as a mutable list[CircuitOperation] throughout circuit construction, and converted to Circuit on demand via to_circuit().

Parameters:

operations (list[CircuitOperation])

operations

List of operations in the circuit.

rot_dict

Dictionary for readout twirling rotations, if applied.

sqg_counter

Counter for single-qubit gates per qubit.

measured_qubits

List of qubits that are measured.

active_qubits

List of all qubits involved in the circuit.

Methods

append_operation(operation)	Append a deep copy of the operation to the circuit and update basic analysis.
basic_analysis()	Perform basic analysis on quantum circuit operations.
get_rot_char_per_meas_key()	Get rotation character per measurement key due to readout twirling.
to_circuit(name)	Convert to an immutable Circuit.

basic_analysis()

Perform basic analysis on quantum circuit operations.

This method analyzes the circuit operations to extract information about single-qubit gates, measurements, and active qubits. It also validates that no mid-circuit measurements are present.

Raises:

ValueError – If mid-circuit measurements are detected (when any qubit is measured more than once).

Return type:

None

Note

This method populates the following instance attributes:

• sqg_counter: Dictionary mapping qubit identifiers to the count of ‘prx’ operations performed on each qubit.

• measured_qubits: List of qubit identifiers that have measurement operations.

• active_qubits: List of all qubit identifiers that appear in any operation.

The method iterates through all operations in the circuit and:

1. Counts ‘prx’ (parametric rotation) operations per qubit

2. Counts measurement operations per qubit

3. Collects all qubits involved in any operation

4. Validates that no qubit is measured more than once

append_operation(operation)

Append a deep copy of the operation to the circuit and update basic analysis.

A deep copy is made to ensure that no external references to the operation are retained, preventing shared-state bugs when the same source circuit is randomized multiple times.

Parameters:

operation (CircuitOperation)

Return type:

None

get_rot_char_per_meas_key()

Get rotation character per measurement key due to readout twirling.

Returns:

Dictionary mapping measurement keys to rotation characters (‘I’ or ‘X’).

Return type:

dict[str, str]

to_circuit(name)

Convert to an immutable Circuit.

Parameters:

name (str) – Name to assign to the circuit.

Returns:

A Circuit with the current operations as instructions.

Return type:

Circuit