Distributed Quantum Services

Quantum operations as discoverable peer-to-peer network services, orchestrated over py-libp2p and analyzed with Qiskit.

---

What this is

A research platform that treats quantum operations as network services. A FastAPI coordinator discovers worker peers over py-libp2p (GossipSub), compiles OpenQASM circuits into distributed execution plans, routes fragments to workers over libp2p streams, and assembles results with Qiskit statevector simulation. A Next.js operator console shows the peer network, job lifecycle, and quantum analysis live.

The same infrastructure powers a QAOA portfolio optimizer that benchmarks quantum against classical baselines.

Watch the demo video

Scope: this is a proof-of-concept on simulators, not a quantum hardware stack. Auth is dev-mode only.

Applications

Application	What it does	Status
Circuit orchestration	Normalize OpenQASM, plan, and execute distributed fragments across worker peers	Available
Financial modelling	QAOA portfolio benchmarks against classical optimization	Available
Risk and options	Simulated VaR, CVaR, credit-risk, and option-pricing experiments	Available
Molecular workflows	Drug-discovery research pipeline with simulated quantum stages	Experimental

Architecture

  Next.js operator console  ──(BFF proxy, REST)──▶  FastAPI coordinator
                                                          │
                                           py-libp2p runtime (Trio)
                                      Ed25519 host · GossipSub · stream RPC
                                                          │
                                       ┌──────────────────┼──────────────────┐
                                  Worker peer        Worker peer        Worker peer

  Persistence: Postgres (event-sourced) · MongoDB (projections) · JSONL (peer log)

Headline result

97% of QAOA runtime is classical COBYLA parameter search, not the quantum circuit, so adding quantum nodes yields at most 1.03x speedup (Amdahl's Law). The advantage shows up in scaling: classical wins at 10 to 20 assets, and QAOA wins from about 40 assets (3.2x faster at 40, 9.5x at 60). The full analysis is in the research paper draft.

---

Quick start

Prerequisites: Python 3.11+ with uv, Node.js 20+, and Docker (full stack only).

Backend (http://localhost:8081, Swagger at /docs):

cd backend
make install
make run          # or `make run-clean` to reset runtime state

Frontend (http://localhost:3000):

cd frontend
npm install
npm run dev

Create frontend/.env.local first:

QUANTUM_BACKEND_URL=http://localhost:8081
NEXT_PUBLIC_TRIAL_DISABLED=true

Full stack with Docker:

cp .env.example .env     # add your Neon Postgres and Atlas MongoDB credentials
docker compose up --build

---

Documentation

Long-form documentation lives in the QMeshPy/documentations repository. Start with its START_HERE page.

I want to...	Read
Contribute code	CONTEXT.md (in this repo), then ARCHITECTURE
Understand the system design	ARCHITECTURE, design, requirements
Work on the frontend	frontend/DESIGN.md (in this repo)
Deploy it	DEPLOYMENT-MANUAL.md (in this repo), Lightsail guide
Read the research	Paper draft, math appendix, scaling strategy
Reproduce the benchmarks	Implementation notes, benchmark results, and the scripts in backend/scripts/
Understand the finance use case	Financial modeling foundations
See where the project is going	Future roadmap

---

Contributing

1. Fork the repo and create a feature branch.
2. Read CONTEXT.md. The Trio/asyncio bridge and event-sourced persistence have constraints that aren't obvious.
3. Run make lint && make test in backend/ and npm run build in frontend/ before opening a PR.
4. Keep changes surgical: match the existing style and don't refactor adjacent code.