Library / SDK
QNLab-USTC/SimQN avatar
QNLab-USTC/SimQN

SimQN installs as qns, and its setup.py points at another account

Project brief: A network-layer simulator for the quantum network investigation. If you would like to follow our work or seek an easy-to-use quantum network simulator, you cannot miss SimQN!

1,029 stars21 forksPythonGPL-3.0

At a glance

What is it?
SimQN is a discrete-event quantum network simulator from a USTC research group, published on PyPI under the name qns. The repository's setup.py still reads 0.2.1 while the newest tag is v0.2.3, its URL field names a different GitHub account, and its dependency pins are from 2022.
Who is it for?
SimQN fits a quantum networking researcher who wants a network-layer simulator with routing and protocol modules already factored out, and who can accept a fidelity-based entanglement model as a stand-in for full state-based physics. It does not fit someone who needs a recognised architecture, because the project deliberately makes no architecture assumption, and it does not fit anyone who wants the GitHub metadata to describe the repository they cloned.
Can I use it commercially?
Yes, with conditions. GPL-3.0 is a copyleft licence: if you distribute software that includes it, you must release that software's source code under the same licence. Running it internally without distributing it does not trigger that obligation.
Is it still maintained?
Yes. The repository last received commits 6 days ago.
What is it written in?
Mainly Python, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 21, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • QNLab-USTC/SimQN1,029 ★ · +72
Star history
Repository2026-08-042026-11-21
QNLab-USTC/SimQN9571k

72 Stars in the last 109 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The repository is SimQN and the distribution is qns

The single most important practical fact about this project is a naming mismatch. The repository is SimQN, the homepage is under that name, and the documentation uses it throughout. The package you install is not called that:

bash
pip3 install -U qns

The badge at the top of the README points at `pypi.org/project/qns/`, and every import in the worked example comes from the `qns` namespace rather than from `simqn`:

python
from qns.simulator.simulator import Simulator
from qns.network.topology import RandomTopology
from qns.network import QuantumNetwork
from qns.network.route.dijkstra import DijkstraRouteAlgorithm

So a search for the project name turns up the repository, and a search for the package name turns up something that does not look like the same project at all. Two things follow. Anyone scripting an install needs the distribution name, not the project name. And anyone reading an issue or a paper that says SimQN has to work out that `import simqn` will fail.

The name collision is worse than that in practice, because searches for the project name also return material about the ordinary English name Simon.

setup.py reads 0.2.1, links a different account, and uses twine to build

The packaging metadata is a single hand-written `setup()` call with no `pyproject.toml` and no `setup.cfg`, and three fields in it are worth reading closely.

The version field reads `0.2.1`. The release history runs v0.2.1 in April 2025, v0.2.2 in January 2026 and v0.2.3 in June 2026, so a checkout of the default branch describes itself as two patch releases behind its own newest tag.

The URL field reads `https://github.com/ertuil/SimQN`, which is a different account from the one hosting the repository. The author field reads `elliot`, and the copyright header above it credits Lutong Chen, Jian Li and Kaiping Xue at the University of Science and Technology of China. So the packaging metadata carries an upstream or fork URL rather than the project's own.

The build requirements include `twine`, which is a publishing tool rather than something needed to compile. Runtime requirements are only `numpy` and `pandas`, which is why the install line above is short.

The pinned dependencies are from 2022

The repository carries a second, stricter dependency list, and it disagrees with the runtime one:

code
Cython==0.29.28
numpy==1.22.3
pandas==1.4.2
pytest==7.1.1
twine==4.0.0

Those are exact pins, not ranges, and they are old enough that they will constrain the interpreter you can use. Cython 0.29 is the last 0.x line, numpy 1.22 and pandas 1.4 both predate Python 3.11, and pytest 7.1 is likewise from that era. A developer working on a current Python will find that this file does not resolve.

Note what is not here. The runtime requirements in `setup.py` are just numpy and pandas, so a user installing from PyPI gets none of these pins. They exist for the development environment, and mixing the two is a common source of confusion on a project with this layout.

The Cython pin is the interesting one, because performance is part of the pitch. The project states that it compiles critical code in C and C++ libraries with Cython to speed up evaluation, and the root carries a separate `setup-cython.py` for that build. Two setup files, one for the package and one for the compiled extension, is a layout worth knowing before you start.

Two physics models, and the cheap one is the point

The physics layer offers a choice, and the framing is not neutral. SimQN provides the commonly used quantum state-based physical models, and alongside them a higher-layer fidelity-based entanglement physical model, described as reducing computation overhead and bringing convenience to evaluation.

That is a fidelity approximation standing in for a full state description. It is the reason large networks are tractable in this simulator, and it is also the assumption a reader has to make before trusting a number. A fidelity is a single scalar per entangled pair; a state-based model carries the state itself.

The project also states that it can simulate quantum noise and fidelity, and that it makes no architecture assumption, on the grounds that there is currently no recognised architecture in quantum network research. That is a defensible design for a research tool and a real constraint for anyone who needs the simulator to match a specific architecture later.

What the documentation does not do is say which model its own headline examples and results use. That is the question to ask before comparing any SimQN number against another simulator's.

The examples directory is the real feature list

Nine example scripts sit under `examples/`, and reading their filenames tells you more about the library's actual coverage than the summary bullets do.

Two are BB84 variants, `simple_bb84.py` and `trusted_relay_bb84.py`. Three cover entanglement distribution, over a line topology and a random topology, plus `entanglement_swapping.py`. `DEJMPS.py` is there as a named distribution protocol rather than a generic one. `parallel_experiments.py` covers running experiments concurrently. And two are classical baselines, `classic_communication.py` and `classic_packet_forward.py`, which sit next to the quantum ones.

Those classical files are the interesting part for an evaluator. Having a non-quantum path in the same examples directory is what lets you tell whether a result came from the quantum channel or from ordinary packet forwarding.

The topology and routing modules the examples import are equally concrete: `RandomTopology`, `ClassicTopology` and `DijkstraRouteAlgorithm` are named in the visible code, and the repository root also carries `AboveNet.gml`, a topology file in the Graph Modelling Language format.

A build artefact directory is committed to the root

The top level of the repository contains `.eggs/`, which is where setuptools caches downloaded build dependencies during a legacy `setup.py` build. Committing it means the directory is versioned, and it is populated by whatever happened to be installed on someone's machine at the time.

Next to it sit two other files that a source repository usually does not carry. `README.html` is a generated rendering of `README.md`, committed next to its own source. And `AboveNet.gml` is data rather than code, a topology description that would be more at home in the examples directory it presumably supports.

None of this breaks anything. It does tell you something about the project's shape: a single `setup.py` with no `pyproject.toml`, a `tox.ini` for tests, a `test/` directory, a `docs/` tree, and a few leftovers.

For an adopter the practical note is that the packaging story is entirely in `setup.py`, so that file is the thing to read before you trust the metadata, and the two setup files it coexists with are the thing to read before you build.

The GUI is on the future list while easy-to-use is the pitch

The project describes itself as an easy-to-use simulator, positioned against NS-3 in the way that NS-3 serves classic network research, and the case for it is that quantum network simulation otherwise forces every user to implement routing and layered protocols separately. The answer offered is a modular quantum node with reusable algorithms and protocols.

The roadmap is more revealing about the current state. The 0.2.x line is described as adding network utilities, meaning more random topology generators, routing algorithms, session request generators, real topology adaptors and multi-path routing, plus representative protocols named Q-CAST, PS/PU, REPS and CASCADE. Everything else is listed as future: quantum repeaters, quantum switches, benchmarking devices, quantum network stack protocols including KM protocols, random request traffic generators, and an easy-to-use GUI.

A GUI being a future item next to an easy-to-use claim is the tension to hold on to. So is the news section's own framing, which reports release v0.2.3, implementation in 22 peer-reviewed papers with 70 citations, and 7 platforms built on top. Those are the project's self-reported figures and are best read as a maintenance signal rather than as a quality measure.

Editorial conclusion

SimQN fits a quantum networking researcher who wants a network-layer simulator with routing and protocol modules already factored out, and who can accept a fidelity-based entanglement model as a stand-in for full state-based physics. It does not fit someone who needs a recognised architecture, because the project deliberately makes no architecture assumption, and it does not fit anyone who wants the GitHub metadata to describe the repository they cloned. Before you build on it, check three things. Install `qns`, not `simqn`, because the distribution name is what resolves on PyPI. Read the `setup.py` in your checkout rather than trusting its version or its URL field, since it reads 0.2.1 against a v0.2.3 tag and links to a different account. And decide deliberately between the fidelity-based model and the state-based one, because the cheaper model is what makes a large network tractable and the project does not tell you which one its own reported results used. The last push to main was on 2026-08-10.

Frequently asked questions

Is SimQN the same thing as Simon?

No. SimQN is a discrete-event quantum network simulator from a USTC research group, distributed on PyPI under the name `qns`. Searches for the ordinary name Simon return unrelated material about the word rather than about this simulator.

What package do I install for SimQN?

The distribution is named `qns`, not `simqn`, so the install command is `pip3 install -U qns` and the imports come from the `qns` namespace, for example `from qns.simulator.simulator import Simulator` and `from qns.network import QuantumNetwork`.

Which version of SimQN is current?

The newest release tag is v0.2.3 from June 2026, following v0.2.2 in January 2026 and v0.2.1 in April 2025. The `setup.py` in the repository still reads version 0.2.1, so the metadata in a source checkout lags the tags.

What physics does SimQN model?

It provides the commonly used quantum state-based physical models plus a higher-layer fidelity-based entanglement model, described as reducing computation overhead. It can also simulate quantum noise and fidelity, and it deliberately makes no architecture assumption because no quantum network architecture is currently recognised.

What can I simulate with SimQN out of the box?

The examples cover simple and trusted-relay BB84, entanglement distribution over line and random topologies, entanglement swapping, the DEJMPS distribution protocol, parallel experiments, and classical communication and packet forwarding as baselines. Topology and routing come from modules such as `RandomTopology`, `ClassicTopology` and `DijkstraRouteAlgorithm`.

Official sources

  1. Official documentation
  2. Official README
  3. Project repository
  4. Release notes
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/qnlab-ustc-simqn.svg)](https://hysenlabs.com/projects/qnlab-ustc-simqn)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/qnlab-ustc-simqn.svg)](https://hysenlabs.com/projects/qnlab-ustc-simqn)

Was this useful?