fl4health.strategies.basic_fedavg module

class BasicFedAvg(*, fraction_fit=1.0, fraction_evaluate=1.0, min_fit_clients=2, min_evaluate_clients=2, min_available_clients=2, evaluate_fn=None, on_fit_config_fn=None, on_evaluate_config_fn=None, accept_failures=True, initial_parameters=None, fit_metrics_aggregation_fn=None, evaluate_metrics_aggregation_fn=None, weighted_aggregation=True, weighted_eval_losses=True)[source]

Bases: FedAvg, StrategyWithPolling

Configurable FedAvg strategy implementation.

__init__(*, fraction_fit=1.0, fraction_evaluate=1.0, min_fit_clients=2, min_evaluate_clients=2, min_available_clients=2, evaluate_fn=None, on_fit_config_fn=None, on_evaluate_config_fn=None, accept_failures=True, initial_parameters=None, fit_metrics_aggregation_fn=None, evaluate_metrics_aggregation_fn=None, weighted_aggregation=True, weighted_eval_losses=True)[source]

Federated Averaging with Flexible Sampling. This implementation extends that of Flower in two ways. The first is that it provides an option for unweighted averaging, where Flower only offers weighted averaging based on client sample counts. The second is that it allows users to Flower’s standard sampling or use a custom sampling approach implemented in by a custom client manager.

FedAvg Paper: https://arxiv.org/abs/1602.05629.

Parameters:

  • fraction_fit (float, optional) – Fraction of clients used during training. In case min_fit_clients is larger than fraction_fit * available_clients, min_fit_clients will still be sampled. Defaults to 1.0.

  • fraction_evaluate (float, optional) – Fraction of clients used during validation. In case min_evaluate_clients is larger than fraction_evaluate * available_clients, min_evaluate_clients will still be sampled. Defaults to 1.0.

  • min_fit_clients (int, optional) – _description_. Defaults to 2.

  • min_evaluate_clients (int, optional) – Minimum number of clients used during validation. Defaults to 2.

  • min_available_clients (int, optional) – Minimum number of total clients in the system. Defaults to 2.

  • evaluate_fn (Callable[[int, NDArrays, dict[str, Scalar]], tuple[float, dict[str, Scalar]] | None] | None) – Optional function used for central server-side evaluation. Defaults to None.

  • on_fit_config_fn (Callable[[int], dict[str, Scalar]] | None, optional) – Function used to configure training by providing a configuration dictionary. Defaults to None.

  • on_evaluate_config_fn (Callable[[int], dict[str, Scalar]] | None, optional) – Function used to configure client-side validation by providing a Config dictionary. Defaults to None.

  • accept_failures (bool, optional) – Whether or not accept rounds containing failures. Defaults to True.

  • initial_parameters (Parameters | None, optional) – Initial global model parameters. Defaults to None.

  • fit_metrics_aggregation_fn (MetricsAggregationFn | None, optional) – Metrics aggregation function. Defaults to None.

  • evaluate_metrics_aggregation_fn (MetricsAggregationFn | None, optional) – Metrics aggregation function. Defaults to None.

  • weighted_aggregation (bool, optional) – Determines whether parameter aggregation is a linearly weighted average or a uniform average. FedAvg default is weighted average by client dataset counts. Defaults to True.

  • weighted_eval_losses (bool, optional) – Determines whether losses during evaluation are linearly weighted averages or a uniform average. FedAvg default is weighted average of the losses by client dataset counts. Defaults to True.

aggregate_evaluate(server_round, results, failures)[source]

Aggregate the metrics and losses returned from the clients as a result of the evaluation round.

Parameters:

  • results (list[tuple[ClientProxy, EvaluateRes]]) – The client identifiers and the results of their local evaluation that need to be aggregated on the server-side. These results are loss values and the metrics dictionary.

  • failures (list[tuple[ClientProxy, EvaluateRes] | BaseException]) – These are the results and exceptions from clients that experienced an issue during evaluation, such as timeouts or exceptions.

Returns:

Aggregated loss values and the aggregated metrics. The metrics

are aggregated according to evaluate_metrics_aggregation_fn.

Return type:

tuple[float | None, dict[str, Scalar]]

aggregate_fit(server_round, results, failures)[source]

Aggregate the results from the federated fit round. This is done with either weighted or unweighted FedAvg, depending on the settings used for the strategy.

Parameters:

  • server_round (int) – Indicates the server round we’re currently on.

  • results (list[tuple[ClientProxy, FitRes]]) – The client identifiers and the results of their local training that need to be aggregated on the server-side.

  • failures (list[tuple[ClientProxy, FitRes] | BaseException]) – These are the results and exceptions from clients that experienced an issue during training, such as timeouts or exceptions.

Returns:

The aggregated model weights and the metrics dictionary.

Return type:

tuple[Parameters | None, dict[str, Scalar]]

configure_evaluate(server_round, parameters, client_manager)[source]

This function configures a sample of clients for a evaluation round. It handles the case where the client manager has a sample fraction vs. a sample function (to allow for more flexible sampling). The function follows the standard configuration flow where the on_evaluate_config_fn function is used to produce configurations to be sent to all clients. These are packaged with the provided parameters and set over to the clients.

Parameters:

  • server_round (int) – Indicates the server round we’re currently on.

  • parameters (Parameters) – The parameters to be used to initialize the clients for the eval round.

  • client_manager (ClientManager) – The manager used to sample from the available clients.

Returns:

List of sampled client identifiers and the configuration/parameters

to be sent to each client (packaged as EvaluateIns).

Return type:

list[tuple[ClientProxy, EvaluateIns]]

configure_fit(server_round, parameters, client_manager)[source]

This function configures a sample of clients for a training round. It handles the case where the client manager has a sample fraction vs. a sample function (to allow for more flexible sampling). The function follows the standard configuration flow where the on_fit_config_fn function is used to produce configurations to be sent to all clients. These are packaged with the provided parameters and set over to the clients.

Parameters:

  • server_round (int) – Indicates the server round we’re currently on.

  • parameters (Parameters) – The parameters to be used to initialize the clients for the fit round.

  • client_manager (ClientManager) – The manager used to sample from the available clients.

Returns:

List of sampled client identifiers and the configuration/parameters to

be sent to each client (packaged as FitIns).

Return type:

list[tuple[ClientProxy, FitIns]]

configure_poll(server_round, client_manager)[source]

This function configures everything required to request properties from ALL of the clients. The client manger, regardless of type, is instructed to grab all available clients to perform the polling process.

Parameters:

  • server_round (int) – Indicates the server round we’re currently on.

  • client_manager (ClientManager) – The manager used to sample all available clients.

Returns:

List of sampled client identifiers and the configuration

to be sent to each client (packaged as GetPropertiesIns).

Return type:

list[tuple[ClientProxy, GetPropertiesIns]]

class OpacusBasicFedAvg(*, model, fraction_fit=1.0, fraction_evaluate=1.0, min_fit_clients=2, min_evaluate_clients=2, min_available_clients=2, evaluate_fn=None, on_fit_config_fn=None, on_evaluate_config_fn=None, accept_failures=True, fit_metrics_aggregation_fn=None, evaluate_metrics_aggregation_fn=None, weighted_aggregation=True, weighted_eval_losses=True)[source]

Bases: BasicFedAvg

Configurable FedAvg strategy implementation.

__init__(*, model, fraction_fit=1.0, fraction_evaluate=1.0, min_fit_clients=2, min_evaluate_clients=2, min_available_clients=2, evaluate_fn=None, on_fit_config_fn=None, on_evaluate_config_fn=None, accept_failures=True, fit_metrics_aggregation_fn=None, evaluate_metrics_aggregation_fn=None, weighted_aggregation=True, weighted_eval_losses=True)[source]

This strategy is a simple extension of the BasicFedAvg strategy to force the model being federally trained to be an valid Opacus GradSampleModule and, thereby, ensure that associated the parameters are aligned with those of Opacus based models used by the InstanceLevelDpClient.

Parameters:

  • model (GradSampleModule) – The model architecture to be federally trained. When using this strategy, the model must be of type Opacus GradSampleModule. This model will then be used to set initialize_parameters as the initial parameters to be used by all clients.

  • fraction_fit (float, optional) – Fraction of clients used during training. In case min_fit_clients is larger than fraction_fit * available_clients, min_fit_clients will still be sampled. Defaults to 1.0.

  • fraction_evaluate (float, optional) – Fraction of clients used during validation. In case min_evaluate_clients is larger than fraction_evaluate * available_clients, min_evaluate_clients will still be sampled. Defaults to 1.0.

  • min_fit_clients (int, optional) – _description_. Defaults to 2.

  • min_evaluate_clients (int, optional) – Minimum number of clients used during validation. Defaults to 2.

  • min_available_clients (int, optional) – Minimum number of total clients in the system. Defaults to 2.

  • evaluate_fn (Callable[[int, NDArrays, dict[str, Scalar]], tuple[float, dict[str, Scalar]] | None] | None) – Optional function used for central server-side evaluation. Defaults to None.

  • on_fit_config_fn (Callable[[int], dict[str, Scalar]] | None, optional) – Function used to configure training by providing a configuration dictionary. Defaults to None.

  • on_evaluate_config_fn (Callable[[int], dict[str, Scalar]] | None, optional) – Function used to configure client-side validation by providing a Config dictionary. Defaults to None.

  • accept_failures (bool, optional) – Whether or not accept rounds containing failures. Defaults to True.

  • fit_metrics_aggregation_fn (MetricsAggregationFn | None, optional) – Metrics aggregation function. Defaults to None.

  • evaluate_metrics_aggregation_fn (MetricsAggregationFn | None, optional) – Metrics aggregation function. Defaults to None.

  • weighted_aggregation (bool, optional) – Determines whether parameter aggregation is a linearly weighted average or a uniform average. FedAvg default is weighted average by client dataset counts. Defaults to True.

  • weighted_eval_losses (bool, optional) – Determines whether losses during evaluation are linearly weighted averages or a uniform average. FedAvg default is weighted average of the losses by client dataset counts. Defaults to True.