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: model_lib.MetricFinalizersType,
    local_unfinalized_metrics_type: tff.types.StructWithPythonType,
    metric_value_ranges: Optional[MetricValueRangeDict] = None
) -> tff.Computation

The returned federated TFF computation has the following type signature:

(local_unfinalized_metrics@CLIENTS ->
 <aggregated_metrics@SERVER, secure_sum_measurements@SERVER)

where the input is given by tff.learning.Model.report_local_unfinalized_metrics() 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 a nested structure of the same form as local_unfinalized_metrics with metrics of the secure summation process (e.g. whether a value at that position in the structure was clipped. See tff.aggregators.SecureSumFactory for details).

Since secure summation works in fixed-point arithmetic space, floating point numbers must be encoding using integer quantization. By default, each tensor in local_unfinalized_metrics_type 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 local_unfinalized_metrics_type.

Example partial value range specification:

finalizers = ...
metrics_type = tff.to_type(collections.OrderedDict(
    a=tff.types.TensorType(tf.int32),
    b=tff.types.TensorType(tf.float32),
    c=[tff.types.TensorType(tf.float32), tff.types.TensorType(tf.float32)])
value_ranges = collections.OrderedDict(
    b=(0.0, 1.0),
    c=[None, (0.0, 1.0)])
aggregator = tff.learning.metrics.secure_sum_then_finalize(
    finalizers, metrics_type, 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`	An `OrderedDict` of `string` metric names to finalizer functions returned by `tff.learning.Model.metric_finalizers()`. It should have the same keys (i.e., metric names) as the `OrderedDict` returned by `tff.learning.Model.report_local_unfinalized_metrics()`. A finalizer is a callable (typically `tf.function` or `tff.tf_computation` decoreated function) that takes in a metric's unfinalized values, and returns the finalized values.
`local_unfinalized_metrics_type`	A `tff.types.StructWithPythonType` (with `OrderedDict` as the Python container) of a client's local unfinalized metrics. Let `local_unfinalized_metrics` be the output of `tff.learning.Model.report_local_unfinalized_metrics()`. Its type can be obtained by `tff.framework.type_from_tensors(local_unfinalized_metrics)`.
`metric_value_ranges`	A `collections.OrderedDict` that matches the structure of `local_unfinalized_metrics_type` (a value for each `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 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.
`ValueError`	If the keys (i.e., metric names) in `metric_finalizers` are not the same as those expected by `local_unfinalized_metrics_type`.

tff.learning.metrics.secure_sum_then_finalize

Args

Returns

Raises