Q2NSViz

Table of Contents

• Topics
• Architecture
• Typical Workflow
• Trace File Format
• Related Publications
• Acknowledgement

Q2NSViz is a desktop companion for Q2NS that replays JSON trace files and renders an interactive, time-stepped view of quantum network protocols and simulations.

It jointly renders physical- and entanglement-connectivity graphs and supports entangled-state manipulations, facilitating an intuitive inspection of entanglement dynamics and protocol behavior. Trace files are produced by the Q2NS simulator and follow an NDJSON or JSON-array format where each event object carries a nanosecond timestamp and a typed payload.

Topics

The Q2NSViz codebase is navigated by topic:

• Core State Engine
• Network Canvas
• Chart Panel
• Side Panels
• Application Window

Architecture

Q2NSViz is organized around a small set of focused roles.

• EventFileParser reads NDJSON and JSON-array trace files from disk.
• SimulationStateManager ingests a trace (file path or parsed event list), builds a sorted timeline, and exposes the network state at arbitrary nanosecond timestamps as immutable Snapshot objects via snapshot_at(t_ns); seek(t_ns) is the packaging-free positioning primitive for bulk scans.
• NetworkCanvas is a QPainter widget that renders the network topology, in-flight qubits, entanglement graph, and lost qubits in a fixed sequence of layered paint passes.
• ChartCanvas wraps a Matplotlib figure and plots three time-series (live qubits, entangled states, total measurements) plus a per-node bar chart.
• ControlPanel provides transport controls (play/pause/step), a time scrubber, and a speed slider. Signals drive the QuantumVisualizerWindow playback loop.
• InfoPanel is a tabbed widget containing the event log, statistics table, entanglement-states table, and the ChartCanvas.
• QuantumVisualizerWindow owns all the above and acts as the controller: a PlaybackController QTimer tick advances current_sim_time_ns and calls _update_visualization(), which queries snapshot_at(t) once per frame and dispatches the resulting Snapshot to the canvas and panels.

Typical Workflow

1. Launch python -m q2nsviz (optionally passing a trace file path).
2. Use the Load Simulation button (Ctrl+O) to load a .json / .ndjson trace.
3. Press Play or use the time scrubber to step through the simulation.
4. Inspect the canvas for qubit positions, channel activity, and entanglement links.
5. Switch to the Charts tab to see time-series trends.
6. Read the Event Log tab for traceText protocol messages.

Trace File Format

Q2NSViz reads the JSON wire format produced by Q2NS. Event type strings and field keys are part of the Q2NS public API and are never renamed inside Q2NSViz:

Event type	Key fields
createNode	t_ns, label, x, y
createChannel	t_ns, from, to, kind
createQubit	t_ns, label, node
createCbit	t_ns, label, node
entangle	t_ns, bits
sendQubit	t0_ns, t1_ns, bit, from, to
sendCbit	t0_ns, t1_ns, bit, from, to
sendPacket	t0_ns, t1_ns, from, to, label, protocol (optional)
measure	t_ns, bit, base
graphMeasure	t_ns, bit, base, supportNode (optional)
removeQubit	t_ns, bit, reason (optional)
removeCbit	t_ns, bit
traceText	t_ns, text, node (optional)

The entangle, measure, and graphMeasure events accept an optional duration_ns field giving the operation's processing time. Events are emitted at operation completion; t_ns is the commit instant, and the visualizer draws a ring during the preceding window [t_ns - duration_ns, t_ns). The ring is distinct per event type: dashed for a quantum gate, solid for measure, solid double for graphMeasure, and marks processing time only; entanglement is shown by qubit color and the entanglement links. The base field of measure is informational and does not affect the state update. The reason field of removeQubit selects how the removal is displayed: a qubit removed with reason: "discarded" leaves the canvas silently (counted under Discarded in the Statistics tab), while any other or missing reason on an unmeasured qubit marks it as lost (red cross marker, Lost statistics and chart bar). The removal itself is identical in both cases.

Related Publications

[1] Quantum Internet Architecture: Unlocking Quantum-Native Routing via Quantum Addressing (invited paper). Marcello Caleffi and Angela Sara Cacciapuoti — IEEE Transactions on Communications, vol. 74, pp. 3577-3599, 2026.

[2] An Extensible Quantum Network Simulator Built on ns-3: Q2NS Design and Evaluation. Adam Pearson, Francesco Mazza, Marcello Caleffi, Angela Sara Cacciapuoti — Computer Networks (Elsevier) 2026.

[3] Q2NS: A Modular Framework for Quantum Network Simulation in ns-3 (invited paper). Adam Pearson, Francesco Mazza, Marcello Caleffi, Angela Sara Cacciapuoti — Proc. QCNC 2026.

[4] Q2NS Demo: a Quantum Network Simulator based on ns-3. Francesco Mazza, Adam Pearson, Marcello Caleffi, Angela Sara Cacciapuoti — 2026.

[5] Q2NSViz: An Open-source Standalone Visualizer for Quantum Network Simulations. Francesco Mazza, Marcello Caleffi, Angela Sara Cacciapuoti — 2026 (submitted).

Acknowledgement

This work has been funded by the European Union under Horizon Europe ERC-CoG grant QNattyNet, n. 101169850. Views and opinions expressed are 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.