Add tutorials to user documentation by ArthurDanjou · Pull Request #55 · calicarpa/krum

ArthurDanjou · 2026-07-21T11:56:54Z

This PR adds a complete tutorial section to the Krum documentation, restructures the quickstart, and fixes several documentation issues.**

New tutorials (14 `.rst` files)

The docs/tutorials/ directory now contains a full walkthrough series:

Tutorial	Covers
`using_aggregators_attacks`	All built-in aggregation rules and attacks, resilience table, combined example
`working_with_models`	`Model` wrapper, zero-copy flat tensor views, standard models (Krum NIPS 2017, MONNA ICML 2023)
`centralised_simulation_walkthrough`	`KrumSimulation` and `HiddenVulnerabilitySimulation` lifecycle, baseline comparison
`decentralised_simulation_walkthrough`	`MonnaSimulation`, per-worker models, Byzantine reach modes, custom data streams
`custom_dataset`	Using any PyTorch `Dataset` with Krum: `TensorDataset`, `torchvision`, disk loading
`working_with_orchestrator`	Structured result collection with `Metric` and `Orchestrator`
`results_analysis`	Filtering, pivoting, merging, plotting, exporting `MetricDataFrame`
`systematic_benchmark`	N aggregators × M attacks sweep, comparison table, LaTeX export
`end_to_end`	Complete experiment in one script: dataset → model → Orchestrator → analysis → CSV export
`troubleshooting`	Common errors (aggregator bounds, NaN, divergence, missing gradients) with causes and fixes
`implement_simulation`	Custom simulation subclassing
`implement_aggregator`	Custom aggregation rule
`implement_attack`	Custom Byzantine attack

Other changes

Quickstart trimmed from ~180 lines to ~40 — a minimal sanity check pointing to tutorials for depth
pyproject.toml — matplotlib, numpy, and seaborn moved to a new [experiments] extra; runtime deps reduced to pandas, torch, torchvision only; dev deps bumped
README updated with krum[experiments] install instructions
Docs nav — Tutorials section added to the Sphinx sidebar and docs homepage
Reference docs — all automodule paths fixed from bare aggregators.xxx to krum.primitives.aggregators.xxx (same for attacks)
Heading fixes — 13 RST heading underlines corrected across 7 tutorial files (off-by-one length mismatches)
uv.lock regenerated to match new dependency tree

Replaced the detailed "Key Concepts" section with a minimal sanity check example. Point users to tutorials for comprehensive guides on aggregators, attacks, and models.

Krum now requires pandas as a runtime dependency. Update install instructions to include the experiments extra which adds matplotlib, numpy, and seaborn.

New tutorial covering MetricDataFrame filtering, merging, pivoting, CSV/JSON export, seed aggregation, and plotting. Added to tutorial index and todo.md marked complete.

New tutorial showing how to run N aggregators × M attacks with Orchestrator, build a comparison table, and export for papers. Added to tutorial index and todo.md marked complete.

Conceptual tutorial covering the Byzantine threat model, the three regimes of the Byzantine budget (f < n/2, 2f+2 < n, 4f+2 < n), a strategy-based panorama of all five built-in attacks, and the fundamental limits of robustness. Added to tutorial index and todo.md marked complete.

Complete the tutorial series with a decision guide for using any PyTorch Dataset with Krum simulations (TensorDataset, torchvision, disk loading, model matching).

Fix RST title underlines that were one character too long across centralised_simulation, decentralised_simulation, results_analysis, systematic_benchmark, and working_with_orchestrator tutorials.

Improve the minimal example and add new sections on data partitioning and evaluating worker models. The data loading pattern now uses an infinite cycle helper to avoid StopIteration when streams are exhausted.

Improve cross-linking between tutorials by adding links to implement_aggregator and implement_attack, reordering sections for better learning flow, and standardizing formatting across all tutorial pages.

Documents the Metric, Orchestrator, and MetricDataFrame API for running reproducible experiments with multiple configurations and collecting comparable metrics across seeds.

- Move implement_aggregator and implement_attack to Available Tutorials - Consolidate advanced orchestration tutorials into structured_experiments - Update introduction paragraph with revised learning path

Added a code example demonstrating how custom kwargs passed to `aggregator_kwargs` are accessible via `specialized.get()`. Updated the testing section to show the specific command.

The tutorial now demonstrates how MultiKrum handles SignFlip attacks by comparing against a simple Average baseline, with an explanation of why their gradient norms differ.

Added "Setup" and "Running the grid" subsections to improve tutorial structure and readability.

- Document that aggregator uses aggregate() and attack uses generate() methods - Add rounds=50 parameter to simulation examples - Document stop_attack_at and weight_decay parameters

ArthurDanjou linked an issue Jul 21, 2026 that may be closed by this pull request

Add tutorials to user documentation #54

Closed

7 tasks

ArthurDanjou added the documentation Improvements or additions to documentation label Jul 21, 2026

ArthurDanjou self-assigned this Jul 21, 2026

ArthurDanjou marked this pull request as ready for review July 27, 2026 08:55

pevab approved these changes Jul 30, 2026

View reviewed changes

ArthurDanjou added 25 commits July 30, 2026 17:19

Fix module paths in aggregator and attack docs

ac6e3c8

Simplify quickstart to focus on essentials

7d90408

Replaced the detailed "Key Concepts" section with a minimal sanity check example. Point users to tutorials for comprehensive guides on aggregators, attacks, and models.

Fix import path in README example

d8d390e

Add tutorial on aggregators and attacks

2117573

Move visualization dependencies to optional experiments extra

2ba4b3c

Update quickstart docs with new dependencies

401f64b

Krum now requires pandas as a runtime dependency. Update install instructions to include the experiments extra which adds matplotlib, numpy, and seaborn.

Update tutorial links to using_simulations

9f93e5c

Update using_aggregators_attacks.rst

f2e7b1b

Create working_with_models.rst

fd5ff8e

Create using_simulations.rst

98de555

Create working_with_orchestrator.rst

db627c0

Create implement_simulation.rst

3dfe3fc

Create implement_aggregator.rst

4d93f55

Create implement_attack.rst

58d9a72

Create index.rst

f13df35

Rework simulations tutorials

54105fa

docs(tutorials): add results analysis tutorial (item 2/6)

660148e

New tutorial covering MetricDataFrame filtering, merging, pivoting, CSV/JSON export, seed aggregation, and plotting. Added to tutorial index and todo.md marked complete.

docs(tutorials): add systematic benchmark tutorial (item 3/6)

90c2df0

New tutorial showing how to run N aggregators × M attacks with Orchestrator, build a comparison table, and export for papers. Added to tutorial index and todo.md marked complete.

docs(tutorials): add custom dataset tutorials

fbff756

Complete the tutorial series with a decision guide for using any PyTorch Dataset with Krum simulations (TensorDataset, torchvision, disk loading, model matching).

Delete todo.md

4f55d41

Remove Byzantine attacks tutorial

c73a9f5

Add new documentation links to tutorial walkthroughs

2c72169

Fix RST title underlines that were one character too long across centralised_simulation, decentralised_simulation, results_analysis, systematic_benchmark, and working_with_orchestrator tutorials.

Add end-to-end tutorial and troubleshooting guide

82abf85

Remove tutorial documentation files

40607c0

ArthurDanjou added 27 commits July 30, 2026 17:19

Normalize bullet point separators and wording in documentation

2305858

Delete implement_simulation.rst

d5fba50

Delete end_to_end.rst

8c00fcf

Update attack tutorial to demonstrate RepeatAttack

e36dd7f

Use FirstGrad for simpler aggregator tutorial

f46ec5e

Add working_with_models to next steps section

2136e32

Update decentralised simulation walkthrough tutorial

78f2973

Improve the minimal example and add new sections on data partitioning and evaluating worker models. The data loading pattern now uses an infinite cycle helper to avoid StopIteration when streams are exhausted.

Update tutorial next steps sections

77a3698

Improve cross-linking between tutorials by adding links to implement_aggregator and implement_attack, reordering sections for better learning flow, and standardizing formatting across all tutorial pages.

Add structured experiments tutorial

905e184

Documents the Metric, Orchestrator, and MetricDataFrame API for running reproducible experiments with multiple configurations and collecting comparable metrics across seeds.

Restructure tutorials index documentation

cbb62a0

- Move implement_aggregator and implement_attack to Available Tutorials - Consolidate advanced orchestration tutorials into structured_experiments - Update introduction paragraph with revised learning path

Refine tutorials index page text and formatting

33e6458

Clarify aggregator_kwargs usage in implement_aggregator tutorial

dc42cb2

Added a code example demonstrating how custom kwargs passed to `aggregator_kwargs` are accessible via `specialized.get()`. Updated the testing section to show the specific command.

Add baseline Average comparison in attacks tutorial

ec866b3

The tutorial now demonstrates how MultiKrum handles SignFlip attacks by comparing against a simple Average baseline, with an explanation of why their gradient norms differ.

Simplify tutorial by linking to reference docs for model list

9f5abe0

Update using_aggregators_attacks.rst

1af1fa8

Move tutorial docs to reference pages

0207283

Clarify test command in implement_attack tutorial

0b95224

Add section headers to structured experiments tutorial

7ad4025

Add section headers to structured experiments tutorial

181b39f

Added "Setup" and "Running the grid" subsections to improve tutorial structure and readability.

Streamline tutorials: remove redundant listings, add seealso refs

ad97280

Restructure tutorial walkthroughs for clearer flow

7e05aaf

Remove 'Going further' section from walkthrough tutorial

e8a17b2

Remove comparing two configurations tutorial

d47c28c

Clarify simulation API and update tutorial examples

dc44690

- Document that aggregator uses aggregate() and attack uses generate() methods - Add rounds=50 parameter to simulation examples - Document stop_attack_at and weight_decay parameters

Document NearestNeighborAverage aggregator in tutorials

1a6c5a4

Fix title underline too short

c1c5a3b

Fix table

4c1beac

ArthurDanjou force-pushed the 54-add-tutorials-to-user-documentation branch from 75ca0d7 to 4c1beac Compare July 30, 2026 15:19

ArthurDanjou merged commit fc0678f into main Jul 30, 2026
6 checks passed

ArthurDanjou deleted the 54-add-tutorials-to-user-documentation branch July 30, 2026 15:21

Navigation Menu

Uh oh!

Add tutorials to user documentation - #55

Add tutorials to user documentation#55
ArthurDanjou merged 53 commits into
mainfrom
54-add-tutorials-to-user-documentation

ArthurDanjou commented Jul 21, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

ArthurDanjou commented Jul 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

New tutorials (14 .rst files)

Other changes

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

ArthurDanjou commented Jul 21, 2026 •

edited

Loading

New tutorials (14 `.rst` files)