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).

adjacency()

coupling_map

e_1q

e_2q

e_ro

enabled_qubits

classmethod from_chip_characterization(chip, *, enabled_qubits=None)

Build a view from a ChipCharacterization.

enabled_qubits defaults to chip.available_qubits.

notes = ()

two_qubit_error(a, b)

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

Bases: object

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

edges

qubits

score

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.

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.

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.

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).