Merge branch 'main' into table_docs

README.md

@@ -2,6 +2,8 @@
 
 # Project SONAR - Self-Organizing Network of Aggregated Representations
 
+Documentation: https://aidecentralized.github.io/sonar/
+
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 [![Documentation Status](https://readthedocs.org/projects/markdown-guide/badge/?version=latest)](https://aidecentralized.github.io/sonar/)
 
@@ -14,12 +16,10 @@ The application currently uses MPI and GRPC (experimental) to enable communicati
 
 ### Framework Rewrite Objective
 - [ ] O1: Benchmark existing configurations and algorithms.
-- [x] O2: Separate the communication layer (topology) from collaborative learning algorithms.
+- [ ] O2: Separate the communication layer (topology) from collaborative learning algorithms.
 - [ ] O3: Implement a few more collaborative learning algorithms.
-- [ ] O4: Write the GRPC module for the communication layer. Then we don't need to rely on MPI which requires ssh access to all the nodes. See https://github.com/aidecentralized/sonar/issues/20
-- [ ] O5: Improve telemetry and logging for visualization of the network. See https://github.com/aidecentralized/sonar/issues/11
-- [ ] O6: Fault tolerance and rogue clients simulation.
-- [ ] O7: Comprehensive documentation - https://github.com/squidfunk/mkdocs-material
-- [ ] O8: Eliminate the need to add a BaseServer module, keep it backward compatible by instantiating the server as yet another node.
-- [ ] O9: Build testing suite. See https://github.com/aidecentralized/sonar/issues/21
-- [ ] O10: Set up milestones for transition to full API like interface and then launch on `pip`
+- [ ] O4: Improve telemetry and logging for visualization of the network. See https://github.com/aidecentralized/sonar/issues/11
+- [ ] O5: Fault tolerance and rogue clients simulation.
+- [ ] O6: Eliminate the need to add a BaseServer module, keep it backward compatible by instantiating the server as yet another node.
+- [ ] O7: Build testing suite. See https://github.com/aidecentralized/sonar/issues/21
+- [ ] O8: Set up milestones for transition to full API like interface and then launch on `pip`

docs/getting-started/issues.md → docs/development.md

@@ -1,4 +1,4 @@
-# Issues
+# Development
 
 Please view a list of issues to improve this project on the [Github Issues](https://github.com/aidecentralized/sonar/issues) Page. 
 

docs/getting-started/issues/sonar.md → docs/development/sonar.md

@@ -1,4 +1,4 @@
-# SONAR Project
+# Contribution Guidelines
 To begin working on the project, please follow the set up instructions.
 
 ### Set up SONAR on Local

docs/index.md

@@ -52,6 +52,7 @@ The application currently uses MPI and GRPC (experimental) to enable communicati
 |      3      | 179.1761            | 153.0658      |
 |      5      | 176.5059            | 139.4547      |
 
+
 *AUC Digit-Five (30 users, 200 rounds)*
 | Num Domains | Within Domain       | Random        |
 |-------------|---------------------|---------------|
@@ -73,7 +74,6 @@ The application currently uses MPI and GRPC (experimental) to enable communicati
 | 500    | 0.4726                    | 0.0502                 | 0.4499                    | 0.0496                 |
 
 
-
 | Rounds |          Camelyon17 (39 users, 3 domains)          |               |               |               |
 |--------|-----------------------------------------------------|---------------|---------------|---------------|
 |        |                  Within Domain                      |               |                Random             |               |

docs/tasks.md

@@ -1,3 +1,3 @@
 # Tasks
 
-Welcome to the **Tasks** section of our repository! Here, you'll find resources and guides for three core tasks in machine learning: Image Classification, Object Detection, and Text Classification.
+Welcome to the **Tasks** section of our repository! Here, you'll find the core tasks and experiments we have integrated with SONAR. These use cases are being expanded. To contribute to this project, please review our [Github Issues](https://github.com/aidecentralized/sonar/issues) page.

docs/tasks/image-classification.md

@@ -1 +1,60 @@
-# Image Classification
+# Image Classification
+
+## Overview
+Our environment supports image classification tasks using various ResNet architectures. We provide implementations of ResNet models tailored for different image classification tasks across several datasets. ResNet (Residual Network) models are widely recognized for their effectiveness in deep learning, particularly in image recognition tasks. In this project, we utilize ResNet models to classify images from multiple datasets, including DomainNet, Camelyon17, Digit-Five, CIFAR-10, CIFAR-100, and Medical MNIST. The implementation is designed to handle decentralized machine learning scenarios, allowing multiple users to train a shared model while keeping their data localized.
+
+### Credit:
+Credit to Huawei Technologies Co., Ltd. <foss@huawei.com> for ResNet. Taken from [Huawei ResNet implementation](https://github.com/huawei-noah/Data-Efficient-Model-Compression/blob/master/DAFL/resnet.py) for comparison with DAFL.
+
+## Dataset Preparation
+We use several datasets for image classification tasks, including DomainNet, Camelyon17, Digit-Five, CIFAR-10, CIFAR-100, and Medical MNIST. Each dataset has specific characteristics and is used for different types of classification tasks. Follow the steps below to download and prepare the datasets:
+1) Download the respective datasets from their official sources:
+   - **DomainNet**: [DomainNet Dataset page](http://ai.bu.edu/M3SDA/)
+   - **Camelyon17**: [Camelyon17 Dataset page](https://camelyon17.grand-challenge.org/)
+   - **Digit-Five**: Collection of five digit datasets, including [MNIST](http://yann.lecun.com/exdb/mnist/), [SVHN](http://ufldl.stanford.edu/housenumbers/), [USPS](https://github.com/keras-team/keras/blob/master/keras/datasets/usps.py), [SYN](https://github.com/gabrieleilertsen/unsupervised-mnist/tree/master/unsupervised_mnist/syn), [MNIST-M](https://github.com/NaJaeMin92/MNIST-M)
+   - **CIFAR-10** and **CIFAR-100**: [CIFAR Dataset page](https://www.cs.toronto.edu/~kriz/cifar.html)
+   - **Medical MNIST**: [Medical MNIST Dataset page](https://www.kaggle.com/andrewmvd/medical-mnist)
+
+## Configure the Training
+To set up the training environment, follow these instructions:
+1) Install Dependencies: If you haven't already, run `pip install -r requirements.txt`.
+2) Configure the system settings. In `src/configs/sys_config.py`, create a system config object such as the example below, with your desired settings.
+```
+image_classification_system_config = {
+    "num_users": 4, 
+    "dset": "cifar10",
+    "dump_dir": "./expt_dump/", # the path to place the results
+    "dpath": "./datasets/imgs/cifar10/", # the location of the dataset
+    "device_ids": {"node_0": [0], "node_1": [0], "node_2": [0], "node_3": [0]},
+    "samples_per_user": 1000, 
+    "train_label_distribution": "iid",
+    "test_label_distribution": "iid",
+    "folder_deletion_signal_path":"./expt_dump/folder_deletion.signal"
+}
+```
+3) Configure the algorithm settings. In `src/configs/algo_config.py`, create an algo config object such as the example below, with your desired algorithm.
+
+```
+fedavg_image_classify = {
+    "algo": "fedavg", # choose any algorithm we support
+    "exp_id": "image_classification",
+    # Learning setup
+    "epochs": 20,
+    "model": "resnet18",
+    "model_lr": 1e-3,
+    "batch_size": 64,
+}
+```
+
+4) Initiate Training: `mpirun -n 5 python3 main.py`
+
+> *Note: the `-n` flag should be followed by (number of desired users + 1), for the server node.*
+
+> The training will proceed across the users as configured. Monitor printed or saved logs to track progress.
+
+> Your result will be written into the `dump_dir` path specified in `sys_config.py`.
+
+## Additional Notes
+
+* Ensure that the setup is correctly configured to avoid issues with client-server communication.
+* If you encounter any issues or have suggestions, please open an issue on our [GitHub repository](https://github.com/aidecentralized/sonar).

docs/tasks/object-detection.md

@@ -3,7 +3,7 @@
 ## Overview
 Our environment supports object detection and classification tasks. We support an implementation of YOLOv3 objection detection model using the Pascal VOC dataset. The YOLOv3 (You Only Look Once, version 3) model is a state-of-the-art object detection algorithm known for its speed and accuracy. It performs both object detection and classification in a single forward pass through the network, making it highly efficient. In this project, we adapt YOLOv3 to work in a decentralized machine learning setup, which allows multiple users to train a shared model while keeping their data localized.
 
-### Credit:
+### Credit
 The implementation of YOLOv3 in this project is based on the [GeeksforGeeks YOLOv3 tutorial](https://www.geeksforgeeks.org/yolov3-from-scratch-using-pytorch/). Special thanks to the authors for providing a detailed guide that served as the foundation for this work.
 
 ## Dataset Preparation

docs/tasks/text-classification.md

@@ -1,9 +1,11 @@
 # Text Classification
 
+> **_NOTE:_**  This task is a work in progress. We are currently running experiments to ensure support for Text Classification. It is currently not integrated properly with the system yet.
+
 ## Overview
 Our environment supports text classification tasks using Long Short-Term Memory (LSTM) networks. We provide an implementation of an LSTM-based text classification model using the AGNews dataset. The LSTM model is a type of recurrent neural network (RNN) that is particularly effective for sequential data such as text. In this project, we adapt an LSTM network to classify news articles into one of four categories: World, Sports, Business, and Sci/Tech. The implementation is designed to handle decentralized machine learning scenarios, where multiple users can train a shared model while keeping their data localized.
 
-### Credit:
+### Credit
 The AG's news topic classification dataset is constructed by Xiang Zhang (xiang.zhang@nyu.edu). It is used as a text classification benchmark in the following paper: Xiang Zhang, Junbo Zhao, Yann LeCun. Character-level Convolutional Networks for Text Classification. Advances in Neural Information Processing Systems 28 (NIPS 2015). This dataset is based on the [AGNews Dataset](http://www.di.unipi.it/~gulli/AG_corpus_of_news_articles.html). 
 
 ## Dataset Preparation
@@ -66,9 +68,12 @@ fedavg_text_classify = {
 }
 ```
 4) Initiate Training: `mpirun -n 4 python3 main.py`
-* *Note: the `-n` flag should be followed by (number of desired users + 1), for the server node.*
-* The training will proceed across the users as configured. Monitor printed or saved logs to track progress.
-* Your result will be written into the `dump_dir` path specified in `sys_config.py`.
+
+> *Note: the `-n` flag should be followed by (number of desired users + 1), for the server node.*
+
+> The training will proceed across the users as configured. Monitor printed or saved logs to track progress.
+
+> Your result will be written into the `dump_dir` path specified in `sys_config.py`.
 
 ## Additional Notes
 * Ensure that the setup is correctly configured to avoid issues with client-server communication.

mkdocs.yml

@@ -9,11 +9,7 @@ nav:
   - Home:
     - Home: index.md
   - Getting Started:
-      - Main: getting-started/getting-started.md
-      - Issues:
-          - Overview: getting-started/issues.md
-          - Documentation: getting-started/issues/documentation.md
-          - Contribution Guidelines: getting-started/issues/sonar.md
+      - Main: getting-started.md
   - CollaBench:
     - Main: collabench.md
   - Algorithms:
@@ -30,8 +26,10 @@ nav:
     - Main: logging/logging.md
     - Log Details: logging/log_details.md
   - Development:
-    - Contribution Guidelines: contributing/contribution-guidelines.md
-    - Documentation: contributing/documentation.md
+    - Overview: development.md
+    - Contribution Guidelines: development/sonar.md
+    - Documentation: development/documentation.md
+
 #
 # Theme Settings
 #
@@ -58,8 +56,8 @@ theme:
     - search.suggest
     - search.highlight
     # https://squidfunk.github.io/mkdocs-material/setup/adding-a-git-repository/#code-actions
-    - content.action.edit
-    - content.action.view
+    # - content.action.edit
+    # - content.action.view
     # https://squidfunk.github.io/mkdocs-material/reference/code-blocks/#configuration
     - content.code.copy
     - content.code.select