req

README.md

@@ -1,10 +1,918 @@
 ---
-title: Optiq
-emoji: 📚
-colorFrom: pink
-colorTo: purple
+title: OptiQ
+emoji: ⚡
+colorFrom: blue
+colorTo: green
 sdk: docker
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+<p align="center">
+  <img src="https://img.shields.io/badge/Python-3.12-blue?style=flat-square&logo=python" />
+  <img src="https://img.shields.io/badge/Qiskit-2.3-6929C4?style=flat-square&logo=ibm" />
+  <img src="https://img.shields.io/badge/PyTorch-2.9-EE4C2C?style=flat-square&logo=pytorch" />
+  <img src="https://img.shields.io/badge/FastAPI-0.128-009688?style=flat-square&logo=fastapi" />
+  <img src="https://img.shields.io/badge/React-18-61DAFB?style=flat-square&logo=react" />
+  <img src="https://img.shields.io/badge/License-MIT-green?style=flat-square" />
+</p>
+
+# ⚡ OptiQ — Hybrid Quantum-AI-Classical Grid Optimization Platform
+
+> **AI-Powered Distribution Grid Reconfiguration SaaS.**  
+> Reduces grid losses by **31 %+** through intelligent network reconfiguration using a three-stage hybrid pipeline: **Quantum Topology Search → GNN Warm-Start → Classical AC-Power-Flow Verification.**
+
+**The first working prototype of the hybrid Quantum-AI-Classical optimization stack for power distribution networks** — a software-only solution that works on existing infrastructure with zero hardware changes.
+
+---
+
+## Table of Contents
+
+1. [Overview](#overview)
+2. [Results](#results)
+3. [Architecture](#architecture)
+4. [Hybrid Pipeline — How It Works](#hybrid-pipeline--how-it-works)
+5. [Mathematical Foundations](#mathematical-foundations)
+6. [Project Structure](#project-structure)
+7. [Backend API Endpoints](#backend-api-endpoints)
+8. [Frontend Pages](#frontend-pages)
+9. [Database Schema](#database-schema)
+10. [Authentication](#authentication)
+11. [Grid Visualization & Out-of-Service Lines](#grid-visualization--out-of-service-lines)
+12. [Evaluation & Impact Metrics](#evaluation--impact-metrics)
+13. [Egypt-Specific Scaling & Implementation](#egypt-specific-scaling--implementation)
+14. [Configuration](#configuration)
+15. [Installation](#installation)
+16. [Running the Application](#running-the-application)
+17. [Deployment with ngrok](#deployment-with-ngrok)
+18. [Environment Variables](#environment-variables)
+19. [Tech Stack](#tech-stack)
+20. [References](#references)
+
+---
+
+## Overview
+
+Electric power distribution grids lose **5–13 %** of generated energy as resistive (I²R) losses in feeder cables. **Network reconfiguration** — opening / closing sectionalising and tie switches — can dramatically reduce these losses while maintaining supply to every bus.
+
+OptiQ solves this NP-hard combinatorial problem with a **hybrid pipeline** that chains:
+
+| Stage | Engine | Role |
+|-------|--------|------|
+| **1. Quantum / SA Topology Search** | Qiskit QAOA or Simulated Annealing | Explore the exponential configuration space, produce top-K candidate topologies |
+| **2. AI Warm-Start** | 3-layer GraphSAGE GNN | Predict bus voltages instantly for each candidate (avoids expensive Newton–Raphson per candidate) |
+| **3. Classical Verification** | pandapower Newton–Raphson AC-OPF | Verify the best candidate(s) with full AC power flow for engineering-grade accuracy |
+
+The platform includes a **full SaaS frontend** (React + Vite + Tailwind CSS) with interactive grid visualization (React Flow), real-time optimization, ROI calculator, PDF reports, audit logs, and a digital-twin scenario simulator.
+
+---
+
+## Results
+
+### OptiQ vs Published Algorithms (IEEE 33-Bus)
+
+Many metaheuristics get trapped at local optima (~146 kW). OptiQ consistently finds the global optimal. All sources listed in [REFERENCES.md](REFERENCES.md).
+
+| Method | Loss (kW) | Reduction | Source |
+|--------|-----------|-----------|--------|
+| Baseline (no reconfiguration) | 202.68 | -- | [1] |
+| Civanlar load-transfer heuristic (1988) | ~146 | ~28% | [2] |
+| PSO (Sulaima 2014, local optimum) | 146.1 | 27.9% | [5] |
+| Baran & Wu branch exchange (1989) | 139.55 | 31.15% | [1] |
+| Goswami & Basu heuristic (1992) | 139.55 | 31.15% | [3] |
+| GA (well-tuned, multiple authors) | 139.55 | 31.15% | [7] |
+| MILP exact (Jabr 2012) | 139.55 | 31.15% | [4] |
+| Branch Exchange + Clustering (Pereira 2023) | 139.55 | 31.15% | [6] |
+| **OptiQ Classical** | **139.55** | **31.15%** | this work |
+| **OptiQ Quantum SA** | **139.55** | **31.15%** | this work |
+| **OptiQ Hybrid** | **139.55** | **31.15%** | this work |
+
+### OptiQ vs Industry Practice
+
+| Solution | Loss Reduction | Cost | Limitation |
+|----------|---------------|------|-----------|
+| Manual switching (status quo in Egypt) | 5-10% [9] | $0 software | Cannot adapt to load changes. Human error. Slow. |
+| Basic ADMS module (ABB/Siemens/GE) | 15-25% [9][22] | $5-50M [22] | Massive CAPEX. 12-24 month deploy. New hardware. |
+| **OptiQ** | **28-32%** | $200/feeder/month | Software-only. Zero CAPEX. Deploys in weeks. |
+
+### Detailed Results
+
+| Method | Loss (kW) | Reduction | Min V (pu) | Violations | Time (s) |
+|--------|-----------|-----------|------------|------------|----------|
+| Baseline (default) | 202.68 | -- | 0.9131 | 21 | -- |
+| **Published Optimal** [1] | **139.55** | **31.15%** | -- | -- | -- |
+| OptiQ Classical | 139.55 | 31.15% | 0.9378 | 7 | 10.7 |
+| OptiQ Quantum SA | 139.55 | 31.15% | 0.9378 | 7 | 17.1 |
+| OptiQ Hybrid | 139.55 | 31.15% | 0.9378 | 7 | 18.1 |
+
+### Multi-Load Robustness
+
+| Load Multiplier | Base Loss (kW) | Optimized (kW) | Reduction |
+|-----------------|----------------|----------------|-----------|
+| 0.70x | 94.91 | 66.99 | 29.4% |
+| 0.85x | 143.09 | 102.11 | 28.6% |
+| 1.00x (nominal) | 202.68 | 141.92 | 30.0% |
+| 1.15x | 274.58 | 187.90 | 31.6% |
+| 1.30x | 359.82 | 243.80 | 32.2% |
+
+---
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│                       React SPA (Vite)                       │
+│  Landing · Dashboard · Grid View · ROI · Audit · Reports     │
+└──────────┬───────────────────────────────────────────────────┘
+           │  REST / JSON
+┌──────────▼───────────────────────────────────────────────────┐
+│               FastAPI  (uvicorn + ngrok tunnel)              │
+│  /api/baseline · /api/optimize · /api/grid · /api/auth  ...  │
+└──────────┬─────────────┬─────────────┬───────────────────────┘
+           │             │             │
+    ┌──────▼──────┐ ┌────▼─────┐ ┌────▼──────┐
+    │  Quantum /  │ │  AI /    │ │ Classical │
+    │  SA Search  │ │  GNN     │ │ pandapower│
+    │  (Qiskit)   │ │ (PyTorch)│ │  (AC PF)  │
+    └─────────────┘ └──────────┘ └───────────┘
+                        │
+                  ┌─────▼─────┐
+                  │  SQLite   │
+                  │  optiq.db │
+                  └───────────┘
+```
+
+**Pipeline flow:**
+
+```
+IEEE Test Data (pandapower built-in)
+         │
+    [Quantum: SA on QUBO] ──→ Top-5 candidate topologies
+         │
+    [AI: Physics-Informed GNN] ──→ Predicted voltages for each topology
+         │
+    [Classical: pandapower AC Power Flow] ──→ Verified feasible solutions
+         │
+    Best Solution ──→ FastAPI ──→ Frontend Dashboard
+```
+
+---
+
+## Hybrid Pipeline — How It Works
+
+The core pipeline is implemented in `src/hybrid/pipeline.py → run_hybrid_pipeline()`:
+
+### Stage 1 — Quantum / Simulated Annealing Topology Search
+
+**File:** `src/quantum/qaoa_reconfig.py`
+
+1. Build a **QUBO (Quadratic Unconstrained Binary Optimization)** matrix from the network graph.
+2. Each binary decision variable xᵢ represents a line: `1 = open (out of service)`, `0 = closed`.
+3. **Simulated Annealing** (primary solver):
+   - Proposes swap moves (close one tie line, open one feeder line).
+   - Checks radiality (connected tree for distribution networks).
+   - Runs quick AC power flow via pandapower.
+   - Accepts/rejects via **Metropolis criterion**.
+   - Multi-restart: 5 restarts × 500 iterations, cooling rate 0.99.
+4. Alternatively, a **reduced QAOA** solver (`solve_qaoa_reduced`) can run on ≤15 qubits using Qiskit's `StatevectorSampler` + COBYLA optimizer.
+5. A **QUBO export** function (`get_qubo_for_qpu`) prepares the matrix for external QPU submission (D-Wave / IBM Quantum).
+6. Output: **Top-K candidate topologies** ranked by total losses.
+
+### Stage 2 — GNN Warm-Start
+
+**File:** `src/ai/model.py`
+
+1. A pre-trained **3-layer GraphSAGE GNN** (`OptiQGNN`) predicts bus voltage magnitudes for each candidate topology.
+2. Input features per node (5-dim): `[Pd, Qd, Vm_init, is_slack, is_gen]`.
+3. Input features per edge (3-dim): `[R, X, in_service]`.
+4. Architecture: 3 × SAGEConv layers with **residual connections**, **LayerNorm**, and **dropout**.
+5. Output: Per-bus voltage magnitude clamped to [0.90, 1.10] p.u. via sigmoid scaling.
+6. Training uses a **physics-informed loss** with dynamic Lagrange multipliers (DeepOPF-NGT inspired).
+
+### Stage 3 — Classical AC Power Flow Verification
+
+**File:** `src/grid/power_flow.py`
+
+1. The best candidate from Stage 2 is passed to **pandapower's Newton–Raphson AC power flow solver**.
+2. Extracts full results: total losses (kW), voltage profile, line loadings, voltage violations.
+3. Returns the verified optimal topology with engineering-grade accuracy.
+
+### Fallback — Classical Branch-Exchange
+
+**File:** `src/grid/reconfiguration.py`
+
+A heuristic branch-exchange search (`branch_exchange_search`) is used as:
+- Baseline comparator for the hybrid pipeline.
+- Fallback when quantum/AI stages are unavailable.
+- Iteratively swaps open/closed line pairs, keeping swaps that reduce losses, until no improving swap exists.
+
+---
+
+## Mathematical Foundations
+
+### QUBO Formulation
+
+The cost Hamiltonian (`src/quantum/hamiltonian.py`) constructs:
+
+$$\min_{\mathbf{x}} \; \mathbf{x}^T \mathbf{Q} \, \mathbf{x}$$
+
+Where:
+- **Objective (diagonal):** $Q_{ii} = -c_i + P(1 - 2K)$
+- **Coupling (off-diagonal):** $Q_{ij} = P \quad \forall\, i < j$
+- **Loss coefficient:** $c_i = r_i \cdot P_i^2 / V^2$ (per-line approximate resistive loss)
+- **Radiality constraint:** Penalty $P \cdot \left(\sum x_i - K\right)^2$ ensures exactly $K$ lines are open
+- $K = $ number of tie switches (5 for IEEE 33-bus)
+
+### Simulated Annealing — Metropolis Criterion
+
+$$P(\text{accept}) = \begin{cases} 1 & \text{if } \Delta E < 0 \\ e^{-\Delta E / T} & \text{otherwise} \end{cases}$$
+
+Cooling schedule: $T \leftarrow 0.99 \cdot T$ per iteration.
+
+### GNN Physics-Informed Loss
+
+$$\mathcal{L} = \underbrace{\| V_{pred} - V_{true} \|^2}_{\text{MSE}} + \lambda_v \cdot \underbrace{\text{mean}\left[\max(0, v_{min} - V_m)^2 + \max(0, V_m - v_{max})^2\right]}_{\text{Voltage bound violation}}$$
+
+With **dynamic Lagrange multiplier** update (dual gradient ascent):
+
+$$\lambda_v \leftarrow \max\!\left(0,\; \lambda_v + \eta \cdot \text{violation}\right)$$
+
+### Power Flow (Newton–Raphson)
+
+pandapower solves the full AC power flow equations:
+
+$$S_i = V_i \sum_{k=1}^{n} Y_{ik}^* V_k^*$$
+
+Where $S_i$ is complex power injection, $V_i$ is bus voltage, and $Y_{ik}$ is the bus admittance matrix element. The Newton–Raphson method iteratively solves the non-linear system using the Jacobian matrix.
+
+### Impact Calculations
+
+| Metric | Formula |
+|--------|---------|
+| **Loss reduction (kW)** | $\Delta P = P_{baseline} - P_{optimized}$ |
+| **Loss reduction (%)** | $100 \times \Delta P / P_{baseline}$ |
+| **Annual energy saved (MWh/yr)** | $\Delta P \times 8760 / 1000$ |
+| **CO₂ saved (tonnes/yr)** | $\text{Energy saved (kWh)} \times \epsilon_f / 1000$ |
+| **Cost saved (USD/yr)** | $\text{Energy saved (kWh)} \times \text{price}_{\$/kWh}$ |
+
+Where $\epsilon_f = 0.475$ kg CO₂/kWh (global grid average) and price = $0.10/kWh.
+
+---
+
+## Project Structure
+
+```
+OptiQ/
+├── api/                          # FastAPI backend
+│   ├── main.py                   # Entry point, router registration, ngrok startup
+│   ├── auth.py                   # Auth middleware (Bearer token verification)
+│   ├── database.py               # SQLite DB (users, usage, audit_logs, feeders)
+│   └── routes/
+│       ├── auth_routes.py        # POST /auth/register, /auth/login
+│       ├── baseline.py           # GET  /baseline/{system}
+│       ├── optimize.py           # POST /optimize
+│       ├── compare.py            # POST /compare
+│       ├── simulate.py           # POST /simulate, /simulate/toggle
+│       ├── grid.py               # GET  /grid, POST /grid/set-out-of-service
+│       ├── digital_twin.py       # POST /digital-twin
+│       ├── roi.py                # POST /roi, GET /roi/pricing
+│       ├── audit.py              # GET  /audit, /audit/summary
+│       ├── report.py             # POST /report (PDF generation)
+│       ├── usage.py              # GET  /usage, /usage/stats
+│       └── validate.py           # GET  /validate/{system}
+│
+├── src/                          # Core computation engine
+│   ├── quantum/
+│   │   ├── qaoa_reconfig.py      # SA solver, QAOA solver, QUBO export
+│   │   ├── hamiltonian.py        # QUBO matrix construction
+│   │   └── decoder.py            # Decode binary strings to topologies
+│   ├── ai/
+│   │   ├── model.py              # GraphSAGE GNN (OptiQGNN)
+│   │   ├── physics_loss.py       # Physics-informed + dynamic Lagrange loss
+│   │   ├── train.py              # Training loop with scenario generation
+│   │   ├── inference.py          # GNN inference on new topologies
+│   │   └── dataset.py            # PyG data construction
+│   ├── grid/
+│   │   ├── loader.py             # Load IEEE test cases (33-bus, 118-bus)
+│   │   ├── power_flow.py         # AC power flow, topology validation
+│   │   └── reconfiguration.py    # Classical branch-exchange heuristic
+│   ├── evaluation/
+│   │   └── metrics.py            # Impact, business model, Egypt scaling
+│   └── hybrid/
+│       └── pipeline.py           # 3-stage hybrid pipeline orchestration
+│
+├── frontend/                     # React SPA
+│   ├── src/
+│   │   ├── App.jsx               # Router + page transitions
+│   │   ├── index.css             # Tailwind + custom animations
+│   │   ├── contexts/
+│   │   │   └── AuthContext.jsx    # SQLite-backed auth context
+│   │   ├── services/
+│   │   │   └── api.js            # API client with Bearer token
+│   │   ├── components/
+│   │   │   ├── Navbar.jsx        # Frosted glass navbar with glow effects
+│   │   │   └── Footer.jsx        # Animated footer
+│   │   └── pages/
+│   │       ├── LandingPage.jsx   # Hero, features, stats, CTA
+│   │       ├── DashboardPage.jsx # Optimization controls, results, charts
+│   │       ├── GridViewPage.jsx  # Interactive React Flow graph, out-of-service panel
+│   │       ├── ROICalculatorPage.jsx  # Calculate savings per feeder
+│   │       ├── AuditPage.jsx     # Audit log history with before/after
+│   │       ├── LoginPage.jsx     # Email + password sign in
+│   │       ├── SignupPage.jsx    # Registration form
+│   │       ├── PricingPage.jsx   # SaaS tier comparison
+│   │       └── AboutPage.jsx     # Team, methodology, tech stack
+│   ├── package.json
+│   ├── vite.config.js
+│   └── tailwind.config.js
+│
+├── config.py                     # Centralized configuration (dataclasses)
+├── requirements.txt              # Python dependencies
+├── Dockerfile                    # Multi-stage Docker build
+├── docker-compose.yml            # Docker Compose for one-command deployment
+├── .dockerignore                 # Docker build exclusions
+├── scripts/
+│   └── benchmark.py              # Full benchmark suite vs published literature
+├── models/                       # Saved GNN checkpoints
+├── start.sh                      # Launch script (backend + ngrok)
+├── .env                          # Environment variables (git-ignored)
+├── .env.example                  # Template for environment variables
+├── optiq.db                      # SQLite database (auto-created)
+├── FRONTEND_SPEC.md              # API contract documentation
+└── REFERENCES.md                 # All external sources with numbered citations
+```
+
+---
+
+## Backend API Endpoints
+
+All endpoints are prefixed with `/api`.
+
+### Authentication
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/auth/register` | Register new user (email, password, display_name) → returns token |
+| POST | `/auth/login` | Login with email + password → returns token |
+
+### Grid & Power Flow
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/grid?system=case33bw` | Get grid topology (nodes + branches) for visualization |
+| POST | `/grid/set-out-of-service` | Set specific lines out of service, run power flow |
+| GET | `/grid/{system}/switches` | Get switch states for all lines |
+| GET | `/baseline/{system}` | Run baseline AC power flow on default topology |
+
+### Optimization
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/optimize` | Run hybrid pipeline (quantum SA → GNN → AC PF) |
+| POST | `/compare` | Compare Classical vs Quantum+Classical vs Full Hybrid |
+| POST | `/simulate` | Run simulation with custom parameters |
+| POST | `/simulate/toggle` | Toggle individual line switches |
+
+### Analytics & Reporting
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/roi` | Calculate ROI for given parameters |
+| GET | `/roi/pricing` | Get SaaS pricing tiers |
+| GET | `/roi/comparison` | Compare pricing models |
+| GET | `/audit` | Get user's audit log history |
+| GET | `/audit/summary` | Aggregated audit statistics |
+| POST | `/report` | Generate downloadable PDF report |
+| GET | `/report/data` | Get report data as JSON |
+| GET | `/usage` | Get usage history |
+| GET | `/usage/stats` | Get aggregated user stats |
+
+### System
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/health` | Health check |
+| GET | `/validate/{system}` | Validate a network system |
+| POST | `/digital-twin` | Run digital-twin scenario simulation |
+| GET | `/digital-twin/scenarios` | Get predefined scenarios |
+
+---
+
+## Frontend Pages
+
+| Page | Route | Description |
+|------|-------|-------------|
+| **Landing** | `/` | Hero section with shimmer effect, feature showcases, animated stats, CTA |
+| **Login** | `/login` | Email + password sign in (SQLite-backed) |
+| **Sign Up** | `/signup` | Registration with name, email, password, benefit highlights |
+| **Dashboard** | `/dashboard` | System selector, optimization controls, results charts, power flow stats |
+| **Grid View** | `/grid` | Interactive React Flow graph with custom BusNode components, out-of-service line panel |
+| **ROI Calculator** | `/roi` | Calculate savings for given # of feeders & electricity price |
+| **Audit Log** | `/audit` | Full history of optimizations with before/after loss comparison |
+| **Pricing** | `/pricing` | SaaS tier comparison (Starter $199, Professional $499, Enterprise custom) |
+| **About** | `/about` | Team bios, methodology explanation, technology stack cards |
+
+### UI Animations
+
+All pages feature modern CSS animations defined in `index.css` and `tailwind.config.js`:
+
+- **Page transitions:** `animate-page-in` — slide-up + fade-in on route change (keyed by pathname)
+- **Staggered elements:** `stagger-1` through `stagger-5` — sequential fade-in with 100ms delays
+- **Floating backgrounds:** `animate-float-slow` — decorative gradient orbs that drift vertically
+- **Shimmer effect:** `animate-shimmer` — gradient sweep on hero text
+- **Hover interactions:** `hover-lift` (translateY -4px) + `glow-ring` (box-shadow pulse)
+- **Navbar:** `backdrop-blur-md` frosted glass with hover-glow brand icon
+- **Reduced motion:** Respects `prefers-reduced-motion` media query
+
+---
+
+## Database Schema
+
+The SQLite database (`optiq.db`) is auto-created on first run via `init_db()`.
+
+### `users` Table
+| Column | Type | Description |
+|--------|------|-------------|
+| id | INTEGER PK | Auto-increment |
+| firebase_uid | TEXT UNIQUE | User identifier (format: `user_<hex>`) |
+| email | TEXT UNIQUE | User email |
+| display_name | TEXT | Display name |
+| password_hash | TEXT | SHA-256 salted password hash |
+| password_salt | TEXT | Random 16-byte hex salt |
+| created_at | TIMESTAMP | Registration time |
+| last_login | TIMESTAMP | Last login time |
+| total_optimizations | INTEGER | Cumulative optimization count |
+| total_energy_saved_kwh | REAL | Cumulative energy savings |
+| total_co2_saved_kg | REAL | Cumulative CO₂ savings |
+| total_money_saved_usd | REAL | Cumulative cost savings |
+
+### `usage` Table
+Tracks every optimization run: user_id, system, method, load_multiplier, baseline/optimized losses, energy/CO₂/money saved, computation time, shadow mode flag, switches changed.
+
+### `audit_logs` Table
+Full audit trail: action, system, method, details, baseline/optimized losses, loss reduction %, annual energy/CO₂/cost savings, open lines before/after.
+
+### `feeders` Table
+Multi-feeder management: user_id, name, system type, created_at.
+
+---
+
+## Authentication
+
+OptiQ uses **SQLite-based authentication** (no external services required):
+
+1. **Registration:** `POST /api/auth/register` — hashes password with SHA-256 + random salt, creates user in `optiq.db`, returns a Bearer token.
+2. **Login:** `POST /api/auth/login` — verifies password against stored hash, returns Bearer token.
+3. **Token format:** `uid:email:displayName` — sent as `Authorization: Bearer <token>` header.
+4. **Middleware:** `api/auth.py` parses the Bearer token and injects user info into route handlers via FastAPI `Depends()`.
+5. **Frontend:** `AuthContext.jsx` manages session state via `localStorage`, syncs token with the API client.
+
+No Firebase, no external OAuth, no third-party dependencies. The system is fully self-contained.
+
+---
+
+## Grid Visualization & Out-of-Service Lines
+
+### Supported Systems
+
+| System | Buses | Lines | Topology | Layout Algorithm |
+|--------|-------|-------|----------|-----------------|
+| **IEEE 33-bus** | 33 | 37 (32 feeder + 5 tie) | Radial (tree) | BFS layered |
+| **IEEE 118-bus** | 118 | 186 | Meshed (loops) | Kamada-Kawai |
+
+### Out-of-Service Lines
+
+Users can manually set lines as out of service via the Grid View page:
+
+- Enter line IDs in the out-of-service panel
+- Click "Apply & Run Power Flow" to validate and compute results
+- **Distribution networks (33-bus):** Must maintain a connected **tree** (radial) topology
+- **Transmission networks (118-bus):** Only requires **connectivity** (mesh loops allowed)
+
+The validation function `check_topology_valid()` in `power_flow.py` automatically detects the system type and enforces the appropriate constraint.
+
+### Visualization Features
+
+- **Custom BusNode components** with React Flow Handle elements for proper edge connections
+- **Color-coded nodes:** Slack bus (green), generator (blue), load (orange)
+- **Line status indicators:** In-service (solid), out-of-service (dashed/red)
+- **Interactive controls:** Pan, zoom, minimap, drag-to-rearrange
+
+---
+
+## Evaluation & Impact Metrics
+
+### What Gets Calculated (`src/evaluation/metrics.py`)
+
+| Category | Metrics |
+|----------|---------|
+| **Power Flow** | Total losses (kW/MW), loss %, voltage profile (min/max/mean p.u.), voltage violations count, per-line loadings (%), per-line losses (kW) |
+| **Optimization Impact** | Loss reduction (kW & %), annual energy saved (MWh/yr), CO₂ reduction (tonnes/yr), cost savings (USD/yr) |
+| **Environmental** | Trees planted equivalent, cars removed equivalent |
+| **Business Model** | SaaS revenue per feeder ($200/month), revenue-share (15%), enterprise licensing |
+| **Solution Footprint** | Energy/CO₂ cost of running the optimization (150W TDP assumed) |
+| **Net Benefit** | Waste eliminated minus solution overhead (typically 0.007% overhead) |
+| **Dependent Variables** | ~178 physical, ~20 algorithmic, 3 external, 5 decision = 201 total |
+
+### Waste Elimination Framework
+
+| Metric | Before OptiQ | After OptiQ |
+|--------|-------------|-------------|
+| Energy wasted as heat (per feeder/year) | 1,775,477 kWh | 1,222,458 kWh |
+| **Waste eliminated** | -- | **553,020 kWh/year (31.15%)** |
+| Solution computational overhead | -- | 36.5 kWh/year (0.007% of savings) |
+
+---
+
+## Egypt-Specific Scaling & Implementation
+
+### Scaling Parameters
+
+| Parameter | Value | Source |
+|-----------|-------|--------|
+| Grid emission factor | 0.50 kg CO₂/kWh | IEA 2022 (88% natural gas) |
+| Total generation | 215.8 TWh | IEA 2022 |
+| T&D losses | 17 % of output | FY 2022/23 target |
+| Distribution losses | 11 % of output | Estimated |
+| Cairo consumption share | 27 % | Estimated |
+
+### Impact at Scale
+
+| Scope | Savings | CO₂ Saved | Cost Saved |
+|-------|---------|-----------|------------|
+| Single feeder | 553 MWh/year | 26.3 t/year | $44K/year |
+| Cairo (5,000 feeders) | 2.0 TWh/year | 1.0 Mt/year | $221M/year |
+| Egypt (all feeders) | 7.4 TWh/year | 3.7 Mt/year | $592M/year |
+| Global | 467 TWh/year | 222 Mt/year | -- |
+
+### Implementation Plan
+
+| Phase | Timeline | Scope | Cost |
+|-------|----------|-------|------|
+| Phase 0 (MVP) | Done | IEEE benchmark validated | $0 |
+| Phase 1 (Pilot) | 3-6 months | 5-10 feeders, NCEDC substation, shadow mode | $10-20K |
+| Phase 2 (District) | 6-12 months | 100+ feeders, automated SCADA pipeline | $50-100K |
+| Phase 3 (Cairo) | 1-2 years | 5,000+ feeders across NCEDC + SCEDC | $500K-1M |
+| Phase 4 (National) | 2-3 years | All 9 distribution companies | $2-5M |
+
+### Pricing Model
+
+| Model | Price | Value Proposition |
+|-------|-------|-------------------|
+| **SaaS Subscription** | $200/feeder/month | 5.4% of savings — immediate payback |
+| **Revenue Share** | 15% of verified savings | ~$6,636/feeder/year, zero upfront cost |
+| **Enterprise License** | $500K/year (up to 1,000 feeders) | $500/feeder/year for large utilities |
+
+### CO₂ Trustworthiness
+
+Energy savings are computed from **pandapower's Newton–Raphson AC power flow** — an industry-standard, physics-validated solver derived from Kirchhoff's laws. CO₂ uses Egypt's grid factor (0.50 kg CO₂/kWh for 88% gas). Annualisation assumes constant load; real-world savings are ~60-80% of this figure due to load variation.
+
+---
+
+## Configuration
+
+All hyperparameters are centralized in `config.py` via Python dataclasses:
+
+| Section | Key Parameters |
+|---------|---------------|
+| **Grid** | `system=case33bw`, `v_min=0.95`, `v_max=1.05`, `n_tie_switches=5` |
+| **Quantum** | `reps=2`, `shots=250,000`, `top_k=5`, `radiality_penalty=100`, `optimizer=COBYLA`, `maxiter=200` |
+| **AI** | `hidden_dim=64`, `num_layers=3`, `dropout=0.1`, `lr=1e-3`, `epochs=200`, `n_scenarios=2000` |
+| **Impact** | `emission_factor=0.475` kg CO₂/kWh, `electricity_price=$0.10/kWh`, `hours_per_year=8760` |
+| **Egypt** | `emission_factor=0.50`, `total_generation=215.8 TWh`, `td_loss=17%`, `dist_loss=11%` |
+| **API** | `host=0.0.0.0`, `port=8000`, `reload=True`, `cors_origins=["*"]` |
+
+---
+
+## Installation
+
+### Prerequisites
+- Python 3.11+ (tested on 3.12)
+- Node.js 18+ (for frontend build)
+- pip / conda
+
+### Backend Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/your-org/OptiQ.git
+cd OptiQ
+
+# Create virtual environment
+python -m venv venv
+source venv/bin/activate
+
+# Install Python dependencies
+pip install -r requirements.txt
+
+# (Optional) Train the GNN model (~60 seconds)
+python -c "
+import sys; sys.path.insert(0, '.')
+from src.ai.train import train
+train(n_scenarios=1000, epochs=100, verbose=True)
+"
+```
+
+### Frontend Setup
+
+```bash
+cd frontend
+npm install
+npm run build    # Produces frontend/dist/ served by FastAPI
+cd ..
+```
+
+---
+
+## Running the Application
+
+### Quick Start
+
+```bash
+# Using the start script (loads .env automatically):
+./start.sh
+
+# Or manually:
+source venv/bin/activate
+python -m uvicorn api.main:app --host 0.0.0.0 --port 8000 --reload
+```
+
+The application is available at **http://localhost:8000**. The built React frontend is served directly from FastAPI.
+
+### Development (separate frontend dev server)
+
+```bash
+# Terminal 1 — Backend
+source venv/bin/activate
+python -m uvicorn api.main:app --host 0.0.0.0 --port 8000 --reload
+
+# Terminal 2 — Frontend (with hot reload)
+cd frontend
+npm run dev
+```
+
+### Run the Benchmark
+
+```bash
+source venv/bin/activate
+python scripts/benchmark.py
+```
+
+---
+
+## Deployment with ngrok
+
+OptiQ uses **pyngrok** (Python library) to create a public tunnel automatically on server startup — no CLI tool needed.
+
+### Setup
+
+1. Copy `.env.example` to `.env`:
+   ```bash
+   cp .env.example .env
+   ```
+
+2. Add your ngrok authtoken (get from [ngrok.com](https://ngrok.com)):
+   ```env
+   NGROK_AUTHTOKEN=your_authtoken_here
+   NGROK_DOMAIN=your-custom-domain.ngrok-free.app
+   ```
+
+3. Start the server — ngrok tunnel opens automatically:
+   ```bash
+   ./start.sh
+   ```
+
+The console will show:
+```
+✓ ngrok tunnel open → https://your-custom-domain.ngrok-free.app
+```
+
+If `NGROK_AUTHTOKEN` is not set, the server starts normally without a tunnel.
+
+### CRL Workaround
+
+On first start, the server writes a clean ngrok v3 config with `crl_noverify: true` to work around the known CRL verification issue in ngrok v3. No manual config is needed.
+
+---
+
+## Deployment with Docker
+
+### Quick Start (Docker Compose)
+
+```bash
+# Build and run
+docker compose up -d
+
+# View logs
+docker compose logs -f optiq
+
+# Stop
+docker compose down
+```
+
+The app is available at **http://localhost:8000**.
+
+### Build Image Only
+
+```bash
+docker build -t optiq .
+docker run -p 8000:8000 -e OPTIQ_MOCK_AUTH=true optiq
+```
+
+### Environment Variables via Docker
+
+Pass any env var at runtime:
+
+```bash
+docker run -p 8000:8000 \
+  -e OPTIQ_MOCK_AUTH=true \
+  -e NGROK_AUTHTOKEN=your_token \
+  -e NGROK_DOMAIN=your-domain.ngrok-free.app \
+  -v optiq-data:/app/data \
+  optiq
+```
+
+### Docker Architecture
+
+The image uses a **multi-stage build**:
+1. **Stage 1 (Node 20):** Builds the React frontend → `frontend/dist/`
+2. **Stage 2 (Python 3.12-slim):** Installs Python dependencies + copies source + built frontend
+
+The `docker-compose.yml` persists the SQLite database and GNN models via named volumes.
+
+---
+
+## Environment Variables
+
+Create a `.env` file (or copy from `.env.example`):
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `NGROK_AUTHTOKEN` | _(empty)_ | ngrok authentication token (optional) |
+| `NGROK_DOMAIN` | _(empty)_ | Custom ngrok domain (optional) |
+| `PORT` | `8000` | Server port |
+| `OPTIQ_MOCK_AUTH` | `true` | `true` = accept any Bearer token; `false` = verify against SQLite |
+
+---
+
+## Tech Stack
+
+### Backend
+| Technology | Version | Purpose |
+|-----------|---------|---------|
+| **Python** | 3.12 | Runtime |
+| **FastAPI** | 0.128+ | REST API framework |
+| **uvicorn** | 0.40+ | ASGI server |
+| **pandapower** | 3.4+ | AC power flow (Newton–Raphson), IEEE test cases |
+| **Qiskit** | 2.3+ | Quantum computing (QAOA circuits, QUBO) |
+| **PyTorch** | 2.9+ | GNN training & inference |
+| **PyTorch Geometric** | 2.7+ | Graph neural network layers (SAGEConv) |
+| **NetworkX** | 3.4+ | Graph algorithms (topology validation, layouts) |
+| **SQLite** | built-in | User database, usage tracking, audit logs |
+| **pyngrok** | 7.0+ | ngrok tunnel from Python (public URL) |
+| **python-dotenv** | 1.0+ | Load .env environment variables |
+
+### Frontend
+| Technology | Version | Purpose |
+|-----------|---------|---------|
+| **React** | 18.3 | UI library |
+| **Vite** | 5.4 | Build tool & dev server |
+| **Tailwind CSS** | 3.4 | Utility-first CSS framework |
+| **React Flow** | 11.11 | Interactive graph visualization |
+| **Recharts** | 2.13 | Charts & data visualization |
+| **Lucide React** | 0.460 | Icon library |
+| **React Router** | 6.28 | Client-side routing |
+
+---
+
+## References
+
+1. Baran & Wu, "Network reconfiguration in distribution systems for loss reduction and load balancing," IEEE Trans. Power Delivery, 1989.
+2. Civanlar et al., "Distribution feeder reconfiguration for loss reduction," IEEE Trans. Power Delivery, 1988.
+3. Goswami & Basu, "A new algorithm for the reconfiguration of distribution feeders for loss minimization," IEEE Trans. Power Delivery, 1992.
+4. Jabr et al., "Minimum Loss Network Reconfiguration Using Mixed-Integer Convex Programming," IEEE Trans. Power Systems, 2012.
+5. Sulaima et al., "A DNR for loss minimization by using improved PSO," IJICIC, 2014.
+6. Pereira et al., "Branch Exchange + Clustering," Applied Sciences, 2023.
+7. Various authors — GA, SA, and other metaheuristics for IEEE 33-bus reconfiguration.
+8. Qiskit SDK 2.x — Migration from 1.x to 2.x (arXiv:2512.08245).
+9. Egyptian Electricity Holding Company (EEHC) annual reports.
+10. Hamilton et al., "Inductive Representation Learning on Large Graphs," NeurIPS 2017 (GraphSAGE).
+11. Thurner et al., "pandapower — An Open-Source Python Tool for Convenient Modeling, Analysis, and Optimization of Electric Power Systems," IEEE Trans. Power Systems, 2018.
+12. IEA Egypt Energy Data, Country profile 2022.
+13. DeepOPF-NGT — Physics-informed neural network with dynamic Lagrange multipliers.
+
+All bracketed numbers (e.g. [1], [12]) refer to the [References](#full-references) section below for full citations.
+
+---
+
+## Full References
+
+All externally-sourced numbers in this project are listed below with their original source.
+
+### IEEE 33-Bus Test System
+
+- **[1]** M. E. Baran and F. F. Wu, "Network reconfiguration in distribution systems for loss reduction and load balancing," *IEEE Trans. Power Delivery*, vol. 4, no. 2, pp. 1401-1407, Apr. 1989. — Source of the IEEE 33-bus benchmark. Base case losses: 202.67 kW. Optimal reconfiguration: 139.55 kW (31.15% reduction). Open switches: 7, 9, 14, 32, 37 (1-indexed).
+- **[2]** S. Civanlar et al., "Distribution feeder reconfiguration for loss reduction," *IEEE Trans. Power Delivery*, 1988. — Load-transfer heuristic. ~146 kW on 33-bus.
+- **[3]** S. K. Goswami and S. K. Basu, "A new algorithm for the reconfiguration of distribution feeders for loss minimization," *IEEE Trans. Power Delivery*, 1992. — ~139.55 kW on 33-bus.
+- **[4]** R. S. Jabr et al., "Minimum loss network reconfiguration using mixed-integer convex programming," *IEEE Trans. Power Systems*, 2012. — MILP exact: 139.55 kW.
+- **[5]** M. F. Sulaima et al., "A DNR by Using Rank Evolutionary PSO for Power Loss Minimization," *ISMS*, 2014. — PSO: 146.1 kW (local optimum).
+- **[6]** E. C. Pereira et al., "Distribution Network Reconfiguration Using Iterative Branch Exchange and Clustering Technique," *Energies*, 2023. — 139.55 kW. Applied to 81 real feeders at CEMIG-D (Brazil).
+- **[7]** F. Bohigas-Daranas et al., "Open-source implementation of distribution network reconfiguration methods," *arXiv:2511.22957*, 2025. — Compares 7 methods, confirms 139.55 kW optimal.
+- **[8]** S. H. Dolatabadi et al., "An Enhanced IEEE 33 Bus Benchmark Test System," *IEEE Trans. Power Systems*, 2021. — Enhanced 33-bus with DG, total load 3.715 MW.
+
+### Distribution Loss Reduction: Industry Practice
+
+- **[9]** "Power Distribution Network Reconfiguration Techniques: A Thorough Review," *Sustainability*, 2024. — Survey of 200+ articles. Manual: 5-10%. Automated: 25-34%.
+- **[10]** Bohigas-Daranas et al., 2025 (same as [7]). Confirms 25-34% on real networks.
+- **[11]** "Operational Cost Minimization of Electrical Distribution Network during Switching for Sustainable Operation," *Sustainability*, 2022. — MISOCP on real 71-bus Malaysian network: 25.5%.
+
+### Egypt Energy Data
+
+- **[12]** IEA, "Egypt — Countries & Regions," 2022. — Total generation: 215.8 TWh. Natural gas: 81%.
+- **[13]** "Egypt plans to reduce electricity network loss to 16.83% in FY23/24," *Egypt Today*, 2023. — T&D losses: 22.19% (FY 2021/22), target 16.83%.
+- **[14]** CEIC, "Egypt: Electric Power T&D Losses: % of Output." — Historical losses: 11.15% (2014), 22.16% (1985).
+- **[15]** EEHC, "Geographical distribution of electricity distribution companies." — 9 regional distribution companies.
+- **[16]** Iskraemeco, "Improving energy efficiency — NCEDC." — 500,000 smart meters, AMI, SCADA.
+- **[17]** PRIME Alliance, "PRIME 1.4 Roll-out of 63,000 Smart Meters in Egypt," 2022. — 300,000 more planned.
+
+### Global Data & Emission Factors
+
+- **[18]** IEA, "Electricity 2025 — Supply." — Global demand grew 4.3% in 2024.
+- **[19]** World Bank, "Electric power T&D losses (% of output)." — Global: 7-10%.
+- **[20]** IEA, "Emission Factors." — Global average: 0.475 kg CO₂/kWh.
+- **[21]** Egypt grid emission factor: ~0.50 kg CO₂/kWh (derived from 88% gas).
+- **[22]** Strategic Market Research, "ADMS Market, 2024-2030." — $3.8B (2024), projected $10.5B by 2030.
+- **[23]** Intent Market Research, "ADMS Market, 2024-2030." — Cloud-based ADMS fastest-growing.
+- **[24]** U.S. EPA, "Greenhouse Gas Equivalencies Calculator." — 21 kg CO₂/tree/year, 4.6 t CO₂/car/year.
+
+### Power System Simulation
+
+- **[25]** L. Thurner et al., "pandapower — An Open-Source Python Tool for Power Systems," *IEEE Trans. Power Systems*, 2018. — Newton-Raphson AC power flow solver.
+- **[26]** MATPOWER, "case33bw — Baran & Wu 33-bus system." — 33 buses, 37 lines, 12.66 kV, 3.715 MW.
+
+---
+
+## API Contract (Frontend Specification)
+
+> Detailed request/response examples for frontend integration.
+
+### Baseline Endpoint
+
+```
+GET /api/baseline/{system}    (system = "case33bw" | "case118")
+```
+
+**Response** (key fields):
+```json
+{
+  "system": "case33bw",
+  "network": { "n_buses": 33, "n_lines": 37, "n_tie_lines": 5, "total_load_mw": 3.715 },
+  "power_flow": {
+    "converged": true, "total_loss_kw": 202.68, "loss_pct": 5.17,
+    "min_voltage_pu": 0.9131, "voltage_violations": 21,
+    "bus_voltages": [1.0, 0.997, "..."],
+    "line_loadings_pct": [47.2, "..."],
+    "line_losses_kw": [12.5, "..."]
+  },
+  "buses": [{ "index": 0, "vn_kv": 12.66, "load_mw": 0.0, "is_slack": true }, "..."],
+  "lines": [{ "index": 0, "from_bus": 0, "to_bus": 1, "in_service": true, "is_tie": false }, "..."]
+}
+```
+
+### Optimize Endpoint
+
+```
+POST /api/optimize
+Body: { "system": "case33bw", "method": "hybrid", "quantum_iters": 300 }
+```
+
+**Response** includes `baseline`, `optimized` (with `open_lines`), `impact` (loss reduction, CO₂, cost), `candidates`, and `timings`.
+
+### Compare Endpoint
+
+```
+POST /api/compare
+Body: { "system": "case33bw", "methods": ["classical", "quantum", "hybrid"] }
+```
+
+**Response** includes per-method `optimized`, `impact`, and `time_sec`.
+
+### Grid Endpoints
+
+```
+GET  /api/grid?system=case33bw       → nodes + branches for React Flow
+POST /api/grid/set-out-of-service    → set lines OOS, run power flow
+GET  /api/grid/{system}/switches     → switch states for all lines
+```
+
+### Additional Endpoints
+
+| Method | Endpoint | Purpose |
+|--------|----------|---------|
+| POST | `/api/simulate` | Custom switch configuration |
+| POST | `/api/simulate/toggle` | Toggle single switch |
+| POST | `/api/digital-twin` | Scenario simulation |
+| POST | `/api/roi` | ROI calculation |
+| POST | `/api/report` | Generate HTML report |
+| GET | `/api/audit` | Audit log history |
+| GET | `/api/usage` | Usage statistics |
+
+---
+
+<p align="center">
+  Built with ⚡ by the OptiQ Team
+</p>

requirements.txt

@@ -0,0 +1,27 @@
+# OptiQ — Hybrid Quantum-AI-Classical Grid Optimization
+# Tested on Python 3.11 + conda (projects env)
+
+# Power system simulation
+pandapower>=3.4.0
+numba>=0.63.0
+
+# Quantum optimization (Qiskit 2.x ecosystem)
+qiskit>=2.3.0
+qiskit-optimization>=0.7.0
+
+# AI / GNN (PyTorch Geometric)
+# PyTorch 2.9+cu128 installed via conda separately
+torch-geometric>=2.7.0
+
+# API
+fastapi>=0.128.0
+uvicorn[standard]>=0.40.0
+python-multipart>=0.0.20
+python-dotenv>=1.0.0
+
+# Visualization & data
+plotly>=6.5.0
+numpy>=2.3.0
+pandas>=2.3.0
+scipy>=1.16.0
+networkx>=3.4.0