Skip to content

Web UI

QPyth includes a modern web interface built with FastAPI (backend) and React (frontend) for interactive quantum computing exploration.

Installation

First, install QPyth with web UI support:

pip install QPyth[web]

Starting the Web UI

Backend (FastAPI)

python server.py

The backend will start on http://localhost:8000

Frontend (React)

In a separate terminal:

cd web
npm install
npm run dev

The frontend will start on http://localhost:3000

Features

Bloch Sphere Visualization

Interactive visualization of quantum states on the Bloch sphere.

Features: - Adjustable theta (θ) and phi (φ) angles - Real-time statevector display - Measurement probability visualization - Preset states: |0⟩, |1⟩, |+⟩, |−⟩, |i+⟩

API Endpoint: 

POST /bloch
Content-Type: application/json

{
  "theta": 1.047,
  "phi": 1.571,
  "shots": 1024
}

Circuit Explorer

Explore quantum circuits including Bell pairs, Hadamard sweeps, and teleportation.

Features: - Bell pair entanglement - Hadamard sweep with configurable depth - Quantum teleportation circuit - Circuit diagram display - Measurement counts

API Endpoints: 

GET /bell

POST /hadamard
Content-Type: application/json

{
  "depth": 3
}

GET /teleport

VQE (Variational Quantum Eigensolver)

Interactive VQE simulation for molecular ground states.

Features: - Multiple molecule support (H₂, LiH, HeH⁺, BeH₂, H₂O) - Three execution modes: - Ideal simulator - Noisy simulator (with IBM calibration data) - IBM Quantum hardware - Energy convergence visualization - Real-time progress tracking

API Endpoint: 

GET /vqe?molecule=H2&use_hardware=false&use_noisy_simulator=true&noise_profile=ibm_brisbane&max_iters=50

QRNG (Quantum Random Number Generator)

Generate quantum random numbers with golden ratio scaling.

Features: - Configurable number of qubits (4-12) - Configurable sequence length (8-32) - Sacred geometry scaling (φ = 1.618...) - Statistical analysis (mean, min, max)

API Endpoint: 

GET /qrng?num_qubits=8&length=16

Noise Profiles

View available IBM Quantum calibration profiles for noisy simulation.

API Endpoint: 

GET /noise/profiles

Response: 

{
  "profiles": ["ibm_brisbane", "ibm_sherbrooke", ...],
  "profile_info": {
    "ibm_brisbane": {
      "name": "ibm_brisbane",
      "num_qubits": 127,
      "avg_t1_us": 123.45,
      "avg_t2_us": 98.76,
      "avg_readout_error": 0.0123
    }
  }
}

API Documentation

Interactive API documentation is available at:

http://localhost:8000/docs

This provides: - Complete API reference - Request/response schemas - Try-it-out functionality - Authentication information

Configuration

Backend Configuration

Configure the FastAPI backend via environment variables:

# Host and port
export QPYTH_HOST="0.0.0.0"
export QPYTH_PORT="8000"

# Rate limiting
export QPYTH_RATE_LIMIT="true"

# IBM Quantum
export QISKIT_IBM_TOKEN="your-token"

Frontend Configuration

The React frontend can be configured in web/src/config.ts (create if needed):

export const API_BASE_URL = process.env.REACT_APP_API_URL || 'http://localhost:8000';

Building for Production

Backend

The backend is production-ready with Uvicorn:

uvicorn server:app --host 0.0.0.0 --port 8000

Frontend

Build the React frontend:

cd web
npm run build

This creates an optimized production build in web/dist/.

Serve with any static file server:

# Using Python
python -m http.server 3000 --directory web/dist

# Using Node.js
npx serve web/dist -l 3000

Deployment

Deploy the frontend to Vercel:

cd web
vercel

Docker

Build and run with Docker:

# Dockerfile
FROM python:3.11-slim

# Install backend dependencies
WORKDIR /app
COPY pyproject.toml .
RUN pip install QPyth[web]

# Copy backend code
COPY server.py .

# Build frontend
COPY web /web
WORKDIR /web
RUN npm install && npm run build

# Expose ports
EXPOSE 8000 3000

# Run both services
CMD ["sh", "-c", "uvicorn server:app --host 0.0.0.0 --port 8000 & npx serve dist -l 3000"]

Troubleshooting

Backend Won't Start

Check if port 8000 is already in use:

# Linux/Mac
lsof -i :8000

# Windows
netstat -ano | findstr :8000

Frontend Won't Start

Ensure dependencies are installed:

cd web
rm -rf node_modules package-lock.json
npm install

API Connection Errors

Check that the backend is running:

curl http://localhost:8000/docs

Verify CORS settings in server.py if needed.

Performance Issues

  • Reduce number of shots in simulations
  • Use simulator instead of hardware for testing
  • Enable rate limiting to prevent abuse
  • Use caching for repeated requests

Next Steps