Q2NS

Table of Contents

• Topics
• Architecture
• Typical Workflow
• Design Goals
• Further Reading
  • Tutorials
  • Design and Reference Notes
• Related Publications
• Acknowledgement

Q2NS is a modular framework for quantum network simulation built on top of ns-3. It adds quantum-state backends, qubits, quantum channels, channel noise models, and node-level quantum operations while remaining compatible with ns-3's event-driven simulation model.

Topics

The Q2NS codebase can be navigated by topic as given below:

• Public API
• Quantum State System
• Quantum Networking Internals
• Channel Maps
• Core Types and Gates

Architecture

Q2NS is organized around a small set of core roles.

• NetController builds and configures the network.
• QNode is the main user-facing per-node API.
• QProcessor is an internal helper for local operations.
• QNetworker is an internal helper for transmission and reception.
• QChannel models a duplex quantum link.
• QMap models transmission-induced effects.
• QStateRegistry is the shared source of truth for backend states.
• QState defines the backend-agnostic state interface.
• Analysis provides common quantum networking analysis functions supported.

Typical Workflow

1. Create a NetController.
2. Create QNodes through the controller.
3. Install links.
4. Create and manipulate qubits through QNode.
5. Run the ns-3 simulation.
6. Inspect outcomes and compute analysis.

Design Goals

• separation of concerns
• modularity and extensibility
• integration with ns-3
• multiple quantum-state backends
• reproducible randomness

Further Reading

Tutorials

• Tutorial 0: The Visualizer
• Tutorial 1: Running Your First Quantum Simulations
• Tutorial 2: Quantum Maps
• Tutorial 3: Teleportation with Classical Communication
• Tutorial 4: Multipartite Entanglement and Simulation Experiments

Design and Reference Notes

• Architecture
• Randomness

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.

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.