EasyFL_with_PgFed/docs/en/tutorials/high-level_apis.md

Tutorial 1: High-level APIs

EasyFL provides three types of high-level APIs: initialization, registration, and execution. The initialization API initializes EasyFL with configurations. Registration APIs register customized components into the platform. Execution APIs start federated learning process. These APIs are listed in the table below.

API Name	Description	Category
init(config)	Initialize EasyFL with configurations	Initialization
register_dataset(train, test, val)	Register a customized dataset	Registration
register_model(model)	Register a customized model	Registration
register_server(server)	Register a customized server	Registration
register_client(client)	Register a customized client	Registration
run()	Start federated learning for standalone and distributed training	Execution
start_server()	Start server service for remote training	Execution
start_client()	Start client service for remote training	Execution

init(config): Initialize EasyFL with provided configurations (config) or default configurations if not specified.
These configurations determine the training hardware and hyperparameters.

register_<module>: Register customized modules to the system. EasyFL supports the registration of customized datasets, models, server, and client, replacing the default modules in FL training. In the experimental phase, users can register newly developed algorithms to understand their performance.

run, start_<server/client>: The APIs are commands to trigger execution. run() starts FL using standalone training or distributed training. start_server and start_client start the server and client services to communicate remotely with args variables for configurations specific to remote training, such as the endpoint addresses.

Next, we introduce how to use these APIs with examples.

Standalone Training Example

Standalone training means that federated learning (FL) training is run on a single hardware device, such as your personal computer and a single GPU. Distributed training means conducting FL with multiple GPUs to speed up training. Running distributed training is similar to standalone training, except that we need to configure the number of GPUs and the distributed settings. We explain more on distributed training in another note and focus on standalone training example here.

To run any federated learning process, we need to first call the initialization API and then use the execution API. Registration is optional.

The simplest way is to run with the default setup.

import easyfl
# Initialize federated learning with default configurations.
easyfl.init()
# Execute federated learning training.
easyfl.run()

You can run it with specified configurations.

import easyfl

# Customized configuration.
config = {
    "data": {"dataset": "cifar10", "num_of_clients": 1000},
    "server": {"rounds": 5, "clients_per_round": 2, "test_all": False},
    "client": {"local_epoch": 5},
    "model": "resnet18",
    "test_mode": "test_in_server",
}
# Initialize federated learning with default configurations.
easyfl.init(config)
# Execute federated learning training.
easyfl.run()

You can also run federated learning with customized datasets, model, server and client implementations.

Note: registration must be done before initialization.

import easyfl
from easyfl.client import BaseClient

# Inherit BaseClient to implement customized client operations.
class CustomizedClient(BaseClient):
    def __init__(self, cid, conf, train_data, test_data, device, **kwargs):
        super(CustomizedClient, self).__init__(cid, conf, train_data, test_data, device, **kwargs)
        pass  # more initialization of attributes.

    def train(self, conf, device):
        pass # Implement customized training method, overwriting the default one.

# Register customized client.
easyfl.register_client(CustomizedClient)
# Initialize federated learning with default configurations.
easyfl.init()
# Execute federated learning training.
easyfl.run()

Remote Training Example

Remote training is the scenario where the server and the clients are running on different devices. We explain more on remote training in another note. Here we provide examples on how to start client and server services using the APIs.

Start remote server.

import easyfl
# Configurations for the remote server.
conf = {"is_remote": True, "local_port": 22999}
# Initialize only the configuration.
easyfl.init(conf, init_all=False)
# Start remote server service.
# The remote server waits to be connected with the remote client.
easyfl.start_server()

Start remote client.

import easyfl
# Configurations for the remote client.
conf = {"is_remote": True, "local_port": 23000}
# Initialize only the configuration.
easyfl.init(conf, init_all=False)
# Start remote client service.
# The remote client waits to be connected with the remote server.
easyfl.start_client()

We expose two additional APIs that wrap starting remote services with customized components. They are start_remote_server and start_remote_client. You can explore more in the API documentation.