Add FL example with nvflare

README.md

@@ -128,6 +128,9 @@ This is a simple example of training and deploying a MONAI network with [BentoML
 This uses the previous notebook's trained network to demonstrate deployment a web server using [Ray](https://docs.ray.io/en/master/serve/index.html#rayserve).
 
 **federated learning**
+#### [NVFlare](./federated_learning/nvflare)
+The example show how to train a federated learning model with [NVFlare](https://pypi.org/project/nvflare/) and the MONAI trainers.
+
 #### [Substra](./federated_learning/substra)
 The example show how to execute the 3d segmentation torch tutorial on a federated learning platform, Substra.
 

federated_learning/nvflare/1-Startup.ipynb

@@ -0,0 +1,255 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Introduction"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "In `Provision Package Preparation` step of the README, we created `audit.pkl` and `zip` files for all the provisioned parties (server, clients, and admins) in `expr_files/`. The zip files are encrypted and the passwords are saved in `audit.pkl`.\n",
+    "\n",
+    "In an experiment, you need to send decrypted folders to each site so they could run it on their system. Therefore, in this notebook, we would decrypt and send folders to all the provisioned parties. After running this notebook."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import shutil\n",
+    "from zipfile import ZipFile\n",
+    "import pickle\n",
+    "import os"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "['project.yml',\n",
+       " 'prerpare_expr_files.sh',\n",
+       " 'researcher@nvidia.com.zip',\n",
+       " 'download_dataset.py',\n",
+       " 'authz_config.json',\n",
+       " 'org1-b.zip',\n",
+       " 'researcher@org2.com.zip',\n",
+       " 'admin@nvidia.com.zip',\n",
+       " 'org1-a.zip',\n",
+       " 'audit.pkl',\n",
+       " 'server.zip',\n",
+       " 'researcher@org1.com.zip',\n",
+       " 'org2.zip',\n",
+       " 'it@org2.com.zip']"
+      ]
+     },
+     "execution_count": 2,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "os.listdir(\"expr_files/\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "In this example, `server.zip` will be used to create the server, `org1-a.zip` and `org1-b.zip` will be used to create two clients, and `admin@nvidia.com.zip` will be used to create an admin client to operate the FL experiment.\n",
+    "\n",
+    "First, unzip all the packages with the following code:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "metadata": {
+    "lines_to_next_cell": 2
+   },
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "demo_workspace  created!\n",
+      "unzip: server finished.\n",
+      "unzip: admin@nvidia.com finished.\n",
+      "unzip: researcher@nvidia.com finished.\n",
+      "unzip: researcher@org1.com finished.\n",
+      "unzip: researcher@org2.com finished.\n",
+      "unzip: it@org2.com finished.\n",
+      "unzip: org1-a finished.\n",
+      "unzip: org1-b finished.\n",
+      "unzip: org2 finished.\n"
+     ]
+    }
+   ],
+   "source": [
+    "startup_path = \"expr_files\"  # this is the path that contains `audit.pkl` and zip files\n",
+    "workspace = \"demo_workspace\"  # this is the folder that will be created to contain all experiment related files\n",
+    "\n",
+    "if not os.path.exists(workspace):\n",
+    "    os.makedirs(workspace)\n",
+    "    print(workspace, \" created!\")\n",
+    "\n",
+    "admin_name = \"admin@nvidia.com\"\n",
+    "client_name_1 = \"org1-a\"\n",
+    "client_name_2 = \"org1-b\"\n",
+    "server_name = \"server\"\n",
+    "\n",
+    "# access audit file get passwords for unzipping packages\n",
+    "with open(os.path.join(startup_path, \"audit.pkl\"), 'rb') as handle:\n",
+    "    audit_file = pickle.load(handle)\n",
+    "\n",
+    "proj_name = list(audit_file.keys())[0]\n",
+    "pw_key = \"zip_pw\"\n",
+    "server_folder_list = [\"server\"]\n",
+    "client_folder_list = [\"admin_clients\", \"fl_clients\"]\n",
+    "\n",
+    "folder_pwd_dict = {}\n",
+    "for obj in server_folder_list:\n",
+    "    unzip_pw = audit_file[proj_name][obj][pw_key]\n",
+    "    folder_pwd_dict[obj] = unzip_pw\n",
+    "\n",
+    "for obj in client_folder_list:\n",
+    "    obj_sub_dict = audit_file[proj_name][obj]\n",
+    "    for client in obj_sub_dict.keys():\n",
+    "        unzip_pw = obj_sub_dict[client][pw_key]\n",
+    "        folder_pwd_dict[client] = unzip_pw\n",
+    "\n",
+    "# unzip all folders into workspace\n",
+    "for name, pwd in folder_pwd_dict.items():\n",
+    "    zip_file_path = os.path.join(startup_path, name + \".zip\")\n",
+    "    dst_file_path = os.path.join(workspace, name)\n",
+    "    if not os.path.exists(dst_file_path):\n",
+    "        os.makedirs(dst_file_path)\n",
+    "    with ZipFile(zip_file_path, 'r') as zip_ref:\n",
+    "        zip_ref.extractall(path=dst_file_path, pwd=bytes(pwd, 'utf-8'))\n",
+    "    # change permissions\n",
+    "    if \".com\" in name:\n",
+    "        sub_file_list = [\"docker.sh\", \"fl_admin.sh\"]\n",
+    "    else:\n",
+    "        sub_file_list = [\"start.sh\", \"sub_start.sh\", \"docker.sh\"]\n",
+    "    for file in sub_file_list:\n",
+    "        os.chmod(os.path.join(dst_file_path, \"startup\", file), 0o755)\n",
+    "    print(\"unzip: {} finished.\".format(name))"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "['org1-b',\n",
+       " 'researcher@nvidia.com',\n",
+       " 'server',\n",
+       " 'admin@nvidia.com',\n",
+       " 'researcher@org2.com',\n",
+       " 'org1-a',\n",
+       " 'org2',\n",
+       " 'researcher@org1.com',\n",
+       " 'it@org2.com']"
+      ]
+     },
+     "execution_count": 4,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "# check the created workspace\n",
+    "os.listdir(workspace)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "With default settings, the experiment related config folder `spleen_example` should be copied into the `transfer` folder within the admin package:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "copied spleen_example into demo_workspace/admin@nvidia.com/transfer/.\n"
+     ]
+    }
+   ],
+   "source": [
+    "config_folder = \"spleen_example\"\n",
+    "\n",
+    "transfer_path = os.path.join(workspace, admin_name, \"transfer/\")\n",
+    "if not os.path.exists(transfer_path):\n",
+    "    os.makedirs(transfer_path)\n",
+    "shutil.copytree(config_folder, os.path.join(transfer_path, config_folder))\n",
+    "print(\"copied {} into {}.\".format(config_folder, transfer_path))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "So far, all required files are created in the workspace. Before starting the docker images, we can update the permissions for these files:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 6,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "!chown -R 1000:1000 demo_workspace/*"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Next Steps\n",
+    "\n",
+    "You have now finished unzipping the provisioning files and copying the experiment folder to the admin's transfer folder.\n",
+    "In the next notebook, [Server Startup Notebook](2-Server.ipynb), you will start the server container."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.8.5"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}