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, Any]#

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

When scale_factors is a per-circuit list of lists, each circuit expands by its own count, so the ZNE contribution is the sum of the per-circuit counts (this assumes num_base_circuits matches the number of per-circuit scale-factor lists).

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[float] | list[list[float]] = [1, 3, 5], folding_method: str = 'local', extrapolation_method: str = 'exponential', extrapolation_degree: int | None = None, seed: int | None = None)#

Configure zero-noise extrapolation settings.

Scale factors may be any real numbers >= 1. Non-odd-integer values (even integers, fractions) are approximated by partially folding a randomly-sampled subset of gates; seed makes that sampling reproducible. Extrapolation uses the achieved scale factors as the x-axis.

scale_factors may be either a single flat list applied to every submitted circuit, or a list of lists (one per submitted circuit) so each circuit uses its own scale factors — the number of lists must then match the number of circuit/observable pairs passed to run().

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, requested_scale_factors: list[list[float]] | None = None, achieved_scale_factors: list[list[float]] | None = None, zne_options: dict[str, Any] | None = None)#

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, requested_scale_factors: list[list[float]] | None = None, achieved_scale_factors: list[list[float]] | None = None, zne_options: dict[str, Any] | None = None) → 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.

  • requested_scale_factors – ZNE scale factors requested for each circuit/observable pair (empty when ZNE is disabled).

  • achieved_scale_factors – ZNE scale factors actually realised by folding for each pair — the x-axis used for extrapolation (empty when ZNE is disabled).

  • zne_options – Frozen snapshot of the ZNE configuration used at submission (folding/extrapolation settings), surfaced via mitigator_options. None when unknown.

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.

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

ZNE scale factors requested for this run, as one list per circuit/observable pair.

Returns all pairs’ lists (a list of lists) when index is None, or a single pair’s list when index is given. Empty when ZNE was disabled for the run. See achieved_scale_factors() for the values folding could actually realise.

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

ZNE scale factors actually realised by folding, as one list per circuit/observable pair.

Folding can only approximate the requested scale factors, so these (the x-axis used for extrapolation) may differ from requested_scale_factors(). Returns all pairs’ lists (a list of lists) when index is None, or a single pair’s list when index is given. Empty when ZNE was disabled for the run.

property mitigator_options: dict[str, Any]#

Mitigation settings frozen at submission time for this estimator run.

Merges the ZNE configuration with the underlying backend job’s snapshot (mitigation_level, rem, dd, pauli_twirl), so the returned dict describes the full mitigation stack the run actually used. Unlike FiQCIEstimator.mitigator_options (which is live and mutable), this never changes after submission. Per-pair scale factors are available via requested_scale_factors() / achieved_scale_factors().