# tff.aggregators.SecureModularSumFactory

<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 under a modulus.

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

    tff.aggregators.SecureModularSumFactory(
        modulus: Union[int, np.ndarray], symmetric_range: bool = False
    )

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

The aggregator requires integer types, and values in range `[0, modulus-1]`
(if `symmetric_range` is `False`) or in range `[-(modulus-1), +(modulus-1)]`
(if `symmetric_range` is `True`). In the latter case, additional computation
is needed for correct reduction to the
[`tff.backends.mapreduce.federated_secure_modular_sum`](https://www.tensorflow.org/federated/api_docs/python/tff/backends/mapreduce/federated_secure_modular_sum) with `2*modulus-1` as
the modulus for actual secure summation.

The aggregator always returns a value in those ranges, implemented as a
modular summation, regardless of input values. That is, if an input value at
runtime is outside of the specified range an error will not be raised, rather
the value will "wrap around", according to modular arithmetic.

For example, if `symmetric_range` is `False`, given client values `[1, 3, 6]`
and modulus `4`, the sum will be
`((1 % 4) + (3 % 4) + (6 % 4)) % 4 = (1 + 3 + 2) % 4 = 6 % 4 = 2`.

If `symmetric_range` is `True`, given client values `[1, 3, 6]` and modulus
`4`, the sum will be
`((1 %s 4) + (3 %s 4) + (6 %s 4)) %s 4 = (1 + 3 + (-3)) %s 4 = 1`.
The `* %s x` operator symbolizes modular "wrap around" to range `[-x, x]`.

The implementation of the case of `symmetric_range` is `True` is by delegation
to [`tff.backends.mapreduce.federated_secure_modular_sum`](https://www.tensorflow.org/federated/api_docs/python/tff/backends/mapreduce/federated_secure_modular_sum) with modulus
`2*modulus-1` is, which is equivalent to modular clip to range `[-(modulus-1),
+(modulus-1)]`, and then representing `x` in that range as `(x + 2*modulus-1)
% 2*modulus-1`, which is congruent with `x` under the desired modulus, thus
compatible with secure aggregation. This is reverted after summation by
modular clip to the initial range `[-(modulus-1), +(modulus-1)]`.

> [!NOTE]
> **Note:** Unlike [`tff.backends.mapreduce.federated_secure_modular_sum`](https://www.tensorflow.org/federated/api_docs/python/tff/backends/mapreduce/federated_secure_modular_sum), the `modulus` cannot be a structure of integers. If different moduli are needed for different tensors, recommended way of to achieve it is using the compositon of aggregators.

<br />

<br />

<br />

| ## Args ||
|---|---|
| `modulus` | An integer modulus for the summation. |
| `symmetric_range` | A bool indicating whether the summation is on symmetric range around `0` or not. |

<br />

<br />

<br />

<br />

| ## Raises ||
|---|---|
| `TypeError` | If `modulus` is not an `int` or Numpy scalar, or `symmetric_range` is not a `bool`. |
| `ValueError` | If `modulus` is not positive. |

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

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