fiqci.ems.primitives.fiqci_estimator

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.

FiQCIEstimatorJob(job, compute_fn, observables)

Lazy wrapper around the backend job that produced an estimator's results.
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 + dynamical decoupling (DD)

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

total_circuits_generated(num_base_circuits: int, observables: SparsePauliOp | list[SparsePauliOp], detailed: bool = False) → int | dict[str, int]#

Calculate total circuits generated for a given number of base circuits and observables.

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

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

  • max_batch_size – Maximum number of circuits to send in a single backend job. All measurement-basis subcircuits (across all circuit/observable pairs and ZNE scale factors) are flattened and split into batches of this size (default: 100).

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

Returns:

A FiQCIEstimatorJob 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.

dd(enabled: bool, gate_sequences: list[tuple[int, str | list[tuple[float, float]], str]] | None = None) → None#

Set dynamical decoupling settings for the estimator. This will configure the underlying backend’s dynamical decoupling accordingly.

Parameters:

  • enabled – Whether to enable dynamical decoupling.

  • gate_sequences – List of (threshold_length, sequence, strategy) tuples defining DD behavior. See build_dd_options for details on each field.

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.

pauli_twirl(enabled: bool, num_twirls: int = 10, gates_to_twirl: list | None = None) → None#

Configure Pauli twirling settings for the estimator.

class FiQCIEstimatorJob(job, compute_fn: Callable[[], tuple[list, list]], observables)#

Bases: object

Lazy wrapper around the backend job that produced an estimator’s results.

The estimator flattens all per-pair measurement-basis circuits into one backend call, so there is exactly one underlying job (which may itself batch internally — see BatchedJob). This class is returned immediately from FiQCIEstimator.run(); the expectation-value computation is deferred until expectation_values() / raw_expectation_values() is first called (it fetches the underlying results and computes once, then caches). Polling the underlying job (status/done/job_ids) works before the values are computed.

__init__(job, compute_fn: Callable[[], tuple[list, list]], observables) → None#

Initialize the estimator job.

Parameters:

  • job – The underlying job that produced the results (BatchedJob or MitigatedJob).

  • compute_fn – Deferred callable returning (expectation_values, raw_expectation_values).

  • observables – Observable(s) for which expectation values were calculated.

result()#

Get the underlying combined result for this estimator run (blocks until ready).

job()#

Get the underlying job for this estimator run.

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

Get the raw (unmitigated) expectation values before extrapolation (computes lazily).

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

Get the calculated expectation values (computes lazily on first access).

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

Get the observables for which expectation values were calculated.