📝 Add Examples

Author: lishenghui

blades/aggregators/__init__.py

@@ -6,12 +6,12 @@
 
 __all__ = [
     "Mean",
-    "Median",
-    "Trimmedmean",
-    "GeoMed",
-    "DnC",
-    "Clippedclustering",
-    "Signguard",
-    "Multikrum",
-    "Centeredclipping",
+    # "Median",
+    # "Trimmedmean",
+    # "GeoMed",
+    # "DnC",
+    # "Clippedclustering",
+    # "Signguard",
+    # "Multikrum",
+    # "Centeredclipping",
 ]

blades/aggregators/aggregators.py

@@ -17,16 +17,29 @@ def _median(inputs: List[torch.Tensor]):
 
 
 class Mean(object):
+    """Computes the ``sample mean`` over the updates from all give clients."""
+
     def __call__(self, inputs: List[torch.Tensor]):
         return _mean(inputs)
 
 
 class Median(object):
+    """Partitioner that uses Dirichlet distribution to allocate samples to
+    clients."""
+
     def __call__(self, inputs: List[torch.Tensor]):
+        """A robust aggregator from paper `Byzantine-robust distributed
+        learning:
+
+        Towards optimal statistical rates.<https://proceedings.mlr.press/v80/yin18a>`_.
+        It computes the coordinate-wise median of the given set of clients
+        """
         return _median(inputs)
 
 
 class Trimmedmean(object):
+    """A robust aggregator."""
+
     def __init__(self, num_byzantine: int, *, filter_frac=1.0):
         if filter_frac > 1.0 or filter_frac < 0.0:
             raise ValueError(f"filter_frac should be in [0.0, 1.0], got {filter_frac}.")

blades/aggregators/clippedclustering.py

@@ -10,9 +10,14 @@
 
 
 class Clippedclustering(object):
-    def __init__(self, agg="mean", max_tau=1e5, linkage="average") -> None:
-        super(Clippedclustering, self).__init__()
-
+    """Clipped clustering aggregator."""
+
+    # def __init__(self, agg="mean", max_tau=1e5, linkage="average") -> None:
+    def __init__(self):
+        agg = "mean"
+        max_tau = 1e5
+        linkage = "average"
+        # def __init__(self, agg="mean", max_tau=1e5, linkage="average") -> None:
         assert linkage in ["average", "single"]
         self.tau = max_tau
         self.linkage = linkage

blades/aggregators/signguard.py

@@ -9,11 +9,10 @@
 
 
 class Signguard(object):
-    r"""A robust aggregator from paper `Xu et al.
+    """A robust aggregator from paper `Xu et al. SignGuard: Byzantine-robust
+    Federated Learning through Collaborative Malicious Gradient Filtering.
 
-    SignGuard: Byzantine-robust Federated
-    Learning through Collaborative Malicious Gradient
-    Filtering <https://arxiv.org/abs/2109.05872>`_.
+    <https://arxiv.org/abs/2109.05872>`_.
     """
 
     def __init__(self, agg="mean", max_tau=1e5, linkage="average") -> None:

docs/requirements.txt

@@ -1,3 +1,9 @@
 git+https://github.com/fedlib/blades_sphinx_theme.git
+lxml_html_clean
+m2r2
 nbsphinx
+nbsphinx-link
 numpy>=1.19.5
+sphinx==5.1.1
+sphinx_autodoc_typehints
+sphinx_gallery

docs/source/_examples/_examples_jupyter.zip

@@ -0,0 +1,43 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "\n# Customize Attack\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "import ray\nfrom ray import tune\nfrom ray.tune.stopper import MaximumIterationStopper\n\nfrom blades.algorithms.fedavg import FedavgConfig, Fedavg\nfrom fedlib.trainers import TrainerConfig\n\n\nfrom fedlib.trainers import Trainer\nfrom fedlib.clients import ClientCallback\nfrom blades.adversaries import Adversary\n\n\nclass LabelFlipAdversary(Adversary):\n    def on_trainer_init(self, trainer: Trainer):\n        class LabelFlipCallback(ClientCallback):\n            def on_train_batch_begin(self, data, target):\n                return data, 10 - 1 - target\n\n        for client in self.clients:\n            client.to_malicious(callbacks_cls=LabelFlipCallback, local_training=True)\n\n\nclass ExampleFedavgConfig(FedavgConfig):\n    def __init__(self, algo_class=None):\n        \"\"\"Initializes a FedavgConfig instance.\"\"\"\n        super().__init__(algo_class=algo_class or ExampleFedavg)\n\n        self.dataset_config = {\n            \"type\": \"FashionMNIST\",\n            \"num_clients\": 10,\n            \"train_batch_size\": 32,\n        }\n        self.global_model = \"cnn\"\n        self.num_malicious_clients = 1\n        self.adversary_config = {\"type\": LabelFlipAdversary}\n\n\nclass ExampleFedavg(Fedavg):\n    @classmethod\n    def get_default_config(cls) -> TrainerConfig:\n        return ExampleFedavgConfig()\n\n\nif __name__ == \"__main__\":\n    ray.init()\n\n    config_dict = (\n        ExampleFedavgConfig()\n        .resources(\n            num_gpus_for_driver=0.0,\n            num_cpus_for_driver=1,\n            num_remote_workers=0,\n            num_gpus_per_worker=0.0,\n        )\n        .to_dict()\n    )\n    print(config_dict)\n    tune.run(\n        ExampleFedavg,\n        config=config_dict,\n        stop=MaximumIterationStopper(100),\n    )"
+      ]
+    }
+  ],
+  "metadata": {
+    "kernelspec": {
+      "display_name": "Python 3",
+      "language": "python",
+      "name": "python3"
+    },
+    "language_info": {
+      "codemirror_mode": {
+        "name": "ipython",
+        "version": 3
+      },
+      "file_extension": ".py",
+      "mimetype": "text/x-python",
+      "name": "python",
+      "nbconvert_exporter": "python",
+      "pygments_lexer": "ipython3",
+      "version": "3.10.14"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 0
+}

docs/source/_examples/_examples_python.zip

@@ -0,0 +1,70 @@
+"""
+Customize Attack
+==================
+
+"""
+
+
+import ray
+from ray import tune
+from ray.tune.stopper import MaximumIterationStopper
+
+from blades.algorithms.fedavg import FedavgConfig, Fedavg
+from fedlib.trainers import TrainerConfig
+
+
+from fedlib.trainers import Trainer
+from fedlib.clients import ClientCallback
+from blades.adversaries import Adversary
+
+
+class LabelFlipAdversary(Adversary):
+    def on_trainer_init(self, trainer: Trainer):
+        class LabelFlipCallback(ClientCallback):
+            def on_train_batch_begin(self, data, target):
+                return data, 10 - 1 - target
+
+        for client in self.clients:
+            client.to_malicious(callbacks_cls=LabelFlipCallback, local_training=True)
+
+
+class ExampleFedavgConfig(FedavgConfig):
+    def __init__(self, algo_class=None):
+        """Initializes a FedavgConfig instance."""
+        super().__init__(algo_class=algo_class or ExampleFedavg)
+
+        self.dataset_config = {
+            "type": "FashionMNIST",
+            "num_clients": 10,
+            "train_batch_size": 32,
+        }
+        self.global_model = "cnn"
+        self.num_malicious_clients = 1
+        self.adversary_config = {"type": LabelFlipAdversary}
+
+
+class ExampleFedavg(Fedavg):
+    @classmethod
+    def get_default_config(cls) -> TrainerConfig:
+        return ExampleFedavgConfig()
+
+
+if __name__ == "__main__":
+    ray.init()
+
+    config_dict = (
+        ExampleFedavgConfig()
+        .resources(
+            num_gpus_for_driver=0.0,
+            num_cpus_for_driver=1,
+            num_remote_workers=0,
+            num_gpus_per_worker=0.0,
+        )
+        .to_dict()
+    )
+    print(config_dict)
+    tune.run(
+        ExampleFedavg,
+        config=config_dict,
+        stop=MaximumIterationStopper(100),
+    )

docs/source/_examples/customize_attack.ipynb

@@ -0,0 +1,114 @@
+
+.. DO NOT EDIT.
+.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
+.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
+.. "_examples/customize_attack.py"
+.. LINE NUMBERS ARE GIVEN BELOW.
+
+.. only:: html
+
+    .. note::
+        :class: sphx-glr-download-link-note
+
+        :ref:`Go to the end <sphx_glr_download__examples_customize_attack.py>`
+        to download the full example code.
+
+.. rst-class:: sphx-glr-example-title
+
+.. _sphx_glr__examples_customize_attack.py:
+
+
+Customize Attack
+==================
+
+.. GENERATED FROM PYTHON SOURCE LINES 6-71
+
+.. code-block:: Python
+
+
+
+    import ray
+    from ray import tune
+    from ray.tune.stopper import MaximumIterationStopper
+
+    from blades.algorithms.fedavg import FedavgConfig, Fedavg
+    from fedlib.trainers import TrainerConfig
+
+
+    from fedlib.trainers import Trainer
+    from fedlib.clients import ClientCallback
+    from blades.adversaries import Adversary
+
+
+    class LabelFlipAdversary(Adversary):
+        def on_trainer_init(self, trainer: Trainer):
+            class LabelFlipCallback(ClientCallback):
+                def on_train_batch_begin(self, data, target):
+                    return data, 10 - 1 - target
+
+            for client in self.clients:
+                client.to_malicious(callbacks_cls=LabelFlipCallback, local_training=True)
+
+
+    class ExampleFedavgConfig(FedavgConfig):
+        def __init__(self, algo_class=None):
+            """Initializes a FedavgConfig instance."""
+            super().__init__(algo_class=algo_class or ExampleFedavg)
+
+            self.dataset_config = {
+                "type": "FashionMNIST",
+                "num_clients": 10,
+                "train_batch_size": 32,
+            }
+            self.global_model = "cnn"
+            self.num_malicious_clients = 1
+            self.adversary_config = {"type": LabelFlipAdversary}
+
+
+    class ExampleFedavg(Fedavg):
+        @classmethod
+        def get_default_config(cls) -> TrainerConfig:
+            return ExampleFedavgConfig()
+
+
+    if __name__ == "__main__":
+        ray.init()
+
+        config_dict = (
+            ExampleFedavgConfig()
+            .resources(
+                num_gpus_for_driver=0.0,
+                num_cpus_for_driver=1,
+                num_remote_workers=0,
+                num_gpus_per_worker=0.0,
+            )
+            .to_dict()
+        )
+        print(config_dict)
+        tune.run(
+            ExampleFedavg,
+            config=config_dict,
+            stop=MaximumIterationStopper(100),
+        )
+
+
+.. _sphx_glr_download__examples_customize_attack.py:
+
+.. only:: html
+
+  .. container:: sphx-glr-footer sphx-glr-footer-example
+
+    .. container:: sphx-glr-download sphx-glr-download-jupyter
+
+      :download:`Download Jupyter notebook: customize_attack.ipynb <customize_attack.ipynb>`
+
+    .. container:: sphx-glr-download sphx-glr-download-python
+
+      :download:`Download Python source code: customize_attack.py <customize_attack.py>`
+
+
+.. only:: html
+
+ .. rst-class:: sphx-glr-signature
+
+    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_