fedn.network.combiner.aggregators package

The aggregator package is responsible for aggregating models from multiple clients. It’s called both in fedn.network.combiner.Combiner and fedn.network.controller.Controller to aggregate models from clients.

Submodules

fedn.network.combiner.aggregators.aggregator module

fedn.network.combiner.aggregators.aggregatorbase module

class fedn.network.combiner.aggregators.aggregatorbase.AggregatorBase(storage, server, modelservice, round_handler)[source]

Bases: ABC

Abstract class defining an aggregator.

Parameters:

  • id (str) – A reference to id of :class: fedn.network.combiner.Combiner

  • storage (class: fedn.common.storage.s3.s3repo.S3ModelRepository) – Model repository for :class: fedn.network.combiner.Combiner

  • server (class: fedn.network.combiner.Combiner) – A handle to the Combiner class :class: fedn.network.combiner.Combiner

  • modelservice (class: fedn.network.combiner.modelservice.ModelService) – A handle to the model service :class: fedn.network.combiner.modelservice.ModelService

  • control (class: fedn.network.combiner.roundhandler.RoundHandler) – A handle to the :class: fedn.network.combiner.roundhandler.RoundHandler

abstract combine_models(nr_expected_models=None, nr_required_models=1, helper=None, timeout=180, delete_models=True, parameters=None)[source]

Routine for combining model updates. Implemented in subclass.

Parameters:

  • nr_expected_models (int) – Number of expected models. If None, wait for all models.

  • nr_required_models (int) – Number of required models to combine.

  • helper – A helper object.

  • timeout (int) – Timeout in seconds to wait for models to be combined.

  • delete_models (bool) – Delete client models after combining.

  • parameters (dict) – Additional key-word arguments.

Returns:

The global model and metadata

Return type:

tuple

get_state()[source]

Get the state of the aggregator’s queue, including the number of model updates.

load_model_update(model_update, helper)[source]

Load the memory representation of the model update.

Load the model update paramters and the associate metadata into memory.

Parameters:

  • model_update (fedn.network.grpc.fedn.proto.ModelUpdate) – The model update.

  • helper (fedn.utils.helpers.helperbase.Helper) – A helper object.

Returns:

A tuple of (parameters, metadata)

Return type:

tuple

next_model_update()[source]

Get the next model update from the queue.

Parameters:

helper (object) – A helper object.

Returns:

The model update.

Return type:

fedn.network.grpc.fedn.proto.ModelUpdate

on_model_update(model_update)[source]

Callback when a new client model update is recieved.

Performs (optional) validation and pre-processing, and then puts the update id on the aggregation queue. Override in subclass as needed.

Parameters:

model_update – fedn.network.grpc.fedn.proto.ModelUpdate

fedn.network.combiner.aggregators.aggregatorbase.get_aggregator(aggregator_module_name, storage, server, modelservice, control)[source]

Return an instance of the helper class.

Parameters:

  • helper_module_name (str) – The name of the helper plugin module.

  • storage (class: fedn.common.storage.s3.s3repo.S3ModelRepository) – Model repository for :class: fedn.network.combiner.Combiner

  • server (class: fedn.network.combiner.Combiner) – A handle to the Combiner class :class: fedn.network.combiner.Combiner

  • modelservice (class: fedn.network.combiner.modelservice.ModelService) – A handle to the model service :class: fedn.network.combiner.modelservice.ModelService

  • control (class: fedn.network.combiner.roundhandler.RoundHandler) – A handle to the :class: fedn.network.combiner.roundhandler.RoundHandler

Returns:

An aggregator instance.

Return type:

class: fedn.combiner.aggregators.AggregatorBase

fedn.network.combiner.aggregators.fedavg module

class fedn.network.combiner.aggregators.fedavg.Aggregator(storage, server, modelservice, round_handler)[source]

Bases: AggregatorBase

Local SGD / Federated Averaging (FedAvg) aggregator. Computes a weighted mean

of parameter updates.

Parameters:

  • id (str) – A reference to id of :class: fedn.network.combiner.Combiner

  • storage (class: fedn.common.storage.s3.s3repo.S3ModelRepository) – Model repository for :class: fedn.network.combiner.Combiner

  • server (class: fedn.network.combiner.Combiner) – A handle to the Combiner class :class: fedn.network.combiner.Combiner

  • modelservice (class: fedn.network.combiner.modelservice.ModelService) – A handle to the model service :class: fedn.network.combiner.modelservice.ModelService

  • control (class: fedn.network.combiner.roundhandler.RoundHandler) – A handle to the :class: fedn.network.combiner.roundhandler.RoundHandler

combine_models(helper=None, delete_models=True, parameters=None)[source]

Aggregate all model updates in the queue by computing an incremental weighted average of model parameters.

Parameters:

  • helper (class: fedn.utils.helpers.helpers.HelperBase, optional) – An instance of :class: fedn.utils.helpers.helpers.HelperBase, ML framework specific helper, defaults to None

  • time_window (int, optional) – The time window for model aggregation, defaults to 180

  • max_nr_models (int, optional) – The maximum number of updates aggregated, defaults to 100

  • delete_models (bool, optional) – Delete models from storage after aggregation, defaults to True

Returns:

The global model and metadata

Return type:

tuple

fedn.network.combiner.aggregators.fedopt module

class fedn.network.combiner.aggregators.fedopt.Aggregator(storage, server, modelservice, round_handler)[source]

Bases: AggregatorBase

Federated Optimization (FedOpt) aggregator.

Implmentation following: https://arxiv.org/pdf/2003.00295.pdf

This aggregator computes pseudo gradients by subtracting the model update from the global model weights from the previous round. A server-side scheme is then applied, currenty supported schemes are “adam”, “yogi”, “adagrad”.

Parameters:

  • id (str) – A reference to id of :class: fedn.network.combiner.Combiner

  • storage (class: fedn.common.storage.s3.s3repo.S3ModelRepository) – Model repository for :class: fedn.network.combiner.Combiner

  • server (class: fedn.network.combiner.Combiner) – A handle to the Combiner class :class: fedn.network.combiner.Combiner

  • modelservice (class: fedn.network.combiner.modelservice.ModelService) – A handle to the model service :class: fedn.network.combiner.modelservice.ModelService

  • control (class: fedn.network.combiner.roundhandler.RoundHandler) – A handle to the :class: fedn.network.combiner.roundhandler.RoundHandler

combine_models(helper=None, delete_models=True, parameters=None)[source]

Compute pseudo gradients using model updates in the queue.

Parameters:

  • helper (class: fedn.utils.helpers.helpers.HelperBase, optional) – An instance of :class: fedn.utils.helpers.helpers.HelperBase, ML framework specific helper, defaults to None

  • time_window (int, optional) – The time window for model aggregation, defaults to 180

  • max_nr_models (int, optional) – The maximum number of updates aggregated, defaults to 100

  • delete_models (bool, optional) – Delete models from storage after aggregation, defaults to True

  • parameters (fedn.utils.parmeters.Parameters, optional) – Aggregator hyperparameters.

Returns:

The global model and metadata

Return type:

tuple

serveropt_adagrad(helper, pseudo_gradient, model_old, parameters)[source]

Server side optimization, FedAdam.

Parameters:

  • helper (Helper) – instance of helper class.

  • pseudo_gradient (As defined by helper.) – The pseudo gradient.

  • model_old (As defined in helper.) – The current global model.

  • parameters (dict) – Hyperparamters for the aggregator.

Returns:

new model weights.

Return type:

as defined by helper.

serveropt_adam(helper, pseudo_gradient, model_old, parameters)[source]

Server side optimization, FedAdam.

Parameters:

  • helper (Helper) – instance of helper class.

  • pseudo_gradient (As defined by helper.) – The pseudo gradient.

  • model_old (As defined in helper.) – The current global model.

  • parameters (dict) – Hyperparamters for the aggregator.

Returns:

new model weights.

Return type:

as defined by helper.

serveropt_yogi(helper, pseudo_gradient, model_old, parameters)[source]

Server side optimization, FedYogi.

Parameters:

  • helper (Helper) – instance of helper class.

  • pseudo_gradient (As defined by helper.) – The pseudo gradient.

  • model_old (As defined in helper.) – The current global model.

  • parameters (dict) – Hyperparamters for the aggregator.

Returns:

new model weights.

Return type:

as defined by helper.