Skip to content

Networking

SimulaQron

Maintained by StephanieWehner

The purpose of this simulator of quantum network nodes is to allow you to develop new applications for a future quantum internet, while we do not yet have real quantum network nodes...

PythonBSD-3-Clause
SimulaQron illustration

Resource snapshot

Category

Networking

Stars

131

Last pushed

May 15, 2026Updated 3mo ago

Open issues

13

What it is

SimulaQron is maintained by StephanieWehner and sits in the Networking lane of the open-source quantum map.

The purpose of this simulator of quantum network nodes is to allow you to develop new applications for a future quantum internet, while we do not yet have real quantum network nodes... It commonly appears alongside projectq-framework-projectq in example workflows.

Last verified by Qtangl generator on May 27, 2026

Who it's for

Researchers and students exploring distributed quantum systems, communication protocols, and quantum internet concepts.

What you can build or learn

  • See how the project models nodes, links, and entanglement distribution.
  • Understand what a networking-oriented workflow looks like in software.
  • Compare education-focused versus research-focused networking tools.

Code samples

Examples from the repository.

Pingpongalice (examples/event-based/pingPong/pingpongAlice.py)
"""
Ping-Pong — Alice (client).
Alice connects to Bob and they exchange PING / PONG messages for NUM_ROUNDS
rounds.  Both sides know NUM_ROUNDS, so no BYE is needed — the connection
simply closes after the last round.
This is a purely classical example — no quantum operations.
It demonstrates the event-based state-machine pattern used throughout
SimulaQron examples.
Alice's state diagram
---------------------
          ┌─ (connect) ──────────────────────────────────────┐
          │                                                   │
          ▼                                                   │
        IDLE ──[send "PING"]──► PLAYING                   (start)
                                    │
                               recv "PONG"
                                    │
                                    ▼
                                  IDLE  (next round)
                          ... after NUM_ROUNDS ...
                                    │
                               recv "PONG" (last)
                                    ▼
                                  DONE
Transition table:
    State    │ Event        │ Action       │ Next state
    ─────────┼──────────────┼──────────────┼─────────────
    IDLE     │ (entry)      │ send "PING"  │ PLAYING
    PLAYING  │ recv "PONG"  │ —            │ IDLE
    PLAYING  │ recv "PONG"  │ (last round) │ DONE
    IDLE → PLAYING is an *entry action*: Alice sends PING immediately on
    entering IDLE, before waiting for the next message.
"""
from asyncio import StreamReader, StreamWriter
from pathlib import Path
from simulaqron.general.host_config import SocketsConfig
from simulaqron.sdk.protocol import SimulaQronClassicalClient
from simulaqron.settings import network_config, simulaqron_settings
from simulaqron.settings.network_config import NodeConfigType
NUM_ROUNDS = 5
Pingpongbob (examples/event-based/pingPong/pingpongBob.py)
"""
Ping-Pong — Bob (server).
Bob listens for Alice's PINGs and replies with PONGs.
Both sides know NUM_ROUNDS, so no BYE is needed — Bob stops after
sending the last PONG and the connection closes naturally.
This is a purely classical example — no quantum operations.
It demonstrates the event-based state-machine pattern used throughout
SimulaQron examples.
Bob's state diagram
-------------------
          ┌─ (connect) ──────────────────────────────────────┐
          │                                                   │
          ▼                                                   │
        IDLE ──[recv "PING"]──► PLAYING                   (start)
                                    │
                               send "PONG"
                                    │
                                    ▼
                                  IDLE  (next round)
                          ... after NUM_ROUNDS ...
                                    │
                               recv "PING" (last)
                                    ▼
                                  DONE
Transition table:
    State    │ Event        │ Action       │ Next state
    ─────────┼──────────────┼──────────────┼─────────────
    IDLE     │ recv "PING"  │ —            │ PLAYING
    PLAYING  │ (entry)      │ send "PONG"  │ IDLE
    PLAYING  │ (entry)      │ (last round) │ DONE
    PLAYING → IDLE/DONE is an *entry action*: Bob sends PONG immediately
    on entering PLAYING, before waiting for the next message.
"""
from asyncio import StreamReader, StreamWriter
from pathlib import Path
from simulaqron.general.host_config import SocketsConfig
from simulaqron.sdk.protocol import SimulaQronClassicalServer
from simulaqron.settings import network_config, simulaqron_settings
from simulaqron.settings.network_config import NodeConfigType
NUM_ROUNDS = 5
Politealice (examples/event-based/politePingPong/politeAlice.py)
"""
Polite Ping-Pong — Alice (client).
Extends plain ping pong with a greeting phase: Bob sends "HI" on connect,
Alice replies with "HI", then the game proceeds exactly as in ping pong.
Alice's state diagram
---------------------
    (connect)
        │
        ▼
  WAITING_HI ──[recv "HI"]──► IDLE            ← greeting phase
                  send "HI"     │
                                │ (entry action: send "PING")
                                ▼
                            PLAYING
                                │
                           recv "PONG"
                          ┌─────┴──────────────┐
                    rounds left?             done?
                          │                   │
                          ▼                   ▼
                        IDLE                DONE
Transition table:
    State       │ Event        │ Action       │ Next state
    ────────────┼──────────────┼──────────────┼────────────────
    WAITING_HI  │ recv "HI"   │ send "HI"    │ IDLE
    IDLE        │ (entry)      │ send "PING"  │ PLAYING
    PLAYING     │ recv "PONG"  │ —            │ IDLE or DONE
"""
from asyncio import StreamReader, StreamWriter
from pathlib import Path
from simulaqron.general.host_config import SocketsConfig
from simulaqron.sdk.protocol import SimulaQronClassicalClient
from simulaqron.settings import network_config, simulaqron_settings
from simulaqron.settings.network_config import NodeConfigType
NUM_ROUNDS = 5
# ── States ───────────────────────────────────────────────────────────────────
STATE_WAITING_HI = "WAITING_HI"
STATE_IDLE       = "IDLE"      # noqa: E221
STATE_PLAYING    = "PLAYING"   # noqa: E221
STATE_DONE       = "DONE"      # noqa: E221

Plays well with

License

BSD-3-Clause

SPDX identifier detected from the repository metadata or license files.

Repository README

Preview from the project README.

Rendered as Markdown inside a scrollable preview. Long READMEs stay contained; expand or open on GitHub for the full document.

~758 words · about 3 min readOpen on GitHub

SimulaQron - simple quantum network simulator (4.1.2)

The purpose of this simulator of quantum network nodes is to allow you to develop new applications for a future quantum internet, while we do not yet have real quantum network nodes available for testing.

Since version 4.0, SimulaQron is compatible with NetQASM. See its documentation for how to use SimulaQron as a backend for running NetQASM applications.

Installation

Linux

Software dependencies

Before proceeding, make sure you install Python 3.12. Please note that Python 3.13 or newer is not supported. To install Python 3.12 in Debian-based distributions, you can first add the "deadsnakes" repository:

sudo add-apt-repository -y "ppa:deadsnakes/ppa"

Then you can install Python 3.12 and the Python development package:

sudo apt-get install python3.12-full python3.12-dev

Additionally, you will need the build-essential package, to install tools used when building some SimulaQron dependencies:

sudo apt-get install build-essential cmake vim linux-headers-generic

After this point, you should have all the required dependencies.

Create Python virtual environment (venv)

Before proceeding with the installation, create a python virtual environment (venv) and activate it:

python3.12 -m venv simulaqron
source simulaqron/bin/activate 
Installing from PyPI

Installing from PyPI is simple; once you activated your virtual environment, simply run:

pip install simulaqron

Which should install SimulaQron in its base backends. Additionally, to allow support for projectq, you might want to install the optional dependencies:

pip install "simulaqron[opt]"

Installing from this repository

It is also possible to install SimulaQron directly from this repository. First, make sure you have checked out this repository, then navigate to the root folder of SimulaQron's repository. Once there, you can install SimulaQron by using the Makefile:

make install

Additionally, you can install SimulaQron with extra dependencies:

make install-optional

Finally, if you would like to contribute to the development of SimulaQron, please install the development dependencies:

make install-development

Windows

In Windows, SimulaQron can be installed in two similar ways:

  • Using WSL: Windows for Linux Subsystems (WSL) is a way to execute the linux kernel (and linux apps) in a Windows environment. To install WSL, you can follow the official microsoft documentation. After this you can install SimulaQron in WSL using the Linux instructions from above.
  • Using a Linux Virtual Machine: It is also possible to create a Linux environment using a Virtual Machine Hypervisor such as Oracle VirtualBox. After installing this, create a new Virtual Machine and install a compatible linux version (such as Ubuntu 24.04). After the installation is finished, follow the instructions to install SimulaQron on a Linux machine as presented above.

macOS

Native installation

SimulaQron has also been tested working on macOS Tahoe (26.5) on an M3 Pro CPU.

Before proceeding with the SimulaQron install, you need to install python 3.12, which is available from the Homebrew package manager. Once that homebrew has been installed, you can install Python 3.12 using the following command:

brew install python@3.12 libomp

Additionally, to install the optional dependencies, you will need to install XCode Command Line Tools. To do so, run the following command in a terminal:

xcode-select --install

And follow the instructions on the screen. After this, you can follow the instructions to install SimulaQron either from PyPI or directly from this repository.

Using the provided virtual machines

It is also possible to install SimulaQron on macOS using a Virtual Machine. Considering this please install a Virtual Machine Hypervisor such as Oracle VirtualBox, and install a compatible operating system:

  • Intel-based Macs: This is the case for Mac computers with Intel processor.s You can directly install the "amd64" version of Ubuntu 24.04.
  • ARM-based Macs: This is the case for "Apple Silicon" processors (M1 or newer, including the A18 Macbook Neo). For this type of Macs, you can install the "arm64" version of Ubuntu 24.04

After installing the Operating System on the virtual machine, please continue the installation of SimulaQron in the virtual machine using the Linux instructions as mentioned above.

Tests

There are 2 sets of tests: quick and slow ones. To ease the execution, the Makefile provides two targets:

  • tests: This target only run the quick tests.
  • tests_all: This target runs quick and slow tests.

To run a test target, simply invoke it with make:

make tests

or:

make tests_all

Documentation

Documentation and examples are explained in the HTML documentation https://softwarequtech.github.io/SimulaQron/index.html

For upcoming and previous changes see the file CHANGELOG.md

More info at http://www.simulaqron.org

Read on GitHub

Activity

Latest release

—

Watchers

16

Python support

>=3.10,<3.13

Key dependencies

dataclasses-serialization, numpy, dill, scipy, twisted, networkx, click, daemons, netqasm, multiprocess, StrEnum, psutil

Learn digest

Get monthly updates when library entries change.

Monthly digest: new library entries, updated flagships, and one editorial pick.

Related resources

Keep exploring nearby tools.

quantumlib

Cirq

Python framework for creating, editing, and running Noisy Intermediate-Scale Quantum (NISQ) circuits.

PythonApache-2.0Flagship

4,971 stars · Updated 3mo ago

open-quantum-safe

liboqs

C library for prototyping and experimenting with quantum-resistant cryptography

CMITFlagship

2,946 stars · Updated 3mo ago

XanaduAI

pennylane

PennyLane is an open-source quantum software platform for quantum computing, quantum machine learning, and quantum chemistry.

PythonApache-2.0FlagshipQtangl relevant

3,229 stars · Updated 3mo ago

QISKit

qiskit

Qiskit is an open-source SDK for working with quantum computers at the level of extended quantum circuits, operators, and primitives.

PythonApache-2.0FlagshipQtangl relevant

7,412 stars · Updated 3mo ago

Microsoft

QuantumKatas

Tutorials and programming exercises for learning Q# and quantum computing

Jupyter NotebookMITFlagshipArchive

4,862 stars · Updated 2y ago

tqsd

QuNetSim

A quantum network simulation framework.

PythonMIT

144 stars · Updated 2y ago