fiqci.ems.primitives.fiqci_estimator

A class that runs quantum circuits and calculates expectation values of observables with error mitigation techniques.

Classes

FiQCIEstimator(backend[, mitigation_level, ...])	FiQCIEstimator wraps a backend with built-in error mitigation (readout error mitigation via M3, zero-noise extrapolation) and computes expectation values of observables directly from circuits, eliminating the need for manual post-processing of measurement counts.
FiQCIEstimatorJobCollection(mitigated_jobs, ...)	Wrapper for job results with mitigated data.

class FiQCIEstimator(backend, mitigation_level=1, calibration_shots=1000, calibration_file=None)

Bases: object

FiQCIEstimator wraps a backend with built-in error mitigation (readout error mitigation via M3, zero-noise extrapolation) and computes expectation values of observables directly from circuits, eliminating the need for manual post-processing of measurement counts.

Mitigation levels:

• 0: No error mitigation (raw results)

• 1: Readout error mitigation using M3 (default)

• 2: Level 1 + TBD

• 3: Level 2 + zero-noise extrapolation (ZNE) with local folding and exponential extrapolation

Parameters:

• backend – An IQMBackendBase instance to wrap.

• mitigation_level – Level of error mitigation to apply (default: 1).

• calibration_shots – Number of shots to use for calibration circuits (default: 1000).

• calibration_file – Optional calibration file to use for readout error mitigation.

__init__(backend, mitigation_level=1, calibration_shots=1000, calibration_file=None)

property mitigator_options: dict[str, Any]

Get current mitigator settings.

run(circuits: QuantumCircuit | list[QuantumCircuit], observables: SparsePauliOp | list[SparsePauliOp], shots: int = 2048, **options) → FiQCIEstimatorJobCollection

Execute the given circuits on the backend and calculate expectation values for the provided observables.

Parameters:

• circuits – A QuantumCircuit or list of QuantumCircuits to execute.

• observables – A SparsePauliOp or list of SparsePauliOps representing the observables for which to calculate expectation values.

• shots – Number of shots to execute each circuit (default: 2048).

• **options – Additional options to pass to the backend’s run method.

Returns:

A FiQCIEstimatorJobCollection containing the jobs and calculated expectation values.

rem(enabled: bool, calibration_shots: int = 1000, calibration_file: str | None = None) → None

Set readout error mitigation settings for the estimator. This will configure the underlying backend’s readout error mitigation accordingly.

Parameters:

• enabled – Whether to enable readout error mitigation.

• calibration_shots – Number of shots to use for calibration circuits (default: 1000).

• calibration_file – Optional calibration file to use for readout error mitigation.

zne(enabled: bool, fold_gates: list | None = None, scale_factors: list[int] = [1, 3, 5], folding_method: str = 'local', extrapolation_method: str = 'exponential', extrapolation_degree: int | None = None)

Configure zero-noise extrapolation settings.

class FiQCIEstimatorJobCollection(mitigated_jobs, expectation_values, observables, raw_expectation_values)

Bases: object

Wrapper for job results with mitigated data.

This class wraps the original job and provides access to mitigated results.

__init__(mitigated_jobs, expectation_values, observables, raw_expectation_values) → None

Initialize the FiQCIEstimatorJobCollection with mitigated results.

Parameters:

• mitigated_jobs – List of original jobs that were run for each circuit/observable pair.

• expectation_values – List of mitigated expectation values corresponding to each job.

• observables – List of observables for which expectation values were calculated.

• raw_expectation_values – List of raw (unmitigated) expectation values before extrapolation

results()

Get all results for this estimator.

jobs()

Get all jobs ran for this estimator.

raw_expectation_values(index: int | None = None) → list[float]

Get the raw (unmitigated) expectation values before extrapolation.

expectation_values(index: int | None = None) → list[float]

Get the calculated expectation values.

observables(index: int | None = None) → SparsePauliOp

Get the observables for which expectation values were calculated.