Demo training task : MNIST

Overview

We are going to train a common model between three simulated clients on the classic MNIST dataset. The input of the model is a set of images of handwritten digits, and the model needs to determine which number between 0 and 9 each image corresponds to.

Setup

To be able to experiment with this tutorial:

• Clone the declearn repo, on the experimental branch:

git clone -b experimental git@gitlab.inria.fr:magnet/declearn/declearn2.git declearn

• Create a dedicated virtual environment.
• Install declearn in it from the local repo:

cd declearn && pip install .[websockets,tensorflow] && cd ..

In an FL experiment, we consider your data as a given. So before running the experiment below, split the MNIST data using :

declearn-split --folder "examples/mnist" --n_shards 3 

Contents

This script runs a FL experiment using MNIST. The folder is structured the following way:

mnist/
│   client.py  - set up and launch a federated-learning client
│   gen_ssl.py - generate self-signed ssl certificates
│   run.py     - launch both the server and clients in a single session
│   server.py  - set up and launch a federated-learning server
└─── data      - data split by client, created with the `split_data` util
└─── results   - saved results from training procedure

Run training routine

The simplest way to run the demo is to run it locally, using multiprocessing. For something closer to real life implementation, we also show a way to run the demo from different terminals or machines.

Locally, for testing and experimentation

To simply run the demo, use the bash command below. You can follow along the code in the hands-on section of the package documentation. For more details on what running the federated learning processes imply, see the last section.

cd
python run.py

Use :

python run.py  # note: python examples/heart-uci/run.py works as well

The run.py scripts collects the server and client routines defined under the server.py and client.py scripts, and runs them concurrently under a single python session using multiprocessing.

This is the easiest way to launch the demo, e.g. to see the effects of tweaking some learning parameters.

On separate terminals or machines

To run the examples from different terminals or machines, we first ensure data is appropriately distributed between machines, and the machines can communicate over network using SSL-encrypted communications. We give the code to simulate this on a single machine. We then sequentially run the server then the clients on separate terminals.

1. Set up SSL certificates:
   Start by creating a signed SSL certificate for the server and sharing the CA file with each and every clients. The CA may be self-signed.

   When testing locally, execute the gen_ssl.py script, to create a self-signed root CA and an SSL certificate for "localhost":

   python gen_ssl.py

   Note that in real-life applications, one would most likely use certificates certificates signed by a trusted certificate authority instead. Alternatively, declearn.test_utils.gen_ssl_certificates may be used to generate a self-signed CA and a signed certificate for a given domain name or IP address.

2. Run the server:
   Open a terminal and launch the server script for 1 to 4 clients, specifying the path to the SSL certificate and private key files, and network parameters. By default, things will run on the local host, looking for gen_ssl.py-created PEM files.

   E.g., to use 2 clients:

   python server.py 2  # use --help for details on network and SSL options

3. Run each client:
   Open a new terminal and launch the client script, specifying one of the dataset-provider names, and optionally the path the CA file and network parameters. By default, things will run on the local host, looking for a gen_ssl.py-created CA PEM file.

   E.g., to launch a client using the "cleveland" dataset:

   python client.py cleveland   # use --help for details on other options

Note that the server should be launched before the clients, otherwise the latter might fail to connect which would cause the script to terminate. A few seconds' delay is tolerable as clients will make multiple connection attempts prior to failing.

To run the example in a real-life setting, follow the instructions from this section, after having generated and shared the appropriate PEM files to set up SSL-encryption, and using additional script parameters to specify the network host and port to use.