From 619447487844fd11df745a34bd163a881d9aa6c3 Mon Sep 17 00:00:00 2001 From: Koleaje Olayinka <100846558+koleajeolayinka@users.noreply.github.com> Date: Wed, 15 Jul 2026 17:19:43 +0100 Subject: [PATCH 01/13] feat(week-3): add non-iid simulation, analysis memo, and interactive walkthrough --- week-3/.gitignore | 30 ++ week-3/MEMO.md | 29 + week-3/README.md | 118 +++++ week-3/fed/__init__.py | 1 + week-3/fed/_compat.py | 39 ++ week-3/fed/client.py | 66 +++ week-3/fed/data.py | 78 +++ week-3/fed/model.py | 19 + week-3/fed/strategy.py | 48 ++ week-3/main.py | 176 +++++++ week-3/main_flower.py | 119 +++++ week-3/plot.py | 155 ++++++ week-3/requirements.txt | 5 + week-3/walkthrough/app.js | 848 ++++++++++++++++++++++++++++++ week-3/walkthrough/index.html | 309 +++++++++++ week-3/walkthrough/style.css | 961 ++++++++++++++++++++++++++++++++++ 16 files changed, 3001 insertions(+) create mode 100644 week-3/.gitignore create mode 100644 week-3/MEMO.md create mode 100644 week-3/README.md create mode 100644 week-3/fed/__init__.py create mode 100644 week-3/fed/_compat.py create mode 100644 week-3/fed/client.py create mode 100644 week-3/fed/data.py create mode 100644 week-3/fed/model.py create mode 100644 week-3/fed/strategy.py create mode 100644 week-3/main.py create mode 100644 week-3/main_flower.py create mode 100644 week-3/plot.py create mode 100644 week-3/requirements.txt create mode 100644 week-3/walkthrough/app.js create mode 100644 week-3/walkthrough/index.html create mode 100644 week-3/walkthrough/style.css diff --git a/week-3/.gitignore b/week-3/.gitignore new file mode 100644 index 0000000..96026b4 --- /dev/null +++ b/week-3/.gitignore @@ -0,0 +1,30 @@ +# Python Bytecode and Caches +__pycache__/ +*.py[cod] +*$py.class +*.egg-info/ +.pytest_cache/ + +# Virtual Environments +.venv/ +venv/ +env/ + +# Ray temp directories +tmp_ray/ + +# Dataset files (re-used from week-2/data or downloaded) +data/ +MNIST/ + +# Experiment results logs and plots +iid_results.csv +noniid_results.csv +convergence_comparison.png +*.pt +*.pth + +# Editor and OS-specific files +.vscode/ +.idea/ +.DS_Store diff --git a/week-3/MEMO.md b/week-3/MEMO.md new file mode 100644 index 0000000..e19095d --- /dev/null +++ b/week-3/MEMO.md @@ -0,0 +1,29 @@ +# Research Memo: The Impact of Non-IID Data on Federated Learning Convergence + +## 1. Expectations +Before running the experiment, I expected that partitioning the MNIST dataset using a Dirichlet distribution ($\alpha = 0.5$) would significantly slow down model convergence and degrade the final accuracy of Federated Averaging (FedAvg) compared to an IID split, due to the statistical misalignment of local client updates. + +--- + +## 2. Experimental Observations +After executing 10 communication rounds across 5 clients, I observed a clear convergence penalty under the Non-IID data distribution, which is most prominent in the early phases of training: + +* **Initial Round Contrast:** In Round 1, the global model trained on IID partitions achieved a weighted test accuracy of **77.75%** with a loss of **1.2763**. In contrast, the model trained on the Non-IID Dirichlet split reached only **57.63%** accuracy with a much higher loss of **1.6053**—representing a performance gap of **20.12%**. +* **Intermediate Convergence Rate:** The IID simulation climbed steadily and reached over 88% accuracy by Round 4 (**88.05%**), whereas the Non-IID simulation lagged behind, requiring 6 rounds to cross the 87% threshold (**87.01%**). +* **Terminal Convergence Point:** By Round 10, the performance gap narrowed, but a clear deficit remained. The IID model finished at **90.58%** accuracy (loss: **0.3360**), while the Non-IID model reached **89.27%** accuracy (loss: **0.3767**). + +The resulting plot (`convergence_comparison.png`) visually overlays these trends, showing that the Non-IID curve stays consistently below the IID curve, validating the statistical heterogeneity penalty. + +--- + +## 3. Underhood Mechanism: Client Drift +The difference in convergence rates is explained by the mechanism of **client drift** (or objective inconsistency): + +In the IID setup, every client has a representative slice of all 10 digit classes. Therefore, each client's local loss function $F_k(w)$ is a close approximation of the global loss function $f(w)$. During local training, the gradient descent updates of all 5 clients point toward a similar global minimum, meaning their parameter vectors move in aligned directions. + +In the Non-IID setup, the Dirichlet split ($\alpha=0.5$) creates highly skewed class distributions. For example, Client 2 only received 6,138 samples, while Client 3 received 14,830, with certain digits heavily concentrated on specific devices. As a result, each client optimizes its local parameters $w^k$ toward its own biased local minimum $\arg\min F_k(w)$. During the local training epoch, their weights drift in divergent directions in the parameter space. When the server averages these drifted weights, the updates pull against each other. The resulting average represents a compromised model that resolves these conflicting gradients but experiences slower, less stable progress toward the global optimum. + +--- + +## 4. Open Question +This experiment raises an important question: **How does the number of local epochs ($E$) affect the magnitude of client drift?** Specifically, while increasing local epochs reduces communication frequency, does it allow client weights to drift further apart, eventually reaching a point where averaging them becomes counterproductive or even degrades global model performance? diff --git a/week-3/README.md b/week-3/README.md new file mode 100644 index 0000000..f0221eb --- /dev/null +++ b/week-3/README.md @@ -0,0 +1,118 @@ +# Decentralized Training Fellowship: Week 3 +## The Non-IID Problem & Client Drift + +Welcome to Week 3 of the Decentralized Training Fellowship! This week focuses on the single most researched problem in Federated Learning: **Non-IID data**. + +In the real world, the assumption that client devices have independent and identically distributed (IID) samples breaks immediately. A client's local dataset represents only its own unique history and usage patterns. When clients optimize their local models on very different data distributions, their parameters diverge. This is known as **client drift**, and it is the main cause of degraded accuracy and slower convergence in federated optimization. + +--- + +## 1. Vocabulary for This Week + +* **Dirichlet Distribution ($\alpha$):** A continuous multivariate probability distribution. In Federated Learning research, it is the standard method for generating synthetic Non-IID data splits. The concentration parameter $\alpha$ controls the degree of skew: + * **Low $\alpha$ (e.g., $\alpha \to 0$):** High heterogeneity. Each client receives labels from only a few classes (extreme skew). + * **High $\alpha$ (e.g., $\alpha \to \infty$):** High homogeneity. The partition approaches a uniform, IID split. + * **$\alpha = 0.5$:** A standard benchmark for moderate label heterogeneity. +* **Client Drift:** The optimization challenge where client models train on highly biased local objectives and update their weights in conflicting directions. When averaged, the global model results in a compromised middle ground that may fit none of the clients well. +* **Convergence Curve:** A plot tracing model metrics (loss or accuracy) against communication rounds. Under Non-IID splits, the convergence curve will climb slower, oscillate heavily, or plateau at a lower peak compared to IID runs. +* **Statistical Heterogeneity:** The technical term indicating that the probability distributions of data vary across clients ($P_i \neq P_j$ for client $i$ and $j$). + +--- + +## 2. Mathematical Framework + +The federated optimization objective decomposes the global learning problem into a weighted sum of independent local objectives. + +### Global Empirical Risk Minimization +The goal is to find the parameter weights $w$ that minimize the global loss function $f(w)$: + +$$\min_{w} f(w)$$ + +* $w \in \mathbb{R}^d$: The neural network parameters (weights) being trained. +* $f(w)$: The global loss function measuring prediction error. + +### Global Objective Function +Since the server cannot access raw data on edge devices, the global loss is computed as a weighted average of local client losses: + +$$f(w) = \sum_{k=1}^{K} \frac{n_k}{n} F_k(w)$$ + +* $K$: Total number of clients (e.g., $K = 5$). +* $n_k$: The number of training samples on client $k$. +* $n$: The total number of training samples across all clients ($n = \sum_k n_k$). +* $F_k(w)$: The local objective (loss) function of client $k$. + +### Local Objective Function +Each client's local objective is the average loss computed over its unique partition $P_k$: + +$$F_k(w) = \frac{1}{n_k} \sum_{i \in P_k} f_i(w)$$ + +* $P_k$: The set of data indices stored on client $k$. +* $f_i(w)$: The loss computed on a single training example $i$. + +### Federated Averaging (FedAvg) Update +At each round, the server aggregates client models by taking an example-weighted average of their local parameters: + +$$w_{t+1} = \sum_{k=1}^{K} \frac{n_k}{n} w_{t+1}^k$$ + +* $w_{t+1}$: The updated global model weights for the next round. +* $w_{t+1}^k$: The local model weights returned by client $k$ after training on its local dataset. + +--- + +## 3. Study Queue + +* **YouTube:** Search *"non-IID federated learning explained"* to watch visual animations of client drift. Focus on videos (10–15 minutes) showing why local optimizations struggle to converge globally. +* **Paper 1 (Abstract & Intro):** *Tackling the Objective Inconsistency Problem in Heterogeneous Federated Optimization* ([arXiv:2007.07481](https://arxiv.org/abs/2007.07481)). Understand how Non-IID data creates "objective inconsistency" (each client optimizing a different local minimum). +* **Paper 2 (Section 2):** *Advances and Open Problems in Federated Learning* ([arXiv:1912.04977](https://arxiv.org/abs/1912.04977)). Search for the "non-IID" sections to read about types of data skew (label skew, feature skew, quantity skew, and temporal skew). + +--- + +## 4. Setup & Running the Simulations + +### Step 1: Environment Setup +Initialize your virtual environment and install the required dependencies: + +```bash +# Navigate to the week-3 directory +cd week-3 + +# Create a virtual environment +python -m venv .venv +source .venv/bin/activate # Windows: .venv\Scripts\activate + +# Install requirements +pip install -r requirements.txt +``` + +### Step 2: Run the Experiments +The simulation runner in `main.py` is configured to run both IID and Non-IID setups sequentially inside isolated subprocesses. This prevents Ray engine reinitialization conflicts: + +```bash +# Run both simulations for 10 rounds +python main.py +``` + +* **IID Run:** Partitions MNIST uniformly across 5 clients. Saves logs to `iid_results.csv`. +* **Non-IID Run:** Partitions MNIST using a Dirichlet distribution with $\alpha=0.5$ across 5 clients. Saves logs to `noniid_results.csv`. +* **Plotter:** Automatically reads both files and generates `convergence_comparison.png`. + +*If you want to run them individually or with a custom alpha:* +```bash +# Run only IID +python main.py --mode iid + +# Run only Non-IID with extreme skew (alpha = 0.1) +python main.py --mode noniid --alpha 0.1 + +# Run the plotter manually +python plot.py +``` + +### Step 3: Interactive Dashboard Walkthrough +To run the interactive concept dashboard, open `walkthrough/index.html` in any web browser, or use a local development server: + +```bash +# If using Python to host locally: +python -m http.server 8000 +# Then visit http://localhost:8000/walkthrough/ +``` diff --git a/week-3/fed/__init__.py b/week-3/fed/__init__.py new file mode 100644 index 0000000..6badc88 --- /dev/null +++ b/week-3/fed/__init__.py @@ -0,0 +1 @@ +# Expose the fed package. diff --git a/week-3/fed/_compat.py b/week-3/fed/_compat.py new file mode 100644 index 0000000..9cde808 --- /dev/null +++ b/week-3/fed/_compat.py @@ -0,0 +1,39 @@ +"""Environment workaround — import this BEFORE importing ``flwr.simulation``. + +Some environments (notably anaconda installs) ship a TensorFlow whose own +imports are broken — e.g. a TensorFlow/JAX build that expects a newer numpy and +raises ``AttributeError: module 'numpy.dtypes' has no attribute 'StringDType'``. + +Flower only imports TensorFlow for an *optional* GPU-memory helper, and guards +it with ``try: import tensorflow except ModuleNotFoundError``. But a broken TF +raises ``AttributeError`` (not ``ModuleNotFoundError``), so the guard misses it +and the error escapes, taking down ``import flwr.simulation``. + +If the installed TensorFlow is broken, we swap it for a harmless empty stub +module so ``import tensorflow`` simply succeeds. We never call the GPU helper +that would actually touch TF (the model is pure PyTorch, and this is a CPU +simulation), so the stub is enough. This is a no-op when TF imports fine or is +absent; the cleanest long-term fix is a dedicated venv without a broken TF +(see README). +""" + +import sys +import types +from importlib.machinery import ModuleSpec + + +def apply(): + """Replace a broken TensorFlow install with an inert stub module.""" + try: + import tensorflow # noqa: F401 + except ModuleNotFoundError: + return # TF not installed — Flower already handles this fine. + except Exception: + # TF is installed but broken. Drop the half-imported modules and put a + # do-nothing stub in their place so the optional `import tensorflow` + # downstream succeeds. + for name in [m for m in sys.modules if m == "tensorflow" or m.startswith("tensorflow.")]: + del sys.modules[name] + stub = types.ModuleType("tensorflow") + stub.__spec__ = ModuleSpec("tensorflow", loader=None) + sys.modules["tensorflow"] = stub diff --git a/week-3/fed/client.py b/week-3/fed/client.py new file mode 100644 index 0000000..2507f77 --- /dev/null +++ b/week-3/fed/client.py @@ -0,0 +1,66 @@ +"""Flower client for the federated MNIST example with custom data configuration.""" + +import os +import torch +import torch.nn as nn +import flwr as fl +from flwr.common import Context + +from .data import load_data +from .model import MLP + + +class FlowerClient(fl.client.NumPyClient): + def __init__(self, client_id, num_clients=5, data_mode="iid", alpha=0.5): + self.model = MLP() + self.trainloader = load_data( + client_id, num_clients=num_clients, data_mode=data_mode, alpha=alpha + ) + self.criterion = nn.CrossEntropyLoss() + self.optimizer = torch.optim.SGD(self.model.parameters(), lr=0.01) + + def get_parameters(self, config): + return [p.detach().cpu().numpy() for p in self.model.parameters()] + + def set_parameters(self, parameters): + for p, new_p in zip(self.model.parameters(), parameters): + p.data = torch.tensor(new_p) + + def fit(self, parameters, config): + self.set_parameters(parameters) + self.model.train() + for images, labels in self.trainloader: + self.optimizer.zero_grad() + loss = self.criterion(self.model(images), labels) + loss.backward() + self.optimizer.step() + return self.get_parameters(config), len(self.trainloader.dataset), {} + + def evaluate(self, parameters, config): + self.set_parameters(parameters) + self.model.eval() + correct, total, loss_sum = 0, 0, 0.0 + with torch.no_grad(): + for images, labels in self.trainloader: + outputs = self.model(images) + loss_sum += self.criterion(outputs, labels).item() + correct += (outputs.argmax(1) == labels).sum().item() + total += labels.size(0) + + avg_loss = loss_sum / len(self.trainloader) + accuracy = correct / total + return avg_loss, total, {"accuracy": accuracy} + + +def client_fn(context: Context): + # Flower (>=1.x) hands the client a Context. + partition_id = int(context.node_config["partition-id"]) + num_partitions = int(context.node_config["num-partitions"]) + + # Read environment variables set in Ray runtime_env + data_mode = os.environ.get("DATA_MODE", "iid") + alpha = float(os.environ.get("ALPHA", "0.5")) + + return FlowerClient( + partition_id, num_clients=num_partitions, data_mode=data_mode, alpha=alpha + ).to_client() diff --git a/week-3/fed/data.py b/week-3/fed/data.py new file mode 100644 index 0000000..96abb35 --- /dev/null +++ b/week-3/fed/data.py @@ -0,0 +1,78 @@ +"""Data loading and partitioning for the federated MNIST example with Dirichlet Non-IID.""" + +import os +import numpy as np +import torch +from torch.utils.data import DataLoader, Subset, random_split +from torchvision import datasets, transforms + +# MNIST is pre-downloaded in week-2/data and reused here to avoid network requests. +DATA_ROOT = "../week-2/data" + + +def dirichlet_split(dataset, num_clients, alpha=0.5, seed=42): + """Splits a dataset across clients using a Dirichlet distribution over labels.""" + np.random.seed(seed) + + # Fast path for extraction of labels in PyTorch datasets (e.g., MNIST) + if hasattr(dataset, "targets"): + labels = dataset.targets.numpy() + else: + labels = np.array([dataset[i][1] for i in range(len(dataset))]) + + num_classes = len(np.unique(labels)) + client_indices = [[] for _ in range(num_clients)] + + for class_id in range(num_classes): + class_indices = np.where(labels == class_id)[0] + np.random.shuffle(class_indices) + + # Draw class proportions from Dirichlet distribution + proportions = np.random.dirichlet([alpha] * num_clients) + proportions = (proportions * len(class_indices)).astype(int) + + # Adjust remainder to sum exactly to the number of class indices + proportions[-1] = len(class_indices) - proportions[:-1].sum() + + # Partition indices using cumsum + splits = np.split(class_indices, np.cumsum(proportions)[:-1]) + for client_id, split in enumerate(splits): + client_indices[client_id].extend(split.tolist()) + + # Safeguard check: if a client gets 0 indices, transfer from the client with the most indices + for client_id in range(num_clients): + if len(client_indices[client_id]) == 0: + max_client_id = int(np.argmax([len(c) for c in client_indices])) + # Take a full batch (e.g. 32 samples) from the max client + transfer_size = min(32, len(client_indices[max_client_id]) // 2) + if transfer_size > 0: + taken = client_indices[max_client_id][-transfer_size:] + client_indices[max_client_id] = client_indices[max_client_id][:-transfer_size] + client_indices[client_id].extend(taken) + + return [Subset(dataset, indices) for indices in client_indices] + + +def load_data(client_id, num_clients=5, data_mode="iid", alpha=0.5, batch_size=32, seed=42): + """Return a DataLoader holding this client's partition of MNIST. + + Supports both 'iid' (uniform random split) and 'noniid' (Dirichlet label skew split). + """ + transform = transforms.ToTensor() + # Always download MNIST to the same root path DATA_ROOT + dataset = datasets.MNIST( + DATA_ROOT, train=True, download=True, transform=transform + ) + + if data_mode == "iid": + partition_size = len(dataset) // num_clients + lengths = [partition_size] * (num_clients - 1) + lengths.append(len(dataset) - partition_size * (num_clients - 1)) + generator = torch.Generator().manual_seed(seed) + partitions = random_split(dataset, lengths, generator=generator) + elif data_mode == "noniid": + partitions = dirichlet_split(dataset, num_clients, alpha=alpha, seed=seed) + else: + raise ValueError(f"Unknown data_mode: {data_mode}") + + return DataLoader(partitions[client_id], batch_size=batch_size, shuffle=True) diff --git a/week-3/fed/model.py b/week-3/fed/model.py new file mode 100644 index 0000000..11449c7 --- /dev/null +++ b/week-3/fed/model.py @@ -0,0 +1,19 @@ +"""Model definition for the federated MNIST example.""" + +import torch.nn as nn + + +class MLP(nn.Module): + """A simple multi-layer perceptron for MNIST (28x28 -> 10 classes).""" + + def __init__(self): + super().__init__() + self.fc = nn.Sequential( + nn.Flatten(), + nn.Linear(784, 128), + nn.ReLU(), + nn.Linear(128, 10), + ) + + def forward(self, x): + return self.fc(x) diff --git a/week-3/fed/strategy.py b/week-3/fed/strategy.py new file mode 100644 index 0000000..1b20395 --- /dev/null +++ b/week-3/fed/strategy.py @@ -0,0 +1,48 @@ +"""Flower FedAvg strategy with custom CSV logging for training performance comparison.""" + +import csv +from flwr.server.strategy import FedAvg + + +class LoggingFedAvg(FedAvg): + def __init__(self, log_path, **kwargs): + super().__init__(**kwargs) + self.log_path = log_path + self.results_log = [] + # Create CSV file and write header up-front + with open(self.log_path, "w", newline="") as f: + writer = csv.writer(f) + writer.writerow(["round", "accuracy", "loss"]) + + def aggregate_evaluate(self, server_round, results, failures): + aggregated = super().aggregate_evaluate(server_round, results, failures) + if aggregated: + loss, metrics = aggregated + + # Extract and compute weighted accuracy across all reporting clients + if results: + total_examples = sum(res.num_examples for _, res in results) + acc = ( + sum(res.num_examples * res.metrics["accuracy"] for _, res in results) + / total_examples + ) + else: + acc = 0.0 + + self.results_log.append([server_round, acc, loss]) + print(f"Round {server_round} | Accuracy: {acc:.4f} | Loss: {loss:.4f}") + + # Append results to the CSV log file immediately + with open(self.log_path, "a", newline="") as f: + writer = csv.writer(f) + writer.writerow([server_round, acc, loss]) + + # Ensure accuracy is propagated back in the returned metrics + aggregated_metrics = {**(metrics or {}), "accuracy": acc} + return loss, aggregated_metrics + + return aggregated + + def save(self): + # Already saved progressively, but here is a hook for manual saving if needed + pass diff --git a/week-3/main.py b/week-3/main.py new file mode 100644 index 0000000..f47328d --- /dev/null +++ b/week-3/main.py @@ -0,0 +1,176 @@ +"""Entry point: run the federated MNIST simulations using a pure PyTorch runner. + +This script bypasses Ray network/socket constraints in sandboxed environments, +while remaining mathematically identical to Flower's FedAvg. + +Usage: + python main.py # Runs both IID and Non-IID simulations and plots results + python main.py --mode iid # Runs only IID + python main.py --mode noniid --alpha 0.5 # Runs only Non-IID +""" + +import argparse +import copy +import csv +import os +import sys +import torch +import torch.nn as nn + +from fed.data import load_data +from fed.model import MLP + +NUM_CLIENTS = 5 +NUM_ROUNDS = 10 + + +def run_simulation(data_mode, log_path, alpha=0.5): + """Run a federated simulation round-by-round using pure PyTorch.""" + print(f"\n=======================================================") + print(f"Starting {data_mode.upper()} Simulation (Rounds: {NUM_ROUNDS}, Clients: {NUM_CLIENTS})") + print(f"=======================================================\n") + + # Initialize the global server model and loss function + global_model = MLP() + criterion = nn.CrossEntropyLoss() + + # Load dataloaders for each simulated client device + client_loaders = [] + for cid in range(NUM_CLIENTS): + loader = load_data( + client_id=cid, + num_clients=NUM_CLIENTS, + data_mode=data_mode, + alpha=alpha, + seed=42, + ) + client_loaders.append(loader) + print(f"Client {cid + 1} dataset loaded: {len(loader.dataset)} samples.") + + # Truncate CSV log file and write header + with open(log_path, "w", newline="") as f: + writer = csv.writer(f) + writer.writerow(["round", "accuracy", "loss"]) + + # Run communication rounds + for server_round in range(1, NUM_ROUNDS + 1): + # 1. Distribute global model parameters to clients + global_params = copy.deepcopy(global_model.state_dict()) + + client_weights = [] + client_sizes = [] + + # 2. Local client training phase + for cid in range(NUM_CLIENTS): + # Instantiate local client model and load global parameters + local_model = MLP() + local_model.load_state_dict(global_params) + local_model.train() + + optimizer = torch.optim.SGD(local_model.parameters(), lr=0.01) + loader = client_loaders[cid] + + # Train locally for 1 epoch (one pass over client partition) + for images, labels in loader: + optimizer.zero_grad() + outputs = local_model(images) + loss = criterion(outputs, labels) + loss.backward() + optimizer.step() + + # Record model weights and dataset size for FedAvg weighting + client_weights.append(local_model.state_dict()) + client_sizes.append(len(loader.dataset)) + + # 3. Server aggregation phase (Weighted average of client weights) + total_samples = sum(client_sizes) + aggregated_weights = copy.deepcopy(global_model.state_dict()) + + for key in aggregated_weights.keys(): + weighted_sum = torch.zeros_like(aggregated_weights[key], dtype=torch.float32) + for cid in range(NUM_CLIENTS): + weight = client_sizes[cid] / total_samples + weighted_sum += client_weights[cid][key].float() * weight + aggregated_weights[key] = weighted_sum + + # Update the global server model + global_model.load_state_dict(aggregated_weights) + + # 4. Global model evaluation phase + global_model.eval() + client_losses = [] + client_accuracies = [] + + with torch.no_grad(): + for cid in range(NUM_CLIENTS): + loader = client_loaders[cid] + correct, total, loss_sum = 0, 0, 0.0 + for images, labels in loader: + outputs = global_model(images) + loss_sum += criterion(outputs, labels).item() + correct += (outputs.argmax(1) == labels).sum().item() + total += labels.size(0) + + client_losses.append(loss_sum / len(loader)) + client_accuracies.append(correct / total) + + # Example-weighted average calculation (FedAvg) + round_loss = sum(l * n for l, n in zip(client_losses, client_sizes)) / total_samples + round_acc = sum(a * n for a, n in zip(client_accuracies, client_sizes)) / total_samples + + print(f"Round {server_round:02d} | Accuracy: {round_acc:.4f} | Loss: {round_loss:.4f}") + + # Write results log row to CSV + with open(log_path, "a", newline="") as f: + writer = csv.writer(f) + writer.writerow([server_round, round_acc, round_loss]) + + +def main(): + parser = argparse.ArgumentParser(description="Run pure PyTorch FL simulation.") + parser.add_argument( + "--mode", + type=str, + choices=["iid", "noniid", "both"], + default="both", + help="Simulation mode: 'iid', 'noniid', or 'both' (default: both)", + ) + parser.add_argument( + "--alpha", + type=float, + default=0.5, + help="Dirichlet distribution alpha parameter for Non-IID mode (default: 0.5)", + ) + args = parser.parse_args() + + if args.mode == "both": + run_simulation("iid", "iid_results.csv") + run_simulation("noniid", "noniid_results.csv", args.alpha) + + print("\n=== GENERATING CONVERGENCE COMPARISON PLOT ===") + try: + import plot + plot.generate_plot("iid_results.csv", "noniid_results.csv", "convergence_comparison.png") + print("Successfully created 'convergence_comparison.png'.") + except Exception as e: + print(f"Could not generate plot automatically: {e}") + + elif args.mode == "iid": + run_simulation("iid", "iid_results.csv") + try: + import plot + plot.generate_plot("iid_results.csv", "noniid_results.csv", "convergence_comparison.png") + except Exception as e: + pass + + elif args.mode == "noniid": + run_simulation("noniid", "noniid_results.csv", args.alpha) + try: + import plot + plot.generate_plot("iid_results.csv", "noniid_results.csv", "convergence_comparison.png") + except Exception as e: + pass + + +if __name__ == "__main__": + main() diff --git a/week-3/main_flower.py b/week-3/main_flower.py new file mode 100644 index 0000000..09d6512 --- /dev/null +++ b/week-3/main_flower.py @@ -0,0 +1,119 @@ +"""Flower-based simulation orchestrator for the Week 3 fellowship. + +Runs both simulations using Flower's simulation engine and Ray. + +Usage: + python main_flower.py +""" + +import argparse +import os +import subprocess +import sys + + +def run_simulation(data_mode, log_path, alpha=0.5): + """Run a single Flower simulation round in the current process.""" + from fed import _compat + _compat.apply() + + import flwr as fl + from fed.client import client_fn + from fed.strategy import LoggingFedAvg + + NUM_CLIENTS = 5 + NUM_ROUNDS = 10 + + print(f"\n=======================================================") + print(f"Starting {data_mode.upper()} Flower Simulation (Rounds: {NUM_ROUNDS}, Clients: {NUM_CLIENTS})") + print(f"=======================================================\n") + + # Set local environment variables for the main process + os.environ["DATA_MODE"] = data_mode + os.environ["ALPHA"] = str(alpha) + + # Redirect all temporary files to /private/tmp/ray_fellowship which has short paths + local_tmp = "/private/tmp/ray_fellowship" + os.makedirs(local_tmp, exist_ok=True) + os.environ["RAY_TMPDIR"] = local_tmp + os.environ["TMPDIR"] = local_tmp + os.environ["TEMP"] = local_tmp + os.environ["TMP"] = local_tmp + + strategy = LoggingFedAvg( + fraction_fit=1.0, + fraction_evaluate=1.0, + min_fit_clients=NUM_CLIENTS, + min_evaluate_clients=NUM_CLIENTS, + min_available_clients=NUM_CLIENTS, + log_path=log_path, + ) + + fl.simulation.start_simulation( + client_fn=client_fn, + num_clients=NUM_CLIENTS, + config=fl.server.ServerConfig(num_rounds=NUM_ROUNDS), + strategy=strategy, + ray_init_args={ + "_temp_dir": local_tmp, + "runtime_env": { + "env_vars": { + "PYTHONPATH": os.getcwd(), + "DATA_MODE": data_mode, + "ALPHA": str(alpha), + "RAY_TMPDIR": local_tmp, + "TMPDIR": local_tmp, + "TEMP": local_tmp, + "TMP": local_tmp, + }, + "worker_process_setup_hook": "fed._compat.apply", + }, + "include_dashboard": False, + "ignore_reinit_error": True, + }, + ) + + +def main(): + parser = argparse.ArgumentParser(description="Run Flower simulation.") + parser.add_argument( + "--mode", + type=str, + choices=["iid", "noniid", "both"], + default="both", + help="Simulation mode: 'iid', 'noniid', or 'both'", + ) + parser.add_argument( + "--alpha", + type=float, + default=0.5, + help="Dirichlet alpha (default: 0.5)", + ) + args = parser.parse_args() + + if args.mode == "both": + print("\n=== RUNNING IID FLOWER SIMULATION ===") + subprocess.run([sys.executable, "main_flower.py", "--mode", "iid"], check=True) + + print("\n=== RUNNING NON-IID FLOWER SIMULATION ===") + subprocess.run( + [sys.executable, "main_flower.py", "--mode", "noniid", "--alpha", str(args.alpha)], + check=True, + ) + + print("\n=== GENERATING CONVERGENCE COMPARISON PLOT ===") + try: + import plot + plot.generate_plot("iid_results.csv", "noniid_results.csv", "convergence_comparison.png") + except Exception as e: + print(f"Could not generate plot: {e}") + + elif args.mode == "iid": + run_simulation("iid", "iid_results.csv") + + elif args.mode == "noniid": + run_simulation("noniid", "noniid_results.csv", args.alpha) + + +if __name__ == "__main__": + main() diff --git a/week-3/plot.py b/week-3/plot.py new file mode 100644 index 0000000..2e51f7a --- /dev/null +++ b/week-3/plot.py @@ -0,0 +1,155 @@ +"""Script to load IID and Non-IID simulation results from CSV and generate a comparative convergence plot using Pillow. + +This replaces matplotlib to avoid sandbox/network issues, while producing a modern dark-themed chart. + +Usage: + python plot.py +""" + +import csv +from PIL import Image, ImageDraw, ImageFont + + +def load_log(filename): + """Load rounds, accuracy, and loss from a CSV log file.""" + rounds, accs, losses = [], [], [] + with open(filename, "r") as f: + reader = csv.DictReader(f) + for row in reader: + rounds.append(int(row["round"])) + accs.append(float(row["accuracy"])) + losses.append(float(row["loss"])) + return rounds, accs, losses + + +def generate_plot(iid_file="iid_results.csv", noniid_file="noniid_results.csv", output_image="convergence_comparison.png"): + """Load logged CSV results and save an overlaid comparison plot using Pillow.""" + iid_rounds, iid_accs = [], [] + noniid_rounds, noniid_accs = [], [] + + try: + iid_rounds, iid_accs, _ = load_log(iid_file) + except FileNotFoundError: + print(f"Warning: {iid_file} not found. Skipping IID curve.") + + try: + noniid_rounds, noniid_accs, _ = load_log(noniid_file) + except FileNotFoundError: + print(f"Warning: {noniid_file} not found. Skipping Non-IID curve.") + + if not iid_rounds and not noniid_rounds: + print("Error: No result logs found to plot. Run simulations first.") + return + + # Image dimensions + w, h = 900, 550 + # Create dark-themed background matching fellowship dashboard aesthetics (#090d16) + img = Image.new("RGB", (w, h), color=(9, 13, 22)) + draw = ImageDraw.Draw(img) + + try: + font = ImageFont.load_default() + except Exception: + font = None + + # Chart padding + pad_left = 70 + pad_right = 40 + pad_top = 70 + pad_bottom = 60 + chart_w = w - pad_left - pad_right + chart_h = h - pad_top - pad_bottom + + # Color Palette + color_grid = (26, 36, 57) # Grid lines (#1a2439) + color_text = (156, 163, 175) # Text labels (#9ca3af) + color_iid = (59, 130, 246) # IID line - Sleek blue (#3b82f6) + color_noniid = (239, 68, 68) # Non-IID line - Sleek red (#ef4444) + color_border = (55, 65, 81) # Border borders (#374151) + + # 1. Draw Y-axis grid lines and ticks (0.0 to 1.0) + for i in range(6): + val = i / 5.0 + y = pad_top + int(chart_h * (1.0 - val)) + + # Grid line + draw.line([(pad_left, y), (w - pad_right, y)], fill=color_grid, width=1) + + # Label + label_text = f"{val:.1f}" + draw.text((pad_left - 35, y - 6), label_text, fill=color_text, font=font) + + # 2. Draw X-axis grid lines and ticks + max_round = max((iid_rounds or [10]) + (noniid_rounds or [10])) + for r in range(1, max_round + 1): + x = pad_left + int(chart_w * (r - 1) / (max_round - 1)) + + # Grid line + draw.line([(x, pad_top), (x, h - pad_bottom)], fill=color_grid, width=1) + + # Label + draw.text((x - 4, h - pad_bottom + 12), str(r), fill=color_text, font=font) + + # 3. Draw chart border axes + draw.line([(pad_left, pad_top), (pad_left, h - pad_bottom), (w - pad_right, h - pad_bottom)], fill=color_border, width=2) + + # Coordinate mapping helper + def map_coords(round_num, acc): + x = pad_left + int(chart_w * (round_num - 1) / (max_round - 1)) + y = pad_top + int(chart_h * (1.0 - acc)) + return (x, y) + + # 4. Plot IID line & points (solid blue line) + if iid_rounds: + pts = [map_coords(r, acc) for r, acc in zip(iid_rounds, iid_accs)] + for i in range(len(pts) - 1): + draw.line([pts[i], pts[i+1]], fill=color_iid, width=3) + for pt in pts: + # Circle point + draw.ellipse([pt[0]-4, pt[1]-4, pt[0]+4, pt[1]+4], fill=(255, 255, 255), outline=color_iid, width=2) + + # 5. Plot Non-IID line & points (dashed red line) + if noniid_rounds: + pts = [map_coords(r, acc) for r, acc in zip(noniid_rounds, noniid_accs)] + for i in range(len(pts) - 1): + p1, p2 = pts[i], pts[i+1] + # Simple dash generator + steps = 10 + for s in range(steps): + if s % 2 == 0: + x1 = p1[0] + (p2[0] - p1[0]) * s / steps + y1 = p1[1] + (p2[1] - p1[1]) * s / steps + x2 = p1[0] + (p2[0] - p1[0]) * (s + 1) / steps + y2 = p1[1] + (p2[1] - p1[1]) * (s + 1) / steps + draw.line([(x1, y1), (x2, y2)], fill=color_noniid, width=3) + for pt in pts: + # Square point + draw.rectangle([pt[0]-4, pt[1]-4, pt[0]+4, pt[1]+4], fill=(255, 255, 255), outline=color_noniid, width=2) + + # 6. Title and Axis Labels + draw.text((pad_left, 25), "FedAvg Convergence: IID vs. Non-IID MNIST", fill=(255, 255, 255), font=font) + draw.text((pad_left + chart_w // 2 - 50, h - 25), "Communication Round", fill=color_text, font=font) + draw.text((pad_left, pad_top - 20), "Weighted Accuracy", fill=color_text, font=font) + + # 7. Legend panel + leg_x = w - pad_right - 250 + leg_y = pad_top + 15 + draw.rectangle([leg_x, leg_y, w - pad_right - 10, leg_y + 60], fill=(17, 25, 40), outline=color_border) + + # Legend - IID + draw.line([(leg_x + 15, leg_y + 18), (leg_x + 45, leg_y + 18)], fill=color_iid, width=3) + draw.ellipse([leg_x + 27, leg_y + 15, leg_x + 33, leg_y + 21], fill=(255, 255, 255), outline=color_iid, width=2) + draw.text((leg_x + 55, leg_y + 12), "IID (Uniform Split)", fill=color_text, font=font) + + # Legend - Non-IID + draw.line([(leg_x + 15, leg_y + 38), (leg_x + 27, leg_y + 38)], fill=color_noniid, width=3) + draw.line([(leg_x + 33, leg_y + 38), (leg_x + 45, leg_y + 38)], fill=color_noniid, width=3) + draw.rectangle([leg_x + 27, leg_y + 35, leg_x + 33, leg_y + 41], fill=(255, 255, 255), outline=color_noniid, width=2) + draw.text((leg_x + 55, leg_y + 32), "Non-IID (alpha=0.5)", fill=color_text, font=font) + + img.save(output_image) + print(f"Saved plot comparison to: {output_image}") + + +if __name__ == "__main__": + generate_plot() diff --git a/week-3/requirements.txt b/week-3/requirements.txt new file mode 100644 index 0000000..8102467 --- /dev/null +++ b/week-3/requirements.txt @@ -0,0 +1,5 @@ +flwr[simulation]>=1.7,<2.0 +torch>=2.0 +torchvision>=0.15 +matplotlib>=3.5 +numpy<2.0 diff --git a/week-3/walkthrough/app.js b/week-3/walkthrough/app.js new file mode 100644 index 0000000..a2f812f --- /dev/null +++ b/week-3/walkthrough/app.js @@ -0,0 +1,848 @@ +// --- Tab Navigation --- +function switchTab(tabId) { + document.querySelectorAll('.tab-content').forEach(el => el.classList.remove('active')); + document.querySelectorAll('.nav-btn').forEach(el => el.classList.remove('active')); + + document.getElementById(`tab-${tabId}`).classList.add('active'); + document.getElementById(`tab-btn-${tabId}`).classList.add('active'); + + // Trigger canvas resizing or initialization when tab changes + if (tabId === 'drift') { + initDriftCanvas(); + } else if (tabId === 'results') { + initResultsChart(); + } +} + +// --- Copy Terminal Commands --- +function copyText(button) { + const pre = button.previousElementSibling; + navigator.clipboard.writeText(pre.innerText).then(() => { + const originalText = button.innerText; + button.innerText = 'Copied!'; + button.style.background = '#10b981'; + button.style.borderColor = '#10b981'; + button.style.color = '#fff'; + setTimeout(() => { + button.innerText = originalText; + button.style.background = ''; + button.style.borderColor = ''; + button.style.color = ''; + }, 1500); + }); +} + +// --- 1. Dirichlet Split Visualizer --- +const DIGIT_COLORS = [ + '#3b82f6', '#ef4444', '#10b981', '#f59e0b', '#8b5cf6', + '#ec4899', '#06b6d4', '#84cc16', '#a855f7', '#f43f5e' +]; + +function initDirichletPlayground() { + // Generate class legend chips + const legendContainer = document.getElementById('digit-legend'); + legendContainer.innerHTML = ''; + for (let i = 0; i < 10; i++) { + const chip = document.createElement('div'); + chip.className = 'legend-item-chip'; + chip.innerHTML = ` +
+ ${i} + `; + legendContainer.appendChild(chip); + } + updateDirichletSplit(); +} + +// Gamma distribution sampler (Marsaglia and Tsang method) +function sampleGamma(shape, scale = 1.0) { + if (shape < 1) { + let u = Math.random(); + return sampleGamma(shape + 1, scale) * Math.pow(u, 1 / shape); + } + let d = shape - 1/3; + let c = 1 / Math.sqrt(9 * d); + while (true) { + let x = 0, v = 0; + do { + let u = Math.random(); + x = Math.sqrt(-2 * Math.log(u)) * Math.cos(2 * Math.PI * Math.random()); // Box-Muller normal + v = 1 + c * x; + } while (v <= 0); + v = v * v * v; + let u = Math.random(); + let x2 = x * x; + if (u < 1 - 0.0331 * x2 * x2) { + return d * v * scale; + } + if (Math.log(u) < 0.5 * x2 + d * (1 - v + Math.log(v))) { + return d * v * scale; + } + } +} + +// Dirichlet distribution sampler +function sampleDirichlet(alpha, size) { + let samples = []; + let sum = 0; + for (let i = 0; i < size; i++) { + let sample = sampleGamma(alpha, 1.0); + if (sample < 1e-5) sample = 1e-5; // Prevent underflow + samples.push(sample); + sum += sample; + } + return samples.map(s => s / sum); +} + +function updateDirichletSplit() { + const alpha = parseFloat(document.getElementById('alpha-slider').value); + document.getElementById('alpha-val').innerText = alpha.toFixed(2); + + // Update description text dynamically + const desc = document.getElementById('alpha-description'); + if (alpha <= 0.15) { + desc.innerHTML = `Extreme Skew: Clients get data from very few classes. A local client model training on this will have highly biased gradients, causing extreme client drift.`; + desc.style.color = '#ef4444'; + } else if (alpha <= 0.6) { + desc.innerHTML = `Moderate Skew (α=0.5): Standard fellowship setup. Clients share partial overlap, but some digits are heavily concentrated on single devices. Client drift is moderate.`; + desc.style.color = '#f59e0b'; + } else { + desc.innerHTML = `Near-IID Distribution: Class proportions are balanced and stable across clients. Client models optimize in similar directions; convergence is fast and smooth.`; + desc.style.color = '#10b981'; + } + + // Set preset button active state + document.querySelectorAll('.preset-btn').forEach(btn => btn.classList.remove('active')); + if (alpha === 0.10) { + // match preset 0.1 + } + + const numClients = 5; + const numClasses = 10; + const totalSamplesPerClass = 1000; // arbitrary base for visualization + + // Generate Dirichlet proportions matrix: Shape (numClasses, numClients) + let proportions = []; + // Seed pseudo-random generator with a fixed sequence when alpha doesn't change + // to keep layout transition clean, but since we are using Math.random(), let's generate live. + for (let c = 0; c < numClasses; c++) { + proportions.push(sampleDirichlet(alpha, numClients)); + } + + // Convert proportions to client-specific profiles: Shape (numClients, numClasses) + let clientProfiles = []; + for (let client = 0; client < numClients; client++) { + let profile = []; + let totalVal = 0; + for (let c = 0; c < numClasses; c++) { + let classVal = proportions[c][client] * totalSamplesPerClass; + profile.push(classVal); + totalVal += classVal; + } + // Normalize profile so it represents exact percentages + clientProfiles.push(profile.map(v => (v / totalVal) * 100)); + } + + // Render client distribution stacked bar charts + const grid = document.getElementById('clients-distribution-grid'); + grid.innerHTML = ''; + + for (let client = 0; client < numClients; client++) { + const clientRow = document.createElement('div'); + clientRow.className = 'client-row'; + + const label = document.createElement('div'); + label.className = 'client-label'; + label.innerText = `Client ${client + 1}`; + + const barContainer = document.createElement('div'); + barContainer.className = 'client-bars'; + + // Populate segments + for (let c = 0; c < numClasses; c++) { + const pct = clientProfiles[client][c]; + if (pct > 0.5) { // Hide extremely tiny slivers for design cleanliness + const segment = document.createElement('div'); + segment.className = 'bar-segment'; + segment.style.width = `${pct}%`; + segment.style.backgroundColor = DIGIT_COLORS[c]; + segment.setAttribute('data-percent', `Digit ${c}: ${pct.toFixed(1)}%`); + barContainer.appendChild(segment); + } + } + + clientRow.appendChild(label); + clientRow.appendChild(barContainer); + grid.appendChild(clientRow); + } +} + +function setAlphaPreset(val) { + document.getElementById('alpha-slider').value = val; + document.querySelectorAll('.preset-btn').forEach(btn => { + btn.classList.remove('active'); + if (parseFloat(btn.innerText) === val) { + btn.classList.add('active'); + } + }); + updateDirichletSplit(); +} + + +// --- 2. Client Drift Sandbox Simulator --- +let driftCtx = null; +let driftCanvas = null; +let driftSimInterval = null; +let driftState = { + globalW: { x: 100, y: 300 }, // Start point of optimization + clientOptima: [ + { x: 300, y: 120, color: '#3b82f6' }, // Client 1 Local optimum (Blue) + { x: 480, y: 280, color: '#ef4444' }, // Client 2 Local optimum (Red) + { x: 380, y: 200, color: '#10b981' } // Client 3 Local optimum (Green) + ], + globalOptimum: { x: 386.6, y: 200 }, // Global average optimum + trajectories: [], // stores steps of clients + currentStep: 0, + maxSteps: 4, // Local epochs E + isSimulating: false, + skewMode: 'skewed' +}; + +function initDriftCanvas() { + driftCanvas = document.getElementById('drift-canvas'); + if (!driftCanvas) return; + driftCtx = driftCanvas.getContext('2d'); + resetDriftSim(); + drawDriftFrame(); +} + +function resetDriftSim() { + if (driftSimInterval) clearInterval(driftSimInterval); + driftState.isSimulating = false; + driftState.currentStep = 0; + + // Starting global weights + driftState.globalW = { x: 90, y: 310 }; + + // Set optimum points based on mode + if (driftState.skewMode === 'iid') { + // In IID mode, all client local loss minimums align with the global minimum + driftState.clientOptima = [ + { x: 400, y: 180, color: '#3b82f6' }, + { x: 400, y: 180, color: '#ef4444' }, + { x: 400, y: 180, color: '#10b981' } + ]; + driftState.globalOptimum = { x: 400, y: 180 }; + } else { + // In Non-IID mode, client loss minimums are pulled in different directions + driftState.clientOptima = [ + { x: 300, y: 110, color: '#3b82f6' }, // Client 1 + { x: 500, y: 300, color: '#ef4444' }, // Client 2 + { x: 400, y: 160, color: '#10b981' } // Client 3 + ]; + // Weighted center of local minima + driftState.globalOptimum = { x: 400, y: 190 }; + } + + // Initialize trajectories holding starting points + driftState.trajectories = [ + [{ x: driftState.globalW.x, y: driftState.globalW.y }], // C1 + [{ x: driftState.globalW.x, y: driftState.globalW.y }], // C2 + [{ x: driftState.globalW.x, y: driftState.globalW.y }] // C3 + ]; + + document.getElementById('drift-play-text').innerText = 'Simulate Round'; + document.getElementById('drift-distance-metric').innerText = 'Client Drift: 0.00'; + drawDriftFrame(); +} + +function setDriftSkew(mode) { + driftState.skewMode = mode; + document.getElementById('btn-drift-iid').classList.toggle('active', mode === 'iid'); + document.getElementById('btn-drift-skewed').classList.toggle('active', mode === 'skewed'); + resetDriftSim(); +} + +function updateDriftParams() { + const val = parseInt(document.getElementById('drift-epochs').value); + document.getElementById('drift-epochs-val').innerText = val; + driftState.maxSteps = val; + resetDriftSim(); +} + +function drawDriftFrame() { + if (!driftCtx) return; + driftCtx.clearRect(0, 0, driftCanvas.width, driftCanvas.height); + + // 1. Draw contour maps for client loss landscapes + drawLossContours(); + + // 2. Draw global and local optimum points + // Draw Client Minima + driftState.clientOptima.forEach((opt, idx) => { + if (driftState.skewMode === 'skewed') { + driftCtx.beginPath(); + driftCtx.arc(opt.x, opt.y, 6, 0, 2*Math.PI); + driftCtx.fillStyle = opt.color; + driftCtx.fill(); + driftCtx.strokeStyle = '#fff'; + driftCtx.lineWidth = 1.5; + driftCtx.stroke(); + + driftCtx.fillStyle = '#fff'; + driftCtx.font = 'bold 9px Outfit'; + driftCtx.fillText(`C${idx+1} Min`, opt.x - 15, opt.y - 12); + } + }); + + // Draw Global Minimum + driftCtx.beginPath(); + driftCtx.arc(driftState.globalOptimum.x, driftState.globalOptimum.y, 8, 0, 2*Math.PI); + driftCtx.fillStyle = '#10b981'; + driftCtx.fill(); + driftCtx.strokeStyle = '#fff'; + driftCtx.lineWidth = 2; + driftCtx.stroke(); + + driftCtx.fillStyle = '#fff'; + driftCtx.font = 'bold 11px Outfit'; + driftCtx.fillText("Global Optimum", driftState.globalOptimum.x - 40, driftState.globalOptimum.y - 15); + + // 3. Draw client trajectories (dotted lines) + driftState.trajectories.forEach((traj, cIdx) => { + driftCtx.beginPath(); + driftCtx.moveTo(traj[0].x, traj[0].y); + for (let i = 1; i < traj.length; i++) { + driftCtx.lineTo(traj[i].x, traj[i].y); + } + driftCtx.strokeStyle = driftState.clientOptima[cIdx].color; + driftCtx.lineWidth = 2; + driftCtx.setLineDash([4, 4]); + driftCtx.stroke(); + driftCtx.setLineDash([]); + + // Draw last node position of client + const lastPt = traj[traj.length - 1]; + driftCtx.beginPath(); + driftCtx.arc(lastPt.x, lastPt.y, 4, 0, 2*Math.PI); + driftCtx.fillStyle = driftState.clientOptima[cIdx].color; + driftCtx.fill(); + }); + + // 4. Draw global model trajectory (solid white line) + // We will draw it from the start to the aggregated point + if (driftState.currentStep === driftState.maxSteps) { + // Draw aggregated global step + const c1Last = driftState.trajectories[0][driftState.trajectories[0].length - 1]; + const c2Last = driftState.trajectories[1][driftState.trajectories[1].length - 1]; + const c3Last = driftState.trajectories[2][driftState.trajectories[2].length - 1]; + + const avgX = (c1Last.x + c2Last.x + c3Last.x) / 3; + const avgY = (c1Last.y + c2Last.y + c3Last.y) / 3; + + // Draw lines from client models to the aggregated global model + driftCtx.beginPath(); + driftState.clientOptima.forEach((opt, idx) => { + const last = driftState.trajectories[idx][driftState.trajectories[idx].length - 1]; + driftCtx.moveTo(last.x, last.y); + driftCtx.lineTo(avgX, avgY); + }); + driftCtx.strokeStyle = 'rgba(255, 255, 255, 0.25)'; + driftCtx.lineWidth = 1.5; + driftCtx.stroke(); + + // Draw solid global trajectory line + driftCtx.beginPath(); + driftCtx.moveTo(driftState.globalW.x, driftState.globalW.y); + driftCtx.lineTo(avgX, avgY); + driftCtx.strokeStyle = '#fff'; + driftCtx.lineWidth = 3; + driftCtx.stroke(); + + // Draw Global Model weights point + driftCtx.beginPath(); + driftCtx.arc(avgX, avgY, 6, 0, 2*Math.PI); + driftCtx.fillStyle = '#fff'; + driftCtx.fill(); + driftCtx.strokeStyle = '#000'; + driftCtx.lineWidth = 1.5; + driftCtx.stroke(); + + driftCtx.fillStyle = '#fff'; + driftCtx.font = 'bold 11px Outfit'; + driftCtx.fillText("w(t+1)", avgX + 10, avgY + 4); + } + + // Draw initial global weight w(t) + driftCtx.beginPath(); + driftCtx.arc(driftState.globalW.x, driftState.globalW.y, 6, 0, 2*Math.PI); + driftCtx.fillStyle = '#f59e0b'; + driftCtx.fill(); + driftCtx.strokeStyle = '#fff'; + driftCtx.lineWidth = 1.5; + driftCtx.stroke(); + driftCtx.fillStyle = '#fff'; + driftCtx.font = 'bold 11px Outfit'; + driftCtx.fillText("w(t)", driftState.globalW.x - 28, driftState.globalW.y + 4); +} + +function drawLossContours() { + // Generate simple concentric circles/ellipses around optima + const numContours = 4; + + if (driftState.skewMode === 'iid') { + // Only draw global contours + for (let r = 1; r <= numContours; r++) { + driftCtx.beginPath(); + driftCtx.arc(driftState.globalOptimum.x, driftState.globalOptimum.y, r * 45, 0, 2*Math.PI); + driftCtx.strokeStyle = 'rgba(16, 185, 129, 0.08)'; + driftCtx.lineWidth = 2; + driftCtx.stroke(); + } + } else { + // Draw local client contours + driftState.clientOptima.forEach(opt => { + for (let r = 1; r <= numContours; r++) { + driftCtx.beginPath(); + driftCtx.ellipse(opt.x, opt.y, r * 28, r * 20, Math.PI / 6, 0, 2*Math.PI); + driftCtx.strokeStyle = opt.color + '0d'; // hex with alpha + driftCtx.lineWidth = 1.5; + driftCtx.stroke(); + } + }); + } +} + +function toggleDriftSim() { + if (driftState.isSimulating) { + resetDriftSim(); + return; + } + + driftState.isSimulating = true; + document.getElementById('drift-play-text').innerText = 'Stop Simulation'; + + driftSimInterval = setInterval(() => { + if (driftState.currentStep < driftState.maxSteps) { + // Local training updates + driftState.currentStep++; + + // Advance each client toward its local minimum + for (let c = 0; c < 3; c++) { + const opt = driftState.clientOptima[c]; + const traj = driftState.trajectories[c]; + const currentPos = traj[traj.length - 1]; + + // Gradient step: move 20% closer to the target minimum + const lr = 0.22; + const nextX = currentPos.x + (opt.x - currentPos.x) * lr; + const nextY = currentPos.y + (opt.y - currentPos.y) * lr; + traj.push({ x: nextX, y: nextY }); + } + + // Calculate drift metric: standard deviation of client updates + const c1Last = driftState.trajectories[0][driftState.trajectories[0].length - 1]; + const c2Last = driftState.trajectories[1][driftState.trajectories[1].length - 1]; + const c3Last = driftState.trajectories[2][driftState.trajectories[2].length - 1]; + const avgX = (c1Last.x + c2Last.x + c3Last.x) / 3; + const avgY = (c1Last.y + c2Last.y + c3Last.y) / 3; + + const dist1 = Math.sqrt((c1Last.x - avgX)**2 + (c1Last.y - avgY)**2); + const dist2 = Math.sqrt((c2Last.x - avgX)**2 + (c2Last.y - avgY)**2); + const dist3 = Math.sqrt((c3Last.x - avgX)**2 + (c3Last.y - avgY)**2); + const avgDrift = (dist1 + dist2 + dist3) / 3; + + document.getElementById('drift-distance-metric').innerText = `Client Drift: ${avgDrift.toFixed(2)} px`; + drawDriftFrame(); + } else { + // Simulation finished + clearInterval(driftSimInterval); + document.getElementById('drift-play-text').innerText = 'Simulate Round'; + } + }, 300); +} + + +// --- 3. Live CSV Results Plotter --- +let chartCanvas = null; +let chartCtx = null; +let iidPlotData = []; +let nonIidPlotData = []; + +// Pre-loaded logs in case user hasn't run simulation yet +const defaultIIDData = [ + { round: 1, accuracy: 0.782, loss: 1.250 }, + { round: 2, accuracy: 0.845, loss: 0.713 }, + { round: 3, accuracy: 0.869, loss: 0.545 }, + { round: 4, accuracy: 0.881, loss: 0.467 }, + { round: 5, accuracy: 0.888, loss: 0.423 }, + { round: 6, accuracy: 0.896, loss: 0.395 }, + { round: 7, accuracy: 0.901, loss: 0.372 }, + { round: 8, accuracy: 0.905, loss: 0.358 }, + { round: 9, accuracy: 0.908, loss: 0.344 }, + { round: 10, accuracy: 0.912, loss: 0.331 } +]; + +const defaultNonIIDData = [ + { round: 1, accuracy: 0.354, loss: 2.102 }, + { round: 2, accuracy: 0.461, loss: 1.834 }, + { round: 3, accuracy: 0.528, loss: 1.621 }, + { round: 4, accuracy: 0.591, loss: 1.432 }, + { round: 5, accuracy: 0.638, loss: 1.298 }, + { round: 6, accuracy: 0.652, loss: 1.221 }, + { round: 7, accuracy: 0.641, loss: 1.254 }, // oscillation + { round: 8, accuracy: 0.678, loss: 1.152 }, + { round: 9, accuracy: 0.694, loss: 1.094 }, + { round: 10, accuracy: 0.702, loss: 1.042 } +]; + +function initResultsChart() { + chartCanvas = document.getElementById('results-chart-canvas'); + if (!chartCanvas) return; + chartCtx = chartCanvas.getContext('2d'); + + if (iidPlotData.length === 0 && nonIidPlotData.length === 0) { + loadDefaultPlotData(); + } else { + drawChart(); + } +} + +function loadDefaultPlotData() { + iidPlotData = [...defaultIIDData]; + nonIidPlotData = [...defaultNonIIDData]; + document.getElementById('file-name-iid').innerText = "Default IID Log loaded"; + document.getElementById('file-name-noniid').innerText = "Default Non-IID Log loaded"; + + updateDiscrepancyMetric(); + drawChart(); +} + +function parseCSV(text) { + const lines = text.trim().split('\n'); + if (lines.length < 2) return []; + + const headers = lines[0].toLowerCase().split(','); + const roundIdx = headers.indexOf('round'); + const accIdx = headers.indexOf('accuracy'); + const lossIdx = headers.indexOf('loss'); + + if (roundIdx === -1 || accIdx === -1) { + alert("CSV requires 'round' and 'accuracy' columns."); + return []; + } + + let parsed = []; + for (let i = 1; i < lines.length; i++) { + const parts = lines[i].split(','); + if (parts.length >= headers.length) { + parsed.push({ + round: parseInt(parts[roundIdx]), + accuracy: parseFloat(parts[accIdx]), + loss: lossIdx !== -1 ? parseFloat(parts[lossIdx]) : 0 + }); + } + } + return parsed; +} + +function handleCSVUpload(input, mode) { + const file = input.files[0]; + if (!file) return; + + document.getElementById(`file-name-${mode}`).innerText = file.name; + + const reader = new FileReader(); + reader.onload = function(e) { + const text = e.target.result; + const parsed = parseCSV(text); + if (parsed.length > 0) { + if (mode === 'iid') { + iidPlotData = parsed; + } else { + nonIidPlotData = parsed; + } + updateDiscrepancyMetric(); + drawChart(); + } + }; + reader.readAsText(file); +} + +function updateDiscrepancyMetric() { + const el = document.getElementById('discrepancy-metric'); + if (iidPlotData.length > 0 && nonIidPlotData.length > 0) { + const lastIID = iidPlotData[iidPlotData.length - 1].accuracy * 100; + const lastNonIID = nonIidPlotData[nonIidPlotData.length - 1].accuracy * 100; + const diff = lastIID - lastNonIID; + el.innerHTML = ` +
Round ${iidPlotData.length} IID: ${lastIID.toFixed(1)}%
+
Round ${nonIidPlotData.length} Non-IID: ${lastNonIID.toFixed(1)}%
+
+ Heterogeneity Penalty: -${diff.toFixed(1)}% Accuracy +
+ `; + } else { + el.innerText = "Upload both CSV logs to compute performance penalty."; + } +} + +function drawChart() { + if (!chartCtx) return; + const w = chartCanvas.width; + const h = chartCanvas.height; + chartCtx.clearRect(0, 0, w, h); + + // Padding settings + const paddingLeft = 50; + const paddingRight = 20; + const paddingTop = 30; + const paddingBottom = 40; + + const chartW = w - paddingLeft - paddingRight; + const chartH = h - paddingTop - paddingBottom; + + // Draw grid background lines + chartCtx.strokeStyle = 'rgba(255, 255, 255, 0.05)'; + chartCtx.lineWidth = 1; + for (let i = 0; i <= 5; i++) { + const y = paddingTop + (chartH * i / 5); + chartCtx.beginPath(); + chartCtx.moveTo(paddingLeft, y); + chartCtx.lineTo(w - paddingRight, y); + chartCtx.stroke(); + + // Acc labels + chartCtx.fillStyle = 'var(--text-secondary)'; + chartCtx.font = '10px JetBrains Mono'; + const labelVal = (1.0 - (i / 5)).toFixed(1); + chartCtx.fillText(labelVal, paddingLeft - 30, y + 4); + } + + // Determine max rounds + const maxR = Math.max( + iidPlotData.length > 0 ? iidPlotData[iidPlotData.length - 1].round : 10, + nonIidPlotData.length > 0 ? nonIidPlotData[nonIidPlotData.length - 1].round : 10 + ); + + // Draw round labels + for (let r = 1; r <= maxR; r++) { + const x = paddingLeft + (chartW * (r - 1) / (maxR - 1)); + chartCtx.beginPath(); + chartCtx.moveTo(x, paddingTop); + chartCtx.lineTo(x, h - paddingBottom); + chartCtx.stroke(); + + chartCtx.fillStyle = 'var(--text-secondary)'; + chartCtx.font = '10px JetBrains Mono'; + chartCtx.fillText(r, x - 4, h - paddingBottom + 18); + } + + // Draw axes + chartCtx.strokeStyle = 'rgba(255, 255, 255, 0.15)'; + chartCtx.lineWidth = 1.5; + chartCtx.beginPath(); + chartCtx.moveTo(paddingLeft, paddingTop); + chartCtx.lineTo(paddingLeft, h - paddingBottom); + chartCtx.lineTo(w - paddingRight, h - paddingBottom); + chartCtx.stroke(); + + // Helper to map (round, accuracy) to coordinates + const mapCoords = (round, acc) => { + const x = paddingLeft + (chartW * (round - 1) / (maxR - 1)); + const y = paddingTop + (chartH * (1.0 - acc)); + return { x, y }; + }; + + // Plot IID + if (iidPlotData.length > 0) { + chartCtx.beginPath(); + let pts = iidPlotData.map(d => mapCoords(d.round, d.accuracy)); + chartCtx.moveTo(pts[0].x, pts[0].y); + for (let i = 1; i < pts.length; i++) { + chartCtx.lineTo(pts[i].x, pts[i].y); + } + chartCtx.strokeStyle = '#3b82f6'; + chartCtx.lineWidth = 2.5; + chartCtx.stroke(); + + // Draw points + pts.forEach(pt => { + chartCtx.beginPath(); + chartCtx.arc(pt.x, pt.y, 4, 0, 2*Math.PI); + chartCtx.fillStyle = '#3b82f6'; + chartCtx.fill(); + chartCtx.strokeStyle = '#fff'; + chartCtx.lineWidth = 1; + chartCtx.stroke(); + }); + } + + // Plot Non-IID + if (nonIidPlotData.length > 0) { + chartCtx.beginPath(); + let pts = nonIidPlotData.map(d => mapCoords(d.round, d.accuracy)); + chartCtx.moveTo(pts[0].x, pts[0].y); + for (let i = 1; i < pts.length; i++) { + chartCtx.lineTo(pts[i].x, pts[i].y); + } + chartCtx.strokeStyle = '#ef4444'; + chartCtx.lineWidth = 2.5; + chartCtx.setLineDash([4, 4]); + chartCtx.stroke(); + chartCtx.setLineDash([]); + + // Draw points + pts.forEach(pt => { + chartCtx.beginPath(); + chartCtx.arc(pt.x, pt.y, 4, 0, 2*Math.PI); + chartCtx.fillStyle = '#ef4444'; + chartCtx.fill(); + chartCtx.strokeStyle = '#fff'; + chartCtx.lineWidth = 1; + chartCtx.stroke(); + }); + } +} + + +// --- 4. Multiple Choice Quiz Engine --- +const quizQuestions = [ + { + question: "What does concentration parameter α control in a Dirichlet data split simulation?", + answers: [ + "The model learning rate on the client devices.", + "The volume of local GPU memory allocated for Flower nodes.", + "The degree of label skew across client datasets. Low α creates extreme skew, while high α approaches IID splits." + ], + correctIdx: 2, + explanation: "Correct! The parameter α controls the concentration. When α is small, class samples are split highly unevenly (giving most of a class to just one client). As α gets larger, each client receives a uniform, representative sample of classes." + }, + { + question: "What is the core optimizer mechanic behind the failure of FedAvg to converge quickly under Non-IID conditions?", + answers: [ + "Objective Inconsistency / Client Drift. Local models optimize for local minima that push parameters in conflicting directions, washing out updates upon aggregation.", + "The central server's failure to weight parameter counts by sample volumes.", + "Excessive client network latency stalling gradient calculations." + ], + correctIdx: 0, + explanation: "Correct! Client drift is the core issue. Because datasets differ statistically, the gradient updates of client A and client B pull the shared parameters in opposite directions. The server average washes out this progress, leading to slow or oscillating convergence." + }, + { + question: "Which skew is simulated when Client A holds primarily images of cats, and Client B holds primarily images of dogs?", + answers: [ + "Feature distribution skew", + "Label distribution skew (or prior probability skew)", + "Quantity distribution skew" + ], + correctIdx: 1, + explanation: "Correct! Label distribution skew is when the marginal distribution of class labels P(y) varies across clients, which is the easiest skew to simulate and study." + }, + { + question: "If alpha is set to 0.1, what data distribution would you expect on a client?", + answers: [ + "A balanced mix of all 10 digits (IID uniform distribution).", + "An empty partition due to numerical errors.", + "A dataset dominated by 1 or 2 specific digits with almost zero samples of others." + ], + correctIdx: 2, + explanation: "Correct! Alpha = 0.1 is highly skewed Non-IID. Each client will get massive chunks of a couple classes and none of the rest." + } +]; + +let quizState = { + currentIdx: 0, + score: 0, + selectedIdx: null, + answered: false +}; + +function initQuiz() { + quizState.currentIdx = 0; + quizState.score = 0; + quizState.selectedIdx = null; + quizState.answered = false; + renderQuizQuestion(); +} + +function renderQuizQuestion() { + const card = document.getElementById('quiz-question-card'); + const scoreDisplay = document.getElementById('quiz-score-display'); + const nextBtn = document.getElementById('btn-next-question'); + + nextBtn.classList.add('hidden'); + scoreDisplay.innerText = `Score: ${quizState.score} / ${quizQuestions.length}`; + + if (quizState.currentIdx >= quizQuestions.length) { + card.innerHTML = ` +
+ 🏆 +

Quiz Complete!

+

Your final score: ${quizState.score} out of ${quizQuestions.length}

+ +
+ `; + return; + } + + const q = quizQuestions[quizState.currentIdx]; + + let answersHTML = q.answers.map((ans, idx) => { + return ` +
+ ${String.fromCharCode(65 + idx)} + ${ans} +
+ `; + }).join(''); + + card.innerHTML = ` +
Question ${quizState.currentIdx + 1} of ${quizQuestions.length}
+
${q.question}
+
+ ${answersHTML} +
+ + `; +} + +function selectQuizAnswer(idx) { + if (quizState.answered) return; + + quizState.selectedIdx = idx; + const q = quizQuestions[quizState.currentIdx]; + quizState.answered = true; + + const optEl = document.getElementById(`quiz-opt-${idx}`); + const expBox = document.getElementById('quiz-explanation'); + const nextBtn = document.getElementById('btn-next-question'); + + expBox.innerHTML = `Explanation: ${q.explanation}`; + expBox.classList.remove('hidden'); + nextBtn.classList.remove('hidden'); + + if (idx === q.correctIdx) { + optEl.classList.add('correct'); + quizState.score++; + } else { + optEl.classList.add('wrong'); + document.getElementById(`quiz-opt-${q.correctIdx}`).classList.add('correct'); + } + + const scoreDisplay = document.getElementById('quiz-score-display'); + scoreDisplay.innerText = `Score: ${quizState.score} / ${quizQuestions.length}`; +} + +function nextQuestion() { + quizState.currentIdx++; + quizState.selectedIdx = null; + quizState.answered = false; + renderQuizQuestion(); +} + + +// --- App Initialization --- +window.addEventListener('DOMContentLoaded', () => { + initDirichletPlayground(); + initQuiz(); +}); diff --git a/week-3/walkthrough/index.html b/week-3/walkthrough/index.html new file mode 100644 index 0000000..2c542b1 --- /dev/null +++ b/week-3/walkthrough/index.html @@ -0,0 +1,309 @@ + + + + + + Federated Learning: Week 3 Walkthrough + + + + + + +
+ +
+
+ 🍭 +
+

FedLearn Week 3

+

The Non-IID Challenge & Client Drift Simulator

+
+
+ +
+ + +
+ +
+
+ +
+

Dirichlet Configuration

+

Simulate label skew across clients. The Concentration Parameter (α) controls how data classes are distributed.

+ +
+
+ Concentration Parameter (α) + 0.5 +
+ + +
+ + + +
+
+ +
+
Distribution State
+
+ Dirichlet distribution generates uneven ratios of MNIST classes (0-9) per client. Local updates will be biased. +
+
+ +
+ 💡 Core Concept: Low α means clients have highly biased local datasets, forcing them to learn partial, skewed boundaries. +
+
+ + +
+

Client Class Distributions

+
+ Labels (MNIST Digits 0-9): +
+
+ + +
+ +
+
+
+
+ + +
+
+ +
+

Drift Controls

+

Simulate gradient steps in a 2D parameter space. Observe how client updates fight each other.

+ +
+ +
+ Steps before aggregation + 4 +
+ +
+ +
+ +
+ + +
+
+ +
+ + +
+ +
+
Client Drift Magnitude
+
+ Client Drift: 0.00 +
+
+ +
+ ⚠️ Client Drift: When client models train on non-aligned loss landscapes (red & blue targets), they diverge. Averaging them yields an aggregated global model that may suffer from slower convergence. +
+
+ + +
+
+

Loss Landscape Optimization

+
+ Global Optimum + Client 1 Min + Client 2 Min +
+
+
+ +
+

Colored rings denote loss gradients. Dotted paths show clients optimizing on their unique datasets. Solid path shows aggregated global updates.

+
+
+
+ + +
+
+
+

Step-by-Step Terminal Guide

+

Reproduce this Non-IID experiment locally on your own GPU/CPU. Follow these commands in your shell:

+ +
+
Step 1
+
+

Setup Environment

+

Clone or navigate into the week-3 workspace, initialize a virtual environment, and install PyTorch and Flower.

+
+ 
cd week-3
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
+ +
+
+
+ +
+
Step 2
+
+

Run Both Simulations

+

Execute the sequential orchestrator. This spins up the Flower simulation, runs 10 rounds of IID training followed by 10 rounds of Non-IID training (α=0.5), logging results to individual CSVs.

+
+ 
python main.py
+ +
+
+
+ +
+
Step 3
+
+

View and Compare Logs

+

The plotter script parses `iid_results.csv` and `noniid_results.csv` to overlay convergence curves. Run it manually if you update CSVs.

+
+ 
python plot.py
+ +
+
+
+
+ + +
+
+ + + + fellowship-student@decentralized: ~/week-3 +
+
+
$ python main.py
+
=== [Process 1/2] RUNNING IID SIMULATION ===
+
Starting IID Simulation (Rounds: 10, Clients: 5)
+
Round 1 | Accuracy: 0.7845 | Loss: 1.2210
+
Round 2 | Accuracy: 0.8491 | Loss: 0.6834
+
...
+
Round 10 | Accuracy: 0.9082 | Loss: 0.3541
+
=== [Process 2/2] RUNNING NON-IID SIMULATION ===
+
Starting NONIID Simulation (Rounds: 10, Clients: 5, alpha=0.5)
+
Round 1 | Accuracy: 0.3120 | Loss: 2.1102
+
Round 2 | Accuracy: 0.4498 | Loss: 1.8904
+
...
+
Round 10 | Accuracy: 0.7104 | Loss: 1.0504
+
=== GENERATING CONVERGENCE COMPARISON PLOT ===
+
Successfully created 'convergence_comparison.png'.
+ | +
+
+
+
+ + +
+
+
+

Plot Custom Logs

+

Upload your generated CSVs from your local training to plot them interactively.

+ +
+ + No file uploaded +
+ +
+ + No file uploaded +
+ +
+ +
+ +
+
Accuracy Discrepancy
+
+ Load results to compare. +
+
+
+ + +
+

Live Convergence Plot

+
+ +
+
+ IID Accuracy + Non-IID Accuracy +
+
+
+
+ + +
+
+
+

Fellowship Quiz: Week 3

+

Verify your understanding of Non-IID distributions and convergence optimization.

+
+ +
+ +
+ +
+
Score: 0 / 0
+ +
+
+
+
+
+ + + + diff --git a/week-3/walkthrough/style.css b/week-3/walkthrough/style.css new file mode 100644 index 0000000..59e487a --- /dev/null +++ b/week-3/walkthrough/style.css @@ -0,0 +1,961 @@ +/* --- Global Theme & Custom Variables --- */ +:root { + --bg-dark: #090d16; + --bg-surface: rgba(17, 25, 40, 0.75); + --border-color: rgba(255, 255, 255, 0.08); + --text-primary: #f3f4f6; + --text-secondary: #9ca3af; + --text-muted: #6b7280; + + /* Neon Palettes */ + --accent-blue: #3b82f6; + --accent-blue-glow: rgba(59, 130, 246, 0.35); + --accent-purple: #8b5cf6; + --accent-purple-glow: rgba(139, 92, 246, 0.35); + --accent-pink: #ec4899; + --accent-green: #10b981; + --accent-red: #ef4444; + --accent-orange: #f59e0b; + + /* Fonts */ + --font-heading: 'Outfit', 'Plus Jakarta Sans', sans-serif; + --font-body: 'Plus Jakarta Sans', sans-serif; + --font-mono: 'JetBrains Mono', monospace; +} + +* { + box-sizing: border-box; + margin: 0; + padding: 0; +} + +body { + background-color: var(--bg-dark); + color: var(--text-primary); + font-family: var(--font-body); + min-height: 100vh; + overflow-x: hidden; +} + +/* Custom Scrollbar */ +::-webkit-scrollbar { + width: 6px; + height: 6px; +} +::-webkit-scrollbar-track { + background: var(--bg-dark); +} +::-webkit-scrollbar-thumb { + background: rgba(255, 255, 255, 0.1); + border-radius: 10px; +} +::-webkit-scrollbar-thumb:hover { + background: var(--accent-blue); +} + +/* --- Layout Container --- */ +.app-container { + max-width: 1300px; + margin: 0 auto; + padding: 20px; + display: flex; + flex-direction: column; + min-height: 100vh; +} + +/* --- Navigation Header --- */ +.app-header { + display: flex; + justify-content: space-between; + align-items: center; + padding: 15px 25px; + background: var(--bg-surface); + backdrop-filter: blur(16px); + -webkit-backdrop-filter: blur(16px); + border: 1px solid var(--border-color); + border-radius: 16px; + margin-bottom: 25px; + box-shadow: 0 8px 32px 0 rgba(0, 0, 0, 0.37); +} + +.logo-area { + display: flex; + align-items: center; + gap: 15px; +} + +.logo-icon { + font-size: 32px; + filter: drop-shadow(0 0 10px var(--accent-blue-glow)); + animation: rotate🍭 6s infinite linear; +} + +@keyframes rotate🍭 { + 0% { transform: rotate(0deg); } + 100% { transform: rotate(360deg); } +} + +.logo-text h1 { + font-family: var(--font-heading); + font-size: 20px; + font-weight: 700; + letter-spacing: -0.5px; + background: linear-gradient(135deg, #fff 0%, var(--text-secondary) 100%); + -webkit-background-clip: text; + -webkit-text-fill-color: transparent; +} + +.logo-text p { + font-size: 11px; + color: var(--text-secondary); + font-weight: 500; +} + +.app-nav { + display: flex; + gap: 8px; +} + +.nav-btn { + display: flex; + align-items: center; + gap: 8px; + background: transparent; + border: none; + color: var(--text-secondary); + padding: 10px 16px; + border-radius: 10px; + font-family: var(--font-heading); + font-size: 13px; + font-weight: 600; + cursor: pointer; + transition: all 0.3s cubic-bezier(0.4, 0, 0.2, 1); +} + +.nav-icon { + width: 18px; + height: 18px; + fill: currentColor; +} + +.nav-btn:hover { + color: var(--text-primary); + background: rgba(255, 255, 255, 0.04); +} + +.nav-btn.active { + color: #fff; + background: linear-gradient(135deg, var(--accent-blue) 0%, var(--accent-purple) 100%); + box-shadow: 0 0 15px var(--accent-blue-glow); +} + +/* --- Main content tabs --- */ +.tab-content { + display: none; + animation: fadeIn 0.4s ease-out forwards; +} + +.tab-content.active { + display: block; +} + +@keyframes fadeIn { + from { opacity: 0; transform: translateY(8px); } + to { opacity: 1; transform: translateY(0); } +} + +/* --- Grid & Layouts --- */ +.content-grid-split { + display: grid; + grid-template-columns: 380px 1fr; + gap: 25px; + align-items: start; +} + +/* --- Cards / Glass Panels --- */ +.glass { + background: var(--bg-surface); + backdrop-filter: blur(12px); + -webkit-backdrop-filter: blur(12px); + border: 1px solid var(--border-color); + border-radius: 16px; + padding: 24px; + box-shadow: 0 8px 32px 0 rgba(0, 0, 0, 0.25); +} + +.control-card { + display: flex; + flex-direction: column; + gap: 20px; +} + +.visualizer-card { + min-height: 520px; + display: flex; + flex-direction: column; +} + +.flex-column-center { + display: flex; + flex-direction: column; + align-items: center; + justify-content: center; +} + +h2 { + font-family: var(--font-heading); + font-size: 18px; + font-weight: 600; + margin-bottom: 8px; + letter-spacing: -0.3px; +} + +.section-intro { + font-size: 13px; + color: var(--text-secondary); + line-height: 1.5; +} + +/* --- Sliders & Controls --- */ +.slider-group, .control-group { + display: flex; + flex-direction: column; + gap: 10px; +} + +.slider-header { + display: flex; + justify-content: space-between; + align-items: center; +} + +.slider-label { + font-size: 13px; + font-weight: 600; + color: var(--text-primary); +} + +.slider-value { + font-family: var(--font-mono); + font-size: 12px; + color: var(--accent-blue); + background: rgba(59, 130, 246, 0.1); + padding: 2px 8px; + border-radius: 6px; + font-weight: 600; +} + +.control-hint { + font-size: 11px; + color: var(--text-muted); +} + +input[type="range"] { + -webkit-appearance: none; + width: 100%; + height: 6px; + background: rgba(255, 255, 255, 0.08); + border-radius: 10px; + outline: none; +} + +input[type="range"]::-webkit-slider-thumb { + -webkit-appearance: none; + width: 18px; + height: 18px; + border-radius: 50%; + background: linear-gradient(135deg, var(--accent-blue) 0%, var(--accent-purple) 100%); + cursor: pointer; + box-shadow: 0 0 8px var(--accent-blue-glow); + transition: transform 0.1s; +} + +input[type="range"]::-webkit-slider-thumb:hover { + transform: scale(1.15); +} + +.alpha-presets { + display: flex; + flex-wrap: wrap; + gap: 6px; + margin-top: 8px; +} + +.preset-btn { + background: rgba(255, 255, 255, 0.03); + border: 1px solid var(--border-color); + border-radius: 8px; + padding: 6px 10px; + color: var(--text-secondary); + font-size: 11px; + font-weight: 500; + cursor: pointer; + transition: all 0.2s; +} + +.preset-btn:hover { + background: rgba(255, 255, 255, 0.06); + color: var(--text-primary); +} + +.preset-btn.active { + background: rgba(59, 130, 246, 0.12); + border-color: var(--accent-blue); + color: var(--accent-blue); +} + +/* --- Toggle buttons --- */ +.toggle-group { + display: grid; + grid-template-columns: 1fr 1fr; + background: rgba(0, 0, 0, 0.2); + padding: 4px; + border-radius: 10px; + border: 1px solid var(--border-color); +} + +.toggle-btn { + background: transparent; + border: none; + color: var(--text-secondary); + padding: 8px; + border-radius: 6px; + font-size: 12px; + font-weight: 600; + cursor: pointer; + transition: all 0.2s; +} + +.toggle-btn.active { + background: rgba(255, 255, 255, 0.08); + color: #fff; +} + +/* --- Buttons --- */ +.btn-group { + display: flex; + gap: 10px; +} + +.btn { + flex: 1; + display: flex; + align-items: center; + justify-content: center; + gap: 8px; + border: none; + border-radius: 10px; + padding: 12px; + font-family: var(--font-heading); + font-size: 13px; + font-weight: 600; + cursor: pointer; + transition: all 0.3s cubic-bezier(0.4, 0, 0.2, 1); +} + +.btn-primary { + background: linear-gradient(135deg, var(--accent-blue) 0%, var(--accent-purple) 100%); + color: #fff; + box-shadow: 0 4px 15px rgba(139, 92, 246, 0.2); +} + +.btn-primary:hover { + transform: translateY(-2px); + box-shadow: 0 6px 20px rgba(139, 92, 246, 0.35); +} + +.btn-secondary { + background: rgba(255, 255, 255, 0.05); + border: 1px solid var(--border-color); + color: var(--text-primary); +} + +.btn-secondary:hover { + background: rgba(255, 255, 255, 0.08); +} + +.btn-danger { + background: rgba(239, 68, 68, 0.1); + border: 1px solid rgba(239, 68, 68, 0.2); + color: var(--accent-red); +} + +.btn-danger:hover { + background: rgba(239, 68, 68, 0.18); +} + +/* --- Stat and Alert boxes --- */ +.stat-box { + background: rgba(0, 0, 0, 0.2); + border: 1px solid var(--border-color); + border-radius: 12px; + padding: 14px 18px; +} + +.stat-title { + font-size: 11px; + color: var(--text-muted); + font-weight: 600; + text-transform: uppercase; + letter-spacing: 0.5px; + margin-bottom: 4px; +} + +.stat-body { + font-size: 13px; + color: var(--text-primary); + line-height: 1.4; +} + +.alert-box { + border-left: 3px solid; + padding: 12px 16px; + border-radius: 0 8px 8px 0; + font-size: 12px; + line-height: 1.5; +} + +.alert-box.tip { + background: rgba(16, 185, 129, 0.06); + border-color: var(--accent-green); + color: rgba(16, 185, 129, 0.95); +} + +.alert-box.warning { + background: rgba(245, 158, 11, 0.06); + border-color: var(--accent-orange); + color: rgba(245, 158, 11, 0.95); +} + +/* --- Dirichlet Splitting Visualizer Elements --- */ +.class-legend { + display: flex; + flex-direction: column; + gap: 8px; + background: rgba(0, 0, 0, 0.15); + padding: 12px 16px; + border-radius: 10px; + margin-bottom: 20px; + border: 1px solid var(--border-color); +} + +.legend-title { + font-size: 11px; + font-weight: 600; + color: var(--text-secondary); +} + +.legend-colors { + display: flex; + justify-content: space-between; + gap: 4px; +} + +.legend-item-chip { + flex: 1; + display: flex; + flex-direction: column; + align-items: center; + gap: 4px; + font-size: 11px; + font-weight: bold; + font-family: var(--font-mono); +} + +.color-bar-indicator { + width: 100%; + height: 6px; + border-radius: 3px; +} + +.clients-dist-container { + display: flex; + flex-direction: column; + gap: 20px; + flex: 1; +} + +.client-row { + display: grid; + grid-template-columns: 80px 1fr; + align-items: center; + gap: 15px; +} + +.client-label { + font-family: var(--font-heading); + font-size: 13px; + font-weight: 600; + color: var(--text-primary); +} + +.client-bars { + display: flex; + height: 36px; + border-radius: 8px; + overflow: hidden; + background: rgba(255, 255, 255, 0.03); + border: 1px solid var(--border-color); + box-shadow: inset 0 2px 4px rgba(0,0,0,0.5); + transition: all 0.3s; +} + +.bar-segment { + height: 100%; + transition: width 0.4s cubic-bezier(0.2, 0.8, 0.2, 1); + position: relative; + cursor: pointer; +} + +.bar-segment:hover::after { + content: attr(data-percent); + position: absolute; + bottom: 110%; + left: 50%; + transform: translateX(-50%); + background: #000; + color: #fff; + font-size: 10px; + padding: 3px 6px; + border-radius: 4px; + white-space: nowrap; + z-index: 10; + font-family: var(--font-mono); +} + +/* --- Client Drift Canvas Elements --- */ +.canvas-header { + width: 100%; + display: flex; + justify-content: space-between; + align-items: center; + margin-bottom: 12px; +} + +.landscape-legend { + display: flex; + gap: 12px; + font-size: 11px; + font-weight: 600; +} + +.legend-item { + display: flex; + align-items: center; + gap: 6px; +} + +.dot { + display: inline-block; + width: 8px; + height: 8px; + border-radius: 50%; +} + +.dot.global-min { background: var(--accent-green); } +.dot.client-min-1 { background: var(--accent-blue); } +.dot.client-min-2 { background: var(--accent-red); } + +.canvas-container { + width: 100%; + background: rgba(0, 0, 0, 0.35); + border-radius: 12px; + border: 1px solid var(--border-color); + position: relative; + overflow: hidden; + display: flex; + justify-content: center; + align-items: center; + box-shadow: inset 0 0 20px rgba(0, 0, 0, 0.6); +} + +canvas { + display: block; +} + +.canvas-caption { + margin-top: 12px; + font-size: 11px; + color: var(--text-secondary); + text-align: center; + max-width: 500px; +} + +/* --- Terminal Tutorial Layout --- */ +.tutorial-layout { + display: grid; + grid-template-columns: 1fr 1fr; + gap: 25px; + align-items: stretch; +} + +.tutorial-text { + display: flex; + flex-direction: column; + gap: 20px; +} + +.step-card { + display: flex; + gap: 15px; + background: rgba(255, 255, 255, 0.015); + border: 1px solid var(--border-color); + padding: 16px; + border-radius: 12px; +} + +.step-badge { + background: rgba(59, 130, 246, 0.1); + color: var(--accent-blue); + border: 1px solid rgba(59, 130, 246, 0.2); + border-radius: 8px; + padding: 4px 10px; + font-size: 11px; + font-weight: 700; + height: fit-content; + white-space: nowrap; +} + +.step-details h3 { + font-family: var(--font-heading); + font-size: 14px; + font-weight: 600; + margin-bottom: 4px; +} + +.step-details p { + font-size: 12px; + color: var(--text-secondary); + line-height: 1.4; + margin-bottom: 12px; +} + +.terminal-command-container { + display: flex; + justify-content: space-between; + align-items: flex-start; + background: rgba(0, 0, 0, 0.4); + border: 1px solid rgba(255, 255, 255, 0.05); + border-radius: 8px; + padding: 12px 14px; + position: relative; +} + +.terminal-command { + font-family: var(--font-mono); + font-size: 11px; + color: #e5e7eb; + line-height: 1.5; + white-space: pre-wrap; + word-break: break-all; +} + +.copy-btn { + background: rgba(255, 255, 255, 0.05); + border: 1px solid var(--border-color); + border-radius: 6px; + color: var(--text-secondary); + padding: 4px 8px; + font-size: 10px; + cursor: pointer; + font-weight: 600; + transition: all 0.2s; + user-select: none; +} + +.copy-btn:hover { + background: var(--accent-blue); + border-color: var(--accent-blue); + color: #fff; +} + +/* Mock Terminal Window */ +.terminal-window { + background: #060913; + border: 1px solid rgba(255, 255, 255, 0.07); + border-radius: 12px; + box-shadow: 0 12px 40px rgba(0, 0, 0, 0.5); + display: flex; + flex-direction: column; + min-height: 480px; +} + +.terminal-titlebar { + display: flex; + align-items: center; + gap: 6px; + padding: 12px 16px; + background: rgba(0, 0, 0, 0.3); + border-bottom: 1px solid rgba(255, 255, 255, 0.04); +} + +.terminal-titlebar .dot { + width: 10px; + height: 10px; + border-radius: 50%; +} + +.terminal-titlebar .dot.red { background: #ff5f56; } +.terminal-titlebar .dot.yellow { background: #ffbd2e; } +.terminal-titlebar .dot.green { background: #27c93f; } + +.terminal-titlebar .title { + font-size: 11px; + color: var(--text-secondary); + font-weight: 500; + margin-left: 10px; +} + +.terminal-body { + flex: 1; + padding: 20px; + font-size: 12px; + line-height: 1.6; + color: #e5e7eb; + overflow-y: auto; + display: flex; + flex-direction: column; + gap: 4px; +} + +.output-dim { + color: var(--text-muted); +} + +.output-success { + color: var(--accent-green); + font-weight: 600; +} + +.terminal-cursor { + animation: blink 1s step-end infinite; + color: var(--accent-blue); + font-weight: bold; +} + +@keyframes blink { + 50% { opacity: 0; } +} + +/* --- Results Chart Tab Elements --- */ +.upload-group { + display: flex; + flex-direction: column; + gap: 8px; + background: rgba(0, 0, 0, 0.15); + padding: 14px; + border-radius: 10px; + border: 1px solid var(--border-color); +} + +.upload-btn { + background: rgba(255, 255, 255, 0.04); + border: 1px solid var(--border-color); + border-radius: 8px; + padding: 10px; + text-align: center; + color: var(--text-primary); + font-size: 12px; + font-weight: 600; + cursor: pointer; + transition: all 0.2s; +} + +.upload-btn:hover { + background: rgba(59, 130, 246, 0.08); + border-color: var(--accent-blue); +} + +.upload-btn input[type="file"] { + display: none; +} + +.file-name-label { + font-size: 10px; + color: var(--text-muted); + font-family: var(--font-mono); + text-align: center; +} + +.chart-legend { + display: flex; + justify-content: center; + gap: 20px; + margin-top: 15px; + font-size: 12px; + font-weight: 600; +} + +.chart-legend .line { + display: inline-block; + width: 20px; + height: 3px; + vertical-align: middle; + margin-right: 6px; + border-radius: 2px; +} + +.chart-legend .line.iid-line { background: var(--accent-blue); } +.chart-legend .line.noniid-line { + background: var(--accent-red); + border-top: 2px dashed #000; /* mimic dashed line */ +} + +/* --- Quiz Tab Elements --- */ +.quiz-container { + max-width: 700px; + margin: 40px auto; +} + +.quiz-header { + text-align: center; + margin-bottom: 24px; +} + +.quiz-header p { + font-size: 13px; + color: var(--text-secondary); +} + +.quiz-card { + display: flex; + flex-direction: column; + gap: 18px; +} + +.quiz-question-num { + font-size: 11px; + color: var(--accent-purple); + font-weight: bold; + text-transform: uppercase; + letter-spacing: 1px; +} + +.quiz-question-text { + font-family: var(--font-heading); + font-size: 16px; + font-weight: 600; + line-height: 1.5; +} + +.quiz-answers-list { + display: flex; + flex-direction: column; + gap: 10px; +} + +.quiz-option { + background: rgba(255, 255, 255, 0.025); + border: 1px solid var(--border-color); + border-radius: 10px; + padding: 14px 18px; + color: var(--text-primary); + font-size: 13px; + line-height: 1.4; + cursor: pointer; + transition: all 0.2s; + display: flex; + align-items: center; + gap: 12px; +} + +.quiz-option:hover { + background: rgba(255, 255, 255, 0.05); + border-color: rgba(255, 255, 255, 0.15); +} + +.quiz-option.selected { + background: rgba(139, 92, 246, 0.08); + border-color: var(--accent-purple); +} + +.quiz-option.correct { + background: rgba(16, 185, 129, 0.08); + border-color: var(--accent-green); + color: #10b981; +} + +.quiz-option.wrong { + background: rgba(239, 68, 68, 0.08); + border-color: var(--accent-red); + color: #ef4444; +} + +.option-marker { + display: inline-block; + width: 20px; + height: 20px; + border-radius: 50%; + border: 2px solid var(--text-muted); + font-family: var(--font-heading); + font-size: 11px; + font-weight: bold; + display: flex; + align-items: center; + justify-content: center; + flex-shrink: 0; +} + +.quiz-option.selected .option-marker { + border-color: var(--accent-purple); + background: var(--accent-purple); + color: #fff; +} + +.quiz-option.correct .option-marker { + border-color: var(--accent-green); + background: var(--accent-green); + color: #fff; +} + +.quiz-option.wrong .option-marker { + border-color: var(--accent-red); + background: var(--accent-red); + color: #fff; +} + +.quiz-explanation-box { + margin-top: 14px; + background: rgba(139, 92, 246, 0.04); + border: 1px solid rgba(139, 92, 246, 0.1); + border-left: 3px solid var(--accent-purple); + padding: 14px 18px; + border-radius: 0 8px 8px 0; + font-size: 13px; + line-height: 1.5; + animation: slideDown 0.3s ease-out forwards; +} + +@keyframes slideDown { + from { opacity: 0; transform: translateY(-5px); } + to { opacity: 1; transform: translateY(0); } +} + +.quiz-footer { + display: flex; + justify-content: space-between; + align-items: center; + margin-top: 25px; + border-top: 1px solid var(--border-color); + padding-top: 20px; +} + +.score-display { + font-size: 13px; + font-weight: 600; + color: var(--text-secondary); +} + +.font-mono { + font-family: var(--font-mono); +} + +.hidden { + display: none !important; +} + +/* --- Font Awesome/SVG helper rules --- */ +svg { + display: inline-block; + vertical-align: middle; +} From 69f6c98ddb0d081ff1b7aa7c41bd11b07268d1a0 Mon Sep 17 00:00:00 2001 From: Koleaje Olayinka <100846558+koleajeolayinka@users.noreply.github.com> Date: Wed, 15 Jul 2026 17:56:13 +0100 Subject: [PATCH 02/13] fix(fed): improve tf stub compatibility check on broken imports --- week-3/fed/_compat.py | 33 +++++++++++++++++++++++---------- 1 file changed, 23 insertions(+), 10 deletions(-) diff --git a/week-3/fed/_compat.py b/week-3/fed/_compat.py index 9cde808..5983b5b 100644 --- a/week-3/fed/_compat.py +++ b/week-3/fed/_compat.py @@ -26,14 +26,27 @@ def apply(): """Replace a broken TensorFlow install with an inert stub module.""" try: import tensorflow # noqa: F401 - except ModuleNotFoundError: - return # TF not installed — Flower already handles this fine. + except ModuleNotFoundError as e: + if e.name == "tensorflow": + return # TF not installed at all — Flower handles this fine. + + # TF is installed, but an internal package dependency is missing (broken install). + # We must stub it out. + _stub_tensorflow() except Exception: - # TF is installed but broken. Drop the half-imported modules and put a - # do-nothing stub in their place so the optional `import tensorflow` - # downstream succeeds. - for name in [m for m in sys.modules if m == "tensorflow" or m.startswith("tensorflow.")]: - del sys.modules[name] - stub = types.ModuleType("tensorflow") - stub.__spec__ = ModuleSpec("tensorflow", loader=None) - sys.modules["tensorflow"] = stub + # TF is installed but broken in other ways (e.g. AttributeError, ImportError). + # We must stub it out. + _stub_tensorflow() + + +def _stub_tensorflow(): + """Helper to remove partially loaded tensorflow modules and replace with a stub.""" + import sys + import types + from importlib.machinery import ModuleSpec + + for name in [m for m in sys.modules if m == "tensorflow" or m.startswith("tensorflow.")]: + del sys.modules[name] + stub = types.ModuleType("tensorflow") + stub.__spec__ = ModuleSpec("tensorflow", loader=None) + sys.modules["tensorflow"] = stub From e38a006c5d8105bf83052d5d9227f9658a453f5a Mon Sep 17 00:00:00 2001 From: Koleaje Olayinka <100846558+koleajeolayinka@users.noreply.github.com> Date: Wed, 15 Jul 2026 17:56:24 +0100 Subject: [PATCH 03/13] refactor(fed): evaluate on validation dataset loader and fix loss averaging --- week-3/fed/client.py | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/week-3/fed/client.py b/week-3/fed/client.py index 2507f77..8db9a41 100644 --- a/week-3/fed/client.py +++ b/week-3/fed/client.py @@ -13,7 +13,7 @@ class FlowerClient(fl.client.NumPyClient): def __init__(self, client_id, num_clients=5, data_mode="iid", alpha=0.5): self.model = MLP() - self.trainloader = load_data( + self.trainloader, self.valloader = load_data( client_id, num_clients=num_clients, data_mode=data_mode, alpha=alpha ) self.criterion = nn.CrossEntropyLoss() @@ -41,14 +41,14 @@ def evaluate(self, parameters, config): self.model.eval() correct, total, loss_sum = 0, 0, 0.0 with torch.no_grad(): - for images, labels in self.trainloader: + for images, labels in self.valloader: outputs = self.model(images) - loss_sum += self.criterion(outputs, labels).item() + loss_sum += self.criterion(outputs, labels).item() * labels.size(0) correct += (outputs.argmax(1) == labels).sum().item() total += labels.size(0) - avg_loss = loss_sum / len(self.trainloader) - accuracy = correct / total + avg_loss = loss_sum / total if total > 0 else 0.0 + accuracy = correct / total if total > 0 else 0.0 return avg_loss, total, {"accuracy": accuracy} From 63761b5f760d70f5a30f72487dc97734e8379dae Mon Sep 17 00:00:00 2001 From: Koleaje Olayinka <100846558+koleajeolayinka@users.noreply.github.com> Date: Wed, 15 Jul 2026 17:56:41 +0100 Subject: [PATCH 04/13] feat(fed): support partitioned train/test splits for IID and Non-IID data --- week-3/fed/data.py | 40 ++++++++++++++++++++++++++++++---------- 1 file changed, 30 insertions(+), 10 deletions(-) diff --git a/week-3/fed/data.py b/week-3/fed/data.py index 96abb35..f0bddb3 100644 --- a/week-3/fed/data.py +++ b/week-3/fed/data.py @@ -54,25 +54,45 @@ def dirichlet_split(dataset, num_clients, alpha=0.5, seed=42): def load_data(client_id, num_clients=5, data_mode="iid", alpha=0.5, batch_size=32, seed=42): - """Return a DataLoader holding this client's partition of MNIST. + """Return (train_loader, val_loader) containing this client's partitioned datasets. Supports both 'iid' (uniform random split) and 'noniid' (Dirichlet label skew split). """ transform = transforms.ToTensor() - # Always download MNIST to the same root path DATA_ROOT - dataset = datasets.MNIST( + # Load training dataset + train_dataset = datasets.MNIST( DATA_ROOT, train=True, download=True, transform=transform ) + # Load test/validation dataset + test_dataset = datasets.MNIST( + DATA_ROOT, train=False, download=True, transform=transform + ) if data_mode == "iid": - partition_size = len(dataset) // num_clients - lengths = [partition_size] * (num_clients - 1) - lengths.append(len(dataset) - partition_size * (num_clients - 1)) - generator = torch.Generator().manual_seed(seed) - partitions = random_split(dataset, lengths, generator=generator) + # Partition training set + train_partition_size = len(train_dataset) // num_clients + train_lengths = [train_partition_size] * (num_clients - 1) + train_lengths.append(len(train_dataset) - train_partition_size * (num_clients - 1)) + train_generator = torch.Generator().manual_seed(seed) + train_partitions = random_split(train_dataset, train_lengths, generator=train_generator) + + # Partition testing set + test_partition_size = len(test_dataset) // num_clients + test_lengths = [test_partition_size] * (num_clients - 1) + test_lengths.append(len(test_dataset) - test_partition_size * (num_clients - 1)) + test_generator = torch.Generator().manual_seed(seed) + test_partitions = random_split(test_dataset, test_lengths, generator=test_generator) + elif data_mode == "noniid": - partitions = dirichlet_split(dataset, num_clients, alpha=alpha, seed=seed) + # Partition training set via Dirichlet split + train_partitions = dirichlet_split(train_dataset, num_clients, alpha=alpha, seed=seed) + # Partition testing set via Dirichlet split using the same parameters + test_partitions = dirichlet_split(test_dataset, num_clients, alpha=alpha, seed=seed) + else: raise ValueError(f"Unknown data_mode: {data_mode}") - return DataLoader(partitions[client_id], batch_size=batch_size, shuffle=True) + train_loader = DataLoader(train_partitions[client_id], batch_size=batch_size, shuffle=True) + val_loader = DataLoader(test_partitions[client_id], batch_size=batch_size, shuffle=False) + + return train_loader, val_loader From 115ec6fa8127e0c754436658f50929537ff7dfbe Mon Sep 17 00:00:00 2001 From: Koleaje Olayinka <100846558+koleajeolayinka@users.noreply.github.com> Date: Wed, 15 Jul 2026 17:56:50 +0100 Subject: [PATCH 05/13] feat(main): load separate train/validation splits and evaluate global model on test partitions --- week-3/main.py | 33 +++++++++++++++++++-------------- 1 file changed, 19 insertions(+), 14 deletions(-) diff --git a/week-3/main.py b/week-3/main.py index f47328d..7175c71 100644 --- a/week-3/main.py +++ b/week-3/main.py @@ -35,17 +35,19 @@ def run_simulation(data_mode, log_path, alpha=0.5): criterion = nn.CrossEntropyLoss() # Load dataloaders for each simulated client device - client_loaders = [] + client_train_loaders = [] + client_val_loaders = [] for cid in range(NUM_CLIENTS): - loader = load_data( + train_loader, val_loader = load_data( client_id=cid, num_clients=NUM_CLIENTS, data_mode=data_mode, alpha=alpha, seed=42, ) - client_loaders.append(loader) - print(f"Client {cid + 1} dataset loaded: {len(loader.dataset)} samples.") + client_train_loaders.append(train_loader) + client_val_loaders.append(val_loader) + print(f"Client {cid + 1} dataset loaded: {len(train_loader.dataset)} train samples, {len(val_loader.dataset)} val samples.") # Truncate CSV log file and write header with open(log_path, "w", newline="") as f: @@ -68,7 +70,7 @@ def run_simulation(data_mode, log_path, alpha=0.5): local_model.train() optimizer = torch.optim.SGD(local_model.parameters(), lr=0.01) - loader = client_loaders[cid] + loader = client_train_loaders[cid] # Train locally for 1 epoch (one pass over client partition) for images, labels in loader: @@ -100,23 +102,26 @@ def run_simulation(data_mode, log_path, alpha=0.5): global_model.eval() client_losses = [] client_accuracies = [] + client_val_sizes = [] with torch.no_grad(): for cid in range(NUM_CLIENTS): - loader = client_loaders[cid] + loader = client_val_loaders[cid] correct, total, loss_sum = 0, 0, 0.0 for images, labels in loader: outputs = global_model(images) - loss_sum += criterion(outputs, labels).item() + loss_sum += criterion(outputs, labels).item() * labels.size(0) correct += (outputs.argmax(1) == labels).sum().item() total += labels.size(0) - client_losses.append(loss_sum / len(loader)) - client_accuracies.append(correct / total) + client_losses.append(loss_sum / total if total > 0 else 0.0) + client_accuracies.append(correct / total if total > 0 else 0.0) + client_val_sizes.append(total) - # Example-weighted average calculation (FedAvg) - round_loss = sum(l * n for l, n in zip(client_losses, client_sizes)) / total_samples - round_acc = sum(a * n for a, n in zip(client_accuracies, client_sizes)) / total_samples + # Example-weighted average calculation (FedAvg) over validation samples + total_val_samples = sum(client_val_sizes) + round_loss = sum(l * n for l, n in zip(client_losses, client_val_sizes)) / total_val_samples if total_val_samples > 0 else 0.0 + round_acc = sum(a * n for a, n in zip(client_accuracies, client_val_sizes)) / total_val_samples if total_val_samples > 0 else 0.0 print(f"Round {server_round:02d} | Accuracy: {round_acc:.4f} | Loss: {round_loss:.4f}") @@ -161,7 +166,7 @@ def main(): import plot plot.generate_plot("iid_results.csv", "noniid_results.csv", "convergence_comparison.png") except Exception as e: - pass + print(f"Could not generate plot automatically: {e}") elif args.mode == "noniid": run_simulation("noniid", "noniid_results.csv", args.alpha) @@ -169,7 +174,7 @@ def main(): import plot plot.generate_plot("iid_results.csv", "noniid_results.csv", "convergence_comparison.png") except Exception as e: - pass + print(f"Could not generate plot automatically: {e}") if __name__ == "__main__": From aa035465e43ea57aa31abae4300222e0d14ae809 Mon Sep 17 00:00:00 2001 From: Koleaje Olayinka <100846558+koleajeolayinka@users.noreply.github.com> Date: Wed, 15 Jul 2026 17:56:56 +0100 Subject: [PATCH 06/13] fix(flower): redirect ray/flower tmp directories using unique system path and validate alpha parameter --- week-3/main_flower.py | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/week-3/main_flower.py b/week-3/main_flower.py index 09d6512..1a032f4 100644 --- a/week-3/main_flower.py +++ b/week-3/main_flower.py @@ -20,6 +20,8 @@ def run_simulation(data_mode, log_path, alpha=0.5): import flwr as fl from fed.client import client_fn from fed.strategy import LoggingFedAvg + import tempfile + import uuid NUM_CLIENTS = 5 NUM_ROUNDS = 10 @@ -32,8 +34,9 @@ def run_simulation(data_mode, log_path, alpha=0.5): os.environ["DATA_MODE"] = data_mode os.environ["ALPHA"] = str(alpha) - # Redirect all temporary files to /private/tmp/ray_fellowship which has short paths - local_tmp = "/private/tmp/ray_fellowship" + # Redirect all temporary files to a platform-native unique path + base_temp = tempfile.gettempdir() + local_tmp = os.path.join(base_temp, f"ray_fellowship_{uuid.uuid4().hex[:8]}") os.makedirs(local_tmp, exist_ok=True) os.environ["RAY_TMPDIR"] = local_tmp os.environ["TMPDIR"] = local_tmp @@ -91,6 +94,9 @@ def main(): ) args = parser.parse_args() + if args.mode in ["noniid", "both"] and args.alpha <= 0: + parser.error("--alpha must be greater than zero") + if args.mode == "both": print("\n=== RUNNING IID FLOWER SIMULATION ===") subprocess.run([sys.executable, "main_flower.py", "--mode", "iid"], check=True) @@ -104,7 +110,7 @@ def main(): print("\n=== GENERATING CONVERGENCE COMPARISON PLOT ===") try: import plot - plot.generate_plot("iid_results.csv", "noniid_results.csv", "convergence_comparison.png") + plot.generate_plot("iid_results.csv", "noniid_results.csv", "convergence_comparison.png", args.alpha) except Exception as e: print(f"Could not generate plot: {e}") From 43f664af30fdf13190c62a873995f10aa1583376 Mon Sep 17 00:00:00 2001 From: Koleaje Olayinka <100846558+koleajeolayinka@users.noreply.github.com> Date: Wed, 15 Jul 2026 17:57:00 +0100 Subject: [PATCH 07/13] feat(plot): support customization of alpha parameter in comparative plot legend --- week-3/plot.py | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/week-3/plot.py b/week-3/plot.py index 2e51f7a..fd84961 100644 --- a/week-3/plot.py +++ b/week-3/plot.py @@ -22,7 +22,7 @@ def load_log(filename): return rounds, accs, losses -def generate_plot(iid_file="iid_results.csv", noniid_file="noniid_results.csv", output_image="convergence_comparison.png"): +def generate_plot(iid_file="iid_results.csv", noniid_file="noniid_results.csv", output_image="convergence_comparison.png", noniid_alpha=0.5): """Load logged CSV results and save an overlaid comparison plot using Pillow.""" iid_rounds, iid_accs = [], [] noniid_rounds, noniid_accs = [], [] @@ -81,8 +81,9 @@ def generate_plot(iid_file="iid_results.csv", noniid_file="noniid_results.csv", # 2. Draw X-axis grid lines and ticks max_round = max((iid_rounds or [10]) + (noniid_rounds or [10])) + round_span = max(max_round - 1, 1) for r in range(1, max_round + 1): - x = pad_left + int(chart_w * (r - 1) / (max_round - 1)) + x = pad_left + int(chart_w * (r - 1) / round_span) # Grid line draw.line([(x, pad_top), (x, h - pad_bottom)], fill=color_grid, width=1) @@ -95,7 +96,7 @@ def generate_plot(iid_file="iid_results.csv", noniid_file="noniid_results.csv", # Coordinate mapping helper def map_coords(round_num, acc): - x = pad_left + int(chart_w * (round_num - 1) / (max_round - 1)) + x = pad_left + int(chart_w * (round_num - 1) / round_span) y = pad_top + int(chart_h * (1.0 - acc)) return (x, y) @@ -145,7 +146,7 @@ def map_coords(round_num, acc): draw.line([(leg_x + 15, leg_y + 38), (leg_x + 27, leg_y + 38)], fill=color_noniid, width=3) draw.line([(leg_x + 33, leg_y + 38), (leg_x + 45, leg_y + 38)], fill=color_noniid, width=3) draw.rectangle([leg_x + 27, leg_y + 35, leg_x + 33, leg_y + 41], fill=(255, 255, 255), outline=color_noniid, width=2) - draw.text((leg_x + 55, leg_y + 32), "Non-IID (alpha=0.5)", fill=color_text, font=font) + draw.text((leg_x + 55, leg_y + 32), f"Non-IID (alpha={noniid_alpha})", fill=color_text, font=font) img.save(output_image) print(f"Saved plot comparison to: {output_image}") From 2b55504438bc8f504b9797fa5ad3ab9497bec123 Mon Sep 17 00:00:00 2001 From: Koleaje Olayinka <100846558+koleajeolayinka@users.noreply.github.com> Date: Wed, 15 Jul 2026 17:57:06 +0100 Subject: [PATCH 08/13] chore: replace matplotlib with Pillow in requirements to reduce package overhead --- week-3/requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/week-3/requirements.txt b/week-3/requirements.txt index 8102467..c775292 100644 --- a/week-3/requirements.txt +++ b/week-3/requirements.txt @@ -1,5 +1,5 @@ flwr[simulation]>=1.7,<2.0 torch>=2.0 torchvision>=0.15 -matplotlib>=3.5 +Pillow>=9.0 numpy<2.0 From 6ae68a82435da772609ab66a9eaf76c072802f16 Mon Sep 17 00:00:00 2001 From: Koleaje Olayinka <100846558+koleajeolayinka@users.noreply.github.com> Date: Wed, 15 Jul 2026 17:57:11 +0100 Subject: [PATCH 09/13] docs(walkthrough): add client 3 legend color and clarify CLI options in walkthrough page --- week-3/walkthrough/index.html | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/week-3/walkthrough/index.html b/week-3/walkthrough/index.html index 2c542b1..481cab4 100644 --- a/week-3/walkthrough/index.html +++ b/week-3/walkthrough/index.html @@ -150,6 +150,7 @@

Loss Landscape Optimization

Global Optimum Client 1 Min Client 2 Min + Client 3 Min
@@ -159,7 +160,7 @@

Loss Landscape Optimization

- +
@@ -182,14 +183,14 @@

Setup Environment

Step 2
-

Run Both Simulations

-

Execute the sequential orchestrator. This spins up the Flower simulation, runs 10 rounds of IID training followed by 10 rounds of Non-IID training (α=0.5), logging results to individual CSVs.

+

Run Simulations

+

Execute the orchestrator. You can run the fast local PyTorch runner (Option A) or the standard Flower/Ray runner (Option B).

- 
python main.py
+ 
# Option A (Recommended): Pure PyTorch Simulation
python main.py

# Option B: Ray-backed Flower Simulation
python main_flower.py
-
+
Step 3
From d71a626d33f40c2953339a0006db93dc75b8be78 Mon Sep 17 00:00:00 2001 From: Koleaje Olayinka <100846558+koleajeolayinka@users.noreply.github.com> Date: Wed, 15 Jul 2026 17:57:16 +0100 Subject: [PATCH 10/13] fix(walkthrough): resolve edge-case divisions, enhance accessibility labels, and improve matched rounds calculation --- week-3/walkthrough/app.js | 63 ++++++++++++++++++++++++++------------- 1 file changed, 43 insertions(+), 20 deletions(-) diff --git a/week-3/walkthrough/app.js b/week-3/walkthrough/app.js index a2f812f..9b141e3 100644 --- a/week-3/walkthrough/app.js +++ b/week-3/walkthrough/app.js @@ -112,10 +112,9 @@ function updateDirichletSplit() { } // Set preset button active state - document.querySelectorAll('.preset-btn').forEach(btn => btn.classList.remove('active')); - if (alpha === 0.10) { - // match preset 0.1 - } + document.querySelectorAll('.preset-btn').forEach(btn => { + btn.classList.toggle('active', parseFloat(btn.innerText) === alpha); + }); const numClients = 5; const numClasses = 10; @@ -157,6 +156,14 @@ function updateDirichletSplit() { const barContainer = document.createElement('div'); barContainer.className = 'client-bars'; + barContainer.setAttribute('role', 'img'); + + // Build accessible text alternative for screen readers + let labelParts = []; + for (let c = 0; c < numClasses; c++) { + labelParts.push(`Class ${c}: ${clientProfiles[client][c].toFixed(1)}%`); + } + barContainer.setAttribute('aria-label', `Client ${client + 1} distribution: ` + labelParts.join(', ')); // Populate segments for (let c = 0; c < numClasses; c++) { @@ -457,6 +464,8 @@ function toggleDriftSim() { } else { // Simulation finished clearInterval(driftSimInterval); + driftSimInterval = null; + driftState.isSimulating = false; document.getElementById('drift-play-text').innerText = 'Simulate Round'; } }, 300); @@ -572,16 +581,29 @@ function handleCSVUpload(input, mode) { function updateDiscrepancyMetric() { const el = document.getElementById('discrepancy-metric'); if (iidPlotData.length > 0 && nonIidPlotData.length > 0) { - const lastIID = iidPlotData[iidPlotData.length - 1].accuracy * 100; - const lastNonIID = nonIidPlotData[nonIidPlotData.length - 1].accuracy * 100; - const diff = lastIID - lastNonIID; - el.innerHTML = ` -
Round ${iidPlotData.length} IID: ${lastIID.toFixed(1)}%
-
Round ${nonIidPlotData.length} Non-IID: ${lastNonIID.toFixed(1)}%
-
- Heterogeneity Penalty: -${diff.toFixed(1)}% Accuracy -
- `; + const iidRounds = iidPlotData.map(d => d.round); + const nonIidRounds = nonIidPlotData.map(d => d.round); + const commonRounds = iidRounds.filter(r => nonIidRounds.includes(r)); + + if (commonRounds.length > 0) { + const targetRound = Math.max(...commonRounds); + const iidRow = iidPlotData.find(d => d.round === targetRound); + const nonIidRow = nonIidPlotData.find(d => d.round === targetRound); + + const iidAcc = iidRow.accuracy * 100; + const nonIidAcc = nonIidRow.accuracy * 100; + const diff = iidAcc - nonIidAcc; + + el.innerHTML = ` +
Round ${targetRound} IID: ${iidAcc.toFixed(1)}%
+
Round ${targetRound} Non-IID: ${nonIidAcc.toFixed(1)}%
+
+ Heterogeneity Penalty: -${diff.toFixed(1)}% Accuracy +
+ `; + } else { + el.innerText = "No matching rounds found between IID and Non-IID datasets."; + } } else { el.innerText = "Upload both CSV logs to compute performance penalty."; } @@ -613,7 +635,7 @@ function drawChart() { chartCtx.stroke(); // Acc labels - chartCtx.fillStyle = 'var(--text-secondary)'; + chartCtx.fillStyle = '#9ca3af'; chartCtx.font = '10px JetBrains Mono'; const labelVal = (1.0 - (i / 5)).toFixed(1); chartCtx.fillText(labelVal, paddingLeft - 30, y + 4); @@ -624,16 +646,17 @@ function drawChart() { iidPlotData.length > 0 ? iidPlotData[iidPlotData.length - 1].round : 10, nonIidPlotData.length > 0 ? nonIidPlotData[nonIidPlotData.length - 1].round : 10 ); + const roundSpan = Math.max(maxR - 1, 1); // Draw round labels for (let r = 1; r <= maxR; r++) { - const x = paddingLeft + (chartW * (r - 1) / (maxR - 1)); + const x = paddingLeft + (chartW * (r - 1) / roundSpan); chartCtx.beginPath(); chartCtx.moveTo(x, paddingTop); chartCtx.lineTo(x, h - paddingBottom); chartCtx.stroke(); - chartCtx.fillStyle = 'var(--text-secondary)'; + chartCtx.fillStyle = '#9ca3af'; chartCtx.font = '10px JetBrains Mono'; chartCtx.fillText(r, x - 4, h - paddingBottom + 18); } @@ -649,7 +672,7 @@ function drawChart() { // Helper to map (round, accuracy) to coordinates const mapCoords = (round, acc) => { - const x = paddingLeft + (chartW * (round - 1) / (maxR - 1)); + const x = paddingLeft + (chartW * (round - 1) / roundSpan); const y = paddingTop + (chartH * (1.0 - acc)); return { x, y }; }; @@ -789,10 +812,10 @@ function renderQuizQuestion() { let answersHTML = q.answers.map((ans, idx) => { return ` -
+
+ `; }).join(''); From 60b5d409f0c54dc5d1440fabfe55c29adff2dfce Mon Sep 17 00:00:00 2001 From: Koleaje Olayinka <100846558+koleajeolayinka@users.noreply.github.com> Date: Wed, 15 Jul 2026 17:57:20 +0100 Subject: [PATCH 11/13] style(walkthrough): add mobile responsiveness media-queries and fix stylelint issues --- week-3/walkthrough/style.css | 54 ++++++++++++++++++++++++++++++++---- 1 file changed, 49 insertions(+), 5 deletions(-) diff --git a/week-3/walkthrough/style.css b/week-3/walkthrough/style.css index 59e487a..3d2ec66 100644 --- a/week-3/walkthrough/style.css +++ b/week-3/walkthrough/style.css @@ -87,10 +87,10 @@ body { .logo-icon { font-size: 32px; filter: drop-shadow(0 0 10px var(--accent-blue-glow)); - animation: rotate🍭 6s infinite linear; + animation: rotate-spinner 6s infinite linear; } -@keyframes rotate🍭 { +@keyframes rotate-spinner { 0% { transform: rotate(0deg); } 100% { transform: rotate(360deg); } } @@ -135,7 +135,7 @@ body { .nav-icon { width: 18px; height: 18px; - fill: currentColor; + fill: currentcolor; } .nav-btn:hover { @@ -555,6 +555,7 @@ input[type="range"]::-webkit-slider-thumb:hover { .dot.global-min { background: var(--accent-green); } .dot.client-min-1 { background: var(--accent-blue); } .dot.client-min-2 { background: var(--accent-red); } +.dot.client-min-3 { background: var(--accent-pink); } .canvas-container { width: 100%; @@ -767,7 +768,20 @@ canvas { } .upload-btn input[type="file"] { - display: none; + position: absolute; + width: 1px; + height: 1px; + padding: 0; + margin: -1px; + overflow: hidden; + clip: rect(0, 0, 0, 0); + white-space: nowrap; + border: 0; +} + +.upload-btn:focus-within { + outline: 2px solid var(--accent-blue); + outline-offset: 2px; } .file-name-label { @@ -882,7 +896,6 @@ canvas { } .option-marker { - display: inline-block; width: 20px; height: 20px; border-radius: 50%; @@ -959,3 +972,34 @@ svg { display: inline-block; vertical-align: middle; } + +/* --- Responsive Adjustments --- */ +@media (max-width: 1024px) { + .tutorial-layout { + grid-template-columns: 1fr; + } + + .content-grid-split { + grid-template-columns: 1fr; + } +} + +@media (max-width: 768px) { + .app-header { + flex-direction: column; + gap: 15px; + align-items: center; + text-align: center; + } + + .app-nav { + flex-wrap: wrap; + justify-content: center; + } + + .visualizer-card canvas, + #results-chart-canvas { + max-width: 100%; + height: auto; + } +} From 668c54e7685ca5c4b56d7e80eaf5d57751e8191e Mon Sep 17 00:00:00 2001 From: Koleaje Olayinka <100846558+koleajeolayinka@users.noreply.github.com> Date: Wed, 15 Jul 2026 17:57:26 +0100 Subject: [PATCH 12/13] docs(memo): update convergence metrics with exact numbers from correct test-set simulation --- week-3/MEMO.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/week-3/MEMO.md b/week-3/MEMO.md index e19095d..dbcef87 100644 --- a/week-3/MEMO.md +++ b/week-3/MEMO.md @@ -8,9 +8,9 @@ Before running the experiment, I expected that partitioning the MNIST dataset us ## 2. Experimental Observations After executing 10 communication rounds across 5 clients, I observed a clear convergence penalty under the Non-IID data distribution, which is most prominent in the early phases of training: -* **Initial Round Contrast:** In Round 1, the global model trained on IID partitions achieved a weighted test accuracy of **77.75%** with a loss of **1.2763**. In contrast, the model trained on the Non-IID Dirichlet split reached only **57.63%** accuracy with a much higher loss of **1.6053**—representing a performance gap of **20.12%**. -* **Intermediate Convergence Rate:** The IID simulation climbed steadily and reached over 88% accuracy by Round 4 (**88.05%**), whereas the Non-IID simulation lagged behind, requiring 6 rounds to cross the 87% threshold (**87.01%**). -* **Terminal Convergence Point:** By Round 10, the performance gap narrowed, but a clear deficit remained. The IID model finished at **90.58%** accuracy (loss: **0.3360**), while the Non-IID model reached **89.27%** accuracy (loss: **0.3767**). +* **Initial Round Contrast:** In Round 1, the global model trained on IID partitions achieved a weighted test accuracy of **78.25%** with a loss of **1.2382**. In contrast, the model trained on the Non-IID Dirichlet split reached only **56.60%** accuracy with a much higher loss of **1.5654**—representing a performance gap of **21.65 percentage points**. +* **Intermediate Convergence Rate:** The IID simulation climbed steadily and reached over 88% accuracy by Round 4 (**88.49%**), whereas the Non-IID simulation lagged behind, requiring 6 rounds to cross the 87% threshold (**87.25%**). +* **Terminal Convergence Point:** By Round 10, the performance gap narrowed, but a clear deficit remained. The IID model finished at **90.95%** accuracy (loss: **0.3209**), while the Non-IID model reached **89.44%** accuracy (loss: **0.3677**). The resulting plot (`convergence_comparison.png`) visually overlays these trends, showing that the Non-IID curve stays consistently below the IID curve, validating the statistical heterogeneity penalty. From b8b358fc44d3170695c4c4fd17270462f3649a53 Mon Sep 17 00:00:00 2001 From: Koleaje Olayinka <100846558+koleajeolayinka@users.noreply.github.com> Date: Wed, 15 Jul 2026 17:57:31 +0100 Subject: [PATCH 13/13] docs(readme): clarify options for pure PyTorch and Ray-backed Flower runner execution --- week-3/README.md | 34 ++++++++++++++++++++++------------ 1 file changed, 22 insertions(+), 12 deletions(-) diff --git a/week-3/README.md b/week-3/README.md index f0221eb..361b3d0 100644 --- a/week-3/README.md +++ b/week-3/README.md @@ -85,26 +85,36 @@ pip install -r requirements.txt ``` ### Step 2: Run the Experiments -The simulation runner in `main.py` is configured to run both IID and Non-IID setups sequentially inside isolated subprocesses. This prevents Ray engine reinitialization conflicts: +We provide two alternative orchestrators to run these experiments. Both support the exact same arguments and generate matching logs and plots: +#### Option A: Pure PyTorch Runner (Recommended) +This runs a pure PyTorch simulation of FedAvg in a single local process. It is fast, lightweight, and sandbox-compatible. ```bash -# Run both simulations for 10 rounds +# Run both simulations sequentially (generates IID & Non-IID CSVs and overlays the plot) python main.py -``` -* **IID Run:** Partitions MNIST uniformly across 5 clients. Saves logs to `iid_results.csv`. -* **Non-IID Run:** Partitions MNIST using a Dirichlet distribution with $\alpha=0.5$ across 5 clients. Saves logs to `noniid_results.csv`. -* **Plotter:** Automatically reads both files and generates `convergence_comparison.png`. +# Run with single-mode CLI options +python main.py --mode iid +python main.py --mode noniid --alpha 0.1 +``` -*If you want to run them individually or with a custom alpha:* +#### Option B: Ray-backed Flower Runner +This runs the simulation using Flower's simulation engine and Ray. It spawns isolated subprocesses to avoid Ray state conflicts. ```bash -# Run only IID -python main.py --mode iid +# Run both Flower simulations sequentially +python main_flower.py -# Run only Non-IID with extreme skew (alpha = 0.1) -python main.py --mode noniid --alpha 0.1 +# Run with single-mode CLI options +python main_flower.py --mode iid +python main_flower.py --mode noniid --alpha 0.1 +``` -# Run the plotter manually +Regardless of which option you run, they will: +* Save logs to `iid_results.csv` and `noniid_results.csv`. +* Generate the comparison chart `convergence_comparison.png`. + +To run the plotter independently: +```bash python plot.py ```