fiqci.ems

fiqci.ems#

FiQCI Error Mitigation Service (EMS).

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

Bases: object

FiQCISampler provides a simple interface for running circuits and obtaining mitigated measurement counts without needing to configure the backend directly. It applies readout error mitigation based on the chosen mitigation level and chosen settings, so users get improved sampling results with minimal setup.

Mitigation levels:

  • 0: No error mitigation (raw results)

  • 1: Readout error mitigation using M3 (default)

  • 2: Level 1 + dynamical decoupling (DD)

  • 3: Level 2 + Pauli twirling

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, 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], shots: int = 2048, max_batch_size: int = 100, **options) → MitigatedJob | BatchedJob#

Execute the given circuits on the backend and return mitigated measurement counts.

Parameters:

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

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

  • max_batch_size – Maximum number of circuits per backend job. Inputs longer than this are split into multiple jobs whose results are combined into a single Result indexed in submission order (default: 100).

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

Returns:

A lazy job handle (BatchedJob at level 0, or a MitigatedJob view at level 1+). It is returned immediately; job_ids()/status() are available right away and the combined/mitigated counts are computed on the first result() call.

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

Set readout error mitigation settings for the sampler. 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 sampler. 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.

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

Configure Pauli twirling settings for the estimator.

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 FiQCIBackend(backend: IQMBackendBase, mitigation_level: int = 1, calibration_shots: int = 1000, calibration_file: str | None = None)#

Bases: object

FiQCI backend wrapper that applies error mitigation automatically.

Mitigation levels:

  • 0: No error mitigation (raw results)

  • 1: Readout error mitigation using M3 (default)

  • 2: Level 1 + dynamical decoupling (DD)

  • 3: Level 2 + Pauli twirling

Parameters:

  • backend – An IQMBackendBase instance to wrap.

  • mitigation_level – Error mitigation level (0-3). Default is 1.

  • calibration_shots – Number of shots for calibration circuits. Default is 1000.

  • calibration_file – Optional path to save/load M3 calibration data.

__init__(backend: IQMBackendBase, mitigation_level: int = 1, calibration_shots: int = 1000, calibration_file: str | None = None) → None#

Initialize the FiQCI backend wrapper.

Parameters:

  • backend – An IQMBackendBase instance to wrap.

  • mitigation_level – Error mitigation level (0-3). Default is 1.

  • calibration_shots – Number of shots for calibration circuits. Default is 1000.

  • calibration_file – Optional path to save/load M3 calibration data.

Raises:

ValueError – If mitigation_level is not in range 0-3.

property backend: IQMBackendBase#

Get the underlying backend.

property mitigation_level: int#

Get the current mitigation level.

property raw_counts: list[dict[str, int]] | None#

Get the raw (unmitigated) counts from the most recent run.

The list is flat with one entry per circuit submitted to the backend, in submission order. With Pauli twirling enabled this is the per-twirl counts before any averaging, so the length is num_input_circuits * (num_twirls + 1) and entries for the same input circuit are contiguous.

Note

Because post-processing is now lazy, this is populated only after the run’s mitigated result() has been retrieved at least once. It returns None until then.

Returns:

List of raw count dictionaries, or None if no run’s result has been computed yet.

property mitigator_options: dict[str, Any]#

Get current mitigator settings.

Returns:

A dictionary of current mitigator settings and their values.

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

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

init_pauli_twirl(enabled: bool, num_twirls: int = 10, gates_to_twirl: Iterable[Gate] | None = None) → None#

Initialize Pauli twirling settings.

Parameters:

  • enabled – Whether Pauli twirling is enabled.

  • num_twirls – Number of twirled circuits to generate per input circuit.

  • gates_to_twirl – Optional list of gates to twirl, if None, all two-qubit basis gates will be twirled.

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

Set dynamical decoupling settings for the backend.

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.

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

Set readout error mitigation settings for the backend.

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.

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

Set Pauli twirling settings for the backend.

Parameters:

  • enabled – Whether to enable Pauli twirling.

  • num_twirls – Number of twirled circuits to generate per input circuit (default: 10).

  • gates_to_twirl – Optional list of gates to twirl, if None, all two-qubit basis gates will be twirled.

run(circuits: QuantumCircuit | list[QuantumCircuit], shots: int = 1024, max_batch_size: int = 100, **kwargs: Any) → MitigatedJob | BatchedJob#

Submit quantum circuits and return a lazy job handle immediately.

Circuits are submitted to the backend (in batches), and a handle is returned right away without waiting for results: the per-batch job_id()``s and ``status() are available immediately, and any configured error mitigation is deferred until the handle’s result() is first called.

Parameters:

  • circuits – Single quantum circuit or list of circuits to execute.

  • shots – Number of shots. Default is 1024.

  • max_batch_size – Maximum number of circuits per backend job. The (post-twirl) circuit list is flattened and split into batches of this size; the resulting jobs are wrapped so that the returned handle’s result() exposes a single combined Result indexed in submission order (default: 100).

  • **kwargs – Additional keyword arguments passed to backend.run().

Returns:

A BatchedJob handle (level 0) or a MitigatedJob view (level 1+). In both cases mitigation/combination is computed lazily on the first result() call.

Raises:

ValueError – If circuits is empty or invalid.

exception BatchFailedError#

Bases: RuntimeError

Raised when one or more batches of a submitted job fail.

The message identifies the failing batch by its index and the range of original circuit indices it covered, so callers can map the failure back to their input.

Modules

fiqci_backend

FiQCI backend wrapper for seamless error mitigation.

mitigators

Mitigators for FiQCI EMS

primitives

Primitives for FiQCI EMS

transpiler_passes

Transpiler passes for FiQCI EMS

utils

Utility functions