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)[source]

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 – Pre-loaded ReadoutCalibrationResult.

  • cache_path – Path to a cached calibration JSON file.

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

  • backend – Backend name used for cache lookup.

  • qubit – Qubit index or pair (for cache lookup).

Raises:

  • StaleCalibrationError – If calibration data exceeds max_age_hours.

  • FileNotFoundError – If cache_path does not exist.

apply(result)[source]

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

property calibration_result
mitigate_counts(counts)[source]

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 mapping outcome (int bitstring) → observed count.

Returns:

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

mitigate_probabilities(probs)[source]

Apply M3 mitigation to a probability dictionary.

Parameters:

probs – Dict mapping outcome → probability.

Returns:

Dict mapping outcome (int) → corrected probability.