I-QMapper: Interactive Quantum Mapper

• I-QMapper is a calibration-aware tool that provides interactive qubit layout selection using live and historical backend data.
• It integrates technologies like ipywidgets and Plotly to offer a user-friendly GUI for error visualization and layout quality scoring.
• The tool bridges static visualization and automated mapping by focusing on layout diagnostics, calibration drift tracking, and reproducible session exports.

Searching arXiv for the specified papers to ground the article. Interactive Quantum Mapper (I-QMapper) is an open-source, Jupyter-based tool for noise-aware qubit layout selection, visualization, and analysis on superconducting NISQ hardware. It is designed for the layout design stage itself: users inspect backend calibration data interactively, manually or automatically construct candidate layouts, score layouts with a single quality metric, compare devices and layouts side by side, track calibration drift over time, and export the session for reproducibility (Bazayeva et al., 25 Jun 2026). In the literature on quantum circuit mapping, this emphasis distinguishes I-QMapper from MQT QMAP, which is presented as an open-source quantum circuit mapping tool focused on efficient, automated mapping with a Python interface and a developer-extensible C++ core rather than as a fully fledged interactive mapper with a GUI-style workflow (Wille et al., 2023).

1. Concept and positioning

I-QMapper is positioned between static backend visualization tools and automated compilers or layout optimizers that usually assume the initial mapping is already chosen. Its main purpose is to help users choose a physical qubit layout that is not only connectivity-valid, but also noise-aware, using live and historical backend calibration data rather than relying only on topology or a transpiler’s default choices (Bazayeva et al., 25 Jun 2026).

This positioning is significant because the broader quantum circuit mapping problem is commonly framed around qubit allocation and routing under restricted hardware connectivity. In MQT QMAP, mapping is the process required to make a logical quantum circuit executable on a target quantum architecture whose qubits have restricted connectivity; it is split into qubit allocation and routing, with routing augmenting the circuit with SWAP gates so that every two-qubit interaction obeys coupling constraints throughout execution (Wille et al., 2023). I-QMapper operates earlier in that workflow. It concentrates on interactive, calibration-aware layout construction and diagnostics rather than on a new routing or compilation algorithm.

A common misconception is to treat I-QMapper as equivalent to a general-purpose circuit mapper. The paper explicitly characterizes its main contribution differently: not a new compilation algorithm, but an interactive environment that merges layout construction, calibration analytics, error-aware scoring, historical drift inspection, reproducible export, and multi-programming support (Bazayeva et al., 25 Jun 2026). A plausible implication is that I-QMapper is best understood as a front end for informed layout selection on noisy hardware, especially when calibration heterogeneity and temporal drift materially affect execution quality.

2. Software architecture and implementation model

I-QMapper is implemented in Python inside the Jupyter ecosystem, making it usable alongside Qiskit workflows in the same notebook. Its main technologies are ipywidgets for the UI, Plotly for interactive backend topology and error maps, qiskit-ibm-runtime for backend access and calibration retrieval, rustworkx for graph operations including subgraph isomorphism, numpy for numerical handling, and Kaleido / imageio for PNG, GIF, and MP4 export (Bazayeva et al., 25 Jun 2026).

The software is modularized into components for backend communication, calibration retrieval and caching, layout construction, error analysis, and user interface support. IBM Quantum authentication is intentionally decoupled from the tool: authentication is performed beforehand with Qiskit’s save_account, and I-QMapper uses the saved credentials. The paper notes that multiple accounts can be managed through the optional name argument of save_account (Bazayeva et al., 25 Jun 2026).

Calibration data are stored in a local JSON cache indexed by IBM’s last_update_date. The stated purposes are fast revisits to historical calibration snapshots, reduced API calls, consistent behavior across sessions, and UTC timestamp storage with local-time display conversion (Bazayeva et al., 25 Jun 2026). This caching model is central to I-QMapper’s temporal analytics, since the tool is designed not only for live inspection but also for historical comparison and replay.

Relative to MQT QMAP, the implementation philosophy is different. QMAP is a C++ library with Python bindings, easy to install via pip, with user-facing APIs and a developer-extensible core; its emphasis is efficient, automated, accessible mapping rather than integrated calibration visualization (Wille et al., 2023). The comparison clarifies that the two systems occupy adjacent but non-identical niches in the quantum software stack.

3. Operating modes and interactive design workflow

I-QMapper has two operating modes. The general-purpose mode supports arbitrary circuits, with users manually assigning qubits to generic roles and designing layouts directly on the hardware topology. The quantum-chemistry mode is dedicated to the Local Unitary Cluster Jastrow (LUCJ) ansatz; it knows the ansatz structure and distinguishes the $\alpha$ spin-orbital chain, the $\beta$ spin-orbital chain, ancilla qubits, and other roles. This mode includes automatic LUCJ layout generation, ranking by an error-aware score, and support for multi-programming (Bazayeva et al., 25 Jun 2026).

The Design panel is the main layout-building workspace. It shows the hardware as a native-coordinate coupling map, with qubits as nodes and two-qubit gates as edges. The left panel contains four collapsible sections: Hardware, Display, Colors, and Multi-Programming. These sections control backend selection, layout dimensions, rendering settings, and visual styling parameters such as colors, opacity, and outline width (Bazayeva et al., 25 Jun 2026).

Within the layout sub-panel, the general ansatz mode assigns generic roles, whereas the LUCJ ansatz mode assigns role-specific labels for $\alpha$, $\beta$, ancilla, and other qubits, together with role-specific styling. Editing tools include Undo / Redo for reversible edits, Clear All to reset all circuits, and Refresh to reload topology and calibration data. The Load panel accepts .json, .npy, and pasted qubit lists, and it can restore a saved .qpusession.json session file. The Export panel provides live JSON preview, export of selected qubits, layout saving to JSON, high-resolution PNG topology export, GIF/MP4 calibration time-lapse export, and full session export for reproducibility (Bazayeva et al., 25 Jun 2026).

The Multi-Programming section supports two paradigms: intra-QPU multi-programming, where multiple sub-circuits are mapped onto one QPU and each sub-circuit has its own control panel, and inter-QPU comparison, where two different quantum devices are shown side by side for direct comparison of backend calibration profiles, chosen layouts, and score outcomes (Bazayeva et al., 25 Jun 2026). The paper explicitly illustrates the latter with two IBM Heron backends whose different calibration profiles lead to different optimal placements.

4. Layout-Quality Score and error-aware layout evaluation

A central technical component of I-QMapper is the Layout-Quality Score (LQS), defined as a single scalar quality measure for a selected physical layout (Bazayeva et al., 25 Jun 2026). The paper gives the formula as

$$\text{LQS} = \prod_{q \in Q_{\text{layout}}} \left(1 - \varepsilon_q^{\text{ro}}\right) \cdot \prod_{(q_i,q_j) \in E_{\text{layout}}} \left(1 - \varepsilon_{(q_i,q_j)}^{\text{2Q}}\right).$$

Here, $Q_{\text{layout}}$ is the set of selected physical qubits, $E_{\text{layout}}$ is the set of coupling-map edges whose endpoints are both in $Q_{\text{layout}}$, $\varepsilon_q^{\text{ro}}$ is the readout assignment error for qubit $q$, and $\beta$0 is the two-qubit gate error for that edge (Bazayeva et al., 25 Jun 2026).

The paper interprets LQS as lying in a fidelity-like range, approximately $\beta$1, under an independent-errors assumption. It aggregates readout quality and two-qubit gate quality, but it explicitly does not include single-qubit gate errors, coherence-time effects, or repeated gate use or circuit depth effects (Bazayeva et al., 25 Jun 2026). The LQS banner also reports the worst qubit in the layout and the worst edge in the layout, allowing immediate identification of bottleneck elements.

The relationship between LQS and compilation-oriented metrics is informative. In MQT QMAP, mapping quality can be assessed by the resulting circuit’s two-qubit gate count, depth, or expected fidelity, and the tool emphasizes minimizing additional gates, especially SWAPs, because added gates worsen fidelity and performance (Wille et al., 2023). I-QMapper’s LQS instead evaluates the layout directly, before routing and depth expansion. The paper states that LQS is conceptually related to mapomatic’s ranking idea but differs in that mapomatic evaluates the compiled circuit, whereas I-QMapper computes LQS directly on the layout (Bazayeva et al., 25 Jun 2026). This suggests a complementary role: I-QMapper supplies a calibration-aware prior over candidate placements, while a mapper such as QMAP addresses connectivity satisfaction and routing overhead.

5. Calibration visualization, temporal modes, and diagnostics

The Error panel has two tabs, Calibration and Analysis, and is intended for both visual inspection and more detailed diagnosis of device quality (Bazayeva et al., 25 Jun 2026). In the Calibration tab, the QPU is rendered as a heatmap using IBM-style color encoding. Users can choose separate properties for qubits and gates. Supported qubit properties include readout assignment error, $\beta$2, $\beta$3, measurement conditional probabilities, readout length, single-qubit gate errors, and measurement errors; supported gate properties include CZ error, RZZ error, and two-qubit gate length. Values are taken from Qiskit backend properties, and unavailable metrics appear as N/A (Bazayeva et al., 25 Jun 2026).

When a layout is active, assigned qubits retain their circuit-specific outline color while the fill color encodes the selected calibration metric. Hover tooltips show qubit index, property name, and value. This coupling of semantic role information with calibration overlays is one of the features that operationalize interactive layout inspection (Bazayeva et al., 25 Jun 2026).

The paper defines four temporal viewing modes: Live, Snapshot, Intraday, and Multi-day range. Live uses the most recent calibration available at connection time. Snapshot fetches a specific historical calibration at a chosen date and time. Intraday shows all updates in a selected 24-hour window, with timestamps in a dropdown, animated slider navigation, and export as GIF or MP4. Multi-day range shows the latest update per day over a date interval and likewise supports slider-based navigation and GIF or MP4 export (Bazayeva et al., 25 Jun 2026). These modes enable comparisons across a single day, a multi-day period, or selected historical snapshots.

Threshold filtering restricts displayed values to a user-specified interval $\beta$4. An element $\beta$5 with value $\beta$6 is rendered gray and excluded from the active colormap if $\beta$7. Qubit thresholds and gate thresholds are controlled independently, and filtering works in all time modes (Bazayeva et al., 25 Jun 2026). Delta Analysis compares two calibration snapshots element by element through

$\beta$8

The resulting map uses a diverging color scale in which blue denotes improvement, gray denotes little or no change, and red denotes degradation. Combined with the Intraday or Multi-day slider, this makes calibration drift visually explicit (Bazayeva et al., 25 Jun 2026).

The Analysis tab adds a Qubit Inspector, a ranking tool, a trend tool, and Stable Finder. Stable Finder accepts a property, a threshold value, and a minimum stability ratio; the paper gives the example of readout error $\beta$9 with stability ratio $\alpha$0, returning elements that satisfied the threshold in at least $\alpha$1 of snapshots and sorting results by stability (Bazayeva et al., 25 Jun 2026). This diagnostic apparatus is particularly relevant for superconducting devices whose error rates and coherence metrics vary across the chip and drift over time.

6. Automatic LUCJ layout generation and multi-programming

The automatic LUCJ layout generator extends IBM Quantum’s SQD tutorial code. IBM’s original approach constructs two parallel chains for $\alpha$2 and $\alpha$3, connects them through ancilla bridges, enumerates valid embeddings using VF2 in rustworkx, and scores each candidate with a lightweight error-sum function comprising the sum of two-qubit gate errors, plus readout errors, plus a coherence penalty if $\alpha$4 or $\alpha$5 falls below threshold (Bazayeva et al., 25 Jun 2026).

I-QMapper extends that approach in three stated ways. First, it keeps all valid mappings, presenting candidates in a ranked dropdown so that users can inspect and compare each layout visually. Second, it deduplicates equivalent layouts: layouts differing only by swapping the $\alpha$6 and $\alpha$7 chain assignments are treated as identical because they produce the same physical circuit. Third, it introduces user-controlled ancilla count, allowing the user to choose anywhere from zero to the maximum number of bridges rather than forcing the maximum number (Bazayeva et al., 25 Jun 2026).

The tool further extends the auto engine to intra-QPU multi-programming. Given a list of circuit sizes and a buffer parameter $\alpha$8 equal to the number of graph hops separating circuits, the engine places circuits sequentially on the residual coupling graph. At each step it removes already assigned qubits and all qubits within $\alpha$9 hops of them. The stated purpose of this buffer is to help avoid crosstalk between simultaneously hosted circuits. If one circuit’s placement is manually changed, I-QMapper triggers a cascading re-optimization of downstream circuits to maintain a consistent global allocation (Bazayeva et al., 25 Jun 2026).

This workflow contrasts with the mapping strategies in MQT QMAP. QMAP’s exact mapper encodes the mapping task as a MaxSAT problem and solves it using the Z3 SMT solver, guaranteeing optimality in terms of SWAP count but being practical only for roughly up to eight qubits and around 1000 gates in most scenarios. Its heuristic mapper uses A*-search, with initial layout strategies including trivial identity, static, and dynamic layout, and scales to hundreds of qubits and hundreds of thousands of gates (Wille et al., 2023). I-QMapper does not replace such routing machinery; rather, it addresses the selection and diagnosis of placements under calibration-awareness, including specialized LUCJ and multi-programming workflows.

7. Reproducibility, scope, and limitations

I-QMapper supports several export paths: JSON layout export, PNG device-map figure export, GIF or MP4 time-lapse exports for calibration evolution, .qpusession.json for full session recreation, and .qpustyle.json for preserving appearance. The session format stores layouts, calibration timestamp, and panel configuration, allowing the exact design environment to be reopened later (Bazayeva et al., 25 Jun 2026). For experimental workflows on drifting hardware, this is a substantive reproducibility feature rather than a purely cosmetic convenience.

The tool also supports inter-QPU mode, in which two devices are shown side by side for comparison of calibration landscapes, selected layouts, auto-generated placements, and quality scores. The paper emphasizes that different backends can produce different optimal LUCJ placements because their calibration profiles differ (Bazayeva et al., 25 Jun 2026). This matters in practice because hardware choice itself can become part of layout optimization.

The principal limitation is scope. I-QMapper is calibration-aware and interactive, but it is not presented as a standalone circuit mapper that performs the full connectivity-constrained compilation task. The contrast with QMAP is explicit in the literature: QMAP addresses the quantum circuit mapping problem directly, including qubit allocation, routing, SWAP insertion, and the trade-off between exact optimality and heuristic scalability (Wille et al., 2023). I-QMapper instead addresses the layout design stage, particularly for superconducting quantum hardware, with dedicated support for arbitrary circuits and for the LUCJ ansatz, together with device diagnostics and multi-programming (Bazayeva et al., 25 Jun 2026).

Another limitation is embedded in the LQS itself. Because it does not include single-qubit gate errors, coherence-time effects, or repeated gate use or circuit depth effects, it is a layout-level proxy rather than a full execution-quality predictor (Bazayeva et al., 25 Jun 2026). A plausible implication is that LQS is most informative when used as part of a broader workflow that also considers routing, gate scheduling, and circuit-specific execution structure. Within that broader ecosystem, I-QMapper’s distinctive contribution is to make backend heterogeneity, calibration drift, and layout alternatives directly inspectable and reproducible in an interactive notebook environment.