(singa) branch dev-postgresql updated: Create a horizontal federated learning example

[zh...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

zhaojing pushed a commit to branch dev-postgresql
in repository https://gitbox.apache.org/repos/asf/singa.git


The following commit(s) were added to refs/heads/dev-postgresql by this push:
     new 323acf0c Create a horizontal federated learning example
     new d632b6de Merge pull request #1124 from lemonviv/add-hfl-example
323acf0c is described below

commit 323acf0c3889c506a401de2d1fed90bc1de1a18a
Author: lemonviv <le...@gmail.com>
AuthorDate: Sat Dec 9 13:57:18 2023 +0800

    Create a horizontal federated learning example
---
 examples/hfl/README.md        | 43 +++++++++++++++++++++++++++++++++++++++++++
 examples/hfl/data/.gitkeep    |  0
 examples/hfl/requirements.txt |  3 +++
 3 files changed, 46 insertions(+)

diff --git a/examples/hfl/README.md b/examples/hfl/README.md
new file mode 100644
index 00000000..df27512a
--- /dev/null
+++ b/examples/hfl/README.md
@@ -0,0 +1,43 @@
+# Horizontal Federated Learning Example
+
+This is an example of federated learning (FL) using the Singa framework. In FL, there is a server and a set of clients. Each client has a local dataset. 
+In each iteration, each client trains the model using its local dataset and uploads the model gradient to the server, which aggregates to get the global
+gradient using the Federated Average algorithm. The server sends the global gradient to all clients for iterative model training. 
+This example uses the Bank dataset and an MLP model in FL.
+
+## Preparation
+
+Go to the Conda environment that contains the Singa library, and run
+
+```bash
+pip install -r requirements.txt
+```
+
+Download the bank dataset and split it into 3 partitions.
+
+```bash
+# 1. download the data from https://archive.ics.uci.edu/ml/datasets/bank+marketing
+# 2. put it under the /data folder
+# 3. run the following command which:
+#    (1) splits the dataset into N subsets
+#    (2) splits each subsets into train set and test set (8:2)
+python -m bank N
+```
+
+## Run the example
+
+Run the server first (set the number of epochs to 3)
+
+```bash
+python -m src.server -m 3 --num_clients 3
+```
+
+Then, start 3 clients in different terminal
+
+```bash
+python -m src.client --model mlp --data bank -m 3 -i 0 -d non-iid
+python -m src.client --model mlp --data bank -m 3 -i 1 -d non-iid
+python -m src.client --model mlp --data bank -m 3 -i 2 -d non-iid
+```
+
+Finally, the server and clients finish the FL training. 
\ No newline at end of file
diff --git a/examples/hfl/data/.gitkeep b/examples/hfl/data/.gitkeep
new file mode 100644
index 00000000..e69de29b
diff --git a/examples/hfl/requirements.txt b/examples/hfl/requirements.txt
new file mode 100644
index 00000000..ed89f5a7
--- /dev/null
+++ b/examples/hfl/requirements.txt
@@ -0,0 +1,3 @@
+pandas
+scikit-learn
+protobuf
\ No newline at end of file