README

Table of Content

About Document
Preparation
Start Work
Obtain Command-Line from GUI
Cleaning after Work
Forum
Reporting an Issue
Another Resources
About the License

About FL_PyTorch

FL_PyTorch is a software suite based on PyTorch to support efficient simulated Federated Learning experiments. This README.md file contains a description of how to prepare and install all needed things to start working with FL_PyTorch.

If you have already installed and prepared all the needed for a start but need assistance in the following steps, we recommend starting with TUTORIAL.md. We also provide automatic generated documentation for the code pdoc3 documentation located in "docs/generated" folder of the project.

Materials:

Video Presentation: Link-1, Link-2
The arXiv link for the paper: https://arxiv.org/abs/2202.03099
Original publication https://dl.acm.org/doi/abs/10.1145/3488659.3493775
FL_PyTorch in deepai.org
FL_PyTorch in researchgate.net
The slides, presentations, posters, and video with the project presentation are available in presentations.

Forum:

Slack Workspace: https://fl-pytorch.slack.com/
The invitation Link: https://join.slack.com/t/fl-pytorch/shared_invite/zt-1cjkjct9c-1wuFdrbVT4LcrAcjyj_gBw

Preparation

Optional IDE installation

Because FL_PyTorch during runtime is presented as a single process, it can be debugged using standard IDE for working with Python, like PyCharm IDE or Visual Studio Code.

So in case of need to debug source code with your changes, we recommend installing some IDE.

Install Conda environment

If you don't have conda package and environment manager you can install via the following steps for Linux OS:

wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
bash Miniconda3-latest-Linux-x86_64.sh -b
export PATH="${PATH}:~/miniconda3/bin"
~/miniconda3/bin/conda init bash && source ~/.bashrc && conda config --set auto_activate_base false

Prepare Conda environment

For refresh conda commands, you can look into official Conda cheat sheet.

Commands below will install all needed software as a part of an environment named fl, or you can use the name you prefer.

For Windows OS, Linux OS, please use the following commands to prepare the environment:

conda create -n fl python=3.9.1 -y
conda install -n fl pytorch"=1.10.0" torchvision numpy cudatoolkit"=11.1" h5py"=3.6.0" coloredlogs matplotlib psutil pyqt pytest pdoc3 wandb -c pytorch -c nvidia -c conda-forge -y

For Mac OS, CUDA is not currently available, please install PyTorch without CUDA support:

conda create -n fl python=3.9.1 -y
conda install -n fl pytorch"=1.10.0" torchvision numpy h5py"=3.6.0" coloredlogs matplotlib psutil pyqt pytest pdoc3 wandb -c pytorch -c nvidia -c conda-forge -y

Install packages via pip and virtualenv

Alternatively, instead of using conda, you can use a standard virtual environment in Python, which sometimes is used instead of Conda.

python -m pip install virtualenv
python -m venv flpip
source flpip/bin/activate
python -m pip install -r requirements.txt -f https://download.pytorch.org/whl/cu113/torch_stable.html

Tackling the possible problems in Windows OS

In case of any problems with installing PyTorch with CUDA support on a Windows workstation, follow the steps:

Install CUDA Toolkit (https://developer.nvidia.com/cuda-toolkit)
Install libCUDNN. You should download and unpack binaries, including all libraries, into the correspondent folders in the local directory with CUDA Toolkit. https://developer.nvidia.com/rdp/cudnn-download
Install a specific version of PyTorch with GPU support. For example, in the following way:

pip install torch==1.8.0+cu111 -f https://download.pytorch.org/whl/torch_stable.html

Ability to edit UI files for Qt5

In case you want to modify the user interface in the GUI tool via appending extra elements, please make one of the following:

Completely install Qt5 SDK,
Install the package with Qt5 tools only, which includes Qt Designer.

Linux

sudo apt-get install qttools5-dev-tools

Apt is a standard package management tool in the Ubuntu OS. If you have never worked with it but want to learn more, this is the best place with various how to: apt-get: How To.

MacOS

brew install qt5
brew install --cask qt-creator

Clone the project and create your branch

Install git client for your OS if it has not been installed, and clone the project:

# Clone project
git clone https://github.com/burlachenkok/fl_pytorch
cd fl_pytorch

# Create a personal branch
git branch my_work
git checkout my_work
git push --set-upstream origin my_work

There is nothing to compile or pre-build. The project is entirely has been written in Python programming language and does not contain any C++ or Cython parts in it explicitly.

Start Work

You have three options to start working.

1. Use GUI

Suppose you interconnect with a physical/remote computing device with a windows management system in such a way you can instantiate an application with a GUI interface. In that case, you can launch our simulation environment with Graphical User Interface(GUI) interface to experiment with optimization algorithms:

cd ./fl_pytorch/GUI 
python start.py

After that, you will observe the GUI tool. GUI tool allows launching several experiments simultaneously. The entry point to use the GUI tool launch script is located here fl_pytorch/GUI/start.py

2. You can not install VCN Server but want to use GUI

Another scenario may happen when you have access to the machine in a cluster with dedicated installed GPU/CPU compute resources. If you don't have root privileges to install the Windows Management system native for OS or provided as VNC systems like tigervncserver, we provide the ability to launch the GUI tool with the following commands:

cd ./fl_pytorch/fl_pytorch/GUI 
./start_with_vnc.sh

To change the listening port, please directly change listet_port parameter inside this bootstrap bash script. To connect remotely for an application instance, please use your host machine and VNC Viewer, e.g. RealVNC VNC Viewer. The booststrap script to launch VNC server is locating here: fl_pytorch/gui/start_with_vnc.sh.

3. Use the console command-line interface

The last option is to use the console interface for the experiment. Any research project has many options to select, and our project is not an exception to this rule, but we provide some assistance on that aspect. To observe options for the CLI program, please launch:

cd ./fl_pytorch/ 
python ./run.py --help

The entry point and the script to use during work with CUI are located here fl_pytorch/run.py.

Obtain Command Line from GUI

The first way is to specify command-line parameters explicitly via using python ./run.py ...
Second way is to launch GUI tool python start.py, select Extra->Low Window(F2), and press one of the command line icons. It will produce a command line for loaded and configured experiments in GUI.

Cleaning after Work

Remove Conda environment in case you are using Conda:

conda remove --name fl --all

And please remove all not need files in the filesystem, including logs, checkpoints, and saved experiments in binary format.

Forum

You are welcome to join the Slack workspace of project and ask questions.

https://fl-pytorch.slack.com/

Please use this invitation Link.

Reporting an Issue

For bug or feature request, please fill the ticket in the github repository.

About the License

The project is distributed under Apache 2.0 license.