5.1.1.8. FedEval.strategy

5.1.1.8.1. Submodules

5.1.1.8.2. Package Contents

5.1.1.8.2.1. Classes

FedAvg

the basic class of federated strategies.

FedSGD

the basic class of federated strategies.

FedSTC

the basic class of federated strategies.

FedProx

the basic class of federated strategies.

FedOpt

the basic class of federated strategies.

FedSCA

MFedAvg

MFedSGD

the basic class of federated strategies.

FedSVD

SecureAggregation

the basic class of federated strategies.

PaillierAggregation

FedStrategy

the basic class of federated strategies.

FedStrategyHostInterface

FedStrategyInterface

the interface of federated strategies.

FedStrategyPeerInterface

class FedEval.strategy.FedAvg(*args, **kwargs)

Bases: FedEval.strategy.FederatedStrategy.FedStrategy

the basic class of federated strategies.

host_select_train_clients(ready_clients)

select clients from the given ones for training purpose.

Parameters:

ready_clients (List[ClientId]) – the id list of clients that are ready for training.

Raises:

NotImplementedError – raised when called but not overriden.

Returns:

the id list of the selected clients.

Return type:

List[ClientId]

host_select_evaluate_clients(ready_clients)

select clients from the given ones for evaluation purpose.

Parameters:

ready_clients (List[ClientId]) – the id list of clients that are ready for evaluaion.

Raises:

NotImplementedError – raised when called but not overriden.

Returns:

the id list of the selected clients.

Return type:

List[ClientId]

class FedEval.strategy.FedSGD(*args, **kwargs)

Bases: FedAvg

the basic class of federated strategies.

compute_gradients(x, y)
host_select_train_clients(ready_clients)

select clients from the given ones for training purpose.

Parameters:

ready_clients (List[ClientId]) – the id list of clients that are ready for training.

Raises:

NotImplementedError – raised when called but not overriden.

Returns:

the id list of the selected clients.

Return type:

List[ClientId]

host_select_evaluate_clients(ready_clients)

select clients from the given ones for evaluation purpose.

Parameters:

ready_clients (List[ClientId]) – the id list of clients that are ready for evaluaion.

Raises:

NotImplementedError – raised when called but not overriden.

Returns:

the id list of the selected clients.

Return type:

List[ClientId]

fit_on_local_data()

fit model with local data at client side.

Called by the selected clients.

Raises:

NotImplementedError – raised when called but not overriden.

Returns:

TODO(fgh)

class FedEval.strategy.FedSTC(**kwargs)

Bases: FedEval.strategy.FedAvg.FedAvg

the basic class of federated strategies.

static stc(input_tensor, sparsity=0.01)
_init_residual()
_tensor_to_vector(input_tensor)
_vector_to_tensor(input_vector)
static compress(input_tensor)
retrieve_local_upload_info()

return the information aggregated from local model for uploading to the central server.

Called by the selected clients.

Raises:

NotImplementedError – raised when called but not overriden.

Returns:

the local model weights/params.

Return type:

ModelWeights

set_host_params_to_local(host_params, current_round)

update the current local ML/DL model’s params with params received from the central server.

Parameters:

  • host_params (ModelWeights) – params received from the central server.

  • current_round (int) – the current round number

Raises:

NotImplementedError – raised when called but not overriden.

update_host_params(client_params, aggregate_weights)

update central server’s model params/weights with the aggregated params received from clients.

Parameters:

  • client_params (Iterable[ModelWeights]) – the weights form different clients, ordered like [params1, params2, …]

  • aggregate_weights (Iterable[Union[float, int]]) – aggregate weights of different clients, usually set according to the clients’ training sample size. E.g., A, B, and C have 10, 20, and 30 images, then the aggregate_weights can be [1/6, 1/3, 1/2] or [10, 20, 30].

Raises:

NotImplementedError – raised when called but not overriden.

retrieve_host_download_info()
get the host download information,

e.g., model params/weights from its machine/deep learning model.

Raises:

NotImplementedError – raised when called but not overriden.

Returns:

the weights/params of its inner machine/deep learning model. TODO(fgh): the meaning of the str in the return type/

Return type:

ModelWeights

class FedEval.strategy.FedProx(*args, **kwargs)

Bases: FedEval.strategy.FedAvg.FedAvg

the basic class of federated strategies.

fit_on_local_data()

fit model with local data at client side.

Called by the selected clients.

Raises:

NotImplementedError – raised when called but not overriden.

Returns:

TODO(fgh)

class FedEval.strategy.FedOpt(*args, **kwags)

Bases: FedEval.strategy.FedAvg.FedAvg

the basic class of federated strategies.

retrieve_local_upload_info()

return the information aggregated from local model for uploading to the central server.

Called by the selected clients.

Raises:

NotImplementedError – raised when called but not overriden.

Returns:

the local model weights/params.

Return type:

ModelWeights

update_host_params(client_params, aggregate_weights)

update central server’s model params/weights with the aggregated params received from clients.

Parameters:

  • client_params (Iterable[ModelWeights]) – the weights form different clients, ordered like [params1, params2, …]

  • aggregate_weights (Iterable[Union[float, int]]) – aggregate weights of different clients, usually set according to the clients’ training sample size. E.g., A, B, and C have 10, 20, and 30 images, then the aggregate_weights can be [1/6, 1/3, 1/2] or [10, 20, 30].

Raises:

NotImplementedError – raised when called but not overriden.

class FedEval.strategy.FedSCA(**kwargs)

Bases: FedEval.strategy.FedAvg.FedAvg

the basic class of federated strategies.

retrieve_host_download_info()
get the host download information,

e.g., model params/weights from its machine/deep learning model.

Raises:

NotImplementedError – raised when called but not overriden.

Returns:

the weights/params of its inner machine/deep learning model. TODO(fgh): the meaning of the str in the return type/

Return type:

ModelWeights

set_host_params_to_local(host_params, current_round)

update the current local ML/DL model’s params with params received from the central server.

Parameters:

  • host_params (ModelWeights) – params received from the central server.

  • current_round (int) – the current round number

Raises:

NotImplementedError – raised when called but not overriden.

update_host_params(client_params, aggregate_weights)

update central server’s model params/weights with the aggregated params received from clients.

Parameters:

  • client_params (Iterable[ModelWeights]) – the weights form different clients, ordered like [params1, params2, …]

  • aggregate_weights (Iterable[Union[float, int]]) – aggregate weights of different clients, usually set according to the clients’ training sample size. E.g., A, B, and C have 10, 20, and 30 images, then the aggregate_weights can be [1/6, 1/3, 1/2] or [10, 20, 30].

Raises:

NotImplementedError – raised when called but not overriden.

fit_on_local_data()

fit model with local data at client side.

Called by the selected clients.

Raises:

NotImplementedError – raised when called but not overriden.

Returns:

TODO(fgh)

retrieve_local_upload_info()

return the information aggregated from local model for uploading to the central server.

Called by the selected clients.

Raises:

NotImplementedError – raised when called but not overriden.

Returns:

the local model weights/params.

Return type:

ModelWeights

class FedEval.strategy.MFedAvg(**kwargs)

Bases: FedEval.strategy.FedAvg.FedAvg

the basic class of federated strategies.

update_host_params(client_params, aggregate_weights)

update central server’s model params/weights with the aggregated params received from clients.

Parameters:

  • client_params (Iterable[ModelWeights]) – the weights form different clients, ordered like [params1, params2, …]

  • aggregate_weights (Iterable[Union[float, int]]) – aggregate weights of different clients, usually set according to the clients’ training sample size. E.g., A, B, and C have 10, 20, and 30 images, then the aggregate_weights can be [1/6, 1/3, 1/2] or [10, 20, 30].

Raises:

NotImplementedError – raised when called but not overriden.

class FedEval.strategy.MFedSGD(**kwargs)

Bases: MFedAvg

the basic class of federated strategies.

class FedEval.strategy.FedSVD(*args, **kwargs)

Bases: FedEval.strategy.FederatedStrategy.FedStrategy

the basic class of federated strategies.

_log_hardware_usage()
_init_model()
host_select_train_clients(ready_clients: List[FedEval.config.ClientId]) → List[FedEval.config.ClientId]

select clients from the given ones for training purpose.

Parameters:

ready_clients (List[ClientId]) – the id list of clients that are ready for training.

Raises:

NotImplementedError – raised when called but not overriden.

Returns:

the id list of the selected clients.

Return type:

List[ClientId]

retrieve_host_download_info()
get the host download information,

e.g., model params/weights from its machine/deep learning model.

Raises:

NotImplementedError – raised when called but not overriden.

Returns:

the weights/params of its inner machine/deep learning model. TODO(fgh): the meaning of the str in the return type/

Return type:

ModelWeights

update_host_params(client_params, *args)

update central server’s model params/weights with the aggregated params received from clients.

Parameters:

  • client_params (Iterable[ModelWeights]) – the weights form different clients, ordered like [params1, params2, …]

  • aggregate_weights (Iterable[Union[float, int]]) – aggregate weights of different clients, usually set according to the clients’ training sample size. E.g., A, B, and C have 10, 20, and 30 images, then the aggregate_weights can be [1/6, 1/3, 1/2] or [10, 20, 30].

Raises:

NotImplementedError – raised when called but not overriden.

safe_memmap_matmul(a, b, step_size=1000)
_server_svd(data_matrix)
set_host_params_to_local(host_params, **kwargs)

update the current local ML/DL model’s params with params received from the central server.

Parameters:

  • host_params (ModelWeights) – params received from the central server.

  • current_round (int) – the current round number

Raises:

NotImplementedError – raised when called but not overriden.

_generate_masked_data_in_secure_agg(shape, base=None)
fit_on_local_data()

fit model with local data at client side.

Called by the selected clients.

Raises:

NotImplementedError – raised when called but not overriden.

Returns:

TODO(fgh)

local_evaluate()

evaluate and test the model received from the central server.

Called by the selected clients.

Raises:

NotImplementedError – raised when called but not overriden.

Returns:

evaluation & test metrics.

Return type:

Mapping[str, Union[int, float]]

client_exit_job(client)

do self-defined finishing jobs before the shutdown of the local clients.

Parameters:

client – TODO(fgh)

Raises:

NotImplementedError – raised when called but not overriden.

retrieve_local_upload_info()

return the information aggregated from local model for uploading to the central server.

Called by the selected clients.

Raises:

NotImplementedError – raised when called but not overriden.

Returns:

the local model weights/params.

Return type:

ModelWeights

host_exit_job(host)

do self-defined finishing jobs before the shutdown of the central server.

Parameters:

host – TODO(fgh)

Raises:

NotImplementedError – raised when called but not overriden.

class FedEval.strategy.SecureAggregation(**kwargs)

Bases: FedEval.strategy.FederatedStrategy.FedStrategy

the basic class of federated strategies.

host_select_train_clients(ready_clients)

select clients from the given ones for training purpose.

Parameters:

ready_clients (List[ClientId]) – the id list of clients that are ready for training.

Raises:

NotImplementedError – raised when called but not overriden.

Returns:

the id list of the selected clients.

Return type:

List[ClientId]

retrieve_host_download_info()
get the host download information,

e.g., model params/weights from its machine/deep learning model.

Raises:

NotImplementedError – raised when called but not overriden.

Returns:

the weights/params of its inner machine/deep learning model. TODO(fgh): the meaning of the str in the return type/

Return type:

ModelWeights

update_host_params(client_params, aggregate_weights)

update central server’s model params/weights with the aggregated params received from clients.

Parameters:

  • client_params (Iterable[ModelWeights]) – the weights form different clients, ordered like [params1, params2, …]

  • aggregate_weights (Iterable[Union[float, int]]) – aggregate weights of different clients, usually set according to the clients’ training sample size. E.g., A, B, and C have 10, 20, and 30 images, then the aggregate_weights can be [1/6, 1/3, 1/2] or [10, 20, 30].

Raises:

NotImplementedError – raised when called but not overriden.

set_host_params_to_local(host_params, current_round: int)

update the current local ML/DL model’s params with params received from the central server.

Parameters:

  • host_params (ModelWeights) – params received from the central server.

  • current_round (int) – the current round number

Raises:

NotImplementedError – raised when called but not overriden.

fit_on_local_data()

fit model with local data at client side.

Called by the selected clients.

Raises:

NotImplementedError – raised when called but not overriden.

Returns:

TODO(fgh)

retrieve_local_upload_info()

return the information aggregated from local model for uploading to the central server.

Called by the selected clients.

Raises:

NotImplementedError – raised when called but not overriden.

Returns:

the local model weights/params.

Return type:

ModelWeights

class FedEval.strategy.PaillierAggregation(**kwargs)

Bases: FedEval.strategy.FederatedStrategy.FedStrategy

the basic class of federated strategies.

host_select_train_clients(ready_clients)

select clients from the given ones for training purpose.

Parameters:

ready_clients (List[ClientId]) – the id list of clients that are ready for training.

Raises:

NotImplementedError – raised when called but not overriden.

Returns:

the id list of the selected clients.

Return type:

List[ClientId]

retrieve_host_download_info()
get the host download information,

e.g., model params/weights from its machine/deep learning model.

Raises:

NotImplementedError – raised when called but not overriden.

Returns:

the weights/params of its inner machine/deep learning model. TODO(fgh): the meaning of the str in the return type/

Return type:

ModelWeights

update_host_params(client_params, aggregate_weights) → None

update central server’s model params/weights with the aggregated params received from clients.

Parameters:

  • client_params (Iterable[ModelWeights]) – the weights form different clients, ordered like [params1, params2, …]

  • aggregate_weights (Iterable[Union[float, int]]) – aggregate weights of different clients, usually set according to the clients’ training sample size. E.g., A, B, and C have 10, 20, and 30 images, then the aggregate_weights can be [1/6, 1/3, 1/2] or [10, 20, 30].

Raises:

NotImplementedError – raised when called but not overriden.

set_host_params_to_local(host_params, current_round: int)

update the current local ML/DL model’s params with params received from the central server.

Parameters:

  • host_params (ModelWeights) – params received from the central server.

  • current_round (int) – the current round number

Raises:

NotImplementedError – raised when called but not overriden.

fit_on_local_data()

fit model with local data at client side.

Called by the selected clients.

Raises:

NotImplementedError – raised when called but not overriden.

Returns:

TODO(fgh)

retrieve_local_upload_info()

return the information aggregated from local model for uploading to the central server.

Called by the selected clients.

Raises:

NotImplementedError – raised when called but not overriden.

Returns:

the local model weights/params.

Return type:

ModelWeights

class FedEval.strategy.FedStrategy(client_id=None, param_parser: type = ParamParser, logger=None)

Bases: FedStrategyInterface

the basic class of federated strategies.

property client_id

Client ID

Type:

Returns

property param_parser: FedEval.utils.ParamParserInterface

the getter of param_parser.

Raises:

NotImplementedError – raised when called but not overriden.

Returns:

self._param_parser

Return type:

ParamParserInterface

property host_params_type

Returns the same parameters for all parties or personalized ML model

property train_selected_clients

Returns the selected clients for training

property host_params

Host parameters

Type:

Returns

property eval_selected_clients

Returns the selected clients for evaluation

property stop

Server-side train stop flag

set_logger(logger) → None

the setter of logger of this federated learning.

Parameters:

logger – an external logger.

Raises:

NotImplementedError – raised when called but not overriden.

_init_model()
_init_data() → None
_init_states()
_config_callback()
_has_callback() → bool
retrieve_host_download_info() → FedEval.aggregator.ModelWeights
get the host download information,

e.g., model params/weights from its machine/deep learning model.

Raises:

NotImplementedError – raised when called but not overriden.

Returns:

the weights/params of its inner machine/deep learning model. TODO(fgh): the meaning of the str in the return type/

Return type:

ModelWeights

update_host_params(client_params, aggregate_weights) → None

update central server’s model params/weights with the aggregated params received from clients.

Parameters:

  • client_params (Iterable[ModelWeights]) – the weights form different clients, ordered like [params1, params2, …]

  • aggregate_weights (Iterable[Union[float, int]]) – aggregate weights of different clients, usually set according to the clients’ training sample size. E.g., A, B, and C have 10, 20, and 30 images, then the aggregate_weights can be [1/6, 1/3, 1/2] or [10, 20, 30].

Raises:

NotImplementedError – raised when called but not overriden.

host_exit_job(host)

do self-defined finishing jobs before the shutdown of the central server.

Parameters:

host – TODO(fgh)

Raises:

NotImplementedError – raised when called but not overriden.

host_select_train_clients(ready_clients: List[FedEval.config.ClientId]) → List[FedEval.config.ClientId]

select clients from the given ones for training purpose.

Parameters:

ready_clients (List[ClientId]) – the id list of clients that are ready for training.

Raises:

NotImplementedError – raised when called but not overriden.

Returns:

the id list of the selected clients.

Return type:

List[ClientId]

host_select_evaluate_clients(ready_clients: List[FedEval.config.ClientId]) → List[FedEval.config.ClientId]

select clients from the given ones for evaluation purpose.

Parameters:

ready_clients (List[ClientId]) – the id list of clients that are ready for evaluaion.

Raises:

NotImplementedError – raised when called but not overriden.

Returns:

the id list of the selected clients.

Return type:

List[ClientId]

set_host_params_to_local(host_params: FedEval.aggregator.ModelWeights, current_round: int)

update the current local ML/DL model’s params with params received from the central server.

Parameters:

  • host_params (ModelWeights) – params received from the central server.

  • current_round (int) – the current round number

Raises:

NotImplementedError – raised when called but not overriden.

fit_on_local_data()

fit model with local data at client side.

Called by the selected clients.

Raises:

NotImplementedError – raised when called but not overriden.

Returns:

TODO(fgh)

_retrieve_local_params()
retrieve_local_upload_info() → FedEval.aggregator.ModelWeights

return the information aggregated from local model for uploading to the central server.

Called by the selected clients.

Raises:

NotImplementedError – raised when called but not overriden.

Returns:

the local model weights/params.

Return type:

ModelWeights

local_evaluate() → Mapping[str, int | float]

evaluate and test the model received from the central server.

Called by the selected clients.

Raises:

NotImplementedError – raised when called but not overriden.

Returns:

evaluation & test metrics.

Return type:

Mapping[str, Union[int, float]]

client_exit_job(client)

do self-defined finishing jobs before the shutdown of the local clients.

Parameters:

client – TODO(fgh)

Raises:

NotImplementedError – raised when called but not overriden.

class FedEval.strategy.FedStrategyHostInterface
abstract property host_params

Host parameters

Type:

Returns

abstract property host_params_type

Returns the same parameters for all parties or personalized ML model

abstract property stop

Server-side train stop flag

abstract property train_selected_clients

Returns the selected clients for training

abstract property eval_selected_clients

Returns the selected clients for evaluation

abstract retrieve_host_download_info() → Tuple[FedEval.aggregator.ModelWeights, str]
get the host download information,

e.g., model params/weights from its machine/deep learning model.

Raises:

NotImplementedError – raised when called but not overriden.

Returns:

the weights/params of its inner machine/deep learning model. TODO(fgh): the meaning of the str in the return type/

Return type:

ModelWeights

abstract update_host_params(client_params: Iterable[FedEval.aggregator.ModelWeights], aggregate_weights: Iterable[float | int]) → None

update central server’s model params/weights with the aggregated params received from clients.

Parameters:

  • client_params (Iterable[ModelWeights]) – the weights form different clients, ordered like [params1, params2, …]

  • aggregate_weights (Iterable[Union[float, int]]) – aggregate weights of different clients, usually set according to the clients’ training sample size. E.g., A, B, and C have 10, 20, and 30 images, then the aggregate_weights can be [1/6, 1/3, 1/2] or [10, 20, 30].

Raises:

NotImplementedError – raised when called but not overriden.

abstract host_exit_job(host)

do self-defined finishing jobs before the shutdown of the central server.

Parameters:

host – TODO(fgh)

Raises:

NotImplementedError – raised when called but not overriden.

abstract host_select_train_clients(ready_clients: List[FedEval.config.ClientId]) → List[FedEval.config.ClientId]

select clients from the given ones for training purpose.

Parameters:

ready_clients (List[ClientId]) – the id list of clients that are ready for training.

Raises:

NotImplementedError – raised when called but not overriden.

Returns:

the id list of the selected clients.

Return type:

List[ClientId]

abstract host_select_evaluate_clients(ready_clients: List[FedEval.config.ClientId]) → List[FedEval.config.ClientId]

select clients from the given ones for evaluation purpose.

Parameters:

ready_clients (List[ClientId]) – the id list of clients that are ready for evaluaion.

Raises:

NotImplementedError – raised when called but not overriden.

Returns:

the id list of the selected clients.

Return type:

List[ClientId]

class FedEval.strategy.FedStrategyInterface

Bases: FedStrategyHostInterface, FedStrategyPeerInterface

the interface of federated strategies.

This class should be inherited instead of being instantiated.

Raises:

NotImplementedError – raised when called but not overriden.

abstract property param_parser: FedEval.utils.ParamParserInterface

the getter of param_parser.

Raises:

NotImplementedError – raised when called but not overriden.

Returns:

self._param_parser

Return type:

ParamParserInterface

abstract set_logger(logger) → None

the setter of logger of this federated learning.

Parameters:

logger – an external logger.

Raises:

NotImplementedError – raised when called but not overriden.

class FedEval.strategy.FedStrategyPeerInterface
abstract property client_id

Client ID

Type:

Returns

abstract set_host_params_to_local(host_params: FedEval.aggregator.ModelWeights, current_round: int)

update the current local ML/DL model’s params with params received from the central server.

Parameters:

  • host_params (ModelWeights) – params received from the central server.

  • current_round (int) – the current round number

Raises:

NotImplementedError – raised when called but not overriden.

abstract fit_on_local_data()

fit model with local data at client side.

Called by the selected clients.

Raises:

NotImplementedError – raised when called but not overriden.

Returns:

TODO(fgh)

abstract retrieve_local_upload_info() → FedEval.aggregator.ModelWeights

return the information aggregated from local model for uploading to the central server.

Called by the selected clients.

Raises:

NotImplementedError – raised when called but not overriden.

Returns:

the local model weights/params.

Return type:

ModelWeights

abstract local_evaluate() → Mapping[str, int | float]

evaluate and test the model received from the central server.

Called by the selected clients.

Raises:

NotImplementedError – raised when called but not overriden.

Returns:

evaluation & test metrics.

Return type:

Mapping[str, Union[int, float]]

abstract client_exit_job(client)

do self-defined finishing jobs before the shutdown of the local clients.

Parameters:

client – TODO(fgh)

Raises:

NotImplementedError – raised when called but not overriden.