uniqc.qem.readout_em module

Unified readout error mitigation.

Provides a single interface for applying readout EM to measurement counts, automatically dispatching to 1-qubit or 2-qubit calibration as needed. Internally calls the ReadoutCalibrator from uniqc.calibration.readout.

class uniqc.qem.readout_em.ReadoutEM(adapter, max_age_hours=24.0, cache_dir=None, shots=1000)

Bases: object

Unified readout error mitigator.

This is the primary interface for applying readout EM to measurement results. It wraps a ReadoutCalibrator and provides mitigation for arbitrary measurement counts.

The mitigator automatically selects: - 1-qubit calibration for single-qubit measurement results - 2-qubit calibration for two-qubit joint measurement results - Per-qubit 1-qubit calibration (sequential approximation) for >2 qubits

Parameters:

• adapter (QuantumAdapter) – A QuantumAdapter instance for running calibration circuits.

• max_age_hours (float) – Maximum acceptable age of cached calibration data in hours.

• cache_dir (str | None) – Directory for calibration cache. Defaults to ~/.uniqc/calibration_cache/.

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

apply(result, measured_qubits=None)

Apply readout mitigation to a UnifiedResult.

Pipeline-style API: returns a new UnifiedResult ready to be consumed by the rest of uniqc. measured_qubits defaults to list(range(width)) inferred from the bitstring length.

Parameters:

• result (Any)

• measured_qubits (list[int] | None)

Return type:

Any

mitigate_counts(counts, measured_qubits)

Apply readout EM to measurement counts.

Automatically dispatches to the appropriate calibration: - 1 qubit → 1q calibrator - 2 qubits → 2q calibrator - N>2 qubits → sequential per-qubit 1q mitigation

Parameters:

• counts (dict[int, int]) – Dict mapping outcome (int) → observed count.

• measured_qubits (list[int]) – List of qubit indices that were measured. The order matters for the bitstring encoding.

Returns:

Dict mapping outcome → corrected count (float, total preserved).

Return type:

dict[int, float]

mitigate_probabilities(probs, measured_qubits)

Apply readout EM to a probability dictionary.

Parameters:

• probs (dict[int, float] | dict[str, float]) – Dict mapping outcome → probability.

• measured_qubits (list[int]) – List of measured qubit indices.

Returns:

Dict mapping outcome (int) → corrected probability.

Return type:

dict[int, float]