fl4health.utils.functions module

class BernoulliSample(*args, **kwargs)

Bases: Function

Bernoulli sampling function that allows for gradient computation.

Bernoulli sampling is by itself not differentiable, so in order to integrate it with autograd, this implementation follows the paper “Estimating or propagating gradients through stochastic neurons for conditional computation” and simply returns the Bernoulli probabilities themselves as the “gradient”. This is called the “straight-through estimator”. For more details, please see Section 4 of the aforementioned paper (https://arxiv.org/pdf/1308.3432).

static backward(ctx, grad_output)

Define a formula for differentiating the operation with backward mode automatic differentiation.

This function is to be overridden by all subclasses. (Defining this function is equivalent to defining the vjp function.)

It must accept a context ctx as the first argument, followed by as many outputs as the forward() returned (None will be passed in for non tensor outputs of the forward function), and it should return as many tensors, as there were inputs to forward(). Each argument is the gradient w.r.t the given output, and each returned value should be the gradient w.r.t. the corresponding input. If an input is not a Tensor or is a Tensor not requiring grads, you can just pass None as a gradient for that input.

The context can be used to retrieve tensors saved during the forward pass. It also has an attribute ctx.needs_input_grad as a tuple of booleans representing whether each input needs gradient. E.g., backward() will have ctx.needs_input_grad[0] = True if the first input to forward() needs gradient computed w.r.t. the output.

Return type:

Tensor

static forward(bernoulli_probs)

Define the forward of the custom autograd Function.

This function is to be overridden by all subclasses. There are two ways to define forward:

Usage 1 (Combined forward and ctx):

@staticmethod
def forward(ctx: Any, *args: Any, **kwargs: Any) -> Any:
    pass

Return type:

Tensor

• It must accept a context ctx as the first argument, followed by any number of arguments (tensors or other types).

• See combining-forward-context for more details

Usage 2 (Separate forward and ctx):

@staticmethod
def forward(*args: Any, **kwargs: Any) -> Any:
    pass

@staticmethod
def setup_context(ctx: Any, inputs: Tuple[Any, ...], output: Any) -> None:
    pass

• The forward no longer accepts a ctx argument.

• Instead, you must also override the torch.autograd.Function.setup_context() staticmethod to handle setting up the ctx object. output is the output of the forward, inputs are a Tuple of inputs to the forward.

• See extending-autograd for more details

The context can be used to store arbitrary data that can be then retrieved during the backward pass. Tensors should not be stored directly on ctx (though this is not currently enforced for backward compatibility). Instead, tensors should be saved either with ctx.save_for_backward() if they are intended to be used in backward (equivalently, vjp) or ctx.save_for_forward() if they are intended to be used for in jvp.

static setup_context(ctx, inputs, output)

There are two ways to define the forward pass of an autograd.Function.

Either: :rtype: None

1. Override forward with the signature forward(ctx, *args, **kwargs). setup_context is not overridden. Setting up the ctx for backward happens inside the forward.

2. Override forward with the signature forward(*args, **kwargs) and override setup_context. Setting up the ctx for backward happens inside setup_context (as opposed to inside the forward)

See torch.autograd.Function.forward() and extending-autograd for more details.

decode_and_pseudo_sort_results(results)

This function is used to convert the results of client training into NDArrays and to apply a pseudo sort based on the zeroeth elements in the weights and the sample counts. As long as the numpy seed has been set on the server this process should be deterministic when repeatedly running the same server code leading to deterministic sorting (assuming the clients are deterministically training their weights as well). This allows, for example, for weights from the clients to be summed in a deterministic order during aggregation.

NOTE: Client proxies would be nice to use for this task, but the CIDs are set by uuid deep in the flower library and are, therefore, not pinnable without a ton of work.

Parameters:

results (list[tuple[ClientProxy, FitRes]]) – Results from a federated training round.

Returns:

The ordered set of weights as NDarrays and the corresponding number of examples

Return type:

list[tuple[ClientProxy, NDArrays, int]]

pseudo_sort_scoring_function(client_result)

This function provides the “score” that is used to sort a list of tuple[ClientProxy, NDArrays, int]. We select the zeroeth (index 0 across all dimensions) element from each of the arrays in the NDArrays list, sum them, and add the integer (client sample counts) to the sum to come up with a score for sorting. Note that the underlying numpy arrays in NDArrays may not all be of numerical type. So we limit to selecting elements from arrays of floats.

Parameters:

client_result (tuple[ClientProxy, NDArrays, int]]) – Elements to use to determine the score.

Returns:

Sum of a the zeroeth elements of each array in the NDArrays and the int of the tuple

Return type:

float

select_zeroeth_element(array)

Helper function that simply selects the first element of an array (index 0 across all dimensions).

Parameters:

array (np.ndarray) – Array from which the very first element is selected

Returns:

zeroeth element value.

Return type:

float

sigmoid_inverse(x)

Return type:

Tensor