uniqc.calibration.readout.calibrator module

Readout calibrator for single-qubit and two-qubit measurement errors.

Generates calibration circuits for all computational basis states, executes them on the given adapter, builds confusion matrices, and saves results to the calibration cache.

class uniqc.calibration.readout.calibrator.ReadoutCalibrator(adapter, shots=1000, cache_dir=None, timeout=300.0, poll_interval=2.0)

Bases: object

Calibrates readout (measurement) errors for 1-qubit and 2-qubit systems.

For 1-qubit: runs two circuits to build a 2×2 confusion matrix:

[[P(0|0), P(1|0)],

[P(0|1), P(1|1)]]

For 2-qubit: runs four circuits to build a 4×4 confusion matrix:

rows = measured outcome (00,01,10,11) cols = prepared state (00,01,10,11)

Results are automatically saved to ~/.uniqc/calibration_cache/ with an ISO-8601 calibrated_at timestamp.

Parameters:

• adapter (QuantumAdapter) – A QuantumAdapter instance (e.g. DummyAdapter). Must implement submit and query methods.

• shots (int) – Number of measurement shots per calibration circuit.

• cache_dir (str | pathlib.Path | None) – Directory to save calibration results. Defaults to ~/.uniqc/calibration_cache/.

• timeout (float)

• poll_interval (float)

calibrate_1q(qubit)

Calibrate readout for a single qubit.

Parameters:

qubit (int) – Qubit index.

Returns:

qubit, type="readout_1q", confusion_matrix (tuple of tuples), assignment_fidelity, calibrated_at, backend. Supports dict-like access (result["confusion_matrix"]) for backward compatibility.

Return type:

A ReadoutCalibrationResult dataclass with fields

calibrate_2q(qubit_u, qubit_v)

Calibrate joint readout for a two-qubit pair.

Parameters:

• qubit_u (int) – First qubit index.

• qubit_v (int) – Second qubit index.

Returns:

qubit (tuple), type="readout_2q", confusion_matrix (tuple of tuples), assignment_fidelity, calibrated_at, backend. Supports dict-like access (result["confusion_matrix"]) for backward compatibility.

Return type:

A ReadoutCalibrationResult dataclass with fields

calibrate_pairs(pairs)

Calibrate joint readout for multiple qubit pairs.

Parameters:

pairs (list[tuple[int, int]]) – List of (qubit_u, qubit_v) tuples.

Returns:

Dict mapping (u, v) → ReadoutCalibrationResult.

Return type:

dict[tuple[int, int], ReadoutCalibrationResult]

calibrate_qubits(qubits)

Calibrate readout for multiple single qubits.

Parameters:

qubits (list[int]) – List of qubit indices.

Returns:

Dict mapping qubit index → ReadoutCalibrationResult.

Return type:

dict[int, ReadoutCalibrationResult]