# tff.learning.metrics.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) |

Aggregation Factory that performs secure summation over metrics.

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

    tff.learning.metrics.SecureSumFactory(
        metric_value_ranges: Optional[UserMetricValueRangeDict] = None
    )

The created [`tff.templates.AggregationProcess`](https://www.tensorflow.org/federated/api_docs/python/tff/templates/AggregationProcess) uses the inner summation
processes created by the [`tff.aggregators.SecureSumFactory`](https://www.tensorflow.org/federated/api_docs/python/tff/aggregators/SecureSumFactory) to sum unfinalized
metrics 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).

Internally metrics are grouped by their value range and dtype, and only one
secure aggregation process will be created for each group. This is an
optimization for computation tracing and compiling, which can be slow
when there are a large number of independent aggregations.

The `initialize` function initializes the `state` for each inner secure
aggregation progress. The `next` function takes the `state` and local
unfinalized metrics reported from [`tff.CLIENTS`](https://www.tensorflow.org/federated/api_docs/python/tff#CLIENTS), and returns a
[`tff.templates.MeasuredProcessOutput`](https://www.tensorflow.org/federated/api_docs/python/tff/templates/MeasuredProcessOutput) object with the following properties:

- `state`: an `collections.OrderedDict` of the `state`s of the inner secure aggregation processes.
- `result`: an `collections.OrderedDict` of secure summed unfinalized metrics.
- `measurements`: an `collections.OrderedDict` of the measurements of inner secure aggregation processes.

<br />

<br />

<br />

| ## Args ||
|---|---|
| `metric_value_ranges` | An optional `collections.OrderedDict` that matches the structure of `local_unfinalized_metrics_type` (a value for each [`tff.types.TensorType`](https://www.tensorflow.org/federated/api_docs/python/tff/types/TensorType) in the type tree). Each leaf in the tree should have a 2-tuple that defines the range of expected values for that variable in the metric. If the entire structure is `None`, a default range of `[0.0, 2.0**20 - 1]` will be applied to integer variables and auto-tuned bounds will be applied to float variable. Each leaf may also be `None`, which will also get the default range according to the variable value type; allowing partial user sepcialization. At runtime, values that fall outside the ranges specified at the leaves will be clipped to within the range. |

<br />

<br />

<br />

<br />

| ## Raises ||
|---|---|
| `TypeError` | If `metric_value_ranges` type mismatches. |

<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(
        local_unfinalized_metrics_type: https://www.tensorflow.org/federated/api_docs/python/tff/types/StructWithPythonType
    ) -> https://www.tensorflow.org/federated/api_docs/python/tff/templates/AggregationProcess

Creates an `AggregationProcess` for secure summation over metrics.

<br />

<br />

<br />

| Args ||
|---|---|
| `local_unfinalized_metrics_type` | A [`tff.types.StructWithPythonType`](https://www.tensorflow.org/federated/api_docs/python/tff/types/StructWithPythonType) (with `collections.OrderedDict` as the Python container) of a client's local unfinalized metrics. For example, `local_unfinalized_metrics` could represent the output type of [`tff.learning.models.VariableModel.report_local_unfinalized_metrics()`](https://www.tensorflow.org/federated/api_docs/python/tff/learning/models/VariableModel#report_local_unfinalized_metrics). |

<br />

<br />

<br />

<br />

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

<br />

<br />

<br />

<br />

| Raises ||
|---|---|
| `TypeError` | If any argument type mismatches. |

<br />