# tff.learning.algorithms.build_weighted_fed_avg

<br />

|---|
| [![](https://www.tensorflow.org/images/GitHub-Mark-32px.png) View source on GitHub](https://github.com/tensorflow/federated/blob/v0.87.0 Version 2.0, January 2004 Licensed under the Apache License, Version 2.0 (the) |

Builds a learning process that performs federated averaging.

    tff.learning.algorithms.build_weighted_fed_avg(
        model_fn: Union[Callable[[], https://www.tensorflow.org/federated/api_docs/python/tff/learning/models/VariableModel], https://www.tensorflow.org/federated/api_docs/python/tff/learning/models/FunctionalModel],
        client_optimizer_fn: https://www.tensorflow.org/federated/api_docs/python/tff/learning/optimizers/Optimizer,
        server_optimizer_fn: Optional[https://www.tensorflow.org/federated/api_docs/python/tff/learning/optimizers/Optimizer] = None,
        *,
        client_weighting: Optional[https://www.tensorflow.org/federated/api_docs/python/tff/learning/ClientWeighting] = https://www.tensorflow.org/federated/api_docs/python/tff/learning/ClientWeighting#NUM_EXAMPLES,
        model_distributor: Optional[https://www.tensorflow.org/federated/api_docs/python/tff/learning/templates/DistributionProcess] = None,
        model_aggregator: Optional[https://www.tensorflow.org/federated/api_docs/python/tff/aggregators/WeightedAggregationFactory] = None,
        metrics_aggregator: Optional[https://www.tensorflow.org/federated/api_docs/python/tff/learning/metrics/MetricsAggregatorType] = None,
        loop_implementation: https://www.tensorflow.org/federated/api_docs/python/tff/learning/LoopImplementation = https://www.tensorflow.org/federated/api_docs/python/tff/learning/LoopImplementation#DATASET_REDUCE
    ) -> https://www.tensorflow.org/federated/api_docs/python/tff/learning/templates/LearningProcess

### Used in the notebooks

| Used in the tutorials |
|---|
| - [Federated Learning for Image Classification](https://www.tensorflow.org/federated/tutorials/federated_learning_for_image_classification) - [Federated Learning for Text Generation](https://www.tensorflow.org/federated/tutorials/federated_learning_for_text_generation) - [High-performance simulations with TFF](https://www.tensorflow.org/federated/tutorials/simulations) - [TFF simulations with accelerators](https://www.tensorflow.org/federated/tutorials/simulations_with_accelerators) - [Working with tff's ClientData.](https://www.tensorflow.org/federated/tutorials/working_with_client_data) |

This function creates a [`tff.learning.templates.LearningProcess`](https://www.tensorflow.org/federated/api_docs/python/tff/learning/templates/LearningProcess) that performs
federated averaging on client models. The iterative process has the following
methods inherited from [`tff.learning.templates.LearningProcess`](https://www.tensorflow.org/federated/api_docs/python/tff/learning/templates/LearningProcess):

- `initialize`: A [`tff.Computation`](https://www.tensorflow.org/federated/api_docs/python/tff/Computation) with the functional type signature `( -> S@SERVER)`, where `S` is a [`tff.learning.templates.LearningAlgorithmState`](https://www.tensorflow.org/federated/api_docs/python/tff/learning/templates/LearningAlgorithmState) representing the initial state of the server.
- `next`: A [`tff.Computation`](https://www.tensorflow.org/federated/api_docs/python/tff/Computation) with the functional type signature `(<S@SERVER, {B*}@CLIENTS> -> <L@SERVER>)` where `S` is a [`tff.learning.templates.LearningAlgorithmState`](https://www.tensorflow.org/federated/api_docs/python/tff/learning/templates/LearningAlgorithmState) whose type matches the output of `initialize` and `{B*}@CLIENTS` represents the client datasets. The output `L` contains the updated server state, as well as aggregated metrics at the server, including client training metrics and any other metrics from distribution and aggregation processes.
- `get_model_weights`: A [`tff.Computation`](https://www.tensorflow.org/federated/api_docs/python/tff/Computation) with type signature `(S -> M)`, where `S` is a [`tff.learning.templates.LearningAlgorithmState`](https://www.tensorflow.org/federated/api_docs/python/tff/learning/templates/LearningAlgorithmState) whose type matches the output of `initialize` and `next`, and `M` represents the type of the model weights used during training.
- `set_model_weights`: A [`tff.Computation`](https://www.tensorflow.org/federated/api_docs/python/tff/Computation) with type signature `(<S, M> -> S)`, where `S` is a [`tff.learning.templates.LearningAlgorithmState`](https://www.tensorflow.org/federated/api_docs/python/tff/learning/templates/LearningAlgorithmState) whose type matches the output of `initialize` and `M` represents the type of the model weights used during training.

Each time the `next` method is called, the server model is communicated to
each client using the provided `model_distributor`. For each client, local
training is performed using `client_optimizer_fn`. Each client computes the
difference between the client model after training and its initial model.
These model deltas are then aggregated at the server using a weighted
aggregation function, according to `client_weighting`. The aggregate model
delta is applied at the server using a server optimizer.

> [!NOTE]
> **Note:** the default server optimizer function is [`tff.learning.optimizers.build_sgdm`](https://www.tensorflow.org/federated/api_docs/python/tff/learning/optimizers/build_sgdm) with a learning rate of 1.0, which corresponds to adding the model delta to the current server model. This recovers the original FedAvg algorithm in [McMahan et al.,
> 2017](https://arxiv.org/abs/1602.05629). More sophisticated federated averaging procedures may use different learning rates or server optimizers (this generalized FedAvg algorithm is described in [Reddi et al.,
> 2021](https://arxiv.org/abs/2003.00295)).

<br />

<br />

<br />

| ## Args ||
|---|---|
| `model_fn` | A no-arg function that returns a [`tff.learning.models.VariableModel`](https://www.tensorflow.org/federated/api_docs/python/tff/learning/models/VariableModel), or an instance of a [`tff.learning.models.FunctionalModel`](https://www.tensorflow.org/federated/api_docs/python/tff/learning/models/FunctionalModel). When passing a callable, the callable must *not* capture TensorFlow tensors or variables and use them. The model must be constructed entirely from scratch on each invocation, returning the same pre-constructed model each call will result in an error. |
| `client_optimizer_fn` | A [`tff.learning.optimizers.Optimizer`](https://www.tensorflow.org/federated/api_docs/python/tff/learning/optimizers/Optimizer). |
| `server_optimizer_fn` | A [`tff.learning.optimizers.Optimizer`](https://www.tensorflow.org/federated/api_docs/python/tff/learning/optimizers/Optimizer). By default, this uses `tff.leanring.optimizers.build_sgdm` with a learning rate of 1.0. |
| `client_weighting` | A member of [`tff.learning.ClientWeighting`](https://www.tensorflow.org/federated/api_docs/python/tff/learning/ClientWeighting) that specifies a built-in weighting method. By default, weighting by number of examples is used. |
| `model_distributor` | An optional `DistributionProcess` that distributes the model weights on the server to the clients. If set to `None`, the distributor is constructed via [`tff.learning.templates.build_broadcast_process`](https://www.tensorflow.org/federated/api_docs/python/tff/learning/templates/build_broadcast_process). |
| `model_aggregator` | An optional [`tff.aggregators.WeightedAggregationFactory`](https://www.tensorflow.org/federated/api_docs/python/tff/aggregators/WeightedAggregationFactory) used to aggregate client updates on the server. If `None`, this is set to [`tff.aggregators.MeanFactory`](https://www.tensorflow.org/federated/api_docs/python/tff/aggregators/MeanFactory). |
| `metrics_aggregator` | A function that takes in the metric finalizers (i.e., [`tff.learning.models.VariableModel.metric_finalizers()`](https://www.tensorflow.org/federated/api_docs/python/tff/learning/models/VariableModel#metric_finalizers)) and a [`tff.types.StructWithPythonType`](https://www.tensorflow.org/federated/api_docs/python/tff/types/StructWithPythonType) of the unfinalized metrics (i.e., the TFF type of [`tff.learning.models.VariableModel.report_local_unfinalized_metrics()`](https://www.tensorflow.org/federated/api_docs/python/tff/learning/models/VariableModel#report_local_unfinalized_metrics)), and returns a [`tff.Computation`](https://www.tensorflow.org/federated/api_docs/python/tff/Computation) for aggregating the unfinalized metrics. If `None`, this is set to [`tff.learning.metrics.sum_then_finalize`](https://www.tensorflow.org/federated/api_docs/python/tff/learning/metrics/sum_then_finalize). |
| `loop_implementation` | Changes the implementation of the training loop generated. See [`tff.learning.LoopImplementation`](https://www.tensorflow.org/federated/api_docs/python/tff/learning/LoopImplementation) for more details. |

<br />

<br />

<br />

<br />

| ## Returns ||
|---|---|
| A [`tff.learning.templates.LearningProcess`](https://www.tensorflow.org/federated/api_docs/python/tff/learning/templates/LearningProcess). ||

<br />

<br />

<br />

<br />

| ## Raises ||
|---|---|
| `TypeError` | If arguments are not the documented types. |

<br />