---
license: apache-2.0
task_categories:
- image-classification
tags:
- federated-learning
- fedavg
- non-iid
- pytorch
---

# Federated Digits

Federated Digits simulates five data-siloed clients learning a shared 8x8 digit
classifier with Federated Averaging. Class samples are partitioned through a
low-concentration Dirichlet distribution, producing deliberately non-IID clients.

The project reports:

- per-client class distributions;
- global test accuracy after every communication round;
- client-update disagreement;
- a centralized training control using the same architecture.

No raw client examples are exchanged during federated rounds; only model parameters
are averaged. This is a local simulation, not a networked privacy guarantee.

## Reproduce

```powershell
uv run python projects/federated-digits/train.py
```

## Verified results

- Model size: **2,410 parameters**
- Clients: **5**, with Dirichlet concentration `0.25`
- Communication rounds: **30**, with two local epochs per round
- Round-one global accuracy: **20.89%**
- Final global accuracy: **93.33%**
- Best global accuracy: **94.00%**
- Centralized control: **96.89%**
- Final federated-to-centralized gap: **-3.56 percentage points**

Mean client-update disagreement fell from 1.487 after the first round to 0.500 after
round 30. The artifact includes every round's accuracy, client loss, update
disagreement, and each client's class distribution.