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

This example uses an in-script NumPy model update loop in the client code, using a simple 3x3 weight matrix to demonstrate aggregation behavior clearly.

See the full implementation in:

Client Code

The client training script follows the standard FL client pattern.

On the client side, the training workflow is as follows:

  1. Receive the model from the FL server

  2. Perform training on the received global model

  3. Send the updated model back to the FL server

Using NVFlare’s Client API, there are three essential methods to help achieve this workflow:

  • flare.init(): Initializes NVFlare Client API environment

  • flare.receive(): Receives model from the FL server

  • flare.send(): Sends the model to the FL server

The following code snippet highlights how these methods are used:

import nvflare.client as flare

flare.init()  # 1. Initialize NVFlare Client API
input_model = flare.receive()  # 2. Receive model from server
params = input_model.params  # 3. Extract model parameters

# Your training code here
new_params = train(params)

output_model = flare.FLModel(params=new_params)  # 4. Package results
flare.send(output_model)  # 5. Send updated model to server

For the complete implementation, see:

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.

See the job recipe implementation:

Model Input Options

For NumPy recipes, model can be a NumPy array or list. To resume from pre-trained weights:

recipe = NumpyFedAvgRecipe(
    model=None,  # Optional when using initial_ckpt
    initial_ckpt="/server/path/to/model.npy",  # Absolute path
    ...
)

Note

NumPy checkpoints contain the full model data, so initial_ckpt can be used without model.

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.

Previous Versions of this Example

For users on older versions of NVIDIA FLARE, this example had different names:

“Hello Scatter and Gather” (versions 2.0-2.4):

“Hello FedAvg NumPy” (versions 2.5-2.6):