tff.aggregators.SecureSumFactory

AggregationProcess factory for securely summing values.

Inherits From: UnweightedAggregationFactory

tff.aggregators.SecureSumFactory(
    upper_bound_threshold: ThresholdEstType,
    lower_bound_threshold: Optional[ThresholdEstType] = None
)

Used in the notebooks

Used in the tutorials

The created tff.templates.AggregationProcess uses the tff.federated_secure_sum_bitwidth operator for movement of all values from tff.CLIENTS to tff.SERVER.

In order for values to be securely summed, their range needs to be known in advance and communicated to clients, so that clients can prepare the values in a form compatible with the tff.federated_secure_sum_bitwidth operator (that is, integers in range [0, 2**b-1] for some b), and for inverse mapping to be applied on the server. This will be done as specified by the upper_bound_threshold and lower_bound_threshold constructor arguments, with the following options:

For integer values to be summed, these arguments must be int Python constants or integer Numpy scalars, and the values during execution will be clipped to these thresholds and then securely summed.

For floating point values to be summed, the values during execution will be clipped to these thresholds, then uniformly quantized to integers in the range [0, 2**32-1], and then securely summed.

The upper_bound_threshold and lower_bound_threshold arguments can in this case be either float Python constants, float Numpy scalars, or instances of tff.templates.EstimationProcess, which adapts the thresholds between rounds of execution.

In all cases, it is possible to specify only upper_bound_threshold, in which case this threshold will be treated as a bound on the absolute value of the value to be summed.

For the case when floating point values are to be securely summed and more aggressive quantization is needed (i.e. less than 32 bits), the recommended pattern is to use tff.aggregators.EncodedSumFactory with this factory class as its inner aggregation factory.

If the value_type passed to the create method is a structure, all its constituent tff.TensorTypes must have the same dtype (i.e. mixing tf.float32 and tf.float64 is not allowed).

The created process will report measurements

  • secure_upper_threshold: The upper constant used for clipping.
  • secure_lower_threshold: The lower constant used for clipping.
  • secure_upper_clipped_count: The number of aggregands clipped to the secure_upper_threshold before aggregation.
  • secure_lower_clipped_count: The number of aggregands clipped to the secure_lower_threshold before aggregation.

upper_bound_threshold Either a int or float Python constant, a Numpy scalar, or a tff.templates.EstimationProcess, used for determining the upper bound before summation.
lower_bound_threshold Optional. Either a int or float Python constant, a Numpy scalar, or a tff.templates.EstimationProcess, used for determining the lower bound before summation. If specified, must be the same type as upper_bound_threshold.

TypeError If upper_bound_threshold and lower_bound_threshold are not instances of one of (int, float or tff.templates.EstimationProcess).
ValueError If upper_bound_threshold is provided as a negative constant.

Methods

create

View source

create(
    value_type: factory.ValueType
) -> tff.templates.AggregationProcess

Creates a tff.aggregators.AggregationProcess without weights.

The provided value_type is a non-federated tff.Type, that is, not a tff.FederatedType.

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

Args
value_type A non-federated tff.Type.

Returns
A tff.templates.AggregationProcess.