tff.templates.AggregationProcess

A stateful process that aggregates values.

Inherits From: MeasuredProcess, IterativeProcess

tff.templates.AggregationProcess(
    initialize_fn: tff.Computation,
    next_fn: tff.Computation
)

Used in the notebooks

Used in the tutorials

This class inherits the constraints documented by tff.templates.MeasuredProcess.

A tff.templates.AggregationProcess is a tff.templates.MeasuredProcess that formalizes the type signature of initialize_fn and next_fn for aggregation.

Compared to the tff.templates.MeasuredProcess, this class requires a second input argument, which is a value placed at CLIENTS and to be aggregated. The result field of returned tff.templates.MeasuredProcessOutput, representing the aggregate, must be placed at SERVER and does not necessarily need to have type signature equal to the type signature of the second input argument.

The intended composition pattern for tff.templates.AggregationProcess is that of nesting. An aggregation will broadly consist of three logical parts:

  • A pre-aggregation computation placed at CLIENTS.
  • Actual aggregation.
  • A post-aggregation computation placed at SERVER. The second step can be realized by direct application of appropriate intrinsic such as tff.federated_sum, or by delegation to (one or more) "inner" aggregation processes.

Both initialize and next must be tff.Computations with the following type signatures:

  • initialize: ( -> S@SERVER)
  • next: (<S@SERVER, V@CLIENTS, *> -> <state=S@SERVER, result=V'@SERVER, measurements=M@SERVER>) where * represents optional other arguments placed at CLIENTS. This can be used for weighted aggregation, where the third parameter is the weight.

Note that while the value type to be aggregated will often be preserved (i.e., V == V'), it is not required. An example is sampling-based aggregation.

initialize_fn A no-arg tff.Computation that returns the initial state of the aggregation process. The returned state must be a server-placed federated value. Let the type of this state be called S@SERVER.
next_fn A tff.Computation that represents the iterated function. next_fn must accept at least two arguments, the first of which is of a type assignable from the state type S@SERVER and the second of which is client-placed data of type V@CLIENTS. next_fn must return a MeasuredProcessOutput where the state attribute is assignable to the first argument and the result is value placed at SERVER.

TypeError If initialize_fn and next_fn are not instances of tff.Computation.
TemplateInitFnParamNotEmptyError If initialize_fn has any input arguments.
TemplateStateNotAssignableError If the state returned by either initialize_fn or next_fn is not assignable to the first input argument of next_fn.
TemplateNotMeasuredProcessOutputError If next_fn does not return a MeasuredProcessOutput.
TemplateNextFnNumArgsError If next_fn does not have at least two input arguments.
AggregationNotFederatedError If initialize_fn and next_fn are not computations operating on federated types.
AggregationPlacementError If the placements of initialize_fn and next_fn are not matching the expected type signature.

initialize A no-arg tff.Computation that returns the initial state.
is_weighted True if next takes a third argument for weights.
next A tff.Computation that runs one iteration of the process.

Its first argument should always be the current state (originally produced by the initialize attribute), the second argument must be the input placed at CLIENTS, and the return type must be a tff.templates.MeasuredProcessOutput with each field placed at SERVER.

state_type The tff.Type of the state of the process.