# tff.federated_aggregate

<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) |

Aggregates `value` from [`tff.CLIENTS`](https://www.tensorflow.org/federated/api_docs/python/tff#CLIENTS) to [`tff.SERVER`](https://www.tensorflow.org/federated/api_docs/python/tff#SERVER).

    tff.federated_aggregate(
        value, zero, accumulate, merge, report
    ) -> https://www.tensorflow.org/federated/api_docs/python/tff/Value

This generalized aggregation function admits multi-layered architectures that
involve one or more intermediate stages to handle scalable aggregation across
a very large number of participants.

The multi-stage aggregation process is defined as follows:

- Clients are organized into groups. Within each group, a set of all the
  member constituents of `value` contributed by clients in the group are first
  reduced using reduction operator `accumulate` with `zero` as the zero in the
  algebra. If members of `value` are of type `T`, and `zero` (the result of
  reducing an empty set) is of type `U`, the reduction operator `accumulate`
  used at this stage should be of type `(<U,T> -> U)`. The result of this
  stage is a set of items of type `U`, one item for each group of clients.

- Next, the `U`-typed items generated by the preceding stage are merged using
  the binary commutative associative operator `merge` of type `(<U,U> -> U)`.
  The result of this stage is a single top-level `U` that emerges at the root
  of the hierarchy at the [`tff.SERVER`](https://www.tensorflow.org/federated/api_docs/python/tff#SERVER). Actual implementations may structure
  this step as a cascade of multiple layers.

- Finally, the `U`-typed result of the reduction performed in the preceding
  stage is projected into the result value using `report` as the mapping
  function (for example, if the structures being merged consist of counters,
  this final step might include computing their ratios).

<br />

<br />

<br />

| ## Args ||
|---|---|
| `value` | A value of a TFF federated type placed at [`tff.CLIENTS`](https://www.tensorflow.org/federated/api_docs/python/tff#CLIENTS) to aggregate. |
| `zero` | The zero of type `U` in the algebra of reduction operators, as described above. |
| `accumulate` | The reduction operator to use in the first stage of the process. If `value` is of type `{T}@CLIENTS`, and `zero` is of type `U`, this operator should be of type `(<U,T> -> U)`. |
| `merge` | The reduction operator to employ in the second stage of the process. Must be of type `(<U,U> -> U)`, where `U` is as defined above. |
| `report` | The projection operator to use at the final stage of the process to compute the final result of aggregation. If the intended result to be returned by [`tff.federated_aggregate`](https://www.tensorflow.org/federated/api_docs/python/tff/federated_aggregate) is of type `R@SERVER`, this operator must be of type `(U -> R)`. |

<br />

<br />

<br />

<br />

| ## Returns ||
|---|---|
| A representation on the [`tff.SERVER`](https://www.tensorflow.org/federated/api_docs/python/tff#SERVER) of the result of aggregating `value` using the multi-stage process described above. ||

<br />

<br />

<br />

<br />

| ## Raises ||
|---|---|
| `TypeError` | If the arguments are not of the types specified above. |

<br />