Sovereign 8s.is mirror of standardgalactic/Stackelberg-FairLearning
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Sebastian Niehaus 07af629610 Refine DSWM search and add ASWM strategy networks
DSWM: build the aggregate inside the search loop so the selection loss
depends on the candidate weight, and select after local training.

ASWM: add leader and shared follower strategy networks with Gaussian
exploration and a score-function update. config['baseline'] selects a
learned critic (default) or the DSWM grid optimum.

Both: leader role by training-set size, per-node selection sets, and the
selection split no longer passed to fit().
2026-09-19 11:59:35 +03:00
algorithms Refine DSWM search and add ASWM strategy networks 2026-09-19 11:59:35 +03:00
config Initial implementation of Fair Distributed Machine Learning 2026-08-01 13:14:34 +02:00
data Initial implementation of Fair Distributed Machine Learning 2026-08-01 13:14:34 +02:00
distribution_plot Refine DSWM search and add ASWM strategy networks 2026-09-19 11:59:35 +03:00
examples Initial implementation of Fair Distributed Machine Learning 2026-08-01 13:14:34 +02:00
experiments Initial implementation of Fair Distributed Machine Learning 2026-08-01 13:14:34 +02:00
metrics Initial implementation of Fair Distributed Machine Learning 2026-08-01 13:14:34 +02:00
models Initial implementation of Fair Distributed Machine Learning 2026-08-01 13:14:34 +02:00
utils Initial implementation of Fair Distributed Machine Learning 2026-08-01 13:14:34 +02:00
.DS_Store Refine DSWM search and add ASWM strategy networks 2026-09-19 11:59:35 +03:00
examples.py Initial implementation of Fair Distributed Machine Learning 2026-08-01 13:14:34 +02:00
LICENSE Initial implementation of Fair Distributed Machine Learning 2026-08-01 13:14:34 +02:00
main.py Initial implementation of Fair Distributed Machine Learning 2026-08-01 13:14:34 +02:00
QUICKSTART.md Initial implementation of Fair Distributed Machine Learning 2026-08-01 13:14:34 +02:00
README.md Initial implementation of Fair Distributed Machine Learning 2026-08-01 13:14:34 +02:00
requirements.txt Initial implementation of Fair Distributed Machine Learning 2026-08-01 13:14:34 +02:00
train_federated.py Initial implementation of Fair Distributed Machine Learning 2026-08-01 13:14:34 +02:00
TRAINING.md Initial implementation of Fair Distributed Machine Learning 2026-08-01 13:14:34 +02:00

Fair Distributed Machine Learning with Imbalanced Data as a Stackelberg Evolutionary Game

Implementation of the paper "Fair Distributed Machine Learning with Imbalanced Data as a Stackelberg Evolutionary Game" by Sebastian Niehaus, Ingo Roeder, and Nico Scherf.


⚠️ Disclaimer

This repository is a simplified, single-machine reference implementation.

The decentralised setting is simulated rather than physically distributed: all nodes (leader(s) and followers) live as separate in-memory models and data partitions inside one Python process, and the "global model update" is a plain weighted average of their parameters. This is a deliberate design choice so that:

  • No decentralised infrastructure is required. You do not need multiple machines, a federated learning framework (Flower, FedML, TFF, NVFlare), a parameter server, message passing (gRPC / MPI / sockets), or any orchestration layer. A single laptop or workstation is enough.
  • The results are reproducible with one command. Everything runs locally and deterministically (given a seed), which makes the Stackelberg weighting logic and the Nash Social Welfare metrics easy to inspect, debug, and verify.
  • The focus stays on the method, not the plumbing. The contribution-weighting mechanisms (DSWM / ASWM) and the fairness evaluation (NSW / WNSW) are exactly what the paper describes; the network layer is abstracted away.

What this means in practice:

Aspect This repository A production federated deployment
Node isolation Logical (separate arrays/models in one process) Physical (separate machines/institutions)
Communication Direct function calls gRPC / HTTPS / message broker
Privacy guarantees None — raw data is co-located by construction Data never leaves the node; secure aggregation, DP, etc.
Fault tolerance / stragglers Not modelled Required
Scalability Limited by one machine's RAM/GPU Horizontal

Because raw data is co-located, this code provides no privacy guarantees and must not be used to process real patient data across institutions. It is intended for research, teaching, and reproducing the reported numbers. Porting the aggregation step to a real federated framework is straightforward — the weighting logic in algorithms/ is independent of the transport layer.


Overview

This repository contains the implementation of two contribution-weighting strategies for decentralised learning:

  • DSWM (Deterministic Stackelberg Weighting Model): selects the contribution weight from a fixed set C = {0.1, 0.2, ..., 1.0} by loss minimisation, using an experience replay buffer to anticipate follower reactions.
  • ASWM (Adaptive Stackelberg Weighting Model): uses a neural network to dynamically predict the contribution weight from the current system state (local data, previous weights, previous global weights, local utility).

Features

  • Stackelberg game-based federated learning, simulated on a single machine
  • Single-Leader–Multiple-Follower (SLMF, 3 nodes) and Multi-Leader–Multi-Follower (MLMF, 5 nodes) setups
  • Nash Social Welfare (NSW) and Weighted Nash Social Welfare (WNSW) fairness metrics
  • Data preparation with Dirichlet-based class imbalance and per-node Gaussian noise
  • Baseline comparison: FedAvg
  • TensorFlow/Keras training pipeline (simple CNN and ResNet-18)

Installation

pip install -r requirements.txt

Tested with Python 3.9+ and TensorFlow 2.x. A GPU is optional — the MedMNIST datasets are small enough to train on CPU.

Repository Structure

.
├── README.md
├── QUICKSTART.md               # 5-minute getting-started guide
├── TRAINING.md                 # detailed training guide
├── requirements.txt
├── train_federated.py          # main training entry point
├── main.py                     # demo / evaluation script
├── examples.py                 # metric and data-prep usage examples
├── config/
│   └── config.yaml
├── data/
│   └── prepare_data.py         # Dirichlet split, Gaussian noise, JSON export
├── models/
│   ├── base_model.py           # simple CNN + ResNet-18 (tensorflow.keras)
│   ├── leader_network.py       # ASWM leader policy network
│   └── follower_network.py     # ASWM shared follower policy network
├── algorithms/
│   ├── fedavg.py               # baseline aggregation
│   └── dswm.py                 # deterministic Stackelberg weighting
├── metrics/
│   ├── nash_social_welfare.py  # NSW / WNSW
│   └── evaluation.py           # AUC and per-node metrics
├── utils/
│   ├── experience_replay.py    # replay buffer for leader/follower anticipation
│   └── visualization.py        # distribution and contribution-weight plots
├── examples/
│   └── simple_training.py      # standalone run on synthetic data (no dataset needed)
└── experiments/                # place your experiment scripts here

Quick Start

The fastest way to verify the installation — runs on synthetic data, so no dataset download is required:

python examples/simple_training.py

Usage

Data Preparation

The MedMNIST .npz files (breastmnist.npz, dermamnist.npz, bloodmnist.npz) are expected in a local folder. Download them from medmnist.com.

from data.prepare_data import prepare_federated_data

# Split the training set across nodes using a Dirichlet distribution
data_splits = prepare_federated_data(
    dataset_name='breastmnist',
    number_of_nodes=3,
    data_path='./data/MedMnist/'
)

Each node receives a different class distribution and its own Gaussian noise pattern, reproducing the heterogeneity described in the paper.

Running Experiments

# SLMF setup (3 nodes): baseline vs. deterministic Stackelberg weighting
python train_federated.py \
    --dataset breastmnist \
    --num_nodes 3 \
    --algorithms fedavg dswm \
    --num_rounds 25 \
    --output_dir ./results/slmf_breast

# MLMF setup (5 nodes)
python train_federated.py \
    --dataset dermamnist \
    --num_nodes 5 \
    --algorithms fedavg dswm \
    --num_rounds 25 \
    --output_dir ./results/mlmf_derma

See TRAINING.md for the full list of arguments.

Evaluation

from metrics.nash_social_welfare import compute_nsw, compute_wnsw

auc_scores  = [0.812, 0.772, 0.674]   # per-node AUC (leader, follower 1, follower 2)
node_weights = [0.66, 0.23, 0.11]     # relative data share, must sum to 1

nsw  = compute_nsw(auc_scores)                 # geometric mean of utilities
wnsw = compute_wnsw(auc_scores, node_weights)  # size-weighted variant

NSW is the geometric mean of the per-node AUCs, so a single weak node pulls the whole score down — this is what makes it a fairness measure rather than an average. WNSW raises each utility to the power of that node's relative data share, so larger nodes influence the welfare proportionally.

Reproducing the Paper's Numbers

Because the Dirichlet split and the Gaussian noise are drawn randomly, individual runs vary. The paper averages over 10 repetitions; use --num_experiments 10 and compare the mean. Exact reproduction of the published AUCs also depends on the ASWM actor-critic hyperparameters, which are not fully specified in the paper — treat the reported values as the target, not a guarantee.

Citation

@article{niehaus2024fair,
  title={Fair Distributed Machine Learning with Imbalanced Data as a Stackelberg Evolutionary Game},
  author={Niehaus, Sebastian and Roeder, Ingo and Scherf, Nico},
  journal={Preprint submitted to Elsevier},
  year={2024}
}

License

MIT License

Acknowledgments

This implementation is based on the paper by Niehaus et al. The original research was supported by BMBF through ACONITE (01IS22065) and ScaDS.AI.