tff.learning.metrics.secure_sum_then_finalize

Creates a TFF computation that aggregates metrics using secure summation.

tff.learning.metrics.secure_sum_then_finalize(
    metric_finalizers: Union[tff.learning.metrics.MetricFinalizersType, tff.learning.metrics.FunctionalMetricFinalizersType],
    local_unfinalized_metrics_type: Optional[tff.types.StructWithPythonType] = None,
    metric_value_ranges: Optional[sum_aggregation_factory.UserMetricValueRangeDict] = None
) -> tff.Computation

The returned federated TFF computation is a polymorphic computation that accepts unfinalized client metrics, and returns finalized, summed metrics placed at the server. Invoking the polymorphic computation will initiate tracing on the argument and will raise a ValueError if the keys (i.e., metric names) in metric_finalizers are not the same as those of the argument the polymorphic method is invoked on.

The computation is intended to be invoked on the output of tff.learning.models.VariableModel.report_local_unfinalized_metrics() when placed at CLIENTS, and the first output (aggregated_metrics) is computed by first securely summing the unfinalized metrics from CLIENTS, followed by applying the finalizers at SERVER. The second output (secure_sum_measurements) is an OrderedDict that maps from factory_keys to the secure summation measurements (e.g. the number of clients gets clipped. See tff.aggregators.SecureSumFactory for details). A factory_key is uniquely defined by three scalars: lower bound, upper bound, and tensor dtype (denoted as datatype enum). Metric values of the same factory_key are grouped and aggegrated together (and hence, the secure_sum_measurements are also computed at a group level).

Since secure summation works in fixed-point arithmetic space, floating point numbers must be encoding using integer quantization. By default, each tensor in from the clients unfinalized metrics will be clipped to [0, 2**20 - 1] and encoded to integers inside tff.aggregators.SecureSumFactory. Callers can change this range by setting metric_value_ranges, which may be a partial tree matching the structure of the argument to metrics_finalizers.

Example partial value range specification:

finalizers = ...
value_ranges = collections.OrderedDict(
    b=(0.0, 1.0),
    c=[None, (0.0, 1.0)])
aggregator = tff.learning.metrics.secure_sum_then_finalize(
    finalizers, value_ranges)

This sets the range of the second tensor of b in the dictionary, using the range for the first tensor, and the a tensor.

Args
`metric_finalizers`	Either the result of `tff.learning.models.VariableModel.metric_finalizers` (an `OrderedDict` of callables) or the `tff.learning.models.FunctionalModel.finalize_metrics` method (a callable that takes an `OrderedDict` argument). If the former, the keys must be the same as the `OrderedDict` returned by `tff.learning.models.VariableModel.report_local_unfinalized_metrics`. If the later, the callable must compute over the same keyspace of the result returned by `tff.learning.models.FunctionalModel.update_metrics_state`.
`local_unfinalized_metrics_type`	Unused, will be removed from the API in the future.
`metric_value_ranges`	A `collections.OrderedDict` that matches the structure of the input arguments of `metric_finalizers`. 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 all variables. Each leaf may also be `None`, which will also get the default range; allowing partial user sepcialization. At runtime, values that fall outside the ranges specified at the leaves, those values will be clipped to within the range.

Returns
A federated TFF computation that securely sums the unfinalized metrics from `CLIENTS`, and applies the correponding finalizers at `SERVER`.

Raises
`TypeError`	If the inputs are of the wrong types.

tff.learning.metrics.secure_sum_then_finalize

Args

Returns

Raises