SimQN: a discrete-event quantum network simulator written in Python

The gap SimQN targets: network-layer quantum simulation

Quantum network research splits into two camps that rarely talk to each other. On one side are physical-layer tools that model optical components and detector dark counts in detail. On the other side are networking papers about routing, entanglement distribution and resource allocation that need hundreds of nodes, not one link. SimQN is aimed squarely at the second camp. The README states the project's core idea is that it makes no architecture assumption, because there is no recognized network architecture in quantum network investigations yet. That is a real design position, not marketing: rather than shipping one canonical quantum internet stack, the library gives you a modular quantum node and lets you assemble protocols yourself.

The intended user is a researcher or graduate student who wants to evaluate a routing algorithm or a distribution protocol and does not want to reimplement the surrounding stack. The README names QKD protocols, entanglement distribution protocols, routing algorithms and resource allocation schemes as the target investigations, and the examples directory backs that up with files such as simple_bb84.py, trusted_relay_bb84.py, DEJMPS.py and entanglement_swapping.py. If your work is about how a network behaves, this is the layer SimQN occupies.

Discrete-event core, Cython hot paths and a fidelity shortcut

The mechanism is a discrete-event scheduler. SimQN is described in the README as a discrete-event-based network simulation platform, and setup.py calls the package a discrete-event scheduler designed for quantum networks. Events advance a simulated clock rather than wall-clock time, which is what makes large topologies tractable.

Two implementation choices matter. First, the README states that SimQN uses Cython to compile critical code into C/C++ libraries, and the repository confirms this with a setup-cython.py at the top level alongside the ordinary setup.py. So the install path has a compiled component, and the pure-Python fallback is a separate concern.

Second, and more interesting for anyone modelling entanglement, SimQN offers two physical models. Alongside the usual quantum state based models, the README describes a higher-layer fidelity-based entanglement model intended to reduce computation overhead. That is a deliberate trade: you give up state-level detail and keep a scalar fidelity per link, which is enough for routing and distribution studies but not for anything that depends on the actual state. The example code opens with init_fidelity = 0.9, which is the kind of parameter this model turns on.

On top of that sit the network auxiliary models: the README lists topology construction, routing table generation and management of multiple session requests. In the code these appear as qns.network.topology, qns.network.route.dijkstra and qns.network.QuantumNetwork.

Installing SimQN and running a first entanglement distribution simulation

The README gives a single install command. The distribution name on PyPI is qns, not simqn, which is the first thing that trips people up.

pip3 install -U qns

After that, the README's first example imports the simulator, a random topology, the entanglement distribution app, the network container, the Dijkstra router and the classic topology helper. The truncated listing begins with the imports and the fidelity parameter:

from qns.simulator.simulator import Simulator
from qns.network.topology import RandomTopology
from qns.network.protocol.entanglement_distribution import EntanglementDistributionApp
from qns.network import QuantumNetwork
from qns.network.route.dijkstra import DijkstraRouteAlgorithm
from qns.network.topology.topo import ClassicTopology
import qns.utils.log as log
import logging

init_fidelity = 0.9

The README does not print a command for running the shipped examples, so the place to start is the file itself. The repository lists examples/entanglement_distribution_random_topo.py, which is the example that matches the imports above, and examples/simple_bb84.py for a QKD protocol on a simpler setup. The expectation when you run one is a log stream from qns.utils.log showing simulated events: link generation, entanglement swapping attempts and the resulting fidelity values as they propagate. Reading those two files before writing your own topology is the fastest way to learn how Simulator, QuantumNetwork and the topology classes fit together, because the README itself does not document the full call sequence.

Where SimQN is the wrong tool

The fidelity-based model is the clearest boundary. It exists to cut computation, and it does so by discarding the quantum state. If your result depends on the state itself, on specific error channels, or on a physical-layer effect that a scalar fidelity cannot express, this model is not the one to use, and the README does not claim otherwise.

The second boundary is hardware. Nothing in the README or the repository layout describes an interface to real quantum devices or to a hardware backend. SimQN is a simulator, and the roadmap puts practical quantum network entities such as quantum repeaters and quantum switches in future versions, which tells you they are not there yet in the 0.2.x line.

The third is packaging friction. requirements.txt pins Cython==0.29.28, numpy==1.22.3 and pandas==1.4.2, while setup.py declares only numpy and pandas as install_requires. Those pins are from an older Python ecosystem, and because Cython is in the build path via setup-cython.py, a modern environment can require care. The README does not document rollback or a supported Python version range, so pinning is on you.

How SimQN differs from NS-3 and from physics-first simulators

The README makes the comparison itself: SimQN is designed to be functional and easy to use, like NS3 in classic networks. The difference in approach is that NS-3 gives you a mature classical stack and a C++ core, whereas SimQN keeps a Python surface and adds quantum-specific primitives: qubit models, fidelity, entanglement distribution apps and a quantum node abstraction. If your paper is about classical network behaviour, NS-3 has the ecosystem. If it is about entanglement distribution over a topology, NS-3 has nothing to offer out of the box.

The second comparison is against physics-first simulators. Those model the optical and detector layers in depth but are not built for routing studies across many nodes. SimQN inverts the emphasis: the README states the developers pay more attention to simulation in the network area, and that the goal is to let users focus on what they study while reusing built-in modules. The cost of that inversion is the fidelity shortcut described above. Choosing between the two is really choosing which layer your contribution lives at.

Maintenance cadence, licence and upgrade cost

The release history is steady but not fast. v0.2.1 landed on 2025-04-17, v0.2.2 on 2026-01-01, and v0.2.3 on 2026-06-09, which is also the date of the last push to the repository. The project is not archived. The roadmap says the team is currently focusing on the 0.2.x line, with network utilities and representative protocols such as Q-CAST, PS/PU, REPS and CASCADE named as in-progress work, and quantum repeaters, switches, a full quantum network stack and a GUI listed for future versions. Treat the roadmap as a statement of direction rather than a schedule.

Upgrade cost is dominated by the compiled component. Because Cython is involved, a version bump can mean a rebuild, and the pinned requirements.txt is a signal that the tested environment is specific. Pin qns together with numpy, pandas and Cython in your own environment file if you need reproducible results for a paper.

On licensing: the repository is GPL-3.0, and setup.py carries the standard GPLv3 header and the matching classifier. GPL-3.0 is a copyleft licence, so if you plan to redistribute SimQN inside a larger product, or to combine it with code under incompatible terms, that is a question for your own legal review. This article does not give legal advice. Note also that setup.py still points its url field at github.com/ertuil/SimQN rather than the QNLab-USTC organization, a leftover from the project's earlier home.

Editorial conclusion

Adopt SimQN if your research question sits above the physical layer: routing, entanglement distribution, resource allocation, or QKD protocol behaviour on multi-node topologies. Skip it if you need a maintained interface to real hardware or a GUI, since the roadmap lists the GUI as a future item and the README documents no hardware backend. Before committing, read examples/entanglement_distribution_random_topo.py and examples/simple_bb84.py against the version you pin, and check that the fidelity model in the entanglement distribution app matches the noise assumptions of your paper. The last push to the repository was on 2026-06-09.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes