Contribute Baselines

Do you have a new federated learning paper and want to add a new baseline to Flower? Or do you want to add an experiment to an existing baseline paper? Great, we really appreciate your contribution.

The goal of Flower Baselines is to reproduce experiments from popular papers to accelerate researchers by enabling faster comparisons to new strategies, datasets, models, and federated pipelines in general.

Before you start to work on a new baseline or experiment, please check the Flower Issues or Flower Pull Requests to see if someone else is already working on it. Please open a new issue if you are planning to work on a new baseline or experiment with a short description of the corresponding paper and the experiment you want to contribute. If you are proposing a brand new baseline, please indicate what experiments from the paper are planning to include.

Requirements

Contributing a new baseline is really easy. You only have to make sure that your federated learning experiments run with Flower, use Flower Datasets, and replicate the results of a paper. Preferably, the baselines make use of PyTorch, but other ML frameworks are also welcome. The baselines are expected to run in a machine with Ubuntu 22.04, but if yours runs also on macOS even better!

Add a new Flower Baseline

Note

The instructions below are a more verbose version of what’s present in the Baselines README on GitHub.

Let’s say you want to contribute the code of your most recent Federated Learning publication, FedAwesome. There are only three steps necessary to create a new FedAwesome Flower Baseline:

  1. Get the Flower source code on your machine

    1. Fork the Flower codebase: go to the Flower GitHub repo and fork the code (click the Fork button in the top-right corner and follow the instructions)

    2. Clone the (forked) Flower source code: git clone git@github.com:[your_github_username]/flower.git

  2. Create a new baseline using the template

    1. Create a new Python environment with Python 3.10 (we recommend doing this with pyenv)

    2. Install flower with: pip install flwr.

    3. Navigate to the baselines directory and run: flwr new fedawesome. When prompted, choose the option Flower Baseline.

    4. A new directory in baselines/fedawesome is created with the structure needed for a Flower Baseline.

    5. Follow the instructions in the README.md in your baseline directory.

    Tip

    At this point, your baseline contains source code showing how a simple PyTorch+CIFAR10 project can be built with Flower. You can run it directly by executing flwr run . from inside the directory of your baseline. Update the code with that needed to implement your baseline.

  3. Open a pull request

    1. Stage your changes: git add .

    2. Commit & push: git commit -m "Create new FedAwesome baseline" ; git push

    3. Open a pull request: go to your fork of the Flower codebase and create a pull request that targets the Flower main branch

    4. Interact with the Flower maintainers during the merging process and make adjustments to your code as needed.

Further reading:

Usability

Flower is known and loved for its usability. Therefore, make sure that your baseline or experiment can be executed with a single command after installing the baseline project:

# Install the baseline project
pip install -e .

# Run the baseline using default config
flwr run .

# Run the baseline overriding the config
flwr run . --run-config "lr=0.01 num-server-rounds=200"

We look forward to your contribution!