Migrated all examples to use the new composable trainer architecture. (#389)

Author: baochunli

docs/docs/examples/algorithms/8. Personalized Federated Learning Algorithms.md

@@ -3,8 +3,8 @@
 FedRep learns a shared data representation (the global layers) across clients and a unique, personalized local "head" (the local layers) for each client. In this implementation, after each round of local training, only the representation on each client is retrieved and uploaded to the server for aggregation.
 
 ```bash
-cd examples/personalized_fl/fedrep
-uv run fedrep.py -c ../configs/fedrep_CIFAR10_resnet18.yml
+cd examples/personalized_fl
+uv run fedrep/fedrep.py -c configs/fedrep_CIFAR10_resnet18.yml
 ```
 
 **Reference:** Collins et al., "[Exploiting Shared Representations for Personalized Federated Learning](http://proceedings.mlr.press/v139/collins21a/collins21a.pdf)," in Proc. International Conference on Machine Learning (ICML), 2021.
@@ -16,8 +16,8 @@ uv run fedrep.py -c ../configs/fedrep_CIFAR10_resnet18.yml
 FedBABU only updates the global layers of the model during FL training. The local layers are frozen at the beginning of each local training epoch.
 
 ```bash
-cd examples/personalized_fl/fedbabu
-uv run fedbabu.py -c ../configs/fedbabu_CIFAR10_resnet18.yml
+cd examples/personalized_fl
+uv run fedbabu/fedbabu.py -c configs/fedbabu_CIFAR10_resnet18.yml
 ```
 
 **Reference:** Oh et al., "[FedBABU: Towards Enhanced Representation for Federated Image Classification](https://openreview.net/forum?id=HuaYQfggn5u)," in Proc. International Conference on Learning Representations (ICLR), 2022.
@@ -29,8 +29,8 @@ uv run fedbabu.py -c ../configs/fedbabu_CIFAR10_resnet18.yml
 APFL jointly optimizes the global model and personalized models by interpolating between local and personalized models. Once the global model is received, each client will carry out a regular local update, and then conduct a personalized optimization to acquire a trained personalized model. The trained global model and the personalized model will subsequently be combined using the parameter "alpha," which can be dynamically updated.
 
 ```bash
-cd examples/personalized_fl/apfl
-uv run apfl.py -c ../configs/apfl_CIFAR10_resnet18.yml
+cd examples/personalized_fl
+uv run apfl/apfl.py -c configs/apfl_CIFAR10_resnet18.yml
 ```
 
 **Reference:** Deng et al., "[Adaptive Personalized Federated Learning](https://arxiv.org/abs/2003.13461)," in Arxiv, 2021.
@@ -42,8 +42,8 @@ uv run apfl.py -c ../configs/apfl_CIFAR10_resnet18.yml
 FedPer learns a global representation and personalized heads, but makes simultaneous local updates for both sets of parameters, therefore makes the same number of local updates for the head and the representation on each local round.
 
 ```bash
-cd examples/personalized_fl/fedper
-uv run fedper.py -c ../configs/fedper_CIFAR10_resnet18.yml
+cd examples/personalized_fl
+uv run fedper/fedper.py -c configs/fedper_CIFAR10_resnet18.yml
 ```
 
 **Reference:** Arivazhagan et al., "[Federated learning with personalization layers](https://arxiv.org/abs/1912.00818)," in Arxiv, 2019.
@@ -55,8 +55,8 @@ uv run fedper.py -c ../configs/fedper_CIFAR10_resnet18.yml
 With LG-FedAvg only the global layers of a model are sent to the server for aggregation, while each client keeps local layers to itself.
 
 ```bash
-cd examples/personalized_fl/lgfedavg
-uv run lgfedavg.py -c ../configs/lgfedavg_CIFAR10_resnet18.yml
+cd examples/personalized_fl
+uv run lgfedavg/lgfedavg.py -c configs/lgfedavg_CIFAR10_resnet18.yml
 ```
 
 **Reference:** Liang et al., "[Think Locally, Act Globally: Federated Learning with Local and Global Representations](https://arxiv.org/abs/2001.01523)," in Proc. NeurIPS, 2019.
@@ -68,8 +68,8 @@ uv run lgfedavg.py -c ../configs/lgfedavg_CIFAR10_resnet18.yml
 Ditto jointly optimizes the global model and personalized models by learning local models that are encouraged to be close together by global regularization. In this example, once the global model is received, each client will carry out a regular local update and then optimizes the personalized model.
 
 ```bash
-cd examples/personalized_fl/ditto
-uv run ditto.py -c ../configs/ditto_CIFAR10_resnet18.yml
+cd examples/personalized_fl
+uv run ditto/ditto.py -c configs/ditto_CIFAR10_resnet18.yml
 ```
 
 **Reference:** Li et al., "[Ditto: Fair and robust federated learning through personalization](https://proceedings.mlr.press/v139/li21h.html)," in Proc ICML, 2021.
@@ -81,8 +81,8 @@ uv run ditto.py -c ../configs/ditto_CIFAR10_resnet18.yml
 Per-FedAvg uses the Model-Agnostic Meta-Learning (MAML) framework to perform local training during the regular training rounds. It performs two forward and backward passes with fixed learning rates in each iteration.
 
 ```bash
-cd examples/personalized_fl/perfedavg
-uv run perfedavg.py -c ../configs/perfedavg_CIFAR10_resnet18.yml
+cd examples/personalized_fl
+uv run perfedavg/perfedavg.py -c configs/perfedavg_CIFAR10_resnet18.yml
 ```
 
 **Reference:** Fallah et al., "[Personalized Federated Learning with Theoretical Guarantees: A Model-Agnostic Meta-Learning Approach](https://proceedings.neurips.cc/paper/2020/hash/24389bfe4fe2eba8bf9aa9203a44cdad-Abstract.html)," in Proc NeurIPS, 2020.
@@ -94,8 +94,8 @@ uv run perfedavg.py -c ../configs/perfedavg_CIFAR10_resnet18.yml
 Hermes utilizes structured pruning to improve both communication efficiency and inference efficiency of federated learning. It prunes channels with the lowest magnitudes in each local model and adjusts the pruning amount based on each local model's test accuracy and its previous pruning amount. When the server aggregates pruned updates, it only averages parameters that were not pruned on all clients.
 
 ```bash
-cd examples/personalized_fl/hermes
-uv run hermes.py -c ../configs/hermes_CIFAR10_resnet18.yml
+cd examples/personalized_fl
+uv run hermes/hermes.py -c configs/hermes_CIFAR10_resnet18.yml
 ```
 
 **Reference:** Li et al., "[Hermes: An Efficient Federated Learning Framework for Heterogeneous Mobile Clients](https://sites.duke.edu/angli/files/2021/10/2021_Mobicom_Hermes_v1.pdf)," in Proc. 27th Annual International Conference on Mobile Computing and Networking (MobiCom), 2021.

docs/docs/references/trainers.md

@@ -96,6 +96,7 @@ Plato's trainer system uses a **composition-based architecture** built on the **
 | **LRSchedulerStrategy** | LR scheduling | Custom schedules, warmup |
 | **ModelUpdateStrategy** | State management | Control variates, personalization (SCAFFOLD, Ditto) |
 | **DataLoaderStrategy** | Data loading | Custom sampling, augmentation |
+| **TestingStrategy** | Model evaluation | Custom model evaluation and testing |
 
 ---
 
@@ -193,85 +194,10 @@ class ComposableTrainer(base.Trainer):
 | `data_loader_strategy` | `DataLoaderStrategy` | `DefaultDataLoaderStrategy()` | Strategy for data loading |
 | `testing_strategy` | `TestingStrategy` | `DefaultTestingStrategy()` | Strategy for model evaluation |
 
-#### Key Methods
+#### Methods
 
-!!! note "`train(trainset, sampler, **kwargs) -> float`"
+Here is a list of methods in `ComposableTrainer` that can be called.
 
-    Train the model on the given dataset and sampler.
-
-    **Parameters:**
-
-    - `trainset`: Training dataset
-    - `sampler`: Data sampler for this client
-    - `**kwargs`: Additional arguments
-
-    **Returns:**
-
-    - Training time in seconds
-
-    **Example:**
-
-    ```python
-    training_time = trainer.train(trainset, sampler)
-    ```
-
-!!! note "`test(testset, sampler=None, **kwargs) -> float`"
-    Test the model on the given dataset.
-
-    **Parameters:**
-
-    - `testset`: Test dataset
-    - `sampler`: Optional data sampler
-    - `**kwargs`: Additional arguments
-
-    **Returns:**
-
-    - Test accuracy (0.0 to 1.0)
-
-    **Example:**
-
-    ```python
-    accuracy = trainer.test(testset)
-    print(f"Accuracy: {accuracy * 100:.2f}%")
-    ```
-
-!!! note "`train_model(config, trainset, sampler, **kwargs)`"
-    Main training loop implementation. Called internally by `train()`.
-
-    **Parameters:**
-
-    - `config`: Configuration dictionary
-    - `trainset`: Training dataset
-    - `sampler`: Data sampler
-    - `**kwargs`: Additional arguments
-
-!!! note "`save_model(filename=None, location=None)`"
-    Save model weights and training history.
-
-    **Parameters:**
-
-    - `filename`: Optional custom filename
-    - `location`: Optional custom directory
-
-    **Example:**
-
-    ```python
-    trainer.save_model("my_model.pth")
-    ```
-
-!!! note "`load_model(filename=None, location=None)`"
-    Load model weights and training history.
-
-    **Parameters:**
-
-    - `filename`: Optional custom filename
-    - `location`: Optional custom directory
-
-    **Example:**
-
-    ```python
-    trainer.load_model("my_model.pth")
-    ```
 
 #### Attributes
 
@@ -662,9 +588,9 @@ class ModelUpdateStrategy(Strategy):
 
 #### When to Implement
 
-- Control variates (SCAFFOLD)
-- Dynamic regularization state (FedDyn)
-- Personalization (FedPer, FedRep, Ditto)
+- Control variates (e.g., SCAFFOLD)
+- Dynamic regularization state (e.g., FedDyn)
+- Personalization (e.g., FedPer, FedRep, Ditto)
 - Layer freezing/unfreezing
 - Custom state management
 
@@ -955,6 +881,22 @@ trainer = ComposableTrainer(
 )
 ```
 
+### Testing Strategies
+
+**Location**: `plato.trainers.strategies.testing`
+
+| Strategy | Description | Parameters |
+|----------|-------------|------------|
+| `DefaultTestingStrategy` | Standard Testing | Uses config settings |
+
+**Example:**
+```python
+from plato.trainers.strategies import TestingStrategy
+
+trainer = ComposableTrainer(
+    testing_strategy=DefaultTestingStrategy()
+)
+```
 ---
 
 ## Algorithm-Specific Strategies
@@ -1212,7 +1154,7 @@ algorithm:
 
 ---
 
-### FedMos
+### FedMoS
 
 **Location**: `plato.trainers.strategies.algorithms.fedmos_strategy`
 
@@ -2241,7 +2183,7 @@ Here is a list of all the methods available in the `RunHistory` class:
 
 When using the strategy pattern is no longer feasible, it is also possible to customize the training or testing procedure using subclassing, and overriding hook methods. To customize the training loop using subclassing, subclass the `basic.Trainer` class in `plato.trainers`, and override the following hook methods:
 
-!!! example "train_model()"
+!!! note "`train_model()`"
     **`def train_model(self, config, trainset, sampler, **kwargs):`**
 
     Override this method to provide a custom training loop.
@@ -2252,8 +2194,8 @@ When using the strategy pattern is no longer feasible, it is also possible to cu
 
     **Example:** A complete example can be found in the Hugging Face trainer, located at `plato/trainers/huggingface.py`.
 
-!!! example "test_model()"
-    **`test_model(self, config, testset, sampler=None, **kwargs):`**
+!!! note "`test_model()`"
+    **`def test_model(self, config, testset, sampler=None, **kwargs):`**
 
     Override this method to provide a custom testing loop.
 
@@ -2262,6 +2204,34 @@ When using the strategy pattern is no longer feasible, it is also possible to cu
 
     **Example:** A complete example can be found in `plato/trainers/huggingface.py`.
 
+!!! note "`save_model(filename=None, location=None)`"
+    Save model weights and training history.
+
+    **Parameters:**
+
+    - `filename`: Optional custom filename
+    - `location`: Optional custom directory
+
+    **Example:**
+
+    ```python
+    trainer.save_model("my_model.pth")
+    ```
+
+!!! note "`load_model(filename=None, location=None)`"
+    Load model weights and training history.
+
+    **Parameters:**
+
+    - `filename`: Optional custom filename
+    - `location`: Optional custom directory
+
+    **Example:**
+
+    ```python
+    trainer.load_model("my_model.pth")
+    ```
+
 ---
 
 ## Import Guide