qlass.mitigation package

Submodules

qlass.mitigation.m3 module

class qlass.mitigation.m3.M3Mitigator(error_model: PhotonicErrorModel)

Bases: object

Implements the Matrix-Free Measurement Mitigation (M3) method for photonic experiments measuring Fock states.

mitigate(noisy_counts: dict[tuple[int, ...], int], tol: float = 1e-05) → dict[tuple[int, ...], float]

Performs the mitigation using a preconditioned GMRES iterative solver.

Parameters:

• noisy_counts (dict) – A dictionary mapping measured Fock state tuples to counts. e.g., {(1, 0, 1): 750, (1, 0, 0): 150}

• tol (float) – Tolerance for the GMRES solver.

Returns:

A dictionary mapping Fock state tuples to their mitigated probabilities.

Return type:

dict

class qlass.mitigation.m3.PhotonicErrorModel(num_modes: int, max_photons_per_mode: int = 2)

Bases: object

A simple error model for a multi-mode photonic system.

Assumes uncorrelated errors between modes. Errors are defined by a probability matrix for each mode: P[i, j] = probability of measuring ‘i’ photons when ‘j’ were present.

get_error_prob(mode_index: int, measured_photons: int, ideal_photons: int) → float

Returns P(measure | ideal) for a single mode.

set_mode_calibration(mode_index: int, prob_matrix: ndarray) → None

Sets the calibration data (error matrix) for a specific mode.

Parameters:

• mode_index (int) – The index of the mode.

• prob_matrix (np.ndarray) – A (max_photons+1) x (max_photons+1) matrix where P[i,j] is P(measure=i | ideal=j).

qlass.mitigation.zne module

class qlass.mitigation.zne.ZNEMitigator(executor: Callable[[...], float], scaling_factors: list[float], extrapolation_method: str = 'polynomial', polynomial_degree: int = 2, scale_keyword: str = 'noise_scale')

Bases: object

Zero Noise Extrapolation helper for expectation-value executors.

The wrapped executor is called once per scaling factor. It must return an expectation value and accept the noise scale through the keyword configured by scale_keyword.

extrapolate(expectation_values: Sequence[float]) → float

Extrapolate expectation values to the zero-noise limit.

Parameters:

expectation_values – Expectation values ordered like scaling_factors.

Returns:

Extrapolated zero-noise expectation value.

mitigate(params: ndarray, *executor_args: Any, **executor_kwargs: Any) → float

Run scaled executions and return the zero-noise extrapolated expectation value.

scaled_expectation_values(params: ndarray, *executor_args: Any, **executor_kwargs: Any) → list[float]

Execute the wrapped expectation-value executor at each noise scale.

Parameters:

• params – Variational parameters passed to the executor.

• *executor_args – Additional positional arguments forwarded to the executor.

• **executor_kwargs – Additional keyword arguments forwarded to the executor.

Returns:

Expectation values ordered like scaling_factors.

qlass.mitigation.zne.fold_global_interferometer(circuit: Circuit, scaling_factor: float) → Circuit

Fold a deterministic linear optical circuit as U (U† U)^n.

The folding factor must be an odd integer lambda = 2n + 1. The original circuit is copied first, then global U† and U blocks are appended for each fold. This keeps the effective unitary unchanged while increasing the deterministic interferometer depth before any post-selection layer.

Parameters:

• circuit – Perceval linear optical circuit to fold.

• scaling_factor – Odd integer noise scaling factor.

Returns:

Folded Perceval circuit with the same effective unitary.

qlass.mitigation.zne.scale_loss_config(config: HardwareConfig, scaling_factor: float) → HardwareConfig

Return a copy of config with photonic loss rates scaled in dB.

Only the component loss and waveguide loss fields are scaled. Source efficiency, detector efficiency, visibility, and other hardware parameters are preserved.

Parameters:

• config – Baseline hardware configuration.

• scaling_factor – Multiplicative loss scaling factor.

Returns:

New hardware configuration with scaled loss rates.

Module contents

class qlass.mitigation.M3Mitigator(error_model: PhotonicErrorModel)

Bases: object

Implements the Matrix-Free Measurement Mitigation (M3) method for photonic experiments measuring Fock states.

mitigate(noisy_counts: dict[tuple[int, ...], int], tol: float = 1e-05) → dict[tuple[int, ...], float]

Performs the mitigation using a preconditioned GMRES iterative solver.

Parameters:

• noisy_counts (dict) – A dictionary mapping measured Fock state tuples to counts. e.g., {(1, 0, 1): 750, (1, 0, 0): 150}

• tol (float) – Tolerance for the GMRES solver.

Returns:

A dictionary mapping Fock state tuples to their mitigated probabilities.

Return type:

dict

class qlass.mitigation.PhotonicErrorModel(num_modes: int, max_photons_per_mode: int = 2)

Bases: object

A simple error model for a multi-mode photonic system.

Assumes uncorrelated errors between modes. Errors are defined by a probability matrix for each mode: P[i, j] = probability of measuring ‘i’ photons when ‘j’ were present.

get_error_prob(mode_index: int, measured_photons: int, ideal_photons: int) → float

Returns P(measure | ideal) for a single mode.

set_mode_calibration(mode_index: int, prob_matrix: ndarray) → None

Sets the calibration data (error matrix) for a specific mode.

Parameters:

• mode_index (int) – The index of the mode.

• prob_matrix (np.ndarray) – A (max_photons+1) x (max_photons+1) matrix where P[i,j] is P(measure=i | ideal=j).

class qlass.mitigation.ZNEMitigator(executor: Callable[[...], float], scaling_factors: list[float], extrapolation_method: str = 'polynomial', polynomial_degree: int = 2, scale_keyword: str = 'noise_scale')

Bases: object

Zero Noise Extrapolation helper for expectation-value executors.

The wrapped executor is called once per scaling factor. It must return an expectation value and accept the noise scale through the keyword configured by scale_keyword.

extrapolate(expectation_values: Sequence[float]) → float

Extrapolate expectation values to the zero-noise limit.

Parameters:

expectation_values – Expectation values ordered like scaling_factors.

Returns:

Extrapolated zero-noise expectation value.

mitigate(params: ndarray, *executor_args: Any, **executor_kwargs: Any) → float

Run scaled executions and return the zero-noise extrapolated expectation value.

scaled_expectation_values(params: ndarray, *executor_args: Any, **executor_kwargs: Any) → list[float]

Execute the wrapped expectation-value executor at each noise scale.

Parameters:

• params – Variational parameters passed to the executor.

• *executor_args – Additional positional arguments forwarded to the executor.

• **executor_kwargs – Additional keyword arguments forwarded to the executor.

Returns:

Expectation values ordered like scaling_factors.

qlass.mitigation.fold_global_interferometer(circuit: Circuit, scaling_factor: float) → Circuit

Fold a deterministic linear optical circuit as U (U† U)^n.

The folding factor must be an odd integer lambda = 2n + 1. The original circuit is copied first, then global U† and U blocks are appended for each fold. This keeps the effective unitary unchanged while increasing the deterministic interferometer depth before any post-selection layer.

Parameters:

• circuit – Perceval linear optical circuit to fold.

• scaling_factor – Odd integer noise scaling factor.

Returns:

Folded Perceval circuit with the same effective unitary.

qlass.mitigation.scale_loss_config(config: HardwareConfig, scaling_factor: float) → HardwareConfig

Return a copy of config with photonic loss rates scaled in dB.

Only the component loss and waveguide loss fields are scaled. Source efficiency, detector efficiency, visibility, and other hardware parameters are preserved.

Parameters:

• config – Baseline hardware configuration.

• scaling_factor – Multiplicative loss scaling factor.

Returns:

New hardware configuration with scaled loss rates.