fiqci.ems.fiqci_backend

fiqci.ems.fiqci_backend#

FiQCI backend wrapper for seamless error mitigation.

FiQCIBackend wraps an IQM backend and applies error mitigation (e.g. M3 readout error correction) to every circuit execution. It handles calibration, caching, and result post-processing automatically, so users get mitigated results through the standard Qiskit backend interface without additional code.

Classes

FiQCIBackend(backend[, mitigation_level, ...])

FiQCI backend wrapper that applies error mitigation automatically.

MitigatedJob(original_job, mitigated_result)

Wrapper for job results with mitigated data.
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.

Returns:

List of raw count dictionaries, or None if no run has been performed yet.

property mitigator_options: dict[str, Any]#

Get current mitigator settings.

Returns:

A dictionary of current mitigator settings and their values.

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, **kwargs: Any) → JobV1 | MitigatedJob#

Run quantum circuits with error mitigation.

This method runs the specified quantum circuit(s) on the backend and applies error mitigation based on the configured mitigation level.

Parameters:

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

  • shots – Number of shots. Default is 1024.

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

Returns:

A JobV1 instance (level 0) or MitigatedJob instance (level 1+) with mitigated results.

Raises:

ValueError – If circuits is empty or invalid.

class MitigatedJob(original_job: JobV1, mitigated_result: Result)#

Bases: object

Wrapper for job results with mitigated data.

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

__init__(original_job: JobV1, mitigated_result: Result) → None#

Initialize mitigated job wrapper.

Parameters:

  • original_job – Original job from backend.

  • mitigated_result – Result object with mitigated counts.

result(timeout: float | None = None) → Result#

Get the mitigated result.

Parameters:

timeout – Maximum time to wait for result (unused, job already complete).

Returns:

Result object with mitigated counts.