# fiqci/fiqci-ems architecture

> Architecture diagram of the GitHub repository fiqci/fiqci-ems, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fiqci/fiqci-ems
- Repository: https://github.com/fiqci/fiqci-ems

## Overview

FiQCI EMS is a Qiskit-facing quantum error-mitigation library for IQM backends. Users submit circuits through a sampler, estimator, or backend wrapper; the backend submits work to IQM and returns lazy job handles that combine batches and apply mitigation when results are requested. The estimator additionally prepares observable measurement circuits and can extrapolate results across noise scales. The README documents mitigation levels and techniques; some internal wiring is omitted because source excerpts are partial.

Main entry points: [`src/fiqci/ems/backend/core.py`](https://github.com/fiqci/fiqci-ems/blob/main/src/fiqci/ems/backend/core.py) (Backend wrapper), [`src/fiqci/ems/primitives/fiqci_estimator.py`](https://github.com/fiqci/fiqci-ems/blob/main/src/fiqci/ems/primitives/fiqci_estimator.py) (Estimator), [`src/fiqci/ems/backend/jobs.py`](https://github.com/fiqci/fiqci-ems/blob/main/src/fiqci/ems/backend/jobs.py) (Lazy batch jobs), [`src/fiqci/ems/primitives/fiqci_sampler.py`](https://github.com/fiqci/fiqci-ems/blob/main/src/fiqci/ems/primitives/fiqci_sampler.py) (Sampler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_sampler["Sampler<br/>[fiqci_sampler.py]"]
  node_estimator["Estimator<br/>[fiqci_estimator.py]"]
end

subgraph group_execution["Execution and results"]
  node_backend["Backend wrapper<br/>[core.py]"]
  node_jobs["Lazy batch jobs<br/>[jobs.py]"]
  node_counts["Count handling<br/>[counts.py]"]
end

subgraph group_mitigation["Error mitigation"]
  node_rem["Readout mitigation<br/>[rem.py]"]
  node_dd["Dynamical decoupling<br/>[dd.py]"]
  node_twirl["Pauli twirling<br/>[pauli_twirl.py]"]
end

subgraph group_estimation["Observable estimation"]
  node_basis["Basis measurement"]
  node_znepass["Noise folding<br/>[zne_circuits.py]"]
  node_zne["Noise extrapolation<br/>[zne.py]"]
end

node_user(("Quantum user"))
node_iqm["IQM backend"]

node_user -->|"submits circuits"| node_sampler
node_user -->|"requests expectations"| node_estimator
node_user -->|"runs circuits"| node_backend
node_sampler -->|"delegates runs"| node_backend
node_estimator -->|"prepares measurements"| node_basis
node_estimator -->|"folds circuits"| node_znepass
node_estimator -->|"submits circuits"| node_backend
node_backend -->|"submits batches"| node_iqm
node_backend -->|"builds handles"| node_jobs
node_backend -->|"applies readout mitigation"| node_rem
node_backend -->|"configures decoupling"| node_dd
node_backend -->|"generates twirls"| node_twirl
node_backend -->|"processes counts"| node_counts
node_jobs -->|"polls and retrieves"| node_iqm
node_jobs -->|"returns results"| node_estimator
node_estimator -->|"extrapolates values"| node_zne

click node_sampler "https://github.com/fiqci/fiqci-ems/blob/main/src/fiqci/ems/primitives/fiqci_sampler.py"
click node_estimator "https://github.com/fiqci/fiqci-ems/blob/main/src/fiqci/ems/primitives/fiqci_estimator.py"
click node_backend "https://github.com/fiqci/fiqci-ems/blob/main/src/fiqci/ems/backend/core.py"
click node_jobs "https://github.com/fiqci/fiqci-ems/blob/main/src/fiqci/ems/backend/jobs.py"
click node_counts "https://github.com/fiqci/fiqci-ems/blob/main/src/fiqci/ems/backend/counts.py"
click node_rem "https://github.com/fiqci/fiqci-ems/blob/main/src/fiqci/ems/mitigators/rem.py"
click node_dd "https://github.com/fiqci/fiqci-ems/blob/main/src/fiqci/ems/mitigators/dd.py"
click node_twirl "https://github.com/fiqci/fiqci-ems/blob/main/src/fiqci/ems/transpiler_passes/pauli_twirl.py"
click node_basis "https://github.com/fiqci/fiqci-ems/blob/main/src/fiqci/ems/transpiler_passes/basis_measurement.py"
click node_znepass "https://github.com/fiqci/fiqci-ems/blob/main/src/fiqci/ems/transpiler_passes/zne_circuits.py"
click node_zne "https://github.com/fiqci/fiqci-ems/blob/main/src/fiqci/ems/mitigators/zne.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_sampler,node_estimator,node_user toneBlue
class node_backend,node_jobs,node_counts toneAmber
class node_rem,node_dd,node_twirl toneMint
class node_basis,node_znepass,node_zne toneRose
class node_iqm toneIndigo
```

## Components

### User interfaces

- [Sampler](https://github.com/fiqci/fiqci-ems/blob/main/src/fiqci/ems/primitives/fiqci_sampler.py): `src/fiqci/ems/primitives/fiqci_sampler.py`
- [Estimator](https://github.com/fiqci/fiqci-ems/blob/main/src/fiqci/ems/primitives/fiqci_estimator.py): `src/fiqci/ems/primitives/fiqci_estimator.py`

### Execution and results

- [Backend wrapper](https://github.com/fiqci/fiqci-ems/blob/main/src/fiqci/ems/backend/core.py): `src/fiqci/ems/backend/core.py`
- [Lazy batch jobs](https://github.com/fiqci/fiqci-ems/blob/main/src/fiqci/ems/backend/jobs.py): `src/fiqci/ems/backend/jobs.py`
- [Count handling](https://github.com/fiqci/fiqci-ems/blob/main/src/fiqci/ems/backend/counts.py): `src/fiqci/ems/backend/counts.py`

### Error mitigation

- [Readout mitigation](https://github.com/fiqci/fiqci-ems/blob/main/src/fiqci/ems/mitigators/rem.py): `src/fiqci/ems/mitigators/rem.py`
- [Dynamical decoupling](https://github.com/fiqci/fiqci-ems/blob/main/src/fiqci/ems/mitigators/dd.py): `src/fiqci/ems/mitigators/dd.py`
- [Pauli twirling](https://github.com/fiqci/fiqci-ems/blob/main/src/fiqci/ems/transpiler_passes/pauli_twirl.py): `src/fiqci/ems/transpiler_passes/pauli_twirl.py`

### Observable estimation

- [Basis measurement](https://github.com/fiqci/fiqci-ems/blob/main/src/fiqci/ems/transpiler_passes/basis_measurement.py): `src/fiqci/ems/transpiler_passes/basis_measurement.py`
- [Noise folding](https://github.com/fiqci/fiqci-ems/blob/main/src/fiqci/ems/transpiler_passes/zne_circuits.py): `src/fiqci/ems/transpiler_passes/zne_circuits.py`
- [Noise extrapolation](https://github.com/fiqci/fiqci-ems/blob/main/src/fiqci/ems/mitigators/zne.py): `src/fiqci/ems/mitigators/zne.py`

### Other components

- **Quantum user**
- **IQM backend**

## Connections

- Quantum user → Sampler: submits circuits
- Quantum user → Estimator: requests expectations
- Quantum user → Backend wrapper: runs circuits
- Sampler → Backend wrapper: delegates runs
- Estimator → Basis measurement: prepares measurements
- Estimator → Noise folding: folds circuits
- Estimator → Backend wrapper: submits circuits
- Backend wrapper → IQM backend: submits batches
- Backend wrapper → Lazy batch jobs: builds handles
- Backend wrapper → Readout mitigation: applies readout mitigation
- Backend wrapper → Dynamical decoupling: configures decoupling
- Backend wrapper → Pauli twirling: generates twirls
- Backend wrapper → Count handling: processes counts
- Lazy batch jobs → IQM backend: polls and retrieves
- Lazy batch jobs → Estimator: returns results
- Estimator → Noise extrapolation: extrapolates values