uniqc.calibration.xeb.topology module

Chip topology utilities for parallel-CZ XEB calibration.

These helpers wrap a uniqc.cli.chip_info.ChipCharacterization into a lightweight view (per-qubit / per-pair fidelities + adjacency) that the parallel-CZ XEB workflow uses to pick a region and build parallel CZ patterns.

The primitives here are generic — no UU15 or paper-specific logic.

Public API

• ChipTopologyView — adapter over ChipCharacterization

• Region — connected qubit subset + induced edges

• pick_region() — fidelity-weighted greedy seed-and-grow

• pick_chain_region() — best chord-free linear chain

• parallel_patterns() — DSatur edge-coloring of a list of edges

• three_color_chip() — chip-wide partition into ≤max_K matchings

class uniqc.calibration.xeb.topology.ChipTopologyView(enabled_qubits, coupling_map, e_1q, e_2q, e_ro, notes=())

Bases: object

Lightweight per-qubit / per-pair fidelity view over a chip.

e_1q[q], e_ro[q] and e_2q[(min(a,b), max(a,b))] are error rates in [0, 1]. Missing entries fall back to safe defaults (1e-3 single-qubit, 1e-2 readout, chip-wide 2q-median).

Parameters:

• enabled_qubits (tuple[int, ...])

• coupling_map (tuple[tuple[int, int], ...])

• e_1q (dict[int, float])

• e_2q (dict[tuple[int, int], float])

• e_ro (dict[int, float])

• notes (tuple[str, ...])

adjacency()

Return type:

dict[int, set[int]]

coupling_map: tuple[tuple[int, int], ...]

e_1q: dict[int, float]

e_2q: dict[tuple[int, int], float]

e_ro: dict[int, float]

enabled_qubits: tuple[int, ...]

classmethod from_chip_characterization(chip, *, enabled_qubits=None)

Build a view from a ChipCharacterization.

enabled_qubits defaults to chip.available_qubits.

Parameters:

• chip (ChipCharacterization)

• enabled_qubits (Iterable[int] | None)

Return type:

ChipTopologyView

notes: tuple[str, ...] = ()

two_qubit_error(a, b)

Parameters:

• a (int)

• b (int)

Return type:

float

class uniqc.calibration.xeb.topology.Region(qubits, edges, score)

Bases: object

A connected induced subgraph of a chip’s coupling graph.

Parameters:

• qubits (tuple[int, ...])

• edges (tuple[tuple[int, int], ...])

• score (float)

edges: tuple[tuple[int, int], ...]

qubits: tuple[int, ...]

score: float

uniqc.calibration.xeb.topology.parallel_patterns(edges, *, max_K=8)

DSatur edge-coloring of edges into edge-disjoint matchings.

Returns a tuple of patterns (P_0, ..., P_{K-1}). Each pattern is a tuple of (a, b) edges with no qubit appearing twice in the same pattern. If the maximum vertex degree exceeds max_K the coloring may spill an edge into a non-empty class — increase max_K to Δ + 1 to avoid that.

Parameters:

• edges (Sequence[tuple[int, int]])

• max_K (int)

Return type:

tuple[tuple[tuple[int, int], …], …]

uniqc.calibration.xeb.topology.pick_chain_region(view, length, *, forced_qubits=None)

Best chord-free linear chain q0 — q1 — … — q_{L-1} of length length.

A “chord-free” chain has only the consecutive edges in its induced subgraph (no shortcuts). Useful for MPS-friendly experiments.

If forced_qubits is given, validate it as a chain and return it directly. Otherwise enumerate simple paths.

Parameters:

• view (ChipTopologyView)

• length (int)

• forced_qubits (Iterable[int] | None)

Return type:

Region

uniqc.calibration.xeb.topology.pick_region(view, n, *, seed=0)

Select n connected qubits maximising Σ log f_v + Σ log f_e.

Uses greedy seed-and-grow over the highest-fidelity vertex, then a seed-deterministic SA polish. Raises if no connected region of the requested size exists.

Parameters:

• view (ChipTopologyView)

• n (int)

• seed (int)

Return type:

Region

uniqc.calibration.xeb.topology.three_color_chip(view, *, max_K=3)

Edge-color the chip’s coupling map into ≤max_K parallel patterns.

Most superconducting chips have max-degree ≤ 3, so max_K = 3 is sufficient. For higher-degree chips, pass max_K = Δ + 1 (where Δ is the max vertex degree).

Parameters:

• view (ChipTopologyView)

• max_K (int)

Return type:

tuple[tuple[tuple[int, int], …], …]