` 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 |
---
Built with ⚡ by the OptiQ Team
