calicarpa · ArthurDanjou · Jul 30, 2026 · Jul 21, 2026 · Jul 21, 2026 · Jul 21, 2026
diff --git a/README.md b/README.md
@@ -16,7 +16,7 @@ The reference documentation is available at
 ```python
 import torch
 from krum.primitives.aggregators import Krum, Average
-from krum.primitives.attacks import Gaussian
+from krum.primitives.attacks.gaussian import Gaussian
 
 # Simulate gradients from 10 workers (8 honest, 2 Byzantine)
 honest = torch.randn(8, 100)
@@ -44,12 +44,21 @@ This project supports Python **3.10 through 3.14**.
 pip install krum
 ```
 
+This installs **PyTorch**, **torchvision**, and **pandas**. Additional
+dependencies (``matplotlib``, ``numpy``, ``seaborn``) are required for running experiments
+and visualisations:
+
+```bash
+pip install "krum[experiments]"
+```
+
 With `uv` (Recommended):
 
 ```bash
 uv pip install krum
 # or directly in a uv project
 uv add krum
+uv add "krum[experiments]"  # with optional experiment deps
 ```
 
 ### From source
@@ -60,15 +69,15 @@ install in editable mode with the development dependencies:
 ```bash
 git clone https://github.com/calicarpa/krum.git
 cd krum
-pip install -e ".[dev]"
+pip install -e ".[dev,experiments]"
 ```
 
 With `uv` (Recommended):
 
 ```bash
 git clone https://github.com/calicarpa/krum.git
 cd krum
-uv sync --extra dev
+uv sync --all-extras --all-groups
 ```
 
 This installs all linting, type-checking, and documentation tools.

diff --git a/docs/conf.py b/docs/conf.py
@@ -158,6 +158,10 @@ def linkcode_resolve(domain, info):
             "title": "Quickstart",
             "url": "quickstart",
         },
+        {
+            "title": "Tutorials",
+            "url": "tutorials/index",
+        },
         {
             "title": "Reference",
             "children": [

diff --git a/docs/index.rst b/docs/index.rst
@@ -26,6 +26,15 @@ Quickstart
 
    quickstart
 
+Tutorials
+---------
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Tutorials
+
+   tutorials/index
+
 Reference
 ---------
 

diff --git a/docs/quickstart.rst b/docs/quickstart.rst
@@ -1,8 +1,7 @@
 Quickstart
 ==========
 
-This guide walks you through installation, basic usage, and key concepts
-of Krum.
+This guide walks you through installing Krum and running your first command.
 
 Installation
 ------------
@@ -37,190 +36,45 @@ install in editable mode with the development dependencies:
 
    git clone https://github.com/calicarpa/krum.git
    cd krum
-   pip install -e ".[dev]"
+   pip install -e ".[dev,experiments]"
 
 With ``uv`` (recommended):
 
 .. code-block:: bash
 
    git clone https://github.com/calicarpa/krum.git
    cd krum
-   uv sync --extra dev
+   uv sync --all-extras --all-groups
 
 Dependencies
 ~~~~~~~~~~~~
 
-Krum's only runtime dependencies are **PyTorch** and **torchvision**. If you plan
-to use CUDA, ensure your PyTorch build matches your CUDA version. All other
-requirements are pulled in automatically when you install Krum.
+Krum's runtime dependencies are **PyTorch**, **torchvision**, and **pandas**.
+If you plan to use CUDA, ensure your PyTorch build matches your CUDA version.
+For experiments and visualisations, install the optional extras:
 
-Basic Usage
------------
-
-Here's a minimal example showing how to use Krum's aggregators and attacks:
-
-.. code-block:: python
-
-   import torch
-   from krum.primitives.aggregators import Krum, Average
-   from krum.primitives.attacks import Gaussian, SignFlip
-
-   # Simulate gradients from 10 workers (each gradient has 100 parameters)
-   n_workers = 10
-   grad_dim = 100
-   n_byzantine = 2
-
-   # Honest worker gradients (normally distributed)
-   honest_gradients = torch.randn(n_workers - n_byzantine, grad_dim)
-
-   # Byzantine attack: generate malicious gradients
-   attack = Gaussian(std=10.0)
-   byzantine_gradients = attack.generate(honest_gradients, f=n_byzantine)
-
-   # Combine all gradients
-   all_gradients = torch.cat([honest_gradients, byzantine_gradients], dim=0)
-
-   # Aggregate using Krum (Byzantine-resilient)
-   robust_result = Krum.aggregate(all_gradients, n=n_workers, f=n_byzantine)
+.. code-block:: bash
 
-   # Compare with simple average (not resilient)
-   naive_result = Average.aggregate(all_gradients)
+   pip install "krum[experiments]"
 
-   print(f"Krum result norm: {robust_result.norm().item():.4f}")
-   print(f"Average result norm: {naive_result.norm().item():.4f}")
+This adds ``matplotlib``, ``numpy``, and ``seaborn``.
 
-Key Concepts
+Sanity check
 ------------
 
-Aggregators
-~~~~~~~~~~~
-
-Aggregators are **stateless** gradient aggregation rules. Call them as classmethods:
-
-.. code-block:: python
-
-   from krum.primitives.aggregators import Average, Median, TrimmedMean, Krum, MultiKrum, Bulyan, Brute, GeoMed
-
-   # Simple average (baseline, no resilience)
-   result = Average.aggregate(gradients)
-
-   # Coordinate-wise median (basic resilience)
-   result = Median.aggregate(gradients)
-
-   # Trimmed mean (basic resilience, requires 2f+1 workers)
-   result = TrimmedMean.aggregate(gradients, f=2)
-
-   # Krum (moderate resilience, requires 2f+3 workers)
-   result = Krum.aggregate(gradients, n=10, f=2)
-
-   # Multi-Krum (moderate resilience, averages m= n-f-2 gradients)
-   result = MultiKrum.aggregate(gradients, n=10, f=2)
-
-   # Bulyan (strong resilience, two-stage, requires 4f+3 workers)
-   result = Bulyan.aggregate(gradients, n=15, f=2)
-
-Attacks
-~~~~~~~
-
-Attacks generate Byzantine gradients from honest worker gradients:
-
-.. code-block:: python
-
-   from krum.primitives.attacks import SignFlip, ALIE, Gaussian, Omniscient, SmallPerturbation
-
-   # Sign flip attack
-   byzantine = SignFlip.generate(honest_gradients, f=2, scale=1.5)
-
-   # ALIE (A Little Is Enough) attack
-   byzantine = ALIE.generate(honest_gradients, f=2, z=2.0)
-
-   # Gaussian attack
-   byzantine = Gaussian.generate(honest_gradients, f=2, std=10.0)
-
-   # Omniscient attack (requires full dataset gradient)
-   byzantine = Omniscient.generate(honest_gradients, f=2, kappa=100.0, full_gradient=full_grad)
-
-   # Small perturbation attack (exploits curse of dimensionality)
-   byzantine = SmallPerturbation.generate(honest_gradients, f=2, aggregator=Krum, n=10, p=2)
-
-Model Wrapper
-~~~~~~~~~~~~~
-
-Krum provides a ``Model`` wrapper for zero-copy flat views of PyTorch parameters and gradients:
-
-.. code-block:: python
-
-   from krum.primitives.models import Model
-   import torch.nn as nn
-
-   module = nn.Linear(10, 5)
-   model = Model(module)
-
-   # Flat parameter view (zero-copy, lazy-initialized)
-   flat_params = model.parameters  # shape: (55,)
-
-   # Flat gradients after backward()
-   loss = module(torch.randn(3, 10)).sum()
-   loss.backward()
-   flat_grads = model.gradients  # shape: (55,)
-
-   # Write aggregated gradients back (zero-copy relink)
-   model.gradients = aggregated_flat
-
-.. note::
-
-   ``zero_grad(set_to_none=True)`` (the default since PyTorch 2.11) replaces
-   each ``.grad`` with ``None``, breaking the cached flat gradient view.
-   After calling ``zero_grad()``, access ``.gradients`` via
-   ``relink_gradients()`` to restore the link in a single call:
-
-   .. code-block:: python
-
-      optimizer.zero_grad()                    # drops .grad tensors
-      grads = model.relink_gradients()         # re-link + get flat view
-      grads[:] = 0                             # equivalent to zero_grad
-
-   The same pattern applies to :meth:`~krum.primitives.models.Model.relink_parameters`
-   when a parameter's ``.data`` has been replaced externally.
-
-   Both methods return the flat tensor directly, so no further property access is
-   needed.
-
-Standard Models
-~~~~~~~~~~~~~~~
-
-Krum provides standard models used in the literature for Byzantine-resilient
-distributed learning simulations:
-
 .. code-block:: python
 
-   from krum.primitives.models import Krum2017MLPMnist, Krum2017MLPSpambase, Krum2017CNN, Monna2023SmallMnist
-
-   # MLP for MNIST (784 → 100 → 10)
-   mlp = Krum2017MLPMnist()
-
-   # MLP for Spambase (57 → 20 → 20 → 2)
-   spambase = Krum2017MLPSpambase()
-
-   # CNN for CIFAR-10 (3×32×32 → 10)
-   cnn = Krum2017CNN()
-
-   # Small MLP for MNIST (784 → 128 → 10)
-   small_mnist = Monna2023SmallMnist()
-
-These models can be wrapped with the ``Model`` class for zero-copy flat views:
-
-.. code-block:: python
-
-   from krum.primitives.models import Model, Krum2017MLPMnist
+   import torch
+   from krum.primitives.aggregators.krum import Krum
 
-   model = Model(Krum2017MLPMnist())
-   flat_params = model.parameters  # shape: (d,) where d ≈ 80,000
+   result = Krum.aggregate(torch.randn(10, 100), n=10, f=2)
+   print(result.shape)  # (100,)
 
-Next Steps
+Next steps
 ----------
 
-- Browse the :doc:`reference/primitives/models/index` for standard models
-- Browse the :doc:`reference/primitives/aggregators/index` for all available aggregation rules
-- Browse the :doc:`reference/primitives/attacks/index` for all available attack strategies
-- See :doc:`reference/simulations/index` for reproducing published experiments in distributed settings
+Dive into the :doc:`tutorials/index` for step-by-step guides:
+
+* :doc:`tutorials/centralised_simulation_walkthrough` — using the built-in simulations
+* :doc:`tutorials/using_aggregators_attacks` — how to use all built-in aggregators and attacks
+* :doc:`tutorials/working_with_models` — zero-copy flat tensor views and standard models
diff --git a/docs/reference/primitives/aggregators/classes/aksel.rst b/docs/reference/primitives/aggregators/classes/aksel.rst
@@ -1,7 +1,7 @@
 AKSEL
 =====
 
-.. automodule:: aggregators.aksel
+.. automodule:: krum.primitives.aggregators.aksel
    :members:
    :undoc-members:
    :show-inheritance:

diff --git a/docs/reference/primitives/aggregators/classes/average.rst b/docs/reference/primitives/aggregators/classes/average.rst
@@ -1,7 +1,7 @@
 Average
 =======
 
-.. automodule:: aggregators.average
+.. automodule:: krum.primitives.aggregators.average
    :members:
    :undoc-members:
    :show-inheritance:

diff --git a/docs/reference/primitives/aggregators/classes/brute.rst b/docs/reference/primitives/aggregators/classes/brute.rst
@@ -1,7 +1,7 @@
 Brute
 =====
 
-.. automodule:: aggregators.brute
+.. automodule:: krum.primitives.aggregators.brute
    :members:
    :undoc-members:
    :show-inheritance:

diff --git a/docs/reference/primitives/aggregators/classes/bulyan.rst b/docs/reference/primitives/aggregators/classes/bulyan.rst
@@ -1,7 +1,7 @@
 Bulyan
 ======
 
-.. automodule:: aggregators.bulyan
+.. automodule:: krum.primitives.aggregators.bulyan
    :members:
    :undoc-members:
    :show-inheritance:

diff --git a/docs/reference/primitives/aggregators/classes/geomed.rst b/docs/reference/primitives/aggregators/classes/geomed.rst
@@ -1,7 +1,7 @@
 GeoMed
 ======
 
-.. automodule:: aggregators.geomed
+.. automodule:: krum.primitives.aggregators.geomed
    :members:
    :undoc-members:
    :show-inheritance:

diff --git a/docs/reference/primitives/aggregators/classes/krum.rst b/docs/reference/primitives/aggregators/classes/krum.rst
@@ -1,7 +1,7 @@
 Krum
 ====
 
-.. automodule:: aggregators.krum
+.. automodule:: krum.primitives.aggregators.krum
    :members:
    :undoc-members:
    :show-inheritance:

diff --git a/docs/reference/primitives/aggregators/classes/median.rst b/docs/reference/primitives/aggregators/classes/median.rst
@@ -1,7 +1,7 @@
 Median
 ======
 
-.. automodule:: aggregators.median
+.. automodule:: krum.primitives.aggregators.median
    :members:
    :undoc-members:
    :show-inheritance:

diff --git a/docs/reference/primitives/aggregators/classes/multikrum.rst b/docs/reference/primitives/aggregators/classes/multikrum.rst
@@ -1,7 +1,7 @@
 MultiKrum
 =========
 
-.. automodule:: aggregators.multikrum
+.. automodule:: krum.primitives.aggregators.multikrum
    :members:
    :undoc-members:
    :show-inheritance:

diff --git a/docs/reference/primitives/aggregators/classes/nearest_neighbor_average.rst b/docs/reference/primitives/aggregators/classes/nearest_neighbor_average.rst
@@ -1,7 +1,7 @@
 Nearest Neighbor Average
 ========================
 
-.. automodule:: aggregators.nearest_neighbor_average
+.. automodule:: krum.primitives.aggregators.nearest_neighbor_average
    :members:
    :undoc-members:
    :show-inheritance:

diff --git a/docs/reference/primitives/aggregators/classes/trimmed_mean.rst b/docs/reference/primitives/aggregators/classes/trimmed_mean.rst
@@ -1,7 +1,7 @@
 Trimmed Mean
 ============
 
-.. automodule:: aggregators.trimmed_mean
+.. automodule:: krum.primitives.aggregators.trimmed_mean
    :members:
    :undoc-members:
    :show-inheritance:

diff --git a/docs/reference/primitives/attacks/classes/alie.rst b/docs/reference/primitives/attacks/classes/alie.rst
@@ -1,7 +1,7 @@
 A Little Is Enough
 ==================
 
-.. automodule:: attacks.alie
+.. automodule:: krum.primitives.attacks.alie
    :members:
    :undoc-members:
    :show-inheritance: