tff.aggregators.ZeroingClippingFactory

AggregationProcessFactory for zeroing and clipping large values.

Inherits From: AggregationProcessFactory

The created tff.templates.AggregationProcess zeroes out any values whose norm is greater than than a given value, and further projects the values onto an L2 ball (also referred to as "clipping") before aggregating the values as specified by inner_agg_factory. The clipping norm is determined by the clipping_norm, and the zeroing norm is computed as a function (zeroing_norm_fn) applied to the clipping norm.

This is intended to be used when it is preferred (for privacy reasons perhaps) to use only a single estimation process. If it is acceptable to use multiple estimation processes it would be more flexible to compose a ZeroingFactory with a ClippingFactory. For example, a ZeroingFactory allows zeroing values with high L-inf norm, whereas this class supports only L2 norm.

The provided clipping_norm can either be a constant (for fixed norm), or an instance of tff.templates.EstimationProcess (for adaptive norm). If it is an estimation process, the value returned by its report method will be used as the clipping norm. Its next method needs to accept a scalar float32 at clients, corresponding to the norm of value being aggregated. The process can thus adaptively determine the clipping norm based on the set of aggregated values. For example if a tff.aggregators.PrivateQuantileEstimationProcess is used, the clipping norm will be an estimate of a quantile of the norms of the values being aggregated.

clipping_norm Either a float (for fixed norm) or an EstimationProcess (for adaptive norm) that specifies the norm over which values should be clipped. If an EstimationProcess is passed, value norms will be passed to the process and its report function will be used as the clipping norm.
zeroing_norm_fn A tff.Computation to apply to the clipping norm to produce the zeroing norm.
inner_agg_factory A factory specifying the type of aggregation to be done after zeroing and clipping.

Methods

create

View source

Creates a tff.aggregators.AggregationProcess aggregating value_type.

The provided value_type is a non-federated tff.Type object, that is, value_type.is_federated() should return False. Provided value_type must be a tff.TensorType or a tff.StructType.

The returned tff.aggregators.AggregationProcess will be created for aggregation of values matching value_type. That is, its next method will expect type <S@SERVER, {value_type}@CLIENTS, *>, where S is the unplaced return type of its initialize method, and * stands for optional additional placed input arguments.

Args
value_type A tff.Type without placement.

Returns
A tff.templates.AggregationProcess.