fluke.client

The module fluke.client provides the base classes for the clients in fluke.

Classes included in fluke.client

Client	Base Client class.
PFLClient	Personalized Federated Learning client.

Classes

class fluke.client.Client

index	The client identifier.
n_examples	The number of examples in the local training set.
channel	The communication channel.
server	The server to which the client is connected.
set_server	Set the reference to the server.
fit	Client's local training procedure.
local_update	Client's local update procedure.
receive_model	Receive the global model from the server.
send_model	Send the current model to the server.
evaluate	Evaluate the local model on the client's test_set.
finalize	Finalize the client.

class fluke.client.Client(index: int, train_set: FastDataLoader, test_set: FastDataLoader, optimizer_cfg: OptimizerConfigurator, loss_fn: Module, local_epochs: int = 3, **kwargs: dict[str, Any])

Bases: ObserverSubject

Base Client class. This class is the base class for all clients in the fluke. The behavior of the client is based on the Federated Averaging algorithm. The default behavior of a client includes:

• Receiving the global model from the server;

• Training the model locally for a number of epochs using the local training set;

• Sending the updated local model back to the server;

• (Optional) Evaluating the model on the local test set.

hyper_params

The hyper-parameters of the client. The default hyper-parameters are:

• loss_fn: The loss function.

• local_epochs: The number of local epochs.

When a new client class inherits from this class, it must add all its hyper-parameters to this dictionary.

Type:

DDict

train_set

The local training set.

Type:

FastDataLoader

test_set

The local test set.

Type:

FastDataLoader

optimizer_cfg

The optimizer configurator. This is used to create the optimizer and the learning rate scheduler.

Type:

OptimizerConfigurator

optimizer

The optimizer.

Type:

torch.optim.Optimizer

scheduler

The learning rate scheduler.

Type:

torch.optim.lr_scheduler.LRScheduler

device

The device where the client trains the model. By default, it is the device defined in fluke.GlobalSettings.

Type:

torch.device

Attention

The client should not directly call methods of the server. The communication between the client and the server must be done through the channel.

Caution

When inheriting from this class, make sure to put all the specific hyper-parameters in the hyper_params attribute. In this way fluke can properly handle the hyper-parameters of the client in the federated learning process.

For example:

class MyClient(Client):
    # We omit the type hints for brevity
    def __init__(self, index, train_set, test_set, optimizer_cfg, loss_fn, my_param):
        super().__init__(index, train_set, test_set, optimizer_cfg, loss_fn)
        self.hyper_params.update(my_param=my_param) # This is important

property index: int

The client identifier. This might be useful to identify the client in the federated learning process for logging or debugging purposes.

Returns:

The client identifier.

Return type:

int

property n_examples: int

The number of examples in the local training set.

Returns:

The number of examples in the local training set.

Return type:

int

property channel: Channel

The communication channel.

Attention

Use this channel to exchange data/information with the server.

Returns:

The communication channel.

Return type:

Channel

property server: Server

The server to which the client is connected. This reference must only be used to send messages through the channel.

Returns:

The server.

Return type:

Server

set_server(server: Server) → None

Set the reference to the server. Along with the server, the communication channel is also set and the client must use this channel to communicate with the server.

Parameters:

server (Server) – The server that orchestrates the federated learning process.

receive_model() → None

Receive the global model from the server. This method is responsible for receiving the global model from the server and updating the local model accordingly. The model is received as a payload of a fluke.comm.Message with msg_type="model" from the inbox of the client itself. The method uses the channel to receive the message.

send_model() → None

Send the current model to the server. The model is sent as a Message with msg_type “model” to the server. The method uses the channel to send the message.

local_update(current_round: int) → None

Client’s local update procedure. Before starting the local training, the client receives the global model from the server. Then, the training occurs for a number of hyper_params.local_epochs epochs using the local training set and as loss function the one defined in hyper_params.loss_fn. The training happens on the device defined in the client. After the training, the client sends the model to the server.

Parameters:

current_round (int) – The current round of the federated learning process.

fit(override_local_epochs: int = 0) → float

Client’s local training procedure.

Parameters:

override_local_epochs (int, optional) – Overrides the number of local epochs, by default 0 (use the default number of local epochs).

Returns:

The average loss of the model during the training.

Return type:

float

evaluate(evaluator: Evaluator, test_set: FastDataLoader) → dict[str, float]

Evaluate the local model on the client’s test_set. If the test set is not set or the client has not received the global model from the server, the method returns an empty dictionary.

Parameters:

• evaluator (Evaluator) – The evaluator to use for the evaluation.

• test_set (FastDataLoader) – The test set to use for the evaluation.

Returns:

The evaluation results. The keys are the metrics and the values are the results.

Return type:

dict[str, float]

finalize() → None

Finalize the client. This method is called at the end of the federated learning process. The default behavior is to receive the global model from the server that is then potentially used to evaluate the performance of the model on the local test set.

Attention

When inheriting from this class, make sure to override this method if this behavior is not desired.

class fluke.client.PFLClient

evaluate

Evaluate the personalized model on the test_set.

class fluke.client.PFLClient(index: int, model: Module, train_set: FastDataLoader, test_set: FastDataLoader, optimizer_cfg: OptimizerConfigurator, loss_fn: Module, local_epochs: int = 3, **kwargs: dict[str, Any])

Bases: Client

Personalized Federated Learning client. This class is a personalized version of the Client class. It is used to implement personalized federated learning algorithms. The main difference is that the client has a personalized model (i.e., the attribute personalized_model).

Note

The client evaluation is performed using personalized_model instead of the global model (i.e., model).

personalized_model

The personalized model.

Type:

torch.nn.Module

evaluate(evaluator: Evaluator, test_set: FastDataLoader) → dict[str, float]

Evaluate the personalized model on the test_set. If the test set is not set or the client has no personalized model, the method returns an empty dictionary.

Parameters:

• evaluator (Evaluator) – The evaluator to use for the evaluation.

• test_set (FastDataLoader) – The test set to use for the evaluation.

Returns:

The evaluation results. The keys are the metrics and the values are the results.

Return type:

dict[str, float]