Quantum operations as discoverable peer-to-peer network services - orchestrated over py-libp2p, analyzed with Qiskit
A research platform with two connected tracks:
Track 1 - Distributed Quantum Orchestration. A coordinator node (FastAPI + py-libp2p) discovers worker nodes via GossipSub pubsub, compiles OpenQASM circuits into distributed execution plans, routes fragments to workers over libp2p streams, and assembles full quantum results using Qiskit statevector simulation. A Next.js operator console gives real-time visibility into the peer network, job lifecycle, and quantum analysis output.
Track 2 - QAOA Portfolio Optimization. The same infrastructure drives a QAOA-based portfolio optimizer that runs rigorous empirical comparisons against classical baselines (Simulated Annealing) to characterize exactly where, and why, quantum computing gains a scaling advantage.
┌─────────────────────────────────────────────────────────────────┐
│ Next.js Operator Console │
│ /dashboard · /runs · /runs/new · /finance │
│ 3D peer graph · circuit builder · quantum analysis · QAOA │
└──────────────────────────┬──────────────────────────────────────┘
│ BFF proxy (REST polling)
▼
┌─────────────────────────────────────────────────────────────────┐
│ FastAPI Coordinator │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │
│ │ Circuit Jobs │ │ Finance │ │ Enrollment & │ │
│ │ Service │ │ (QAOA) │ │ Discovery │ │
│ └──────────────┘ └──────────────┘ └──────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ py-libp2p Runtime (Trio) │ │
│ │ Ed25519 host · GossipSub pubsub · Stream RPC │ │
│ └──────────────────────────┬─────────────────────────────┘ │
└─────────────────────────────┼───────────────────────────────────┘
│ libp2p streams
┌──────────────────┼──────────────────┐
▼ ▼ ▼
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
│ Worker Peer │ │ Worker Peer │ │ Worker Peer │
│ hadamard/cnot│ │ qft/teleport │ │ programmable │
└───────────────┘ └───────────────┘ └───────────────┘
Persistence: Postgres (event-sourced) · MongoDB (projections) · JSONL (peer log)
97% of quantum runtime is classical COBYLA parameter search — not the quantum circuit.
Quantum runtime breakdown:
Parameter search (COBYLA): ████████████████████████████████████ 97%
Circuit execution: █ 2%
Overhead: ▌ 1%
Implication (Amdahl's Law): adding more quantum nodes yields at most 1.03× speedup. Quantum advantage comes from scaling behavior, not raw speed:
| Portfolio Size | Classical (SA) | Quantum (QAOA) | Winner |
|---|---|---|---|
| 10 assets | 20 ms | 1,500 ms | Classical 75× faster |
| 20 assets | 600 ms | 1,700 ms | Classical 2.8× faster |
| 40 assets | 6,000 ms | 1,900 ms | Quantum 3.2× faster |
| 60 assets | 20,000 ms | 2,100 ms | Quantum 9.5× faster |
- Python 3.11+ with uv
- Node.js 20+ with npm
- Docker (for full-stack deployment)
cd backend
make install # uv sync --extra dev
make run # FastAPI on http://localhost:8081Swagger docs at http://localhost:8081/docs. To restart with a clean runtime state: make run-clean.
cd frontend
npm install
npm run dev # Next.js on http://localhost:3000Create frontend/.env.local:
QUANTUM_BACKEND_URL=http://localhost:8081
NEXT_PUBLIC_TRIAL_DISABLED=true
cp .env.example .env # fill in Neon Postgres + Atlas MongoDB credentials
docker compose up --buildFrontend → localhost:3000 · Backend API → localhost:8081 · Swagger → localhost:8081/docs
Apple-style navigation — pick your goal, go directly there. No guessing needed.
→ Start here: docs/research/RESEARCH_PAPER_DRAFT.md
~15,000 words · 9 sections · publication-ready draft. All experiments, benchmarks, and findings from bottleneck analysis through scaling characterization.
Then read:
- docs/research/MATHEMATICAL_APPENDIX.md — rigorous proofs: QUBO→Ising conversion, parameter-shift rule, Amdahl's Law, complexity comparisons
- docs/research/QUANTUM_SCALING_STRATEGY.md — why we pivoted from speed to scaling, crossover predictions, success criteria
- docs/research/ALTERNATIVE_QUANTUM_FINANCE_PROBLEMS.md — option pricing QAE (proven 100× speedup) as backup
→ Start here: CONTEXT.md
Deep contributor context — package layout, critical caveats (Trio/asyncio bridge, auth model, embedded dev swarm), and entry points for every type of change.
Then read:
- docs/ARCHITECTURE.md — full system architecture: control/execution/data planes, every component, state machines, Mermaid diagrams
- docs/design.md — design rationale, cost model, failure model, protocol contracts
- docs/requirements.md — FR-001–FR-014 with implementation status
→ Start here: frontend/DESIGN.md
The Clay design system — oklch colors, component patterns, shadcn/ui conventions used throughout the UI.
Then read:
- docs/ARCHITECTURE.md §Frontend — BFF proxy pattern, Zustand stores, polling hooks
/runs/new— visual circuit builder with drag-and-drop gate palette + OpenQASM editor/runs/[id]— full quantum analysis: Bloch spheres, fragment DAG, entanglement entropy, density matrices
→ Start here: docs/technical/IMPLEMENTATION_NOTES.md
Complete technical timeline from initial 600× slowdown through three optimization phases to the final scaling result.
Then read:
- docs/technical/BENCHMARK.md — original bottleneck discovery (77% → 97% parameter search)
- docs/technical/GRADIENT_OPTIMIZATION_POSTMORTEM.md — honest analysis of why parameter-shift gradients made it 2–3× slower
- docs/technical/QAOA_OPTIMIZATION_RESEARCH.md — literature survey of 10+ QAOA optimization papers (2024–2025)
backend/scripts/— benchmark scripts used to produce all results
→ Start here: DEPLOYMENT-MANUAL.md
Full production runbook: frontend on Vercel, backend on AWS Lightsail, Neon Postgres, MongoDB Atlas, Caddy HTTPS. ~$40/month all-in.
Then read:
- docs/LIGHTSAIL-DEPLOYMENT.md — Lightsail-specific setup with cost breakdown
- .env.example — all environment variables with descriptions
→ Start here: docs/FINANCIAL_MODELING_FOUNDATIONS.md
What "financial modeling" actually means, Track A (corporate finance) vs Track B (quantum-finance optimization), and why portfolio optimization maps naturally to QAOA.
Then read:
- docs/research/RESEARCH_PAPER_DRAFT.md §1 — the computational crisis in modern financial modeling
- docs/research/ALTERNATIVE_QUANTUM_FINANCE_PROBLEMS.md — option pricing, credit risk, yield curves
→ Start here: docs/FUTURE_ROADMAP.md
Five-milestone evolution: SDK platform → open node network → autonomous research engine → torrent-native service swarm → self-healing distributed organism.
Then read:
- docs/future-roadmap/ — per-milestone detail docs (M1–M5)
- docs/IPFS_INTEGRATION_STRATEGIC_VISION.md — VAULT: browser-native Helia nodes for peer-to-peer circuit sharing (Phase 1 planned)
→ docs/START_HERE.md — the full documentation navigator in one page
| Phase | Approach | Result |
|---|---|---|
| Baseline | Default COBYLA (150 iters × 12 starts) | 10,000 ms · 77% parameter search |
| Phase 1 ✅ | Reduced iterations + parameter caching | 1,400 ms · 97% parameter search — Amdahl limit hit |
| Phase 2 ❌ | Parameter-shift gradients + L-BFGS-B | 2–3× slower — 8× evaluation overhead dominated |
| Phase 3 ✅ | Focus on scaling N, not speed | Quantum wins at N ≥ 40 assets |
Full paper: docs/research/RESEARCH_PAPER_DRAFT.md · Failure analysis: docs/technical/GRADIENT_OPTIMIZATION_POSTMORTEM.md
| Milestone | Theme |
|---|---|
| M1 | Production SDK & Platform |
| M2 | Bring Your Own Node Network |
| M3 | Autonomous Research & Drug Discovery Platform |
| M4 | Torrent-Native Service Network |
| M5 | Hydra Self-Healing Network |
Details: docs/FUTURE_ROADMAP.md
- Fork and create a feature branch.
- Read CONTEXT.md first — the Trio/asyncio bridge and event-sourced persistence have constraints that aren't obvious.
make lint && make testmust pass inbackend/before submitting.npm run buildmust succeed infrontend/(no TypeScript errors).- Surgical changes only — match existing style, don't refactor adjacent code.
@article{bhoir2026quantum,
title={Quantum Portfolio Optimization: Bottleneck Analysis and Scaling Studies},
author={Bhoir, Soham and Gupta, Manusheel},
journal={[Pending submission]},
year={2026},
note={QAOA bottleneck profiling, Amdahl's Law analysis, and quantum advantage characterization for financial portfolio optimization using distributed py-libp2p infrastructure}
}- Qiskit (IBM) — quantum computing framework
- py-libp2p — peer-to-peer networking
- FastAPI — async Python API framework
- shadcn/ui — UI component library
- Yahoo Finance / Prof. Aswath Damodaran (NYU Stern) — market data
docs/START_HERE.md · Research Paper · Architecture · Deployment
Built with quantum circuits, debugged with patience, documented with care.