fiqci.ems.primitives

Primitives for FiQCI 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.

The returned dict is a copy, so mutating it does not change the sampler’s configuration; use rem() / dd() / pauli_twirl(), which validate their input.

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, seed: int | None = None) → None

Configure Pauli twirling settings for the sampler.

seed makes the random twirl selection reproducible for a run.

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.

The returned dict is a copy, so mutating it does not change the estimator’s configuration; use zne() / rem() / dd() / pauli_twirl(), which validate their input.

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.

The number of measurement-basis circuits depends on the observable, and the number of ZNE circuits can depend on the circuit, so the total is summed per circuit/observable pair rather than taken from a single multiplier: pauli_twirl_multiplier * sum(measurement_groups_i * scale_factors_i).

Parameters:

• num_base_circuits – Number of circuits to be submitted.

• observables – A single SparsePauliOp used for every circuit, or one per circuit.

• detailed – Print the breakdown and return it as a dict instead of just the total.

Returns:

The total circuit count, or a dict with the breakdown when detailed is set. Entries that differ between circuits (measurement groups, ZNE multiplier) are reported as a list.

Raises:

ValueError – If a list of observables or per-circuit scale factors does not have one entry per base circuit.

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 | Callable[[...], list[float] | tuple[list[float], list[float]]] = '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().

extrapolation_method may be one of the built-in strings ("exponential", "richardson", "polynomial", "linear") or a user-defined callable. The callable is invoked once per circuit/observable pair as fn(expectation_values, scale_factors), where expectation_values is a list (one entry per scale factor) of per-observable expectation-value lists and scale_factors is the list of achieved scale factors; it must return a list of floats (the zero-noise estimate per observable). extrapolation_degree is ignored for callables.

A callable can also report the uncertainty of its estimate the way the built-in extrapolators do. If it accepts a sigmas keyword argument, it is additionally called with sigmas=<per-scale shot standard errors> (same shape as expectation_values), and it may then return a (values, standard_errors) pair instead of just the values. Those standard errors are surfaced as the "zne_extrapolation_error" / "total" entries of FiQCIEstimatorJob.standard_errors(); callables that return only values leave both None.

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

Configure Pauli twirling settings for the estimator.

seed makes the random twirl selection reproducible for a run.

Modules

fiqci_estimator	A class that runs quantum circuits and calculates expectation values of observables with error mitigation techniques.
fiqci_sampler	A lightweight wrapper around FiQCIBackend for sampling quantum circuits with error mitigation.