fluke: federated learning utility framework for experimentation and research

fluke is a Python package that provides a framework for federated learning research. It is designed to be modular and extensible, allowing researchers to easily implement and test new federated learning algorithms. fluke provides a set of pre-implemented state-of-the-art federated learning algorithms that can be used as a starting point for research or as a benchmark for comparison.

Installation

fluke is a Python package that can be installed via pip. To install it, you can run the following command:

pip install fluke-fl

Warning

When installing fluke via pip, the opacus package will be installed as well. Unfortunately, this package is not compatible with Numpy 2.0.0 or higher and thus it will downgrade the Numpy installation. This hopefully should be fixed in the next release of opacus. In the meantime, after installing fluke, you should upgrade Numpy to the latest version by running the following command:

pip install --upgrade numpy

Run a federated algorithm

To run an algorithm in fluke you need to create two configuration files:

• EXP_CONFIG: the experiment configuration file (independent from the algorithm);
• ALG_CONFIG: the algorithm configuration file;

Then, you can run the following command:

fluke federation EXP_CONFIG ALG_CONFIG

You can find some examples of these files in the configs folder of the repository.

Example

Let say you want to run the classic FedAvg algorithm on the MNIST dataset. Then, using the configuration files exp.yaml and fedavg.yaml, you can run the following command:

fluke federation path_to_folder/exp.yaml path_to_folder/fedavg.yaml

where path_to_folder is the path to the folder containing the configuration files.

Documentation

The documentation for fluke can be found here. It contains detailed information about the package, including how to install it, how to run an experiment, and how to implement new algorithms.

Tutorials

Tutorials on how to use fluke can be found here. In the following, you can find some quick tutorials to get started with fluke:

• Getting started with fluke API
• Run your algorithm in fluke
• Use your own model with fluke
• Add your dataset and use it with fluke
• Add your custom evaluation metric in fluke

Contributing

If you have suggestions for how fluke could be improved, or want to report a bug, open an issue! We'd love all and any contributions.

For more, check out the Contributing Guide.

fluke @ ECML-PKDD 2024

fluke has been presented at the ECML-PKDD 2024 conference in the Workshop on Advancements in Federated Learning. The slides of the presentation are available here.

Citing fluke

fluke is a research tool, and we kindly ask you to cite it in your research papers if you use it. You can use the following BibTeX entry:

@misc{polato2024fluke,
      title={fluke: Federated Learning Utility frameworK for Experimentation and research}, 
      author={Mirko Polato},
      year={2024},
      eprint={2412.15728},
      archivePrefix={arXiv},
      primaryClass={cs.LG},
      url={https://arxiv.org/abs/2412.15728}, 
}

Authors and main contributors

• Mirko Polato - Idealization, Design, Development, Testing, Tutorial, and Documentation
• Roberto Esposito - Testing
• Samuele Fonio - Testing, Tutorial
• Edoardo Oglietti - Testing