FairShare-WiFi

A SimPy-based discrete-event WiFi simulation framework that compares classic packet schedulers (FIFO, Priority, WFQ) against four contextual multi-armed bandit schedulers (PlainUCB, LinUCB, DLinUCB, DKernelUCB), measured by Jain's Fairness Index, normalized throughput, and a composite reward.

Headline result

LinUCB achieves JFI 0.6722 vs FIFO 0.5767 -- a 16.5 percent fairness improvement -- while still maintaining competitive throughput. The bandit schedulers consistently dominate the fairness axis, while WFQ and FIFO retain a slight throughput edge.

Scheduler	Jain Index	Norm. Throughput	Composite Reward
FIFO	0.5767	0.8140	0.6479
Priority	0.5778	0.8111	0.6478
WFQ	0.6003	0.8089	0.6629
PlainUCB	0.6503	0.6745	0.6576
LinUCB	0.6722	0.6301	0.6596
DLinUCB	0.6532	0.6487	0.6519
DKernelUCB	0.6123	0.6415	0.6211

Composite reward = 0.7 x Jain Index + 0.3 x Normalized Throughput.

Adaptation under non-stationary traffic

When the traffic mix changes mid-simulation (priority fraction shifts, queue depth varies), bandit schedulers re-converge on the new optimum within the first few hundred decision rounds while static policies do not adapt.

Pareto frontier

Sweeping the composite-reward fairness weight from 0 to 1 traces the fairness-vs-throughput Pareto frontier. The bandit schedulers occupy the high-fairness end of the frontier; WFQ and FIFO occupy the high-throughput end.

What it does

The simulator models a single WiFi access point serving multiple users with heterogeneous traffic patterns. Each tick:

1. Users generate packets according to their traffic model (Poisson, ON/OFF, periodic, etc.).
2. The scheduler picks one user to transmit (or applies its weighted round-robin / bandit policy).
3. The metrics layer records per-user throughput, queue depth, and the running Jain's Fairness Index.
4. For bandit schedulers, the reward (JFI + throughput) is fed back to update the per-arm value estimate.

The simulation is deterministic given a seed; reproducibility is built into run_experiments.py.

Schedulers implemented

File	Scheduler	Type
schedulers/fifo.py	FIFO	First-come, first-served (baseline)
schedulers/priority.py	Priority	Strict priority by user class
schedulers/wfq.py	WFQ	Weighted Fair Queueing
schedulers/bandit.py	PlainUCB	UCB1 over discrete user arms
schedulers/bandit.py	LinUCB	Linear UCB with per-arm context features
schedulers/bandit.py	DLinUCB	Disjoint LinUCB (separate models per arm)
schedulers/bandit.py	DKernelUCB	Disjoint kernelized UCB

The bandit context vector is 4-dimensional: (queue_depth, active_users, priority_fraction, current_jfi). Each scheduler observes this state each decision round and selects an arm.

Repository layout

FairShare-WiFi/
  engine/
    access_point.py             # event-driven AP, packet flow
    simulation.py               # SimPy simulation harness
  schedulers/
    base.py                     # abstract Scheduler interface
    fifo.py, priority.py, wfq.py
    bandit.py                   # PlainUCB, LinUCB, DLinUCB, DKernelUCB
  metrics/
    evaluator.py                # Jain's Fairness Index, throughput, reward
    logger.py                   # per-run CSV / JSON logging
    plots.py                    # matplotlib plot generation
    report.py                   # summary table builder
  frontend/
    app.py                      # Flask dashboard
    templates/index.html        # live metrics UI
  results/
    exp{1..5}_summary.json      # per-experiment summary
    exp*_timeseries.csv         # per-step time series
    plots/                      # 12 PNG figures
  docs/
    DOCUMENTATION.md            # design notes
    paper.pdf                   # IEEE-format conference paper
    proposal.pdf                # original project proposal
  wireless_models.py            # channel / traffic models
  run_experiments.py            # entry point: runs all 5 experiments
  run_tests.py                  # unit tests
  requirements.txt

Requirements

Python 3.9+ with the packages listed in requirements.txt:

pip install -r requirements.txt

Key dependencies: simpy, numpy, matplotlib, flask (dashboard only).

Run

All five experiments

python run_experiments.py

Writes results/exp<N>_*.csv time series, exp<N>_summary.json aggregates, and regenerates all plots in results/plots/.

Experiments

1. Static scheduler comparison (FIFO vs Priority vs WFQ)
2. Bandit vs static schedulers under stationary traffic
3. Non-stationary traffic -- bandit adaptability test
4. Ablation study -- cold-start vs warm-start bandit behavior
5. Reward sweep -- fairness-vs-throughput Pareto frontier

Tests

python run_tests.py

Live dashboard

python frontend/app.py

Then open http://localhost:5000 in a browser. The dashboard polls the running simulation and plots metrics in real time.

Paper

A full conference-style writeup is in docs/paper.pdf. It covers the problem formulation, the contextual-bandit framework, the four UCB variants, the experimental protocol, and the result interpretation.