# tff.learning.algorithms.build_weighted_fed_prox

<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 the FedProx algorithm.

    tff.learning.algorithms.build_weighted_fed_prox(
        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],
        proximal_strength: float,
        client_optimizer_fn: https://www.tensorflow.org/federated/api_docs/python/tff/learning/optimizers/Optimizer,
        server_optimizer_fn: https://www.tensorflow.org/federated/api_docs/python/tff/learning/optimizers/Optimizer = DEFAULT_SERVER_OPTIMIZER_FN,
        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

This function creates a [`tff.learning.templates.LearningProcess`](https://www.tensorflow.org/federated/api_docs/python/tff/learning/templates/LearningProcess) that performs
example-weighted FedProx on client models. This algorithm behaves the same as
federated averaging, except that it uses a proximal regularization term that
encourages clients to not drift too far from the server model.

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 the 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, as in the FedOpt
framework proposed in [Reddi et al., 2021](https://arxiv.org/abs/2003.00295).

> [!NOTE]
> **Note:** The default server optimizer function is SGD with a learning rate of 1.0, which corresponds to adding the model delta to the current server model. This recovers the original FedProx algorithm in [Li et al., 2020](https://arxiv.org/abs/1812.06127). More sophisticated federated averaging procedures may use different learning rates or server optimizers.

<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. |
| `proximal_strength` | A nonnegative float representing the parameter of FedProx's regularization term. When set to `0.0`, the algorithm reduces to FedAvg. Higher values prevent clients from moving too far from the server model during local training. |
| `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 SGD 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 broadcasts the model weights on the server to the clients. If set to `None`, the distributor is constructed via `distributors.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 ||
|---|---|
| `ValueError` | If `proximal_parameter` is not a nonnegative float. |

<br />