PQN Stack

Software stack for Public Quantum Network (PQN) nodes

A distributed node based approach to quantum networks. This repository hosts all the code necessary to make the backend of nodes of the PQN function. For the frontend, see here.

PQN web interface for public interaction with a quantum network

Warning

Early Development: This package is in early stages of development. APIs, installation procedures, and distribution methods are subject to change. Use in production environments is not recommended at this time.

Node Architecture

PQN web interface for monitoring and controlling quantum network nodes

Our Node is composed of multiple components. All components inside a node are part of an in internal intranet with no external world access except for quantum links to other hardware or the Node API.

• Node API: FastAPI based, handles communications with web-ui as well as Node to Node communication. Only component in a Node than can talk to other components and the outside world. Resides in src/pqnstack/app/main.py. See the FastAPI docs for more options on how to run the API.
• Lightweight Web UI: Designed for the general public to be able to interact with quantum networks. Resides in its own repository here.
• Router: Routes messages between Hardware Providers, PQN developers and Node APIs. Uses ZMQ sockets to communicate between machines. Resides in src/pqnstack/network/router.py.
• Hardware Provider: Hosts hardware resources that are provided to whoever needs them inside a Node through the use of ProxyInstruments. Resides in src/pqnstack/network/instrument_provider.py.

Quick Start

Note

Hardware Requirements: To do anything interesting with this software currently requires real quantum hardware components (TimeTagger, rotators, etc.). We are actively working on fully simulated hardware components to enable single-machine demos without physical devices, but this capability is not yet available.

Prerequisites

• Python 3.12 or higher
• uv package manager
• Quantum hardware components (TimeTagger, compatible instruments)

Installation

1. Clone the repository

   git clone https://github.com/PublicQuantumNetwork/pqn-stack.git
   cd pqn-stack

2. Install dependencies

   To run the fastapi backend for node operations, use:

   uv sync --extra webapp

Start a Node

To fully start a PQN Node, you need to initialize 4 different processes:

• PQN API
• Router
• Hardware provider (optional)
• Web GUI (optional)

Set up the PQN API

Config file

Before starting a Node API, you need to set up a configuration file for the Node:

1. Copy the example configuration:

   cp configs/config_app_example.toml config.toml

Important

The configuration file must be named config.toml and placed at the root of the repository. If you use a different name or location, the API will not be able to find it.

2. Edit the configuration: Open config.toml in your editor and replace the placeholder values with your actual settings (router addresses, instrument names, etc.).

Configure Router and Hardware Provider

For the first computer on the PQN, both a router and hardware provider are needed. For subsequent computers added to the same node, only a hardware provider is needed.

Both the Router and Hardware Provider can be configured using a config file. (Alternatively you could use CLI flags for quick tests.)

Create a TOML configuration file for the router and hardware provider (see example in configs/config_messaging_example.toml). The config file can contain settings for both router and provider:

• Router settings go under [router]
• Provider settings go under [provider] with instruments defined as [[provider.instruments]]

Start the router:

uv run pqn start-router --config configs/config_messaging_example.toml

Start the Hardware Provider:

uv run pqn start-provider --config configs/config_messaging_example.toml

Alternative method using CLI flags: - Pass configuration directly as command-line arguments

Start the Router with CLI flags:

uv run pqn start-router --name router1 --host localhost --port 5555

Start the Instrument Provider with CLI flags:

uv run pqn start-provider \
  --name provider1 \
  --router-name router1 \
  --instruments '{"dummy1": {"import": "pqnstack.pqn.drivers.dummies.DummyInstrument", "desc": "Test Instrument", "hw_address": "123456"}}'

Start the PQN API server

uv run fastapi run src/pqnstack/app/main.py

To see the list of all the protocols that can be run, go to http://127.0.0.1:8000/docs.

Install the Web GUI

For instructions on how install and start the web GUI please see the repo where it lives at https://github.com/PublicQuantumNetwork/pqn-gui

Acknowledgements

The Public Quantum Network is supported in part by NSF Quantum Leap Challenge Institute HQAN under Award No. 2016136, Illinois Computes, and by the DOE Grant No. 712869, "Advanced Quantum Networks for Science Discovery."

Have questions?

Feel free to contact the PQN team at publicquantumnetwork@gmail.com.