# tff.aggregators.SecureSumFactory

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

`AggregationProcess` factory for securely summing values.

Inherits From: [`UnweightedAggregationFactory`](https://www.tensorflow.org/federated/api_docs/python/tff/aggregators/UnweightedAggregationFactory)

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

### Used in the notebooks

| Used in the tutorials |
|---|
| - [Tuning recommended aggregations for learning](https://www.tensorflow.org/federated/tutorials/tuning_recommended_aggregators) |

The created [`tff.templates.AggregationProcess`](https://www.tensorflow.org/federated/api_docs/python/tff/templates/AggregationProcess) uses the
[`tff.federated_secure_sum_bitwidth`](https://www.tensorflow.org/federated/api_docs/python/tff/federated_secure_sum_bitwidth) operator for movement of all values 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).

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`](https://www.tensorflow.org/federated/api_docs/python/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`](https://www.tensorflow.org/federated/api_docs/python/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`](https://www.tensorflow.org/federated/api_docs/python/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.TensorType`](https://www.tensorflow.org/federated/api_docs/python/tff/types/TensorType)s must have the same dtype (i.e. mixing
[`tf.float32`](https://www.tensorflow.org/api_docs/python/tf#float32) and [`tf.float64`](https://www.tensorflow.org/api_docs/python/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.

<br />

<br />

<br />

| ## Args ||
|---|---|
| `upper_bound_threshold` | Either a `int` or `float` Python constant, a Numpy scalar, or a [`tff.templates.EstimationProcess`](https://www.tensorflow.org/federated/api_docs/python/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`](https://www.tensorflow.org/federated/api_docs/python/tff/templates/EstimationProcess), used for determining the lower bound before summation. If specified, must be the same type as `upper_bound_threshold`. |

<br />

<br />

<br />

<br />

| ## Raises ||
|---|---|
| `TypeError` | If `upper_bound_threshold` and `lower_bound_threshold` are not instances of one of (`int`, `float` or [`tff.templates.EstimationProcess`](https://www.tensorflow.org/federated/api_docs/python/tff/templates/EstimationProcess)). |
| `ValueError` | If `upper_bound_threshold` is provided as a negative constant. |

<br />

## Methods

### `create`

[View source](https://github.com/tensorflow/federated/blob/v0.87.0
Version 2.0, January 2004
Licensed under the Apache License, Version 2.0 (the)

    create(
        value_type: factory.ValueType
    ) -> https://www.tensorflow.org/federated/api_docs/python/tff/templates/AggregationProcess

Creates a `tff.aggregators.AggregationProcess` without weights.

The provided `value_type` is a non-federated [`tff.Type`](https://www.tensorflow.org/federated/api_docs/python/tff/types/Type), that is, not a
[`tff.FederatedType`](https://www.tensorflow.org/federated/api_docs/python/tff/types/FederatedType).

The returned `tff.aggregators.AggregationProcess` will be created for
aggregation of values matching `value_type` placed at [`tff.CLIENTS`](https://www.tensorflow.org/federated/api_docs/python/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.

<br />

<br />

<br />

| Args ||
|---|---|
| `value_type` | A non-federated [`tff.Type`](https://www.tensorflow.org/federated/api_docs/python/tff/types/Type). |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| A [`tff.templates.AggregationProcess`](https://www.tensorflow.org/federated/api_docs/python/tff/templates/AggregationProcess). ||

<br />