# Q-Raftar (کیو-رفتار) — Complete Technical Documentation & LLM Knowledge Base
*Karachi Quantum Transit Optimizer & Spatial Intelligence Platform*
*SBF Consultancy Corporate Social Responsibility Civic Initiative (Fee-Sabeel-Allah)*

---

## 1. Executive Summary & Urban Context

Karachi is Pakistan's largest economic hub and financial capital, home to over 20 million residents. Despite generating over 20% of national GDP, the city suffers from acute public transit starvation:
- Estimated mass transit requirement: 15,000+ modern standard buses.
- Present operational fleet: Fewer than 1,100 active mass transit buses (inclusive of Peoples Bus Service, Green Line BRT, and private minibuses).
- Resulting crisis: Chronic commuter delay, unsafe vehicle overloading (crush loads exceeding 180% capacity), excessive deadhead mileage between maintenance depots, and uncontrolled diesel fuel expenditure in Pakistani Rupees (PKR).

Q-Raftar was engineered as a civic-tech public good by SBF Consultancy to formulate public transit fleet allocation and corridor routing as a Quadratic Unconstrained Binary Optimization (QUBO) problem solvable on quantum processors (IBM Quantum via Qiskit) and hybrid classical solvers.

---

## 2. Mathematical Formulation (QUBO & Hamiltonian)

The transit optimization is formulated as a graph energy minimization problem:

$$H = A \sum_{i} \left( \sum_{k} x_{i,k} - 1 \right)^2 + B \sum_{k} \left( \sum_{i} c_i x_{i,k} - C_{\text{target}} \right)^2 + C \sum_{(i,j) \in E} d_{i,j} x_{i,k} x_{j,k}$$

Where:
- $x_{i,k} \in \{0, 1\}$: Binary decision variable indicating whether transit hub/stop $i$ is assigned to bus route $k$.
- Term 1 (Constraint Penalty $A$): Ensures each high-demand transit hub receives adequate line coverage.
- Term 2 (Capacity Balancing $B$): Minimizes the variance between allocated passenger carrying capacity $c_i$ and surveyed commuter demand $C_{\text{target}}$.
- Term 3 (Deadhead & Fuel Penalty $C$): Minimizes the inter-hub distance $d_{i,j}$ and road friction along OpenStreetMap snapped geometries.

Execution Methods:
1. **IBM Quantum QPUs**: Deployed to IBM Quantum Runtime V2 backends (e.g., ibm_brisbane, ibm_kyiv, ibm_sherbrooke) utilizing Qiskit Nature/Optimization converters to Pauli-Z spin operators.
2. **Qiskit Aer Simulator**: High-fidelity local quantum circuit simulation up to 32 state qubits.
3. **Simulated Annealing Heuristics**: High-speed classical fallbacks for real-time interactive browser parameter adjustments.

---

## 3. Surveyed Corridors & Demand-Supply Matrix

Q-Raftar actively tracks 8 primary arterial transit lines across 40 strategic Karachi hubs:

1. **PBS Route 1 (Model Colony to Merewether Tower via Shahrah-e-Faisal)**:
   - Distance: 28.4 km | Speed: 24 km/h | Current Fleet: 28 buses | Headway: 12 min
   - Daily Demand: 42,000 passengers | Supply: 24,000 seats | Status: Severe Overload (Ratio: 1.75)
   - Key Hubs: Model Colony, Malir Halt, Star Gate, Airport, Karsaz, FTC, Metropole, Tower.

2. **PBS Route 2 (North Karachi to Indus Hospital Korangi via Rashid Minhas)**:
   - Distance: 34.2 km | Speed: 22 km/h | Current Fleet: 24 buses | Headway: 15 min
   - Daily Demand: 38,500 passengers | Supply: 19,200 seats | Status: Severe Overload (Ratio: 2.01)
   - Key Hubs: Power House North Karachi, Nagan Chowrangi, Sohrab Goth, NIPA, Drigh Road, Korangi Crossing, Indus Hospital.

3. **PBS Route 3 (Nagan Chowrangi to Korangi Industrial via Liaquatabad & FTC)**:
   - Distance: 26.8 km | Speed: 21 km/h | Current Fleet: 20 buses | Headway: 16 min
   - Daily Demand: 31,000 passengers | Supply: 16,000 seats | Status: Severe Overload (Ratio: 1.94)

4. **Green Line BRT (Surjani Town to Numaish Central Interchange)**:
   - Distance: 21.0 km | Speed: 32 km/h | Current Fleet: 80 articulated buses | Headway: 4.5 min
   - Daily Demand: 68,000 passengers | Supply: 62,000 seats | Status: Optimal (Ratio: 1.10)
   - Dedicated grade-separated median corridor with off-board ticketing.

5. **PBS Route 9 (Gulshan-e-Hadeed to Tower via National Highway & Malir)**:
   - Distance: 44.5 km | Speed: 26 km/h | Current Fleet: 18 buses | Headway: 22 min
   - Daily Demand: 29,000 passengers | Supply: 12,500 seats | Status: Severe Overload (Ratio: 2.32)

6. **PBS Route 10 (Numaish Chowrangi to Sea View Clifton via Saddar & Teen Talwar)**:
   - Distance: 14.6 km | Speed: 19 km/h | Current Fleet: 16 buses | Headway: 14 min
   - Daily Demand: 18,500 passengers | Supply: 14,000 seats | Status: High Load (Ratio: 1.32)

7. **Orangi Feeder Route (Orangi Town Sector 5 to Clifton Sub-Terminal)**:
   - Distance: 22.3 km | Speed: 18 km/h | Current Fleet: 14 minibuses | Headway: 20 min
   - Daily Demand: 34,000 passengers | Supply: 11,200 seats | Status: Severe Overload (Ratio: 3.04)

8. **Malir Cantt Express (Malir Cantt Check Post 6 to Saddar Electronic Market)**:
   - Distance: 24.1 km | Speed: 25 km/h | Current Fleet: 12 buses | Headway: 25 min
   - Daily Demand: 16,000 passengers | Supply: 9,600 seats | Status: High Load (Ratio: 1.67)

---

## 4. Operational & Economic Impact (OPEX Engine)

- **Diesel Price Basis**: Dynamic benchmark (default PKR 285.0 per liter).
- **Deadhead Reduction**: Quantum network optimization reduces empty depot-to-route travel by up to 38.4%.
- **Average Passenger Wait Time**: Reduced from 21.4 minutes to 8.2 minutes with synchronized headways.
- **Projected Diesel Savings**: ~149,500 liters monthly across the 8 surveyed corridors (~PKR 42.6M monthly OPEX savings).
- **CO2 Emission Abatement**: ~396 metric tons of CO2 eliminated per month.

---

## 5. Technology Stack & Architecture

- **Frontend**: Next.js 15 App Router, React 19, TypeScript, Tailwind CSS, Framer Motion, Zustand.
- **Cartographic Engines**: MapLibre GL JS, Deck.gl ArcLayer & PathLayer, Google Maps Directions snapping.
- **Quantum Optimization Core**: FastAPI, Python 3.11, Qiskit Runtime V2, IBM Quantum Qiskit Aer, OSMnx, NetworkX.
- **Standards Compliance**: W3C Semantic HTML5, Schema.org JSON-LD (SoftwareApplication, Dataset, FAQPage, Organization), Dublin Core, OpenGraph 3.0, Twitter Cards, WCAG 2.1 AA accessibility.

---

## 6. Official Links & SBF Consultancy Reference

- **Parent Organization**: SBF Consultancy (https://sbf-consultancy.net)
- **Charter**: Corporate Social Responsibility (CSR) — Fee-Sabeel-Allah Public Welfare
- **Platform Sitemap Page**: /sitemap
- **XML Sitemap**: /sitemap.xml
- **Keywords Taxonomy Registry**: /keywords.json
- **Standard LLMs Overview**: /llms.txt