iqm.error_reduction_tools.readout_characterization.topologies.QPUTopology

class iqm.error_reduction_tools.readout_characterization.topologies.QPUTopology(name, num_qubits, positions=None, couplers=None, control_lines=None, adjacent_qubits=None)

Bases: object

Container for QPU topology information.

Parameters:

• name (str)

• num_qubits (int)

• positions (dict[int, tuple[int, int]] | None)

• couplers (list[tuple[str, str]] | None)

• control_lines (list[tuple[str, ...]] | None)

• adjacent_qubits (dict[str, list[str]] | None)

name

Name of the quantum computer (e.g., “emerald”, “garnet”)

num_qubits

Total number of qubits

positions

Dictionary mapping qubit number to (x, y) position for visualization. Populated when the topology is built via topology_from_qc(); empty by default.

couplers

List of tuples representing connected qubit pairs

control_lines

List of tuples grouping qubits by control/readout lines

adjacent_qubits

Optional dictionary mapping each qubit to its neighbors

Methods

_compute_adjacent_qubits()	Compute adjacent qubits from coupler list.
get_control_line_for_qubit(qubit)	Get the control line index for a given qubit.
get_coupler_pairs()	Return list of all coupler pairs (connected qubits).
get_neighbors(qubit)	Get neighboring qubits for a given qubit, excluding itself.
get_qubit_labels()	Return list of all qubit names (e.g., ['QB1', 'QB2', ...]).
get_qubits_in_control_line(line_index)	Get qubits belonging to a specific control/readout line.
parse_qubit_index(label)	Extract the numeric index from a qubit name.
sort_qubit_labels(labels)	Sort qubit labels by their numeric index.

get_qubit_labels()

Return list of all qubit names (e.g., [‘QB1’, ‘QB2’, …]).

Return type:

list[str]

static parse_qubit_index(label)

Extract the numeric index from a qubit name.

Parses names of the form "QBn" and returns the integer n.

Parameters:

label (str) – Qubit name (e.g., "QB12").

Returns:

The integer index embedded in the name.

Return type:

int

Example

>>> QPUTopology.parse_qubit_index("QB12")
12

static sort_qubit_labels(labels)

Sort qubit labels by their numeric index.

Example

>>> QPUTopology.sort_qubit_labels(["QB12", "QB4", "QB1"])
['QB1', 'QB4', 'QB12']

Parameters:

labels (list[str])

Return type:

list[str]

get_neighbors(qubit)

Get neighboring qubits for a given qubit, excluding itself.

Parameters:

qubit (str) – Qubit label (e.g., ‘QB1’).

Returns:

List of neighboring qubit labels, not including qubit.

Return type:

list[str]

Example

>>> topology.get_neighbors("QB5")
['QB1', 'QB4', 'QB6', 'QB11']

get_qubits_in_control_line(line_index)

Get qubits belonging to a specific control/readout line.

Parameters:

line_index (int) – Index of the control line (0-based).

Returns:

Tuple of qubit labels in that control line.

Raises:

ValueError – If no control lines are defined or line_index is out of range.

Return type:

tuple[str, …]

get_control_line_for_qubit(qubit)

Get the control line index for a given qubit.

Parameters:

qubit (str) – Qubit label (e.g., ‘QB1’).

Returns:

Index of the control line containing the qubit, or None if not found.

Return type:

int | None

get_coupler_pairs()

Return list of all coupler pairs (connected qubits).

Return type:

list[tuple[str, str]]