⚛️ quantum physics

Q2NSViz: An Open-source Standalone Visualizer for Quantum Network Simulations

This paper introduces Q2NSViz, an open-source, standalone Python tool that visualizes quantum network simulation traces to reconstruct dynamic network states and entanglement relationships, thereby bridging the gap between abstract protocol logic and concrete execution for researchers and educators.

Original authors: Francesco Mazza, Marcello Caleffi, Angela Sara Cacciapuoti

Published 2026-07-15

📖 4 min read🧠 Deep dive

CC BY 4.0

Original authors: Francesco Mazza, Marcello Caleffi, Angela Sara Cacciapuoti

Original paper licensed under CC BY 4.0 (http://creativecommons.org/licenses/by/4.0/). ✨ This is an AI-generated explanation of the paper below. It is not written or endorsed by the authors. For technical accuracy, refer to the original paper. Read full disclaimer

Imagine trying to understand a complex magic trick where the magician isn't just pulling rabbits out of hats, but is actually weaving invisible, ghostly threads between them that snap, stretch, and vanish in the blink of an eye. That's what studying quantum networks feels like. These aren't your grandma's telephone lines; they rely on "entanglement," a spooky connection where particles stay linked even when far apart. But here's the problem: when scientists run simulations of these networks on computers, the results usually come out as boring, endless lists of text logs. It's like trying to understand a movie by reading a spreadsheet of every frame's pixel data. You know something happened, but you have no idea how it looked or felt.

Enter Q2NSViz, a new, free tool created by researchers Francesco Mazza, Marcello Caleffi, and Angela Sara Cacciapuoti. Think of Q2NSViz as a time-traveling movie projector for these invisible quantum networks. Instead of staring at a wall of text, this tool takes the raw data from a simulation and turns it into a colorful, interactive visual story that you can play, pause, and scrub through like a video on your phone.

The Magic Behind the Curtain

The paper explains that quantum networks are tricky because their "connectivity" changes constantly. A physical wire might exist between two nodes, but the quantum connection (the entanglement) might be created, used up, or destroyed by the software protocols running the show. The authors argue that looking at the physical map alone isn't enough; you need to see the "ghostly" entanglement graph evolving over time.

Q2NSViz solves this by acting as a replay engine. It doesn't try to run the simulation itself; instead, it reads a special "script" (a JSON/NDJSON trace file) that other simulators, like the popular Q2NS, write down. This script is like a recipe card that says, "At 4 microseconds, Alice sends a qubit," or "At 5 microseconds, a measurement happens." Q2NSViz reads this script and rebuilds the scene in real-time on your screen.

What You Actually See

When you open Q2NSViz, you aren't just looking at static dots. You get a living dashboard:

The Network Canvas: You see the physical nodes (like Alice, Bob, and a Repeater) and the channels connecting them.
The Ghostly Threads: As the simulation plays, you see "entanglement" appear as lines connecting qubits. If a measurement happens, those lines might snap or change color.
The Action: You can watch qubits (the tiny quantum bits of information) physically "fly" along the channels as animated dots. If a qubit gets lost, it turns red and disappears.
The Stats: On the side, charts grow in real-time, showing you exactly how many qubits are alive, how many entangled pairs exist, and how many measurements have happened at any specific moment.

For example, the paper describes a specific moment in a simulation at $t \approx 4 \mu s$ (4 microseconds). In the visualization, you can see a "swap" happening mid-flight: a repeater node is holding onto two memory qubits from a Bell pair (a specific type of entangled state, $|\Phi^+\rangle$ ), while a measurement is actively transferring the entanglement to the final destination qubits, $q_a$ and $q_b$ . Without the visualizer, you'd just see a line of code saying "measurement in progress." With Q2NSViz, you see the tension of that moment.

Why This Matters (Without the Jargon)

The authors are clear that this tool is a zero-coding solution. You don't need to be a programmer to use it. If you are a teacher, a student, or a researcher, you can load a trace file (even one from a different simulator, as long as it speaks the same "JSON language") and instantly see what the network is doing.

The paper explicitly states that this tool does not run the simulation itself; it only replays what has already been simulated. It turns a finished, boring log file into a "portable, time-resolved visual artifact." This means you can save a simulation, send it to a friend, and they can scrub through the timeline to find exactly where a protocol failed—maybe a qubit got lost, or an entanglement link never formed—without having to re-run the whole complex simulation or dig through messy logs.

The Bottom Line

Q2NSViz is a standalone, open-source Python tool (version v0.1.0) that bridges the gap between abstract quantum logic and concrete visual understanding. It suggests that by visualizing the "dynamic entanglement-induced structure," researchers and educators can finally "narrow the gap" between the math and the reality of how these networks behave. It's not a magic wand that solves all quantum problems, but it is a powerful new lens that makes the invisible, visible, turning a confusing stream of data into a navigable, reproducible story.

Technical Summary of Q2NSViz

Problem Statement
Quantum networks possess unique, non-classical features—specifically distributed entanglement resources that are stateful and consumed during protocol execution—that make their simulation and intuitive understanding inherently difficult. Unlike classical networks, the operational connectivity of a quantum network is defined by an entanglement graph that evolves over time, often diverging from the physical network topology. Consequently, interpreting quantum network simulations from physical topology diagrams or textual logs alone is insufficient. The critical dynamics, including the generation, transformation, and consumption of entangled states, are typically buried in low-level logs and trace files, making it difficult for researchers and educators to inspect the relationship between abstract protocol logic and concrete execution.

Methodology
To address these challenges, the authors present Q2NSViz, an open-source, standalone Python-based visualization tool designed for replaying and inspecting quantum network simulation traces. The system is architected around three core components:

Decoupled Trace Contract: The tool relies on a standardized JSON/NDJSON trace format that acts as a contract between the simulator (currently Q2NS) and the viewer. This decoupling ensures that any simulator or script emitting this specific format can generate traces compatible with Q2NSViz, independent of the simulator's internal logic.
Qt-Free Replay Engine: The core logic is implemented in a Python module (logic.py) that is independent of the graphical user interface (GUI). This engine includes:
- EventFileParser: Ingests the trace file and parses events into a structured representation.
- SimulationStateManager: Constructs a keyframe timeline of parsed events. It supports incremental replay and "scrubbing" (seeking to a specific time) by restoring from sparse checkpoints rather than re-replaying the entire trace from the beginning. It tracks qubits, classical bits (cbits), and entanglement relations at any requested simulation time.
Interactive PyQt6 Interface: The desktop application renders the reconstructed state through a QuantumVisualizerWindow. This interface includes a network canvas, an information panel, and control mechanisms for playback (play, step, scrub, speed adjustment).

The visualization workflow reconstructs the time evolution of the network, displaying physical topology alongside dynamic elements such as stored and in-flight qubits, classical bits, measurements, and entanglement relationships. The network canvas visualizes nodes, channels, and qubit states (color-coded), while an entanglement graph represents qubits as vertices and entanglement relationships as edges. The system supports thirteen specific trace event types (e.g., createNode, entangle, measure, sendQubit), each triggering specific updates to the views, such as animating qubit transmission or toggling edges in the entanglement graph.

Key Contributions

Standalone Visualization Tool: Q2NSViz transforms the browser-based visualizer previously associated with Q2NS into a standalone Python application, removing the dependency on a web browser for inspection.
Time-Resolved Reconstruction: The tool provides a navigable, time-resolved view of the simulation, allowing users to scrub through the timeline to observe the exact moment of protocol events, such as entanglement swaps or qubit loss.
Protocol-Agnostic Design: By relying on a trace contract rather than simulator internals, the tool is reusable by other simulation backends that emit the same trace format.
Comprehensive State Tracking: It visualizes not only physical connectivity but also the dynamic, entanglement-induced structure produced and consumed by protocol execution, including Bell-state measurements (BSM) and graph-state Pauli measurements via local complementation.

Results and Capabilities
The paper demonstrates Q2NSViz's ability to ingest simulation traces and replay them with high fidelity. In a demonstration involving a repeater-swap trace, the tool successfully visualized the physical network topology, the entanglement graph, and live quantities (number of active qubits, entangled states, and measurements) over time. The system correctly identified the state of the network at specific timestamps (e.g., $t \approx 4 \mu s$ ), showing a repeater holding memory qubits from Bell pairs while a Bell-state measurement was in progress. The tool validates traces upon loading, reporting issues such as out-of-order timestamps or dangling references.

Significance
The authors position Q2NSViz as a "zero-coding" tool that narrows the gap between abstract protocol logic and concrete execution. Its primary significance lies in:

Accessibility: It lowers the knowledge barrier for researchers and educators, allowing them to inspect complex quantum network behaviors (from teleportation to graph-state manipulation) without writing code or understanding simulator internals.
Debugging and Analysis: It enables users to pinpoint specific failures, such as an entanglement edge that never forms or a qubit lost in flight, by scrubbing to the exact instant of the anomaly rather than reconstructing it from interleaved log lines.
Reproducibility and Sharing: By converting execution traces into portable, self-contained visual artifacts, the tool facilitates the archiving, sharing, and re-examination of simulation results.
Comparative Analysis: It provides a reusable visual layer for comparing protocol behaviors across different scenarios and future releases of Q2NS or compatible simulators.

The work is presented as a complementary layer to the Q2NS simulator, enhancing the experimental workflow for quantum network simulation by making the output inspectable, shareable, and reproducible.

The Magic Behind the Curtain

What You Actually See

Why This Matters (Without the Jargon)

The Bottom Line

Technical Summary of Q2NSViz

More like this