Q2NSViz: An Open-source Standalone Visualizer for Quantum Network Simulations Francesco Mazza, Marcello Caleffi and Angela Sara Cacciapuoti∗
arXiv:2607.12444v1 [quant-ph] 14 Jul 2026
Quantum Internet Research Group, University of Naples Federico II, Naples, 80125, Italy
ARTICLE INFO
ABSTRACT
Keywords: Quantum Network Visualization Quantum Network Simulation Q2NS Quantum Internet
The unique and non-classical features of quantum networks make their simulation and intuitive understanding inherently difficult. In this work, we present Q2NSViz, an open-source Pythonbased visualization tool for replaying and inspecting quantum-network simulation traces. Q2NSViz reconstructs the time evolution of the simulated network state, including physical topology, stored and in-flight qubits, classical bits and packets, measurements, and entanglement relationships. In this way, it exposes not only physical connectivity, but also the dynamic entanglement-induced structure produced, consumed, and transformed by protocol execution. Q2NSViz is built around a decoupled JSON/NDJSON trace contract, a Qt-free replay engine, and an interactive PyQt6 interface, making it a standalone companion to Q2NS and reusable by other simulation backends that emit the same trace format. By turning execution traces into navigable and reproducible visual artifacts, Q2NSViz provides a zero-coding tool for researchers and educators, narrowing the gap between abstract protocol logic and concrete execution.
Metadata
Description
Current code version Permanent link to repository Permanent archive (DOI) Legal code license Code versioning system Languages, tools, services Compilation requirements, dependencies Developer documentation
v0.1.0
Support email
github.com/QuantumInternet-it/q2nsviz doi.org/10.5281/zenodo.21216676
MIT git Python 3, PyQt6, Matplotlib, Q2NS Python ≥3.12, PyQt6 ≥6.6, Matplotlib ≥3.7 Repository README, Doxygen API, bundled example traces [email protected]
1. Motivation and Significance Quantum networks differ from classical networks because their operation depends on distributed entanglement resources that are stateful and consumed by protocol execution. Entanglement induces a connectivity graph that may diverge from the physical network graph, and that evolves over time as protocols generate, transform, consume, or discard entangled states [1, 2]. Consequently, quantum-network simulations are difficult to interpret from topology or textual logs alone. A meaningful view of the execution must track both classical network events and quantum-state evolution, including the evolving entanglement structure [3, 4]. Stateof-the-art quantum-network simulators such as Q2NS provide the execution substrate for these studies, enabling protocol modeling, performance evaluation, and analysis under different physical and architectural conditions [5, 6, 3]. Yet the output of such simulations often remains difficult to ⋆
This work has been funded by the European Union under Horizon Europe ERC-CoG grant QNattyNet, n.101169850. Views and opinions expressed are however those of the author(s) only and do not necessarily reflect those of the European Union or the European Research Council Executive Agency. Neither the European Union nor the granting authority can be held responsible for them. [email protected] (A.S. Cacciapuoti)
F. Mazza, M. Caleffi, A. S. Cacciapuoti
inspect: the relevant dynamics are distributed across lowlevel logs, diagnostics, and trace files. In particular, the entanglement structure produced by the protocol is not directly visible in the raw output, even though it is central to understanding the simulated execution. In this work, we present Q2NSViz, an open-source standalone Python tool for replaying and inspecting quantumnetwork traces. Q2NSViz reconstructs a time-resolved view of the simulated execution, combining the physical topology with the evolving quantum states, classical communication, measurements, and entanglement-induced connectivity. It is designed as a coding-free tool for researchers and educators, and reworks the browser-based visualizer introduced with Q2NS into a standalone Python application [3]. Although Q2NS is the reference producer, Q2NSViz relies on a decoupled JSON trace contract: any simulator or script emitting the same format can generate traces that Q2NSViz can replay.
2. Software Description Q2NSViz is organized as a trace-driven replay workflow rather than as a monolithic visualizer. Fig. 1 illustrates the architecture and its core concepts: a decoupled JSON/NDJSON trace format, which acts as the contract between simulator and viewer; a Qt-free replay engine, which parses the trace and reconstructs the simulated state; and a PyQt6 desktop interface, which renders the reconstructed state through interactive views. Keeping the replay logic independent of the frontend lets traces from Q2NS, or from any compatible producer, be inspected through the same execution path. The replay workflow proceeds from the trace file to the Replay Engine, then through the QuantumVisualizerWindow controller, and finally to the Visualization Interface. Inside the Replay Engine, the EventFileParser parses the JSON/NDJSON events, while the SimulationStateManager Page 1 of 3
Q2NSViz: An Open-source Standalone Visualizer for Quantum Network Simulations Q2NSViz Replay Pipeline – PyQt6 desktop (this paper)
Q2NS – ns-3 / C++ Replay engine (logic.py)
Protocol logic
NetController ⋅ QNode
q2nsviz-trace.h TraceWriter
Visualization Interface (Qt)
NetworkCanvas
EventFileParser emit
trace.json NDJSON / JSON-array
QuantumVisualizerWindow
load
same format viewer.html (portable companion)
controller
snapshot_at(t)
SimulationStateManager
(timeline & incremental replay)
ControlPanel
on_update
signals
(play/step/scrub/speed)
PlaybackController
InfoPanel Logs
Stats
Entangled States
Charts
Figure 1: Q2NSViz replay workflow. The simulator and viewer are decoupled through a typed NDJSON/JSON-array trace that feeds both the desktop application and the portable browser companion shipped with Q2NS [3]. The parser and state-management routines (logic.py) are Qt-free, exposing a programmatic API independent of the GUI.
builds the timeline and exposes the simulated network state at any requested time. The controller queries this state through snapshot_at(t) and dispatches it to the network canvas, information panel, and plots. Fig. 2 shows this workflow with a logical view from endto-end on a repeater-swap trace: the NDJSON events (1) are replayed into the physical and entanglement-graph views (2), together with the live-quantity plots (3). At 𝑡 ≈ 4 𝜇s, the swap is mid-flight: the repeater still holds one memory qubit from each Bell pair |Φ+ ⟩, and the Bell-state measurement that transfers the entanglement to the end qubits 𝑞𝑎 and 𝑞𝑏 is in progress. The main entities involved in the replay workflow are: i. EventFileParser: ingests the trace file and parses its events into the structured representation. ii. SimulationStateManager: builds a keyframe timeline of parsed events and replays them incrementally, against sparse checkpoints – thus scrubbing costs a checkpoint restore rather than a full re-replay – tracking qubits, cbits, and entanglement relations at any requested simulation time. iii. QuantumVisualizerWindow: acts as the controller between replay engine and interface, advancing the clock in response to ControlPanel (user) signals, querying snapshot_at(t), and pushing the resulting state to the visualization components. iv. Views: render the current state through the network canvas and the tabbed information panel, including event logs, statistics, entanglement-state views, and charts. Transport controls (play/step/scrub/speed) let users navigate the timeline and observe the network’s evolution. The network canvas renders network nodes, stored and in-flight qubits and their color-coded state, channel types, and entanglement-induced connectivity. Entanglement is shown through an entanglement graph where qubits are vertices and their entanglement relationships are edges. This view exposes the entanglement connectivity structure and the effects of Bell-state measurements (BSM) and graph-state Pauli measurements via local complementation [3, 7]. Within the information panel, charts plot the F. Mazza, M. Caleffi, A. S. Cacciapuoti
Event
Effect on the views
createNode Node card placed on the canvas. createChannel Quantum or classical link drawn between two nodes. createQubit Qubit marker appears at its host node. removeQubit Qubit cleared from the graph, red × if lost. entangle Toggles edge(s) among nodes on the entanglement graph. measure Bell/Pauli measurement: qubit greyed and removed. graphMeasure Graph-state 𝑋∕𝑌 ∕𝑍 measurement via local sendQubit createCbit sendCbit removeCbit sendPacket traceText
complementation. Qubit animated along the quantum channel over [𝑡0 , 𝑡1 ]. Classical-bit marker appears at its host node. Classical-bit marker animated along the classical channel. Classical bit cleared from its node. Classical packet animated along the channel. Message shown as overlay and in the event-log tab.
Table 1 Trace events by semantic category: network topology , qubit lifecycle , entanglement manipulation , quantum communication , classical communication , and annotation .
number of live qubits, entangled states, and the cumulative measurements over time. Q2NSViz currently supports thirteen trace event types, summarized in Table 1. Each type drives a specific update – adding or removing nodes and qubits, toggling edges in the entanglement graph, animating in-flight qubits and packets, or appending a message to the event log. The entangle, measure and graphMeasure events also accept an optional duration_ns field that models the latency of a state transition (e.g. unentangled to entangled or alive to measured), shown as a gating ring during the duration_ns window that precedes the event timestamp. On load, the engine also validates the trace, reporting out-of-order timestamps, dangling node and qubit references. Because the replay engine is Qt-free, it can also be imported directly into a Python script. The graphical interface uses snapshot_at(t) for live views, while the plotting routines sweep it across the timeline to generate charts.
3. Impact Overview Quantum-network simulators are becoming essential tools for studying protocol and network behavior, but their Page 2 of 3
Q2NSViz: An Open-source Standalone Visualizer for Quantum Network Simulations
rep𝑎
q𝑎
q𝑏 tang en
rep𝑏
Src1
load
4
|Φ+ ⟩ led
Src2 ork
Repeater
Alice
0
2
sta
tes
4 simulation time (𝜇s)
Bob
tw ne
gra
ph
6
2 0
per-step state
entangled states
BSM
0
2
4 𝑡 [𝜇s]
6
2
qubits / node
|Φ+ ⟩
(3) live quantities (𝑡 = 4 𝜇s) live qubits
{"type":"createNode", "label":"Alice"} {"type":"createChannel", "kind":"quantum"} {"type":"createQubit", "label":"q_a"} {"type":"entangle", "duration_ns":300, "bits":["q_a","rep_a"]} {"type":"sendQubit", "bit":"q_a"} {"type":"measure", "bit":"rep_a", "base":"Bell"} {"type":"removeQubit", "bit":"rep_a"} {"type":"entangle", "bits":["q_a","q_b"]} …
(2) replay & visualisation
measurements
(1) trace
1 0
0
2
4 𝑡 [𝜇s]
6
2 1 0
0
2
4 𝑡 [𝜇s]
6
2 1 0
e 1 p 2 b fl t lic Src Re Src Bo in- los
A
Figure 2: Q2NSViz at a glance: a simulator trace is ingested and replayed (1), driving (logical) views of the physical network topology and the entanglement-induced connectivity graph – capturing links that transcend physical proximity – alongside a navigation timeline. Panel (3) plots live quantities over time: active qubits, entangled states, and measurements. At 𝑡 ≈ 4 𝜇s an entanglement swap is in progress: the repeater still holds the two memory qubits of the Bell pairs |Φ+ ⟩, both under measurement.
outputs often remain difficult to inspect without detailed knowledge of the simulator internals and debugging abilities. Q2NSViz turns finished simulation traces into portable, time-resolved visual artifacts: any Q2NS run can be archived, replayed, shared, and re-examined as a self-contained file. Users can scrub to the exact instant a protocol misbehaves – an entanglement edge that never forms, a qubit lost in flight, a late correction – rather than reconstructing it from interleaved log lines. Q2NSViz also lowers the knowledge barrier. Together with Q2NS, it ships with example traces covering from basic to advanced quantum communications scenarios, such as from teleportation to graph-state manipulation and transmission over a lossy channel. Users can load any of these traces without writing code and observe how the protocol events modify qubits, classical information, measurements, and entanglement-induced connectivity over time. This makes the tool useful for debugging, education, and demonstrations. Q2NSViz also embeds non-trivial entanglement manipulation primitives: entanglement created and consumed, swapped across repeaters, and reshaped by local measurements. Because the visualization is driven by a trace contract rather than by Q2NS internals, the same workflow can be reused by any compatible simulator or script, adding a reproducible visual layer for comparing protocol behavior across scenarios and future Q2NS releases.
4. Conclusions This article presented Q2NSViz, an open-source standalone tool for replaying and inspecting quantumnetwork simulation traces. By combining a documented trace format, a Qt-free replay engine, and an interactive Python/PyQt6 interface, Q2NSViz turns simulator output into a time-resolved, navigable, and reproducible representation of quantum-network execution. It therefore complements Q2NS not only as a visual frontend, but as a software layer for inspecting, sharing, and comparing protocol dynamics [3, 4, 7]. By converting finished traces F. Mazza, M. Caleffi, A. S. Cacciapuoti
into navigable, shareable artifacts, Q2NSViz strengthens the experimental workflow around quantum-network simulation and provides a reusable basis for future Q2NS releases and compatible simulation backends. CRediT authorship contribution statement
F.M: Writing – review, editing, original draft, Visualization, Validation, Software, Investigation, Data curation. M.C: Writing – review & editing, Supervision, Methodology. A.S.C: Writing – review & editing, original draft, Supervision, Project administration, Methodology, Funding acquisition, Conceptualization. Declaration of competing interest
The authors declare that they have no known competing financial interests or personal relationships that could have appeared to influence the work reported in this paper. Data availability
Q2NSViz, as Q2NS, is openly available on GitHub and archived on Zenodo according to the code metadata.
References [1] M. Caleffi and A. S. Cacciapuoti, “Quantum internet architecture: Unlocking quantum-native routing via quantum addressing,” IEEE Trans. Commun., vol. 74, pp. 3577–3599, 2026, invited paper. [2] A. S. Cacciapuoti and M. Caleffi, “A quantum internet protocol suite beyond layering,” IEEE Trans. Netw. Sci. Eng., 2026, invited paper. [3] A. Pearson, F. Mazza, M. Caleffi, and A. S. Cacciapuoti, “An extensible quantum network simulator built on ns-3: Q2NS design and evaluation,” Comput. Netw., vol. 283, p. 112292, 2026. [4] A. Pearson, M. Caleffi, and A. S. Cacciapuoti, “A dynamickernel/QPacket executable for quantum repeater chains in Q2NS/ns3,” in Proc. of The ACM International Conference Proceeding Series (ICPS), 2026, to appear. [5] T. Coopmans et al., “NetSquid, a NETwork Simulator for QUantum Information using Discrete events,” Commun. Phys., vol. 4, no. 1, 2021. [6] X. Wu et al., “SeQUeNCe: A customizable discrete-event simulator of quantum networks,” Quantum Sci. Technol., vol. 6, no. 4, 2021. [7] F. Mazza, A. Pearson, M. Caleffi, and A. S. Cacciapuoti, “Q2NS demo: A quantum network simulator based on ns-3,” in Proc. of IEEE Int. Conf. Smart Comput. (SMARTCOMP), 2026, to appear.
Page 3 of 3