ReadoutMitigation#

class qiskit_calculquebec.mitigation.readout.ReadoutMitigation(backend, method: str = 'm3', iter_threshold: int = 4096)#

Bases: object

Readout Error Mitigation (REM) for MonarQ.

Calibration data (P(0|0) and P(1|1) per qubit) is loaded from the Anyon benchmark via the Calcul Québec API — no calibration circuits are submitted to the hardware.

Parameters:

backend (MonarQBackend) – Calcul Québec backend initialized with an ApiClient.
method (str) – 'matrix' (mitiq, exact, limited to ~12 qubits) or 'm3' (mthree, scalable to 24+ qubits). Default: 'm3'.
iter_threshold (int) – (M3 only) Number of distinct bitstrings above which the iterative solver (GMRES) is preferred over the direct solver. Default: 4096.

Examples

M3 method (recommended for MonarQ 24 qubits):

>>> mit = ReadoutMitigation(backend, method='m3')
>>> mit.cals_from_system()
>>> quasi = mit.apply_correction(counts_raw, qubits=physical_qubits)
>>> counts_mit = {k: int(round(v * shots))
...               for k, v in quasi.nearest_probability_distribution().items()
...               if round(v * shots) > 0}

Matrix method (mitiq-compatible, small circuits):

>>> mit = ReadoutMitigation(backend, method='matrix')
>>> mit.cals_from_system()
>>> counts_mit = mit.apply_correction(counts_raw, qubits=physical_qubits)

Methods

`apply_correction`(counts, qubits, **kwargs)	Apply REM correction to raw measurement counts.
`cals_from_matrices`(matrices)	Initialize calibration from a list of 2×2 NumPy matrices.
`cals_from_system`([qubits])	Load P(0\|0) and P(1\|1) from the Anyon benchmark (Calcul Québec API).
`get_confusion_matrix`(qubits)	Return the direct (non-inverted) confusion matrix for the given qubits.
`get_inv_confusion_matrix`(qubits)	Return the inverse confusion matrix (tensor product of pseudo-inverses).
`readout_fidelity`([qubits])	Return the readout fidelity (P(0\|0), P(1\|1), mean) per qubit.
`reduced_cal_matrix`(counts, qubits[, distance])	Return the reduced calibration sub-matrix for the observed bitstrings (M3).

apply_correction(counts, qubits: list[int], **kwargs)#

Apply REM correction to raw measurement counts.

Parameters:

counts (dict) – Qiskit counts dict (little-endian bitstrings → shot count).
qubits (list[int]) – Physical qubits corresponding to the bitstring bits, in the same order as the bits in the bitstring.
**kwargs –
Additional parameters passed to the underlying method.

For method=’m3’:
- distance (int | None): max Hamming distance, default min(n, 3).
- solver (str): 'auto', 'direct', or 'iterative'.
- max_iter (int): max GMRES iterations, default 25.
- tol (float): GMRES tolerance, default 1e-4.
- details (bool): also return solver metrics.

Returns:

Corrected counts (same format as input) for: method='matrix', or QuasiDistribution (mthree) for method='m3'. Convert the latter with quasi.nearest_probability_distribution().

Return type:

dict

Raises:

RuntimeError – If calibration has not been loaded, or if a requested qubit is not calibrated.

cals_from_matrices(matrices: list)#

Initialize calibration from a list of 2×2 NumPy matrices.

Parameters:: matrices (list[np.ndarray | None]) – List of length num_qubits. Use None for uncalibrated qubits.

cals_from_system(qubits: list[int] | None = None)#

Load P(0|0) and P(1|1) from the Anyon benchmark (Calcul Québec API).

No calibration circuits are submitted to the hardware.

Parameters:: qubits (list[int] | None) – Physical qubits to calibrate. None → all qubits on the backend.

get_confusion_matrix(qubits: list[int]) → ndarray#

Return the direct (non-inverted) confusion matrix for the given qubits.

Useful for visualization (e.g. heatmap).

Parameters:: qubits (list[int]) – Physical qubits to include.
Returns:: Tensor product of local calibration matrices.
Return type:: np.ndarray
Raises:: RuntimeError – If calibration has not been loaded.

get_inv_confusion_matrix(qubits: list[int]) → ndarray#

Return the inverse confusion matrix (tensor product of pseudo-inverses).

Useful for visualization or reuse in custom correction pipelines.

Parameters:

qubits (list[int]) – Physical qubits to include.

Returns:

Tensor product of pseudo-inverse local calibration: matrices.

Return type:

np.ndarray

Raises:

RuntimeError – If calibration has not been loaded.

readout_fidelity(qubits: list[int] | None = None) → list#

Return the readout fidelity (P(0|0), P(1|1), mean) per qubit.

Parameters:

qubits (list[int] | None) – Qubits to query. None → all qubits.

Returns:

Each entry is: {'p00': float, 'p11': float, 'mean': float}, or None if the qubit is not calibrated.

Return type:

list[dict | None]

Raises:

RuntimeError – If calibration has not been loaded yet.

reduced_cal_matrix(counts, qubits, distance=None)#

Return the reduced calibration sub-matrix for the observed bitstrings (M3).

Parameters:

counts (dict) – Measurement counts.
qubits (list[int]) – Physical qubits.
distance (int | None) – Max Hamming distance. None → min(n, 3).

Returns:

Reduced calibration matrix and bitstring: index mapping.

Return type:

tuple[np.ndarray, dict]

ReadoutMitigation

Contents

ReadoutMitigation#

Methods