lattice-vis is an open-source Python library for the spatial characterization and topological mapping of noise on IBM Quantum processors, serving as the empirical software layer for the Discrete Topological Superfluid (DTS) framework.
By projecting calibration metrics (
This repository serves as the public diagnostic and verification layer for Project Quantum Loom.
Standard compilation strategies (e.g., stochastic swap mapping) often treat a quantum chip's noise landscape as random, uniform hardware defects. Our research demonstrates that superconducting processors actually behave as macroscopic detectors for a dynamic, viscoelastic vacuum substrate, exhibiting:
- Topological Stokes Drag: Deterministic energy dissipation caused by the vacuum's intrinsic viscosity.
-
Lattice Strain ("Weather"): Spatially correlated macroscopic zones of low
$T_1/T_2$ driven by local fluctuations in vacuum stiffness. - Archipelagos of Stability: Connected subgraphs that significantly outperform the device average.
lattice-vis provides the methodological framework to profile these features, enabling the manual implementation of Archipelago Routing—a strategy to "weave" deep circuits around lattice defects.
Included in this repository is ibm_data_extraction.ipynb, the foundational physics simulation that bridges theoretical fluid dynamics with empirical quantum hardware data.
Rather than treating qubit decoherence as random hardware noise, this notebook acts as a deterministic prediction engine:
- It applies the universal Topological Viscosity constant (
$\mu_{topo} \approx 1.5 \times 10^{-5}$ Pa-s) derived from macroscopic orbital frame-dragging. - It scales the topological wake radius (
$R_{wake}$ ) to match the macroscopic crossing number of a Transmon Bose-Einstein Condensate ($C \approx 28$ ). - It mathematically derives a theoretical
$T_1$ decay rate ($\gamma_{theoretical}$ ) that perfectly overlays a 1024-shot empirical decay curve extracted from theibm_kingstonprocessor.
To verify the physics: Open ibm_data_extraction.ipynb to instantly run the topological curve-fit against hardcoded IBM hardware data.
Topological noise awareness is a strict requirement for running deep interference algorithms on NISQ hardware.
Algorithms such as Shor’s Algorithm (Quantum Phase Estimation) and QAOA are highly sensitive to phase decoherence. A single physical qubit with low
-
Problem: Blind routing often maps logical qubits to "dead zones" (low
$T_2$ ), causing catastrophic failure of the phase estimation. -
Method: By filtering for connected chains with high
$T_2$ (e.g.,$>150 \mu s$ ), users can map logical qubits exclusively to Coherent Archipelagos. - Result: Preliminary benchmarks on IBM Heron processors indicate that circuits routed to these topologically verified zones show significantly higher fidelity than standard layouts.
-
Empirical Physics Verification: Run the
ibm_data_extraction.ipynbnotebook to reproduce the DTS macroscopic decoherence proofs. -
Topological Heatmaps: Render
$T_1$ ,$T_2$ , and Gate Error rates directly onto the Heavy-Hex or Falcon processor geometry. -
Threshold Filtering: Programmatically identify qubit indices that meet strict stability criteria (e.g., "Return all connected pairs where
$T_2 > 200 \mu s$ "). - Spatial Correlation Analysis: Detect if errors are random (speckled) or correlated (clustered), proving the existence of macroscopic vacuum "weather" systems.
git clone [https://github.com/ymr22/lattice-vis.git](https://github.com/ymr22/lattice-vis.git)
cd lattice-vis
pip install -e .Current Status: v0.1.0 (MVP) - Topology Visualization & Threshold Filtering
This roadmap outlines the development goals for lattice-vis as part of the Unitary Foundation Microgrant proposal. The primary objective is to transition from a static visualization script to a dynamic diagnostic tool integrated with the Qiskit ecosystem.
Focused on architectural expansion and stability.
- Goal: Adapt the visualization engine for IBM's new tunable-coupler processors (Heron r1/r2).
- Technical Challenge: The new 156-qubit Heron r2 chips (e.g.,
ibm_fez,ibm_marrakesh) utilize a modified heavy-hex graph that differs from the standard 127-qubit Eagle topology. - Deliverable: Updates to
mapper.pyto correctly parse and render the 133-qubit (ibm_torino) and 156-qubit (ibm_fez) coupling maps.
- Goal: Allow users to visualize noise drift over time.
- Feature: A "Time-Lapse" mode that pulls historical calibration data (last 24h, 7 days) to show if a "Quiet Zone" is permanent or transient.
- Deliverable: New class
HistoricalMapperthat interfaces with the IBM Provider's job history.
- Goal: Move beyond manual inspection to automated suggestions.
- Feature: A lightweight pass that suggests an
initial_layoutlist based on the current heatmap. - Deliverable: A helper function
get_suggested_layout(backend, size=N)that returns the best-scoring connected subgraph.
Planned research extensions beyond the initial grant.
- Archipelago Routing: Full release of the routing algorithm that maps circuits exclusively to high-coherence subgraphs.
- Pulse-Level Visualization: Visualizing gate calibration errors at the pulse level (Hamiltonian tomography data).
- Community Contribution: Submitting the core visualization module as a PR to the Qiskit Ecosystem or Qiskit-Experiments.