Hello NumPy

This example demonstrates how to use NVIDIA FLARE with NumPy to train a simple model using federated averaging (FedAvg). The complete example code can be found in the hello-numpy directory. It is recommended to create a virtual environment and run everything within a virtualenv.

NVIDIA FLARE Installation

For the complete installation instructions, see installation

pip install nvflare

Install the dependency

pip install -r requirements.txt

Code Structure

Get the example code from GitHub:

git clone https://github.com/NVIDIA/NVFlare.git

Navigate to the hello-numpy directory:

git switch <release branch>
cd examples/hello-world/hello-numpy

hello-numpy
    |
    |-- client.py             # client local training script
    |-- model.py              # model definition
    |-- job.py                # job recipe that defines client and server configurations
    |-- requirements.txt      # dependencies

Data

This example uses a simplified synthetic dataset. Each client performs basic operations on a 3x3 weight matrix, adding a small delta to each weight during training. This approach allows you to clearly observe the federated learning aggregation process without the complexity of real data loading and preprocessing.

In a real FL experiment, each client would have their own dataset used for their local training. Here for simplicity’s sake, we use synthetic data that allows you to clearly see and understand the federated learning aggregation process.

Model

The SimpleNumpyModel class implements a basic neural network model using NumPy arrays. The model represents a simple 3x3 weight matrix that can be trained through federated learning. The model starts with fixed weights [[1, 2, 3], [4, 5, 6], [7, 8, 9]] and provides methods for training and evaluation.

The model implementation is located in model.py.

Client Code

Notice the training code follows the standard FL client pattern. The only difference is that we added a few lines to receive and send data to the server.

Server Code

In federated averaging, the server code is responsible for aggregating model updates from clients. The workflow pattern is similar to scatter-gather. In this example, we will directly use the default federated averaging algorithm provided by NVFlare. The FedAvg class is defined in nvflare.app_common.workflows.fedavg.FedAvg. There is no need to define a customized server code for this example.

Job Recipe Code

Job Recipe contains the client.py and built-in fedavg algorithm.

Run FL Job

This section provides the command to execute the federated learning job using the job recipe defined above. Run this command in your terminal.

Note

The model starts with weights [[1, 2, 3], [4, 5, 6], [7, 8, 9]] and each client adds 1 to each weight during training. After aggregation, you should see the weights increase by 1 each round, demonstrating the federated learning process.

Command to execute the FL job

Use the following command in your terminal to start the job with the specified number of rounds and number of clients.

python job.py --num_rounds 3 --n_clients 2

The full source code for this exercise can be found in examples/hello-world/hello-numpy.