def federated_secure_sum_bitwidth(value, bitwidth):
"""Computes a sum at `tff.SERVER` of a `value` placed on the `tff.CLIENTS`.
This function computes a sum such that it should not be possible for the
server to learn any clients individual value. The specific algorithm and
mechanism used to compute the secure sum may vary depending on the target
runtime environment the computation is compiled for or executed on. See
https://research.google/pubs/pub47246/ for more information.
Not all executors support `tff.federated_secure_sum_bitwidth()`; consult the
documentation for the specific executor or executor stack you plan on using
for the specific of how it's handled by that executor.
The `bitwidth` argument represents the bitwidth of the aggregand, that is the
bitwidth of the input `value`. The federated secure sum bitwidth (i.e., the
bitwidth of the *sum* of the input `value`s over all clients) will be a
function of this bitwidth and the number of participating clients.
Example:
```python
value = tff.federated_value(1, tff.CLIENTS)
result = tff.federated_secure_sum_bitwidth(value, 2)
value = tff.federated_value([1, 1], tff.CLIENTS)
result = tff.federated_secure_sum_bitwidth(value, [2, 4])
value = tff.federated_value([1, [1, 1]], tff.CLIENTS)
result = tff.federated_secure_sum_bitwidth(value, [2, [4, 8]])
```
Note: To sum non-integer values or to sum integers with fewer constraints and
weaker privacy properties, consider using `federated_sum`.
Args:
value: An integer value of a TFF federated type placed at the `tff.CLIENTS`,
in the range [0, 2^bitwidth - 1].
bitwidth: An integer or nested structure of integers matching the structure
of `value`. If integer `bitwidth` is used with a nested `value`, the same
integer is used for each tensor in `value`.
Returns:
A representation of the sum of the member constituents of `value` placed
on the `tff.SERVER`.
Raises:
TypeError: If the argument is not a federated TFF value placed at
`tff.CLIENTS`.
"""
value = value_impl.to_value(value, None)
value = value_utils.ensure_federated_value(value, placements.CLIENTS,
'value to be summed')
type_analysis.check_is_structure_of_integers(value.type_signature)
bitwidth_value = value_impl.to_value(bitwidth, None)
value_member_type = value.type_signature.member
bitwidth_type = bitwidth_value.type_signature
if not type_analysis.is_single_integer_or_matches_structure(
bitwidth_type, value_member_type):
raise TypeError(
'Expected `federated_secure_sum_bitwidth` parameter `bitwidth` to match '
'the structure of `value`, with one integer bitwidth per tensor in '
'`value`. Found `value` of `{}` and `bitwidth` of `{}`.'.format(
value_member_type, bitwidth_type))
if bitwidth_type.is_tensor() and value_member_type.is_struct():
bitwidth_value = value_impl.to_value(
structure.map_structure(lambda _: bitwidth, value_member_type),
None)
comp = building_block_factory.create_federated_secure_sum_bitwidth(
value.comp, bitwidth_value.comp)
comp = _bind_comp_as_reference(comp)
return value_impl.Value(comp)
def federated_secure_modular_sum(value, modulus):
"""Computes a modular sum at `tff.SERVER` of a `value` from `tff.CLIENTS`.
This function computes a sum such that it should not be possible for the
server to learn any clients individual value. The specific algorithm and
mechanism used to compute the secure sum may vary depending on the target
runtime environment the computation is compiled for or executed on. See
https://research.google/pubs/pub47246/ for more information.
Not all executors support `tff.federated_secure_modular_sum()`; consult the
documentation for the specific executor or executor stack you plan on using
for the specific of how it's handled by that executor.
The `modulus` argument is the modulus under which the client values are added.
The result of this function will be equivalent to `SUM(value) % modulus`.
*Lower values may allow for improved communication efficiency.*
Example:
```python
value = tff.federated_value(5, tff.CLIENTS)
result = tff.federated_secure_modular_sum(value, 3)
# `result == (5 * num_clients % 3)@SERVER`
value = tff.federated_value((3, 9), tff.CLIENTS)
result = tff.federated_secure_modular_sum(value, (100, 200))
# `result == (3 * num_clients % 100, 9 * num_clients % 100)@SERVER`
```
Note: To sum non-integer values or to sum integers with fewer constraints and
weaker privacy properties, consider using `federated_sum`.
Args:
value: An integer or nested structure of integers placed at `tff.CLIENTS`.
Values outside of the range [0, modulus-1] will be considered equivalent
to mod(value, modulus), i.e. they will be projected into the range
[0, modulus-1] as part of the modular summation.
modulus: A Python integer or nested structure of integers matching the
structure of `value`. If integer `modulus` is used with a nested `value`,
the same integer is used for each tensor in `value`.
Returns:
A representation of the modular sum of the member constituents of `value`
placed on the `tff.SERVER`. The resulting modular sum will be on the range
[0, modulus-1].
Raises:
TypeError: If the argument is not a federated TFF value placed at
`tff.CLIENTS`.
"""
value = value_impl.to_value(value, None)
value = value_utils.ensure_federated_value(value, placements.CLIENTS,
'value to be summed')
type_analysis.check_is_structure_of_integers(value.type_signature)
modulus_value = value_impl.to_value(modulus, None)
value_member_type = value.type_signature.member
modulus_type = modulus_value.type_signature
if not type_analysis.is_single_integer_or_matches_structure(
modulus_type, value_member_type):
raise TypeError(
'Expected `federated_secure_sum` parameter `modulus` to match '
'the structure of `value`, with one integer max per tensor in '
'`value`. Found `value` of `{}` and `modulus` of `{}`.'.format(
value_member_type, modulus_type))
if modulus_type.is_tensor() and value_member_type.is_struct():
modulus_value = value_impl.to_value(
structure.map_structure(lambda _: modulus, value_member_type),
None)
comp = building_block_factory.create_federated_secure_modular_sum(
value.comp, modulus_value.comp)
comp = _bind_comp_as_reference(comp)
return value_impl.Value(comp)
def federated_secure_sum(value, max_input):
"""Computes a sum at `tff.SERVER` of a `value` placed on the `tff.CLIENTS`.
This function computes a sum such that it should not be possible for the
server to learn any clients individual value. The specific algorithm and
mechanism used to compute the secure sum may vary depending on the target
runtime environment the computation is compiled for or executed on. See
https://research.google/pubs/pub47246/ for more information.
Not all executors support `tff.federated_secure_sum()`; consult the
documentation for the specific executor or executor stack you plan on using
for the specific of how it's handled by that executor.
The `max_input` argument is the maximum value (inclusive) that may appear in
`value`. *Lower values may allow for improved communication efficiency.*
Attempting to return a `value` higher than `max_input` is invalid, and will
result in a failure at the given client.
Example:
```python
value = tff.federated_value(1, tff.CLIENTS)
result = tff.federated_secure_sum(value, 1)
value = tff.federated_value((1, 2), tff.CLIENTS)
result = tff.federated_secure_sum(value, (1, 2))
```
Note: To sum non-integer values or to sum integers with fewer constraints and
weaker privacy properties, consider using `federated_sum`.
Args:
value: An integer or nested structure of integers placed at `tff.CLIENTS`,
in the range `[0, max_input]`.
max_input: A Python integer or nested structure of integers matching the
structure of `value`. If integer `max_value` is used with a nested
`value`, the same integer is used for each tensor in `value`.
Returns:
A representation of the sum of the member constituents of `value` placed
on the `tff.SERVER`.
Raises:
TypeError: If the argument is not a federated TFF value placed at
`tff.CLIENTS`.
"""
value = value_impl.to_value(value, None)
value = value_utils.ensure_federated_value(value, placements.CLIENTS,
'value to be summed')
type_analysis.check_is_structure_of_integers(value.type_signature)
max_input_value = value_impl.to_value(max_input, None)
value_member_type = value.type_signature.member
max_input_type = max_input_value.type_signature
if not type_analysis.is_single_integer_or_matches_structure(
max_input_type, value_member_type):
raise TypeError(
'Expected `federated_secure_sum` parameter `max_input` to match '
'the structure of `value`, with one integer max per tensor in '
'`value`. Found `value` of `{}` and `max_input` of `{}`.'.format(
value_member_type, max_input_type))
if max_input_type.is_tensor() and value_member_type.is_struct():
max_input_value = value_impl.to_value(
structure.map_structure(lambda _: max_input, value_member_type),
None)
comp = building_block_factory.create_federated_secure_sum(
value.comp, max_input_value.comp)
comp = _bind_comp_as_reference(comp)
return value_impl.Value(comp)
def test_returns_false(self, type_sig, shape_type):
self.assertFalse(
type_analysis.is_single_integer_or_matches_structure(
type_sig, shape_type))