Hugging Face's logo

Spaces:
AhmedSamir1598
/
OptiQ
Running

App Files Community
OptiQ / README.md
AhmedSamir1598's picture
AhmedSamir1598
Add Hugging Face Spaces deployment support
bcd2ced
preview code
|
raw
history blame contribute delete
40.4 kB
metadata 
title: OptiQ
emoji: ⚡
colorFrom: blue
colorTo: green
sdk: docker
pinned: false

⚡ 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
  2. Results
  3. Architecture
  4. Hybrid Pipeline — How It Works
  5. Mathematical Foundations
  6. Project Structure
  7. Backend API Endpoints
  8. Frontend Pages
  9. Database Schema
  10. Authentication
  11. Grid Visualization & Out-of-Service Lines
  12. Evaluation & Impact Metrics
  13. Egypt-Specific Scaling & Implementation
  14. Configuration
  15. Installation
  16. Running the Application
  17. Deployment with ngrok
  18. Environment Variables
  19. Tech Stack
  20. 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.

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⁡x  xTQ x\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(accept)={1if ΔE<0e−ΔE/TotherwiseP(\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

L=∥Vpred−Vtrue∥2⏟MSE+λv⋅mean[max⁡(0,vmin−Vm)2+max⁡(0,Vm−vmax)2]⏟Voltage bound violation\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):

λv←max⁡ ⁣(0,  λv+η⋅violation)\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:

Si=Vi∑k=1nYik∗Vk∗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 

# 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 

cd frontend
npm install
npm run build    # Produces frontend/dist/ served by FastAPI
cd ..

Running the Application

Quick Start 

# 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) 

# 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 

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:

    cp .env.example .env

  2. Add your ngrok authtoken (get from ngrok.com):

    NGROK_AUTHTOKEN=your_authtoken_here
NGROK_DOMAIN=your-custom-domain.ngrok-free.app

  3. Start the server — ngrok tunnel opens automatically:

    ./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) 

# 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 

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:

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 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):

{
  "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

Built with ⚡ by the OptiQ Team