Start Your Own Case

In addition to the rich collcetion of datasets, models and evaluation metrics, FederatedScope also allows to create your own or introduce more to our package.

We provide register function to help build your own federated learning workflow.  This introduction will help you to start with your own case:

  1. Load a dataset
  2. Build a model
  3. Create a trainer
  4. Introduce more evaluation metrics
  5. Specify your own configuration

Load a dataset

We provide a function federatedscope.register.register_data to make your dataset available with three steps:

  • Step1: set up your data with Data Translator (standalone), which translates your to FS data format (for more details about FS data module, see FS Data):

    def load_my_data(config, client_cfgs=None):
        from import BaseDataTranslator
        # Load a dataset, whose class is ``
        dataset = ...
    		# Instantiate a translator according to config
        translator = BaseDataTranslator(config, client_cfgs)
        # Translate torch dataset to FS data
        fs_data = translator(dataset)
        return fs_data, config	
  • We take torchvision.datasets.MNIST, which is split and assigned to two clients, as an example:

      def load_my_data(config, client_cfgs=None):
          transform = transforms.Compose([
                transforms.Normalize(mean=[0.1307], std=[0.3081])
          data_train = MNIST(root='data', train=True, transform=transform, download=True)
          data_test = MNIST(root='data', train=False, transform=transform, download=True)
          translator = BaseDataTranslator(config, client_cfgs)
          fs_data = translator([data_train, [], data_test])
          return fs_data, config
  • Step2: register your data with a keyword, such as "mydata".

     from federatedscope.register import register_data
     def call_my_data(config):
         if == "mydata":
             data, modified_config = load_my_data(config)
             return data, modified_config
     register_data("mydata", call_my_data)
  • Step3: put this .py file in the federatedscope/contrib/data/ folder, and set = "mydata" to use it.

Also,  you can modify the source code to make the FederatedScope support your dataset. Please see federatedscope.core.auxiliaries.data_builder , and you can add an elif to skip Step2 and Step3 above.

Build a model

We provide a function federatedscope.register.register_model to make your model available with three steps: (we take ConvNet2 as an example)

  • Step1: build your model with Pytorch or Tensorflow and instantiate your model class with config and data.

     import torch
     class MyNet(torch.nn.Module):
         def __init__(self,
             super(MyNet, self).__init__()
             self.conv1 = torch.nn.Conv2d(in_channels, 32, 5, padding=2)
             self.conv2 = torch.nn.Conv2d(32, 64, 5, padding=2)
             self.fc1 = torch.nn.Linear((h // 2 // 2) * (w // 2 // 2) * 64, hidden)
             self.fc2 = torch.nn.Linear(hidden, class_num)
             self.relu = torch.nn.ReLU(inplace=True)
             self.maxpool = torch.nn.MaxPool2d(2)
         def forward(self, x):
             x = self.conv1(x)
             x = self.maxpool(self.relu(x))
             x = self.conv2(x)
             x = self.maxpool(self.relu(x))
             x = torch.nn.Flatten()(x)
             x = self.relu(self.fc1(x))
             x = self.fc2(x)
             return x
     def load_my_net(model_config, local_data):
         # You can also build models without local_data
         data = next(iter(local_data['train']))
         model = MyNet(in_channels=data[0].shape[1],
         return model
  • Step2: register your model with a keyword, such as "mynet".

     from federatedscope.register import register_model
     def call_my_net(model_config, local_data):
         if model_config.type == "mynet":
             model = load_my_net(model_config, local_data)
             return model
     register_model("mynet", call_my_net)
  • Step3: put this .py file in the federatedscope/contrib/model/ folder, and set cfg.model.type = "mynet" to use it.

Also,  you can modify the source code to make the FederatedScope support your model. Please see federatedscope.core.auxiliaries.model_builder , and you can add an elif to skip Step2 and Step3 above.

Create a trainer

FederatedScope decouples the local learning process and details of FL communication and schedule, allowing users to freely customize the local learning algorithms via the Trainer. We recommend user build trainer by inheriting federatedscope.core.trainers.trainer.GeneralTrainer, for more details, please see Trainer. Similarly, we provide federatedscope.register.register_trainer to make your customized trainer available:

  • Step1: build your trainer by inheriting GeneralTrainer. Our GeneralTrainer already supports many different usages, for the advanced user, please see federatedscope.core.trainers.trainer.GeneralTrainer for more details.

     from federatedscope.core.trainers.trainer import GeneralTrainer
     class MyTrainer(GeneralTrainer):
  • Step2: register your trainer with a keyword, such as "mytrainer".

     from federatedscope.register import register_trainer
     def call_my_trainer(trainer_type):
         if trainer_type == 'mytrainer':
             trainer_builder = MyTrainer
             return trainer_builder
     register_trainer('mytrainer', call_my_trainer)
  • Step3: put this .py file in the federatedscope/contrib/trainer/ folder, and set cfg.trainer.type = "mytrainer" to use it.

Also,  you can modify the source code to make the FederatedScope support your model. Please see federatedscope/core/auxiliaries/ , and you can add an elif to skip Step2 and Step3 above.

Introduce more evaluation metrics

We provide a number of metrics to monitor the entire federal learning process. You just need to list the name of the metric you want in cfg.eval.metrics. We currently support metrics such as loss, accuracy, etc. (See federatedscope.core.monitors.metric_calculator for more details).

We also provide a function federatedscope.register.register_metric to make your evaluation metrics available with three steps:

  • Step1: build your metric (see federatedscope.core.trainers.context for more about ctx)

     def cal_my_metric(ctx, **kwargs):
         return MY_METRIC_VALUE
  • Step2: register your metric with a keyword, such as "mymetric".

     from federatedscope.register import register_metric
     def call_my_metric(types):
         if "mymetric" in types:
             metric_builder = cal_my_metric
             return "mymetric", metric_builder
     register_metric("mymetric", call_my_metric)
  • Step3: put this .py file in the federatedscope/contrib/metircs/ folder, and add "mymetric" to cfg.eval.metric activate it.

Specify your own configuration

Basic usage

FederatedScope provides an extended configuration system based on yacs. We leverage a two-level tree structure that consists of several internal dict-like containers to allow simple key-value access and management. For example,

cfg.backend = 'torch'  # level-1 configuration

cfg.federate = CN()  # level-2 configuration
cfg.federate.client_num = 0

The frequently-used APIs include

  • merge_from_file, merge_from_other_cfg and merge_from_list that load configs from a yaml file, another cfg instance or a list stores the keys and values.
  • Besides, we can use freeze to make the configs immutable and save the configs in a yaml file under the specified cfg.outdir.
  • Both these functions will trigger the configuration validness checking.
  • To modify a config node after calling freeze, we can call defrost.

As a start, our package will initialize a global_cfg instance by default, i.e.,

global_cfg = CN()

see more details in the file federatedscope/core/configs/ Users can clone and use their own configuration object as follows:

from federatedscope.core.configs.config import global_cfg

def main():

    init_cfg = global_cfg.clone()
    args = parse_args()


    # federated dataset might change the number of clients
    # thus, we allow the creation procedure of dataset to modify the global cfg object
    data, modified_cfg = get_data(config=init_cfg.clone())

    # do sth. further

Built-in configurations

We divide the configuration could be used in the FL process into several sub files such as cfg_fl_setting, cfg_fl_algo, cfg_model, cfg_training, cfg_evaluation, see more details in federatedscope/core/configs directory.

Customized configuration

To add new configuration, you need

  1. implement your own extend function extend_my_cfg(cfg):, e.g.,

    def extend_training_cfg(cfg):
        # ------------------------------------------------------------------------ #
        # Trainer related options
        # ------------------------------------------------------------------------ #
        cfg.trainer = CN()
        cfg.trainer.type = 'general'
        cfg.trainer.finetune = CN()
        cfg.trainer.finetune.steps = 0
        cfg.trainer.finetune.only_psn = True
        cfg.trainer.finetune.stepsize = 0.01
        # --------------- register corresponding check function ----------
  2. and implement your own config validation check function assert_my_cfg, e.g.,

    def assert_training_cfg(cfg):
        if cfg.backend not in ['torch', 'tensorflow']:
            raise ValueError(
                 "Value of 'cfg.backend' must be chosen from ['torch', 'tensorflow']."
  3. finally, register your own extended function, e.g.,

    from federatedscope.register import register_config
    register_config("fl_training", extend_training_cfg)

We recommend users put the new customized configuration in federatedscope/contrib/configs directory