uniqc.qem.m3 module

M3 readout error mitigator.

Provides confusion-matrix-based readout error mitigation with TTL-based calibration freshness enforcement.

class uniqc.qem.m3.M3Mitigator(calibration_result=None, cache_path=None, max_age_hours=24.0, backend='dummy:local:simulator', qubit=None, cache_dir=None)

Bases: object

M3 (Matrix Misassignment Mitigation) readout error mitigator.

Uses a calibration confusion matrix to correct measurement outcomes via linear inversion. The calibration data can be provided directly or loaded from the calibration cache.

Parameters:

• calibration_result (Any | None) – Pre-loaded ReadoutCalibrationResult.

• cache_path (str | pathlib.Path | None) – Path to a cached calibration JSON file.

• max_age_hours (float) – Maximum acceptable age of calibration data in hours. If the cached data is older, StaleCalibrationError is raised.

• backend (str) – Backend name used for cache lookup.

• qubit (int | tuple[int, int] | None) – Qubit index or pair (for cache lookup).

• cache_dir (str | pathlib.Path | None)

Raises:

• StaleCalibrationError – If calibration data exceeds max_age_hours.

• FileNotFoundError – If cache_path does not exist.

apply(result)

Apply mitigation to a UnifiedResult and return a new one.

This is the recommended pipeline-style API: call M3Mitigator(...).apply(result) and feed the returned object straight back into any uniqc workflow that expects a UnifiedResult.

Parameters:

result (Any) – A uniqc.backend_adapter.task.result_types.UnifiedResult produced by submit_task/wait_for_result/simulate.

Returns:

A new UnifiedResult whose counts/probabilities are mitigated. shots, platform, task_id and metadata are preserved; the original is kept as raw_result.

Return type:

Any

property calibration_result: Any

mitigate_counts(counts)

Apply M3 mitigation to measurement counts.

Uses linear inversion: n_corrected = C⁻¹ · n_obs. The result is normalized so the total counts are preserved.

Parameters:

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

Returns:

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

Return type:

dict[int, float]

mitigate_probabilities(probs)

Apply M3 mitigation to a probability dictionary.

Parameters:

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

Returns:

Dict mapping outcome (int) → corrected probability.

Return type:

dict[int, float]