From be9f481c1b1874d174430e80f822d176232dd5b9 Mon Sep 17 00:00:00 2001 From: Isaac Yang Date: Wed, 1 May 2024 09:57:11 -0700 Subject: [PATCH 01/15] Add information about dig (bind9-dnsutils) in the document --- docs/real_world_fl/cloud_deployment.rst | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/real_world_fl/cloud_deployment.rst b/docs/real_world_fl/cloud_deployment.rst index 0a7cca8e7a..26bb86b7b8 100644 --- a/docs/real_world_fl/cloud_deployment.rst +++ b/docs/real_world_fl/cloud_deployment.rst @@ -44,11 +44,11 @@ To run NVFlare dashboard on Azure, run: .. note:: - The script also requires sshpass and jq. Both can be installed on Ubuntu, with: + The script also requires sshpass, dig and jq. All can be installed on Ubuntu, with: .. code-block:: shell - sudo apt install sshpass jq + sudo apt install sshpass bind9-dnsutils jq Users only need to enter an email address and press Enter. This user needs to remember this email and the temporary password that will be provided, as this is the login credentials for the NVFLARE Dashboard once the Dashboard is up and running. @@ -101,11 +101,11 @@ To run NVFlare dashboard on AWS, run: .. note:: - The script also requires sshpass and jq. They can be installed on Ubuntu, with: + The script also requires sshpass, dig and jq. They can be installed on Ubuntu, with: .. code-block:: shell - sudo apt install sshpass jq + sudo apt install sshpass bind9-dnsutils jq AWS manages authentications via AWS access_key and access_secret, you will need to have these credentials before you can start creating AWS infrastructure. @@ -128,9 +128,10 @@ You can accept all default values by pressing ENTER. .. code-block:: none - This script requires az (Azure CLI), sshpass and jq. Now checking if they are installed. + This script requires az (Azure CLI), sshpass dig and jq. Now checking if they are installed. Checking if az exists. => found Checking if sshpass exists. => found + Checking if dig exists. => found Checking if jq exists. => found Cloud VM image, press ENTER to accept default Canonical:0001-com-ubuntu-server-focal:20_04-lts-gen2:latest: Cloud VM size, press ENTER to accept default Standard_B2ms: @@ -190,9 +191,10 @@ You can accept all default values by pressing ENTER. .. code-block:: - This script requires aws (AWS CLI), sshpass and jq. Now checking if they are installed. + This script requires aws (AWS CLI), sshpass, dig and jq. Now checking if they are installed. Checking if aws exists. => found Checking if sshpass exists. => found + Checking if dig exists. => found Checking if jq exists. => found If the server requires additional dependencies, please copy the requirements.txt to /home/nvflare/workspace/aws/nvflareserver/startup. Press ENTER when it's done or no additional dependencies. From fc739504a048464f2859e0ce6b693d1933215e68 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yuan-Ting=20Hsieh=20=28=E8=AC=9D=E6=B2=85=E5=BB=B7=29?= Date: Sun, 5 May 2024 18:05:37 -0700 Subject: [PATCH 02/15] Update monai readme to remove logging.conf (#2552) --- .../monai/examples/spleen_ct_segmentation_local/README.md | 7 +++++++ .../monai/examples/spleen_ct_segmentation_sim/README.md | 6 ++++++ 2 files changed, 13 insertions(+) diff --git a/integration/monai/examples/spleen_ct_segmentation_local/README.md b/integration/monai/examples/spleen_ct_segmentation_local/README.md index bd7d481316..a1ce642581 100644 --- a/integration/monai/examples/spleen_ct_segmentation_local/README.md +++ b/integration/monai/examples/spleen_ct_segmentation_local/README.md @@ -67,6 +67,13 @@ The final folder structure under `JOB_NAME` will be: └── meta.json ``` + +The logging.conf inside the bundle will overwrite the logger behavior, so let's remove it: + +``` +rm ./${JOB_NAME}/app/config/spleen_ct_segmentation/configs/logging.conf +``` + ## 2. Download the data Download the spleen CT data from the [MSD challenge](http://medicaldecathlon.com/) and update data path. diff --git a/integration/monai/examples/spleen_ct_segmentation_sim/README.md b/integration/monai/examples/spleen_ct_segmentation_sim/README.md index e7b8dd03ed..397c49761f 100644 --- a/integration/monai/examples/spleen_ct_segmentation_sim/README.md +++ b/integration/monai/examples/spleen_ct_segmentation_sim/README.md @@ -54,6 +54,12 @@ The final folder structure under `JOB_NAME` will be: └── meta.json ``` +The logging.conf inside the bundle will overwrite the logger behavior, so let's remove it: + +``` +rm ./${JOB_NAME}/app/config/spleen_ct_segmentation/configs/logging.conf +``` + ### 2. Download the data Download the spleen CT data from the [MSD challenge](http://medicaldecathlon.com/) and update data path. From 30e42d5836dc8e2f0aff82506d2b44f9efcf2ee1 Mon Sep 17 00:00:00 2001 From: Holger Roth <6304754+holgerroth@users.noreply.github.com> Date: Mon, 6 May 2024 11:02:44 -0400 Subject: [PATCH 03/15] MONAI mednist example (#2532) * add monai notebook * add training script * update example * update notebook * use job template * call init later * swith back * add gitignore * update notebooks * add readmes * send received model to GPU * use monai tb stats handler * formatting --- integration/monai/examples/README.md | 4 + integration/monai/examples/mednist/.gitignore | 3 + integration/monai/examples/mednist/README.md | 18 ++ .../mednist/code/monai_mednist_train.py | 169 +++++++++++ .../monai/examples/mednist/figs/mlflow.png | Bin 0 -> 146306 bytes .../monai/examples/mednist/figs/tb.png | Bin 0 -> 98409 bytes .../fedavg_mednist/config_fed_client.conf | 67 ++++ .../fedavg_mednist/config_fed_server.conf | 94 ++++++ .../job_templates/fedavg_mednist/info.conf | 5 + .../job_templates/fedavg_mednist/info.md | 11 + .../job_templates/fedavg_mednist/meta.conf | 10 + .../monai/examples/mednist/monai_101.ipynb | 286 ++++++++++++++++++ .../monai/examples/mednist/monai_101_fl.ipynb | 233 ++++++++++++++ .../monai/examples/mednist/requirements.txt | 3 + nvflare/client/tracking.py | 4 + 15 files changed, 907 insertions(+) create mode 100644 integration/monai/examples/mednist/.gitignore create mode 100644 integration/monai/examples/mednist/README.md create mode 100644 integration/monai/examples/mednist/code/monai_mednist_train.py create mode 100644 integration/monai/examples/mednist/figs/mlflow.png create mode 100644 integration/monai/examples/mednist/figs/tb.png create mode 100644 integration/monai/examples/mednist/job_templates/fedavg_mednist/config_fed_client.conf create mode 100644 integration/monai/examples/mednist/job_templates/fedavg_mednist/config_fed_server.conf create mode 100644 integration/monai/examples/mednist/job_templates/fedavg_mednist/info.conf create mode 100644 integration/monai/examples/mednist/job_templates/fedavg_mednist/info.md create mode 100644 integration/monai/examples/mednist/job_templates/fedavg_mednist/meta.conf create mode 100644 integration/monai/examples/mednist/monai_101.ipynb create mode 100644 integration/monai/examples/mednist/monai_101_fl.ipynb create mode 100644 integration/monai/examples/mednist/requirements.txt diff --git a/integration/monai/examples/README.md b/integration/monai/examples/README.md index 6a92e363d4..60fa3a0005 100644 --- a/integration/monai/examples/README.md +++ b/integration/monai/examples/README.md @@ -1,5 +1,9 @@ # Examples of MONAI-NVFlare Integration +### [Converting MONAI Code to a Federated Learning Setting](./mednist/README.md) +A tutorial to show how simple it can be to run an end-to-end classification pipeline with MONAI +and deploy it in a federated learning setting using NVFlare. + ### [Simulated Federated Learning for 3D spleen CT segmentation](./spleen_ct_segmentation_sim/README.md) An example of using [NVIDIA FLARE](https://nvflare.readthedocs.io/en/main/index.html) to train a medical image analysis model using federated averaging ([FedAvg](https://arxiv.org/abs/1602.05629)) diff --git a/integration/monai/examples/mednist/.gitignore b/integration/monai/examples/mednist/.gitignore new file mode 100644 index 0000000000..c964d5fc95 --- /dev/null +++ b/integration/monai/examples/mednist/.gitignore @@ -0,0 +1,3 @@ +# nvflare artifacts for this example +fedavg_workspace +jobs \ No newline at end of file diff --git a/integration/monai/examples/mednist/README.md b/integration/monai/examples/mednist/README.md new file mode 100644 index 0000000000..25693d35fc --- /dev/null +++ b/integration/monai/examples/mednist/README.md @@ -0,0 +1,18 @@ +## Converting MONAI Code to a Federated Learning Setting + +In this tutorial, we will introduce how simple it can be to run an end-to-end classification pipeline with MONAI +and deploy it in a federated learning setting using NVFlare. + +### 1. Standalone training with MONAI +[monai_101.ipynb](./monai_101.ipynb) is based on the [MONAI 101 classification tutorial](https://github.com/Project-MONAI/tutorials/blob/main/2d_classification/monai_101.ipynb) and shows each step required in only a few lines of code, including + +- Dataset download +- Data pre-processing +- Define a DenseNet-121 and run training +- Check the results on test dataset + +### 2. Federated learning with MONAI +[monai_101_fl.ipynb](./monai_101_fl.ipynb) shows how we can simply put the code introduced above into a Python script and convert it to running in an FL scenario using NVFlare. + +To achieve this, we utilize the [`FedAvg`](https://arxiv.org/abs/1602.05629) algorithm and NVFlare's [Client +API](https://nvflare.readthedocs.io/en/main/programming_guide/execution_api_type.html#client-api). diff --git a/integration/monai/examples/mednist/code/monai_mednist_train.py b/integration/monai/examples/mednist/code/monai_mednist_train.py new file mode 100644 index 0000000000..86ab525642 --- /dev/null +++ b/integration/monai/examples/mednist/code/monai_mednist_train.py @@ -0,0 +1,169 @@ +# Copyright (c) 2024, NVIDIA CORPORATION. All rights reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +# MONAI Example adopted from https://github.com/Project-MONAI/tutorials/blob/main/2d_classification/monai_101.ipynb +# +# Copyright (c) MONAI Consortium +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# http://www.apache.org/licenses/LICENSE-2.0 +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +import logging +import os +import sys +import tempfile +from pathlib import Path + +import numpy as np +import torch +from monai.apps import MedNISTDataset +from monai.config import print_config +from monai.data import DataLoader +from monai.engines import SupervisedTrainer +from monai.handlers import StatsHandler, TensorBoardStatsHandler +from monai.inferers import SimpleInferer +from monai.networks import eval_mode +from monai.networks.nets import densenet121 +from monai.transforms import Compose, EnsureChannelFirstD, LoadImageD, ScaleIntensityD + +# (1) import nvflare client API +import nvflare.client as flare + +# (optional) metrics +from nvflare.client.tracking import SummaryWriter + +print_config() + + +def main(): + # (2) initializes NVFlare client API + flare.init() + + # Setup data directory + directory = os.environ.get("MONAI_DATA_DIRECTORY") + root_dir = tempfile.mkdtemp() if directory is None else directory + print(root_dir) + + # Use MONAI transforms to preprocess data + transform = Compose( + [ + LoadImageD(keys="image", image_only=True), + EnsureChannelFirstD(keys="image"), + ScaleIntensityD(keys="image"), + ] + ) + + # Prepare datasets using MONAI Apps + dataset = MedNISTDataset(root_dir=root_dir, transform=transform, section="training", download=True) + + # Define a network and a supervised trainer + + # If available, we use GPU to speed things up. + DEVICE = "cuda" if torch.cuda.is_available() else "cpu" + + max_epochs = 1 # rather than 5 epochs, we run 5 FL rounds with 1 local epoch each. + model = densenet121(spatial_dims=2, in_channels=1, out_channels=6).to(DEVICE) + + train_loader = DataLoader(dataset, batch_size=512, shuffle=True, num_workers=4) + + logging.basicConfig(stream=sys.stdout, level=logging.INFO) + trainer = SupervisedTrainer( + device=torch.device(DEVICE), + max_epochs=max_epochs, + train_data_loader=train_loader, + network=model, + optimizer=torch.optim.Adam(model.parameters(), lr=1e-5), + loss_function=torch.nn.CrossEntropyLoss(), + inferer=SimpleInferer(), + train_handlers=StatsHandler(), + ) + + # TensorBoardStatsHandler plots loss at every iteration and plots metrics at every epoch, same as StatsHandler + summary_writer = SummaryWriter() + train_tensorboard_stats_handler = TensorBoardStatsHandler(summary_writer=summary_writer) + train_tensorboard_stats_handler.attach(trainer) + + # (optional) calculate total steps + steps = max_epochs * len(train_loader) + # Run the training + + while flare.is_running(): + # (3) receives FLModel from NVFlare + input_model = flare.receive() + print(f"current_round={input_model.current_round}") + + # (4) loads model from NVFlare and sends it to GPU + trainer.network.load_state_dict(input_model.params) + trainer.network.to(DEVICE) + + trainer.run() + + # (5) wraps evaluation logic into a method to re-use for + # evaluation on both trained and received model + def evaluate(input_weights): + # Create model for evaluation + eval_model = densenet121(spatial_dims=2, in_channels=1, out_channels=6).to(DEVICE) + eval_model.load_state_dict(input_weights) + + # Check the prediction on the test dataset + dataset_dir = Path(root_dir, "MedNIST") + class_names = sorted(f"{x.name}" for x in dataset_dir.iterdir() if x.is_dir()) + testdata = MedNISTDataset( + root_dir=root_dir, transform=transform, section="test", download=False, runtime_cache=True + ) + correct = 0 + total = 0 + max_items_to_print = 10 + _print = 0 + with eval_mode(eval_model): + for item in DataLoader(testdata, batch_size=512, num_workers=0): # changed to do batch processing + prob = np.array(eval_model(item["image"].to(DEVICE)).detach().to("cpu")) + pred = [class_names[p] for p in prob.argmax(axis=1)] + gt = item["class_name"] + # changed the logic a bit from tutorial to compute accuracy on full test set + # but only print for some. + for _gt, _pred in zip(gt, pred): + if _print < max_items_to_print: + print(f"Class prediction is {_pred}. Ground-truth: {_gt}") + _print += 1 + + # compute accuracy + total += 1 + correct += float(_pred == _gt) + + print(f"Accuracy of the network on the {total} test images: {100 * correct // total} %") + return correct / total + + # (6) evaluate on received model for model selection + accuracy = evaluate(input_model.params) + summary_writer.add_scalar(tag="global_model_accuracy", scalar=accuracy, global_step=input_model.current_round) + + # (7) construct trained FL model + output_model = flare.FLModel( + params=trainer.network.cpu().state_dict(), + metrics={"accuracy": accuracy}, + meta={"NUM_STEPS_CURRENT_ROUND": steps}, + ) + # (8) send model back to NVFlare + flare.send(output_model) + + +if __name__ == "__main__": + main() diff --git a/integration/monai/examples/mednist/figs/mlflow.png b/integration/monai/examples/mednist/figs/mlflow.png new file mode 100644 index 0000000000000000000000000000000000000000..662e3637f65bb834ef8d78e0cd912d185e21b4af GIT binary patch literal 146306 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 UgR|+F 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�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

gY|&jkidxoqL9t59$+GKrUxQFn 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 literal 0 HcmV?d00001 diff --git a/integration/monai/examples/mednist/figs/tb.png b/integration/monai/examples/mednist/figs/tb.png new file mode 100644 index 0000000000000000000000000000000000000000..329838ca2e12b301a4621ff74fe9bf9304bb6b0e GIT binary patch literal 98409 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

AED_o7u$XBkY$bDC-;aQ70};R0ww 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 U8MS@FM*=?g)phQas9L@F7wobcrvLx| literal 0 HcmV?d00001 diff --git a/integration/monai/examples/mednist/job_templates/fedavg_mednist/config_fed_client.conf b/integration/monai/examples/mednist/job_templates/fedavg_mednist/config_fed_client.conf new file mode 100644 index 0000000000..47c9d32c80 --- /dev/null +++ b/integration/monai/examples/mednist/job_templates/fedavg_mednist/config_fed_client.conf @@ -0,0 +1,67 @@ +{ + # version of the configuration + format_version = 2 + + # This is the application script which will be invoked. Client can replace this script with user's own training script. + app_script = "monai_mednist_train.py" + + # Additional arguments needed by the training code. For example, in lightning, these can be --trainer.batch_size=xxx. + # Additional arguments needed by the training code. For example, in lightning, these can be --trainer.batch_size=xxx. + app_config = "" + + # Client Computing Executors. + executors = [ + { + # tasks the executors are defined to handle + tasks = ["train"] + + # This particular executor + executor { + + path = "nvflare.app_opt.pt.in_process_client_api_executor.PTInProcessClientAPIExecutor" + args { + task_script_path = "{app_script}" + task_script_args = "{app_config}" + + # if the transfer_type is FULL, then it will be sent directly + # if the transfer_type is DIFF, then we will calculate the + # difference VS received parameters and send the difference + params_transfer_type = "DIFF" + + # if train_with_evaluation is true, the executor will expect + # the custom code need to send back both the trained parameters and the evaluation metric + # otherwise only trained parameters are expected + train_with_evaluation = true + + # time interval in seconds. Time interval to wait before check if the local task has submitted the result + # if the local task takes long time, you can increase this interval to larger number + # uncomment to overwrite the default, default is 0.5 seconds + result_pull_interval = 0.5 + + # time interval in seconds. Time interval to wait before check if the trainig code has log metric (such as + # Tensorboard log, MLFlow log or Weights & Biases logs. The result will be streanmed to the server side + # then to the corresponding tracking system + # if the log is not needed, you can set this to a larger number + # uncomment to overwrite the default, default is None, which disable the log streaming feature. + log_pull_interval = 0.1 + + } + } + } + ], + + # this defined an array of task data filters. If provided, it will control the data from server controller to client executor + task_data_filters = [] + + # this defined an array of task result filters. If provided, it will control the result from client executor to server controller + task_result_filters = [] + + # define this component that will help relay local metrics log to FL server. + components = [ + { + "id": "event_to_fed", + "name": "ConvertToFedEvent", + "args": {"events_to_convert": ["analytix_log_stats"], "fed_event_prefix": "fed."} + } + ] +} diff --git a/integration/monai/examples/mednist/job_templates/fedavg_mednist/config_fed_server.conf b/integration/monai/examples/mednist/job_templates/fedavg_mednist/config_fed_server.conf new file mode 100644 index 0000000000..e0336318a4 --- /dev/null +++ b/integration/monai/examples/mednist/job_templates/fedavg_mednist/config_fed_server.conf @@ -0,0 +1,94 @@ +{ + # version of the configuration + format_version = 2 + + # task data filter: if filters are provided, the filter will filter the data flow out of server to client. + task_data_filters =[] + + # task result filter: if filters are provided, the filter will filter the result flow out of client to server. + task_result_filters = [] + + # This assumes that there will be a "net.py" file with class name "Net". + # If your model code is not in "net.py" and class name is not "Net", please modify here + model_class_path = "monai.networks.nets.densenet121" + + # densenet arguments + spatial_dims = 2 + in_channels = 1 + out_channels = 6 + + # workflows: Array of workflows the control the Federated Learning workflow lifecycle. + # One can specify multiple workflows. The NVFLARE will run them in the order specified. + workflows = [ + { + # 1st workflow" + id = "scatter_and_gather" + + # name = ScatterAndGather, path is the class path of the ScatterAndGather controller. + path = "nvflare.app_common.workflows.fedavg.FedAvg" + args { + # argument of the ScatterAndGather class. + # min number of clients required for ScatterAndGather controller to move to the next round + # during the workflow cycle. The controller will wait until the min_clients returned from clients + # before move to the next step. + min_clients = 2 + + # number of global round of the training. + num_rounds = 5 + } + } + ] + + # List of components used in the server side workflow. + components = [ + { + # This is the persistence component used in above workflow. + # PTFileModelPersistor is a Pytorch persistor which save/read the model to/from file. + + id = "persistor" + path = "nvflare.app_opt.pt.file_model_persistor.PTFileModelPersistor" + + # the persitor class take model class as argument + # This imply that the model is initialized from the server-side. + # The initialized model will be broadcast to all the clients to start the training. + args.model.path = "{model_class_path}" + args.model.args.spatial_dims = "{spatial_dims}" + args.model.args.in_channels = "{in_channels}" + args.model.args.out_channels = "{out_channels}" + }, + { + # This component is not directly used in Workflow. + # it select the best model based on the incoming global validation metrics. + id = "model_selector" + path = "nvflare.app_common.widgets.intime_model_selector.IntimeModelSelector" + # need to make sure this "key_metric" match what server side received + args.key_metric = "accuracy" + }, + { + id = "receiver" + path = "nvflare.app_opt.tracking.tb.tb_receiver.TBAnalyticsReceiver" + args.events = ["fed.analytix_log_stats"] + }, + { + id = "mlflow_receiver" + path = "nvflare.app_opt.tracking.mlflow.mlflow_receiver.MLflowReceiver" + args { + # tracking_uri = "http://0.0.0.0:5000" + tracking_uri = "" + kwargs { + experiment_name = "nvflare-fedavg-mednist-experiment" + run_name = "nvflare-fedavg-mednist-with-mlflow" + experiment_tags { + "mlflow.note.content": "## **NVFlare FedAvg MONAI experiment with MLflow**" + } + run_tags { + "mlflow.note.content" = "## Federated Experiment tracking with MONAI and MLflow \n###" + } + } + artifact_location = "artifacts" + events = ["fed.analytix_log_stats"] + } + } + ] + +} diff --git a/integration/monai/examples/mednist/job_templates/fedavg_mednist/info.conf b/integration/monai/examples/mednist/job_templates/fedavg_mednist/info.conf new file mode 100644 index 0000000000..123dcb6539 --- /dev/null +++ b/integration/monai/examples/mednist/job_templates/fedavg_mednist/info.conf @@ -0,0 +1,5 @@ +{ + description = "FedAvg using MONAI with in_process Client API" + execution_api_type = "client_api" + controller_type = "server" +} \ No newline at end of file diff --git a/integration/monai/examples/mednist/job_templates/fedavg_mednist/info.md b/integration/monai/examples/mednist/job_templates/fedavg_mednist/info.md new file mode 100644 index 0000000000..a35c68ec2d --- /dev/null +++ b/integration/monai/examples/mednist/job_templates/fedavg_mednist/info.md @@ -0,0 +1,11 @@ +# Job Template Information Card + +## fedavg_mednist + name = "fedavg_mednist" + description = "FedAvg with Scatter and Gather Workflow using pytorch with in_process Client API" + class_name = "ScatterAndGather" + controller_type = "server" + executor_type = "in_process_client_api_executor" + contributor = "NVIDIA" + init_publish_date = "2024-02-8" + last_updated_date = "2024-02-8" # yyyy-mm-dd diff --git a/integration/monai/examples/mednist/job_templates/fedavg_mednist/meta.conf b/integration/monai/examples/mednist/job_templates/fedavg_mednist/meta.conf new file mode 100644 index 0000000000..43a7e6a2a3 --- /dev/null +++ b/integration/monai/examples/mednist/job_templates/fedavg_mednist/meta.conf @@ -0,0 +1,10 @@ +{ + name = "fedavg_mednist" + resource_spec = {} + deploy_map { + # change deploy map as needed. + app = ["@ALL"] + } + min_clients = 2 + mandatory_clients = [] +} diff --git a/integration/monai/examples/mednist/monai_101.ipynb b/integration/monai/examples/mednist/monai_101.ipynb new file mode 100644 index 0000000000..0a8b42ba69 --- /dev/null +++ b/integration/monai/examples/mednist/monai_101.ipynb @@ -0,0 +1,286 @@ +{ + "cells": [ + { + "attachments": {}, + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Copyright (c) 2024, NVIDIA CORPORATION. All rights reserved.\n", + "\n", + "Licensed under the Apache License, Version 2.0 (the \"License\");\n", + "you may not use this file except in compliance with the License.\n", + "You may obtain a copy of the License at\n", + "\n", + " http://www.apache.org/licenses/LICENSE-2.0\n", + "\n", + "Unless required by applicable law or agreed to in writing, software\n", + "distributed under the License is distributed on an \"AS IS\" BASIS,\n", + "WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n", + "See the License for the specific language governing permissions and\n", + "limitations under the License.\n", + "\n", + "MONAI Example adopted from https://github.com/Project-MONAI/tutorials/blob/main/2d_classification/monai_101.ipynb\n", + "\n", + "Copyright (c) MONAI Consortium \n", + "Licensed under the Apache License, Version 2.0 (the \"License\"); \n", + "you may not use this file except in compliance with the License. \n", + "You may obtain a copy of the License at \n", + "    http://www.apache.org/licenses/LICENSE-2.0 \n", + "Unless required by applicable law or agreed to in writing, software \n", + "distributed under the License is distributed on an \"AS IS\" BASIS, \n", + "WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. \n", + "See the License for the specific language governing permissions and \n", + "limitations under the License.\n", + "\n", + "# MONAI 101 tutorial\n", + "\n", + "In this tutorial, we will introduce how simple it can be to run an end-to-end classification pipeline with MONAI.\n", + "\n", + "These steps will be included in this tutorial, and each of them will take only a few lines of code:\n", + "- Dataset download\n", + "- Data pre-processing\n", + "- Define a DenseNet-121 and run training\n", + "- Check the results on test dataset\n", + "\n", + "This tutorial will use about 7GB of GPU memory and 10 minutes to run.\n", + "\n", + "[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/NVIDIA/NVFlare/blob/main/integration/monai/examples/mednist/monai_101.ipynb)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Setup environment" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "!python -c \"import monai\" || pip install -q \"monai-weekly[ignite, tqdm]\"" + ] + }, + { + "attachments": {}, + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Setup imports" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "import logging\n", + "import numpy as np\n", + "import os\n", + "from pathlib import Path\n", + "import sys\n", + "import tempfile\n", + "import torch\n", + "\n", + "from monai.apps import MedNISTDataset\n", + "from monai.config import print_config\n", + "from monai.data import DataLoader\n", + "from monai.engines import SupervisedTrainer\n", + "from monai.handlers import StatsHandler\n", + "from monai.inferers import SimpleInferer\n", + "from monai.networks import eval_mode\n", + "from monai.networks.nets import densenet121\n", + "from monai.transforms import LoadImageD, EnsureChannelFirstD, ScaleIntensityD, Compose\n", + "\n", + "print_config()" + ] + }, + { + "attachments": {}, + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Setup data directory\n", + "\n", + "You can specify a directory with the `MONAI_DATA_DIRECTORY` environment variable. \n", + "This allows you to save results and reuse downloads. \n", + "If not specified a temporary directory will be used." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "directory = os.environ.get(\"MONAI_DATA_DIRECTORY\")\n", + "root_dir = tempfile.mkdtemp() if directory is None else directory\n", + "print(root_dir)" + ] + }, + { + "attachments": {}, + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Use MONAI transforms to preprocess data\n", + "\n", + "Medical images require specialized methods for I/O, preprocessing, and augmentation.\n", + "They often follow specific formats, are handled with specific protocols, and the data arrays are often high-dimensional.\n", + "\n", + "In this example, we will perform image loading, data format verification, and intensity scaling with three `monai.transforms` listed below, and compose a pipeline ready to be used in next steps." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "transform = Compose(\n", + " [\n", + " LoadImageD(keys=\"image\", image_only=True),\n", + " EnsureChannelFirstD(keys=\"image\"),\n", + " ScaleIntensityD(keys=\"image\"),\n", + " ]\n", + ")" + ] + }, + { + "attachments": {}, + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Prepare datasets using MONAI Apps\n", + "\n", + "We use `MedNISTDataset` in MONAI Apps to download a dataset to the specified directory and perform the pre-processing steps in the `monai.transforms` compose.\n", + "\n", + "The MedNIST dataset was gathered from several sets from [TCIA](https://wiki.cancerimagingarchive.net/display/Public/Data+Usage+Policies+and+Restrictions),\n", + "[the RSNA Bone Age Challenge](http://rsnachallenges.cloudapp.net/competitions/4),\n", + "and [the NIH Chest X-ray dataset](https://cloud.google.com/healthcare/docs/resources/public-datasets/nih-chest).\n", + "\n", + "The dataset is kindly made available by [Dr. Bradley J. Erickson M.D., Ph.D.](https://www.mayo.edu/research/labs/radiology-informatics/overview) (Department of Radiology, Mayo Clinic)\n", + "under the Creative Commons [CC BY-SA 4.0 license](https://creativecommons.org/licenses/by-sa/4.0/).\n", + "\n", + "If you use the MedNIST dataset, please acknowledge the source. " + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "dataset = MedNISTDataset(root_dir=root_dir, transform=transform, section=\"training\", download=True)" + ] + }, + { + "attachments": {}, + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Define a network and a supervised trainer\n", + "\n", + "To train a model that can perform the classification task, we will use the DenseNet-121 which is known for its performance on the ImageNet dataset.\n", + "\n", + "For a typical supervised training workflow, MONAI provides `SupervisedTrainer` to define the hyper-parameters." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# If available, we use GPU to speed things up.\n", + "DEVICE = \"cuda\" if torch.cuda.is_available() else \"cpu\"\n", + "\n", + "max_epochs = 5\n", + "model = densenet121(spatial_dims=2, in_channels=1, out_channels=6).to(DEVICE)\n", + "\n", + "logging.basicConfig(stream=sys.stdout, level=logging.INFO)\n", + "trainer = SupervisedTrainer(\n", + " device=torch.device(DEVICE),\n", + " max_epochs=max_epochs,\n", + " train_data_loader=DataLoader(dataset, batch_size=512, shuffle=True, num_workers=4),\n", + " network=model,\n", + " optimizer=torch.optim.Adam(model.parameters(), lr=1e-5),\n", + " loss_function=torch.nn.CrossEntropyLoss(),\n", + " inferer=SimpleInferer(),\n", + " train_handlers=StatsHandler(),\n", + ")" + ] + }, + { + "attachments": {}, + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Run the training" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "trainer.run()" + ] + }, + { + "attachments": {}, + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Check the prediction on the test dataset" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "dataset_dir = Path(root_dir, \"MedNIST\")\n", + "class_names = sorted(f\"{x.name}\" for x in dataset_dir.iterdir() if x.is_dir())\n", + "testdata = MedNISTDataset(root_dir=root_dir, transform=transform, section=\"test\", download=False, runtime_cache=True)\n", + "\n", + "max_items_to_print = 10\n", + "with eval_mode(model):\n", + " for item in DataLoader(testdata, batch_size=1, num_workers=0):\n", + " prob = np.array(model(item[\"image\"].to(DEVICE)).detach().to(\"cpu\"))[0]\n", + " pred = class_names[prob.argmax()]\n", + " gt = item[\"class_name\"][0]\n", + " print(f\"Class prediction is {pred}. Ground-truth: {gt}\")\n", + " max_items_to_print -= 1\n", + " if max_items_to_print == 0:\n", + " break" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "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.10.12" + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/integration/monai/examples/mednist/monai_101_fl.ipynb b/integration/monai/examples/mednist/monai_101_fl.ipynb new file mode 100644 index 0000000000..e63db20b01 --- /dev/null +++ b/integration/monai/examples/mednist/monai_101_fl.ipynb @@ -0,0 +1,233 @@ +{ + "cells": [ + { + "attachments": {}, + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Copyright (c) 2024, NVIDIA CORPORATION. All rights reserved.\n", + "\n", + "Licensed under the Apache License, Version 2.0 (the \"License\");\n", + "you may not use this file except in compliance with the License.\n", + "You may obtain a copy of the License at\n", + "\n", + " http://www.apache.org/licenses/LICENSE-2.0\n", + "\n", + "Unless required by applicable law or agreed to in writing, software\n", + "distributed under the License is distributed on an \"AS IS\" BASIS,\n", + "WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n", + "See the License for the specific language governing permissions and\n", + "limitations under the License.\n", + "\n", + "MONAI Example adopted from https://github.com/Project-MONAI/tutorials/blob/main/2d_classification/monai_101.ipynb\n", + "\n", + "Copyright (c) MONAI Consortium \n", + "Licensed under the Apache License, Version 2.0 (the \"License\"); \n", + "you may not use this file except in compliance with the License. \n", + "You may obtain a copy of the License at \n", + "    http://www.apache.org/licenses/LICENSE-2.0 \n", + "Unless required by applicable law or agreed to in writing, software \n", + "distributed under the License is distributed on an \"AS IS\" BASIS, \n", + "WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. \n", + "See the License for the specific language governing permissions and \n", + "limitations under the License.\n", + "\n", + "# MONAI 101 tutorial with Federated Learning\n", + "\n", + "In this example, the **server** uses the [`FedAvg`](https://github.com/NVIDIA/NVFlare/blob/main/nvflare/app_common/workflows/fedavg.py) controller, which performs the following steps:\n", + "1. Initialize the global model. This is achieved through the method `load_model()`\n", + " from the base class\n", + " [`ModelController`](https://github.com/NVIDIA/NVFlare/blob/fa4d00f76848fe4eb356dcde417c136047eeab36/nvflare/app_common/workflows/model_controller.py#L292),\n", + " which relies on the\n", + " [`ModelPersistor`](https://nvflare.readthedocs.io/en/main/glossary.html#persistor). \n", + "2. During each training round, the global model will be sent to the\n", + " list of participating clients to perform a training task. This is\n", + " done using the\n", + " [`send_model()`](https://github.com/NVIDIA/NVFlare/blob/d6827bca96d332adb3402ceceb4b67e876146067/nvflare/app_common/workflows/model_controller.py#L99)\n", + " method under the hood from the `ModelController` base class. Once\n", + " the clients finish their local training, results will be collected\n", + " and sent back to the server as an [`FLModel`](https://nvflare.readthedocs.io/en/main/programming_guide/fl_model.html#flmodel)s.\n", + "3. Results sent by clients will be aggregated based on the\n", + " [`WeightedAggregationHelper`](https://github.com/NVIDIA/NVFlare/blob/fa4d00f76848fe4eb356dcde417c136047eeab36/nvflare/app_common/aggregators/weighted_aggregation_helper.py#L20),\n", + " which weighs the contribution from each client based on the number\n", + " of local training samples. The aggregated updates are\n", + " returned as a new `FLModel`.\n", + "5. After getting the aggregated results, the global model is [updated](https://github.com/NVIDIA/NVFlare/blob/724140e7dc9081eca7a912a818817f89aadfef5d/nvflare/app_common/workflows/fedavg.py#L63).\n", + "6. The last step is to save the updated global model, again through\n", + " the [`ModelPersistor`](https://nvflare.readthedocs.io/en/main/glossary.html#persistor).\n", + "\n", + "The **clients** implement the local training logic using NVFlare's [Client\n", + "API](https://nvflare.readthedocs.io/en/main/programming_guide/execution_api_type.html#client-api)\n", + "[here](./code/monai_mednist_train.py). The Client API\n", + "allows the user to add minimum `nvflare`-specific codes to turn a typical\n", + "centralized training script to a federated client-side local training\n", + "script.\n", + "1. During local training, each client receives a copy of the global\n", + " model sent by the server using `flare.receive()` API. The received\n", + " global model is an instance of `FLModel`.\n", + "2. A local validation is first performed, where validation metrics\n", + " (accuracy and precision) are streamed to server using the\n", + " [`SummaryWriter`](https://nvflare.readthedocs.io/en/main/apidocs/nvflare.client.tracking.html#nvflare.client.tracking.SummaryWriter). The\n", + " streamed metrics can be loaded and visualized using [TensorBoard](https://www.tensorflow.org/tensorboard) or [MLflow](https://mlflow.org/).\n", + "3. Then, each client performs local training as in the non-federated training [notebook](./monai_101.ipynb). At the end of each FL round, each client then sends the computed results (always in\n", + " `FLModel` format) to the server for aggregation, using the `flare.send()`\n", + " API.\n", + "\n", + "This tutorial will use about 7GB of GPU memory and 10 minutes to run.\n", + "\n", + "[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/NVIDIA/NVFlare/blob/main/integration/monai/examples/mednist/monai_101_fl.ipynb)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Setup environment" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "scrolled": true + }, + "outputs": [], + "source": [ + "!python -c \"import monai\" || pip install -q \"monai-weekly[ignite, tqdm]\"\n", + "!pip install -r requirements.txt" + ] + }, + { + "attachments": {}, + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Configure the NVFlare job templates folder" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "!nvflare config -jt ./job_templates\n", + "!nvflare job list_templates" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Create job folder\n", + "\n", + "We will use the in-process client API, we prepared a job template ([fedavg_mednist](./job_templates/fedavg_mednist)) based on the [sag_pt in_proc job template](../../../job_templates/sag_pt_in_proc) and run the following command to create the job.\n", + "The `-f` option allows us to customize some options in the template, such as specifying the training script to be used on the clients and initial arguments to the global model, as well as the number of FL rounds." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "!nvflare job create -force -j ./jobs/fedavg_mednist -w fedavg_mednist -sd ./code/. \\\n", + " -f config_fed_client.conf app_script=monai_mednist_train.py \\\n", + " -f config_fed_server.conf model_class_path=monai.networks.nets.densenet121 \\\n", + " -f config_fed_server.conf spatial_dims=2 \\\n", + " -f config_fed_server.conf in_channels=1 \\\n", + " -f config_fed_server.conf out_channels=6 \\\n", + " -f config_fed_server.conf num_rounds=5" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Run FL experiment\n", + "Then we can run it using the NVFlare Simulator for `n=2` clients on `t=2` threads in parallel:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "!nvflare simulator -n 2 -t 2 ./jobs/fedavg_mednist -w fedavg_workspace" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Visualize the streamed metrics\n", + "The accuracy metrics streamed to the server during training can be visualized using either\n", + "\n", + "1. TensorBoard" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "!tensorboard --logdir fedavg_workspace/server/simulate_job/app_server/simulate_job/tb_events" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "\"TensorBoard" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "or\n", + "\n", + "2. MLflow" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "!mlflow ui --backend-store-uri fedavg_workspace/server/simulate_job/app_server/mlruns" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "\"MLflow" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "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.10.12" + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/integration/monai/examples/mednist/requirements.txt b/integration/monai/examples/mednist/requirements.txt new file mode 100644 index 0000000000..00e550082a --- /dev/null +++ b/integration/monai/examples/mednist/requirements.txt @@ -0,0 +1,3 @@ +nvflare-nightly @ git+https://github.com/NVIDIA/NVFlare.git@main +tensorboard +mlflow \ No newline at end of file diff --git a/nvflare/client/tracking.py b/nvflare/client/tracking.py index c04b797037..e2ba7e66b7 100644 --- a/nvflare/client/tracking.py +++ b/nvflare/client/tracking.py @@ -64,6 +64,10 @@ def add_scalars(self, tag: str, scalars: dict, global_step: Optional[int] = None **kwargs, ) + def flush(self): + """Skip flushing which would normally write the event file to disk""" + pass + class WandBWriter: """WandBWriter mimics the usage of weights and biases. From a761a1bd96bd6f61ced41ee35b0b473ff4f946ed Mon Sep 17 00:00:00 2001 From: Isaac Yang Date: Wed, 1 May 2024 09:33:08 -0700 Subject: [PATCH 04/15] Improve AWS cloud launch script --- nvflare/dashboard/cli.py | 2 + nvflare/lighter/impl/aws_template.yml | 93 +++++++++++++++++++++--- nvflare/lighter/impl/azure_template.yml | 24 +++--- nvflare/lighter/impl/master_template.yml | 14 +++- 4 files changed, 107 insertions(+), 26 deletions(-) diff --git a/nvflare/dashboard/cli.py b/nvflare/dashboard/cli.py index 58e45dbe10..a3dbea95d8 100644 --- a/nvflare/dashboard/cli.py +++ b/nvflare/dashboard/cli.py @@ -138,6 +138,8 @@ def stop(): def cloud(args): lighter_folder = os.path.dirname(utils.__file__) template = utils.load_yaml(os.path.join(lighter_folder, "impl", "master_template.yml")) + template.update(utils.load_yaml(os.path.join(lighter_folder, "impl", "aws_template.yml"))) + template.update(utils.load_yaml(os.path.join(lighter_folder, "impl", "azure_template.yml"))) tplt = tplt_utils.Template(template) cwd = os.getcwd() csp = args.cloud diff --git a/nvflare/lighter/impl/aws_template.yml b/nvflare/lighter/impl/aws_template.yml index 8ba14d6f2d..0b0e1e9092 100644 --- a/nvflare/lighter/impl/aws_template.yml +++ b/nvflare/lighter/impl/aws_template.yml @@ -12,6 +12,13 @@ aws_start_sh: | check_binary dig "Please install it first." check_binary jq "Please install it first." + if [ -z ${vpc_id+x} ] + then + using_default_vpc=true + else + using_default_vpc=false + fi + if [ -z ${image_name+x} ] then container=false @@ -19,7 +26,7 @@ aws_start_sh: | container=true fi - if [ $container = true ] + if [ $container == "true" ] then AMI_IMAGE=ami-06b8d5099f3a8d79d EC2_TYPE=t2.xlarge @@ -40,7 +47,7 @@ aws_start_sh: | fi - if [ $useDefault = true ] + if [ $useDefault == true ] then while true do @@ -55,12 +62,31 @@ aws_start_sh: | done fi - if [ $container = false ] + if [ $container == false ] then echo "If the {~~type~~} requires additional dependencies, please copy the requirements.txt to ${DIR}." prompt ans "Press ENTER when it's done or no additional dependencies. " fi + # Check if default VPC exists + if [ $using_default_vpc == true ] + then + echo "Checking if default VPC exists" + found_default_vpc=$(aws ec2 describe-vpcs | jq '.Vpcs[] | select(.IsDefault == true)') + if [ -z "${found_default_vpc}" ] + then + echo "No default VPC found. Please create one before running this script with the following command." + echo "aws ec2 create-default-vpc" + echo "or specify your own vpc and subnet with --vpc-id and --subnet-id" + exit + else + echo "Default VPC found" + fi + else + echo "Please check the vpc-id $vpc_id and subnet-id $subnet_id are correct and they support EC2 with public IP and internet gateway with proper routing." + echo "This script will use the above info to create EC2 instance." + fi + cd $DIR/.. # Generate key pair @@ -74,7 +100,12 @@ aws_start_sh: | # Generate Security Group # Try not reusing existing security group because we have to modify it for our own need. - sg_id=$(aws ec2 create-security-group --group-name $SECURITY_GROUP --description "NVFlare security group" | jq -r .GroupId) + if [ $using_default_vpc == true ] + then + sg_id=$(aws ec2 create-security-group --group-name $SECURITY_GROUP --description "NVFlare security group" | jq -r .GroupId) + else + sg_id=$(aws ec2 create-security-group --group-name $SECURITY_GROUP --description "NVFlare security group" --vpc-id $vpc_id | jq -r .GroupId) + fi report_status "$?" "creating security group" my_public_ip=$(dig +short myip.opendns.com @resolver1.opendns.com) if [ "$?" -eq 0 ] && [[ "$my_public_ip" =~ ^(([1-9]?[0-9]|1[0-9][0-9]|2([0-4][0-9]|5[0-5]))\.){3}([1-9]?[0-9]|1[0-9][0-9]|2([0-4][0-9]|5[0-5]))$ ]] @@ -91,7 +122,12 @@ aws_start_sh: | echo "Creating VM at region $REGION, may take a few minutes." - aws ec2 run-instances --region $REGION --image-id $AMI_IMAGE --count 1 --instance-type $EC2_TYPE --key-name $KEY_PAIR --security-group-ids $sg_id > vm_create.json + if [ $using_default_vpc == true ] + then + aws ec2 run-instances --region $REGION --image-id $AMI_IMAGE --count 1 --instance-type $EC2_TYPE --key-name $KEY_PAIR --security-group-ids $sg_id > vm_create.json + else + aws ec2 run-instances --region $REGION --image-id $AMI_IMAGE --count 1 --instance-type $EC2_TYPE --key-name $KEY_PAIR --security-group-ids $sg_id --subnet-id $subnet_id > vm_create.json + fi report_status "$?" "creating VM" instance_id=$(jq -r .Instances[0].InstanceId vm_create.json) @@ -109,7 +145,7 @@ aws_start_sh: | scp -q -i $KEY_FILE -r -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null $PWD $DEST report_status "$?" "copying startup kits to VM" - if [ $container = true ] + if [ $container == true ] then echo "Launching container with docker option ${DOCKER_OPTION}." ssh -f -i $KEY_FILE -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null ${DEST_SITE} \ @@ -154,6 +190,13 @@ aws_start_dsb_sh: | check_binary dig "Please install it first." check_binary jq "Please install it first." + if [ -z ${vpc_id+x} ] + then + using_default_vpc=true + else + using_default_vpc=false + fi + echo "One initial user will be created when starting dashboard." echo "Please enter the email address for this user." read email @@ -169,9 +212,33 @@ aws_start_dsb_sh: | report_status "$?" "creating key pair" chmod 400 $KEY_FILE - # Generate Security Group + # Check if default VPC exists + if [ $using_default_vpc == true ] + then + echo "Checking if default VPC exists" + found_default_vpc=$(aws ec2 describe-vpcs | jq '.Vpcs[] | select(.IsDefault == true)') + if [ -z "${found_default_vpc}" ] + then + echo "No default VPC found. Please create one before running this script with the following command." + echo "aws ec2 create-default-vpc" + echo "or specify your own vpc and subnet with --vpc-id and --subnet-id" + exit + else + echo "Default VPC found" + fi + else + echo "Please check the vpc-id $vpc_id and subnet-id $subnet_id are correct and they support EC2 with public IP and internet gateway with proper routing." + echo "This script will use the above info to create EC2 instance." + fi - sg_id=$(aws ec2 create-security-group --group-name $SECURITY_GROUP --description "NVFlare security group" | jq -r .GroupId) + # Generate Security Group + # Try not reusing existing security group because we have to modify it for our own need. + if [ $using_default_vpc == true ] + then + sg_id=$(aws ec2 create-security-group --group-name $SECURITY_GROUP --description "NVFlare security group" | jq -r .GroupId) + else + sg_id=$(aws ec2 create-security-group --group-name $SECURITY_GROUP --description "NVFlare security group" --vpc-id $vpc_id | jq -r .GroupId) + fi report_status "$?" "creating security group" echo "Security group id: ${sg_id}" my_public_ip=$(dig +short myip.opendns.com @resolver1.opendns.com) @@ -188,8 +255,12 @@ aws_start_dsb_sh: | # Start provisioning echo "Creating VM at region $REGION, may take a few minutes." - - aws ec2 run-instances --region $REGION --image-id $AMI_IMAGE --count 1 --instance-type $EC2_TYPE --key-name $KEY_PAIR --security-group-ids $sg_id > vm_create.json + if [ $using_default_vpc == true ] + then + aws ec2 run-instances --region $REGION --image-id $AMI_IMAGE --count 1 --instance-type $EC2_TYPE --key-name $KEY_PAIR --security-group-ids $sg_id > vm_create.json + else + aws ec2 run-instances --region $REGION --image-id $AMI_IMAGE --count 1 --instance-type $EC2_TYPE --key-name $KEY_PAIR --security-group-ids $sg_id --subnet-id $subnet_id > vm_create.json + fi report_status "$?" "creating VM" instance_id=$(jq -r .Instances[0].InstanceId vm_create.json) @@ -246,7 +317,7 @@ aws_start_dsb_sh: | python3 -m nvflare.dashboard.cli --start -f ${DEST_FOLDER} --cred ${credential} {~~START_OPT~~}" > /tmp/dashboard.json echo "Dashboard url is running at IP address ${IP_ADDRESS}, listening to port 443." - if [ "$secure" = true ] + if [ "$secure" == true ] then echo "URL is https://${IP_ADDRESS}" else diff --git a/nvflare/lighter/impl/azure_template.yml b/nvflare/lighter/impl/azure_template.yml index 9c42a10cf3..73fb7255fa 100644 --- a/nvflare/lighter/impl/azure_template.yml +++ b/nvflare/lighter/impl/azure_template.yml @@ -39,7 +39,7 @@ azure_start_svr_header_sh: | container=true fi - if [ $container = true ] + if [ $container == true ] then VM_IMAGE=Canonical:0001-com-ubuntu-server-focal:20_04-lts-gen2:latest VM_SIZE=Standard_D8s_v3 @@ -55,20 +55,20 @@ azure_start_svr_header_sh: | useDefault=false . $config_file report_status "$?" "Loading config file" - if [ $self_dns = false ] && [ $DERIVED_LOCATION != $LOCATION ] + if [ $self_dns == false ] && [ $DERIVED_LOCATION != $LOCATION ] then echo "Server name implies LOCATION=${DERIVED_LOCATION} but the config file specifies LOCATION=${LOCATION}. Unable to continue provisioning." exit 1 fi fi - if [ $useDefault = true ] + if [ $useDefault == true ] then while true do prompt VM_IMAGE "Cloud VM image, press ENTER to accept default ${VM_IMAGE}: " prompt VM_SIZE "Cloud VM size, press ENTER to accept default ${VM_SIZE}: " - if [ $self_dns = true ] + if [ $self_dns == true ] then prompt LOCATION "Cloud location, press ENTER to accept default ${LOCATION}: " prompt ans "VM image = ${VM_IMAGE}, VM size = ${VM_SIZE}, location = ${LOCATION}, OK? (Y/n) " @@ -79,7 +79,7 @@ azure_start_svr_header_sh: | done fi - if [ $container = false ] + if [ $container == false ] then echo "If the client requires additional dependencies, please copy the requirements.txt to ${DIR}." prompt ans "Press ENTER when it's done or no additional dependencies. " @@ -95,7 +95,7 @@ azure_start_svr_header_sh: | echo "Creating Resource Group $RESOURCE_GROUP at Location $LOCATION" az group create --output none --name $RESOURCE_GROUP --location $LOCATION report_status "$?" "creating resource group" - elif [ $useDefault = true ] + elif [ $useDefault == true ] then report_status "1" "Only one NVFL server VM and its resource group is allowed. $RESOURCE_GROUP exists and thus creating duplicate resource group" else @@ -103,7 +103,7 @@ azure_start_svr_header_sh: | fi echo "Creating Virtual Machine, will take a few minutes" - if [ $self_dns = true ] + if [ $self_dns == true ] then az vm create \ --output json \ @@ -200,7 +200,7 @@ azure_start_cln_header_sh: | container=true fi - if [ $container = true ] + if [ $container == true ] then VM_IMAGE=Canonical:0001-com-ubuntu-server-focal:20_04-lts-gen2:latest VM_SIZE=Standard_D8s_v3 @@ -217,7 +217,7 @@ azure_start_cln_header_sh: | report_status "$?" "Loading config file" fi - if [ $useDefault = true ] + if [ $useDefault == true ] then while true do @@ -229,7 +229,7 @@ azure_start_cln_header_sh: | done fi - if [ $container = false ] + if [ $container == false ] then echo "If the client requires additional dependencies, please copy the requirements.txt to ${DIR}." prompt ans "Press ENTER when it's done or no additional dependencies. " @@ -298,7 +298,7 @@ azure_start_common_sh: | cd $DIR/.. && sshpass -p $PASSWORD scp -r -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null $PWD $DEST report_status "$?" "copying startup kits to VM" - if [ $container = true ] + if [ $container == true ] then echo "Installing and lauching container in $VM_NAME, may take a few minutes." scripts=$(cat << 'EOF' @@ -505,7 +505,7 @@ azure_start_dsb_sh: | # credential=$(jq -r .value[0].message /tmp/dashboard.json | grep "Project admin") # echo "The VM was created with user: ${ADMIN_USERNAME} and password: ${PASSWORD}" - if [ "$secure" = true ] + if [ "$secure" == true ] then echo "URL is https://${IP_ADDRESS}" else diff --git a/nvflare/lighter/impl/master_template.yml b/nvflare/lighter/impl/master_template.yml index 24342030ba..a2c6572aae 100644 --- a/nvflare/lighter/impl/master_template.yml +++ b/nvflare/lighter/impl/master_template.yml @@ -339,7 +339,7 @@ start_cln_sh: | shift done - if [ $doCloud = true ] + if [ $doCloud == true ] then case $csp in azure) @@ -367,7 +367,7 @@ start_svr_sh: | key="$1" case $key in --cloud) - if [ $ha_mode = false ] + if [ $ha_mode == false ] then doCloud=true csp=$2 @@ -381,7 +381,7 @@ start_svr_sh: | shift done - if [ $doCloud = true ] + if [ $doCloud == true ] then case $csp in azure) @@ -819,6 +819,14 @@ cloud_script_header: | image_name=$2 shift ;; + --vpc-id) + vpc_id=$2 + shift + ;; + --subnet-id) + subnet_id=$2 + shift + ;; esac shift done From 1df954f1270a073f4f7c3172070b0a919f3e3f5a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yuan-Ting=20Hsieh=20=28=E8=AC=9D=E6=B2=85=E5=BB=B7=29?= Date: Tue, 7 May 2024 15:43:06 -0700 Subject: [PATCH 05/15] Add in process client api tests (#2549) * Add in process client api tests * Fix headers * Fix comments --- .../data/apps/cyclic/app/custom/__init__.py | 2 +- .../cyclic/app/custom/tf2_model_persistor.py | 2 +- .../data/apps/cyclic/app/custom/tf2_net.py | 2 +- .../data/apps/cyclic/app/custom/trainer.py | 2 +- .../app/custom/__init__.py | 2 +- .../app/custom/np_trainer.py | 2 +- .../apps/sag_exception/app/custom/__init__.py | 2 +- .../app/custom/exception_trainer.py | 2 +- .../apps/tb_streaming/app/custom/__init__.py | 2 +- .../app/custom/custom_controller.py | 2 +- .../app/custom/custom_executor.py | 2 +- .../app/custom/cifar10_structured_fl.py | 2 +- .../data/jobs/decorator/app/custom/net.py | 2 +- .../app/config/config_fed_client.conf | 37 +++++ .../app/config/config_fed_server.conf | 62 ++++++++ .../app/custom/cifar10_structured_fl.py | 139 ++++++++++++++++++ .../decorator_in_process/app/custom/net.py | 37 +++++ .../data/jobs/decorator_in_process/meta.conf | 11 ++ .../app/custom/cifar10_lightning_fl.py | 2 +- .../data/jobs/lightning/app/custom/lit_net.py | 2 +- .../data/jobs/lightning/app/custom/net.py | 2 +- .../app/config/config_fed_client.conf | 37 +++++ .../app/config/config_fed_server.conf | 62 ++++++++ .../app/custom/cifar10_lightning_fl.py | 105 +++++++++++++ .../app/custom/lit_net.py | 72 +++++++++ .../lightning_in_process/app/custom/net.py | 37 +++++ .../data/jobs/lightning_in_process/meta.conf | 11 ++ .../app/config/config_fed_client.conf | 37 +++++ .../app/config/config_fed_server.conf | 88 +++++++++++ .../app/custom/cifar10_fl.py | 137 +++++++++++++++++ .../app/custom/net.py | 37 +++++ .../jobs/pt_client_api_in_process/meta.conf | 11 ++ .../standalone_job/client_api.yml | 62 +++++++- tests/unit_test/app_opt/__init__.py | 2 +- tests/unit_test/fuel/utils/fobs/datum_test.py | 2 +- 35 files changed, 998 insertions(+), 20 deletions(-) create mode 100644 tests/integration_test/data/jobs/decorator_in_process/app/config/config_fed_client.conf create mode 100644 tests/integration_test/data/jobs/decorator_in_process/app/config/config_fed_server.conf create mode 100644 tests/integration_test/data/jobs/decorator_in_process/app/custom/cifar10_structured_fl.py create mode 100644 tests/integration_test/data/jobs/decorator_in_process/app/custom/net.py create mode 100644 tests/integration_test/data/jobs/decorator_in_process/meta.conf create mode 100644 tests/integration_test/data/jobs/lightning_in_process/app/config/config_fed_client.conf create mode 100644 tests/integration_test/data/jobs/lightning_in_process/app/config/config_fed_server.conf create mode 100644 tests/integration_test/data/jobs/lightning_in_process/app/custom/cifar10_lightning_fl.py create mode 100644 tests/integration_test/data/jobs/lightning_in_process/app/custom/lit_net.py create mode 100644 tests/integration_test/data/jobs/lightning_in_process/app/custom/net.py create mode 100644 tests/integration_test/data/jobs/lightning_in_process/meta.conf create mode 100644 tests/integration_test/data/jobs/pt_client_api_in_process/app/config/config_fed_client.conf create mode 100644 tests/integration_test/data/jobs/pt_client_api_in_process/app/config/config_fed_server.conf create mode 100644 tests/integration_test/data/jobs/pt_client_api_in_process/app/custom/cifar10_fl.py create mode 100644 tests/integration_test/data/jobs/pt_client_api_in_process/app/custom/net.py create mode 100644 tests/integration_test/data/jobs/pt_client_api_in_process/meta.conf diff --git a/tests/integration_test/data/apps/cyclic/app/custom/__init__.py b/tests/integration_test/data/apps/cyclic/app/custom/__init__.py index 2db92b2574..4fc50543f1 100644 --- a/tests/integration_test/data/apps/cyclic/app/custom/__init__.py +++ b/tests/integration_test/data/apps/cyclic/app/custom/__init__.py @@ -1,4 +1,4 @@ -# Copyright (c) 2022, NVIDIA CORPORATION. All rights reserved. +# Copyright (c) 2023, NVIDIA CORPORATION. All rights reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. diff --git a/tests/integration_test/data/apps/cyclic/app/custom/tf2_model_persistor.py b/tests/integration_test/data/apps/cyclic/app/custom/tf2_model_persistor.py index f2bcbf1d1a..33c5a7c119 100644 --- a/tests/integration_test/data/apps/cyclic/app/custom/tf2_model_persistor.py +++ b/tests/integration_test/data/apps/cyclic/app/custom/tf2_model_persistor.py @@ -1,4 +1,4 @@ -# Copyright (c) 2022, NVIDIA CORPORATION. All rights reserved. +# Copyright (c) 2023, NVIDIA CORPORATION. All rights reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. diff --git a/tests/integration_test/data/apps/cyclic/app/custom/tf2_net.py b/tests/integration_test/data/apps/cyclic/app/custom/tf2_net.py index 2ccb46862f..46766284c2 100644 --- a/tests/integration_test/data/apps/cyclic/app/custom/tf2_net.py +++ b/tests/integration_test/data/apps/cyclic/app/custom/tf2_net.py @@ -1,4 +1,4 @@ -# Copyright (c) 2022, NVIDIA CORPORATION. All rights reserved. +# Copyright (c) 2023, NVIDIA CORPORATION. All rights reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. diff --git a/tests/integration_test/data/apps/cyclic/app/custom/trainer.py b/tests/integration_test/data/apps/cyclic/app/custom/trainer.py index 46013fa46e..720f795198 100644 --- a/tests/integration_test/data/apps/cyclic/app/custom/trainer.py +++ b/tests/integration_test/data/apps/cyclic/app/custom/trainer.py @@ -1,4 +1,4 @@ -# Copyright (c) 2022, NVIDIA CORPORATION. All rights reserved. +# Copyright (c) 2023, NVIDIA CORPORATION. All rights reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. diff --git a/tests/integration_test/data/apps/np_sag_weights_diff/app/custom/__init__.py b/tests/integration_test/data/apps/np_sag_weights_diff/app/custom/__init__.py index 2db92b2574..4fc50543f1 100644 --- a/tests/integration_test/data/apps/np_sag_weights_diff/app/custom/__init__.py +++ b/tests/integration_test/data/apps/np_sag_weights_diff/app/custom/__init__.py @@ -1,4 +1,4 @@ -# Copyright (c) 2022, NVIDIA CORPORATION. All rights reserved. +# Copyright (c) 2023, NVIDIA CORPORATION. All rights reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. diff --git a/tests/integration_test/data/apps/np_sag_weights_diff/app/custom/np_trainer.py b/tests/integration_test/data/apps/np_sag_weights_diff/app/custom/np_trainer.py index 0b7e860213..8b754271aa 100755 --- a/tests/integration_test/data/apps/np_sag_weights_diff/app/custom/np_trainer.py +++ b/tests/integration_test/data/apps/np_sag_weights_diff/app/custom/np_trainer.py @@ -1,4 +1,4 @@ -# Copyright (c) 2022, NVIDIA CORPORATION. All rights reserved. +# Copyright (c) 2023, NVIDIA CORPORATION. All rights reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. diff --git a/tests/integration_test/data/apps/sag_exception/app/custom/__init__.py b/tests/integration_test/data/apps/sag_exception/app/custom/__init__.py index 2db92b2574..4fc50543f1 100644 --- a/tests/integration_test/data/apps/sag_exception/app/custom/__init__.py +++ b/tests/integration_test/data/apps/sag_exception/app/custom/__init__.py @@ -1,4 +1,4 @@ -# Copyright (c) 2022, NVIDIA CORPORATION. All rights reserved. +# Copyright (c) 2023, NVIDIA CORPORATION. All rights reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. diff --git a/tests/integration_test/data/apps/sag_exception/app/custom/exception_trainer.py b/tests/integration_test/data/apps/sag_exception/app/custom/exception_trainer.py index d8273ac7f7..ca471871be 100755 --- a/tests/integration_test/data/apps/sag_exception/app/custom/exception_trainer.py +++ b/tests/integration_test/data/apps/sag_exception/app/custom/exception_trainer.py @@ -1,4 +1,4 @@ -# Copyright (c) 2022, NVIDIA CORPORATION. All rights reserved. +# Copyright (c) 2023, NVIDIA CORPORATION. All rights reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. diff --git a/tests/integration_test/data/apps/tb_streaming/app/custom/__init__.py b/tests/integration_test/data/apps/tb_streaming/app/custom/__init__.py index 2db92b2574..4fc50543f1 100755 --- a/tests/integration_test/data/apps/tb_streaming/app/custom/__init__.py +++ b/tests/integration_test/data/apps/tb_streaming/app/custom/__init__.py @@ -1,4 +1,4 @@ -# Copyright (c) 2022, NVIDIA CORPORATION. All rights reserved. +# Copyright (c) 2023, NVIDIA CORPORATION. All rights reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. diff --git a/tests/integration_test/data/apps/tb_streaming/app/custom/custom_controller.py b/tests/integration_test/data/apps/tb_streaming/app/custom/custom_controller.py index 9a585eb81c..c89750518b 100755 --- a/tests/integration_test/data/apps/tb_streaming/app/custom/custom_controller.py +++ b/tests/integration_test/data/apps/tb_streaming/app/custom/custom_controller.py @@ -1,4 +1,4 @@ -# Copyright (c) 2022, NVIDIA CORPORATION. All rights reserved. +# Copyright (c) 2023, NVIDIA CORPORATION. All rights reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. diff --git a/tests/integration_test/data/apps/tb_streaming/app/custom/custom_executor.py b/tests/integration_test/data/apps/tb_streaming/app/custom/custom_executor.py index d3e0d8ce54..8680a9a280 100755 --- a/tests/integration_test/data/apps/tb_streaming/app/custom/custom_executor.py +++ b/tests/integration_test/data/apps/tb_streaming/app/custom/custom_executor.py @@ -1,4 +1,4 @@ -# Copyright (c) 2022, NVIDIA CORPORATION. All rights reserved. +# Copyright (c) 2023, NVIDIA CORPORATION. All rights reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. diff --git a/tests/integration_test/data/jobs/decorator/app/custom/cifar10_structured_fl.py b/tests/integration_test/data/jobs/decorator/app/custom/cifar10_structured_fl.py index b92b37cb54..74aaf898f7 100644 --- a/tests/integration_test/data/jobs/decorator/app/custom/cifar10_structured_fl.py +++ b/tests/integration_test/data/jobs/decorator/app/custom/cifar10_structured_fl.py @@ -1,4 +1,4 @@ -# Copyright (c) 2023, NVIDIA CORPORATION. All rights reserved. +# Copyright (c) 2024, NVIDIA CORPORATION. All rights reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. diff --git a/tests/integration_test/data/jobs/decorator/app/custom/net.py b/tests/integration_test/data/jobs/decorator/app/custom/net.py index 031f84f432..47ac7e9589 100644 --- a/tests/integration_test/data/jobs/decorator/app/custom/net.py +++ b/tests/integration_test/data/jobs/decorator/app/custom/net.py @@ -1,4 +1,4 @@ -# Copyright (c) 2023, NVIDIA CORPORATION. All rights reserved. +# Copyright (c) 2024, NVIDIA CORPORATION. All rights reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. diff --git a/tests/integration_test/data/jobs/decorator_in_process/app/config/config_fed_client.conf b/tests/integration_test/data/jobs/decorator_in_process/app/config/config_fed_client.conf new file mode 100644 index 0000000000..0f810bf50a --- /dev/null +++ b/tests/integration_test/data/jobs/decorator_in_process/app/config/config_fed_client.conf @@ -0,0 +1,37 @@ +{ + format_version = 2 + app_script = "cifar10_structured_fl.py" + app_config = "" + executors = [ + { + tasks = [ + "train" + ] + executor { + path = "nvflare.app_opt.pt.in_process_client_api_executor.PTInProcessClientAPIExecutor" + args { + task_script_path = "{app_script}" + task_script_args = "{app_config}" + params_transfer_type = "DIFF" + train_with_evaluation = true + result_pull_interval = 0.5 + log_pull_interval = 0.1 + } + } + } + ] + task_data_filters = [] + task_result_filters = [] + components = [ + { + id = "event_to_fed" + name = "ConvertToFedEvent" + args { + events_to_convert = [ + "analytix_log_stats" + ] + fed_event_prefix = "fed." + } + } + ] +} diff --git a/tests/integration_test/data/jobs/decorator_in_process/app/config/config_fed_server.conf b/tests/integration_test/data/jobs/decorator_in_process/app/config/config_fed_server.conf new file mode 100644 index 0000000000..8245a2d527 --- /dev/null +++ b/tests/integration_test/data/jobs/decorator_in_process/app/config/config_fed_server.conf @@ -0,0 +1,62 @@ +{ + format_version = 2 + task_data_filters = [] + task_result_filters = [] + model_class_path = "net.Net" + workflows = [ + { + id = "scatter_and_gather" + path = "nvflare.app_common.workflows.scatter_and_gather.ScatterAndGather" + args { + min_clients = 2 + num_rounds = 2 + start_round = 0 + wait_time_after_min_received = 0 + aggregator_id = "aggregator" + persistor_id = "persistor" + shareable_generator_id = "shareable_generator" + train_task_name = "train" + train_timeout = 0 + } + } + ] + components = [ + { + id = "persistor" + path = "nvflare.app_opt.pt.file_model_persistor.PTFileModelPersistor" + args { + model { + path = "{model_class_path}" + } + } + } + { + id = "shareable_generator" + path = "nvflare.app_common.shareablegenerators.full_model_shareable_generator.FullModelShareableGenerator" + args {} + } + { + id = "aggregator" + path = "nvflare.app_common.aggregators.intime_accumulate_model_aggregator.InTimeAccumulateWeightedAggregator" + args { + expected_data_kind = "WEIGHT_DIFF" + } + } + { + id = "model_selector" + path = "nvflare.app_common.widgets.intime_model_selector.IntimeModelSelector" + args { + key_metric = "accuracy" + } + } + { + id = "receiver" + path = "nvflare.app_opt.tracking.tb.tb_receiver.TBAnalyticsReceiver" + args { + events = [ + "fed.analytix_log_stats" + ] + } + } + ] +} diff --git a/tests/integration_test/data/jobs/decorator_in_process/app/custom/cifar10_structured_fl.py b/tests/integration_test/data/jobs/decorator_in_process/app/custom/cifar10_structured_fl.py new file mode 100644 index 0000000000..74aaf898f7 --- /dev/null +++ b/tests/integration_test/data/jobs/decorator_in_process/app/custom/cifar10_structured_fl.py @@ -0,0 +1,139 @@ +# Copyright (c) 2024, NVIDIA CORPORATION. All rights reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +import torch +import torch.nn as nn +import torch.optim as optim +import torchvision +import torchvision.transforms as transforms +from net import Net + +# (1) import nvflare client API +import nvflare.client as flare + +# (optional) set a fix place so we don't need to download everytime +DATASET_PATH = "/tmp/nvflare/data" +# (optional) We change to use GPU to speed things up. +# if you want to use CPU, change DEVICE="cpu" +DEVICE = "cuda:0" +PATH = "./cifar_net.pth" + + +def main(): + transform = transforms.Compose([transforms.ToTensor(), transforms.Normalize((0.5, 0.5, 0.5), (0.5, 0.5, 0.5))]) + + batch_size = 4 + + trainset = torchvision.datasets.CIFAR10(root=DATASET_PATH, train=True, download=True, transform=transform) + trainloader = torch.utils.data.DataLoader(trainset, batch_size=batch_size, shuffle=True, num_workers=2) + + testset = torchvision.datasets.CIFAR10(root=DATASET_PATH, train=False, download=True, transform=transform) + testloader = torch.utils.data.DataLoader(testset, batch_size=batch_size, shuffle=False, num_workers=2) + + net = Net() + + # (2) initializes NVFlare client API + flare.init() + + # (3) decorates with flare.train and load model from the first argument + # wraps training logic into a method + @flare.train + def train(input_model=None, total_epochs=2, lr=0.001): + net.load_state_dict(input_model.params) + + criterion = nn.CrossEntropyLoss() + optimizer = optim.SGD(net.parameters(), lr=lr, momentum=0.9) + + # (optional) use GPU to speed things up + net.to(DEVICE) + # (optional) calculate total steps + steps = total_epochs * len(trainloader) + + for epoch in range(total_epochs): # loop over the dataset multiple times + + running_loss = 0.0 + for i, data in enumerate(trainloader, 0): + # get the inputs; data is a list of [inputs, labels] + # (optional) use GPU to speed things up + inputs, labels = data[0].to(DEVICE), data[1].to(DEVICE) + + # zero the parameter gradients + optimizer.zero_grad() + + # forward + backward + optimize + outputs = net(inputs) + loss = criterion(outputs, labels) + loss.backward() + optimizer.step() + + # print statistics + running_loss += loss.item() + if i % 2000 == 1999: # print every 2000 mini-batches + print(f"[{epoch + 1}, {i + 1:5d}] loss: {running_loss / 2000:.3f}") + running_loss = 0.0 + + print("Finished Training") + + torch.save(net.state_dict(), PATH) + + # (4) construct trained FL model + output_model = flare.FLModel(params=net.cpu().state_dict(), meta={"NUM_STEPS_CURRENT_ROUND": steps}) + return output_model + + # (5) decorates with flare.evaluate and load model from the first argument + @flare.evaluate + def fl_evaluate(input_model=None): + return evaluate(input_weights=input_model.params) + + # wraps evaluate logic into a method + def evaluate(input_weights): + net.load_state_dict(input_weights) + # (optional) use GPU to speed things up + net.to(DEVICE) + + correct = 0 + total = 0 + # since we're not training, we don't need to calculate the gradients for our outputs + with torch.no_grad(): + for data in testloader: + # (optional) use GPU to speed things up + images, labels = data[0].to(DEVICE), data[1].to(DEVICE) + # calculate outputs by running images through the network + outputs = net(images) + # the class with the highest energy is what we choose as prediction + _, predicted = torch.max(outputs.data, 1) + total += labels.size(0) + correct += (predicted == labels).sum().item() + + # return evaluation metrics + return 100 * correct // total + + while flare.is_running(): + # (6) receives FLModel from NVFlare + input_model = flare.receive() + print(f"current_round={input_model.current_round}") + + # (7) call fl_evaluate method before training + # to evaluate on the received/aggregated model + global_metric = fl_evaluate(input_model) + print(f"Accuracy of the global model on the 10000 test images: {global_metric} %") + # call train method + train(input_model, total_epochs=2, lr=0.001) + # call evaluate method + metric = evaluate(input_weights=torch.load(PATH)) + print(f"Accuracy of the trained model on the 10000 test images: {metric} %") + + +if __name__ == "__main__": + main() diff --git a/tests/integration_test/data/jobs/decorator_in_process/app/custom/net.py b/tests/integration_test/data/jobs/decorator_in_process/app/custom/net.py new file mode 100644 index 0000000000..47ac7e9589 --- /dev/null +++ b/tests/integration_test/data/jobs/decorator_in_process/app/custom/net.py @@ -0,0 +1,37 @@ +# Copyright (c) 2024, NVIDIA CORPORATION. All rights reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +import torch +import torch.nn as nn +import torch.nn.functional as F + + +class Net(nn.Module): + def __init__(self): + super().__init__() + self.conv1 = nn.Conv2d(3, 6, 5) + self.pool = nn.MaxPool2d(2, 2) + self.conv2 = nn.Conv2d(6, 16, 5) + self.fc1 = nn.Linear(16 * 5 * 5, 120) + self.fc2 = nn.Linear(120, 84) + self.fc3 = nn.Linear(84, 10) + + def forward(self, x): + x = self.pool(F.relu(self.conv1(x))) + x = self.pool(F.relu(self.conv2(x))) + x = torch.flatten(x, 1) # flatten all dimensions except batch + x = F.relu(self.fc1(x)) + x = F.relu(self.fc2(x)) + x = self.fc3(x) + return x diff --git a/tests/integration_test/data/jobs/decorator_in_process/meta.conf b/tests/integration_test/data/jobs/decorator_in_process/meta.conf new file mode 100644 index 0000000000..113a25d240 --- /dev/null +++ b/tests/integration_test/data/jobs/decorator_in_process/meta.conf @@ -0,0 +1,11 @@ +{ + name = "decorator" + resource_spec {} + deploy_map { + app = [ + "@ALL" + ] + } + min_clients = 2 + mandatory_clients = [] +} diff --git a/tests/integration_test/data/jobs/lightning/app/custom/cifar10_lightning_fl.py b/tests/integration_test/data/jobs/lightning/app/custom/cifar10_lightning_fl.py index 2a42f0e0a8..7bf2b1e2e9 100644 --- a/tests/integration_test/data/jobs/lightning/app/custom/cifar10_lightning_fl.py +++ b/tests/integration_test/data/jobs/lightning/app/custom/cifar10_lightning_fl.py @@ -1,4 +1,4 @@ -# Copyright (c) 2023, NVIDIA CORPORATION. All rights reserved. +# Copyright (c) 2024, NVIDIA CORPORATION. All rights reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. diff --git a/tests/integration_test/data/jobs/lightning/app/custom/lit_net.py b/tests/integration_test/data/jobs/lightning/app/custom/lit_net.py index aaf150a4c5..e98275e554 100644 --- a/tests/integration_test/data/jobs/lightning/app/custom/lit_net.py +++ b/tests/integration_test/data/jobs/lightning/app/custom/lit_net.py @@ -1,4 +1,4 @@ -# Copyright (c) 2023, NVIDIA CORPORATION. All rights reserved. +# Copyright (c) 2024, NVIDIA CORPORATION. All rights reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. diff --git a/tests/integration_test/data/jobs/lightning/app/custom/net.py b/tests/integration_test/data/jobs/lightning/app/custom/net.py index 031f84f432..47ac7e9589 100644 --- a/tests/integration_test/data/jobs/lightning/app/custom/net.py +++ b/tests/integration_test/data/jobs/lightning/app/custom/net.py @@ -1,4 +1,4 @@ -# Copyright (c) 2023, NVIDIA CORPORATION. All rights reserved. +# Copyright (c) 2024, NVIDIA CORPORATION. All rights reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. diff --git a/tests/integration_test/data/jobs/lightning_in_process/app/config/config_fed_client.conf b/tests/integration_test/data/jobs/lightning_in_process/app/config/config_fed_client.conf new file mode 100644 index 0000000000..23c3f2fa11 --- /dev/null +++ b/tests/integration_test/data/jobs/lightning_in_process/app/config/config_fed_client.conf @@ -0,0 +1,37 @@ +{ + format_version = 2 + app_script = "cifar10_lightning_fl.py" + app_config = "" + executors = [ + { + tasks = [ + "train" + ] + executor { + path = "nvflare.app_opt.pt.in_process_client_api_executor.PTInProcessClientAPIExecutor" + args { + task_script_path = "{app_script}" + task_script_args = "{app_config}" + params_transfer_type = "DIFF" + train_with_evaluation = true + result_pull_interval = 0.5 + log_pull_interval = 0.1 + } + } + } + ] + task_data_filters = [] + task_result_filters = [] + components = [ + { + id = "event_to_fed" + name = "ConvertToFedEvent" + args { + events_to_convert = [ + "analytix_log_stats" + ] + fed_event_prefix = "fed." + } + } + ] +} diff --git a/tests/integration_test/data/jobs/lightning_in_process/app/config/config_fed_server.conf b/tests/integration_test/data/jobs/lightning_in_process/app/config/config_fed_server.conf new file mode 100644 index 0000000000..45811d3380 --- /dev/null +++ b/tests/integration_test/data/jobs/lightning_in_process/app/config/config_fed_server.conf @@ -0,0 +1,62 @@ +{ + format_version = 2 + task_data_filters = [] + task_result_filters = [] + model_class_path = "lit_net.LitNet" + workflows = [ + { + id = "scatter_and_gather" + path = "nvflare.app_common.workflows.scatter_and_gather.ScatterAndGather" + args { + min_clients = 2 + num_rounds = 2 + start_round = 0 + wait_time_after_min_received = 0 + aggregator_id = "aggregator" + persistor_id = "persistor" + shareable_generator_id = "shareable_generator" + train_task_name = "train" + train_timeout = 0 + } + } + ] + components = [ + { + id = "persistor" + path = "nvflare.app_opt.pt.file_model_persistor.PTFileModelPersistor" + args { + model { + path = "{model_class_path}" + } + } + } + { + id = "shareable_generator" + path = "nvflare.app_common.shareablegenerators.full_model_shareable_generator.FullModelShareableGenerator" + args {} + } + { + id = "aggregator" + path = "nvflare.app_common.aggregators.intime_accumulate_model_aggregator.InTimeAccumulateWeightedAggregator" + args { + expected_data_kind = "WEIGHT_DIFF" + } + } + { + id = "model_selector" + path = "nvflare.app_common.widgets.intime_model_selector.IntimeModelSelector" + args { + key_metric = "val_acc_epoch" + } + } + { + id = "receiver" + path = "nvflare.app_opt.tracking.tb.tb_receiver.TBAnalyticsReceiver" + args { + events = [ + "fed.analytix_log_stats" + ] + } + } + ] +} diff --git a/tests/integration_test/data/jobs/lightning_in_process/app/custom/cifar10_lightning_fl.py b/tests/integration_test/data/jobs/lightning_in_process/app/custom/cifar10_lightning_fl.py new file mode 100644 index 0000000000..7bf2b1e2e9 --- /dev/null +++ b/tests/integration_test/data/jobs/lightning_in_process/app/custom/cifar10_lightning_fl.py @@ -0,0 +1,105 @@ +# Copyright (c) 2024, NVIDIA CORPORATION. All rights reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +import torch +import torchvision +import torchvision.transforms as transforms +from lit_net import LitNet +from pytorch_lightning import LightningDataModule, Trainer, seed_everything +from torch.utils.data import DataLoader, random_split + +# (1) import nvflare lightning client API +import nvflare.client.lightning as flare + +seed_everything(7) + + +DATASET_PATH = "/tmp/nvflare/data" +BATCH_SIZE = 4 + +transform = transforms.Compose([transforms.ToTensor(), transforms.Normalize((0.5, 0.5, 0.5), (0.5, 0.5, 0.5))]) + + +class CIFAR10DataModule(LightningDataModule): + def __init__(self, data_dir: str = DATASET_PATH, batch_size: int = BATCH_SIZE): + super().__init__() + self.data_dir = data_dir + self.batch_size = batch_size + + def prepare_data(self): + torchvision.datasets.CIFAR10(root=self.data_dir, train=True, download=True, transform=transform) + torchvision.datasets.CIFAR10(root=self.data_dir, train=False, download=True, transform=transform) + + def setup(self, stage: str): + # Assign train/val datasets for use in dataloaders + if stage == "fit" or stage == "validate": + cifar_full = torchvision.datasets.CIFAR10( + root=self.data_dir, train=True, download=False, transform=transform + ) + self.cifar_train, self.cifar_val = random_split(cifar_full, [0.8, 0.2]) + + # Assign test dataset for use in dataloader(s) + if stage == "test" or stage == "predict": + self.cifar_test = torchvision.datasets.CIFAR10( + root=self.data_dir, train=False, download=False, transform=transform + ) + + def train_dataloader(self): + return DataLoader(self.cifar_train, batch_size=self.batch_size) + + def val_dataloader(self): + return DataLoader(self.cifar_val, batch_size=self.batch_size) + + def test_dataloader(self): + return DataLoader(self.cifar_test, batch_size=self.batch_size) + + def predict_dataloader(self): + return DataLoader(self.cifar_test, batch_size=self.batch_size) + + +def main(): + model = LitNet() + cifar10_dm = CIFAR10DataModule() + + trainer = Trainer(max_epochs=1, devices=1 if torch.cuda.is_available() else None) + # (2) patch the lightning trainer + flare.patch(trainer) + + while flare.is_running(): + # (3) receives FLModel from NVFlare + # Note that we don't need to pass this input_model to trainer + # because after flare.patch the trainer.fit/validate will get the + # global model internally + input_model = flare.receive() + print(f"current_round={input_model.current_round}") + + # (4) evaluate the current global model to allow server-side model selection + print("--- validate global model ---") + trainer.validate(model, datamodule=cifar10_dm) + + # perform local training starting with the received global model + print("--- train new model ---") + trainer.fit(model, datamodule=cifar10_dm) + + # test local model + print("--- test new model ---") + trainer.test(ckpt_path="best", datamodule=cifar10_dm) + + # get predictions + print("--- prediction with new best model ---") + trainer.predict(ckpt_path="best", datamodule=cifar10_dm) + + +if __name__ == "__main__": + main() diff --git a/tests/integration_test/data/jobs/lightning_in_process/app/custom/lit_net.py b/tests/integration_test/data/jobs/lightning_in_process/app/custom/lit_net.py new file mode 100644 index 0000000000..e98275e554 --- /dev/null +++ b/tests/integration_test/data/jobs/lightning_in_process/app/custom/lit_net.py @@ -0,0 +1,72 @@ +# Copyright (c) 2024, NVIDIA CORPORATION. All rights reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +from typing import Any + +import torch.nn as nn +import torch.optim as optim +from net import Net +from pytorch_lightning import LightningModule +from torchmetrics import Accuracy + +NUM_CLASSES = 10 +criterion = nn.CrossEntropyLoss() + + +class LitNet(LightningModule): + def __init__(self): + super().__init__() + self.save_hyperparameters() + self.model = Net() + self.train_acc = Accuracy(task="multiclass", num_classes=NUM_CLASSES) + self.valid_acc = Accuracy(task="multiclass", num_classes=NUM_CLASSES) + # (optional) pass additional information via self.__fl_meta__ + self.__fl_meta__ = {} + + def forward(self, x): + out = self.model(x) + return out + + def training_step(self, batch, batch_idx): + x, labels = batch + outputs = self(x) + loss = criterion(outputs, labels) + self.train_acc(outputs, labels) + self.log("train_loss", loss) + self.log("train_acc", self.train_acc, on_step=True, on_epoch=False) + return loss + + def evaluate(self, batch, stage=None): + x, labels = batch + outputs = self(x) + loss = criterion(outputs, labels) + self.valid_acc(outputs, labels) + + if stage: + self.log(f"{stage}_loss", loss) + self.log(f"{stage}_acc", self.valid_acc, on_step=True, on_epoch=True) + return outputs + + def validation_step(self, batch, batch_idx): + self.evaluate(batch, "val") + + def test_step(self, batch, batch_idx): + self.evaluate(batch, "test") + + def predict_step(self, batch: Any, batch_idx: int, dataloader_idx: int = 0) -> Any: + return self.evaluate(batch) + + def configure_optimizers(self): + optimizer = optim.SGD(self.parameters(), lr=0.001, momentum=0.9) + return {"optimizer": optimizer} diff --git a/tests/integration_test/data/jobs/lightning_in_process/app/custom/net.py b/tests/integration_test/data/jobs/lightning_in_process/app/custom/net.py new file mode 100644 index 0000000000..47ac7e9589 --- /dev/null +++ b/tests/integration_test/data/jobs/lightning_in_process/app/custom/net.py @@ -0,0 +1,37 @@ +# Copyright (c) 2024, NVIDIA CORPORATION. All rights reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +import torch +import torch.nn as nn +import torch.nn.functional as F + + +class Net(nn.Module): + def __init__(self): + super().__init__() + self.conv1 = nn.Conv2d(3, 6, 5) + self.pool = nn.MaxPool2d(2, 2) + self.conv2 = nn.Conv2d(6, 16, 5) + self.fc1 = nn.Linear(16 * 5 * 5, 120) + self.fc2 = nn.Linear(120, 84) + self.fc3 = nn.Linear(84, 10) + + def forward(self, x): + x = self.pool(F.relu(self.conv1(x))) + x = self.pool(F.relu(self.conv2(x))) + x = torch.flatten(x, 1) # flatten all dimensions except batch + x = F.relu(self.fc1(x)) + x = F.relu(self.fc2(x)) + x = self.fc3(x) + return x diff --git a/tests/integration_test/data/jobs/lightning_in_process/meta.conf b/tests/integration_test/data/jobs/lightning_in_process/meta.conf new file mode 100644 index 0000000000..f50197ccb0 --- /dev/null +++ b/tests/integration_test/data/jobs/lightning_in_process/meta.conf @@ -0,0 +1,11 @@ +{ + name = "lightning" + resource_spec {} + deploy_map { + app = [ + "@ALL" + ] + } + min_clients = 2 + mandatory_clients = [] +} diff --git a/tests/integration_test/data/jobs/pt_client_api_in_process/app/config/config_fed_client.conf b/tests/integration_test/data/jobs/pt_client_api_in_process/app/config/config_fed_client.conf new file mode 100644 index 0000000000..6a1b31708f --- /dev/null +++ b/tests/integration_test/data/jobs/pt_client_api_in_process/app/config/config_fed_client.conf @@ -0,0 +1,37 @@ +{ + format_version = 2 + app_script = "cifar10_fl.py" + app_config = "" + executors = [ + { + tasks = [ + "train" + ] + executor { + path = "nvflare.app_opt.pt.in_process_client_api_executor.PTInProcessClientAPIExecutor" + args { + task_script_path = "{app_script}" + task_script_args = "{app_config}" + params_transfer_type = "DIFF" + train_with_evaluation = true + result_pull_interval = 0.5 + log_pull_interval = 0.1 + } + } + } + ] + task_data_filters = [] + task_result_filters = [] + components = [ + { + id = "event_to_fed" + name = "ConvertToFedEvent" + args { + events_to_convert = [ + "analytix_log_stats" + ] + fed_event_prefix = "fed." + } + } + ] +} diff --git a/tests/integration_test/data/jobs/pt_client_api_in_process/app/config/config_fed_server.conf b/tests/integration_test/data/jobs/pt_client_api_in_process/app/config/config_fed_server.conf new file mode 100644 index 0000000000..267a815c72 --- /dev/null +++ b/tests/integration_test/data/jobs/pt_client_api_in_process/app/config/config_fed_server.conf @@ -0,0 +1,88 @@ +{ + format_version = 2 + task_data_filters = [] + task_result_filters = [] + model_class_path = "net.Net" + workflows = [ + { + id = "scatter_and_gather" + path = "nvflare.app_common.workflows.scatter_and_gather.ScatterAndGather" + args { + min_clients = 2 + num_rounds = 3 + start_round = 0 + wait_time_after_min_received = 0 + aggregator_id = "aggregator" + persistor_id = "persistor" + shareable_generator_id = "shareable_generator" + train_task_name = "train" + train_timeout = 0 + } + } + ] + components = [ + { + id = "persistor" + path = "nvflare.app_opt.pt.file_model_persistor.PTFileModelPersistor" + args { + model { + path = "{model_class_path}" + } + } + } + { + id = "shareable_generator" + path = "nvflare.app_common.shareablegenerators.full_model_shareable_generator.FullModelShareableGenerator" + args {} + } + { + id = "aggregator" + path = "nvflare.app_common.aggregators.intime_accumulate_model_aggregator.InTimeAccumulateWeightedAggregator" + args { + expected_data_kind = "WEIGHT_DIFF" + } + } + { + id = "model_selector" + path = "nvflare.app_common.widgets.intime_model_selector.IntimeModelSelector" + args { + key_metric = "accuracy" + } + } + { + id = "receiver" + path = "nvflare.app_opt.tracking.tb.tb_receiver.TBAnalyticsReceiver" + args { + events = [ + "fed.analytix_log_stats" + ] + } + } + { + id = "mlflow_receiver" + path = "nvflare.app_opt.tracking.mlflow.mlflow_receiver.MLflowReceiver" + args { + tracking_uri = "" + kwargs { + experiment_name = "nvflare-sag-pt-experiment" + run_name = "nvflare-sag-pt-with-mlflow" + experiment_tags { + "mlflow.note.content" = "## **NVFlare SAG PyTorch experiment with MLflow**" + } + run_tags { + "mlflow.note.content" = """## Federated Experiment tracking with MLflow +### Example of using **[NVIDIA FLARE](https://nvflare.readthedocs.io/en/main/index.html)** to train an image classifier using federated averaging ([FedAvg]([FedAvg](https://arxiv.org/abs/1602.05629))) and [PyTorch](https://pytorch.org/) as the deep learning training framework. This example also highlights the NVFlare streaming capability from the clients to the server. + +> **_NOTE:_** + This example uses the *[CIFAR-10](https://www.cs.toronto.edu/~kriz/cifar.html)* dataset and will load its data within the trainer code. +""" + } + } + artifact_location = "artifacts" + events = [ + "fed.analytix_log_stats" + ] + } + } + ] +} diff --git a/tests/integration_test/data/jobs/pt_client_api_in_process/app/custom/cifar10_fl.py b/tests/integration_test/data/jobs/pt_client_api_in_process/app/custom/cifar10_fl.py new file mode 100644 index 0000000000..eaaabff176 --- /dev/null +++ b/tests/integration_test/data/jobs/pt_client_api_in_process/app/custom/cifar10_fl.py @@ -0,0 +1,137 @@ +# Copyright (c) 2024, NVIDIA CORPORATION. All rights reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +import torch +import torch.nn as nn +import torch.optim as optim +import torchvision +import torchvision.transforms as transforms +from net import Net + +# (1) import nvflare client API +import nvflare.client as flare + +# (optional) metrics +from nvflare.client.tracking import SummaryWriter + +# (optional) set a fix place so we don't need to download everytime +DATASET_PATH = "/tmp/nvflare/data" +# (optional) We change to use GPU to speed things up. +# if you want to use CPU, change DEVICE="cpu" +DEVICE = "cuda:0" + + +def main(): + transform = transforms.Compose([transforms.ToTensor(), transforms.Normalize((0.5, 0.5, 0.5), (0.5, 0.5, 0.5))]) + + batch_size = 4 + epochs = 2 + + trainset = torchvision.datasets.CIFAR10(root=DATASET_PATH, train=True, download=True, transform=transform) + trainloader = torch.utils.data.DataLoader(trainset, batch_size=batch_size, shuffle=True, num_workers=2) + + testset = torchvision.datasets.CIFAR10(root=DATASET_PATH, train=False, download=True, transform=transform) + testloader = torch.utils.data.DataLoader(testset, batch_size=batch_size, shuffle=False, num_workers=2) + + net = Net() + + # (2) initializes NVFlare client API + flare.init() + + summary_writer = SummaryWriter() + while flare.is_running(): + # (3) receives FLModel from NVFlare + input_model = flare.receive() + print(f"\n[Current Round={input_model.current_round}, Site = {flare.get_site_name()}]\n") + + # (4) loads model from NVFlare + net.load_state_dict(input_model.params) + + criterion = nn.CrossEntropyLoss() + optimizer = optim.SGD(net.parameters(), lr=0.001, momentum=0.9) + + # (optional) use GPU to speed things up + net.to(DEVICE) + # (optional) calculate total steps + steps = epochs * len(trainloader) + for epoch in range(epochs): # loop over the dataset multiple times + + running_loss = 0.0 + for i, data in enumerate(trainloader, 0): + # get the inputs; data is a list of [inputs, labels] + # (optional) use GPU to speed things up + inputs, labels = data[0].to(DEVICE), data[1].to(DEVICE) + + # zero the parameter gradients + optimizer.zero_grad() + + # forward + backward + optimize + outputs = net(inputs) + loss = criterion(outputs, labels) + loss.backward() + optimizer.step() + + # print statistics + running_loss += loss.item() + if i % 2000 == 1999: # print every 2000 mini-batches + print(f"[{epoch + 1}, {i + 1:5d}] loss: {running_loss / 2000:.3f}") + global_step = input_model.current_round * steps + epoch * len(trainloader) + i + + summary_writer.add_scalar(tag="loss_for_each_batch", scalar=running_loss, global_step=global_step) + running_loss = 0.0 + + print("Finished Training") + + PATH = "./cifar_net.pth" + torch.save(net.state_dict(), PATH) + + # (5) wraps evaluation logic into a method to re-use for + # evaluation on both trained and received model + def evaluate(input_weights): + net = Net() + net.load_state_dict(input_weights) + # (optional) use GPU to speed things up + net.to(DEVICE) + + correct = 0 + total = 0 + # since we're not training, we don't need to calculate the gradients for our outputs + with torch.no_grad(): + for data in testloader: + # (optional) use GPU to speed things up + images, labels = data[0].to(DEVICE), data[1].to(DEVICE) + # calculate outputs by running images through the network + outputs = net(images) + # the class with the highest energy is what we choose as prediction + _, predicted = torch.max(outputs.data, 1) + total += labels.size(0) + correct += (predicted == labels).sum().item() + + print(f"Accuracy of the network on the 10000 test images: {100 * correct // total} %") + return 100 * correct // total + + # (6) evaluate on received model for model selection + accuracy = evaluate(input_model.params) + # (7) construct trained FL model + output_model = flare.FLModel( + params=net.cpu().state_dict(), + metrics={"accuracy": accuracy}, + meta={"NUM_STEPS_CURRENT_ROUND": steps}, + ) + # (8) send model back to NVFlare + flare.send(output_model) + + +if __name__ == "__main__": + main() diff --git a/tests/integration_test/data/jobs/pt_client_api_in_process/app/custom/net.py b/tests/integration_test/data/jobs/pt_client_api_in_process/app/custom/net.py new file mode 100644 index 0000000000..47ac7e9589 --- /dev/null +++ b/tests/integration_test/data/jobs/pt_client_api_in_process/app/custom/net.py @@ -0,0 +1,37 @@ +# Copyright (c) 2024, NVIDIA CORPORATION. All rights reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +import torch +import torch.nn as nn +import torch.nn.functional as F + + +class Net(nn.Module): + def __init__(self): + super().__init__() + self.conv1 = nn.Conv2d(3, 6, 5) + self.pool = nn.MaxPool2d(2, 2) + self.conv2 = nn.Conv2d(6, 16, 5) + self.fc1 = nn.Linear(16 * 5 * 5, 120) + self.fc2 = nn.Linear(120, 84) + self.fc3 = nn.Linear(84, 10) + + def forward(self, x): + x = self.pool(F.relu(self.conv1(x))) + x = self.pool(F.relu(self.conv2(x))) + x = torch.flatten(x, 1) # flatten all dimensions except batch + x = F.relu(self.fc1(x)) + x = F.relu(self.fc2(x)) + x = self.fc3(x) + return x diff --git a/tests/integration_test/data/jobs/pt_client_api_in_process/meta.conf b/tests/integration_test/data/jobs/pt_client_api_in_process/meta.conf new file mode 100644 index 0000000000..d274eff79a --- /dev/null +++ b/tests/integration_test/data/jobs/pt_client_api_in_process/meta.conf @@ -0,0 +1,11 @@ +{ + name = "pt_client_api_in_process" + resource_spec {} + deploy_map { + app = [ + "@ALL" + ] + } + min_clients = 2 + mandatory_clients = [] +} diff --git a/tests/integration_test/data/test_configs/standalone_job/client_api.yml b/tests/integration_test/data/test_configs/standalone_job/client_api.yml index c8c030a79b..611135a07c 100644 --- a/tests/integration_test/data/test_configs/standalone_job/client_api.yml +++ b/tests/integration_test/data/test_configs/standalone_job/client_api.yml @@ -107,7 +107,7 @@ tests: - python -c "from torchvision.datasets import CIFAR10; CIFAR10(root='/tmp/nvflare/data', train=True, download=True)" teardown: - rm -rf /tmp/nvflare/data - - test_name: "run pt-decorator" + - test_name: "run decorator" event_sequence: - "trigger": "type": "server_log" @@ -126,7 +126,7 @@ tests: - python -c "from torchvision.datasets import CIFAR10; CIFAR10(root='/tmp/nvflare/data', train=True, download=True)" teardown: - rm -rf /tmp/nvflare/data - - test_name: "run lightning" + - test_name: "run lightning-client-api" event_sequence: - "trigger": "type": "server_log" @@ -146,3 +146,61 @@ tests: - python -c "from torchvision.datasets import CIFAR10; CIFAR10(root='/tmp/nvflare/data', train=True, download=True)" teardown: - rm -rf /tmp/nvflare/data + - test_name: "run pt-client-api-in-process" + event_sequence: + - "trigger": + "type": "server_log" + "data": "Server started" + "actions": [ "submit_job pt_client_api_in_process" ] + "result": + "type": "job_submit_success" + - "trigger": + "type": "run_state" + "data": { "run_finished": True } + "actions": [ "ensure_current_job_done" ] + "result": + "type": "run_state" + "data": { "run_finished": True } + setup: + - python -c "from torchvision.datasets import CIFAR10; CIFAR10(root='/tmp/nvflare/data', train=True, download=True)" + teardown: + - rm -rf /tmp/nvflare/data + - test_name: "run decorator-in-process" + event_sequence: + - "trigger": + "type": "server_log" + "data": "Server started" + "actions": [ "submit_job decorator_in_process" ] + "result": + "type": "job_submit_success" + - "trigger": + "type": "run_state" + "data": { "run_finished": True } + "actions": [ "ensure_current_job_done" ] + "result": + "type": "run_state" + "data": { "run_finished": True } + setup: + - python -c "from torchvision.datasets import CIFAR10; CIFAR10(root='/tmp/nvflare/data', train=True, download=True)" + teardown: + - rm -rf /tmp/nvflare/data + - test_name: "run lightning-client-api-in-process" + event_sequence: + - "trigger": + "type": "server_log" + "data": "Server started" + "actions": [ "submit_job lightning_in_process" ] + "result": + "type": "job_submit_success" + - "trigger": + "type": "run_state" + "data": { "run_finished": True } + "actions": [ "ensure_current_job_done" ] + "result": + "type": "run_state" + "data": { "run_finished": True } + setup: + - python -m pip install pytorch_lightning + - python -c "from torchvision.datasets import CIFAR10; CIFAR10(root='/tmp/nvflare/data', train=True, download=True)" + teardown: + - rm -rf /tmp/nvflare/data diff --git a/tests/unit_test/app_opt/__init__.py b/tests/unit_test/app_opt/__init__.py index d9155f923f..4fc50543f1 100644 --- a/tests/unit_test/app_opt/__init__.py +++ b/tests/unit_test/app_opt/__init__.py @@ -1,4 +1,4 @@ -# Copyright (c) 2024, NVIDIA CORPORATION. All rights reserved. +# Copyright (c) 2023, NVIDIA CORPORATION. All rights reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. diff --git a/tests/unit_test/fuel/utils/fobs/datum_test.py b/tests/unit_test/fuel/utils/fobs/datum_test.py index 5255a3e3dd..b0d5f2b68d 100644 --- a/tests/unit_test/fuel/utils/fobs/datum_test.py +++ b/tests/unit_test/fuel/utils/fobs/datum_test.py @@ -1,4 +1,4 @@ -# Copyright (c) 2022, NVIDIA CORPORATION. All rights reserved. +# Copyright (c) 2023, NVIDIA CORPORATION. All rights reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. From 1ea74d7728118221cecc5b7dc61775a5c7546a75 Mon Sep 17 00:00:00 2001 From: Sean Yang Date: Tue, 7 May 2024 16:58:06 -0700 Subject: [PATCH 06/15] Add client controller executor (#2530) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * add client controller executor * address comments * enhance abort, set peer props * remove asserts --------- Co-authored-by: Yuan-Ting Hsieh (謝沅廷) --- .../sag_cse_ccwf_pt/config_fed_client.conf | 183 ++++++++ .../sag_cse_ccwf_pt/config_fed_server.conf | 39 ++ job_templates/sag_cse_ccwf_pt/info.conf | 5 + job_templates/sag_cse_ccwf_pt/info.md | 11 + job_templates/sag_cse_ccwf_pt/meta.conf | 8 + nvflare/apis/controller_spec.py | 2 +- nvflare/apis/impl/controller.py | 32 +- nvflare/apis/impl/wf_comm_client.py | 83 +++- .../ccwf/client_controller_executor.py | 391 ++++++++++++++++++ nvflare/app_common/ccwf/common.py | 1 + nvflare/app_common/ccwf/server_ctl.py | 14 +- .../app_common/workflows/model_controller.py | 18 +- nvflare/fuel/utils/validation_utils.py | 11 +- .../private/fed/client/client_run_manager.py | 6 + nvflare/private/fed/utils/fed_utils.py | 2 +- 15 files changed, 765 insertions(+), 41 deletions(-) create mode 100644 job_templates/sag_cse_ccwf_pt/config_fed_client.conf create mode 100644 job_templates/sag_cse_ccwf_pt/config_fed_server.conf create mode 100644 job_templates/sag_cse_ccwf_pt/info.conf create mode 100644 job_templates/sag_cse_ccwf_pt/info.md create mode 100644 job_templates/sag_cse_ccwf_pt/meta.conf create mode 100644 nvflare/app_common/ccwf/client_controller_executor.py diff --git a/job_templates/sag_cse_ccwf_pt/config_fed_client.conf b/job_templates/sag_cse_ccwf_pt/config_fed_client.conf new file mode 100644 index 0000000000..0ee5e16152 --- /dev/null +++ b/job_templates/sag_cse_ccwf_pt/config_fed_client.conf @@ -0,0 +1,183 @@ +{ + # version of the configuration + format_version = 2 + + # This is the application script which will be invoked. Client can replace this script with user's own training script. + app_script = "train.py" + + # Additional arguments needed by the training code. For example, in lightning, these can be --trainer.batch_size=xxx. + app_config = "" + + # Path to defined PyTorch network + # This assumes that there will be a "net.py" file with class name "Net", please modify accordingly + model_class_path = "net.Net" + + # Client Computing Executors. + executors = [ + { + # tasks the executors are defined to handle + tasks = [ + "train", + "validate", + "submit_model" + ] + + # This particular executor + executor { + + # This is an executor for pytorch + Client API. The underline data exchange is using Pipe. + path = "nvflare.app_opt.pt.client_api_launcher_executor.PTClientAPILauncherExecutor" + + args { + + # launcher_id is used to locate the Launcher object in "components" + launcher_id = "launcher" + + # pipe_id is used to locate the Pipe object in "components" + pipe_id = "pipe" + + # Timeout in seconds for waiting for a heartbeat from the training script. Defaults to 30 seconds. + # Please refer to the class docstring for all available arguments + heartbeat_timeout = 60 + + # format of the exchange parameters + params_exchange_format = "pytorch" + + # if the transfer_type is FULL, then it will be sent directly + # if the transfer_type is DIFF, then we will calculate the + # difference VS received parameters and send the difference + params_transfer_type = "FULL" + # if train_with_evaluation is true, the executor will expect + # the custom code need to send back both the trained parameters and the evaluation metric + # otherwise only trained parameters are expected + train_with_evaluation = true + + train_task_name = "train" + evaluate_task_name = "validate" + submit_model_task_name = "submit_model" + } + } + } + { + # All tasks prefixed with wf_ are routed to this ClientControllerExecutor + tasks = ["wf_*"] + executor { + id = "client_controller_executor" + path = "nvflare.app_common.ccwf.client_controller_executor.ClientControllerExecutor" + # ClientControllerExecutor for running controllers on client-side. + args { + # list of controller ids from components to be run in order + controller_id_list = ["sag_ctl", "cse_ctl"] + task_name_prefix = "wf" + # persistor used to distribute and save final results for clients + persistor_id = "persistor" + } + } + } + ] + + # Array of task data filters. If provided, it will control the data from client controller to client executor + # Filter direction (in, out, inout) can be set as since clients send tasks to each other, a task has both a sending (out) and a receiving (in) direction + task_data_filters = [] + + # Array of task result filters. If provided, it will control the data from client executor to client controller + # Filter direction (in, out, inout) can be set as since clients send tasks to each other, a task has both a sending (out) and a receiving (in) direction + task_result_filters = [] + + components = [ + { + id = "sag_ctl" + path = "nvflare.app_common.workflows.scatter_and_gather.ScatterAndGather" + args { + min_clients = 2 + num_rounds = 3 + start_round = 0 + wait_time_after_min_received = 0 + aggregator_id = "aggregator" + persistor_id = "persistor" + shareable_generator_id = "shareable_generator" + train_task_name = "train" + train_timeout = 0 + } + } + { + id = "cse_ctl", + path = "nvflare.app_common.workflows.cross_site_model_eval.CrossSiteModelEval", + args { + model_locator_id = "model_locator", + submit_model_timeout = 600, + validation_timeout = 6000, + cleanup_models = false + } + } + { + # component id is "launcher" + id = "launcher" + + # the class path of this component + path = "nvflare.app_common.launchers.subprocess_launcher.SubprocessLauncher" + + args { + # the launcher will invoke the script + script = "python3 custom/{app_script} {app_config} " + # if launch_once is true, the SubprocessLauncher will launch once for the whole job + # if launch_once is false, the SubprocessLauncher will launch a process for each task it receives from server + launch_once = true + } + } + { + id = "pipe" + + path = "nvflare.fuel.utils.pipe.file_pipe.FilePipe" + + args { + # Mode of the endpoint. A pipe has two endpoints. + # An endpoint can be either the one that initiates communication or the one listening. + # PASSIVE is the one listening. + mode = "PASSIVE" + + # root_path: is the directory location of the parameters exchange. + # You can also set it to an absolute path in your system. + root_path = "{WORKSPACE}/{JOB_ID}/{SITE_NAME}" + } + } + # required components for the client-controlled workflow defined on client-side + { + id = "persistor" + path = "nvflare.app_opt.pt.file_model_persistor.PTFileModelPersistor" + args.model.path = "{model_class_path}" + } + { + id = "shareable_generator" + path = "nvflare.app_common.shareablegenerators.full_model_shareable_generator.FullModelShareableGenerator" + args = {} + } + { + # This is the aggregator that perform the weighted average aggregation. + # the aggregation is "in-time", so it doesn't wait for client results, but aggregates as soon as it received the data. + id = "aggregator" + path = "nvflare.app_common.aggregators.intime_accumulate_model_aggregator.InTimeAccumulateWeightedAggregator" + args.expected_data_kind = "WEIGHTS" + }, + { + id = "model_locator" + name = "PTFileModelLocator" + args { + pt_persistor_id = "persistor" + } + }, + { + # This component is not directly used in Workflow. + # it select the best model based on the incoming global validation metrics. + id = "model_selector" + path = "nvflare.app_common.widgets.intime_model_selector.IntimeModelSelector" + # need to make sure this "key_metric" match what server side received + args.key_metric = "accuracy" + }, + { + id = "json_generator" + name = "ValidationJsonGenerator" + args {} + } + ] +} diff --git a/job_templates/sag_cse_ccwf_pt/config_fed_server.conf b/job_templates/sag_cse_ccwf_pt/config_fed_server.conf new file mode 100644 index 0000000000..514c8cc8fe --- /dev/null +++ b/job_templates/sag_cse_ccwf_pt/config_fed_server.conf @@ -0,0 +1,39 @@ +{ + # version of the configuration + format_version = 2 + + # task data filter: if filters are provided, the filter will filter the data flow out of server to client. + task_data_filters =[] + + # task result filter: if filters are provided, the filter will filter the result flow out of client to server. + task_result_filters = [] + + # This assumes that there will be a "net.py" file with class name "Net". + # If your model code is not in "net.py" and class name is not "Net", please modify here + model_class_path = "net.Net" + + # workflows: Array of workflows the control the Federated Learning workflow lifecycle. + # One can specify multiple workflows. The NVFLARE will run them in the order specified. + workflows = [ + { + # server-side controller to manage job life cycle and configuration + id = "svr_ctl" + path = "nvflare.app_common.ccwf.server_ctl.ServerSideController" + args { + # the prefix for task names of this workflow + task_name_prefix = "wf" + # the maximum amount of time allowed for a client to miss a status report + max_status_report_interval = 300 + # policy to choose which client to run the controller logic from + starting_client_policy = "random" + # timeout for the ClientControllerExecutor start task, which runs all of the controllers + start_task_timeout = 600 + } + } + ] + + # List of components used in the server side workflow. + components = [ + ] + +} diff --git a/job_templates/sag_cse_ccwf_pt/info.conf b/job_templates/sag_cse_ccwf_pt/info.conf new file mode 100644 index 0000000000..850794a095 --- /dev/null +++ b/job_templates/sag_cse_ccwf_pt/info.conf @@ -0,0 +1,5 @@ +{ + description = "Client Controller FedAvg and cross-site evaluation with PyTorch" + execution_api_type = "client_api" + controller_type = "client" +} \ No newline at end of file diff --git a/job_templates/sag_cse_ccwf_pt/info.md b/job_templates/sag_cse_ccwf_pt/info.md new file mode 100644 index 0000000000..e2a768a04a --- /dev/null +++ b/job_templates/sag_cse_ccwf_pt/info.md @@ -0,0 +1,11 @@ +# Job Template Information Card + +## sag_cse_ccwf_pt + name = "sag_cse_ccwf_pt" + description = "Client Controller FedAvg with scatter & gather workflow and cross-site evaluation with PyTorch" + class_name = "ClientControllerExecutor" + controller_type = "client" + executor_type = "launcher_executor" + contributor = "NVIDIA" + init_publish_date = "2024-04-25" + last_updated_date = "2024-04-25" diff --git a/job_templates/sag_cse_ccwf_pt/meta.conf b/job_templates/sag_cse_ccwf_pt/meta.conf new file mode 100644 index 0000000000..155d780e05 --- /dev/null +++ b/job_templates/sag_cse_ccwf_pt/meta.conf @@ -0,0 +1,8 @@ +name = "sag_cse_ccwf_pt" +resource_spec {} +min_clients = 2 +deploy_map { + app = [ + "@ALL" + ] +} diff --git a/nvflare/apis/controller_spec.py b/nvflare/apis/controller_spec.py index 2f18f95623..772fe54d9b 100644 --- a/nvflare/apis/controller_spec.py +++ b/nvflare/apis/controller_spec.py @@ -88,7 +88,7 @@ def __init__( name (str): name of the task data (Shareable): data of the task props: Any additional properties of the task - timeout: How long this task will last. If == 0, the task never time out. + timeout: How long this task will last. If == 0, the task never time out (WFCommServer-> never time out, WFCommClient-> time out after `max_task_timeout`). before_task_sent_cb: If provided, this callback would be called before controller sends the tasks to clients. It needs to follow the before_task_sent_cb_signature. after_task_sent_cb: If provided, this callback would be called after controller sends the tasks to clients. diff --git a/nvflare/apis/impl/controller.py b/nvflare/apis/impl/controller.py index 924512f77b..d8646145c2 100644 --- a/nvflare/apis/impl/controller.py +++ b/nvflare/apis/impl/controller.py @@ -60,7 +60,7 @@ def broadcast( min_responses: int = 1, wait_time_after_min_received: int = 0, ): - self.communicator.broadcast(task, fl_ctx, targets, min_responses, wait_time_after_min_received) + return self.communicator.broadcast(task, fl_ctx, targets, min_responses, wait_time_after_min_received) def broadcast_and_wait( self, @@ -71,12 +71,12 @@ def broadcast_and_wait( wait_time_after_min_received: int = 0, abort_signal: Optional[Signal] = None, ): - self.communicator.broadcast_and_wait( + return self.communicator.broadcast_and_wait( task, fl_ctx, targets, min_responses, wait_time_after_min_received, abort_signal ) def broadcast_forever(self, task: Task, fl_ctx: FLContext, targets: Union[List[Client], List[str], None] = None): - self.communicator.broadcast_forever(task, fl_ctx, targets) + return self.communicator.broadcast_forever(task, fl_ctx, targets) def send( self, @@ -86,7 +86,7 @@ def send( send_order: SendOrder = SendOrder.SEQUENTIAL, task_assignment_timeout: int = 0, ): - self.communicator.send(task, fl_ctx, targets, send_order, task_assignment_timeout) + return self.communicator.send(task, fl_ctx, targets, send_order, task_assignment_timeout) def send_and_wait( self, @@ -97,7 +97,7 @@ def send_and_wait( task_assignment_timeout: int = 0, abort_signal: Signal = None, ): - self.communicator.send_and_wait(task, fl_ctx, targets, send_order, task_assignment_timeout, abort_signal) + return self.communicator.send_and_wait(task, fl_ctx, targets, send_order, task_assignment_timeout, abort_signal) def relay( self, @@ -109,7 +109,7 @@ def relay( task_result_timeout: int = 0, dynamic_targets: bool = True, ): - self.communicator.relay( + return self.communicator.relay( task, fl_ctx, targets, send_order, task_assignment_timeout, task_result_timeout, dynamic_targets ) @@ -124,7 +124,7 @@ def relay_and_wait( dynamic_targets: bool = True, abort_signal: Optional[Signal] = None, ): - self.communicator.relay_and_wait( + return self.communicator.relay_and_wait( task, fl_ctx, targets, @@ -136,7 +136,11 @@ def relay_and_wait( ) def get_num_standing_tasks(self) -> int: - return self.communicator.get_num_standing_tasks() + try: + return self.communicator.get_num_standing_tasks() + except Exception as e: + self.logger.warning(f"get_num_standing_tasks() is not supported by {self.communicator}: {e}") + return None def cancel_task( self, task: Task, completion_status=TaskCompletionStatus.CANCELLED, fl_ctx: Optional[FLContext] = None @@ -144,7 +148,10 @@ def cancel_task( self.communicator.cancel_task(task, completion_status, fl_ctx) def cancel_all_tasks(self, completion_status=TaskCompletionStatus.CANCELLED, fl_ctx: Optional[FLContext] = None): - self.communicator.cancel_all_tasks(completion_status, fl_ctx) + try: + self.communicator.cancel_all_tasks(completion_status, fl_ctx) + except Exception as e: + self.log_warning(fl_ctx, f"cancel_all_tasks() is not supported by {self.communicator}: {e}") def get_client_disconnect_time(self, client_name): """Get the time when the client is deemed disconnected. @@ -157,4 +164,9 @@ def get_client_disconnect_time(self, client_name): """ if not self.communicator: return None - return self.communicator.get_client_disconnect_time(client_name) + + try: + return self.communicator.get_client_disconnect_time(client_name) + except Exception as e: + self.logger.warning(f"get_client_disconnect_time() is not supported by {self.communicator}: {e}") + return None diff --git a/nvflare/apis/impl/wf_comm_client.py b/nvflare/apis/impl/wf_comm_client.py index a8753f5b64..8589cbeec9 100644 --- a/nvflare/apis/impl/wf_comm_client.py +++ b/nvflare/apis/impl/wf_comm_client.py @@ -12,7 +12,7 @@ # See the License for the specific language governing permissions and # limitations under the License. -from typing import List, Union +from typing import List, Optional, Union from nvflare.apis.client import Client from nvflare.apis.controller_spec import ClientTask, SendOrder, Task, TaskCompletionStatus @@ -24,6 +24,7 @@ from nvflare.apis.signal import Signal from nvflare.apis.utils.task_utils import apply_filters from nvflare.apis.wf_comm_spec import WFCommSpec +from nvflare.app_common.ccwf.common import Constant from nvflare.private.fed.utils.fed_utils import get_target_names from nvflare.private.privacy_manager import Scope from nvflare.security.logging import secure_format_exception @@ -32,10 +33,17 @@ class WFCommClient(FLComponent, WFCommSpec): def __init__( self, + max_task_timeout: int = Constant.MAX_TASK_TIMEOUT, ) -> None: + """Communicator using aux channel communication. + + Args: + max_task_timeout (int, optional): Maximum task timeout when `task.timeout` is set to 0. Defaults to 3600. + """ super().__init__() self.task_data_filters = {} self.task_result_filters = {} + self.max_task_timeout = max_task_timeout def broadcast( self, @@ -57,7 +65,6 @@ def broadcast_and_wait( abort_signal: Signal = None, ): engine = fl_ctx.get_engine() - request = task.data # apply task filters self.log_debug(fl_ctx, "firing event EventType.BEFORE_TASK_DATA_FILTER") fl_ctx.set_prop(FLContextKey.TASK_DATA, task.data, sticky=False, private=True) @@ -66,7 +73,7 @@ def broadcast_and_wait( # # first apply privacy-defined filters try: filter_name = Scope.TASK_DATA_FILTERS_NAME - task.data = apply_filters(filter_name, request, fl_ctx, self.task_data_filters, task.name, FilterKey.OUT) + task.data = apply_filters(filter_name, task.data, fl_ctx, self.task_data_filters, task.name, FilterKey.OUT) except Exception as e: self.log_exception( fl_ctx, @@ -80,6 +87,9 @@ def broadcast_and_wait( fl_ctx.set_prop(FLContextKey.TASK_DATA, task.data, sticky=False, private=True) self.fire_event(EventType.AFTER_TASK_DATA_FILTER, fl_ctx) + if targets is None: + targets = engine.all_clients.values() + target_names = get_target_names(targets) _, invalid_names = engine.validate_targets(target_names) if invalid_names: @@ -92,16 +102,22 @@ def broadcast_and_wait( task.client_tasks.append(client_task) task.last_client_task_map[client_task.id] = client_task - # task_cb_error = self._call_task_cb(task.before_task_sent_cb, client, task, fl_ctx) - # if task_cb_error: - # return self._make_error_reply(ReturnCode.ERROR, targets) + task_cb_error = self._call_task_cb(task.before_task_sent_cb, client, task, fl_ctx) + if task_cb_error: + return self._make_error_reply(ReturnCode.ERROR, targets) + + if task.timeout < 0: + raise ValueError(f"The task timeout must >= 0. But got {task.timeout}") - if task.timeout <= 0: - raise ValueError(f"The task timeout must > 0. But got {task.timeout}") + if task.timeout == 0: + task.timeout = self.max_task_timeout + + # Note: set request here since task.data can be modified by user callback before_task_sent_cb + request = task.data request.set_header(ReservedKey.TASK_NAME, task.name) replies = engine.send_aux_request( - targets=targets, + targets=target_names, topic=ReservedTopic.DO_TASK, request=request, timeout=task.timeout, @@ -109,10 +125,20 @@ def broadcast_and_wait( secure=task.secure, ) + for client_task in task.client_tasks: + task_cb_error = self._call_task_cb(task.after_task_sent_cb, client_task.client, client_task.task, fl_ctx) + if task_cb_error: + return self._make_error_reply(ReturnCode.ERROR, targets) + self.log_debug(fl_ctx, "firing event EventType.BEFORE_TASK_RESULT_FILTER") self.fire_event(EventType.BEFORE_TASK_RESULT_FILTER, fl_ctx) for target, reply in replies.items(): + + peer_ctx = reply.get_header(FLContextKey.PEER_CONTEXT) + peer_ctx.set_prop(FLContextKey.SHAREABLE, reply, private=True) + fl_ctx.set_peer_context(peer_ctx) + # get the client task for the target for client_task in task.client_tasks: if client_task.client.name == target: @@ -133,6 +159,9 @@ def broadcast_and_wait( client_task.result = error_reply break + if not reply.get_peer_props() and fl_ctx.get_peer_context(): + reply.set_peer_props(fl_ctx.get_peer_context().get_all_public_props()) + # assign replies to client task, prepare for the result_received_cb client_task.result = reply @@ -220,21 +249,49 @@ def send( targets: Union[List[Client], List[str], None] = None, send_order: SendOrder = SendOrder.SEQUENTIAL, task_assignment_timeout: int = 0, + ): + return self.send_and_wait(task, fl_ctx, targets, send_order, task_assignment_timeout) + + def send_and_wait( + self, + task: Task, + fl_ctx: FLContext, + targets: Union[List[Client], List[str], None] = None, + send_order: SendOrder = SendOrder.SEQUENTIAL, + task_assignment_timeout: int = 0, + abort_signal: Signal = None, ): engine = fl_ctx.get_engine() self._validate_target(engine, targets) - return self.send_and_wait(task, fl_ctx, targets, send_order, task_assignment_timeout) + for target in targets: + reply = self.broadcast_and_wait(task, fl_ctx, [target], abort_signal=abort_signal) + if reply.get_return_code() == ReturnCode.OK: + return reply - def send_and_wait( + def relay( self, task: Task, fl_ctx: FLContext, targets: Union[List[Client], List[str], None] = None, send_order: SendOrder = SendOrder.SEQUENTIAL, task_assignment_timeout: int = 0, - abort_signal: Signal = None, + task_result_timeout: int = 0, + dynamic_targets: bool = True, + ): + return self.relay_and_wait(task, fl_ctx, targets, send_order, task_assignment_timeout) + + def relay_and_wait( + self, + task: Task, + fl_ctx: FLContext, + targets: Union[List[Client], List[str], None] = None, + send_order=SendOrder.SEQUENTIAL, + task_assignment_timeout: int = 0, + task_result_timeout: int = 0, + dynamic_targets: bool = True, + abort_signal: Optional[Signal] = None, ): engine = fl_ctx.get_engine() @@ -249,8 +306,6 @@ def send_and_wait( def _validate_target(self, engine, targets): if len(targets) == 0: raise ValueError("Must provide a target to send.") - if len(targets) != 1: - raise ValueError("send_and_wait can only send to a single target.") target_names = get_target_names(targets) _, invalid_names = engine.validate_targets(target_names) if invalid_names: diff --git a/nvflare/app_common/ccwf/client_controller_executor.py b/nvflare/app_common/ccwf/client_controller_executor.py new file mode 100644 index 0000000000..f2b278c858 --- /dev/null +++ b/nvflare/app_common/ccwf/client_controller_executor.py @@ -0,0 +1,391 @@ +# Copyright (c) 2024, NVIDIA CORPORATION. All rights reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +import copy +import threading +import time +from typing import List + +from nvflare.apis.event_type import EventType +from nvflare.apis.executor import Executor +from nvflare.apis.fl_constant import FLContextKey, ReturnCode +from nvflare.apis.fl_context import FLContext +from nvflare.apis.impl.task_controller import Task +from nvflare.apis.impl.wf_comm_client import WFCommClient +from nvflare.apis.shareable import Shareable, make_reply +from nvflare.apis.signal import Signal +from nvflare.app_common.abstract.learnable import Learnable +from nvflare.app_common.abstract.learnable_persistor import LearnablePersistor +from nvflare.app_common.app_constant import AppConstants +from nvflare.app_common.ccwf.common import Constant, StatusReport, make_task_name, topic_for_end_workflow +from nvflare.fuel.utils.validation_utils import check_number_range +from nvflare.security.logging import secure_format_exception + + +class ClientControllerExecutor(Executor): + def __init__( + self, + controller_id_list: List, + task_name_prefix: str = "", + persistor_id=AppConstants.DEFAULT_PERSISTOR_ID, + final_result_ack_timeout=Constant.FINAL_RESULT_ACK_TIMEOUT, + max_task_timeout: int = Constant.MAX_TASK_TIMEOUT, + ): + """ + ClientControllerExecutor for running controllers on client-side using WFCommClient. + + Args: + controller_id_list: List of controller ids, used in order. + task_name_prefix: prefix of task names. All CCWF task names are prefixed with this. + persistor_id: ID of the persistor component + final_result_ack_timeout: timeout for sending final result to participating clients + max_task_timeout: Maximum task timeout for Controllers using WFCommClient when `task.timeout` is set to 0. Defaults to 3600. + """ + check_number_range("final_result_ack_timeout", final_result_ack_timeout, min_value=1.0) + + Executor.__init__(self) + self.controller_id_list = controller_id_list + self.task_name_prefix = task_name_prefix + self.persistor_id = persistor_id + self.final_result_ack_timeout = final_result_ack_timeout + self.max_task_timeout = max_task_timeout + + self.start_task_name = make_task_name(task_name_prefix, Constant.BASENAME_START) + self.configure_task_name = make_task_name(task_name_prefix, Constant.BASENAME_CONFIG) + self.report_final_result_task_name = make_task_name(task_name_prefix, Constant.BASENAME_REPORT_FINAL_RESULT) + + self.persistor = None + + self.current_status = StatusReport() + self.last_status_report_time = time.time() # time of last status report to server + self.config = None + self.workflow_id = None + self.finalize_lock = threading.Lock() + + self.asked_to_stop = False + self.status_lock = threading.Lock() + self.engine = None + self.me = None + self.is_starting_client = False + self.workflow_done = False + self.fatal_system_error = False + + def get_config_prop(self, name: str, default=None): + """ + Get a specified config property. + Args: + name: name of the property + default: default value to return if the property is not defined. + Returns: + """ + if not self.config: + return default + return self.config.get(name, default) + + def start_run(self, fl_ctx: FLContext): + self.engine = fl_ctx.get_engine() + if not self.engine: + self.system_panic("no engine", fl_ctx) + return + + runner = fl_ctx.get_prop(FLContextKey.RUNNER) + if not runner: + self.system_panic("no client runner", fl_ctx) + return + + self.me = fl_ctx.get_identity_name() + + self.persistor = self.engine.get_component(self.persistor_id) + if not isinstance(self.persistor, LearnablePersistor): + self.log_warning( + fl_ctx, f"Persistor {self.persistor_id} must be a Persistor instance but got {type(self.persistor)}" + ) + self.persistor = None + + self.initialize(fl_ctx) + + def initialize_controller(self, controller_id, fl_ctx): + controller = self.engine.get_component(controller_id) + + comm = WFCommClient(max_task_timeout=self.max_task_timeout) + controller.set_communicator(comm) + controller.config = self.config + controller.initialize(fl_ctx) + + return controller + + def handle_event(self, event_type: str, fl_ctx: FLContext): + if event_type == EventType.START_RUN: + self.start_run(fl_ctx) + + elif event_type == EventType.BEFORE_PULL_TASK: + # add my status to fl_ctx + if not self.workflow_id: + return + + reports = fl_ctx.get_prop(Constant.STATUS_REPORTS) + if reports: + reports.pop(self.workflow_id, None) + + if self.workflow_done: + return + report = self._get_status_report() + if not report: + self.log_debug(fl_ctx, "nothing to report this time") + return + self._add_status_report(report, fl_ctx) + self.last_status_report_time = report.timestamp + + elif event_type in [EventType.ABORT_TASK, EventType.END_RUN]: + if not self.asked_to_stop and not self.workflow_done: + self.asked_to_stop = True + self.finalize(fl_ctx) + + elif event_type == EventType.FATAL_SYSTEM_ERROR: + if self.is_starting_client and not self.fatal_system_error: + self.fatal_system_error = True + self.fire_fed_event(EventType.FATAL_SYSTEM_ERROR, Shareable(), fl_ctx) + + def _add_status_report(self, report: StatusReport, fl_ctx: FLContext): + reports = fl_ctx.get_prop(Constant.STATUS_REPORTS) + if not reports: + reports = {} + # set the prop as public, so it will be sent to the peer in peer_context + fl_ctx.set_prop(Constant.STATUS_REPORTS, reports, sticky=False, private=False) + reports[self.workflow_id] = report.to_dict() + + def initialize(self, fl_ctx: FLContext): + """Called to initialize the executor. + Args: + fl_ctx: The FL Context + Returns: None + """ + fl_ctx.set_prop(Constant.EXECUTOR, self, private=True, sticky=False) + self.fire_event(Constant.EXECUTOR_INITIALIZED, fl_ctx) + + def finalize(self, fl_ctx: FLContext): + """Called to finalize the executor. + Args: + fl_ctx: the FL Context + Returns: None + """ + with self.finalize_lock: + if self.workflow_done: + return + + fl_ctx.set_prop(Constant.EXECUTOR, self, private=True, sticky=False) + fl_ctx.set_prop(FLContextKey.WORKFLOW, self.workflow_id, private=True, sticky=False) + self.fire_event(Constant.EXECUTOR_FINALIZED, fl_ctx) + self.workflow_done = True + + def execute(self, task_name: str, shareable: Shareable, fl_ctx: FLContext, abort_signal: Signal) -> Shareable: + if self.workflow_done: + self.log_error(fl_ctx, f"ClientControllerExecutor is finalized, not executing task {task_name}.") + return make_reply(ReturnCode.ERROR) + + if task_name == self.configure_task_name: + self.config = shareable[Constant.CONFIG] + my_wf_id = self.get_config_prop(FLContextKey.WORKFLOW) + if not my_wf_id: + self.log_error(fl_ctx, "missing workflow id in configuration!") + return make_reply(ReturnCode.BAD_REQUEST_DATA) + self.log_info(fl_ctx, f"got my workflow id {my_wf_id}") + self.workflow_id = my_wf_id + + self.engine.register_aux_message_handler( + topic=topic_for_end_workflow(my_wf_id), + message_handle_func=self._process_end_workflow, + ) + + return make_reply(ReturnCode.OK) + + elif task_name == self.start_task_name: + self.is_starting_client = True + + for controller_id in self.controller_id_list: + + if self.asked_to_stop: + self.log_info(fl_ctx, "Asked to stop, exiting") + return make_reply(ReturnCode.OK) + + self.controller = self.initialize_controller(controller_id, fl_ctx) + self.log_info(fl_ctx, f"Starting control flow {self.controller.name}") + + try: + res = self.controller.control_flow(abort_signal, fl_ctx) + except Exception as e: + error_msg = f"{controller_id} control_flow exception: {secure_format_exception(e)}" + self.log_error(fl_ctx, error_msg) + self.system_panic(error_msg, fl_ctx) + + if abort_signal.triggered: + return make_reply(ReturnCode.TASK_ABORTED) + + if hasattr(self.controller, "persistor"): + self.broadcast_final_result(self.controller.persistor.load(fl_ctx), fl_ctx) + + self.controller.stop_controller(fl_ctx) + + self.log_info(fl_ctx, f"Finished control flow {self.controller.name}") + + self.update_status(action=f"finished_{controller_id}", error=None, all_done=True) + + self.update_status(action="finished_start_task", error=None, all_done=True) + + return make_reply(ReturnCode.OK) + + elif task_name == self.report_final_result_task_name: + return self._process_final_result(shareable, fl_ctx) + + else: + self.log_error(fl_ctx, f"Could not handle task: {task_name}") + return make_reply(ReturnCode.TASK_UNKNOWN) + + def _get_status_report(self): + with self.status_lock: + status = self.current_status + must_report = False + if status.error: + must_report = True + elif status.timestamp: + must_report = True + + if not must_report: + return None + + # do status report + report = copy.copy(status) + return report + + def update_status(self, last_round=None, action=None, error=None, all_done=False): + with self.status_lock: + status = self.current_status + status.timestamp = time.time() + if all_done: + # once marked all_done, always all_done! + status.all_done = True + if error: + status.error = error + if action: + status.action = action + if status.last_round is None: + status.last_round = last_round + elif last_round is not None and last_round > status.last_round: + status.last_round = last_round + + status_dict = status.to_dict() + self.logger.info(f"updated my last status: {status_dict}") + + def _process_final_result(self, request: Shareable, fl_ctx: FLContext) -> Shareable: + peer_ctx = fl_ctx.get_peer_context() + if peer_ctx: + client_name = peer_ctx.get_identity_name() + else: + self.log_error(fl_ctx, "Request from unknown client") + return make_reply(ReturnCode.BAD_REQUEST_DATA) + result = request.get(Constant.RESULT) + + if not result: + self.log_error(fl_ctx, f"Bad request from client {client_name}: no result") + return make_reply(ReturnCode.BAD_REQUEST_DATA) + + if not isinstance(result, Learnable): + self.log_error(fl_ctx, f"Bad result from client {client_name}: expect Learnable but got {type(result)}") + return make_reply(ReturnCode.BAD_REQUEST_DATA) + + self.log_info(fl_ctx, f"Got final result from client {client_name}") + + fl_ctx.set_prop(AppConstants.GLOBAL_MODEL, result, private=True, sticky=True) + + if self.persistor: + self.persistor.save(result, fl_ctx) + else: + self.log_error(fl_ctx, "persistor not configured, model will not be saved") + + return make_reply(ReturnCode.OK) + + def _process_end_workflow(self, topic: str, request: Shareable, fl_ctx: FLContext) -> Shareable: + self.log_info(fl_ctx, f"ending workflow {self.get_config_prop(FLContextKey.WORKFLOW)}") + self.asked_to_stop = True + # self._abort_current_task(fl_ctx) + self.finalize(fl_ctx) + return make_reply(ReturnCode.OK) + + def is_task_secure(self, fl_ctx: FLContext) -> bool: + """ + Determine whether the task should be secure. A secure task requires encrypted communication between the peers. + The task is secure only when the training is in secure mode AND private_p2p is set to True. + """ + private_p2p = self.get_config_prop(Constant.PRIVATE_P2P) + secure_train = fl_ctx.get_prop(FLContextKey.SECURE_MODE, False) + return private_p2p and secure_train + + def broadcast_final_result(self, result: Learnable, fl_ctx: FLContext): + targets = self.get_config_prop(Constant.RESULT_CLIENTS) + + if not isinstance(targets, list): + self.log_warning(fl_ctx, f"expected targets of result clients to be type list, but got {type(targets)}") + return None + + if self.me in targets: + targets.remove(self.me) + + if len(targets) == 0: + # no targets to receive the result! + self.log_info(fl_ctx, "no targets to receive final result") + return None + + shareable = Shareable() + shareable[Constant.RESULT] = result + + self.log_info(fl_ctx, f"broadcasting final result to clients {targets}") + + self.update_status(action="broadcast_final_result") + + task = Task( + name=self.report_final_result_task_name, + data=shareable, + timeout=int(self.final_result_ack_timeout), + secure=self.is_task_secure(fl_ctx), + ) + + resp = self.controller.broadcast_and_wait( + task=task, + targets=targets, + min_responses=len(targets), + fl_ctx=fl_ctx, + ) + + if not isinstance(resp, dict): + self.log_error(fl_ctx, f"bad response for final result from clients, expected dict but got {type(resp)}") + return + + num_errors = 0 + for t in targets: + reply = resp.get(t) + if not isinstance(reply, Shareable): + self.log_error( + fl_ctx, + f"bad response for final result from client {t}: " f"reply must be Shareable but got {type(reply)}", + ) + num_errors += 1 + continue + + rc = reply.get_return_code(ReturnCode.OK) + if rc != ReturnCode.OK: + self.log_error(fl_ctx, f"bad response for final result from client {t}: {rc}") + num_errors += 1 + + if num_errors == 0: + self.log_info(fl_ctx, f"successfully broadcast final result to {targets}") + return num_errors diff --git a/nvflare/app_common/ccwf/common.py b/nvflare/app_common/ccwf/common.py index e1883fbe24..27ac91b381 100644 --- a/nvflare/app_common/ccwf/common.py +++ b/nvflare/app_common/ccwf/common.py @@ -87,6 +87,7 @@ class Constant: LEARN_TASK_ABORT_TIMEOUT = 5.0 FINAL_RESULT_ACK_TIMEOUT = 10 GET_MODEL_TIMEOUT = 10 + MAX_TASK_TIMEOUT = 3600 PROP_KEY_TRAIN_CLIENTS = "cwf.train_clients" diff --git a/nvflare/app_common/ccwf/server_ctl.py b/nvflare/app_common/ccwf/server_ctl.py index 82f6499183..01365113c6 100644 --- a/nvflare/app_common/ccwf/server_ctl.py +++ b/nvflare/app_common/ccwf/server_ctl.py @@ -14,6 +14,7 @@ import time from datetime import datetime +from typing import List from nvflare.apis.client import Client from nvflare.apis.controller_spec import ClientTask, Task @@ -57,7 +58,7 @@ def __init__(self): class ServerSideController(Controller): def __init__( self, - num_rounds: int, + num_rounds: int = 1, start_round: int = 0, task_name_prefix: str = "wf", configure_task_timeout=Constant.CONFIG_TASK_TIMEOUT, @@ -65,10 +66,10 @@ def __init__( start_task_timeout=Constant.START_TASK_TIMEOUT, task_check_period: float = Constant.TASK_CHECK_INTERVAL, job_status_check_interval: float = Constant.JOB_STATUS_CHECK_INTERVAL, - starting_client=None, + starting_client: str = "", starting_client_policy: str = DefaultValuePolicy.ANY, participating_clients=None, - result_clients=None, + result_clients: List[str] = [], result_clients_policy: str = DefaultValuePolicy.ALL, max_status_report_interval: float = Constant.PER_CLIENT_STATUS_REPORT_TIMEOUT, progress_timeout: float = Constant.WORKFLOW_PROGRESS_TIMEOUT, @@ -78,7 +79,7 @@ def __init__( Constructor Args: - num_rounds - the number of rounds to be performed. This is a workflow config parameter. + num_rounds - the number of rounds to be performed. This is a workflow config parameter. Defaults to 1. start_round - the starting round number. This is a workflow config parameter. task_name_prefix - the prefix for task names of this workflow. The workflow requires multiple tasks (e.g. config and start) between the server controller and the client. @@ -97,7 +98,8 @@ def __init__( starting_client - name of the starting client. starting_client_policy - how to determine the starting client if the name is not explicitly specified. Possible values are: - ANY - any one of the participating clients (randomly chosen) + ANY - any one of the participating clients (the first client) + RANDOM - a random client EMPTY - no starting client DISALLOW - does not allow implicit - starting_client must be explicitly specified start_task_timeout - how long to wait for the starting client to finish the “start” task. @@ -182,6 +184,7 @@ def start_controller(self, fl_ctx: FLContext): allow_none=False, ) + self.log_info(fl_ctx, f"Using participating clients: {self.participating_clients}") self.starting_client = validate_candidate( var_name="starting_client", candidate=self.starting_client, @@ -189,6 +192,7 @@ def start_controller(self, fl_ctx: FLContext): default_policy=self.starting_client_policy, allow_none=True, ) + self.log_info(fl_ctx, f"Starting client: {self.starting_client}") self.result_clients = validate_candidates( var_name="result_clients", diff --git a/nvflare/app_common/workflows/model_controller.py b/nvflare/app_common/workflows/model_controller.py index d5db8215e3..8d511b9805 100644 --- a/nvflare/app_common/workflows/model_controller.py +++ b/nvflare/app_common/workflows/model_controller.py @@ -63,7 +63,7 @@ def __init__( raise ValueError("task_check_period must be greater than 0.") self._task_check_period = task_check_period self._persistor_id = persistor_id - self._persistor = None + self.persistor = None # config data self._ignore_result_error = ignore_result_error @@ -77,13 +77,13 @@ def start_controller(self, fl_ctx: FLContext) -> None: self.info("Initializing ModelController workflow.") if self._persistor_id: - self._persistor = self._engine.get_component(self._persistor_id) - if not isinstance(self._persistor, LearnablePersistor): + self.persistor = self._engine.get_component(self._persistor_id) + if not isinstance(self.persistor, LearnablePersistor): self.warning( f"Model Persistor {self._persistor_id} must be a LearnablePersistor type object, " - f"but got {type(self._persistor)}" + f"but got {type(self.persistor)}" ) - self._persistor = None + self.persistor = None self.engine = self.fl_ctx.get_engine() FLComponentWrapper.initialize(self) @@ -292,9 +292,9 @@ def control_flow(self, abort_signal: Signal, fl_ctx: FLContext) -> None: def load_model(self): # initialize global model model = None - if self._persistor: + if self.persistor: self.info("loading initial model from persistor") - global_weights = self._persistor.load(self.fl_ctx) + global_weights = self.persistor.load(self.fl_ctx) if not isinstance(global_weights, ModelLearnable): self.panic( @@ -332,12 +332,12 @@ def load_model(self): return model def save_model(self, model): - if self._persistor: + if self.persistor: self.info("Start persist model on server.") self.event(AppEventType.BEFORE_LEARNABLE_PERSIST) # persistor uses Learnable format to save model ml = make_model_learnable(weights=model.params, meta_props=model.meta) - self._persistor.save(ml, self.fl_ctx) + self.persistor.save(ml, self.fl_ctx) self.event(AppEventType.AFTER_LEARNABLE_PERSIST) self.info("End persist model on server.") else: diff --git a/nvflare/fuel/utils/validation_utils.py b/nvflare/fuel/utils/validation_utils.py index 774638050e..45d2abaa8c 100644 --- a/nvflare/fuel/utils/validation_utils.py +++ b/nvflare/fuel/utils/validation_utils.py @@ -12,6 +12,8 @@ # See the License for the specific language governing permissions and # limitations under the License. +import random + SYMBOL_ALL = "@all" SYMBOL_NONE = "@none" @@ -24,12 +26,13 @@ class DefaultValuePolicy: DISALLOW = "disallow" ANY = "any" + RANDOM = "random" EMPTY = "empty" ALL = "all" @classmethod def valid_policy(cls, p: str): - return p in [cls.DISALLOW, cls.ANY, cls.EMPTY, cls.ALL] + return p in [cls.DISALLOW, cls.ANY, cls.RANDOM, cls.EMPTY, cls.ALL] def check_positive_int(name, value): @@ -144,6 +147,7 @@ def validate_candidates(var_name: str, candidates, base: list, default_policy: s 1. Not explicitly specified (Python object None or empty list []) In this case, the default_policy decides the final result: - ANY: returns a list that contains a single item from the base + - RANDOM: returns a list that contains a random item from the base - EMPTY: returns an empty list - ALL: returns the base list - DISALLOW: raise exception - candidates must be explicitly specified @@ -189,6 +193,8 @@ def validate_candidates(var_name: str, candidates, base: list, default_policy: s return base elif default_policy == DefaultValuePolicy.DISALLOW: raise ValueError(f"invalid value '{candidates}' in '{var_name}': it must be subset of {base}") + elif default_policy == DefaultValuePolicy.RANDOM: + return [random.choice(base)] else: # any return [base[0]] @@ -222,6 +228,7 @@ def validate_candidate(var_name: str, candidate, base: list, default_policy: str 1. Not explicitly specified (Python object None or empty string) In this case, the default_policy decides the final result: - ANY: returns the first item from the base + - RANDOM: returns a random item from the base - EMPTY: returns an empty str - ALL or DISALLOW: raise exception - candidate must be explicitly specified @@ -263,6 +270,8 @@ def validate_candidate(var_name: str, candidate, base: list, default_policy: str return "" elif default_policy == DefaultValuePolicy.ANY: return base[0] + elif default_policy == DefaultValuePolicy.RANDOM: + return random.choice(base) else: raise ValueError(f"invalid value '{candidate}' in '{var_name}': it must be one of {base}") else: diff --git a/nvflare/private/fed/client/client_run_manager.py b/nvflare/private/fed/client/client_run_manager.py index b92766047a..7c15dd57ca 100644 --- a/nvflare/private/fed/client/client_run_manager.py +++ b/nvflare/private/fed/client/client_run_manager.py @@ -175,6 +175,12 @@ def get_client_from_name(self, client_name): return c return None + def get_clients(self): + return list(self.all_clients.values()) + + def persist_components(self, fl_ctx: FLContext, completed: bool): + self.logger.warning(f"will not persist components, not supported by {self.__class__.__name__}") + def get_widget(self, widget_id: str) -> Widget: return self.widgets.get(widget_id) diff --git a/nvflare/private/fed/utils/fed_utils.py b/nvflare/private/fed/utils/fed_utils.py index 2eddb292b5..c069d91324 100644 --- a/nvflare/private/fed/utils/fed_utils.py +++ b/nvflare/private/fed/utils/fed_utils.py @@ -314,7 +314,7 @@ def get_target_names(targets): continue if name not in target_names: - target_names.append(t) + target_names.append(name) return target_names From 3f64939ddb1beec9804c6fb613b5d5e1dd20bbc3 Mon Sep 17 00:00:00 2001 From: Isaac Yang Date: Wed, 8 May 2024 09:01:53 -0700 Subject: [PATCH 07/15] Add option in dashboard cli for AWS vpc and subnet --- nvflare/dashboard/cli.py | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/nvflare/dashboard/cli.py b/nvflare/dashboard/cli.py index a3dbea95d8..2c18cdae0c 100644 --- a/nvflare/dashboard/cli.py +++ b/nvflare/dashboard/cli.py @@ -153,7 +153,11 @@ def cloud(args): "t", exe=True, ) - print(f"Dashboard launch script for cloud is written at {dest}. Now running the script.") + print(f"Dashboard launch script for cloud is written at {dest}. Now running it.") + if args.vpc_id and args.subnet_id: + option = [f"--vpc-id={args.vpc_id}", f"--subnet-id={args.subnet_id}"] + print(f"Option of the script: {option}") + dest = [dest] + option _ = subprocess.run(dest) os.remove(dest) @@ -192,6 +196,18 @@ def define_dashboard_parser(parser): parser.add_argument("--cred", help="set credential directly in the form of USER_EMAIL:PASSWORD") parser.add_argument("-i", "--image", help="set the container image name") parser.add_argument("--local", action="store_true", help="start dashboard locally without docker image") + parser.add_argument( + "--vpc-id", + type=str, + default="", + help="VPC id for AWS EC2 instance. Applicable to AWS only. Ignored if subnet-id is not specified.", + ) + parser.add_argument( + "--subnet-id", + type=str, + default="", + help="Subnet id for AWS EC2 instance. Applicable to AWS only. Ignored if vpc-id is not specified.", + ) def handle_dashboard(args): From 75187e00d0c5c03e5acd0bff3d9632d1ee3e0467 Mon Sep 17 00:00:00 2001 From: Yan Cheng <58191769+yanchengnv@users.noreply.github.com> Date: Thu, 9 May 2024 15:44:12 -0400 Subject: [PATCH 08/15] [2.5] Clean up to allow creation of nvflare light (#2573) * clean up to allow creation of nvflare light * move defs to cellnet --- nvflare/client/ipc/ipc_agent.py | 9 ++++++-- nvflare/fuel/f3/cellnet/cell.py | 3 +-- nvflare/fuel/f3/cellnet/defs.py | 36 +++++++++++++++++++++++++++++++ nvflare/private/defs.py | 38 ++------------------------------- 4 files changed, 46 insertions(+), 40 deletions(-) diff --git a/nvflare/client/ipc/ipc_agent.py b/nvflare/client/ipc/ipc_agent.py index e7b104cc96..6f527c50c1 100644 --- a/nvflare/client/ipc/ipc_agent.py +++ b/nvflare/client/ipc/ipc_agent.py @@ -104,8 +104,13 @@ def __init__( self.cell.register_request_cb(channel=defs.CHANNEL, topic=defs.TOPIC_HEARTBEAT, cb=self._handle_heartbeat) self.cell.register_request_cb(channel=defs.CHANNEL, topic=defs.TOPIC_BYE, cb=self._handle_bye) self.cell.register_request_cb(channel=defs.CHANNEL, topic=defs.TOPIC_ABORT, cb=self._handle_abort_task) - self.cell.add_incoming_request_filter( - channel=defs.CHANNEL, + self.cell.core_cell.add_incoming_request_filter( + channel="*", + topic="*", + cb=self._msg_received, + ) + self.cell.core_cell.add_incoming_reply_filter( + channel="*", topic="*", cb=self._msg_received, ) diff --git a/nvflare/fuel/f3/cellnet/cell.py b/nvflare/fuel/f3/cellnet/cell.py index 723b894f75..8544e733cb 100644 --- a/nvflare/fuel/f3/cellnet/cell.py +++ b/nvflare/fuel/f3/cellnet/cell.py @@ -20,13 +20,12 @@ from typing import Dict, List, Union from nvflare.fuel.f3.cellnet.core_cell import CoreCell, TargetMessage -from nvflare.fuel.f3.cellnet.defs import MessageHeaderKey, MessageType, ReturnCode +from nvflare.fuel.f3.cellnet.defs import CellChannel, MessageHeaderKey, MessageType, ReturnCode from nvflare.fuel.f3.cellnet.utils import decode_payload, encode_payload, make_reply from nvflare.fuel.f3.message import Message from nvflare.fuel.f3.stream_cell import StreamCell from nvflare.fuel.f3.streaming.stream_const import StreamHeaderKey from nvflare.fuel.f3.streaming.stream_types import StreamFuture -from nvflare.private.defs import CellChannel from nvflare.security.logging import secure_format_exception CHANNELS_TO_EXCLUDE = ( diff --git a/nvflare/fuel/f3/cellnet/defs.py b/nvflare/fuel/f3/cellnet/defs.py index de86aeed3e..bb4c4d0971 100644 --- a/nvflare/fuel/f3/cellnet/defs.py +++ b/nvflare/fuel/f3/cellnet/defs.py @@ -135,3 +135,39 @@ class AbortRun(Exception): class InvalidRequest(Exception): pass + + +class SSLConstants: + """hard coded names related to SSL.""" + + CERT = "ssl_cert" + PRIVATE_KEY = "ssl_private_key" + ROOT_CERT = "ssl_root_cert" + + +class CellChannel: + + CLIENT_MAIN = "admin" + AUX_COMMUNICATION = "aux_communication" + SERVER_MAIN = "task" + SERVER_COMMAND = "server_command" + SERVER_PARENT_LISTENER = "server_parent_listener" + CLIENT_COMMAND = "client_command" + CLIENT_SUB_WORKER_COMMAND = "client_sub_worker_command" + MULTI_PROCESS_EXECUTOR = "multi_process_executor" + SIMULATOR_RUNNER = "simulator_runner" + RETURN_ONLY = "return_only" + + +class CellChannelTopic: + + Register = "register" + Quit = "quit" + GET_TASK = "get_task" + SUBMIT_RESULT = "submit_result" + HEART_BEAT = "heart_beat" + EXECUTE_RESULT = "execute_result" + FIRE_EVENT = "fire_event" + REPORT_JOB_FAILURE = "report_job_failure" + + SIMULATOR_WORKER_INIT = "simulator_worker_init" diff --git a/nvflare/private/defs.py b/nvflare/private/defs.py index 6ae5c7fd8c..6ccc6895ab 100644 --- a/nvflare/private/defs.py +++ b/nvflare/private/defs.py @@ -12,6 +12,8 @@ # See the License for the specific language governing permissions and # limitations under the License. +# this import is to let existing scripts import from nvflare.private.defs +from nvflare.fuel.f3.cellnet.defs import CellChannel, CellChannelTopic, SSLConstants # noqa: F401 from nvflare.fuel.f3.message import Message from nvflare.fuel.hci.server.constants import ConnProps @@ -128,42 +130,6 @@ class AppFolderConstants: CONFIG_ENV = "environment.json" -class SSLConstants: - """hard coded names related to SSL.""" - - CERT = "ssl_cert" - PRIVATE_KEY = "ssl_private_key" - ROOT_CERT = "ssl_root_cert" - - -class CellChannel: - - CLIENT_MAIN = "admin" - AUX_COMMUNICATION = "aux_communication" - SERVER_MAIN = "task" - SERVER_COMMAND = "server_command" - SERVER_PARENT_LISTENER = "server_parent_listener" - CLIENT_COMMAND = "client_command" - CLIENT_SUB_WORKER_COMMAND = "client_sub_worker_command" - MULTI_PROCESS_EXECUTOR = "multi_process_executor" - SIMULATOR_RUNNER = "simulator_runner" - RETURN_ONLY = "return_only" - - -class CellChannelTopic: - - Register = "register" - Quit = "quit" - GET_TASK = "get_task" - SUBMIT_RESULT = "submit_result" - HEART_BEAT = "heart_beat" - EXECUTE_RESULT = "execute_result" - FIRE_EVENT = "fire_event" - REPORT_JOB_FAILURE = "report_job_failure" - - SIMULATOR_WORKER_INIT = "simulator_worker_init" - - ERROR_MSG_PREFIX = "NVFLARE_ERROR" From 8fd1aa90d7973068e433d188020a1313dc1681fd Mon Sep 17 00:00:00 2001 From: Isaac Yang Date: Thu, 9 May 2024 15:24:46 -0700 Subject: [PATCH 09/15] Enable patch and build for nvflight (#2574) --- nvflight/__init__.py | 13 +++ nvflight/build_wheel.py | 79 ++++++++++++++++ nvflight/patch.diff | 27 ++++++ nvflight/prepare_setup.py | 186 ++++++++++++++++++++++++++++++++++++++ nvflight/setup.py | 54 +++++++++++ 5 files changed, 359 insertions(+) create mode 100644 nvflight/__init__.py create mode 100644 nvflight/build_wheel.py create mode 100644 nvflight/patch.diff create mode 100644 nvflight/prepare_setup.py create mode 100644 nvflight/setup.py diff --git a/nvflight/__init__.py b/nvflight/__init__.py new file mode 100644 index 0000000000..4fc50543f1 --- /dev/null +++ b/nvflight/__init__.py @@ -0,0 +1,13 @@ +# Copyright (c) 2023, NVIDIA CORPORATION. All rights reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. diff --git a/nvflight/build_wheel.py b/nvflight/build_wheel.py new file mode 100644 index 0000000000..312bcfbe45 --- /dev/null +++ b/nvflight/build_wheel.py @@ -0,0 +1,79 @@ +# Copyright (c) 2023, NVIDIA CORPORATION. All rights reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +import datetime +import os +import shutil +import subprocess + +from prepare_setup import prepare_setup + +import versioneer + +versions = versioneer.get_versions() +if versions["error"]: + today = datetime.date.today().timetuple() + year = today[0] % 1000 + month = today[1] + day = today[2] + version = f"2.3.9.dev{year:02d}{month:02d}{day:02d}" +else: + version = versions["version"] + + +def patch(setup_dir, patch_file): + file_dir_path = os.path.abspath(os.path.dirname(__file__)) + cmd = ['git', 'apply', os.path.join(file_dir_path, patch_file)] + try: + subprocess.run(cmd, check=True, cwd=setup_dir) + except subprocess.CalledProcessError as e: + print(f"Error to patch prepared files {e}") + exit(1) + +nvflight_setup_dir = "/tmp/nvflight_setup" +patch_file = "patch.diff" +# prepare +prepare_setup(nvflight_setup_dir) + +patch(nvflight_setup_dir, patch_file) +# build wheel +dist_dir = os.path.join(nvflight_setup_dir, "dist") +if os.path.isdir(dist_dir): + shutil.rmtree(dist_dir) + +env = os.environ.copy() +env['NVFL_VERSION'] = version + +cmd_str = "python setup.py -v sdist bdist_wheel" +cmd = cmd_str.split(" ") +try: + subprocess.run(cmd, check=True, cwd=nvflight_setup_dir, env=env) +except subprocess.CalledProcessError as e: + print(f"Error: {e}") + +results = [] +for root, dirs, files in os.walk(dist_dir): + result = [os.path.join(root, f) for f in files if f.endswith(".whl")] + results.extend(result) + +if not os.path.isdir("dist"): + os.makedirs("dist", exist_ok=True) + +if len(results) == 1: + shutil.copy(results[0], os.path.join("dist", os.path.basename(results[0]))) +else: + print(f"something is not right, wheel files = {results}") + +print(f"Setup dir {nvflight_setup_dir}") +shutil.rmtree(nvflight_setup_dir) diff --git a/nvflight/patch.diff b/nvflight/patch.diff new file mode 100644 index 0000000000..b65b48fbcc --- /dev/null +++ b/nvflight/patch.diff @@ -0,0 +1,27 @@ +diff --git a/nvflare/client/__init__.py b/nvflare/client/__init__.py +index 8d668962..7bcb2978 100644 +--- a/nvflare/client/__init__.py ++++ b/nvflare/client/__init__.py +@@ -15,22 +15,4 @@ + + # https://github.com/microsoft/pylance-release/issues/856 + +-from nvflare.apis.analytix import AnalyticsDataType as AnalyticsDataType +-from nvflare.app_common.abstract.fl_model import FLModel as FLModel +-from nvflare.app_common.abstract.fl_model import ParamsType as ParamsType +- +-from .api import get_config as get_config +-from .api import get_job_id as get_job_id +-from .api import get_site_name as get_site_name +-from .api import init as init +-from .api import is_evaluate as is_evaluate +-from .api import is_running as is_running +-from .api import is_submit_model as is_submit_model +-from .api import is_train as is_train +-from .api import log as log +-from .api import receive as receive +-from .api import send as send +-from .api import system_info as system_info +-from .decorator import evaluate as evaluate +-from .decorator import train as train + from .ipc.ipc_agent import IPCAgent diff --git a/nvflight/prepare_setup.py b/nvflight/prepare_setup.py new file mode 100644 index 0000000000..94514789fe --- /dev/null +++ b/nvflight/prepare_setup.py @@ -0,0 +1,186 @@ +# Copyright (c) 2023, NVIDIA CORPORATION. All rights reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + + +import os +import shutil + +exclude_extensions = [".md", ".rst", ".pyc", "__pycache__"] + +nvflight_packages = { + "nvflare": { + "include": ["_version.py"], + "exclude": ["*"] + }, + "nvflare/apis": { + "include": ["__init__.py", "fl_constant.py"], + "exclude": ["*"] + }, + "nvflare/app_common": { + "include": ["__init__.py"], + "exclude": ["*"] + }, + "nvflare/app_common/decomposers": { + "include": ["__init__.py", "numpy_decomposers.py"], + "exclude": ["*"] + }, + "nvflare/client": { + "include": ["__init__.py"], + "exclude": ["*"] + }, + "nvflare/client/ipc": { + "include": ["__init__.py", "defs.py", "ipc_agent.py"], + "exclude": ["*"] + }, + "nvflare/fuel": { + "include": ["__init__.py"], + "exclude": ["*"] + }, + "nvflare/fuel/common": { + "include": ["*"], + "exclude": [] + }, + "nvflare/fuel/f3": { + "include": ["__init__.py", + "comm_error.py", + "connection.py", + "endpoint.py", + "mpm.py", + "stats_pool.py", + "comm_config.py", + "communicator.py", + "message.py", + "stream_cell.py" + ], + "exclude": ["*"] + }, + "nvflare/fuel/f3/cellnet": { + "include": ["*"], + "exclude": [] + }, + "nvflare/fuel/f3/drivers": { + "include": ["*"], + "exclude": ["grpc", "aio_grpc_driver.py", "aio_http_driver.py", "grpc_driver.py"] + }, + "nvflare/fuel/f3/sfm": { + "include": ["*"], + "exclude": [] + }, + "nvflare/fuel/f3/streaming": { + "include": ["*"], + "exclude": [] + }, + "nvflare/fuel/hci": { + "include": ["__init__.py", "security.py"], + "exclude": ["*"] + }, + "nvflare/fuel/utils": { + "include": ["*"], + "exclude": ["fobs"] + }, + "nvflare/fuel/utils/fobs": { + "include": ["*"], + "exclude": [] + }, + "nvflare/fuel/utils/fobs/decomposers": { + "include": ["*"], + "exclude": [] + }, + "nvflare/security": { + "include": ["__init__.py", "logging.py"], + "exclude": ["*"] + } +} + + +def should_exclude(str_value): + return any(str_value.endswith(ext) for ext in exclude_extensions) + + +def package_selected_files(package_info: dict): + if not package_info: + return + all_items = "*" + results = {} + + for p, package_rule in package_info.items(): + include = package_rule["include"] + exclude = package_rule["exclude"] + paths = [] + for include_item in include: + item_path = os.path.join(p, include_item) + if all_items != include_item: + if all_items in exclude: + # excluded everything except for included items + if os.path.isfile(item_path) and not should_exclude(item_path): + paths.append(item_path) + elif include_item not in exclude: + paths.append(item_path) + else: + if all_items in exclude: + # excluded everything except for included items + if os.path.isfile(item_path): + paths.append(item_path) + else: + # include everything in the package except excluded items + for root, dirs, files in os.walk(p): + if should_exclude(root) or os.path.basename(root) in exclude: + continue + + for f in files: + if not should_exclude(f) and f not in exclude: + paths.append(os.path.join(root, f)) + results[p] = paths + return results + + +def create_empty_file(file_path): + try: + with open(file_path, 'w'): + pass # This block is intentionally left empty + except Exception as e: + print(f"Error creating empty file: {e}") + + +def copy_files(package_paths: dict, target_dir: str): + for p, paths in package_paths.items(): + for src_path in paths: + dst_path = os.path.join(target_dir, src_path) + os.makedirs(os.path.dirname(dst_path), exist_ok=True) + shutil.copy(src_path, dst_path) + + for p in package_paths: + init_file_path = os.path.join(target_dir, p, "__init__.py") + if not os.path.isfile(init_file_path): + create_empty_file(init_file_path) + + +def prepare_setup(setup_dir: str): + if os.path.isdir(setup_dir): + shutil.rmtree(setup_dir) + + os.makedirs(setup_dir, exist_ok=True) + nvflight_paths = package_selected_files(nvflight_packages) + copy_files(nvflight_paths, setup_dir) + + src_files = [ + "setup.cfg", + "README.md", + "LICENSE", + os.path.join("nvflight", "setup.py") + ] + + for src in src_files: + shutil.copy(src, os.path.join(setup_dir, os.path.basename(src))) + diff --git a/nvflight/setup.py b/nvflight/setup.py new file mode 100644 index 0000000000..1aea531751 --- /dev/null +++ b/nvflight/setup.py @@ -0,0 +1,54 @@ +# Copyright (c) 2023, NVIDIA CORPORATION. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +import datetime +import os + +from setuptools import find_packages, setup + +this_directory = os.path.abspath(os.path.dirname(__file__)) + +today = datetime.date.today().timetuple() +year = today[0] % 1000 +month = today[1] +day = today[2] + +release_package = find_packages( + where=".", + include=[ + "*", + ], + exclude=["tests", "tests.*"], +) + +package_data = {"": ["*.yml", "*.config"], } + +release = os.environ.get("NVFL_RELEASE") +version = os.environ.get("NVFL_VERSION") + +if release == "1": + package_dir = {"nvflare": "nvflare"} + package_name = "nvflare-light" +else: + package_dir = {"nvflare": "nvflare"} + package_name = "nvflare-light-nightly" + +setup( + name=package_name, + version=version, + package_dir=package_dir, + packages=release_package, + package_data=package_data, + include_package_data=True, +) From 297a079cd0d7d88a947b48439b8704f50891edd4 Mon Sep 17 00:00:00 2001 From: Minghui Chen <50226876+MinghuiChen43@users.noreply.github.com> Date: Sat, 11 May 2024 04:05:23 +0800 Subject: [PATCH 10/15] add FedBN Implementation on NVFlare research folder - a local batch normalization federated learning method (#2524) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * add research/fedbn * delete redudant controller and correct figs requirements * update plot_requirements * rewrite fedbn * update jobs * remove workspace * update README * simplify job simulator_run to take only one workspace parameter. (#2528) * Add missing client api test jobs (#2535) * Fixed the simulator server workspace root dir (#2533) * Fixed the simulator server root dir error. * Added unit test for SimulatorRunner start_server_app. --------- Co-authored-by: Chester Chen <512707+chesterxgchen@users.noreply.github.com> * Improve InProcessClientAPIExecutor (#2536) * 1. rename ExeTaskFnWrapper class to TaskScriptRunner 2. Replace implementation of the inprocess function exection from calling a main() function to user runpy.run_path() which reduce the user requirements to have main() function 3. redirect print() to logger.info() * 1. rename ExeTaskFnWrapper class to TaskScriptRunner 2. Replace implementation of the inprocess function exection from calling a main() function to user runpy.run_path() which reduce the user requirements to have main() function 3. redirect print() to logger.info() * make result check and result pull use the same configurable variable * rename exec_task_fn_wrapper to task_script_runner.py * fix typo * FIX MLFLow and Tensorboard Output to be consistent with new Workspace root changes (#2537) * 1) fix mlruns and tb_events dirs due to workspace directory changes 2) for MLFLow, add tracking_rui default to workspace_dir / /mlruns instead current default /mlruns. This is a) consistent with Tensorboard 2) avoid job output oeverwrite the 1st job * 1) fix mlruns and tb_events dirs due to workspace directory changes 2) for MLFLow, add tracking_rui default to workspace_dir / /mlruns instead current default /mlruns. This is a) consistent with Tensorboard 2) avoid job output oeverwrite the 1st job * 1) fix mlruns and tb_events dirs due to workspace directory changes 2) for MLFLow, add tracking_rui default to workspace_dir / /mlruns instead current default /mlruns. This is a) consistent with Tensorboard 2) avoid job output oeverwrite the 1st job * 1. Remove the default code to use configuration 2. fix some broken notebook * rollback changes * Fix decorator issue (#2542) * update create and run job script * FLModel summary (#2544) * add FLModel Summary * format * remove jobs folder * expose aggregate_fn to users for overwriting (#2539) * handle cases where the script with relative path in Script Runner (#2543) * handle cases where the script with relative path * handle cases where the script with relative path * add more unit test cases and change the file search logics * code format * add more unit test cases and change the file search logics * Lr newton raphson (#2529) * Implement federated logistic regression with second-order newton raphson. Update file headers. Update README. Update README. Fix README. Refine README. Update README. Added more logging for the job status changing. (#2480) * Added more logging for the job status changing. * Fixed a logging call error. --------- Co-authored-by: Chester Chen <512707+chesterxgchen@users.noreply.github.com> Co-authored-by: Yuan-Ting Hsieh (謝沅廷) Fix update client status (#2508) * check workflow id before updating client status * change order of checks Add user guide on how to deploy to EKS (#2510) * Add user guide on how to deploy to EKS * Address comments Improve dead client handling (#2506) * dev * test dead client cmd * added more info for dead client tracing * remove unused imports * fix unit test * fix test case * address PR comments --------- Co-authored-by: Sean Yang Enhance WFController (#2505) * set flmodel variables in basefedavg * make round info optional, fix inproc api bug temporarily disable preflight tests (#2521) Upgrade dependencies (#2516) Use full path for PSI components (#2437) (#2517) Multiple bug fixes from 2.4 (#2518) * [2.4] Support client custom code in simulator (#2447) * Support client custom code in simulator * Fix client custom code * Remove cancel_futures args (#2457) * Fix sub_worker_process shutdown (#2458) * Set GRPC_ENABLE_FORK_SUPPORT to False (#2474) Pythonic job creation (#2483) * WIP: constructed the FedJob. * WIP: server_app josn export. * generate the job app config. * fully functional pythonic job creation. * Added simulator_run for pythonic API. * reformat. * Added filters support for pythonic job creation. * handled the direct import case in fed_job. * refactor. * Added the resource_spec set function for FedJob. * refactored. * Moved the ClientApp and ServerApp into fed_app.py. * Refactored: removed the _FilterDef class. * refactored. * Rename job config classes (#3) * rename config related classes * add client api example * fix metric streaming * add to() routine * Enable obj in the constructor as paramenter. * Added support for the launcher script. * refactored. * reformat. * Update the comment. * re-arrange the package location. * Added add_ext_script() for BaseAppConfig. * codestyle fix. * Removed the client-api-pt example. * removed no used import. * fixed the in_time_accumulate_weighted_aggregator_test.py * Added Enum parameter support. * Added docstring. * Added ability to handle parameters from base class. * Move the parameter data format conversion to the START_RUN event for InProcessClientAPIExecutor. * Added params_exchange_format for PTInProcessClientAPIExecutor. * codestyle fix. * Fixed a custom code folder structure issue. * work for sub-folder custom files. * backed to handle parameters from base classes. * Support folder structure job config. * Added support for flat folder from '.XXX' import. * codestyle fix. * refactored and add docstring. * Address some of the PR reviews. --------- Co-authored-by: Holger Roth <6304754+holgerroth@users.noreply.github.com> Co-authored-by: Yuan-Ting Hsieh (謝沅廷) Co-authored-by: Chester Chen <512707+chesterxgchen@users.noreply.github.com> Enhancements from 2.4 (#2519) * Starts heartbeat after task is pull and before task execution (#2415) * Starts pipe handler heartbeat send/check after task is pull before task execution (#2442) * [2.4] Improve cell pipe timeout handling (#2441) * improve cell pipe timeout handling * improved end and abort handling * improve timeout handling --------- Co-authored-by: Yuan-Ting Hsieh (謝沅廷) * [2.4] Enhance launcher executor (#2433) * Update LauncherExecutor logs and execution setup timeout * Change name * [2.4] Fire and forget for pipe handler control messages (#2413) * Fire and forget for pipe handler control messages * Add default timeout value * fix wait-for-reply (#2478) * Fix pipe handler timeout in task exchanger and launcher executor (#2495) * Fix metric relay pipe handler timeout (#2496) * Rely on launcher check_run_status to pause/resume hb (#2502) Co-authored-by: Chester Chen <512707+chesterxgchen@users.noreply.github.com> --------- Co-authored-by: Yan Cheng <58191769+yanchengnv@users.noreply.github.com> Co-authored-by: Chester Chen <512707+chesterxgchen@users.noreply.github.com> Update ci cd from 2.4 (#2520) * Update github actions (#2450) * Fix premerge (#2467) * Fix issues on hello-world TF2 notebook * Fix tf integration test (#2504) * Add client api integration tests --------- Co-authored-by: Isaac Yang Co-authored-by: Sean Yang use controller name for stats (#2522) Simulator workspace re-design (#2492) * Redesign simulator workspace structure. * working, needs clean. * Changed the simulator workspacce structure to be consistent with POC. * Moved the logfile init to start_server_app(). * optimzed. * adjust the stats pool location. * Addressed the PR views. --------- Co-authored-by: Chester Chen <512707+chesterxgchen@users.noreply.github.com> Co-authored-by: Yuan-Ting Hsieh (謝沅廷) Simulator end run for all clients (#2514) * Provide an option to run END_RUN for all clients. * Added end_run_all option for simulator to run END_RUN event for all clients. * Fixed a add_argument type, added help message. * Changed to use add_argument(() compatible with python 3.8. * reformat. * rewrite the _end_run_clients() and add docstring for easier understanding. * reformat. * adjusting the locking in the _end_run_clients. * Fixed a potential None pointer error. * renamed the clients_finished_end_run variable. --------- Co-authored-by: Chester Chen <512707+chesterxgchen@users.noreply.github.com> Co-authored-by: Sean Yang Co-authored-by: Yuan-Ting Hsieh (謝沅廷) Secure XGBoost Integration (#2512) * Updated FOBS readme to add DatumManager, added agrpcs as secure scheme * Refactoring * Refactored the secure version to histogram_based_v2 * Replaced Paillier with a mock encryptor * Added license header * Put mock back * Added metrics_writer back and fixed GRPC error reply simplify job simulator_run to take only one workspace parameter. (#2528) Fix README. Fix file links in README. Fix file links in README. Add comparison between centralized and federated training code. Add missing client api test jobs (#2535) Fixed the simulator server workspace root dir (#2533) * Fixed the simulator server root dir error. * Added unit test for SimulatorRunner start_server_app. --------- Co-authored-by: Chester Chen <512707+chesterxgchen@users.noreply.github.com> Improve InProcessClientAPIExecutor (#2536) * 1. rename ExeTaskFnWrapper class to TaskScriptRunner 2. Replace implementation of the inprocess function exection from calling a main() function to user runpy.run_path() which reduce the user requirements to have main() function 3. redirect print() to logger.info() * 1. rename ExeTaskFnWrapper class to TaskScriptRunner 2. Replace implementation of the inprocess function exection from calling a main() function to user runpy.run_path() which reduce the user requirements to have main() function 3. redirect print() to logger.info() * make result check and result pull use the same configurable variable * rename exec_task_fn_wrapper to task_script_runner.py * fix typo Update README for launching python script. Modify tensorboard logdir. Link to environment setup instructions. expose aggregate_fn to users for overwriting (#2539) FIX MLFLow and Tensorboard Output to be consistent with new Workspace root changes (#2537) * 1) fix mlruns and tb_events dirs due to workspace directory changes 2) for MLFLow, add tracking_rui default to workspace_dir / /mlruns instead current default /mlruns. This is a) consistent with Tensorboard 2) avoid job output oeverwrite the 1st job * 1) fix mlruns and tb_events dirs due to workspace directory changes 2) for MLFLow, add tracking_rui default to workspace_dir / /mlruns instead current default /mlruns. This is a) consistent with Tensorboard 2) avoid job output oeverwrite the 1st job * 1) fix mlruns and tb_events dirs due to workspace directory changes 2) for MLFLow, add tracking_rui default to workspace_dir / /mlruns instead current default /mlruns. This is a) consistent with Tensorboard 2) avoid job output oeverwrite the 1st job * 1. Remove the default code to use configuration 2. fix some broken notebook * rollback changes Fix decorator issue (#2542) Remove line number in code link. FLModel summary (#2544) * add FLModel Summary * format formatting Update KM example, add 2-stage solution without HE (#2541) * add KM without HE, update everything * fix license header * fix license header - update year to 2024 * fix format --------- Co-authored-by: Chester Chen <512707+chesterxgchen@users.noreply.github.com> * update license --------- Co-authored-by: Chester Chen <512707+chesterxgchen@users.noreply.github.com> Co-authored-by: Holger Roth * Add information about dig (bind9-dnsutils) in the document * format update * Update KM example, add 2-stage solution without HE (#2541) * add KM without HE, update everything * fix license header * fix license header - update year to 2024 * fix format --------- Co-authored-by: Chester Chen <512707+chesterxgchen@users.noreply.github.com> * Update monai readme to remove logging.conf (#2552) * MONAI mednist example (#2532) * add monai notebook * add training script * update example * update notebook * use job template * call init later * swith back * add gitignore * update notebooks * add readmes * send received model to GPU * use monai tb stats handler * formatting * Improve AWS cloud launch script * Add in process client api tests (#2549) * Add in process client api tests * Fix headers * Fix comments * Add client controller executor (#2530) * add client controller executor * address comments * enhance abort, set peer props * remove asserts --------- Co-authored-by: Yuan-Ting Hsieh (謝沅廷) * Add option in dashboard cli for AWS vpc and subnet * add note on README visualization * update README * update readme * update readme * update readme * [2.5] Clean up to allow creation of nvflare light (#2573) * clean up to allow creation of nvflare light * move defs to cellnet * Enable patch and build for nvflight (#2574) * verified commit --------- Co-authored-by: Yuhong Wen Co-authored-by: Yuan-Ting Hsieh (謝沅廷) Co-authored-by: Chester Chen <512707+chesterxgchen@users.noreply.github.com> Co-authored-by: Sean Yang Co-authored-by: Zhijin Co-authored-by: Holger Roth Co-authored-by: Isaac Yang Co-authored-by: Ziyue Xu Co-authored-by: Ziyue Xu <71786575+ZiyueXu77@users.noreply.github.com> Co-authored-by: Holger Roth <6304754+holgerroth@users.noreply.github.com> Co-authored-by: Yan Cheng <58191769+yanchengnv@users.noreply.github.com> --- research/fed-bn/LICENSE | 201 +++++++++++++++++++++++++++ research/fed-bn/README.md | 75 ++++++++++ research/fed-bn/create_job.sh | 1 + research/fed-bn/figs/loss.jpeg | Bin 0 -> 29518 bytes research/fed-bn/prepare_data.sh | 3 + research/fed-bn/requirements.txt | 4 + research/fed-bn/run_job.sh | 1 + research/fed-bn/src/fedbn_cifar10.py | 145 +++++++++++++++++++ research/fed-bn/src/net.py | 41 ++++++ 9 files changed, 471 insertions(+) create mode 100644 research/fed-bn/LICENSE create mode 100644 research/fed-bn/README.md create mode 100755 research/fed-bn/create_job.sh create mode 100644 research/fed-bn/figs/loss.jpeg create mode 100755 research/fed-bn/prepare_data.sh create mode 100644 research/fed-bn/requirements.txt create mode 100755 research/fed-bn/run_job.sh create mode 100644 research/fed-bn/src/fedbn_cifar10.py create mode 100644 research/fed-bn/src/net.py diff --git a/research/fed-bn/LICENSE b/research/fed-bn/LICENSE new file mode 100644 index 0000000000..261eeb9e9f --- /dev/null +++ b/research/fed-bn/LICENSE @@ -0,0 +1,201 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/research/fed-bn/README.md b/research/fed-bn/README.md new file mode 100644 index 0000000000..5e541d2235 --- /dev/null +++ b/research/fed-bn/README.md @@ -0,0 +1,75 @@ +# FedBN: Federated Learning on Non-IID Features via Local Batch Normalization + +Welcome to the repository for FedBN, a federated learning algorithm designed to address the feature shift problem when aggregating models across different data distributions. + +###### Abstract: + +> In this work, we propose an effective method that uses local batch normalization to alleviate the feature shift before averaging models. The resulting scheme, called FedBN, outperforms both classical FedAvg and FedProx on our extensive experiments. These empirical results are supported by a convergence analysis that shows in a simplified setting that FedBN has a faster convergence rate than FedAvg. + +## License +This project is open-sourced under the Apache v2 License. The codebase builds upon the initial work shared at [FedBN](https://github.com/med-air/FedBN). + +## Setup Instructions + +To set up the environment for training, execute the following commands: +``` +pip install --upgrade pip +pip install -r ./requirements.txt +``` + +## Running the code + +### Initial Configuration + +Ensure all shell scripts are executable: +``` +find . -name ".sh" -exec chmod +x {} \; +``` + +Set the Python path to recognize the FedBN modules: +``` +export PYTHONPATH=${PYTHONPATH}:${PWD}/.. +``` + +Data Preparation + +Download the necessary datasets by running: +``` +./prepare_data.sh +``` + +# Run FedBN on different data splits + +We will use the in-process client API, we choose the sag_pt job template and run the following command to create the job: +``` +./create_job.sh +``` + +Execution + +Run the FedBN simulation with the following command: +``` +./run_job.sh +``` + +## Visualizing Results +To visualize training losses, we use the [Comet ML](https://www.comet.com/site/). +Below is an example of the loss visualization output: +![FedBN Loss Results](./figs/loss.jpeg) + +> **Note**: To use Comet ML experiment tracking system, you need to get Comet API key to get access. +> Alternatively, you can use Tensorboard or MLfow. + +## Citation +If you find the code and dataset useful, please cite our paper. +```latex +@inproceedings{ +li2021fedbn, +title={Fed{\{}BN{\}}: Federated Learning on Non-{\{}IID{\}} Features via Local Batch Normalization}, +author={Xiaoxiao Li and Meirui Jiang and Xiaofei Zhang and Michael Kamp and Qi Dou}, +booktitle={International Conference on Learning Representations}, +year={2021}, +url={https://openreview.net/pdf?id=6YEQUn0QICG} +} +``` + diff --git a/research/fed-bn/create_job.sh b/research/fed-bn/create_job.sh new file mode 100755 index 0000000000..c793ca3444 --- /dev/null +++ b/research/fed-bn/create_job.sh @@ -0,0 +1 @@ +nvflare job create -force -j ./jobs/fed_bn -w sag_pt -sd ./src/ -f config_fed_client.conf app_script=fedbn_cifar10.py diff --git a/research/fed-bn/figs/loss.jpeg b/research/fed-bn/figs/loss.jpeg new file mode 100644 index 0000000000000000000000000000000000000000..3fb646bcbed483ff78b7467bf3d57cf9ac148adc GIT binary patch literal 29518 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%0A7gib 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 YnpSXN%ibmJ|Mm1_G0Oj!w)8{Kzh?g3DF6Tf literal 0 HcmV?d00001 diff --git a/research/fed-bn/prepare_data.sh b/research/fed-bn/prepare_data.sh new file mode 100755 index 0000000000..d01ee2a3d7 --- /dev/null +++ b/research/fed-bn/prepare_data.sh @@ -0,0 +1,3 @@ +DATASET_ROOT="/tmp/nvflare/data" + +python3 -c "import torchvision.datasets as datasets; datasets.CIFAR10(root='${DATASET_ROOT}', train=True, download=True)" \ No newline at end of file diff --git a/research/fed-bn/requirements.txt b/research/fed-bn/requirements.txt new file mode 100644 index 0000000000..eb6efcb233 --- /dev/null +++ b/research/fed-bn/requirements.txt @@ -0,0 +1,4 @@ +nvflare~=2.4.0rc +torch +torchvision +comet_ml diff --git a/research/fed-bn/run_job.sh b/research/fed-bn/run_job.sh new file mode 100755 index 0000000000..e7cd2231e7 --- /dev/null +++ b/research/fed-bn/run_job.sh @@ -0,0 +1 @@ +nvflare simulator -n 2 -t 2 ./jobs/fed_bn -w fedbn_workspace diff --git a/research/fed-bn/src/fedbn_cifar10.py b/research/fed-bn/src/fedbn_cifar10.py new file mode 100644 index 0000000000..e0747941f1 --- /dev/null +++ b/research/fed-bn/src/fedbn_cifar10.py @@ -0,0 +1,145 @@ +# Copyright (c) 2024, NVIDIA CORPORATION. All rights reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# (optional) metrics +import comet_ml +import torch +import torch.nn as nn +import torch.optim as optim +import torchvision +import torchvision.transforms as transforms +from net import Net + +# (1) import nvflare client API +import nvflare.client as flare + +# (optional) set a fix place so we don't need to download everytime +DATASET_PATH = "/tmp/nvflare/data" +# (optional) We change to use GPU to speed things up. +# if you want to use CPU, change DEVICE="cpu" +DEVICE = "cuda:0" +# input your own comet ml account API key +COMET_API_KEY = "" + + +# key function for FedBN +def load_state_dict_skip_bn(model, state_dict): + new_state_dict = {k: v for k, v in state_dict.items() if "bn" not in k} + model.load_state_dict(new_state_dict, strict=False) + + +def main(): + transform = transforms.Compose([transforms.ToTensor(), transforms.Normalize((0.5, 0.5, 0.5), (0.5, 0.5, 0.5))]) + + batch_size = 4 + epochs = 2 + + trainset = torchvision.datasets.CIFAR10(root=DATASET_PATH, train=True, download=True, transform=transform) + trainloader = torch.utils.data.DataLoader(trainset, batch_size=batch_size, shuffle=True, num_workers=8) + + testset = torchvision.datasets.CIFAR10(root=DATASET_PATH, train=False, download=True, transform=transform) + testloader = torch.utils.data.DataLoader(testset, batch_size=batch_size, shuffle=False, num_workers=8) + + net = Net() + + # (2) initializes NVFlare client API + flare.init() + + comet_ml.init() + exp = comet_ml.Experiment(project_name="fedbn_cifar10", api_key=COMET_API_KEY) + + while flare.is_running(): + # (3) receives FLModel from NVFlare + input_model = flare.receive() + print(f"\n[Current Round={input_model.current_round}, Site = {flare.get_site_name()}]\n") + + # (4) loads model from NVFlare, but skip bn layers + load_state_dict_skip_bn(net, input_model.params) + + criterion = nn.CrossEntropyLoss() + optimizer = optim.Adam(net.parameters(), lr=0.001) + + # (optional) use GPU to speed things up + net.to(DEVICE) + # (optional) calculate total steps + steps = epochs * len(trainloader) + for epoch in range(epochs): # loop over the dataset multiple times + running_loss = 0.0 + for i, data in enumerate(trainloader, 0): + # get the inputs; data is a list of [inputs, labels] + # (optional) use GPU to speed things up + inputs, labels = data[0].to(DEVICE), data[1].to(DEVICE) + + # zero the parameter gradients + optimizer.zero_grad() + + # forward + backward + optimize + outputs = net(inputs) + loss = criterion(outputs, labels) + loss.backward() + optimizer.step() + + # print statistics + running_loss += loss.item() + if i % 2000 == 1999: # print every 2000 mini-batches + print(f"[{epoch + 1}, {i + 1:5d}] loss: {running_loss / 2000:.3f}") + global_step = input_model.current_round * steps + epoch * len(trainloader) + i + + exp.log_metrics({"loss": running_loss}, step=global_step) + running_loss = 0.0 + + print("Finished Training") + + PATH = "./cifar_net.pth" + torch.save(net.state_dict(), PATH) + + # (5) wraps evaluation logic into a method to re-use for + # evaluation on both trained and received model + def evaluate(input_weights): + net = Net() + net.load_state_dict(input_weights) + # (optional) use GPU to speed things up + net.to(DEVICE) + + correct = 0 + total = 0 + # since we're not training, we don't need to calculate the gradients for our outputs + with torch.no_grad(): + for data in testloader: + # (optional) use GPU to speed things up + images, labels = data[0].to(DEVICE), data[1].to(DEVICE) + # calculate outputs by running images through the network + outputs = net(images) + # the class with the highest energy is what we choose as prediction + _, predicted = torch.max(outputs.data, 1) + total += labels.size(0) + correct += (predicted == labels).sum().item() + + print(f"Accuracy of the network on the 10000 test images: {100 * correct // total} %") + return 100 * correct // total + + # (6) evaluate on received model for model selection + accuracy = evaluate(input_model.params) + # (7) construct trained FL model + output_model = flare.FLModel( + params=net.cpu().state_dict(), + metrics={"accuracy": accuracy}, + meta={"NUM_STEPS_CURRENT_ROUND": steps}, + ) + # (8) send model back to NVFlare + flare.send(output_model) + + +if __name__ == "__main__": + main() diff --git a/research/fed-bn/src/net.py b/research/fed-bn/src/net.py new file mode 100644 index 0000000000..12d6929561 --- /dev/null +++ b/research/fed-bn/src/net.py @@ -0,0 +1,41 @@ +# Copyright (c) 2024, NVIDIA CORPORATION. All rights reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +import torch +import torch.nn as nn +import torch.nn.functional as F + + +class Net(nn.Module): + def __init__(self): + super().__init__() + self.conv1 = nn.Conv2d(3, 6, 5) + self.bn1 = nn.BatchNorm2d(6) + self.pool = nn.MaxPool2d(2, 2) + self.conv2 = nn.Conv2d(6, 16, 5) + self.bn2 = nn.BatchNorm2d(16) + self.fc1 = nn.Linear(16 * 5 * 5, 120) + self.bn3 = nn.BatchNorm1d(120) + self.fc2 = nn.Linear(120, 84) + self.bn4 = nn.BatchNorm1d(84) + self.fc3 = nn.Linear(84, 10) + + def forward(self, x): + x = self.pool(F.relu(self.bn1(self.conv1(x)))) + x = self.pool(F.relu(self.bn2(self.conv2(x)))) + x = torch.flatten(x, 1) + x = F.relu(self.bn3(self.fc1(x))) + x = F.relu(self.bn4(self.fc2(x))) + x = self.fc3(x) + return x From 27726f1804c4f2991737f22a47ddcc3f30ffc72a Mon Sep 17 00:00:00 2001 From: Chester Chen <512707+chesterxgchen@users.noreply.github.com> Date: Fri, 10 May 2024 19:13:15 -0700 Subject: [PATCH 11/15] fix MLFLOW example (#2575) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Yuan-Ting Hsieh (謝沅廷) --- .../app/config/config_fed_server.conf | 1 + .../cifar10/code/fl/train_with_mlflow.py | 2 +- .../step-by-step/cifar10/sag/sag.ipynb | 46 ++++++++++++++++++- .../sag_pt_in_proc/config_fed_server.conf | 2 +- 4 files changed, 47 insertions(+), 4 deletions(-) diff --git a/examples/advanced/experiment-tracking/mlflow/jobs/hello-pt-mlflow/app/config/config_fed_server.conf b/examples/advanced/experiment-tracking/mlflow/jobs/hello-pt-mlflow/app/config/config_fed_server.conf index 9bc187c8ab..5b0f694a6a 100644 --- a/examples/advanced/experiment-tracking/mlflow/jobs/hello-pt-mlflow/app/config/config_fed_server.conf +++ b/examples/advanced/experiment-tracking/mlflow/jobs/hello-pt-mlflow/app/config/config_fed_server.conf @@ -48,6 +48,7 @@ "id": "mlflow_receiver_with_tracking_uri", "path": "nvflare.app_opt.tracking.mlflow.mlflow_receiver.MLflowReceiver", "args": { + tracking_uri = "file:///{WORKSPACE}/{JOB_ID}/mlruns" "kwargs": { "experiment_name": "hello-pt-experiment", "run_name": "hello-pt-with-mlflow", diff --git a/examples/hello-world/step-by-step/cifar10/code/fl/train_with_mlflow.py b/examples/hello-world/step-by-step/cifar10/code/fl/train_with_mlflow.py index 1d43b88d4d..3e05f715b2 100644 --- a/examples/hello-world/step-by-step/cifar10/code/fl/train_with_mlflow.py +++ b/examples/hello-world/step-by-step/cifar10/code/fl/train_with_mlflow.py @@ -139,7 +139,7 @@ def evaluate(input_weights): running_loss += loss.item() if i % 2000 == 1999: # print every 2000 mini-batches print(f"({client_id}) [{epoch + 1}, {i + 1:5d}] loss: {running_loss / 2000:.3f}") - global_step = input_model.current_round * local_epochs * batch_size + epoch * batch_size + i + global_step = input_model.current_round * steps + epoch * len(trainloader) + i mlflow.log_metric("loss", running_loss / 2000, global_step) running_loss = 0.0 diff --git a/examples/hello-world/step-by-step/cifar10/sag/sag.ipynb b/examples/hello-world/step-by-step/cifar10/sag/sag.ipynb index dbd515b0f0..6d8b8ca76e 100644 --- a/examples/hello-world/step-by-step/cifar10/sag/sag.ipynb +++ b/examples/hello-world/step-by-step/cifar10/sag/sag.ipynb @@ -232,8 +232,8 @@ "source": [ "! nvflare job create -j /tmp/nvflare/jobs/cifar10_sag_pt -w sag_pt_in_proc \\\n", "-f meta.conf min_clients=2 \\\n", - "-f config_fed_client.conf app_script=train.py app_config=\"--batch_size 4 --dataset_path {CIFAR10_ROOT} --num_workers 2\" \\\n", - "-f config_fed_server.conf num_rounds=5 \\\n", + "-f config_fed_client.conf app_script=train_with_mlflow.py app_config=\"--batch_size 4 --dataset_path {CIFAR10_ROOT} --num_workers 2\" \\\n", + "-f config_fed_server.conf num_rounds=2 \\\n", "-sd ../code/fl \\\n", "-force" ] @@ -289,6 +289,48 @@ "The next 5 examples will use the same ScatterAndGather workflow, but will demonstrate different execution APIs and feature.\n", "In the next example [sag_deploy_map](../sag_deploy_map/sag_deploy_map.ipynb), we will learn about the deploy_map configuration for deployment of apps to different sites." ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "a49b430b-a65b-4b1e-8793-9b3befcfcfd9", + "metadata": { + "tags": [] + }, + "outputs": [], + "source": [ + "!tree /tmp/nvflare/jobs/cifar10_sag_pt_workspace/" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "50594df7-b4c9-4e5e-944a-403b5a105c27", + "metadata": { + "tags": [] + }, + "outputs": [], + "source": [ + "!mlflow ui --port 5000 --backend-store-uri /tmp/nvflare/jobs/cifar10_sag_pt_workspace/server/simulate_job/mlruns" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "af2b6628-61af-4bc8-84d4-a9876a27c7c2", + "metadata": {}, + "outputs": [], + "source": [ + "!tensorboard --logdir=/tmp/nvflare/jobs/cifar10_sag_pt_workspace/server/simulate_job/tb_events" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "d3ad11c3-6ef7-46cd-8778-0090505b14e1", + "metadata": {}, + "outputs": [], + "source": [] } ], "metadata": { diff --git a/job_templates/sag_pt_in_proc/config_fed_server.conf b/job_templates/sag_pt_in_proc/config_fed_server.conf index ab5691c4b7..deb678189f 100644 --- a/job_templates/sag_pt_in_proc/config_fed_server.conf +++ b/job_templates/sag_pt_in_proc/config_fed_server.conf @@ -107,7 +107,7 @@ path = "nvflare.app_opt.tracking.mlflow.mlflow_receiver.MLflowReceiver" args { # tracking_uri = "http://0.0.0.0:5000" - tracking_uri = "" + tracking_uri = "file:///{WORKSPACE}/{JOB_ID}/mlruns" kwargs { experiment_name = "nvflare-sag-pt-experiment" run_name = "nvflare-sag-pt-with-mlflow" From d050cf23b33e3ac82ad5d33d1a077c9c39107d13 Mon Sep 17 00:00:00 2001 From: Chester Chen <512707+chesterxgchen@users.noreply.github.com> Date: Fri, 10 May 2024 21:42:02 -0700 Subject: [PATCH 12/15] BugFix: InProcessClientAPIExecutor's TaskScriptRunner (#2558) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 1) find script full path to indicate which site script to avoid loading run script 2) make sure the task script failed will cause the client to return failure status which will trigger job stop rather wait forever 3) add different unit tests * sort key in unit test * add logic to improve error message * style format * add more tests and logics * code format * code format * fix steps error * fix global steps * rollback some changes and split it into another PR * rollback some changes and split it into another PR --------- Co-authored-by: Yuan-Ting Hsieh (謝沅廷) --- .../in_process_client_api_executor.py | 15 +- .../executors/task_script_runner.py | 60 ++++-- .../executors/task_script_runner_test.py | 174 ++++++++++++++++-- tests/unit_test/client/in_process/api_test.py | 4 +- .../data/jobs/in_proc_job/custom/src/model.py | 18 ++ .../data/jobs/in_proc_job/custom/src/train.py | 43 +++++ .../in_proc_job/server/custom/failed_train.py | 44 +++++ .../jobs/in_proc_job/server/custom/model.py | 18 ++ .../jobs/in_proc_job/server/custom/train.py | 47 +++++ .../in_proc_job/site-1/custom/failed_train.py | 44 +++++ .../jobs/in_proc_job/site-1/custom/model.py | 18 ++ .../site-1/custom/relative_import_train.py | 43 +++++ .../jobs/in_proc_job/site-1/custom/train.py | 43 +++++ 13 files changed, 537 insertions(+), 34 deletions(-) create mode 100644 tests/unit_test/data/jobs/in_proc_job/custom/src/model.py create mode 100644 tests/unit_test/data/jobs/in_proc_job/custom/src/train.py create mode 100644 tests/unit_test/data/jobs/in_proc_job/server/custom/failed_train.py create mode 100644 tests/unit_test/data/jobs/in_proc_job/server/custom/model.py create mode 100644 tests/unit_test/data/jobs/in_proc_job/server/custom/train.py create mode 100644 tests/unit_test/data/jobs/in_proc_job/site-1/custom/failed_train.py create mode 100644 tests/unit_test/data/jobs/in_proc_job/site-1/custom/model.py create mode 100644 tests/unit_test/data/jobs/in_proc_job/site-1/custom/relative_import_train.py create mode 100644 tests/unit_test/data/jobs/in_proc_job/site-1/custom/train.py diff --git a/nvflare/app_common/executors/in_process_client_api_executor.py b/nvflare/app_common/executors/in_process_client_api_executor.py index 2277f4718f..15049e4177 100644 --- a/nvflare/app_common/executors/in_process_client_api_executor.py +++ b/nvflare/app_common/executors/in_process_client_api_executor.py @@ -61,6 +61,7 @@ def __init__( submit_model_task_name: str = "submit_model", ): super(InProcessClientAPIExecutor, self).__init__() + self._abort = False self._client_api = None self._result_pull_interval = result_pull_interval self._log_pull_interval = log_pull_interval @@ -93,6 +94,7 @@ def __init__( self._event_manager = EventManager(self._data_bus) self._data_bus.subscribe([TOPIC_LOCAL_RESULT], self.local_result_callback) self._data_bus.subscribe([TOPIC_LOG_DATA], self.log_result_callback) + self._data_bus.subscribe([TOPIC_ABORT, TOPIC_STOP], self.to_abort_callback) self.local_result = None self._fl_ctx = None self._task_fn_path = None @@ -106,17 +108,19 @@ def handle_event(self, event_type: str, fl_ctx: FLContext): self._init_converter(fl_ctx) self._task_fn_wrapper = TaskScriptRunner( - script_path=self._task_script_path, script_args=self._task_script_args + site_name=fl_ctx.get_identity_name(), + script_path=self._task_script_path, + script_args=self._task_script_args, ) self._task_fn_thread = threading.Thread(target=self._task_fn_wrapper.run) - self._task_fn_thread.start() - meta = self._prepare_task_meta(fl_ctx, None) self._client_api = InProcessClientAPI(task_metadata=meta, result_check_interval=self._result_pull_interval) self._client_api.init() self._data_bus.put_data(CLIENT_API_KEY, self._client_api) + self._task_fn_thread.start() + elif event_type == EventType.END_RUN: self._event_manager.fire_event(TOPIC_STOP, "END_RUN received") if self._task_fn_thread: @@ -142,7 +146,7 @@ def execute(self, task_name: str, shareable: Shareable, fl_ctx: FLContext, abort # wait for result self.log_info(fl_ctx, "Waiting for result from peer") while True: - if abort_signal.triggered: + if abort_signal.triggered or self._abort is True: # notify peer that the task is aborted self._event_manager.fire_event(TOPIC_ABORT, f"{task_name}' is aborted, abort_signal_triggered") return make_reply(ReturnCode.TASK_ABORTED) @@ -231,3 +235,6 @@ def log_result_callback(self, topic, data, databus): # fire_fed_event = True w/o fed_event_converter somehow did not work with self._engine.new_context() as fl_ctx: send_analytic_dxo(self, dxo=dxo, fl_ctx=fl_ctx, event_type=ANALYTIC_EVENT_TYPE, fire_fed_event=False) + + def to_abort_callback(self, topic, data, databus): + self._abort = True diff --git a/nvflare/app_common/executors/task_script_runner.py b/nvflare/app_common/executors/task_script_runner.py index fba46f6b05..bd563e2b43 100644 --- a/nvflare/app_common/executors/task_script_runner.py +++ b/nvflare/app_common/executors/task_script_runner.py @@ -14,67 +14,91 @@ import builtins import logging import os +import runpy import sys import traceback +from nvflare.client.in_process.api import TOPIC_ABORT +from nvflare.fuel.data_event.data_bus import DataBus +from nvflare.fuel.data_event.event_manager import EventManager + print_fn = builtins.print class TaskScriptRunner: logger = logging.getLogger(__name__) - def __init__(self, script_path: str, script_args: str = None): + def __init__(self, site_name: str, script_path: str, script_args: str = None, redirect_print_to_log=True): """Wrapper for function given function path and args Args: + site_name (str): site name script_path (str): script file name, such as train.py script_args (str, Optional): script arguments to pass in. """ + + self.redirect_print_to_log = redirect_print_to_log + self.event_manager = EventManager(DataBus()) self.script_args = script_args - self.client_api = None + self.site_name = site_name self.logger = logging.getLogger(self.__class__.__name__) - self.script_path = self.get_script_full_path(script_path) + self.script_path = script_path + self.script_full_path = self.get_script_full_path(self.site_name, self.script_path) def run(self): """Call the task_fn with any required arguments.""" - self.logger.info(f"\n start task run() with {self.script_path}") + self.logger.info(f"\n start task run() with full path: {self.script_full_path}") try: - import runpy - curr_argv = sys.argv - builtins.print = log_print + builtins.print = log_print if self.redirect_print_to_log else print_fn sys.argv = self.get_sys_argv() - runpy.run_path(self.script_path, run_name="__main__") + runpy.run_path(self.script_full_path, run_name="__main__") sys.argv = curr_argv - + except ImportError as ie: + msg = "attempted relative import with no known parent package" + if ie.msg == msg: + xs = [p for p in sys.path if self.script_full_path.startswith(p)] + import_base_path = max(xs, key=len) + raise ImportError( + f"{ie.msg}, the relative import is not support. python import is based off the sys.path: {import_base_path}" + ) + else: + raise ie except Exception as e: msg = traceback.format_exc() self.logger.error(msg) - if self.client_api: - self.client_api.exec_queue.ask_abort(msg) + self.logger.error("fire abort event") + self.event_manager.fire_event(TOPIC_ABORT, f"'{self.script_full_path}' is aborted, {msg}") raise e finally: builtins.print = print_fn def get_sys_argv(self): args_list = [] if not self.script_args else self.script_args.split() - return [self.script_path] + args_list + return [self.script_full_path] + args_list - def get_script_full_path(self, script_path) -> str: + def get_script_full_path(self, site_name, script_path) -> str: target_file = None script_filename = os.path.basename(script_path) script_dirs = os.path.dirname(script_path) + if os.path.isabs(script_path): + if not os.path.isfile(script_path): + raise ValueError(f"script_path='{script_path}' not found") + return script_path + for r, dirs, files in os.walk(os.getcwd()): for f in files: absolute_path = os.path.join(r, f) if absolute_path.endswith(script_path): parent_dir = absolute_path[: absolute_path.find(script_path)].rstrip(os.sep) if os.path.isdir(parent_dir): - target_file = absolute_path - break + path_components = parent_dir.split(os.path.sep) + if site_name in path_components: + target_file = absolute_path + break - if not script_dirs and f == script_filename: + if not site_name and not script_dirs and f == script_filename: target_file = absolute_path break @@ -82,7 +106,9 @@ def get_script_full_path(self, script_path) -> str: break if not target_file: - raise ValueError(f"{script_path} is not found") + msg = f"Can not find {script_path}" + self.event_manager.fire_event(TOPIC_ABORT, f"'{self.script_path}' is aborted, {msg}") + raise ValueError(msg) return target_file diff --git a/tests/unit_test/app_common/executors/task_script_runner_test.py b/tests/unit_test/app_common/executors/task_script_runner_test.py index 65057e5f01..f065f78651 100644 --- a/tests/unit_test/app_common/executors/task_script_runner_test.py +++ b/tests/unit_test/app_common/executors/task_script_runner_test.py @@ -12,9 +12,13 @@ # See the License for the specific language governing permissions and # limitations under the License. import os +import sys import unittest +import pytest + from nvflare.app_common.executors.task_script_runner import TaskScriptRunner +from nvflare.client.in_process.api import TOPIC_ABORT, TOPIC_STOP class TestTaskScriptRunner(unittest.TestCase): @@ -22,34 +26,34 @@ def test_app_scripts_and_args(self): curr_dir = os.getcwd() script_path = "nvflare/cli.py" script_args = "--batch_size 4" - wrapper = TaskScriptRunner(script_path=script_path, script_args=script_args) + wrapper = TaskScriptRunner(site_name="", script_path=script_path, script_args=script_args) - self.assertTrue(wrapper.script_path.endswith(script_path)) + self.assertTrue(wrapper.script_full_path.endswith(script_path)) self.assertEqual(wrapper.get_sys_argv(), [os.path.join(curr_dir, "nvflare", "cli.py"), "--batch_size", "4"]) def test_app_scripts_and_args2(self): curr_dir = os.getcwd() script_path = "cli.py" script_args = "--batch_size 4" - wrapper = TaskScriptRunner(script_path=script_path, script_args=script_args) + wrapper = TaskScriptRunner(site_name="", script_path=script_path, script_args=script_args) - self.assertTrue(wrapper.script_path.endswith(script_path)) + self.assertTrue(wrapper.script_full_path.endswith(script_path)) self.assertEqual(wrapper.get_sys_argv(), [os.path.join(curr_dir, "nvflare", "cli.py"), "--batch_size", "4"]) def test_app_scripts_with_sub_dirs1(self): curr_dir = os.getcwd() script_path = "nvflare/__init__.py" - wrapper = TaskScriptRunner(script_path=script_path) + wrapper = TaskScriptRunner(site_name="", script_path=script_path) - self.assertTrue(wrapper.script_path.endswith(script_path)) + self.assertTrue(wrapper.script_full_path.endswith(script_path)) self.assertEqual(wrapper.get_sys_argv(), [os.path.join(curr_dir, "nvflare", "__init__.py")]) def test_app_scripts_with_sub_dirs2(self): curr_dir = os.getcwd() script_path = "nvflare/app_common/executors/__init__.py" - wrapper = TaskScriptRunner(script_path=script_path) + wrapper = TaskScriptRunner(site_name="", script_path=script_path) - self.assertTrue(wrapper.script_path.endswith(script_path)) + self.assertTrue(wrapper.script_full_path.endswith(script_path)) self.assertEqual( wrapper.get_sys_argv(), [os.path.join(curr_dir, "nvflare", "app_common", "executors", "__init__.py")] ) @@ -57,9 +61,9 @@ def test_app_scripts_with_sub_dirs2(self): def test_app_scripts_with_sub_dirs3(self): curr_dir = os.getcwd() script_path = "executors/task_script_runner.py" - wrapper = TaskScriptRunner(script_path=script_path) + wrapper = TaskScriptRunner(site_name="app_common", script_path=script_path) - self.assertTrue(wrapper.script_path.endswith(script_path)) + self.assertTrue(wrapper.script_full_path.endswith(script_path)) self.assertEqual( wrapper.get_sys_argv(), [os.path.join(curr_dir, "nvflare", "app_common", "executors", "task_script_runner.py")], @@ -68,7 +72,153 @@ def test_app_scripts_with_sub_dirs3(self): def test_app_scripts_with_sub_dirs4(self): curr_dir = os.getcwd() script_path = "in_process/api.py" - wrapper = TaskScriptRunner(script_path=script_path) + wrapper = TaskScriptRunner(site_name="client", script_path=script_path) - self.assertTrue(wrapper.script_path.endswith(script_path)) + self.assertTrue(wrapper.script_full_path.endswith(script_path)) self.assertEqual(wrapper.get_sys_argv(), [os.path.join(curr_dir, "nvflare", "client", "in_process", "api.py")]) + + def test_file_not_found_with_exception(self): + curr_dir = os.getcwd() + script_path = "in_process/api.py" + with pytest.raises(ValueError, match="Can not find in_process/api.py"): + wrapper = TaskScriptRunner(site_name="site-1", script_path=script_path) + self.assertTrue(wrapper.script_full_path.endswith(script_path)) + self.assertEqual( + wrapper.get_sys_argv(), [os.path.join(curr_dir, "nvflare", "client", "in_process", "api.py")] + ) + + def test_run_scripts_with_sub_dirs(self): + old_sys_path = sys.path + script_args = "--batch_size 4" + sys.path.append(os.path.join(os.getcwd(), "tests/unit_test/data/jobs/in_proc_job/custom")) + sys.path.append(os.path.join(os.getcwd(), "tests/unit_test/data/jobs/in_proc_job/server/custom")) + sys.path.append(os.path.join(os.getcwd(), "tests/unit_test/data/jobs/in_proc_job/site-1/custom")) + + try: + script_path = "train.py" + wrapper = TaskScriptRunner( + site_name="site-1", script_path=script_path, script_args=script_args, redirect_print_to_log=False + ) + self.assertTrue(wrapper.script_full_path.endswith(script_path)) + expected_path = os.path.join(os.getcwd(), "tests/unit_test/data/jobs/in_proc_job/site-1/custom/train.py") + self.assertEqual(wrapper.get_sys_argv(), [expected_path, "--batch_size", "4"]) + wrapper.run() + finally: + sys.path = old_sys_path + + def test_run_scripts_with_sub_dirs2(self): + old_sys_path = sys.path + script_args = "--batch_size 4" + sys.path.append(os.path.join(os.getcwd(), "tests/unit_test/data/jobs/in_proc_job/custom")) + sys.path.append(os.path.join(os.getcwd(), "tests/unit_test/data/jobs/in_proc_job/server/custom")) + sys.path.append(os.path.join(os.getcwd(), "tests/unit_test/data/jobs/in_proc_job/site-1/custom")) + + try: + script_path = "train.py" + wrapper = TaskScriptRunner( + site_name="server", script_path=script_path, script_args=script_args, redirect_print_to_log=False + ) + self.assertTrue(wrapper.script_full_path.endswith(script_path)) + expected_path = os.path.join(os.getcwd(), "tests/unit_test/data/jobs/in_proc_job/server/custom/train.py") + self.assertEqual(wrapper.get_sys_argv(), [expected_path, "--batch_size", "4"]) + wrapper.run() + finally: + sys.path = old_sys_path + + def test_run_scripts_with_sub_dirs3(self): + old_sys_path = sys.path + script_args = "--batch_size 4" + sys.path.append(os.path.join(os.getcwd(), "tests/unit_test/data/jobs/in_proc_job/custom")) + sys.path.append(os.path.join(os.getcwd(), "tests/unit_test/data/jobs/in_proc_job/server/custom")) + sys.path.append(os.path.join(os.getcwd(), "tests/unit_test/data/jobs/in_proc_job/site-1/custom")) + + try: + script_path = "src/train.py" + wrapper = TaskScriptRunner( + site_name="", script_path=script_path, script_args=script_args, redirect_print_to_log=False + ) + self.assertTrue(wrapper.script_full_path.endswith(script_path)) + expected_path = os.path.join(os.getcwd(), "tests/unit_test/data/jobs/in_proc_job/custom/src/train.py") + self.assertEqual(wrapper.get_sys_argv(), [expected_path, "--batch_size", "4"]) + wrapper.run() + finally: + sys.path = old_sys_path + + def test_run_failed_scripts(self): + old_sys_path = sys.path + script_args = "--batch_size 4" + sys.path.append(os.path.join(os.getcwd(), "tests/unit_test/data/jobs/in_proc_job/custom")) + sys.path.append(os.path.join(os.getcwd(), "tests/unit_test/data/jobs/in_proc_job/server/custom")) + sys.path.append(os.path.join(os.getcwd(), "tests/unit_test/data/jobs/in_proc_job/site-1/custom")) + + try: + script_path = "failed_train.py" + wrapper = TaskScriptRunner( + site_name="site-1", script_path=script_path, script_args=script_args, redirect_print_to_log=False + ) + wrapper.event_manager.data_bus.subscribe([TOPIC_ABORT, TOPIC_STOP], self.abort_callback) + + self.assertTrue(wrapper.script_full_path.endswith(script_path)) + with pytest.raises(ValueError, match="failed to train model"): + # 1 ) check if the exception is through, + # 2 ) more important to see if the callback is trigger. + wrapper.run() + finally: + sys.path = old_sys_path + + def abort_callback(self, topic, data, databus): + print("\n ===== calling abort_callback begin") + # assert failure here will not cause test to fail + self.assertEqual(topic, TOPIC_ABORT) + print("\n ===== calling abort_callback end") + + def test_run_relative_import_scripts(self): + old_sys_path = sys.path + script_args = "--batch_size 4" + sys.path.append(os.path.join(os.getcwd(), "tests/unit_test/data/jobs/in_proc_job/custom")) + sys.path.append(os.path.join(os.getcwd(), "tests/unit_test/data/jobs/in_proc_job/server/custom")) + sys.path.append(os.path.join(os.getcwd(), "tests/unit_test/data/jobs/in_proc_job/site-1/custom")) + + try: + script_path = "relative_import_train.py" + wrapper = TaskScriptRunner( + site_name="site-1", script_path=script_path, script_args=script_args, redirect_print_to_log=False + ) + self.assertTrue(wrapper.script_full_path.endswith(script_path)) + path = os.path.join(os.getcwd(), "tests/unit_test/data/jobs/in_proc_job/site-1/custom") + msg = f"attempted relative import with no known parent package, the relative import is not support. python import is based off the sys.path: {path}" + with pytest.raises(ImportError, match=msg): + # check the ImportError + wrapper.run() + finally: + sys.path = old_sys_path + + def test_run_abs_path_scripts(self): + old_sys_path = sys.path + script_args = "--batch_size 4" + + sys.path.append(os.path.join(os.getcwd(), "tests/unit_test/data/jobs/in_proc_job/site-1/custom")) + + try: + # path doesn't exist + script_path = "/foo/dummy/train.py" + with pytest.raises(ValueError, match="script_path='/foo/dummy/train.py' not found"): + wrapper = TaskScriptRunner( + site_name="site-1", script_path=script_path, script_args=script_args, redirect_print_to_log=False + ) + finally: + sys.path = old_sys_path + + def test_run_abs_path_scripts2(self): + old_sys_path = sys.path + script_args = "--batch_size 4" + sys.path.append(os.path.join(os.getcwd(), "tests/unit_test/data/jobs/in_proc_job/site-1/custom")) + + try: + script_path = os.path.join(os.getcwd(), "tests/unit_test/data/jobs/in_proc_job/site-1/custom/train.py") + wrapper = TaskScriptRunner( + site_name="site-1", script_path=script_path, script_args=script_args, redirect_print_to_log=False + ) + wrapper.run() + finally: + sys.path = old_sys_path diff --git a/tests/unit_test/client/in_process/api_test.py b/tests/unit_test/client/in_process/api_test.py index af2a62bc44..835bd80b5d 100644 --- a/tests/unit_test/client/in_process/api_test.py +++ b/tests/unit_test/client/in_process/api_test.py @@ -64,7 +64,9 @@ def test_init_with_custom_interval(self): def test_init_subscriptions(self): client_api = InProcessClientAPI(self.task_metadata) - assert list(client_api.data_bus.subscribers.keys()) == [TOPIC_GLOBAL_RESULT, TOPIC_ABORT, TOPIC_STOP] + xs = list(client_api.data_bus.subscribers.keys()) + xs.sort() + assert xs == [TOPIC_ABORT, TOPIC_GLOBAL_RESULT, TOPIC_STOP] def local_result_callback(self, data, topic): pass diff --git a/tests/unit_test/data/jobs/in_proc_job/custom/src/model.py b/tests/unit_test/data/jobs/in_proc_job/custom/src/model.py new file mode 100644 index 0000000000..936da53207 --- /dev/null +++ b/tests/unit_test/data/jobs/in_proc_job/custom/src/model.py @@ -0,0 +1,18 @@ +# Copyright (c) 2024, NVIDIA CORPORATION. All rights reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + + +class Model: + def train(self, dataset_path, batch_size): + pass diff --git a/tests/unit_test/data/jobs/in_proc_job/custom/src/train.py b/tests/unit_test/data/jobs/in_proc_job/custom/src/train.py new file mode 100644 index 0000000000..b57342173c --- /dev/null +++ b/tests/unit_test/data/jobs/in_proc_job/custom/src/train.py @@ -0,0 +1,43 @@ +# Copyright (c) 2024, NVIDIA CORPORATION. All rights reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +import argparse + +from model import Model + + +class Code: + # code to test relative import + def run(self, dataset_path, batch_size): + model = Model() + model.train(dataset_path, batch_size) + + def define_parser(self): + parser = argparse.ArgumentParser() + parser.add_argument("--dataset_path", type=str, default="/data", nargs="?") + parser.add_argument("--batch_size", type=int, default=4, nargs="?") + return parser.parse_args() + + def main(self): + args = self.define_parser() + dataset_path = args.dataset_path + batch_size = args.batch_size + self.run(dataset_path, batch_size) + + +print("__name__ src is ", __name__) + +if __name__ == "__main__": + code = Code() + code.main() diff --git a/tests/unit_test/data/jobs/in_proc_job/server/custom/failed_train.py b/tests/unit_test/data/jobs/in_proc_job/server/custom/failed_train.py new file mode 100644 index 0000000000..26c5d36853 --- /dev/null +++ b/tests/unit_test/data/jobs/in_proc_job/server/custom/failed_train.py @@ -0,0 +1,44 @@ +# Copyright (c) 2024, NVIDIA CORPORATION. All rights reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +import argparse + +from model import Model + + +class Code: + # code to test relative import + def run(self, dataset_path, batch_size): + model = Model() + model.train(dataset_path, batch_size) + raise ValueError("failed to train model") + + def define_parser(self): + parser = argparse.ArgumentParser() + parser.add_argument("--dataset_path", type=str, default="/data", nargs="?") + parser.add_argument("--batch_size", type=int, default=4, nargs="?") + return parser.parse_args() + + def main(self): + args = self.define_parser() + dataset_path = args.dataset_path + batch_size = args.batch_size + self.run(dataset_path, batch_size) + + +print("__name__ in server is ", __name__) + +if __name__ == "__main__": + code = Code() + code.main() diff --git a/tests/unit_test/data/jobs/in_proc_job/server/custom/model.py b/tests/unit_test/data/jobs/in_proc_job/server/custom/model.py new file mode 100644 index 0000000000..936da53207 --- /dev/null +++ b/tests/unit_test/data/jobs/in_proc_job/server/custom/model.py @@ -0,0 +1,18 @@ +# Copyright (c) 2024, NVIDIA CORPORATION. All rights reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + + +class Model: + def train(self, dataset_path, batch_size): + pass diff --git a/tests/unit_test/data/jobs/in_proc_job/server/custom/train.py b/tests/unit_test/data/jobs/in_proc_job/server/custom/train.py new file mode 100644 index 0000000000..ce3759cf7e --- /dev/null +++ b/tests/unit_test/data/jobs/in_proc_job/server/custom/train.py @@ -0,0 +1,47 @@ +# Copyright (c) 2024, NVIDIA CORPORATION. All rights reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# print("\n in server train.py __package__ = ", __package__) +# __package__ = "nvflare.app_common.executors.server" +# print("\n in server train.py __package__ = ", __package__) + +import argparse + +from model import Model + + +class Code: + # code to test relative import + def run(self, dataset_path, batch_size): + model = Model() + model.train(dataset_path, batch_size) + + def define_parser(self): + parser = argparse.ArgumentParser() + parser.add_argument("--dataset_path", type=str, default="/data", nargs="?") + parser.add_argument("--batch_size", type=int, default=4, nargs="?") + return parser.parse_args() + + def main(self): + args = self.define_parser() + dataset_path = args.dataset_path + batch_size = args.batch_size + self.run(dataset_path, batch_size) + + +print("__name__ server is ", __name__) + +if __name__ == "__main__": + code = Code() + code.main() diff --git a/tests/unit_test/data/jobs/in_proc_job/site-1/custom/failed_train.py b/tests/unit_test/data/jobs/in_proc_job/site-1/custom/failed_train.py new file mode 100644 index 0000000000..8e0e5b0331 --- /dev/null +++ b/tests/unit_test/data/jobs/in_proc_job/site-1/custom/failed_train.py @@ -0,0 +1,44 @@ +# Copyright (c) 2024, NVIDIA CORPORATION. All rights reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +import argparse + +from model import Model + + +class Code: + # code to test relative import + def run(self, dataset_path, batch_size): + model = Model() + model.train(dataset_path, batch_size) + raise ValueError("failed to train model") + + def define_parser(self): + parser = argparse.ArgumentParser() + parser.add_argument("--dataset_path", type=str, default="/data", nargs="?") + parser.add_argument("--batch_size", type=int, default=4, nargs="?") + return parser.parse_args() + + def main(self): + args = self.define_parser() + dataset_path = args.dataset_path + batch_size = args.batch_size + self.run(dataset_path, batch_size) + + +print("__name__ site-1 is ", __name__) + +if __name__ == "__main__": + code = Code() + code.main() diff --git a/tests/unit_test/data/jobs/in_proc_job/site-1/custom/model.py b/tests/unit_test/data/jobs/in_proc_job/site-1/custom/model.py new file mode 100644 index 0000000000..936da53207 --- /dev/null +++ b/tests/unit_test/data/jobs/in_proc_job/site-1/custom/model.py @@ -0,0 +1,18 @@ +# Copyright (c) 2024, NVIDIA CORPORATION. All rights reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + + +class Model: + def train(self, dataset_path, batch_size): + pass diff --git a/tests/unit_test/data/jobs/in_proc_job/site-1/custom/relative_import_train.py b/tests/unit_test/data/jobs/in_proc_job/site-1/custom/relative_import_train.py new file mode 100644 index 0000000000..3a6801ecd9 --- /dev/null +++ b/tests/unit_test/data/jobs/in_proc_job/site-1/custom/relative_import_train.py @@ -0,0 +1,43 @@ +# Copyright (c) 2024, NVIDIA CORPORATION. All rights reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +import argparse + +from .model import Model + + +class Code: + # code to test relative import + def run(self, dataset_path, batch_size): + model = Model() + model.train(dataset_path, batch_size) + + def define_parser(self): + parser = argparse.ArgumentParser() + parser.add_argument("--dataset_path", type=str, default="/data", nargs="?") + parser.add_argument("--batch_size", type=int, default=4, nargs="?") + return parser.parse_args() + + def main(self): + args = self.define_parser() + dataset_path = args.dataset_path + batch_size = args.batch_size + self.run(dataset_path, batch_size) + + +print("__name__ site-1 is ", __name__) + +if __name__ == "__main__": + code = Code() + code.main() diff --git a/tests/unit_test/data/jobs/in_proc_job/site-1/custom/train.py b/tests/unit_test/data/jobs/in_proc_job/site-1/custom/train.py new file mode 100644 index 0000000000..943e40e567 --- /dev/null +++ b/tests/unit_test/data/jobs/in_proc_job/site-1/custom/train.py @@ -0,0 +1,43 @@ +# Copyright (c) 2024, NVIDIA CORPORATION. All rights reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +import argparse + +from model import Model + + +class Code: + # code to test relative import + def run(self, dataset_path, batch_size): + model = Model() + model.train(dataset_path, batch_size) + + def define_parser(self): + parser = argparse.ArgumentParser() + parser.add_argument("--dataset_path", type=str, default="/data", nargs="?") + parser.add_argument("--batch_size", type=int, default=4, nargs="?") + return parser.parse_args() + + def main(self): + args = self.define_parser() + dataset_path = args.dataset_path + batch_size = args.batch_size + self.run(dataset_path, batch_size) + + +print("__name__ site-1 is ", __name__) + +if __name__ == "__main__": + code = Code() + code.main() From 4025b7c5c27a14887d87b3e4bb587e108c979cee Mon Sep 17 00:00:00 2001 From: Chester Chen <512707+chesterxgchen@users.noreply.github.com> Date: Mon, 13 May 2024 21:14:59 -0700 Subject: [PATCH 13/15] update client_api.png (#2577) --- docs/resources/client_api.png | Bin 160494 -> 160306 bytes 1 file changed, 0 insertions(+), 0 deletions(-) diff --git a/docs/resources/client_api.png b/docs/resources/client_api.png index ef82720a922d94354b11ccb3493ace8b922558b9..edc340b010eaf25f26eb55993cb42e549ef45877 100644 GIT binary patch delta 46820 zcmd?Rbx>9P_dn{PyGt4oK|)$O1QBVZ5d>*z5F{ivD526ELJ$N*8mS|tgo1QRNSAbX z9P;-*_&m?&`F!Vl?>~3$%$>P24s-T7`@Q$t>%HQ&UTbYP=5fpBaHILqq}F2uR49dc z_=R-%gxCb{@bjVm2;CA95{`+Dg$cpgU>p<<^!5=Wtz-34A;gBr_Oc3sR z-67U45k4(ViMTGljSZjdWrj;CQNSO{@xZC+3gOCFr0^3pT)2rA4*Y%e9e4>HIsDr{ z-+hO>-A#Zq7ZJc^6=>nsc;s-05*m01i~v5J%8#hWVSvGV94O&!_blP#gpXrgND=Q9 z9btdnH zkb%2Uz*jXW;Tw2fH2d%u87gcY%tVwB23K{|0CX-B@SF)i3JYnV}Z*$#zvZ< z?ub~kT!X?WMVoER?Shx)#hOa|fUISB)&UWaR962R9#P{N}_dEvqO z$q0+*J^!_U7G6#!j;Qk!L;GJ(#|)fD|NHtxaIZI1z<5i^q!Av$3;+A|?Oy#yAk+f7 z%j+M#d4LAb*EU7uMtH#BCy!8%KzAt*dNdja9AAm=Qb@jeEYz29sTfjt+6!E`+B+P0 z#H){pl6dg&sO6f8g)ne7Km5Fx0?wC&1KxBsOE3V2!u7W|%xAmZBvI}E{`+W~_YIGQ4q^I!kDvq0en>~BS=BNB^# z{OhQ%WZ=(9n27CveeGDDjrNbQ(0ATTVOgs6{}C3YA4)WS(aRmftX2FYZ$W+ff8;&u zrG)>z)UZMRUrTeFE>#P6T(OUrh2_9qUQ!`6TPQCDfzx)8C8kTks1R$dU;YxUqXGs` zcQ!@PcE$hsK-AOww=U&@PK;3oT{1ugXX~>EQeT7jI0`17a>F9wZ+?*>g8MHO|3ALH z@$32@ne&F}|J>&KsPTV&t&E%5i1;e{m4gjSrU&!o2y%x)wHJ|7e5T*p5T*5&R?n$EmvDCxUKjNVu|I2=uPVd64(Lvy)dx0Q2 zu- z=g<)wwsUz{307@fZdD~d0qo&_)XH>9nV3WfL;16Dq9!KHGqI2ewuZVw;3ZTp{b zD3L@GMp-$*2)p`6?$hfqvPv6f7zl)@#{h@ql}*=R!+#_JhdC%i<4deygHa_8-+e{y8nFAm-t)GNGTW$hLO4px2}Xs!`^s6 zXb+24HcpPRtEdR|&?tCl$KPRaY}{&MtFq4!ZF-@CyFv9?6jQGE_xCIVvhnrrEStw0 zizA0pVoB9*i`|_JCmZEu4>vmLktu?Q8^|tbbAn?t^J&yeq>JHcj98T;9!Gir%!+ao zc0r;Sl9%R>6&F8&zVG#{dUNb)+Eo7{G_ce%)X%t4e1P_e@y*@Kw5l*JBBPJ5DpjmfQAfud;3P<^O`T? zhmO@fo6Bx?d$X&y#E1GmFz`!+(L~8pmP$?KbcT%#kCT&MPK!n>jLx51OrI}9S+e_c z9lZ7Q3vVqV?@35TDZ(&mWxoZKHH1wwHMC#Z@9zmHEAvTbEWUNzhVjQ=JjDFZGRGn@SEw?L#L#r)o!tCT4YI z0~yKq(hEsOWrE^iD>-Q}E2~3UNXq2V#!1Ea;^Cf{@bUKk=g^aaT3HDU)^f&$^^=N& zL)(JQ43yZSEo*+GPK#rzn?GL?ON-W=9gNK++ZWkpHy#*JYNm%`5^!)~91@#Z1spHi z$Qq7FX-4TMp49OiBBlJ)Bm8}()@RP`czcOpR>u?4maWmf#isT7A1a_QQ{A8A!%xuG zpAwgkO;w_l?QH}UlNDIa&g8RJ$~R&O7w$0gNx|dL#0J{L`*|jBa5dfk_^PI!2l2q{ z;C!8Pho8Sjnsz3WsfJHg{V4ut710K7EhVMa3%u^WyA~PF1s&CU)GWvfcA_6rJ<>RYv_Mf&{vGO*$Wz1OwE&wa`>I~}~l_C?j!nM_43IRR*d%#URaXB4*nqbBIT^i*!r znVHkmawc3SD}i}^FeQwvk~LEFS~#t6{x)x!;&3$Dx(BiF@zj*v)b$kJjA8RI9=&z7 zueAc0?|paLXq4YSZNF)T=(^3dJ1G4KhB>N>G9<1kC+LW4j&^qbSog*#r~mwW#p<47 z)e-$g%=UeV7i=f^X9{TjsYoa?-)P3QY5G-U%x zfLYYwkFFC#!Nyo|x>yeJC&lBt9EV6-`Ym87$)tR)B}9o z?&{c#$w53ZdsinXgc!!?HltnTlyC~~%-oH44rE1NR`N@}W6=qw@o2zKD?rE@vCOPbpE%#rZ?%#&wECu3ebFuz^)$`Y>Y!rExcYovx}Nb{`9nvj zigEF`G@U+ku=~1rsCn{5af;b!Q1WNHVvNZu&)152j)5L^p~*9w&cel>2fm8oG^7{KEQJc7&n4)BgWn z|Erkek&PECRuhpYpFX}QiLdF4!^>LusA@7Fl=NwCu3G2Tv=oIL;`Hp(soljU6<+G5 z^vN3eM)l%*mtTf9P1P=rgOt;L6=P0cn+CralC)$8pyBCU1D5{UBt|BP(y8o|$)poQ zj-Bba-Zs~vWV@e#`NWu?&-`)X$tm>wm{#kTcKx$MM^Ukba<#!Y46K_%j~|2yQBVsu zC{cfTGI6NzshfL3-XRS$epD>ZF1x;du!`wT>gM$KmyL`*Yow?fyL9rm=ve4Gu?D#; zWrT*{^VaaCxHexkYa|pIxC_Ii$Ta|-AlKk=(rC&uM8i8&Eb#M>ERdhSRePN{uVxVh zoTAdpgT@X|aTJN}R9mcw*hmYANJu^DK6%nv@S2>ft}oUQVd56`l^>&zbF*%$Fuij! zCe8oYcG$W8tf9oLv7xkukxtLlZ@;<9?A;cJQ~lY2ODjugkhI@%P#`*XNM6qSFStDo z@*sWOLj{_xd?9EIdlOHias?$)pWgPYq{Ank-f*{#Ebp6y>JLvQ3kOHCTs}^4RoTt2 zdVo0lSytkpSb1N>sSdedfUKN;fgjRHB*EP&JY<~3;&+e2YrTA^;ejFp<$IrvYJ=Bb zy2V#HGEw`13I%fAdbqDREtd{D_E&E|^3Cv%M?y$DOyH+LMZj4P$VF#@$jw_Tz$Jgg z*X4j`JCI-ceHGgJjvYw(rAOxClxBm`YdY|eZN{Nr(t z{&P9-GxgCLqNm|C`+FK{PqRqn^DfEV&Uxot1yg?CqblX%)!%_e`5stQ+ux{A< zPdQluXc3n&QkU;>0fDB>87KMHAS#Cgw?h4KHx0nMBUdHZBPrANH?6oab2D9*3ztSy&r6tam=nN(`gRQ8^1mcTi9Ja9IBNwYdC772 zel;NTOTybY_Qkax&pi8}D@I@E6O0=6hfJ9Y*oGc?PLwoJ8C5lSqZ?Bb-wE`fM43rD zUCIBZUOU!rlJPIGiHSrey)3*=w_6%%?F&iu9z7c@0pTdrHajW%w#26yJsIR2+~sh> zGgM-;MsVC?%+c&MTLRANr%IDy7pRdi)wC>R!|5Ri7dJq-5YG9~Bk;fKe!yfpGfEmy zM~`enlyErr$`$4-N_X$*Ot|$(nSo$H$-;$&BNroAr;DdfrK(XE*lSJ8N z`XVNy|IrN1@pe5occYvDDqS!2=V-iz&XJA4pvbM0ZL=9AN@7?QLlRB>#cH-1@Xdxx z%x0Ez(ulaP{CFYLaqFuCfi}|g9qMMeXjpNSCRfobP~fT<5`dY0`rEoV(q+#uO?s5=`j7_yxG?$+MQAeWx8x-@dmtWSwO0)IPP z=KRPEL>=7a-JiVmr)2(MN4}xmc31>EPoQ%bbvV;VEJLtaduT$#Z+_S7WWBNxqI0ex zt(50b7X1Qzxw*t0_;rCyxZS9&|BDi9> z61Y+}GD%hmd}9uXrWO=bmKDSg7jAdYOe#)mDf*9AP@j6Qq4`QyzRFa%m7S9jfMx~k zJ)vnHp7?VJMunT643s)J;BJ)oU=kc^CIF8!G?q3@{5}q&#KX+L36g=DT4h#Z#u$tW z=l>IHp?_os30r5nl{JcfwiIlSG5=*Kydd8?{8;${4R1jC+Z1nktmEeTbJOy}{lhiN zTvU25SD1K@hDSj`V_#U>e1yz>kU5}*GT9>;7^Lx>3#jrF#_5?B*T}(S(V?!7Db!;U zXonACgweqIO;D0#L5G)GC4|W=JwxwG1Pch zoDLWBRB9xMx=UU!T?r-Fb?W>!qW+Wowp(vQ3uIq{N4b53xwA#_gfj5_>?9PM(d+T& zezD)LSYL2?SGH3gNP=sS!Sv+jJ@50I(ia)*}q1G~kWr94PBa(OVz0zHo}f;l~_6+?*_#2;$v za0uC{+|_`-+(OH|7m?rLKaq!q_xU}z9Di}%*~^uw#q){$x;!JD^i&K2jWQ}?H zb^Z*MYEZZ$J9|t^Hn0p6kB4MNbFA#DUmzNuP>if}fKZ&nhp@#A&R%mg=%Df8+KXRH z?x$aMSq((M=41kwelCBRWSRqtm`uO`>C~e?nY%X~ z?SPneuffXzD02sd9vDJEU-d83Ogap6jY())VLKX}$%ESU-vU0dm#2DPTKDG{>`|p(4rfA{Zp8s{{-+uS zP~fWQbi?>k3npkma9^AZV8OiSz+8t0UF!cV5efmCYpx<<3klQ1FNX8^4g($z}nB?f{poG3d2qs7X7 z2gI02d^`e9od8e1n#el=V}@34Y>heB2Q&E}v4jJ3fl6z6W3E*efA$IGmCfWw^NFSn z8Zu`T%}mfK-@&kj=ktIm=)&)4V$+{G%^rmhDV|6J2^YRvGnS&M@whbLvIo5+66ZKQ znYxH%XqCA@_H5TjNo-U(r40c9OD=u3*IxqA{4>ahuH1hHz!h>7&MjFh>j+Vxe)Rd* zSGSYD6qGJ2kE7G4ApvgNm=VfIyHPb8S+bH}KqbZWqSLj7L4>c&nK^T5121) z@ef$-u;EIV4MuBWf_z1fre8LKf{x+*s6{3O(IYLfw>c$);sv0I$(`R}yo{)-n$K<^ z*U35a7jMntd!L4Ou3~yDB6^wwu&6?u=Jm=c=}sWMLQm)e zvAyE+tx%ca9=lfs8+TAUIuGJhg7X3wur+)%P;0v!jZK|XnfR=iA4MF3Vur4O4MM=? zKliKCc}zST+8U}q7hVHLGoawYKiRB@j(VVTawrQyFs0#07}%j?6k3mg8kresGd(Sd*@hz3(#g{j}JH#RqRrCi_V7g zH4+H^aNP2Jp&OD@Tz9-u`qV8yFZ<0!n)8O(4e|Dr&2hILhI-`Glgxp?ut?_0~3Ym#Na{fp>Uj^457}EA|^@135IO*eT@U)H1BHq?+cxNi;i@{9u z!N@I246aX~wZ^*v%)5FolKv`}i1#D_jPJV8FJwIMWZ>(RAS}SQJiaBhia}GbdaiA!(jv|Ftfu+#Q+-O08 z;m|ITDaiwGP_~D;Ob22&pPNIa=MPKI8BTb9$=v#7YDN38`&d^e=V{Si{Bqb&nH0b{ zJY1&QF$NYCfr?g3=05p&dvR9+^*1MLXE$($mJEJMpC8TAv}fV9kJ~DsJX1>pwG52if5%q~Bli%KhR-*0f zDT6|p`}H>^e!Sx?MKNVnOlT6vVnW#%ABdY1=a4NPph%>Nv!*khe(L+#fhjIM=3Jw$ z{$9LI>G=c(xvFLvl(Jd;-ec5O;Y9bS6EG>I#a;f(=;Y@D^phy&L?|-=23ZN32uB$P zVo@{aicbfii-!oNc`qdKe-j5ZvAM$IjDV*gE{4U&VHo?K`219$4z9mA+blhfiKJ%G zdeLFzTq}&_2e$HIp|RyyDj~zQyVs|E=i~Jo?vkrf3=^9zpeovz_t9DhaL#iZ#zDNC ztvmvZvBEfS;~Si{B`Cb_!NSGvC$ZxBQs9cb9(c4g>BUn@1rv7cFnz zbTeBLTRSo>-2>F_ZwAva>U18M*KIe`g|;yI6y~B!>)e1`2#2vVI8*&1lU6X#6CcMD zv*g}T^sZ*s|1!LAYQLGoJt~v^9H9w410`jKMw&F{iLP%_PcD<>0f=nFm1o;6OtU!j z)M05tJ~`QnGRu}QuYhDS=Wf} zHJOt|C+{qQkjU zKeC&#+rE{?A|Ddue|FpyDVFL*tBYsr*wi z&)%uosNK zUx4G26v7elG2=qftDSlhLV0HTRnSv-x1I0Zi6>NbrO^VXJ9mTCg*7E}w-PX*O=*<* z=_${C8KRh&->XZ^0@TC|#h~PuCb>bTnT_|Y2rG_{Up0v&f`|=v^&%~jx$!HCJzY#! zjZnTT{@k~qyVsHvV>w9RZW43M%s@~m!S4C=OX3DV(NIGuIw+L+=kol!?a$9GX%|em z(^XTSaZ2Qger!~YZb6ct{+!8r2=|uU<-v^e5?~^uOwnKjz(uBpw&UaY2zt|Qf# zlsy_F8?#8Rxzi=tq9M%Y7J^Fhu1`eVL_tP61c?^;Kb6LmM(9OMz3Gl^rLrsI}9YW#hDq(G{_PKH0_45z6_Kf4tM zf$2R2;jtN_Q$WRM!t(tm08E1bAcRzm?`g;dHj_P`yx+hZLf=1<$*P3?MmCJd672Mr z-8phG%8jVhfMD}tr5 zUe_$d{g(KE^(Jc5@G%zdtkLM+==A7(CGl55pSX`2HR;7e2->n))vA)}AYmJy&WlES zE!j4aqqV557?vS!(2FyuJhb0R>PvH$9pX4 zr5id?_fRk#Kvp}R==B_kKlHXKqYb+9G4I};T)R1Zvtv%71+VK>oy6NkLg|((^vAw? ziN8RcjSQxcz~}ImX4Rspl}mfgJMQgQSD$bXk8)*d+se1}od1lcZmsK3A9*cl`8D2t zLCH0tEK_9#_QsLrDOcZqRYA2+yai*ZG9>>ND0rS}iGVH?4)n3xx{vwjH=Rv`qMXzV zQBGRi!z1SfsgJbLTam%`PcZyciMq$5f`Wrw-L-J3^Nur0^5LKMn5ov)4nLxIJ<1iy-5Vuex zpS5^`ka(djrTQwWgT;rD(k;5!?5)Won-d$&TP~!bMN6bUeE(IFbKZ+s*=QC;A@PRJ z9x;F!TZjbBIL4HC?0@v&7$CD#iE;Cu3rZytV@alE%r+&i55TTLpVMS3h~;GL-rUTl z`IOesO0(ehu}6VKbWlgTiPt0v{~fPt651fT*6cgA7|obtcA%Z%8Q_v5_&= zlsL2}f{aaA4p|D@3HG8@i>;NjjY(O%_HvJDnYE1L+F7jw6p`O!e)hHdxTOgMmd!W& z1#g{WdHa^@`;MS%$%{`r|7T!%eI->>+!(aX#-8j7Cy4uU5-+EmpC8uq?hiz^AQR32 z2mU5?QZAz9>Km!uPQj>(c266L#~(Z*gJ*FkMy!H*O_||BQ%LX(`7_v0(r$kk|0)qlUx@jDSuz zr4q%Z*2Jli1T^J3dYc)Ab52Fds!%mqJXY^uVeU+f1v7e z38P9>T|RI(AlQNC%@00MrBz;%1D9#p{ZRm^0KtVnfVQ(Q1PY4lp40QgooPB*x^<+& z4a|yMFUwrnb&x3SZB`R5DMaja5O=aFUnSldf>C1Q{XeZ>g|JotnQbVN_j8sxA)Nwb;py{Gmbr zF>@3(0aEK1z;^#Km~nybM5Jp)nAfkw#r|`^TT69u)g#ZET4I&UHxZBT%Fd>nskYzGM(}d29fxh*>d_ zhl1%2pSgZ-U%J)5|H$^^L+--q*L_n!A<+mRi#|MHC&jHBm(Hnb=E>N?aBhl2XuwV= zlRpk`?Vc9F%{;kOFo)2vQc%pOE;b*xC3CSW6L`f9R1x^IQ8NDhQ*K%60eq*qnUQz^ zqv+@5930JJ#Yw4e5K;a`rv0P5^g+xow3<#(&33a{X2fkgP|*1wou6!449+unj+1h+ z4?VR1R00ZI4;@WVoLA07%M;;xPCV0p`}hU!@6}u!dK*9|O{-GIp(>7H(6_*Ux`^J6 z;$OzWuFU{^K)_X0Wj+iR%U_(I&DxI)*%f@Edhhl7wW#GW&~R9M=vo@I@&m95f@?Lq z-DaSn#_`0VUN4E=7H-cCQccIHxQQAX${g z#+N`FfFX*M-wtzpX`kerDs>1-2YfJC;#s4PD#jYAj2uW&nIsex;C$oHS3g}2gBTx@ ztBbPuf`;n$xQ5jJfaqLW^D{uB2sWTNjZOUUg;dYUqhYDTaq=GY4$v9A<>dJtlbYMM z3UqRVjGU_3-utlXbw!eDLOa&ecW>@zJ^0)(MI%%*LMi=$2SI;l7 zNBV?&+@+B)(3|hQ-@(WhAR2-|dy)IOHfP;{mP*97O2o*5_8IBI^gv(ZgECBzq{n9&UJa#wu!3-71UR^=b< z-}(aR6$$?eP#RuV7#9nPNXNk_F$BTB-^Yf=!p*F(-a-*9pi>NCH7RIkk}Mz`GF(}H_#w{6*%I( zm`Yt#y^u^(H&2Ib_z-rBmP@2^)UIF)VE^Vta(A-NSuT;9F>mfQD4~6+oP5s3Xm7Kq zo}eJxzDvWY@#^_ZFg2F+A-P^Q#4?GIkB&v~Dy_-&9hke32=TJea-c&7R3gquIlB2< z=v|kj&31tc(trxJz65}%eH7X#_0q z6GQ?_Kzcd57H=I7nL<*XfM7|bC6jap9321F_4FTzm{A(od=8Z6FFyLC&{*gSr{neS zpeEEvyo~^x5S0+?xvU_aryU5Lt(tBVZh-=o+HcbId?)cJEJ);u9R~bVOEu!%TZ*)1 zzwhs^2`~JdPBfIFy~8?%@v#E%WuD?~y!EO$OVqd5wy}L5zUKy4Yhzd;12P^h!c{A$T0+*Z>0Ii z0EdX|nW7&8)Ey(Lf6V_4M`YyQ0fO7@PMId5ZnE#B5eO6(nC$Dw#k8pSK#VLMBM*-a zkqLKg?xK$F!M5Am*TdSo?);DErvCgo#pV-PHiW+ zn;^*zkr(16A}5P0z?O4;e|m(Id^!<7&rhFrS+dQKGs7t%AXdc5Lp=guP;qY1)mG3* zGBp8h`$?K8@;Wl8fyzGX{M($VCu#^s%OM$NrN8lwKdo{98-KaZ#6;~UB<0wJ3twmq$L>R)?C1QBpL-TgSlK z2#*7|hy$Yoyb*ElY(CVByzfDbB9z5)!b+ibhqfmxHu_3@vy1bK`<#s0bmHz$I-k}7 z?$dz3Rnw6c#*&Gp9n1k62eshUmwF39mLIRpJUkE-DrP1Bz!xg}8R5qMLlSh`8$q_D z+({eT4Vwd0h__#<igs8<4xJ01F(-C$&-l;Umk$B#9zod^-v zFWWu~LyD{G!Opj}hTnEau1JU2?sja(>ziEtv=hBZqP64ZwAPKL?7vJ8xMhYXo%@=_ zEG_d`ai@JYRX%m3c4SUe_DEC6{Zvkkkoa75&gl4dUP?f$Js*hW9?#`>6w^&83#5?h z{OM~-j)!2bS)q`zVa{QzN~`d&geJ17IA0QqY$Aa?Lqm?LX_7eyV_C{xtg zqRhqXJC1h5QhS<5yJ;8n1rL&@-~j?gzVa~28P=;bhK3oW`NJ`bE;4iaGdC4pA#S{Y_8Z*`3V~<7x94adDruMtvo%33})jT&$Ort$3SQ%A@*@?VC9_qkZM8pbAuwu`T2mXwXH(jQ2w36uzT zeIfwUf5;bnp|MQ}vpR62SOHS%u78S7 z-Rxjx*E`8}p5|fKqF+Au)etpTqQ!4L94|ifMI|&CE*Q>LL#e3}^10p&lxdx>l`==+ z`5GY#o>s3!C|@;I#PGhiXstnJ2zVOWn!z~D><#FQN1IEy$}|%g7NCj2T=JX*aYvIvB1S zhb6VYQV+|p#ZI3?6MYnEKL6o20Kp}i4{&}PFmR?hkPmD*qK$R*1h(Guf~SGrUuG9( zdr$S%JS}dWtQO;p&e?B4h&=wA4*oxr&E2@o+p3|QW@Wt^F+c$!tyw-TG_CI7%IvCa z;m@H)&>BOWeUChDV0K9c?rb}Zh-J-p)_>zIamYM|i!htfEH?5c%SDdM)NCVzlO2PK zeKTWdPdXVb4yet~zo}rxNv7GyEiBK~i|OSv*i&j|lOf#;N4zbnhu#{Co|v>IyzyK- zhpc3Rx_l+zb=&RYq=n{h8BD(2tvUUm7V%BMXT6{Ia8DGvUk%~5?G7cZD$f!V*H_u9 zs(tq<>D}J)N_G(SNkMATu|~2ou#Y_iU9jdV&oeM8@UKFnmoo4vy0WwgnGnD8HHAl= zVy%m}1g;1Wze&Q`ZDq?nfGj>U?$T;W>OHysSPX=)gsXb${KO~OG@(7ao$`iH>Xf_F zdd7UM#h21w{{DT-H^k&?xFX4JNSxk?e zC3$M953N)?8lOX&W|YMj0LjfsALyegOUq~%>O7&F6B_w7a^4zs1krbw&lupaT_w`U z?L378I!KN(E~wON98?wj`pkUIZyF@eNjC(X*{iYaUqp+Q67PJV(4-QyWYowvueNr` zL^OOV8lM{US2qls(t`mF}1ZR~_@R;q=$Qur`XOMNo$a@+Z?k}>3pZv9ftsV^>wdW_ha8SR^nZNlVH z>co}tAm7Xvlo9E{vnmnJgm2%aYi8#2eIja}#b_d6+Ss6v6D5nI#3SlI*Ir3O%khj|r6Wb&UOc|n!WsCJV6JkB}2EJ9Pb>*e8aZc(EEVsnE}hoJFb>E-3rq^%~3lZYCb+=MxkRR|3~{)NuI*z3AE7NvP}rR-R`2=)#q;; zfk0mSoOmTo>g`30+$)DnoKVuN@P@fvb~E}kR>RI?uO8eedfm_;&OOw=&qmEXwH~u-|)JANF zEdOL@Fl8C(ASl7kjwv7Hs3Qe9es5ZDNIH}1=8+OUTD-Vt!+olpj2Qg~TXG=^-(C|d z@LA%9cYeGU^H})neWIZc!?*Dweyp!m+p=xAPp&2QET?Ga0i&xRc(;g7D4=0kJ~w^S`XQx@_moU7P6EXC!;EWu4{9-~XoF_M|4^3ilX}3C=E#*9It7-@dS+ ztEcC1?ha*h2>mQ0!+yPoJ$3ON@nqb{z2SC?k1N+FY~RtNJBv45^*6LUjDKYHF822t zZ$r2LP0Ft~zk+T8?IekBe~e=d3$7-Fh`@b`v{C`Pxa>_(ZpGnre#~#kSI>-WYT!dU zJn1?|db~DG7-!0J?LwGcuRlV1gzO;KIH&1->W|HsmP)_{FEV zS995&(YNC+rk&l0Y4~aQ&~DgmCgUAxHJAs;VHI62`@Vzj8N6HufsrzC(B}<|IAd*p zXTBO4pD4s5+9~dB>~QDTW&Jc;=ghC>{odA3;js0eav%c)E*QbE@PX0yw0~wMfECH| zU>=>SuwZ#BWN?aX z&B+|%A#L{iY^YgfhBj>%N9^YHYdW3OM8FL0HIsGjRM+$lJbhHkVMCWHC8D+(il6qg zPS~`zp?%fLq)&XX(3`#r>qz4qZeTbp11F9G?Eh{bi=_Kb! zXAIHE0U9z?q1gP5|00{6V&=#TzFiY%y!-G4(~XyG^eW_aJ8o!#v5ro73w@nLNsNH- z;oh`@;*@flMc4^`W@YWH?$OLo_!@nq6EtGGKhGZTD%2ge8Xd9~dz7Q}Fpr2eNGT%! zj-Cf6l=F-|y|XyF%f+V%eb<|e#5|GE2x-;gekB;7m0?^OT-$1*5l)Q?B~hhS06LAa zH(n0pa?DG&h0cy38OuyYOgS*jFvjv+dHJ}dnFey4o7!%pBOE z%#qC1C+qL3a{7J+i9*k|1^gJ4}?2*w`_Fzv}g@(o7y^KXlCCLa2*9|bc zED+0PoV=KwS3#?L3>sKuA9mGlOkEQYmK{~kTb-HxJAnL!izldCL+mYaDt0iFCrUm9 z2*`|!Nhq?#jmUB{X?g@F2kYWYJwXPP^sox+LOb**fm5^BL zml9~)?UCA<55xPW268`J7DBYiojtgrH0`Oh^F0_(^IREIG^Eol=`buEcrhz%zms!b zAGwziUv<@A?Y;tsYE?4T3A2|{yr<5HmHd=hV@Q*1Wy-HqAPVI-Fug#zSav^RrYEjA zC*j7GZV)qd$9JQ&8K5>P#Z^1mB;xr#j4z#LZ*TNj`HU!!6zW$`d65inOJ@uUq+6b( zcC{!C-wSwOcSpGZ%5qy>IqQ(qYfBkgC?H6Z5SB3H9STk_)q}Ae-an{S4ruqeIkq!c zYD@ajS2ih4FC*pfb&u{J#`16aWU1~-e6o(Mz$qkFf1r3+Icieu;L-R7O*v%Tn(L%b z^w=HWT_pWF{Rg>dv(h{O$J?LubM{EGGkql0BGH>Os>_eojmM!%ddFNYbiEQ`lr-}L zS;9+aurun*#-QueIhDxpG-V3=&W#p<$KL`Xuf$QLJe@XoTO++s_EgI-iJ>kf%``gr zF%1!9q`s;ynHO=U#nXg%qst0rosXT>19HqG`M*w~_Ex|zoIh#oK%7|R zikfNLsXpo0Uj`~Ew&aJ(&-mJjeh!-Z(Lj z{{nmJh-6fdK)n9BmlzmXz?;#El0a z-4RkB?9r|1j#m2+D-NTiP}PKUx{JwFI*7OYzPin!ss=_JHj}T5@dVe@u;)W$c*_@` zi?S!$9{emf=B;2kT0Bge*3`Yf%XKbLZ?rJHYrFM$aD+Z?urPhCothlV>h5p(!%#ob zht=Usp;%ub>5)1nXg8@McbNKh#B_Wb)oVFeU9R;T_G5ov z*L?cmiv%{C*~8m4X78mMehlPVv&t$(;BljsJH)epC+Qfnp`(P`N-F^edoPg2#%26- zDVKjP*=zyA2n`Af${K0D#@d;rn8P8gM`Tka%0+=-#*sHbG`1yq#+C@xn+q4Slc*Ii z=d6=X@+Vq(G|lR$fzT4$Jr20xUe}t!-X=Nayizp>Eeldsaj2YtV|O>)V_z-h(SFj9 z&{NsA_F3Z=xd_`U20z#dMS6N-Mh8zk0cDF%0JUil4mo5k!LaE`Pz-fsOA-`^Y4f%$ zKp{e_!*fS$V=aI45g|u`7%6xR;)V)_zJdsa4?RTt2Ah3Q0@p8FqK~ zD7xH#+gO>S(@SbX#+{v@mtg%p)j`3;<3XBlFf9v_SvO}vA=z7e0pWxY8v_?RWOV!) zYM?2Tr_T+HI5y2p=FQ6|e?}9FT5Oc__W)Bj7*r!>4`}pm+MKsIDBM`ou%e%$@?=l9 zoPXw^Jv-)}KZ|pSbHh6v!W$jvTUi_g8Vk#s(YlX@yH0iL`{+M_jnwh zV~&;TTu;Rq#oKN=SU)+G!{-?&O_qof9J;AZ^RYRlXyi(b#G$i)xm*5I+yk7cJUr`G zUk_5w2HOVYsgIzWrlib|v4FDMkmYzj z%KKz}a7Z-YgLqR)oO;}zA_imXU)oZz1Xy9L2Q8U?(c+nklTWN%~2uhra11-MwKQTB|v7FF+9rW--&MXp9T7Bv0WxG_4?g%s+HFw<{q( z;+Bm_Twvk0)LOZ%6!vPX1|UU(`Q`qco+oBk7hf~nd2)VC5-R{%u)(bA@Dhkv3qFwd zYJG1x2a%LUQoe3CBASPeW>=KUH>bT3Y@^B}R>s8?)S%4K03ftPuzK=JH6haPx4-)w z)F3E7PgFzIm5bmlYT1(av`oxZlSm(F2}O<*@JiJ)MF}2G?katJ!mmA8amakNNsG>| z=gn7bex&o)SCO_fV$)Z=`-Eq`SknTAooBu1!D~0w9e-0RkI0$RKmLx^j6TPnxdvuJ zx%T{!J|My`d|%jvM8lZ+WG2l*8Gg_1nJzc-tEP~u>;-y#%En0hfI%@Di!35UFWU&do@#aDRFKV-_^!W9pia7zNe(yMyeR_i$9j zick#ztPj4{({ByJcYcs-gq!~8>$&M+BKlX}gHUe-0uCiR)#Fo@I=jMl9; z?^yfKudl6wmwdQ!pOoDpxua+kK>{}`4l;5`W4Y%3RJq(iLEoRK-n@98Zf?ytSu)D3 zB1ixkP|GW z<*iKoN)tt#_RMP^X+CZbCNOQIw`^V1=BpAPr*mu9N-htnAf}(sc*Oi*NwP4Vd!MfD zuSm~vOIB74y!>iF*aj^zHpt0I)afiPVgz8sg{yv$k-K=)oOq;4cz2%_Y*t9nE8Br) zphkv*o8An5LdQSD-`|(9q2sP-lU^$5XIIv4D^a_r?|U>8T1woq6yxyBM*Q6=ecWlv zPZ1r99k%Dv>DRsH7g-e}2~Y&3pV~ckN^xF#hrbdnr1|i1IG_afw!WujkOEVORi7tb0jH$S_PfSicl}fp#A4S#Cw$*2buvF{J&vm1Iedg_(i+Kuz)bR4$&y zgCt)znjThTvnRrhA3)#5Fz@ko3{DCs^9GmS4s_scvD1VqgOY0S#&=V&x@gY;ju#Ho z@;6Fol$haK5#iL*f_}0!olgGtCl?Qv*foBB`nT2GyZC2w=*mSbEq73)yt@*QQEGD! zjkt!DsmFu(J!3R(@sA^%_ryQCn`o;r4D3z0-$ve(EI&2Q&><BqTs&}F_b=m35LX``ju`Z zU5_;R9j0~OESSc+TS*Q^=Jwjcuf&q@f2AQjvpg2^B~{8K=HIN@ZEiy5)~U)Y@*nSm zd9&dFJC%lx0h(ubp0rcP?TO)GhSa<_o5|z7#}sDq;U_i-7%dE*#sp%vd1;+{%Bp5@ z7i<@zKjq&Q_3I5Nb+C=>0bunAI$U`C-(ntq?Ki+#42edG8QrC}v#Y{hGKZ9-`3$ zdU&o!D{RGJ_#Lt9ZXIyz!VKuG!%pNSnEG%wxl?=k}>3bNyDs!#6s zu)A0c3o>X+W`kK>zV8_1?w)RryI(fO>&I1U6ss!6JB){r3-5~OFm_a7-_B6cuIcc8 zei?VLT5EUh58;JmtHjc<{yrBNnZZK?gFWWfJ&ZU{96pp5@9AohV!_;`klN+6ni zA@T%DK~tt`W-U>bPfLn?Rlm8{zf8WB#o12-Mii3{Ud2$>MAmU-umdobm@F*^$}e}4 z__)3DylhF(Gi(t}l5^9{W(W02-H&W0_00P3uDe;1^55}OsWbBa9!gTi|LiVnc)aHq z@^5sj!x>G;(Ju-0P+;*ref5(Z%vdGIJWvW(&uEB_Vc_<41Le2J&2-C2r3EY*)aW;b zWOxD#$$Xd(=T$H@8=n$R@u4(;IMBQX}_&A)JDhs-SMXcvM141qzrj<5VD z>doHl_s>^iVQj3zxiylYQ#(7JfRPe@>)NxZC{QcDJ3aLw@6CY z5d@_V(g-LZNT+mcK)O2w2?LQ132EsLB^BvVIz{?jo0+-C_r2fe`7$47m~+lvd&NJl z>$h}mDn{g}=KARQ^+M)n$8jn^aVg@lvEczpE??hOG)^EpyQN;bYupO*vZ~>mrS+ES+OAPOV}HlPIKVGdXiqAE`DgEtLU{)6Ka@5C5qKfN-9MurnwQq+o7zKguq8?87QR&mf7#-^(LY4cyAjqN@e!wKw($lhQ=8 z#6dt}g4E|6T#ewNLOn?R4O_h?o@Uk?L(X}Y(V{E4C14>W))xXR1XBdH2p`;hzLH?N zdWiUQQsjmsaaarM@^PVW>(79d&$8C(R{)ia@3ceY&SDQ}=TpNjq^&_2f;Pg??s}nV zFMc2$Coq}|WyJ@*H4itiM4N#lf)HO~Z_pla3xa^j=7^oM@npxZyN2>(nxxA@*uaba5%t<~3%I~=Id>{19eXYu z5k^2d6QOEgRanss>^IaKUkZR%6}4r(W*;8~#gp*{Om)ffmml8pEkONUVHMvWDl z)*bh8qu@59HlQl7o|KenKHo`hY_&N%9Dwlg6eU*+%A4UnF|e~Fmw;Co3^z3TIg-gAsU(k(xmoVlY6%&z|UV z9?rWo+nOQ6^Y5usbNAQCth;A<+7P%Wd{b;X`f>oVXzCC zG*tl|TzgjRc>}O+%~M_o<#ecd9wXt*#CZHR5bOm4M1W`nFlzADF`}XybQ$#C|_>3|5G7 zOb2R@gp)5I^?-Mlxp;OQypX?CLEb7to+l&F^CEV3{1+{VD}Nw2dz56#kbN z3NJy8{bW%sX_((2q$K+D&1}L*@DZTnB9j?V7Mx%b2UaOwJm%p=eJEFh z$?Hk(X-=B$^{RNAlZXzm1QvvEzi51k{t53bmtbq{Ft6)Uj{y7zOb8W_6IFK8yhYPs zsZl^aa6;iUa|U#P7R|s(P91&o>h_Yy-p?|gqVDpnqH|9iL8J4(%y|clO)W7t2%z&GS^AHHGUDH z@90NG;@m^rxjvGtA>#sygvbRi+xq=cifV@_YO!U*6&-ABi*%towhgePtaK+qK|K$8 z@P05INSsWZIh^jf2)2qDU?P+`?pmO~NH+AaDDb#NhDs7$>i2pdb4#GrGt>K5=pCj5 zB0r7|jm$G3YYZ`Rz+rpMDczc}(=<${0(c80vOWtG=Y8f_7D#Hn;j0_9L0B|oia4q$yKc;Vbvp2J8D zyge*h$`?wEoUgw|55`r33DZj7#~z@>+JUm-;MMIl8`0EW7hVQEe_^dfHQjqixxnQ+ zm^Vmhm&Ylh`YX?XGqs(51(w86b1BbnVvnSVs{}#}9Vyob7 zGju@D)EL=qrEufsavwrq!h4CEsiW5`QzL|UPZDghH_)t}f~IH_$i@3!eX;`937)Ep z`QzMmC4u_U6o27oW#KM?ccKaOy8$s1INd;(c5`d<(fN@!CbrB9WqbeD)`N}-6UZ)v zYpv6_4EMg|pYz3xxWuC@wMfhAMn0OUm4WI&&M^X%{qwG=w=u{#P%ia&CE|U5%WKC- z>f6hD-%b9)iPJhedApg<9~tEGB@EO?d0EF9?0bueB?iQITNUmg`0};^Af&3g&>AT} z(`j$i?-%H^14XMJ-oKxGy#uyWMw6lV2pAImEkcB{*^TJv8Khp<>;es8NK2jK4J$z= z&S$c@S#J~)x116+wL*8T`SxCB&uI9%kfCx`d5l{_ex%uf9~tyK8J;m96mz<}B*B{c zB#z<(G2aeFOQlH1387t{F(rpjzsT}4YSF|Jbm)6;m+p#iEflPMo(Mn_LeAlT6gq+X zIwrU1#HQY9v%a$7B*RNC3lujN8N-iI^6~=okt^N6JA4}th?#o98T1{WZGsGqawNX@ zIOTdv*HfTO)QKF^^=;=E>V1@I;Fmr|Y(@s6vGl}8UfZ(z!a?m`$sP7U?)LLAm@S;#bu+fnjKj-m|Fppi>~r zqhg$JQvp1zX|@nP={vmeWzj(_+4pal#95S7Wa=oJBgJ-YK4baoP6lTQYIeJreYj~)!Y^Bn&d9Z&kkOd-rThME;0zYRje^=NToUH6V+i{I? zr%ZhwcRnx~sgeI6_Pzi|_}QEGm7nN-y}Df-69Mn=?mUg9T*CWndw4*aKtZVF6p2&V z9K}4l1M4t>M7Fg02f;DZAhVJ(aP;&sC}{W-WAT$O16%NCUQE-AoiZKRA^+d45(fh> zgadtVkrdnQT(fmK{Na7Ns}4R3vG?Zm!vmsE)}q8Veh4cDv6MFpwA5MPb--G|`Sf^T zP`3Q!8VPy^?v!}3!u|4H^T!#*4pwU=>?t9+lCwhfqv{`RQvam_9DMV~JHYviC zA(ILV4%{#Ehl&D#TSO5+Z2UPl=85yRM(TZ2=9~WSoZg1TAY(W_Kj=`n-)ZkchRZRm z^CM_5@sQPGBC%uJEJ{wRW=S7*DpNF=Q6=WX&diR|(%*!BbTXUe$2kw;HT$vM6>m7P zKMKmcHkvciyt^zbz$Q~gIj6chlCKTn`BG+NzI-0%u84gTJIjKzx3w-CeM$rDy8Ut< zJ(MWH&m&tpf21e5$flJpoGmX4P2jP}Z~h_o^}a8Tq}Dqc*GY%@t*2xH@6BE-Y=cwl zM=mkv({CE?4L~@W?YcRIk${4~%Wg;T z9|{3eVJ-G@&mW^@&ICgqI@+%2ydB9w)`KBiW#04w35eek$o#A~R-xsgKYjoq23}Ad z(e*n`$0bBX{v8(;02t=5Yrr3U0doL99DKUp5IXhL`qd#e@XNr@6~_nvGV3Gw@U&GA z_YW8A`LBOO&_720RQ})o4*KU0n@-|;CAz2+1Tj`%q>ifh0n9GCT?~J_p;+_jzno}q6`&|R2mBKVbb+YNppON8KUMy)QW{q3!ScU7JsU)%*Z_1iDN5WY4bg7KRq=J@b8 zSF6zcT`k9f;7!@KE&J;h2AjJCPP>T3crOwp!bj?1NbF zo3|$wzk;#CxCOS?VAx9C3(CRF1X=0JNs~HPGq=Dl8#LPz94t$w`zFZK;R_f@4_f%^ z{(h9fH;AA+kg~_D-tUrn)`!36JS=Z)grcT%)1 z2vUWE@@Bv(Ack|t>lFo`IPu^?x(6gbp2Z?epaB-9>qM6Xg z{FDDda019&-|cSO6*;nneI-Glwa?}&PIpGRi|W5aj-#R6L|T_G_cJJu4a_20C84)S z0-Oup7;LbBIRiSj9~YZpJ3VmQM3(^7eIV>JtOLo?EUXO8ckqBBRy!&R0?Cve1u)PUryK&zND$l!Ne6OG2Xj}KahId>x?ixJ12(f%gCnm6 zMy!+o)>`7eex(#>=Kl?1dtp}REvM|(xa=yl4ExiN$2kPgtXNI;_-(4Is z!O1L}#Sus6{3?_M2ZB}p;+cTiKz{-ZHAcWc5w@HzeZK*3fqEQYGZQ#s9;Se-$Jp%{ z{O1m*r;pG}E4#r4adUU~PkP_5ELbsIYa6h~7b*Ku{?Bxf2z@eqyK05~+IObg%PN1D0Vf|VZhA9qrCRp}SgaS9j zTl%p{%A-#KpJO{k_?{LWD>}3No4hzVx-LR{5MI|_yPIPl-vN+UUx^-TorirGBfHA> zZPmlG^4|q}ivdY^`)?F4nFyomYf|va9?o)j;IDH4uRlCi^XU<{rA48omv3yUXM>Dj z=)_0_h#YN)eEDi$2|39TpTK5xiDY|t72w0>2|Qs7*iD2dfeWY)slc&h3d8R1lV<(& z$mxKoB*IE*zreZyJMKE~@qw`K45)$U{~Fk%bty4GlefT1l@65!MT%i93f4 zlnAzQt)=DsKaQ8&aNj#9gYoYc*l3%Ic0?F2v_aILO7pY<7}Y_wHuI8{j(um~S83edX)_QUWD=(qce78oi|fdJqYpBj<^4eD-yitZMCUF=nVzS5>iHsR(Dh8{x`m0-m8flkTtcLVw!LR18tIhFS zY5-Sds02_uUBu;n-{0!|_*tik_2Jbn9~dU2b4T7pMS%?Jk+*@Nk#KoF1-JmIw!#F* z=t0;!w!dTk$D9a}88n|DkS}BV{9C3zaeZ%B}V)&DpG-KeBB=wGRAQSH7xSkByCmVgK~(| z~hQ?~&KAd0IU|i8K^})zxNSzDuB;gRgnSWpj89)f&2dn&9mAt zAUr?46NJ$APj@@P?Y7-PI5ZXokh;=ZoN$zu0b=eo3x|UXO59(85QM}) zaK)&jWpEdM1i!B@^gF!b2IIiT-*VTLVE@na`Du~zT(TUw`R)4h;_1Zov7vIf9pRw| zM)O_U_ssvCy}pR=B#$@bgWSZ-K@QYNfJ<4}X6W$T_ULdRFBB^{PQ1Uit2- zR?cbK6gu%`Sr@MUoPa~L|Lpbu87rh8NK63-eQ!|!G(!qRO2y#s*MkE^X6}5}e*?wA zFhr14p_}Hz)%3c14_7@r1mQ7K1>4-Ogb&ARf5q_d$7V^RwPZp#Xx{F97Osk!}YMrr9&{#OV0ZR@Wbc<*4U`t_`jGk(7(Vy^QYC?+!!lw#T`q?GLiQ z=7sq)v|v}EBhsDUalUAa=Z)kIAmV_wKruK7L^-Sx6ub;|U{k&TsRCM<0}SQ591ZRE z3C)7u3NCD;fw^>|hT;HD767b|Qc9pK4HH_gf_9C23aDbr6dTrGP+rV{4fz7;3bx9w+Xk|VDW_4>!Oo=_{TCG5(Uv7vvKEad4z6UqlT0X;3 zHzx>|i~#HED(uZYzrg)n|BE+o(xe3g`ZZZ*{ywnHZTv{igy-H@6g!n?8u)x=kroXS zP~RWpIM@J@CCLRR8wA!ta7xn)I%vFmAZ%E?2={I>P!*~{4u?NpM+XJdc(4V%hif=G z7H<=q0pjaA4BO@brEbBm^q%54Jc8PS|7Zl*2HP*j#p}Pu#R^wPV&dyqm1aK|#?QlD zdCkN=j|_CL{{ktu)PpXMh!TI_ZAjTw57>d^t3gA@q|*b`M+2FYbQlVNJs2j8TX*_a z{PdN04B#4n73P*v1u+96U>~?WQ%E@YckyDd2@xQP7k>j-d@s|!4bEvg$05->Dbvko zeVH1GCW(t0p|c~n_ZJ8uO#sBq8H0l67quz@R)0Nn6!PybTq#pA%+ zw6xKGy{}blh(e`uO28(Wzq|Oy_s-?MlQ@tz8ViFU*%+&%5psVAj|P~yK78a5ND0bevar^DZlSIh1iNXt{+Z*pirsN{#^eh<9dd3 z1^U-gNHed|0c>I&F*cxOi5GmsMJEMhsCjMQcfPr=Lw_*cDK?70R&opK&&UE$*#fY= z22K?c6KZx2t|zaK+0^`Q{s*%Ee{t=vXCxIq=Htvg(6necy=F-Onvq=g&5Z!I>w=!t z=PFnsGDmVUzmR;Xg4edH@aS#R5AC{%vokG^Mi-X`i1VZj^wt7_Dn1Zsct#WRZZ??( z?#kecFu~m|JZfPcF18C`RUW8i>1G?(p3WA>SVbhSYNwj#|4#Iz0oNVynLhfi0!)St zL%GI$342q;Nl2XfU_8n>?|mqDf*avhOf*BR@fquxItGVS75kv3--*QVMq|&n!bV7A z%?p!&hI%=9(zbTpcrmk36ru47-e4V~y1_*hC8AW$H^ELgda>fqE-3%WXr_s14;Rn= zx^N(I;+v1t#f1YNXtivz^$Xuj8a1#Sqboe`r@j=;F5k*cCHra~EmnQl|JgIwS?=qz z{f(Q$(~ljJ;XMh0Ib%L|hBZ6+GCDT*fRq0ge7lE3DLpI^LBV`^W{+F9TPvl5Y#Zxz z{ljfDA4fhK|L3ZWZBz5wzU0-5D<@u%<=7WBdHkpvkW{~~YZ>)Hi}a_;{j?=Brtu2) z!5jZv_TXA%Q9AZyz!fHpq}f1~*g$-S|NP2T9Js_G;JR4JhmbnmQ>OsE*QOJgL$P!L zHWC8^@LjE^F6ZLn34!*W{d}blnkRqVJdwI{ZnY`iw9nRkCP8BHndyVC@BP!?NYsl2 zLev`>x&Xt3BI%O^jt8+0{u{h{=lenGhxLbGDnMlM}x@6;D{ zCSITys`*kz^WnD#5R5Y@0lo6TQj?DMYc$W|ZD7(F>E$guBc6=SiX zgvhA-^KPABIIyFV@Jb#nJ(}`a=zGNXtD8JI8Jap-zoI`9X;mxoa2mqW7zvA8MiL$T z%EJL;euWu91EsMS*%iH?qh9&7U$xdH3&Aen5>TuOh8yP*l>9ks9GrGoi206a0ytY0 z293LxA49JfnbENC(~*N)4D_p6`t&OT8|k<(y5rD(^_=v4i>^CVY&Sfd+u0dNYy9pz z@j>g9F3^R)*uz^h&B@doJ@%G^PjJyk3Q90&gN26r<*|}D(HtU+tzVz`UKr&@n4a5Q$cRvIHqM-_yt`MB& z1!0iu^UxTUc5~z}uorRfYFXfG+IZ*dLA9q>WI30fZNeOwu*8dpmLWoAQHKo@HoDSt zUP1ZnJV#Es#|S~Z-G&B=bQe#oT=(tUm@Uodmb$Q5bx$joh zs(znpaM>+s7`>M3kDTb1)apVM?U$Fn5YRCFdq_QhZh&H^cMB|3Qauoa;J2H550JrU zChh+kQS~fNK}=Bx=c!{syEB)A_x~BqLXu6r>7#Z_b7$K8XM-q{*7NvP5OCqZNxpCL z$+{i%#e-cY2gfPba`oZJQQGpv;8k}(aM*`&$>u{galYtGJcMBJ`0q9cmQWxMyHx$4 zvT^Dktt0N6-@sh`{?69!QLVeqqgCt=dUaOb1VKgFBL|uzDkd~9enXBIHDN&WaXJxV zb-VW5akAQBHd1H`tMRbUu6ZF|b;?}LJF^&k{m6k)m2zC(e$}_%1S1(h0woLwrn4}M z0~A~aQ4^>2=uD_P2%H2A2=n_tKjnY;C405ViJ~+2O+i6zDNrQgffECmzTvf^o@u%E zDr{lpKxBCHH2-Ce=Bgd{R8H%wIuH`J1dH6{+%;lnP(~* zSTBzaa*a*6jC^5_G9B>*Me+dCWCKAxEiNDvG9~>+zPNY%&m3J*4k2BHLDz60+i=}~ zJ;@hc?=EqNF3V&fxHLg{$IRQP* zyb9w40GR7N)yiiWl_j|ys(L$NOevD+$EfG~X^d{I@9Gt=4Kc{Sx0@Y7P6qCaiSXW) zxlqRK{Znxkh;uf-Iy2iz^>j~fI^`N180*ffeMkqR&sMBr0D;gY095uQf&A*$OH2QK z1th{i0iJG6)r4f1*&aw8I;SBIVV*T7xM~Hab7KMZ22_e>xw8Uu!C?#tEZngw3m7#_ zI%w!iYpf{D{IFN{?LznxuOiCcuERh?c-A3x=AZ-0*Q?2dHxWG0x5(nzBUr>z0_wiO zK$G%*)+)?w4LngMMz;%&{PI_=)um z&c`S3!7k)2e#L4U)DH<84(d0r{=V}z`PlRuGo7C?Sc&1=;oP3+^g;snkUo75irV|Q z7dtQ{MX<<(+BtYCbvz-SoRn1cP&UzQ+2CeJKHd-0N&+HVaEfp9glTH&GQ*`ecn`t? z7lb%g14fp@H8%ER!2fp9hhUvFkK;looB1Z_<(Sf0$W!Vl6aYoqZ07mNQ^juD+(Fy= z2vgRY)D)q1zPiOp_u=j^jjR5V+U8ylDp?-OH9r*r`3qQnwI=klyC< zMEe*{Lj5!D8;+gyrH%HSj1>=CZ@%t}Od8r~*!RTyB=_;17u@dv!R02(oR?#9@1T#7w{~oLEsMc&!cb{q1d}t2 z`yEms@C&iBpwe;%;BFYZ|K94D9>_<)L*{IQ;#WmSl_TpHD_ z*S*K@V?~d3^)26=SGZ$we+rI~I@^xE*4jxTJqNatFxnoaYuA1(iwtiZmws`|w>(|H zz4>Z?*QcjrU~j0>+})5H4Z_}&gg0=LAAjv;V~U8y%(K0BY*!eF%VuS=TH~&2f6GQ! zxSI=0MZ!dZh|z+?3*4Uc(aoP;%ZaJAA4ZMgM4x;zNC^mO^ScR)UvsQJ;INeehxZYhF%ed1~RSR4_z&d zfbVg9T@tx(B4{KMnx&Uk;&J!(cL2|L%_AS7RX~fS=u0RzI8bi-1fx4|TJe+vn1~WpecJVe+A@WJU&l;FLFbaw{oygKkatiM)CUjWXPBn+12yd zfk?-YB0l@;{of=R${_MSK#VC~(q=t?S_Yooy<#oh;F9thioyp zx$ViUj5(}9!KLrVFs126jxS9QoL1Tq$22vezaV3q2F>Xh=kMKQ=b)$A>ZVm4vQ6q* zayOlN^4i2qj9lb(Qj@&W(v`sB&_Gya8*TeC^LTQZMOtHXS;pZmmeI9|{&-FGwC)+9 zm|Dg~xKYW=Bkugh&2C?(#QomMr*3xU0J_QBBG4YXU&vLdB&XqfUQ&~+Y4TY5)=OXL zN&6DiSQ;7jlbvlYqVx zSIBDhPQGlz1+p?XR5u*9W6=2s#vtX_6kDAp4+w+oG3C6Z#f@KQBU7KgIZvyCdJkKx zcfFcqGY|c$JMPHowCzMJQZ|1L5$<#f{vD$u&EiLFCC|wP=GbHjm`9kSdiaH1IpPTB z{cF>qA}uGT{q_|2yNf^*9lfny3^bS3OU9*LCyS{ay98r5@5&dM7MiITyLWw+DNtx8 zLkS)r4w{fstU;Cvx_)u)-yp?<&&oV?vU+u6*8RFIq>;v7)*&r6W6;F} zQq(L9KRyW*(X)`yBxUrydq|UP6SRWlkYYigwXBY9iNiYJ6_lvXw)Z#Zext$}fMt?? zDIzOLdEZBpH8{sYRB@q!i;;Prl)dmWwGr`?Z9*DB|0l)L(n zmq2d-idPH+GJ?+H zyKen&QHbh*vK+<`;+jjY&xoh40`PH4C3|*}Wk#5Wi!-VpwXop3Z1KR$zS9)-ewxsSaQs$?Kfz|9(zm|}rDtLCn z+jYx38O_I+=O{djz}+%8ee9W81QE=%i|)}&-YKqYX2i73zeC!N@n{8QHW|A9vc1i$Yjw2)4m&RSyLS)BY@J*C8DgZ;JnypHW#uQ6 zEJzIT9#Y~kp?@;ewiA|&E|~ElUJ%}YwoU!iy@_aMeD`s~w?QON)mHYT@6LHyvaK+J zgUal8$zgkaY$?V4T+ZjykJFr&#!%pZ;^0o1NG=yfh!OJZuJa?5$ZZ)RgTkEM^Kpy6Z}d2@>bmEoet$#g9{1D@-UCaFY*Q3#w+I>3jk%kH-G1T9XFb^r43Ym$`5EcS_e-B573Rur zzb4~F9nJ)?-tjPetQj(PiPoh&v;;jslcA1$6^*v}zI;~i2Je?o4t4RnG*dPR=416= zW-4B83lp89{hrr7(SGGvNPWttB%F3s>j?H%X_|z{ zWG_*K5@hz^HTUiPZXa+-p>cuCUEQ;w%cFvv;?`$63qPrB0@#C%wnpN=Ktyz3dN3BB zKvAfmo4mNxN$;twOYTHaw#yfDu3%+WfBxb#iA%{p7ySuctFMN8>=*y>&h0^54K<&H zP-K@}CIt(-(f5!aaNztZ%IyU{FQs`w8Ck+`FhtQi*%}wuMyr?wUwmvk7snBYKq9YLzC&wECDVDZcA=cQ`f zYizt4j~_Kj#(R@8(2pkU(VC$Da-&Fu=3Js%A3b}q? z4`Le*L1Oz942SG?__s@UJ}0RXq^S!Hs*_Sbr#mR#s@rOYMo#r|ziM|BsqjLt-iI^{fUvsCe?kHCqQ>} z@kJm7ZxxXr@sby*nc;}yW$Xl~?*8`MYstz-pZ0b3o8xPUn!hMwkd@WBJ>J(7Am42L z(CdzBuVXi{)vk!BJK0^b!x-aResuHe)6@}$m;mun{ZaM@#4M#XrY~tZ#T8gBnDcY3 zsp3!~37uc^TwL>}wD#Ybf7F@S_35gm!!D)Dm-0!HmLe&9JzZ2R6kM%M1o_1Aq#k`& zrX{>W{BpJaY5Ak(AM>CLd&3@U6+2=7*Aurl^d&~O5i-B7heT8xmlx+Q&-Lk3OL#n+ zEH=6kY98iH?{7}bR(|yj=MvAc(t|4Ogb(bibA1hHm#KcChXijml_Lm*e$}qY5ZUk| z-;=T#gj%vK6%wdDra(|a0kc>d~MyEFcX-)`by?tKX9(<+uF>I}c? zoirvoG;9(ww(x4VUDIGpGsheAMqwkA2+C3G)^`ix4+QBS?_|kkwNi^?D9Sx!= z&y1{#Kb&Z&JNX9fbFzP47T+ztFJX8S4U5jBWb~b|%c*oAL6eSX#kV*$znw<@A0X;a zCmf3w?$D{+=IRT6ICc8l-tI*La-BM_f~=^XVSsudUT7qKc>-xDY5gXey27Tf$jnZ@?)U3SZ`D^BL!Dg*zk7EP1+2-Rq`;Y@o4jX82=3VN z`^CsW{54ea9YueuM-eGoc`z}rirdggLuQHHr)q{kR+*W_1{O0(uB8$qsfhbwgQ2EY zRqyIH6TeTvCTu6ux`5U(cFLz^lrVLsH^U`{k zK-x4tml_$@hm_D=<{(Ud=#y(#CK(pZoYxSCVispvsWK+UkX?aFspS)+SzLp;ThAlv?eU{y^8pQRGd;pqcBg}a7i zlC4z>meVJDM+1rO4Qqnx+G>7r7&IC7-8G?3kMYy)lertBTVf~}LOI}mvKnkEr6sCu zb+^>Hw{)JJ@;5QM8Fq^)r}_-lm&CVZb0*Z-mTTZu$o($yTJnRX6D!$c&T>8UI1J`` zvr|<}Qf3^T86if?56>AkuUD+UE!6S)T&z;9cN2ByxfqiIG41JLbswfi z!AGTdVv1gWVyjkbXzpb!N+FU({KXE-FR92Jl3>2H#taNo(c6)yB*zg6)x{I>+sA(B z3i`pAU*nA;!Kos~dt9|QC6$6qE#M^TABSSxI#`|%uS++*?)8x4S=bctBVJXNwkz$J zv%VBz8X};36UB!glKSQoxMo;r^f^yyNN#3LcrTWq!N&#cqX zzp4W84KrdM2w+(D!rFqW!`QbGflVQ@wA@u#;#eYelg9NytNf!0Udkq=bNMu6z9G*l z5X`1?98KYrxYTC*Ok^4jHAboTw~Xc--&Ci5r$c>~<0QA>c3?W(Y4Z;h4!Vzx>!Z?q z!~ct6=uK=~sCuh{_wCvM@3QJP%i&6>GY9L3xzCZZGXP#gV)A3lKX9g}`HIsdMv3@h z56h#YFc!g^)I2fvv(s46KIy{MlB;qvqvHx3ZY*rh)_!8b}d^n0xM_@|$K zU1`6ms7($rZiu_6iK>TNmP_xKZLY$Td#*XzoJstT2pO)LaZ*v zOyY7x`9*oYwN_xG(rsuasi&51Gpz36-1k`YY+Fkwp%13HA_>M4pGQ@6aR^%9k6y3+ zl~J$`k=r%}FwPm!`Vo#<+~xmeQir*VFCK&JnzG1}pxiCYK!y_DtCN+S;y-`ToS24E zugiRD^7GoeSZ_K9YEQMSCsJ)^5tpBr9bY+8j!;I|PccDn7B)h)WYDe78K`D4DUo>U zR~w=HV)2iWfdBVcH5Py2(`vX^#4XQhaVsBIXhYTn<>FuCtdQl2eft)Q_$0-R{`p6@ zdA&Gg^fTpBvO|$HW_%A3Aj)QW!nnZ@ev82I?k&!9w;=|4L?o@0Bu*4oLN(G!M_!@M zjsCWSw7{K2`Bs*@=FQ4}0fE#64h2NmX8KfPjGL&d`_lXx?$#&v@0-eE1CF^L-Bynv zh3-CVP+(Xyn-3;DkLfdBe-(c!@`z0&A`m0fk%E7&dGM**mjCA!?w=NnUw-`bm)XAl z<3I*Gp(2UKV#D;fU-+?u2e=GUDcApFXt=~H;iR0_=uZOAkKAHguA?2`soY}PX7Fta zr6O&1EJTL>=sKwfRQ0(NxhC!v7qw?+0xeK&s#SLe=K2qz`QGw3f{DDgk$ek*2{E{> z94k2q7m?OM#oD2^+_8?B?(`M0^!x~qGSgwnQqq-I zKDy(PwEHd`;W+nR-W-WJ}A8(f}>m?{XBfySP7f&emrB=gbqYxxx4pE~G zm&@NVW{3sP<5hM9xC`l_=CXr2AW~_rDQ$~sr02wWPCd=L)N)K_B@(Sfis+b3=OQrs zcnJ($A}(W+F~7b6?j5MI-;fr?!c-$>#Q7EX;oZ0RcW$o7SQC=iACi$@5T>bptrBU$ zd}NosEP7ZbwI_z@KFsEQR^sF*duTXLxaSs< zDH+}S_#?$yk;<%@yoD?3v5tqr1IJ9Z83jfmjIj6p#N>Jka!O?Q>VbJ#1~q4abiGe$ zqx9`oH$T@YIeaw>7uELNk1o(yo_mTbb&oBkAtn%8eeu-_FMv!!g4bLvSdTHA;}cASr`t&^mt1SqbAwc}|m*6)^PzZ5GuaVBOHaO6G*quYPvPdBr&eswA3gOPocMYic%dJd?q#D#5epgv6;kGcqaps`jxx3O zhIRw$njP4G^(1c-l3nUC*Uz=rJ~~;JqU~w&Pa4GbLYoG@abpTx&f${bMU2RR5teLn zEXt-aN6y^R5A%9EC7)XJ{J0lC_(gM3w+Dp8PkLfm40T_um_qAgq^avGZ*VR+VTH3w z>KW}1{4Qsq!*U>I)lw}WjS$lsj}Rh@@S2%x6QRMil~$q~RJ&qy%YN55-ani*snOb) z=oTS$YG(CoBT~bg)z@D6Uv5tEoRGl|u?RM0cH${U%6pb4gKHg?k>659nHMT*qF=6P zvu@04m0MSON&3#+iI-p^Ho`7_HA?kvLiA|6#%zgjV95431SKZex0j#XQH67=3@Q`& zR>_3&2r3A--;aYc0E6hN$H$Yfp>=W}_v2V0h(Cddjp$a$Y@#w2E0%ajv=<85v@lJb za+d-ZoqSFm?y2xLa53PHUJlTt3*y{1JA4%xBCo{SO0Vzypv0+_6`cg1f5x8ExO%St zxignB37K`8U4wgs69}FL+j_o(x*V;^tBvvjd`Y!oOVf*at5sP~m0T^4kcR~6GfeJ8 zZ5ePclCp^;3W#NfJ`WlXd5Uhsyuo`w6+GuaFeJAmW-QUnVa%vheNcU63_1COkh}EK z9OENLSthB|yPS+uQy{vzehw;o9NAB*iw}{$o;PgWp6foXG?sKx=(Li3RA$OBJ}5N# z7R(uOBVA{xMH~e%P{YByf+W&tb6!4E!o>uS0e10Dp(A0#3Kf4RM(&p~^x-0$g!Z&Nr?-Y1x{%F*n z*bk4M$OxaF$`9;GDy{HDOB*Wk?Jkd~SDd-TIqN#l|Aanu#21XX>Y6@`0`dsYi{@eK|J6K9 z%N9=wcjX|U4+aYF7$r>Skj5ciis;pm=N!chp^)rZG#J64E=&e9N%+1$rySx1PJlT4| z{WfG;dKPcl!mhEBeyaOr&m15bQ1i^5BB`pER=>FnJK4V5q$NhVm$#LUQ?Q4SjmYTB z9p~1i=36(^NM?yWRmn?$?P;7KGX*2e90|5kPiVVNN+G1*soBLQW-Dq8bb>k%TO)IXas8$sA;3QP*&08wzvoGN!#dN)-#qDP5G*S!kbR-5BjMpn8 z$RQ07ge5Wa-c0S7Na-97UZm$*FvSHarlb6ajJrIGgTgDqKn#FM!WQ4->EVLM1aMxd zpw;MukM~J0Q3kt2n5FU^!gTkbAF1sqRk4e{<3pDG;s&KO+vB&S18EhTWed69M{H6 z)$AF#XdcBnNG&cH-o1yeFsBA_!Rz*Cx z3>*jn)%GD@LdGNbN8_zuh+HKhH(kQt4mL0gK#o?7>5iy*txov+lN13s?@LZ?y(55Jq{tb9=hXpN#{mYC2cG2o(rA9Ke^4 zzNS!U&?Db8gD@0~Rfx|?x387Pd4>>R!tYM(vVq93{Pf}|*{j;~$L}bT4IWh`cLZZ> z7!U_n5|t+&XYL0_o4c#xZTvb*8fpNYy_Y)E-4yX=J-K>N+T!r7F`^}`0X(VnXFVa~ z_}I@f;EpHn-$J8RGqA(OR$%wsR>4@hgn;yG4|l>tLSy_j8IvAU8^;rCSz^({ZCya# zxxrFB2J^GFW1;~EfDhcxE2`Gpx)P_%v`B}7xf*I%ZDCO<@fTH#uudVM|CS3EzN@i< zeDX=Q`Ud-j>P74*rttN(b(ul4Ne2hH+Z6m}O4h^(A*tm67tYHL(BVBVdWZ3=CgKUm zP&U7&;PEc~JL3x|=5A1v>54CKELSRd(rS9$h>=+Z_ud;Odej3|LHgk@$sPz(7fD9B zoHJ0SW|X5T`pSe~G3)#O8G}&K&sIlS^g>cLA^{7<(Y9K!(}tTKb)B} zee*zEle}p<^;9SR(9HstRmA{BBw0Ex=#*aSR`nt56eHMK;+7LRAJNI8HzekdQ%^4c zIime2l8iGXY9e3+XqbA53){=E$t4Q7<9mdq@p+F3Aq_$yvDm-Vi{2|izlfg4mM+>e ze|?VX@OoSX19XV6M-$wM>CsDk3SO#5Ciy*NlcwDzz#ZUQdbsY@Um18rxMYMh*h{Nq zY)_80UuO}VhPh0z^Nj85%+VP*#FIZ)iQ8C%D;?k2$nI9|4qjhrKDwnE67%YG^%t~C z#G1O?%Cz*s!?=6rlYa?Ot9<)|>AgpYQ_0{OBX6r^FCYp0)>XMyqordM_=CO~)AOQa z4NIP8^#7hz|Dzu8RF8I!jp3?R2Q}L>;M)y=)%tpA6=M59-^Ddlk|_cSim{eru_U0; z-}pUv2k$FrA&cle-u>i9$eeRd{Nq4Gqhh}hh$2QjDK{~sI|(=1;a&=zBK+-M|C@I1 zRDT+#h08F~%@Il(0qvn}?LL#&u>pyNwo;?d^7vZ)eXPrKZKlSzdOx884C#ikAXtd; z?-w4YwrmNX#8OONlyPwqnETOyz>DWX;AQNTbxnJ@-VW3~T{CO`(O(X3zPevKSy%5$ zm6l)K)Y5&M-Onde=5(s@YcjVw;s&HlY)@}ZJbB)ziuvM+9(gi{!e*V;tplo z_L;_>Wd=!!jBScSJxNl=5=lg*M%jkP(nGSPBJQRzmQ*Aor6#4PNcN=##gMHmy`*H{ zQe-YPe2I0Wu`eW$~Md=CBZ zx^ax4^OG|p`8V6_A>B8}pVqe#%lp5uk=RLe>qDb$^uZy7ok7%dRO~GrF`-=pA@3>6 zqLr5+9qb)<*UvC0k^`2KUlWt-5yY>(mi-6`gqH(-ztik#K?XqlE^#1!@4tg$>XaWJ z+vV9IQLKXisnG@Mqn`km`EW)Pn?$(Gi&w-(;6&ehCjJoWz+7oG)yLKGu6{_^v17NK2X%N7dM4c;73m{lv z?v~HZhpm$Up4|yx4X;woQGh39RW9)eMUdP|_BxcoE{-~Z>$eOIpDLceEB2qD)Qrt_ z*V|{ZOWvzkD$#G$QRBTg0_Lq8kln9mPI(GFh@&(QSQciMy6hl+jV2esp;&@lUVp!$ zH>|@5OS#6_{ zdn{Ayx7Zff5;yE`TwgmZjI+LMXdTqj;J`L5TXGqg1e$sD+r{|GvvP8)ls9AqeSFh6 zlJWW#-0O-8i(=!=pI$H~#ZINzta%i25#ubjs#{eZY&n>EoVV5Z4e^5o&pH$>l_uX0 z^N-7O(QjeWu{mjVfqvmf+|tu^7=g5zReqH>W__0nB?Q4-5k|#4FIrPumgCRpPE;W( zI>V>8GK`>LT(u1c#_R=o&%IdlFPi`EVnTwcuw z%9Gzj9}ZBbD>hlL3wMf|V?HroYIT0M`e)Ow_KjwqHZSpMy7RYxm^%{;WbiWBZI?pW z9B+{G4h8T{T3wo&Dsu-Fw+Q>g5FDxWUl%>n{!51iy(Qb{bSmygeOi>gd|1VP#f>sc z%@yLAx=yZoJ~`?Y0@@6NHy1t?PPxzh9ZLWD0CpT0P>Xc)WuWkAF1mZ$7Wdi>^o;iF zW?Wj}!%2dp#9#qtkogQVpk`HVv$M~a`a6fO&|#{7!~`83W(FQR_GR#Cr)f!4eDaOX z(!;727CHshNyNv?BY9>1inaBjg=-J#OU(p1X_7pY*~(G?J=8<-!0*V?J|Ir)QoQ)8&ON=Y0s*M6B_ zTl+G6(~8lKL;EaU-TG8B9}+)<0ERapkr?G78`Thkv|W=HlqHE26k89K&Xi$0%~naC z0i8!sG|T<$sP35q8E_0|EwwH4;6tH+!jHB6dlw!k9lI`fb5^+_T61!z?Y6M5|F zw-re(r6|3HB!MiAAx1+gS`A0!I^a`IE>0@34KcqSEmf1bST7Th&FG8^zCyeuONW4? z8|AriByX4QP!JHjnol)2o^=4~&m)0$#4?aLG6|$f-poHZbM`oN;=_27Vj<27A?6)4 zarUd`n}RhE%(H2{J!IjSH=AI>F1L%Ys=f+D5OqvHIIsc*fL^l+MtS&WAV_L>wq|V} z$!Ld!>pmShAuCHqRm4G1HGY(?^!@Qrn+>|$YIs8T8DO4f0qE5@y+(2m_1YI)&~y#R zYHr$RX7Bx&hlbV$Ma^Y-PxzV#%vcl?l)}l7c?uA6yVME)a39RYpWUtyK#;m_Pzx47 z>e;$eE&zWN-hVLPI??O?P?S_hKlAE-2<)R132nL%2(NNlGyjLy`iWgP-XaeU%y6Z~ zG~c>JO{5dkzo&^O6*wR+wCSnw#(lo1k}p7IV^l65d0fq;Mmx0P=ygH zM-V(DIGNQE_$~|r?8ZBQsG>m)We@YzRcfC=>msNKcpqi!Uf7D?1<{Kv;5srIubVJH zdXYU9x2n&p5&V!dytt*kyVo;u`~TM$*CLLzKXC~cB7%Tb6O6#$Sb0^fLU{y1p)5-E zZtDe{9PS-jk)y3m@8{<0!w_(o7PGD;g7gjo+0p@E^|hSJ?lVYK(3%$;O?^lfUFE@%r#M7mc15nIngrd#!Mp=(h%za)s9Ep zTJawM;>V{(f>N^mV*siPAG{K@8lHM>H>5oa5oBA9&q~6_A13T+ry=-4$1#lpm~rPQ zr|>D1myY(i&GJw=mgE`Wo5gi0ir_sf**n<$n~@UTF&=KC3Iu2F2DQ>CCsGQjheYZH z5ynMZOxPwyTiIKUs^i5}39AU|1UbT5q_ju&BKeX6NP!^(Yp)6*T-$UpXMEJf6NjCf zW9()1+92wqng44x1RI*aLFu>8`baFwMIq)zCFWySoTL!AlQobECYV0YVO~QQTDszRFk3KWzwR}; z;NX?%VEo_COB`v?=euAN=7RF4U;R2r>iQOZiLyTi|MeU=7&(zNyEsawSR#rL2i~H5 zN%d)A@^2Twy9qxrI%&ZNQ{D!;_cZQ<4*aOW?cgY=kjFLOQ*6F_{=(dyqYqrko)P%K zGthdy@I~PS%AD9350uPmy7K!7Kbj00M1D*SGEvv+W67Mzq^=Q0*!OQEbsyc^Zmoot z5pI(SjLl$p9j_S+xqS~Ua76NUM<^E}ghWe~ zR}Mnn4;rcKAS>~Y2BTt38DUsk-m zm+=`HX$+lLeGYIt2;81uzW8e>r3I_vqQ&j@IQpnwg8c2zMS+9aV}v^^8cx)oQjG5DOvwv4g_D5+}Cbws4SS|Z*}4fWfgG>&YgHjV2><$co1RQ z8njWg61U*q$-K1HwHMIv(4UD_-Jg~>T4@~MDs#sgN5sxiHVU|JdTH^hMTy=4S>4NT z&hDa$4Il6lD}qA!NB(V0mBlPC`>%m9I0kk!pyV0?w^G9I98P-m=+&y*bq2r3ndS5* z0kMu#4YHMI)t6=PY-5eWHJ@k1+VllJ%F^k$gYQIIgL>Vu=-)2-dY+QOb({S1YOiOe zVuJ;AV&uj_yPqb-IxBGFtf|Zi!zFbqH`}~al-bwzah#py@$(Cg{BVf{;n#$uClGE) zxwW3R+aLb=Vc;>d`~|2G4b4Y``gMY3^x9H{r4|{xnW1np3OM_ zbCi>n;SCHCvS4JtKS0AEeh-Awa~4xK(=WddhN=1KSmwx;Uv@;fjzW==3!EtZeCC_{ z%PmMdUG+;8OjVH28TTwEJc;bnncyLMP@mH=Gnq6MEAI zj@LoniHH9*-114o{%lTbe9#(;G9<&)M;F8V(=mq8a(4b@J;&yI{?iy&DU3lj z9EP-yX=%4_3huJl;8OcG+wq4b&HJSzXkNc>ed#;@F=a1N8#dL-kAUwSL+lrhXdRN) zottYs8}cvzpn6ag90RGVP{22346WH0+>Lgipc)j`lm!5M2GCS)HaFXp{4((q_^;t$ zL7fXzm!XviOd)?hI+C)Zbp}rg1N_@=YS>M0sRfjk;E41AGnO^PyBajGx}mPE2-017 z?vnSl46U|Mw%2{@`WZo_lz>3`dW*D&^ zGuGCF9{yCW)pg?vt?7aFr2-~0K1NiKCNBfZ>4z~m8d0=G)JK$e!(Y21NOYY`N@qq6 zamorHm3h#7+N*YInm@hh?@U->HTwDigL}La6f`_N#oxdCcmxtuDPg2NhIIU#+mIg2 z*vu%Vhcq|3fypBZ(kK2$k!0;*DwEXG0qAKfwqiZdXv9jUD%6ctpT|2wN!G(Op7k|< zzvk#1W>+rBzKlrasE9197P?JAqjGJCDpnN&sYCR!TcZ%oqDD@PU@uBO=Tq%A ziF{n9+*=tFEhFY2%|KkOmcyWjvxSf}vA7LJIfZhKc5msD+IqowQ?Y&>b}pi$S!o#BmNzHO&4INEbxu{TFN0!Nva_JJABu>)NMnH( zF6|nDYdeH}Ya_pvS0tVAfpJOdsHd4P0!7G|FyT0?73R4F*m92h20eM&JT2ni%sxi1`G z=8uqZjtTS2-f4jOeey3Cv<8jIN&Jxk#E%uE!r75~9={9|?}_ACq<9xZN7`^M{dsrNtlVag=+A<~rW{gaPN~8xpcnQJ?@| zl+lO;3A09Eyr}QHTo$jZkvhYlkCdzPW{t)wqKE^i2nSMyeCK;YbkFV6+=rK^IT6e* zF{eFo%X#jh6oe^%5O!yBIM7I=bw+uwLh}`zr2A$38}z#&X*;vJldAk4VEv8l_W=X* z;DZYAhq?Lsz^2Y5giyJ9Dz_iwkG!EM+hQNly!`zus&`LIoxI+PVyKcJZew}#{;qp) z?CK=DDD}3?o$Ulc!ZN~E0y%qS*xrNNa7sODIQi`LDp#@N6Xfkqx2rl|&UWR@MmtQC zUc>er4TRfcyt*Q5k$%AAO}ZYb8zlH%w-fvbL8kn1Dwn+t{0B{RjoIb`s!xIMzCn=9 z*+Bo1%k(Kh?#@j7@*`=97?&nI%X)9usxd+T{~SV)+r97CF^ncu)INJlLD z0_(sqV65`7jqo*pa<|^1R9kl4JRK1L>>?xjX-uJ^yJH57k-a#61ub&x!)nCIyRYml zA8|o`bq#-H(Jlqqo`IP%A@xvH^$V%!a}*{MuIARQF{{JC*;W*t;b(oq*C?hry^O4o zZ^4rIkA0Nu76lfQdC$=nadNlm!mVoB*&R26Bku6WS2thw=#FUsPUxbm)Qu!^oE+U3 z)}~P-PmMV@X-2`T zng_6+`n4Y67=ZBr52Ud3Mk}_SI4;C=W*diYxx+)q%eo`8m1Xo0RX%Z&*(wtKcwek` zyp)~4mBcKsI5}I_h^t~*lCSoZQmUdB(b+e4%OZhJD6ZlBK%2_T^s&7|;K`mfbPR%R zF{cd?snn&UB_s)_b&(C>tu=JLr3dq@s4x|;n`xzB$~~?*Q8ylfYuB+q4-n6`+oIzH zriaK~`ht_nq}88xZRV>z2QcO8C;A4|-NcQ=Sa=dJtQ7f^3ZA7Ol1JHziDL%S>=D^( z7sjs%7lnz7ioe@inJvp_J0-1P`@B1{SuuD^MBm)M7(8UJUh2Iv38@gySq3LYq5e-m z(o|EP z%VO12{TEyK@|k!VvG15yS1i>Z138cAQsXy@n+H|&zEqPfN#Q#!w%Hg@FQiKr9#Y$W z{*!A>bcAV$?UQ#tEV+pK$OS2ie>43~YWFDlY~AJbnt+jWdwULk57-=Apc{j8(ArjW z{Ks%?H{j9~rF%o2n?$mGujQ>QT^TJ;YT|*L7sG3Gx+gCy&cGI0*pA@0yB64&kNQ+x zIaKmRS*JfJOHlj3rGl=s)G6Bz z`8<8{SH8VWLpa}y(?6aTobm-&2iOdC7k>EhnZE-44yBrI^lwh$<66j8LeypLzA1l? zhLjz|uH{Re{CX;5JUCl9Ka;tc?T}<&HF;5DijsCIfm#@%fG=Di0B{X{6`XGhwZzGc u7s3KyHChe!FZlBVC()LHmKy5uvvSnP;HMXHgKRGNW4gt{=&pg|$^QXc%*T!Z delta 47037 zcmeGEcRbbq|38j*WF31GBH1H*?W^K75LPg% z%YwXu2p?DvmAJ5kFsq;-t02FPH>=Ps@KI2JUl?hQ;Vudji&MQ0V?_kolf#4&jU|rJ z4snP{SxO{}X~GfadbkKjY}0za}Vv!7mZl63vl|n*OkhbvMY!5H9yA zkjvVtu(+#)F#dDm8TD}x&bsX92XLY!M-z=S*VDL|gM=G!{WH6k2E7jjVp*FKv4-b= zPK1Tw==q*&tVD=4YdYi$BPY!By^y+Q1sC*R{6vM|H^(~P0=hv8h=3!H%pd==upB=b z@|Pv+KO36gSNSjER%~z)I6nvx>(;bj_J2-~T(Mb!#nsTlED^<`6o|)@l!y`0Xh0Gb z0{(FGoB|9Hp}18^7z+Zjr@#=GK)`e!l{o~QZ=!-or(r3=BkpJ|W`NgBBrD z!W~T{h2-91x)>bhl?#3&N9bS?Ab!24M94*ABNzfX&nL?H^!}Yl2@^vIl<-9pNg@;d zCD7mgpQlU(&RzyT5+I;3D#Z5y9E4a2Cwh|Ji#gc;&q+!z&k00N0u-YOltd1M>7sYB zKn90uf6#I+<+#6*GwB0V(_nGwqa z17pY$^2!=Wp12|yLI#Tw!T6aH5v5y-2uLJF_9R51iA6Jp0&yINdqJ!eayiBNV($;> zC;v_Lt#ht?&W!)d6$%Uy!M|*Q&aT0b$GKfFM4^)flC9v?znc>ktz9ew)C^%BMvlG! zw~t@{$9Eq~2L7EiRkry*2B?0@!T9GCw-E1i3y~+EjsCKm5|Lhm{r7sOYLqWd5L%xO zLzvTCTo&W!i&-K~iWjqrTmJGJp}O=4>D=0f9&CY3Z~ued+X6Y&Sph?&J6j;q+sTl) z-=3d8AeVZ+|I5s??|gt1r*r)ete}kUa|9HUBjN}Y;-Yw95r~aJGNe`iIrsnl7P&Df zih;18xVW4b!}PGf4`sj1E{+{Is*Q*x=s^&^qC{ql+5Be!(q=s2f;h9u`HK(l{}5iV zWn$+1iZW|wF#-7mh*@7MU~m7CTh%4NPHL-}zmvj%MfpdQ(Nk^#N}VbwU`FQ$s;r=d z*NK*`OhPHrSWyx@PE!x z2}b0eOH>>!4#!|wCZyB8-X6ND{Yu*_5#w(u_7fs1b(pd>;oa_jt^LP*o{~3V>>mC>S`&p#vBN;6$ zd_UJ8;+Ok!^cgkR_^pP#=YmADw?;wD0I@{m;@a7=9vGtrPIlu zz4am9Uc+oYoOqQ|8>;m=RC4v?Lw`@@pm}5A$1e_doojcS7<^ZLIE1cka;3{N!fAA< zg7?BpXwn0q!z(&e)i|`9D-ITwgR*tSz4;@N#loX{LU7YyYXmh+~&So(N++M;m>0!Z%i^K)^tDcaM4cQc!lBN zS7f38Z^NU5I@#O@a&>ikF3>LZLU5qq$zw(l2ZOuNlNQQHVZS&7L~grTPs80iWd`im zol`vOK5UiM%|xqXxM`1jPWVsZ$Q|4)q_1ep55yoO;ZNszxd!f0{@;82pV#QFCf?+& zr>d%A+%@;8;$31&)d#JrP{~>8{(EEg^P_mhC4*k zzz#rEcwVmm-*=Et2&f+_3oApcEJ5rZa}1J;e=qg{geAApaM|k9pdo&oxsUx_yOgJi zCoVFwSQHO2V3#|eQ8%7*3HqOG^5L8NF*HAYnrM-Zz=$^Kx&3PNtun)vx}&w~x%zen zD}6loUorzL>-C@NRK+b6N?GH~%6=w!_};;jKA3zi5F@=>-rw}j^s(_Q(*H9Co_j$c z%(jtx!ru89tBTF*OF+x5(U#(0+j)DNEiwL(hk3fmnFHg*&>!p={~K$klB=oHehHyl zFPS4a+&5A86y%NFrCty%cB$SEh8+q&_#E&s<^*Ek1p}ej;9V#eJAGz`9V3G67<~0i;?0*{Pfp4ZBLww>-IM> z;y8-{?_sa$aMS5I$IQ%{!=*y&7M8-N&Y!13oZKIzhGF3CyZ{HkIjiM6&DU-#Z*1M* zQFT@z6Y0QcVZ9eIVfN`1h&w6NaJw0yM2|dj)C|(19Z#uM@FSI%A4rNS)Bk3&P2}8@ zxi;XNM>!5X@@~u8w!KNkwZAuP9qG~l!x?a;eq2ZwgwU3iAh;?iOu#5BT~yM9XTq5t zh;av>M#oT7^psq3HN5^>9LzQxHadG+xF=oU?-xEI72q~_XmoU-bZH2B^l3^d`Sp>b zc@Rb4(c zR>LJ$R%IP*g|i>W43#Fk`05E1LkQsU7Ji#8KgQ6k-%$dFN6aB%-u)LHbd&dTC++2m zt`nnGZ-b))TBPUk98|Ddytf&SvG#Qe3NKsxdP0?d&5^xWI9nlGf)imRV)Z~u!kf1R zt0q+8VeJ0IAETqQ3Y{gt{okGw{H`#V7a?b=IfrZPCi00-_YmmL(7TInxFC;8q&Qnx89QJ z2&oY3NSO+%YF9d@;ASEz9y7107gI&Z9=s&SvR7<)9O?2_Xq^jA*=x0kdh{%J*+`@O z-Z5GjAVv#~5xaS;3pP;o5-DmDG^$?BF0}b)D&(lqljn9*&L!25jKQHDaHD!b{&|(wO z(`ZS|#_%^22$fG7d$r?ne1C(19fMV@RtWiT@Opg_fq+`7jJ8B>mwc*}=kBSBo68m! zw_o=~n%l)Sz11q7EQl)}y(1sgiIFl~UobH7dF{*c{n?54uX$;SG^&yKf^LUu@X zC#&XD@s%0<-Mv;y+wQY29WECazrn!c(9uVqKY5jmgwkeVw|{q8>7 z1QyMsd3dtdpH~7lqu%o=(`pmQ9?3`ZOgkHICj7R)HQ@c8PlEyoJc%V2(ivp?L(x(` z2poywyhvjv;ma`K{VW7vX&=s)x>#=)W4-e*-mgL}tHWqW!LadrYUf}b7zQ%i8_Dys&_(R1nE)9`EgBG#z8PkIm zWN*{PRC9CM+3|eCGX<&Da(x;>8`5HR=!i06gj;CHcn4U!DR+ z3>XH+7Vy>X^tr5l8UiGTi;asHRgU|7`mIXtxC((AA~v${e_Hfz%u@=nHzS#o3Nr3JKL`u%%Xff&1_mZ_bj%u2zJK31`fL1!mcV0j|&@Zc_B zZu1+Vp1Wy4=?d5DjvjxWeP`PAO>Bbxam{9H$xfeoD52OGzay|5JrJLb>$oRN>0V~lA90HZ%&&KCCp$T@WRi`d%H^BugKpDVD6K8bF zbpIcjw^Q2yEX`F#xznyDK^_+5!JpTmL6>ntV3)Cjv8c`Xy9L_l{XHzFTf_0S$V6&zWQTVV4|r1 zctE(f;mXwa+<(x#NGhltmU z_P|Ws0bIQE1Z5d_a|}j_N0FBeZt#Z4?{{%iZ7?ca16H8FlySsyx5Pe#D6|F4(}{fA~lrl8CSNrz|ij8DFjzNlD4T-b((l&}dL(^)m|WW4g!zUE)qt z`GJ+U#is+Toej!|f?zwg>T4-};&qKrw+8pe&WZG6++hHM;sZZ8$~G@cslB&e*i(0! zT8r_C3gkJT@(9q81Lwg9gX#y=E0C4T{(~b!6G)@W_k zjW?8d3>Y6pp2vyu5;-N0Akll2r$$J=2xHRx& zCG{Ttk)n)Sr(Ea$hw&;D4;ID285RLYEnT8kLyvy{Ju+fQ1zfsLIx*I9)KKW~npzMM zc}d!DE9#m^t)cx7vd=uk@XD(ISCT9y4P|PD*^L4k0}W*uBQHE*kQxSon9UcgdE<{P zv%Qo$=`X>i*L`HgxF?U^?LP;{&;xGcUE?#yKs#STbT z-jf2U}Rv z1J4H#*a8~IJC{ja%lEI?66Ko$`;rv@87ryUaH_+8&#Ctg3@cF;oFn05NZWg0h=g?- zh`cXv{{D0>m*DwD;7LZ#X99*`kl~~QX5pB-YlC#0f`ipEbnHms?|S#Zdbty@)Os*Q z4XmfTwPpl?AAwd$&1ibul%~HRl48LPcBJU9wMGO^7{p;IzZiaQ1WB+AP3*Iy49jQM zi`M+Vk}BtA{xys4ZvY7qRRgJjxxxv61jIcOVrBH&F_)%TQe1z9aet&aqtOvva`F^tP{0?w zfC-7H$HF{c0-pW^3=T(n_Qo~-1asYM0PSrP7#MM|VHi0+*isw}Zyl+&JGby~Nprxr zX=fNLZt5qD0*~ThG8jL-@*9aZ_>}Oge86;URt8==Ukz7S3yglUw-!g*2)sj31T_dN z4ou}QU93gR4hD<+?ia-gG{Pt#`8JRzc^u!k7Kjl}ey}&{+zf(D1~w42^LMZygxBQ9 zfLi_yPy6A1C%Z#a=qv{~YVUa9?5kz!&Q8{$Dc^}BbH5_A8`DYO1!p&1PxStZS6<%m zianKvNcLcIqZc|A^0)?VzP9*U&j=lF*2)%he}q0?uh}2>wE`w!eOGkp(+l zTC7mBam4C8rMGH5=lA{*dHJ9m5{^D?DRhi)6?&EG^mM;IRAk5uxq>3G(UM%uvg%-s zBOsREkk?PH#K}NQiB1aO)Kha=6BrgAUb0IQd@4$j2wpkns(#R+9YEFtfq=NAPmTM< z)1iBnL#E~q`Pog+iDhZfslK^$=D0S!gsaVYILDcrOa|Cf@3Y>s`XBGC$)uB&wigK< zGw)sT{AHh8@?8NxR)$e&_Iv%|W+db&SIGJC%Q+N{M38yKd|lp#(j0^$mh!uTVDiC<-hmN~i>73~!WDgfy4i|GnC(cgyr@%GAmy3{EpZ9(} zYNNy088otJS?X5jtzu!=^;!Nv4Mk2>j6TL^PjT0a2QgAJIeThf5BnRKQp_FI_Y2qZ7m5t2)JC8)WiP<*}`{$!6|_ERA0kLZOmzr>X6ogS@6 zraWSBTmDcPf{yV^JB39YQBoPahM!CQE7Y+X(UEKA_77#o7f+^JTRJrvDgp8s3Zg=G zhGqb(k*=~QK74;bvnS@Wv*1NP{J8SB#}m(4dT~#U5MoA#tGE_bMEcq?PsfHpaz-bo zQzG+m_1B}~-_NU|*3iGgEd~D`*SXifAoiWFdryC%`bV)O$myDK82w0&w0Csh-SZgP zn3p?~*sDHx7WY#Xp-TP}`Wo+zDgJ(+er zxs!8q>7&K%r(E-D772AUC(R(*E=hUJ)O#C-C8+{b{5fw$Zh^c7oWyH)d5CW^gLtculC4hewvFv1=ek$h z4yP-2a`;0QkiWEO1+xA6Yv?PHfE+t+Rw>^zMcN|>D7`hikO%{GFcs=~a^egfnXb6> zi}R)`PG7#%$lUghb~ML2<)gBP1&HsT3tuugb*X%IKZnGob~@nW_w7XYm;4j{XNp#-TVNvix|?L>OxnPA1%U*0Dd7x5YD5pL9QrlWQ+>`(#k4M?BN99xv_mL@jB0q!hlcs;58`y04vcfFntMReA~a2J%%KP55nUY8bqA zC$$UjUpK7>>{s7CQE7Wk#Mw9tQc9BNb)SBka2xWLt*(U-kzOZrk=^bVvMR{W!CMLC z-$wSzzP`x)FH_r2W>inU>W30tOF^L2 zdX3QI=S1Rdu^4L4R3$qM!WeuOGD`nY=rcU$Y}3}M?iTF&x}=R^QNSSpO#ma)1k9Mx zPZ%Q?`Dg5v=Q^=HvTYi>7-y_^XBBZ{lau>F);B)m`7t#2AHV;Js(r5?4b{UBIf-R< zbXFMq_L-z@SX7n@Nr`eKIP~R>3*_1tV)bCQhtY9$>=q_Mg26x7OdU&a({GjmcjFnp zw#b_W_jJXjo~t%d!OKXtVXNTczA$F9@yV8nBezjReR`mF8yToy1srnl&vb zz6%GJHi#v~v#yF=n(eD*IM=uB9w|QTucCjWGM*s7$BMKqfQz)`+s4zfjpB}}VZ~$v zZIA-Oftj|mypXxUDsCYwah$~p*yE0t*gs5{M?^af3TjdggW{yIX7KdUCoa_purRmkqzb-c6Cj_LD2My;w z!6i#Eue+jMsGMW91}76Xs$avMfKqR3}XhKi^75g@mZlmfhTbpvb z8ji>v*R3%F5&1#p6#Ig!a0+i}80$p0+p&SZpxr{Ok@=NS51~+f37npFxiggZaYfqF zU4}MMXdR%JpZz0V;oaHmuojn_b1p-}dgwsj4jzNYfjps@i_J=WJNZ`D67P5CIor_! zqsL086L7rQ_C)TDp4ARfrsV?TQ)->97vdIg`jy`+l$t>ws!y+;)ViKnAHL2$Ec8pz zk}EK%4|9p-t6oG1VubKzj$ogZR6%ozg~-Q(y@oKXUkZTjH+VDIGvwXi{LU;>)QS;{ zD?i?5UA~=u8>h@bUe!y)vLR4>p5%3l&WHBzvGu3B#R3P*yy;n6QI}#O*ha0U;s*4F z+vyS8y>bwJXY-TN5(35h3!nRpv!>M=_GS>;t*a#O^qf>4s_3W;vRu8@WC&3mTX7Iw zRSdD|f6F$eF_DOrnLC@3;7p&P^V?HCXpeeC^|3KX9zha!f;=&h`Hl#TcC%q(!cd=! zV6m}b==76UeW)_|@`hq`JUKaElXeIfX}PPvICjVjePj7u?xE7;%Zdk8N(7p1hyvA~ z*lW@CNI5R~E23Jtvi`UaKT1J^nY#Zt10Q^wBm3@*Z*grSfzhY<{v-voD24bsyl@Ey zIPbP%&1>u!jTFVS$kVh0Yh>Ql+kJCUk;!#5S?Y54pXz@j+ zmijO=S(^-mtlrbT*{&c&V4Y*Fn%SIaSQ;=HgoB~ju=vL9aWc*zhC3G=rKi5ll07vU z93C8xddI~9$GqZtE0ekVI2j#aT8Ad^$E;?(6ZtcNdl!|HLJZIM5t4aFj4hp-F+CgS zGyuB}xu?ok5G%+nDa#%H@H(MTYUNL3_UC=p00KbSfXz;`VLz)*3VFXx^?D$-Q9qyAz-A*45Nf*~` zj~*HLzgwPoIwZ$CWRVRSeY9xtL-@VbI*Vjkyrq zHoGo*`XdM$<8D7$6H;)i#G-jBos^MlihkY4N+^4aWn>c zO8INpq$XGzue!+y?j%JBZ_DK<*}ctBoUN8bYo9AW-5LQTX1AwH}7G(DmQAY)#+&cl2ma!-$Zl!-rm9eL;1gXDtD0D ziEz$@6$|{Nd<9_L*EU$WGu02uk}gGg^TPLVucEf3fYa@Wo93xeVT^h!6AO%M_1a|x>W-NL-AuMwvnwX0lEN~N3;knu2FP;>sVU4^zSmodv=toURj=jg!sA0M^`>Yv>= zwHA~InPQXP$XXewot>U^VaL3AS9)%d2DE{B2&j0B&hYbIU&0^Zr+8&G=C}Pfm;zrf zR9#}Wp*cMP{<;;*7MqxXUb%aQj>he!&>doC!}v$%^)L<{Ip8S|N50se=cBk3d7#{| zc;h`f9i_r11Q@s@OaAI zS|M@ut>F6*fD?(niR=9h6M_qC0Aj6n*6zkN0z@>fVHie-Wd*`3!nm8`Fp9XqVHj3i z$!h+cb1S z@ih%pA$HKI3RK`Q`eDbCAPuC6-|L|>-exqm0Lm|PR+9}u0Qxsy_(Ju;-F(%f2s>ug zK!t4sn0GM}OLR%ZYO90Y8Rh%24^9%o=)d#B z3Ir`5cfQM>Rl#i25Y>wR`_2>(J%duQp_nA63gcn-e$8ejIwuN%)tt2ybfHtwQdigC zPlpJrS1U}7ux4}90%(b3cD`?*VH6F47K%-8157PY${}~j!RtgPCytHV3z~Acu*<4f%G9Oni|bD%Q&gH>_u9$w`{fbU&U*`I#0@@4ts)TbeHe30z8i390t-fUxJC-k4@Q z6GyiPK&8>KC2Ih%iBR0^a(ezK!TGn$9=iO5&NXVZ)qF52rx&D{_AP%^e6yju}%!Bd)9FZy)p7^+#BR?|Q8mu-M;h#hUS7`#+g} zLjKEvZv#kPC_0o2^5$m%m%9NfX~CeOMbJl|s}97(8XM~2N0aT$kpvR~M^4h$Is;KT zL9LYpHSu~!yT#Decji8ezZktzD%$z%1M+iP#SCLSJ%ZM2m8snYT}RUsDBFPPa52NDIgg4;mF_;Snl12&AU3=R$o>lS0v$}2 znQV!)$#xV(&b4z#*iin9pJ{U{+=-VxfSt z)C574-ce%Sl<&y=CNq(rPRHDPHdf%8Msq6sN1pVIcs}n;X|O-2C2A6|O7Ml`33<+? z`mSBMjFdawjGO}C@yjXGy0?5hrC-TPUEM~VDhUBbX6Gk;ll`VC-aIa4{zH~zmUQ36 z?6^Or9-eD9#+X^s5gA*-dDP}!R?wuIoRux@AI)@0oA#&!WBN)^F#q`Ir5M|6#am*p z>QTm^KQ-GubfIhHqV=FOX?1q8PmB)PJ_9)E4C}N*#9}nQFsQG3yw{L?Vm>Rc5M;*y8Yh$QMCqem|Bsz5<+nv_z z?!0|D{UI|PU846bPXHjGe@#q{vi8=^-+0HX&d_VVKya|!mFWOr-&!qLYUK5q<7eXT zJB)qJIuKsNH>b!Kh{Ue%ru~6Si(X|-bXMJ36}uS)>Hfw3|#^d=Hx zeE91h;tHWyPoUa$e?HmZ>8?6Xdbe(Ysgh=**K*UNZ`GzA2FS6e`MDmm4y~;M4Il(n zD-~(Y@sh++irU}BLGyp}{BzuS5Z~bNIG&he2=t24IHmvySKv~X?p06FUC|mC-Mj7g zcpk}0=~*80iDX7MKhEj*x0|Xj<`N%$ge1)6Rr&XTnQVJ6LYvl%yT4YwUPtqXRHyIY zSd*l^Cc$sbAE2AnvXGk@qu<8O&%i{pUt%7!p&RKf>&EI(5HYad@^*esDEg8zxf~6N z8Df*g=sAu2uCf4NXz6EODI@mLuLvG4DIC@euGoxFdRG-5Dm6D9viNtS*pTRml8f0| zY4@her6d_D&|8yyKXxkt4O;R5!}A1bpiD+XCXBd4GK_A<*tGLwn;V03bV#-f42#~d zr89UG&F5~{o}6?;sF!6maM*<$g>+dZ;JD|f>*h0<3#u8L1te`XNRc~?;F zTPczTT0Z_F{NU40_@y*P&ReQh*1x#ZlsO-C;KUd-2=Jgl8%4_tDPLHQC|zsKt3M`zoE0Rww(^8+py2nMD$}I~WMt`m zG;5k9sx8(InaYt7#yxpW7WccRYnFtH$}408_~#(w0cL~LL* z(=ghHPJf>{w$oP-m@De8aF|cGiBM81B4yYbNmY~O+Af3HdaOYThF>2rv>qoTf?X9u ziNcw&;L{J^7}$tQZmXCFpk@V%YqO%Mk zhp|)bnCRB1#?+(ylT9RavTPxcr@4x5)vP~g;kz%wwe3r$^We2JNBVU?mdniC+#(8; zQd{(Ep~qZfHjpDh6?+?}-AicHKqva=R%k0>9Gev@C3b@A{b=Vo^7cwU`3}M=;A-7v z-Xw+7amA8tUp6Pn=ZP;H6ehktiO`a?_v4)q-*{#zTkklnu>F3nMgEm5Xal)_zZcSf zc5f|?h!3NpD-GQRV(3OT_jJgMNQ|wKfhdM!e*RiFB$rlZhH)z*vegeK_?1vMzv9Tf z%?}DbL=yxX^i4&_eAh(-VH45(^|u|y+K;bKdgtr*X;is*eBQoIeUG9mwi=%Ub!CWE z1ay27;b@(Kcih8*Loc=)YN`)I<2ctkE<6GGDJH4 ztnBOc)^c96NNroD;xm6Vrf-%6@OArV&2zLlk6trP1lZCYoq>4b%jx3L#96@5nGv~; zYw;85<0)#seN&LFRnJYeuOW_J4UXxlAI(6ibA<608@~zn*E>FK3jCLfb9}GD7{rd5 z!R_W#d10H#z@v$yB#)YWPTZQ&foW#nNO79>hYq82Wu9Z85YCaWHG?F7WRR87G9wTi zJBy(<*D>SvxI!A-tqRmxHxPZ@F+L%ajJU^ACNGseoxZ44Qh08yqbaS1^b#khR<*$9p zc8{aJS$FvMYl?wfEJVM3pavistJ(LC*BWF$!|gHCG!9j#6-dnmhhVndF_k%+`^U-9 zWmy^7qi5Hor&{f_0{xh;SrNThY2sTH!1UEHPy7%+Z5Qm&Ed!jFltzinGjYSvPWDku z5x=B{y)CzEWu)daxv4%&UT#6a5WF$qd{@wC{ZVJ`iDlCWG!RcATK`b9N`k6%W=!9j zmD@ZSSPDO6l;QRtZ&Yv^iuC{sR8cB5EStq-{iG1j9x%wGyed|b`&{QNCaLdM=$>@o zNAbVeo}$*|R9<5=KR8zSCfa0F_d_Mz|3Rd{5xxL42{3ksUJZr=H|I}7NBg9rh6FphZHDy|ug)|RBsrgCy>L2PemvoyS?R3eU zB#Y^-Stx8Bf13T$=QTY=Ef${7=|%WXk|7|Kjjo5mPIjR6<+Ms$N5xNb-&Oe9y)$(0 z*uM$K!YlbtFxE6Wcw)TR+xNV4^fPV{^_5ErI4v5%-ZNwdM*=31-h`YC+#+Np!2B_F z5pd_mhx+TkX`c6<%is~QV4d%scajyl>bKGOy z5nN&Jt8DvgJ$d7vC~xWfu-U}Y@HMVgQ*%AzQD8qf z^ETp(EBV&@9_$#*=-{Y)+sja=-+~U&o5|PInhpd)xnrU?T6NdF&34MeL?SzI__9;m z2;&Jwt5o&L%pc3u1ma%O&o=g%^7OpyLcSG_XDIxPDuPd>PQ>!@GrjPFrgBLdId+Z* z2QJR@>0jTb7a6$3@1^OTQHal8Ry(a7+uod_CSrP+zx1P=xIh_&%{7V(-RYO6IhLAO zv*EVMSIPFN81O@&In$DO^)Qu9{G*Y42cJ~Hs|O$Su-Nv!6E7p&Sb1{GrSHh?&z;&* zdevQ9So`I=>J`pr6p(=QF>ycz3Nl7*zm5~DJWi6|liW(2-M#sVW#7aTUw%_s!83yC zp5mOn)gW@fi@c-ml#l~@bmB3+_un$Y1C#aTKVyDDGNMFE#H@DZMaR5$lenyMSv>w= zn4h6mS|yFHQjmV4b#yPM0d`KBKF#g;+n3^;gWtTl{w>n-n`{K0;#_&wv*_L;KWz0; zwy)ROEp51%#o@z!*8QSeX|wI>d23xpZaHnpZ!5`AG6ex?h3>A3e8Qal%;p=DtV#A8 zxCV=3aAxD=5GC{5jrdonVC=FKjZv)pf{3tN&jwenOPIZO9pw-qtE_IziT&K~jkJ)> zb<+Y$COazVnA*E0EV~}ftrMv9SgArW*2$qrLcua+ZgZuFf7ZwT_T~eh+f)Fv|NdsN z7l#TWh}EFf0vz8CGVzdYaFkEL(SWhqOW%1qGClc6zvK3olwxTX%&8W&>H9g9vHg4A zys*0!q%|aSq#NigO#rJ`G(bXUJegR1n8+Rq&{AR0mh2T{tl>b0m&B&MEkL;EI=K?m zEa2K5*uMR3&Sj$<_gycKiyl!r2DpzbiW0C(R%0@63cjE@5PEMP^ zz`KmksO2`B#^Yx*)cDOa$PAIA`BByYV^=7vRiroM?eU-a(JP(v$ihIk71WY`g)V2h zO`c$o{a)Qv-Gfg>z;~_H>M3UTdvDwzr_9T@g#@;orPD0RQIpX__IM?}Zf9jqP)Ol? zVUD`LaU-64jc%V0a8{bA+QyC36`39ndq3n?I+_VG+gyRk-J2v`%luG1sag(7cME2F zDgs(1)+(Q!ef;mhbeCdso9_k93}tq~Si8xAqZn!i(bnr1n^RgicNbpOH?Jh?ym=+A z=6$sYS^IsCtqe$#&z9%+Dx%lHKHevhmhZ(QzaHk9tf-ed0v6&x46a;J=kJ=|($nwS z{rW!9$$fuV_yZ%apHi{Mk9%QnKVxU-z*yWYDFm$^(JGDWD@ME~4d*Ogex+(5ouebK z>T-*c?oMRZ=Pn+k#t>#6y)>t<+U7Qlbx^~8L5SR6kEtCJ!x~Y_ySbsjO{ufBiZQ(o zPtFVI#&ON+%=+0NG(kUs>q4I|z_QbX&-W(C`t-IoN7Lr!_30;^RdZFCavIp`;_uk} zW+&j?Diu|n@#;cSHit3#TCZknS0V)$2M*?fnZA@81f&Egd5cX@Z8UWo!u3$9w)ElK zeILSw1R4SuPZ!Na!Ah5;i2SLO2qqXj)M zloU)pDpqtNoXE8Ld?ayLhk}l-iEyb^X>Uz=dDMj#8SPQy-K1&sa2UfUc-@P$yJ%YK zfYGTo#DP_~_~bw*yK9-_lOGnBn>qin^r!K$dJS_Z`Gd-A!1O0zu^$DCMX#W8)jGy8 zV-~|dR7-FqOdwGD`qS!!7U?~DxNK%{yQB-g9VSOH4_lTkYMFv1) zly8vZXQdF!Li6-NLVTi=2yO~4v@a!o7H8nC9D7f62VET|a4$S(u0Bk9 z=eyz)-q!;(ry3|9$iW_C(oa6YqDAJ+t$?{|{vn8{w=>KV<>Mp>`fq)4AFwaaejyS5$(=sK z&{1ay*YUn#Yg#8MdgECPF~@d4m%+B=X6e6S9(4Y(mO5Pz!KE1@H$QZ`aAGL6obciC zU5<2{cBhImzVJ-#N_l5cOlIQ3yh4>^BAcG|M)bp0xAoRdS|%*3+jX;rc*b{LS-!1; z>!~ZcR#(Sf(Ml#hDhp!m{btmsJKK8fKf=_8@+Yxzc6I$zVCSeD7&B-e41h=DEx5$4}F{rKO6MJ^_VK)b(zY)$by{$14Ka zg7|sVZYtd%#Z*(iW0!@Wdnms1niREz4?Shhh_A$n6oMOh-PEDB78>!W2#d8Ejy3#j zm$r+?kuWA^D$@Cg^;>a5Pb`)zl&7S1;~PAQm?J;Lc8%yit$i2eRdlBNK|Ui;@P^)7 zA_O|MdG0Wob-YbO;+X^p{_!K}n)dNMD{Ij4`0`vY$TEK# zDl(E!`0!Gb@(1cGj>Z0j3smdXR4@}?U zsd4S@fp-W#e#>sL|6&c`h0ta)b)Fx)Bns)aarY`#^l`1O943bh3yyFG@xFc;V=9q6 zSOkDG$lVEHH4UND#c7uZ7&&_3Q6U+1$8k$C&wdTy_OAgbJi6Dq+J2LSA!_by1>7>8 zDZz>64Z72Jza$iYz;~9e=#Vv(33_J-ia~xTlDfX@62E^7`IG9PUwC}-wAjyj!hTjL z;OFR3-0h^Y*Kh$&K78>z=m4cUkg7NPa38>G%fBEE4_M*aTzZi$maTSOe4cyiso8nV z8l*)z`Fi7?#|W#|G-CB=Gqtz;_H3PsBX;p|xe5i|#%&RO=^y*kT@%L-V;+bn?i-chfcKY85pJ)LvgIg=(81Ik3@l0WYzw8~A$RL!NAuz}wpGb=1fiW6 z6p!&#n38fh(-46WyEqFA3(q%Esw-AK(vr9HOI^jATZ}W}v2M~dC0^C)sX+v1qbLi# zWrH4?U`aSdZbVe^Ah{WG9m;^-xX)=xZ+`taZTo_kN>44^={|z?HO&uHp`Cm}nq7G= z-=CF&Ug_L~%W8%U^OElzG%hz>mxb&k64Uyia=32^xQfcrM+j%;uNZIbRM z$tY!Gmk>_;y92;-v!_k>d^{ZQ2W`u4IMAsg}f>m>4Hwd6rRnkKFd(qI3ur50*e9!Ir%319xdtts3)Z z6%F^~Knv6+)ne6BLE#^l^?@xWO_QKx&^D)V3R=u2t53iQ8=s(@!I_nffj0e5g&s5;iW6JcZ+L{7`0L83S#C_buL> zE&u?6fw%79&oHrFfcL3?Cui;(i*ccP;S1;dQ#Uj0U0k)Qqcc5^5(@tc_U>uN3?xU7fm=$D7hx)HLx%(V}*d${Gq zJnY5@Q?oBH!9o1;JMyZw*I$R)6vE*wxF>g$LoBb4mf`z3mbOrpX1;ZD4=!tDk?SJj z%bjliKIoWvxjF3Di1*=v1ay^4Qn@=R{_38BEgg)3G9*}agh-z@TGORz3>r}iY%vQ( z;|D7Qw!H~G=82&tF{;_4EH|z84-UCbN5BW}uc8RXUHuZ)0@&QSw|> zGQ7>6p8YKH#BRTf-z&s#o{q^>lz(o%Xd{J-_=qdL$UXc(Vtxk#jeBjOYoKN$;H4G* zA`G_zK8~DE`H;T)?WC(#X1!(```PZm!KKFCo{8-d35Ah$Y&u8&aeG~>##$4HVSmx| zZX>5HTIY>Wgf25?4*d{lxnaDlD=Xxp!K38er^?>K2i;$skCEb|cl@i8#_1n0I`uLXC7yvc zK&chb_j^z7K|ANo2LZFIE8B1>I1l_`*-et0%AVmQ2&>{?Q^z!>>+Y^xpB!%+1rXJ{ z_RiAHtoS8LM_5$^3!(xm21NUwi7eUyALjkI?pgUj9d7jF+TEWe1A6K$jMQ+51N|1% zM-qW*KB`|Ce6zsZJ9cVL^kS9pR(!h@&>1RQYeMHf3$yop}%={F_4vPbSG z9C8Cv^?!Wwmt$%n-$PpKQ-cC(eI2bA>}#lok}>~e08C~lRk3Z~xTB|6)g1?qoui&L z%lDalek*^wX;gNo8V2^HC|&1}gttxGEM9qlZK%sa&o z{a*DB$Q#J@Ij1|Tyo^_J@&i3prHRq=Ka?{Wzb(AlS$BNiB07TO|Mc*dJ=c|rj)gGr z-XQnh6pc*uhcyj5MB4Lc$Zm&lFy8M~DlrG#9JLP`lwSm#9JbU!Y?%nP6l$WsjdXcD z{5Rzjh!b3N9=Pm}1WY!3ml4O>H`H)#V}_7*p`O|mzc0z0oo=KSp?sJfAl`>kSSow2|S-Gd*!Put7+^xHPnT)(|- zZ|HWzujs;-rSL{!sEuo*@j7vzSA1&Tk#@4mbI$DP-Fu6OD=-$O`yK+chaEfi2iK#O z81HAipbC4vt?Qp~nv(XT*iJ>X1>3-s%si(x4_`sQEE|M)=7M!Tft)8-ijhu zn*HDoxH4*3UL&~FTAVo*XB}~46cBb zgPvDC_Z1O+o9d*&8V#I%gcwF-C3ux1Rnace*_B&lZr=)*07{XRd=~5|9hb3b|6)^Z zG;eQy1&6waT-%Y$+ps!v#|uL&M5bS$#rmhQ9ihI4z-?!-A%Wgyv~m3UDELuVZTHiA z;0;M`t!up$m&PE3rl_%BcotWe+Hmm7n7WzuM@~w7)DYaw+*SJ6>Q``T4H5V1P})DQ zM#$R+K@>WIVIgm&cI-HHEMJPO_W}&TN*bd}cqd`;r5BW&rj-`RcPF7W&rH6fT=`AW zr1#D}xQutNow>syE-Enk$4vvhzM-7|hq1Q|sAB8Gz7HEvN;;)GrIeD|bP8J zM5Gx&Iu%JlLPZ)$0ZHiwMY=%&L0Y=rHJp6<{c?XeH_o0}v*I7u^_y2ap!S+NXQkRF zlR^gq;UnTyKhfy(D;<4FJ9wCUZYDwR|6O5&BWTt?h7O3}Ef4y;tA)~Gphms-Oy|Ti z`%d_lT??rq#QZjn^0jO*BeS@{;Sxx|f89lP)xGS!<_DAx9h@GNH{=+)DGqc5fzXyq zjEYm<5{(|w=2O6yX@##E^O`@drXL(#-Az+V7+Klg1Da`rhgZBn_wnddA*B^z6g!bAo#)MjO4|{<)Gceq9T067*mIy`(Pow zgc@HxX>9rMh8TLc;*9Rbe_ilW#85R51TCb)wwCATjj>PHogT83EJSdJfad(LoxPJH z;L>n5H5-D9Jn`82e6e`yU&5Bp9&a4CU3&OBwEOm4HLH{6lR5-`f4lQC4M zejM0)m_c`&ZXWjK8#z|$UiLg;<9L46OQ;z(A|;waen(ro85eb{jslH4{o*M zz*dv91%xP}K;DwS>L{{<4P0j5+-LtD8aU|I(2(AHHF`Pc?K0quV|U%zjGp!5y6>Ou~W==N?SDq{D!%U{o^D~_-K9|LOn@* zAQ01lF(NJZ-KWXqShx;MfWl@A{Br0fFmcR-IgO_&u`QnrJQSC%uVS$BwthfKrXfI8 zErv1_0iD!PSUm3lf)Df2`|j6ZFv+Dy1=!e#pMp384l7!_dw~a^m#{$qqekcL!>z-` zSOT7%O5kV;nmyZaH~*qQ5lsMY!L7w6)sY+yWDafn#g_5FdvZvc2U6F@t;yMQ;Zq>M zh?RTg37tCCu9J7`qTs%}i@`QRjnw#Yh&0Ad)nAVBKz~b=M&i?i``h)@Vp8OoZNL+)P z&1gU@v`+C%@!Ssx?b>gSfkkauA_{ac&Hzu)R`LKgqyROXda_lViiL+t=KfH|`7Nn) zk;bDt9zX|Ei(qfAf<;(_I9dVjz|E$~AZJ$z62Nw#0FNzM-JgUW5x`cYwAAM~4VqF% zELS}76f{3G$t8Qzl9=q!#P|X~96oeBl(8TMRPz{RIus_ZeL~wV7@k3;r>}i~HC~(x zgjq}T)osawxbxY?HRxq1ZHg(cyhk zJeu{*``2QD@9Xb(5OAFs`yCE})af|s3O8&#iF+#Dmt=YsK@R~3qeX6q<)JG`0)o-; zMH#MK%%02~G{Yu5?o~UCSb(C^W9aP`SrTFKXK8wKmq-lA*E+h9GxS)4u*nVigE2Zn zit7Xm;mOmX7|a~N5WT9F&*)8!B4&6jB{JnKhc_jv6!Y5k!;`|Gpj-W^3?j1|z{OzT zshZ8H3+3t9X^2ceDZQOg!(2D0TvP!G@; z?F?}zVMsFfd`;N0)lnjf84p~RzNg{=TcF%cg+4-mz7={O%^Dtw(HH-lk-*+UD@h5F z7+I;9Qh$jH0TJ*K=FZl!dZrHY2zVr~kUL}%eG_oFO??PdHu^BEC-UyM|Th@9o%MKH<|CqP7k*&s1! zoCA4J3e!YzzgZomG(M-fxeFQvs)HwBFLK8$1kGVQG*cje>AvzI8#sBUR6C|#^Nj+h z$73JQfeKZTd6v<%Ra8hXiL4Db2M8(7n=%^D)*szx!OOFy6mMzarnSw0>KVLBn9;lG z7>)@4nJ&Onqtdk6rT6LHx*IHZb(54#oxuh6k~|G{vPir(>tw!NUBM?w?RC*Qe+XtU z%(J5XV2+g_4s`{igN2})xWi3>5^PN~i)<2TRQ(-@%S*|PiQSpoJ_#x&iywiOJb<|+ zSnMkKaTj!v)~zJ_>6_>bDEc_n`Nw$@=8>w))nVVkM#m;P63G{b83m%fwO>nZSZ~Z`Kv(S8Nn$|wsKW@EjkbpZ{+q{#|EhI39aTUDypSP_B5{~Fobg#;NL?vux1}$!)$^54E!$+&}jHej}9W z@V;Qa6plKn|2peYDDc7q{iW)k0}(x=RK}DdA|dGoE`kE8B8%tO66-`c=dVz{xoKXQx}7mF$1c*7G$P1{&ARoxxcI^kNnZloAJee5r!J(;Hc_lrMrz7 zS`M@6LOOO@ce}f%5@ITW%u?cIp@*bRZ?dQ+`{uLWo=%$hQ)yQbts+$grr}(k%7?3>5avq@Fk0;sDC#~*>-!yd^WW$G_p$wR88S8bSmw_3!v@%^ULdb8 z_<-5bT0@Rae^k|Y0iA8$x9u9V(yO*f7Kxs(278run(NNEZN?2yb|x(|yXFW>ec|#1 zhAV34Cb^pVn2@>N!(Oozy|whl2A2F z<*jVoaGSO@Q$j)^R(gK|mn=diUzwYhn~||)+>j?%2eQnfmepU%cxSCo*O4lA-SFot zS5MgYdicswr??oz1ou1I7vwMk@#+UQQdRHhiLrk#deWQVL*=JokgA6}kU=q=i8pN% zChZ7B?h$DGExYBeD8WaZ=B#M9qJvYCMdF)Mak^DI#?|>ixA)$?)VLlhU7o9QgIYHNjtKP=%!DT2ckcqN8}`}p9=G9- zq*-$AXc8SQ+D_D(53@Qm-uGplm?fhZmexiz+^#ld5kk?(WHSQo5Z~QU)h?~*HZLqp zL*w_~ROf$8MbO*~;2eGJsRZ>1A(i{M-6PlEB7}FKsJ>asrvZ25~nZz#%^-Fiqhij-UKzk9(!iKni~^HwohOEDk>a3X|Hi9P;+$3+eN$j9&2yP1EJ8NlTarO}o%erwpVfd~0} z)(zfq2CN*1-(=1g@MZ1c%PzU?=KklhVTdcT zGgy6KJ&&pDw^+h%y?aW)-Q!lApagiAe-D2X2K;xV|L?zpJP^Fk7q5MB0C(2+R6&9c zew#utv10MICpZ%So+mi!408xEa7EZ||Oo=K=2lywah&XF=vKD<}N7C_{g;I>Y)@U8v3x=hidu=5HEf#>xb=V*$m})k`cD z`W3ufk3WVbJ}$Jc9{K~}HXqDXGzW004~r&Kx4`|*T>a-qLB^cxZ;pyIsTP)U*z6K+ zs7}8(d71c{fA4$&Q!aiE*O)ke#xw`2S^QbwgZpjE`nzKh)KI}9I>NLt>@R zt7E)fhQOr(W$2$ruP6bR#x<=ImV5#(U0;%}r-YRTWaj2c_n-c}+hlU=LH=bS$xf;PQl!cZnzxs%I^>#VJ3_M zG>7Hg!bHEO&RtM*#4(>Ge`)wjgXSsAsl#~GvQPeBmKe-fN_9G zGh|hzxehQ0_^$+Fq(t(RDW8r5j|+VP@dbFgcs$xoFk?!7mG!iD5If-m3SJtJ*y~C@ z1+BG97~dgCElI27f|mfcL|ZTu@&OrXGit47vG*#^d1+3r_*<<*lf3tq!I& z4j(|uvPL8080R32cszIZF!gyhX?g$# z)b}?$;r?o9bSv{$;oAE6KgT2vK+eew=H7kV3~VrCY_{JYRKS~-xUs@OmNq8v|HF*O zw3jawl{@NQR@@ODXW;=(vC>yAAnm+Cjk3}IZPTwD*!UO?+%hpfTw$08#Fc0?c4!@> zchOn4K%kwTd z0?AwH;t7es@wbZMs^PckJsY{JGZ6ve1M>e7%6Ch?i6NKq*G5I4|3P+D7&r(~oSEv< zwhfBSkjeyCL7~>D|Kr20`O@ZX7_9^2Z>HGgipL>vR}qR0)jd~U1%<-Yo83F0bIdsk zmRa=;@)kpjaMpzZY>pHuR%$ci{27o%g4uB14LW#Idd|eEUz7D;2D^QA-WjPsj+TB5 z5KgA(vHu>u$bftdW9V}&7cc!(D46EHVe7@DxuwW_ek+r9xZ2SRXfcdNGASXNBwGR^ z%(1p^zu=nHRzvHS9eG(6v7mU6IIYbiE{?p9R%qAtux$67_4^n*19Zz>(4Y*sgQce-SjC1rSMpWFoMrhXc^6|8 z%NWcqUX+!FElzlBhFz&R>P7-!QCj%@4**ap3g>_{DR%czNpQ;jVvHxy&cw!qcW{2^ zxu#3=7%0Dq!6Zt7!na;86vvd19Tqn$U`H8#tqs;KD2w*9nIuSWTVMr-p43+?48v={ zY|R&25WP&T`=XaZg_Xq-kXxc7m-q`$V2CBPLy64j02VzqotXZ0+(WAZ#_>(K&SoH^ zVyU4@-lO8UHTQYGoBIPEY)MbuiugFfNQL@1vbSUR-#|ic&~BVS1uEkh#DmX%XEKQ^ zm|lEaz)iuo6^hgPIQob-MeXs&ahpg2Pf&wu0VYGb_n=ucvss;LD+Noth8^^FZ8lU8 zIx(Ao2OXY}o_&2+NAR~-qM=PV_j6ln-NZum{;8C+lY`BBgzSdziQ&ya71~$Q@Qt<8ufAS$KH2RyRbjVqVX7Q zc~$ZmVu5c|^m{6f3VC&DWhhvQ-o{D;e>2uV1oI37rlc82{=}J~ee%WVyUsNZqwlhw z$v73y|B$N#WzEs*t!wLGFM~YIKBrfpG;v=?gib_*I(*fC>+m<&%&@*$P!vAHAN4N( z6EH-N%YStV05V8IUrtWICh)W3Jll8w#6N>eh!CWsUx3l!?>Z5q!v)V35J&(nAn>_-$obih_Q?sBJjQ4c-G$2ZH3?_oPrtxQSg&Mx84~0SNx45%2GY|H|IaJ(pFZd)m@rxX zE;(T`I#dn^pU0};i9WoWj{PT2@Q2eN2nTWe`xCB5?8xgeTKLBt;Y218a1sA?6WNJ? zjH7Cj%yD2B63BEISX(uOW79ntR9RIr`JeP4^9lk(x^Si*v@%A_?44u-jzJDG(lJ~F zpA74~;L02NW4r$jzMW?P@GLUJY0^CC0@xq9ZevUsfg7#=@WB=~@&N{?f0;>{lm1^b z9ppdAfa}pBr{vv|< z6Xu`8{px{*6Q+zg1aq?eFcxUm3Q z`N6<(%njNQ65GpgpD!~3(*pUR>C1`Q3bpg*y2tzf@`fuK{ab1$FRoYZP-#tj16bjc z*Rl=Jz}Y1B?tAzwo1ce5>G8p0Hn;@kg4mR{r31jALO~289ugiD5fm8|1^%lq9;hy3 zGh#Div%aJ^XU$@rXPsp1^#R+GWwlDD%9zT^5!fDYw>}=A=ypU= zk+gh;VLCkJy@Hnrzh_sjMO;+EldX>nzLRd~f96UD?2{|c$1Vh@y)2mBJfWf1z<_A{oJMC+pJ>Wf?pl5CgS~>s#a)zkmL@-Q6nv zBa5KLN-6sKaI4bKEY2+mfI}M{hF4X%SpNoBhrlpB*u`!RdQogR)KzI<>v5q?+)UKt6Q(u9dts6_#MVd zK(&J>mWc8^>bt$GhppJ!;^ZMyM zy!peM0Nf(H%Xsj!v>qhV0@XhTfb1_rU++W|piiEK$~Y68v>oGA60e#RP|22i8|D7E0T&Vz}xNqWZi-|pM8%MLSU$$W{JsH zU9ai)akz)aKF$4e=BN6#flqq>WzBbf1i-ftP-vFumA*KwTyQ#BmpGVmod-RR%MAt3 z9VB39AEj+IQQ)l5g9psL7DFDB%IoaOnb#ePj4@un;dCWH{O5cBt9%#n=l2gHbLJn6 z(jiO)Fn9MiDiGtdU*3YU| z&L*ah%C>p{K7hU*tb33eit6X{`uE{1gO-RLj7$>+n2Lo!*~?9n9BlNMWa8`5P$R=A zhUVypWV_l!U2i(@1&HLbfsJ>dQ7~(#BS59z|_xI1G@3;-O@&m7`gKGfRVRIlK`(iN8wdH zuw%ak!3D0#`Q>*gp#Rf{DDF1#s(#@(>L24H3!JiiO{Zm(qp`v(@i04B`1T^cQ+@ew zx`!DrgeB`wRQE&-rmW#I3#bn4J%K^LN2K=>=$jECjSSJ9+-Yfi`unTjP z2{Dnb*A0v`$uN5j{q-IyV?XR#uT=Nx!{6SZMtep6-nqC*amBq~N?Y0RK}^L{vY&U9 zQ5}P)pH-hJ z|9&?`QUWw``ud9TaI}4nn9(eRr8686w~VAa*w4qQElTocLC`@)oW+ld^A>2hPL7R! ze}B^maPN1=K!K9_7IVt+}4f%aFZ=?`9(MH?{ zT`)#55i<2VDmg!1yM+GV6X*kl2Xi2wjYPN%YY#7>0MPr*GV>WNDD04ON}3heeF6|N zb6s$jxQGJ!>s!_W6$J5fWH|;YM=Gljvf=+e4wcvJbB^xKzQf4BwH!gro|TM0hH=-9 z`Ys?WaX z{a>Hi`jKglr-A7SHYw*sWn<;h!_Kvd`=;Jx(@)Byn!p#8uEWFyXHXjoflm;)5O?{p zA9HZdM1|@XmUVL(My&PJ>AsTFHJZ&InJt^m3~Ni<00+0NQt4L~G;C!v4g^lT9MScK z1KyycKe{#j2s>{Rlr0S?jTfw8Tm8rof^x!>>V01?nftD@qsRivXwM2C;tkl?vgWM7 zT4{4omBR-Kue}Eh$q?v(Xh`ry=lm&?h}}2ybGZ7l@{1nnu07(L>VX^EfX;diah2i* zIKb-%ttL6pu%EmDFJI&EuOG*WKUzYH6!&}0+Vsu-luG#fhX?WJi_ePsP2_4fint7$ ztaIpK9y<{X6S!QZpqD5Lt5ddbL6(}sXMBD6y;)DEpB44?Xc%i(o<9wIK;)JNx@z-) zD~bg}W|Dy}Ad=&&APYl)6l*3j#ntRS)-GCn#wjVsZeM_t@$0>YzE_PyzFgiXxBFU- zCp0s05Z2-+2CTT%`vdI{M^Fi3I+c4x56{-KYr(rcxCSH=Rua>bED$`V3}8&fmP2sO zrTlkZW+1E^#0H}a%4ez!cilf}{_{>NwCn7lwbX*FY2U)HGID)H7n;Rzffg2iU*kIh zVwm@PTGvvzdjA^3L|ZwkonkmD0tw!iH>`vQl4(6vv9(8F32tuYe#~c*2MxO- z1)ecY|A!d^{WE1a(LS6>J}{QcF}4-g)vOXF*WCm?Y!X<3VP{waNLHk}4yN%#o36PJ z*NldbCksRv_2S`^752|T?2&JFh0=rBC%be>dO{l%leil3{62aY4B zjt}?!+ddZf0yz@okPKE=%QtP!X`Q4Q=;CZET+`=GUY*Uu7^LB5wjTw@q?_h&tQVQ_ zlho9o7kzGE{e%GZ5){|d@H?9?7;I+^6>F*^e&h*_v&*QQjkY)K%#Xyt5;8HF{&WsX z(pd2R4VO|s4P&e&_+zN5!UNw_{pYx&67FQ40<86Qa%1PuTdgFTK|tswJ^M$c$DYhp zT2dhUt#Jk-wn_t8Z@!+(Wi~USdC%+1y7+c0Nej%yvgCPzg>~5k;Q6%j20ba13&9VG zM}PQvd?`K$J%v!v2gv(rzhlF*R{w1PVa<-2p)r!+&ii!L%K~-&gAYo{{RA7mcmSh1 z!1nb63&fdJXoSgZw-f~LL9rcX>qh3mWX%T+2lXNJI$kxVAMYcGJC(q5&^I2IDG@%_ zw#WEBdcEq2ZsS(ZL~P*^RF2X>utE?}zx6$SVD8z&m0xjtb3)8S0m)b98|DmG5<~C8 z``!HKtMquVqTd6wd|}0#ZZcA3eD-|5YVmj%CVB&?lcJ1wDD6`Ygo;sjla>Wc$^uAi z=}9fWx3WE6e0$}{@t+N3o)=FYEI!sSrDKC~8-pikS#ZDMuK{T8AXrt_3;Gw1#Wf<4 zo6BO~27K+4Mz|65WM=TX5BT)wn~-5xljwXUjhlqSgGeVZ{Pddhk>0uCuI)p0w3NuC zDjq};bbD~Xp4yZTwg0vL36LhXo;R0@B&FJWxfwg>XEUn5I+26@y##%OA zhT8iMxJ{2#$L!ulzo`zWz6sLnP(b?IA5rzD=M*5RHBnE?gxy@t8MQ0)cFD_GHSA4Fn%A@7qbA*L3cK>YJqt z-r=*A&SVD4_oDID=FF5V2fpVQ02`)QN)!L%^aK6U$!oJDd(fhjCC0Fvgd~#(i()!+F0SRWXX@`<{kCS46uYZ zJDdiJ^7pDH>vl&5PHxak4=GL7{qU^EfLI1kK*-@5llA9GVakUc4=d{4P=+aYh7bf0 zs|g!Bh7xlSWxdbvJLXt*0HVgbTZVw*wE&!OeJ=>bDFAYrLt^KuyE!ov`PJfIaDWU1 zj42HF=4T?Gw}y~zV+h~{L{Yw4SHC-!?%=W&3r&h$ik#m& zBQ|-w!Po3(GC*AV@!E<>WOW$o2{?X~vdWWI`4QL2_OK~jTHk229b9gX8JoqOer_+4 zs00vv&@dZ@s{GD(rzp|aOU$wu2v*tFi_?J%c}8Mfm5CR`qn1>jfOe&1PQBJK5%hy4 z@S$(>D$$oGpdA_8%p!2F)Q^D&P1fOU#%SW*%V%EI4=AIS)f8FnJ&%8ILFU8I^pHMs zsimnBIlKaU zdT96RCM!b#4k1T0vdbnoTB}IhfN#s4u~$UZdhr0X(v-}xT*5KSf8{xx-usbINe}jb zBnm;Wrw-%98%R9P7bvcL2h0$ny`WUEZT4(JyY3}2yq0(Sk8rsZ49*~q3E4C`%x)g$ zv)MX@e)g%~aBGr7BIh?a=-No;iBf>hvzbH3VqRGmIhQR_<8f0nE_ev;E?TMT>yBr{jyK@2*b8%G(fed@t^rtt&|S)m2k%qfShJG9tPWk&&}a@s%X*P9kJJDD z^>2{+UNx3;kzRgccDw_&st_1f=(A=t8)3mwycF#hqx?#%2x++ItrAdH>Ft(T5K$Kz z>1epD+H(5@eEnfPlMEKyl1TYKDYmY^tKHb2_4!z#&}xLaIdX3P3qhV~M=3<#Zj&iR zhvackCDLj zAa|G{f=V8%Vl!fi+=1{VWf&}4Vt>%=5zP`Dbm2`7s$mM%6HLu!E+JvhoP$Ke$NX31qNEE42x*9NLx?$CW`7`4;r23J zd>LS8D>tPH4@5h$ z3JlUqCFBgKiLQEX5YiK?b+Vu=ZiKh}fD^foKy=)6uO~~Wk~0#ia@Oi@(a#U1+@uL< z@u>mubj#Cka6`Aa#=t=k@?6?JZP~-Q8)t7=kn+;Nq->wCAg%;6zOTMXa&Tq26?G?1 zFVkuUg3mr+mu-zj7*vqIIM&VlrPm0*MoQD36-mU|?a=Fck&+bjLmp3aTE#I1Lb_tf zr06A&%=FgK;@ot$@!?FiqL|)ppwk>`y>|}4O;Vqgv%k>2th57Fst8EAE@QjS{B_}- zX&R*w?2*slQ*N0LbSM?)guaAtN!)=%@>{6JEwgC1iml*e6ukNrx?HT=t?~tTFn%i` zEwe1qXgG*W9b3bQT$n>yi8d@9yqx9cF}|26Pa9wnwTq%r$`lD-`@NebY9SyuRr>~0 zweZo{T$unp2ifP?zS|N{L4XmSFN0dJrBT+h@6(wj=ZR2^p`o&Dn74>5HVTt_|kkk=BTgBwTQ){Xlth}MEVg|py`Y-o|~`ul8pGtYmDw=KbHl5y%#?# ztb&?BO2huCnd!ILoy4Wv1Cl|xSs1G6Zmn0XUiu#fl&C~Wcjr-XbUmAkQK02J;oPCtgjl=$SAV(Ii zvl9FKbd!umSc-w!wtLxJTSPJe68)?$QFoo@$FqBU(`r$)BYl;NuOMr>k!4!dPVToo z4{jcOMV)oGIF#7e9z{LS&)}&l$0+O1`khu><-BQCkXpmOcA|iFea6*ObN&p?B}#Ji zo_!ISbTu&vbwFI~PMy-ORIm6`?r;KgpVkH65CYS^a4@0cStOJ^`s2RR?ZQ3KdG*7= zc5(7G^BsI-=J&zR&@pA7VMl3#-?b;#eCJD&j!Pt;4S&AfJJD(4#XwZmDV$i!(|!bY zxoFoWIN@TbLUzejzF?({oIoL1Q<;qE4Vy%_6Iuh zo^5IfYRw6iRAAfaKP+p?YrrCKZaNNb^8jIcw1r{WQYKWH^j!qOMXh&Oa@1b`qSTH> zhy3%SlD^x!_8bAkLvr2IyF4a6nXHv_E>LBUrS4X#5Wz(yr+~Ptj~$~p zTV?6u`;xZB5bBVgRyp4-^n^3eR%tT`4J$jncD2yaz+>#Rv~x&g0!tgeWv+ld=Yk3O zJ_)xw?@UaVs<@TM+2FlX$>%EqHk9o3Wx32g3#ytYE__zKVbWJf3@TR}jAsWXl5!OJ zP@YG3*$}MMz81;vg4~$jSl&diM&4d{aJ%*07lYw@C@p%(g5Q-yO_dzt35Wq`tKVJV9YRw% zlBZak&kQ01uANYI zoAH>VgTReLrB`vE6t)XZLC*=^((ZqW@2bS=^$=&UTR1|Ew4Rg35)^vhA%5_OeMPAK;t7(3 zd@L5y>J7z3cgjFW}nm`rN(mr}j!GJmvQ=;+}WB>bb3;+RUO?Rk-^sSm`HQ zkrkQlWC)86KI=|J!Sr-~)%~+BBVN7zI@29qW!YcttFal`g9M&yD^+V(U&&1sKv>c$ z$?9jkLsx?o-|Qkc$A2a9AH#K6YW#U5;s?@OP~t1$82|MEM(=C#ipHhm`gq?L`iyCS zm}=^SIc>OIgd1a^9azNF%7(q>`zi0ru;VN8M%q$+(XR;q!X_k`4*)Vor(f>lp-dAN z{#tyfWV}Y-y%&5uiHvS zMIG7t`#7kLORp9yNd>7y+HOt%qQ)+u%&^~jAjz68US^9+eBkLvKJE(*NwuBdVm+rl z+Oeame;~r>3imi;?l+?5(fJcKUVpUG$voY}^8&pL_SQY-et|^CI}_%|FtTr-I(AB3NgvekmzqIal)jtY-jU+(BPg zl4q$P@zoGW3*R&5Lygd>wu;Ux=wJ9XH()M85v1vO0ZAvXl8>sBTSCtGnK)(H6N{`h z4QIJ~X6Pr`K~Yd6vjD-$+m(DWN@v!*5Rr{5z)D0^%B#H1akSGat1Kanq1rq7(q6bx z&iDErvUrn<@CuWA~W(l6-zb z@^coY?GqMx*@>@M(v{Z-T+lRgrWqp~L9h63W-A$$y;Px+m{{_dVC!oY0S+Qh!$ZQ^ zxB}m`p*3lJo1?Nx)%%{9s^lIX&3Pkt($HPUkNVtI*Euy?JqOetK0%p&#AU>K-i=Y*F0PEp2~paSya-6#5&VRtyLhC@>hJzS@sm zJVD)kK1f5LS>(%!k5)q6~g-KaOmA_PnL%#)y5jl;xeS(Ocx)4Xfs8Vaob^ zC@r>PL|t-elewOzh0Kov>cnsidNy9Ah*ZNX0dc|>HOk)M%w0)*xc9EHqAaLX=2j=Hp|Bb!0@o_d+QQI68ak7111;M0pp zk&&8Sb`uFARw^ZvUxaKmP7DFW2c!sF*Xyn`I#=d%Qlv;F3B0mr`$~ScNx+RR(_1g! zESr8=U(@kSDekOgouO4BWs1PN-C;07=c@E*lx0ETL_d}&88 z^%XM8pCttHx8CFJlm0}~)irc>jFlbql`Xk1n%uf#Es|@LgVC*)X&n$Z*U^eg)!Rlr z8aE+7H%n>{;9G_ZnNSjpDwY*q;4K^5VNm+kyc0`tgP3XXaC`CXTo^JO_f}}ayVghw zSrT>~5}g!z2iYLDDN<#F&TYbu>o3gO_go~)@P|=+x8xE!+6h2CmRhCyVn^X-n}JNl zj{=rvC&yF51^P0>LenP?p?(Tgd`t7sIW+B2)%?Gy=;|^npc6H(iOyTzpXN|?*U$Vo z0?KB-GWXR_G~C2DNHYPPeUf}Lrv-~xj+kuDZA<6AOevG^C5law&$Mw>>aZA`7Zig_ zz^2CJB?x^0wGh!pqOILe_rJe}ing47yaIta`*EM>E>E7OLX=TCo+l&gcSLDKcYN8- zz^lfU269R0BEpW|o_%f7EYy|kuBIc^-az)}?v7WOd{>3FIJecmJM#(07izc8-PwL^ z-y_>=MZ0Wi;P}u@s@(5ZnPB0KR05C6Vi$#S?oV|A_%HLwxO(gqQVQAE6rQ){7=?a+ zazds3`?OPg2Id1u%Q7QCAwmHCOVCNm0Wm(=tvjkv=D1jVkZK`Ec;nc5yhSrxLBChe zn&MfrTJ*AYQID`9e%<7I%6Nkx=2=PU1?cNtW0tpwIkq)qf2nV3Rk}U`W`hXVigVgz zN!slxF&f(vNw(e|JDKp%>vZ~9H6EtfVE?ziNZt2Jv+1Xc=f7*9Yat=)H&O#8P?YCZ znI%LcTEaoKUNYKV9qdZ+RYo){j`D6v(mP3O&Gd!)`$T2F#49`jiJ09?so~zj1lBxP z4!`Q9I-6Q+KN}1wP~|S|HE{4Wmm6GUG_iWPA8eC(`vJ8nnP;ili}^KHSv_eCfk!rP zPE#grw)k~`9{yY z_8V+%HFtdFzO%pAVkZt1GaYl8rrO3Wx+0$n(PePVXiQ0K{7D<26erOvRt2g%N>Px&7LTmuKknU1j$~ zEw&?EFa+4O?JDlQ#oZUg>cASr`fRNU1zE^3d=Mh$^iFlm03{MBL^dJE01OOLGM2|2K-OM%Kw^RXCTsLv5w z3^!;jj)m)QeT!G8n%fujA!4n~WYktL8vGxDu7W@mCiz2y)g35MvH9W4 zLEIp`IeRhkZw3=CH$2D8EQXts9#1qWQQ%w3wyJDM236SEUXK0KkM(!Qr|nGZkzF*+ z3*oVP24^?V3$d|e(^|uaN$fEfW5|RTqcNH3t366P0#gY|u%5)r7~oFTjlG*&2>-#C zY9Nn`p|r%lVP_CLin|e%OFHMzzhttWh0$8kQWhtcteg3+zA|ZF32_G!Px-|9y|OlT zdR1R!WBzHmL#2|i??tzwUdHsd)+b>oY2l*Z1xX!MIA?bd ztn~P6B=&QFu1>xfzOyli8(v9GfSgIX%q>7$pg(|%CrFIwnpe%~&X;uxKf{w3LJ)U6 zsAS&=o7YVx)FAYDKuCWC#JOFKV*KI!pO(1uPi8rdW2(w`;6meI{L|OLAAXPSHuoO%WCwoSzCPjt|F$^oLi`S zZLh#zYiu?1f9ZIP^hnfGfTS)*jG1!F;K9^b$ldU#*FM#&?6i;;oW>T9_0 zo)#@A5FS^WqW2YX{Z87WcZox3?}ZciddLv&@Vq8B**|%HKxy&ttIbOc5YdBHu4^U^ zuDOOhPP`+=7~k$+^An4ZBOF_Yo;(n}kWi!K2@64^QiVLn=i82;l@e}&!z*D>)C>F- z0{sv#xry;Je|Za%BOq4|0-6gEQVy53Vz+RG67!*0H3H7p6Utb4g>!^brl4W{u_GaS z11_^YvaZ`P9*W)v={M7JMi!=CMk{8Ng+e%`WIQrFn{-~S7<}{c@Nw+kH-K@VSe#<& zd_lNRxJr2A@L94FlN4FAXy}7)Y)dzBujVjv;K!HY#K&tVov0$Hpn9Z=@k9B;C&WCb zb9&r>R{zdB+B@_FV+~KV#Ixm7&^5YVGLGFTNfOh^YoOcUMy^y?9asIR?M>%oA8?KOV_z5X#R1ng+JDH>>SK&tlmt^=1_k9K}ExW0MG#*(+xAKZryg z1w%V#yfb+cK{SCi>@tG1-*ipsi$7wqInb>=YtAuS?h1_iFl%59B0z)6?VUt?Yt^d> zj6O^n+Y0q2b`L?+WBd}HUwsu>of2Td79qRF7I&fs(|G8dZHp;5h(?^XHOS*DLz}0b zPC8zGhUkr`ixyGu8iBs-id?SRRVWnnf=@rQ77EW3Yj`?PJ|uC)6Tph>V*;I;u_q|n z(i&$qB~k?s`NL(5F-3$mvCvTYvn`yko0SOG1*q%~h2-yM5{0))l$YcXoU~W6kcQu< zgW6&-_dU9Y2MNKa{UZbyM-b?}C@0rBIV)rlv*o29S4^#-{cbO&^!NUNL@ zT9ioe!+xA%!t*TP(1{*#k`kN!g$a$Knf&wFMbCHkMixOU@b4^U@K{0EADn$Xkl0Ds zfS-61U&MZ4k~Ita?$s>J7jYghIoSwDE%(|&UaSp0=*LP947Zi(G`*ib-8D)jGfT$6{I&e=p%^l@!B{M^ECt1Jc)9 z&ygxTY8HBevG$fs+VqK`)z2wzpiCZjv3~I){v0p2n7arpERGx~wxomKzwB60Bl|b8 z)EzW2yGJ%(E9yU%cH6<&@gq;VM@uEkVU`_hrefjyL#$=sc%HCb zuLkeQed&QLr@}`Hv6_iHpxMvk(47n=EfZ(OtjhJpmlk~lLaP-#cqOL&CAjJ4K`|jm zIu1YIzIOK+rC(UGK^_qsfDKKyYMmz^-QkT#a>jgkf$@uv=? zXg;f0Da>cDuIZGSw!ktk%BQ19I( zR>$TYitYFoyAmm@ekK%?1)QTGJQn00V|5^NJVyI%Wy!wX1L=VJY{^9HH2f{^7z>W0 z)%$fu5E)0fn98Yst7fa}2BQ=W2kN8W=B-bUb6++@7Tu6{zxb>n!27A8EU6X^*5n-FRE8NP>WeyN_zX=@Wh!4|STYu;fsh4uJEJhCd3Ffl4*aceS|F+o^j?R} zegsF!z-ie6EPNzw>V>@H@>=+aA8@TW7*)6uCI-S7BgL#RA6Ua*5hf>}jW17b93=jt z>{8V9hM>~z$y;Bni70X2{;(^S?NQ-(WapNa(*|R#8F-Xz3v&pWSxJup;h7G=S+OU@fqJ#_;m zY`fc+@;HXeZI8nEPjMK-^UGdb?Bo4{QlwlRiw#Q-@929NjdZVs;r0kyp$TkjuoD8o z=a-ga!I~&$z(XT|WH4RIsX4hXE+tul6|t02Q8z-lzt9EUUP5>M5iK$krd;yAHx7%@ zf6wwP?cqnfDOsZ9WXQmSTwr!}+11e~m%yCv$~T3^2jUh!MA)NF7Q2q1KRgdJG2UD& z-rQ`w@MHAt`P!}#>0vmLDDsG%peT#CaJDQ6t822c3^I)s?UG<;6UZ4R(M}{F4~k~c z5KKINe?h!*0Aj|yqL;g{kd0;X&DuR6%Xt%uMgQwE1|hyYF+cyQEh9h}F3XIZ9&vcP zNd~}&+UBk8OL^IGrBv%(`Rj!-VyKmk7DVbC z=(4xBvYt^^z+&`@rln`-jH>Dvtb_jwunq)gaD$#RPDNj;F>k=XzWdj&17+L)Dr`Hh zX#lK2t`J3JE2B>{u%t}8tf?IC*ZzOiU3nnX+uLW5v4j~yA$uvitR+T9){3qzgdq~L zMH2a@$X3acA>2qSDqPBq(3m7kXwOoJQlt`D<9*Jc+x`9C`~Ked&-eb*HS=B0IrE(7 zJm)!|&*zbQd@UpL$D@*G;mLf<=!qWp9WsvR;qQ{J66P}2toikY8)AC{C#6*@7DFzs zY!;Y8u7HC4Mql`5KGJQOM(H zvEK;{c|N1*Gq-)>+VH0#b>1N#edyQh$(bCA?H2achg@}+hZYC7XuO~wzicrtX&JMG zD=ZJ60zFzD`yG0Kvr`p_L1O~Iw|fU_;rFm)VEz7mL@7|NLK>g}|IIBJ^tl@1f3{Li@ zM)!9!5>8CYmAf%J_djAJF`7wbchy~gk=7>&MZ*wTLx3#6@P{>z0Y5bcVX2`Y;l|&c z{HJ-N0Nc2JtmL2`AeZh2EAz8V0AYw5Y56H@blyVmT?5!m{)$C-jC>aB`)$=>sS_WO z{k3*h7rg*z>aH30xl#VB$4HsKf8y18eaPJ&=o(yNX$4<=*r;aKI7wz(s;@O}tvU`F zRNH^*!}>n_4|)nQxwN5w^ClJQ18bZda|87Y{DbMdkNppjPHUrFi`EIL>vDzk8_zN) z0e(m44?=YJ!FP9|+F&dytO-IWcb`eke7y4$9Q(?@xpL%=d{IgLDg<~xts2O%#}iVy zBprb~$;i)JGI(=m`>`veOn;u>w+ooVoRQxudA|(?!%sfTS|D>qU}YlFk6k<>U=qZR zn)DlP6{oQlXvQ{H&k1fe9aO&X5+sWqgWJ=o$+bui%Lu6%Z}bJfzVfDKC99034Z^M& zS9^0|+nrLKlxiZ#GcgPd`1zz#yBGWojrtf^F~42zuzKK7VMlg;4Lwg6YH0>7*J~xR zHdYPvdq)dRs7DpFOifKbb3vvHg}&<8*uVb_}GnxY>K=W1Ms&nhc1{O0ls6E4A<+i!PIA5JB``W%1I z@=|M<)7?a(PA9d<7PkufgS9?MTwHOD&h>D>mFHaV>VQD(_q7Pxi!Z$O_PIoo52qMtkF^gu?80_k=x5Lxg?)DN2VZ`*A4*reMS_F#xOgsN>GokFG4 zG8qRLWdMmPUE!_q!g_yiYrJ_>sq4`nYV)PvrG4g(mDp8RFub^6&-y#_A&DU?hFaVW zUhb&cX%ds?wsVd1E_!oh-yWAy{s5ksHu)j{x%Rmo9H*u$VH=MGmG!bwp+LbK*X(g! zdn-R-w;Xk^XR!oYpmVWNK8QvP{g1||>`gv}Ho1Go(o2nsu%z(ID`>E8QeKhXC$H$eXC#t>dS|5vEh~TjklWJPexsKrYzdSMGP!RP@^DvfG_++Y85~i<7T*5!o`sb=t$lSRD-tmO7s1=sbSC0%Y`1xmuxg2k&bE zPpyn&01R8s9!^OGgq9i+MQZEs-un9JRX0tU>Y{h?2Q4WwV>*kZT;F9LxNgPv>2SYW zg`v=#J8X89lMXjnWmLcps$G_kR|i5R%&ko|i0h3?+)|Q_1Xr%Qs3R4HfmWotD5&@M zfIlZ71l~}|t+E)PIID-*#y_k;A{8f(QWCO59ZOE%#YXf zsG2D+D0c2{5EFOA!pg>oi0b2eOwnU;2m9|G|m`2#$Kl z_PqwIy0{=z!&L!2RTVdS9MWV>---1Yx}qusG{n+Gex5-rKr5Qn9){*8Kmpq$1D-R? z%@n5OwqvX0vi@Pr9`RRz0!seigEyiIbp~ok;nf}~z92}iARt~Jn;#vOn(|AO=!SX5YetZ5riOtM~(WMlxsv8YO6?s6p7;MB8oBy$R-U)BuJe` zHesc(8yLlvy!C>}XuMKLz(H#Exy6i+m@UCO=7=iPUXEbR#-=92{x-up44ACGg1C$i z(qX-j;TLx`t|G2s5<)DacEVQzfv8HfQj?{dkTJSE40~1@BnD}3qk`1iUPro!R7XDW*1l^No*j4ui{tQU{1{o#0heea7Hi-6jCmGP;&#}dlD`aXlkA`4^OIh{DrFB&m}3t_Q<)spOj&BOCvF87LG#+$2|Ggpqi)a2{9*LnQ z|F_R90!P^!S~Js4_7DXTfP1M`2Pori|I)+VlC>PKhd+3yhF9I-jyY?VJBAvsPky#f zqEAN3BR@^B9M#x%L8oHRnB8~C{@q5>vN6*25)PWowbx8B=hs=LM@WFny#rQKYTk4G z;7;6ejx+{?5N;cjit6C?{_y6ME{i>jKRBRx&7f17A$J>UH5W(7n*-Gzz$L@nSK(l0 zGh1tP4X+-=EN8>A|K#F2$b>5&@xv!4B(ssq@u)8tQEoHy^|jDsO-tNv>0Ht)jWJtY zK4v4c_a}Z`@4$HGq;j=ixxC%yFJq|=Hgh4~!C8`ZXLHK*(Z(17Kgp$EbaC`$+6cI4 zZON+m_xNDe+h^Y!)>;u-8$M>WOqls0X2>npK8+dU`|73HQF zUa*gy{ayiMm0fs}nGp=IbsfcBMgpU5bfXb@WX3%v0%&0EZ@#wdLz@O2~FB>=yPxB z^(MKh%yd(-*<;WoTQx6dxzX{L%L^c0DlL%quVL7tB(!dDBXhJF-IQ^Hu=Lgf3%IH= z-~Y{$H)->Lm+W56R7j=svHiL7&$rRUcWp zi3&Fz3}Y&CW;jF+8#HhO?YBQKUO$MgSK>YTjNu@KI2vI#73xlZ-@S18Zn*r_0CVx- z1@~x;cyecr-&8ZM7RJNHmAXu}%E%oGaz?F(lwr~6U}xyU)xqd$Dtqn6r5;(L9@(ru zGNZJ3gA&{@Jj!H$_pcst{y!WCY-t=8Y;SNc4k?^WPSnhcT?S4ATFt*7u=|wt(+*LT z+$IGhFL*C3bLrDl9HJmg-dp+Rhu`G*O-u|00>zE%3+eOogU0&aD_;TYPTU#DT1fw_ z+-Ym2as;f?G|-*KR@uVm#m#C>WtAJ7fH?Wn_(*RcULDTLE0bQZ)Tki7Nf2NYMJK!g zaAX$K3hM8@kW=6W

8vrFHP@K?g>t;1^P*zm48g1vKb7sLs9;Dd!^*{C{~3cIMyS z^N5JztvW=<`+_KPh-iki>DnDiZF95TPwUWt%)IIrsBwLPzHWvBS1go830Gr#hzsiw z$HyyhGFE?9l0iX&*gt7YKZIq%NVtGUr~k|sBtJg;C03ssL(-@A5FXXRE{1p+ROdNz zj)3e+e#kr6Cau6UAv%6};?3+kEe2T^Y3@xz)!Egc_IExSG-%X(VGGRI2BQGDc>;JI ziYMVHOB4iUDX6xG#~E?Tiit5`erY-Q@rYgZ0 zI|Di{qSa9BI~G*hb+aRqUXhNVl@8xlh=sTr< zL8+)`>r~ndq_(0pp4&^Oe}fcyENqZ89sE-K(Y6p(5O)_rayhSdKoFqHI}Uq_Z6#vG zKd_D$)q;g0aV$q-A65jum13vc)ua7HQb%ewUkfyq2H%v#3CjV#(iwIob# zEyI1ri{_FeeY8gdAma6$gcp28CLl@>BruS|HUK-gP517HgEmY23kmhe0eP2rrJjqZ z7D7Ta-cP1T2|EwMIFtUYMow4OB@I=B#$ElW4_l*5T##7bEAjcs2XYybH+sEW<`LO4 z#y{e%2$Emq1tO9Q4HC|xNCgW;zvQS-F!cKc#`%Z@k`}}{la;90*0G91kj#um^v{S7 z<}L|+?}2M3{MI|Nm&*l@HawWG$Uwx%f%A!5q-u=uGFCz~$@poIntUiXd5Jv7!mArV zn}^9)ZYAaf@arT~jt$fN++Kd1eRJGwUEt zLaSyY;UBVpfz{Nya*ySsU>@6R;3%mocU_#8P=iFQE^oI_UA z+jH<~aRp!k2kik6wDz2hX>J#)xd0fYI#dFn$sTCkZk0ewQ;EkXTpC3A0mbbUv(*`o zBcnT3*xE}vU{aHAMjYRuZwg)THA~P@UfXLYnL{KB+z94bR0Cg}1eOUagy+_GY)fld z&&HF9$~dRe2n%cP-Bmt{a)f7m?H~D{pN{iLJJ4pp9s`q5`%Z*=W(C-VQRomrYPxdt zzsB!S7d?a0unyAzp%d9KASsiQa>yQ&v^`$o<9;vRaYO9v#W7%9ZQo;%`EmOIoZ!ZV z*{5B`f{N9QI$d!u}kFWQnU#epQW zb=wu6>9QCCU{S*73BBAydaPP>9o7mYB{5f&%r*cTaN-AHmLKYd0tYRm;RYnZ$1Sd> zE3rn(at&9lC!5&`oR$Z<46I}==bl-SD4vNCv>&U_wcs!(_igh7&V9SaN-l#U?m(-p zCiI+DU-`5?BlRbA^4|+W`5Yhgxrtq&nHiJ9bDTv(r;V=wAGvd@tZqDWJlopmS!KM*E27l?Ja<5`im1cH44_(Qgz2Le{lVyBTI=J zWXg-V#;~ZRQKO$C&(a2jO9&K#j{&Qqg1iX)Mt0~_<|NBQimJUlF?JNn@+HvTxZ-5f zWAV8ahQIN!*IZ1aZ*{X!f`Tc%pgeHUSBSl-N9}Z?#s!Jz7~Yq6^O&UqdkH4sV@NiP z-cq!N(81@Z^JQ=TDNRn;)yVtjE6yKIEo>nYs|9ru4@t%n6;^wl`Gn$GrI^hLngZg2nw0;)a@~u}Efe zTY1dR4DTX(?$~79)mXk*Bk8`?^J_;WpC6426?HP)GPvnohP&IaF?|bN+o^~kR5D$6 zj=)tfP?PLaT-6_NF0DAYf0dgeGA++&OCrvFqe4W^d z)UJC35rXQ_Z$V$T@>PMlP2Wwz#`sn^+lf@;OpD7)OWmm`9eJWQp;Jrn^25U$28@=` zW%O^nWuZC;;DjuE9^CIlDbAnsr3JRjzUgUGOVcMKn#pZ7t`~OtDppnXd6twgZ4jYS zf$AH}&xX)G>zGcXtnvBjr&m@{?*-siV7o>9iM^-olPV(JLriBMq`ijf0}Q!Tlu%lp zSf7wq3Xb)#*vN#nf`M$jy*xTA(2WKpg@ZpbL7AUoG;OPPJI74s! z0b**YX0KV2kDhHI%YEkkhXYzb^kXULx7-KQ`|Rq-O$!bflE Date: Tue, 14 May 2024 15:53:32 -0400 Subject: [PATCH 14/15] Fix the simulator worker sys path (#2561) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Fixed the simulator worker sys path. * fixed the get_new_sys_path() logic, added in unit test. * fixed isort. * Changed the _get_new_sys_path() implementation. --------- Co-authored-by: Yuan-Ting Hsieh (謝沅廷) --- .../fed/app/simulator/simulator_runner.py | 13 ++++-- .../fed/app/simulator/simulator_worker.py | 7 ++-- .../app/simulator/simulator_runner_test.py | 40 ++++++++++++++++++- 3 files changed, 50 insertions(+), 10 deletions(-) diff --git a/nvflare/private/fed/app/simulator/simulator_runner.py b/nvflare/private/fed/app/simulator/simulator_runner.py index 1d7057c295..f6d138a2a3 100644 --- a/nvflare/private/fed/app/simulator/simulator_runner.py +++ b/nvflare/private/fed/app/simulator/simulator_runner.py @@ -658,10 +658,8 @@ def do_one_task(self, client, num_of_threads, gpu, lock, timeout=60.0, task_name if gpu: command += " --gpu " + str(gpu) new_env = os.environ.copy() - if not sys.path[0]: - new_env["PYTHONPATH"] = os.pathsep.join(sys.path[1:]) - else: - new_env["PYTHONPATH"] = os.pathsep.join(sys.path) + new_env["PYTHONPATH"] = os.pathsep.join(self._get_new_sys_path()) + _ = subprocess.Popen(shlex.split(command, True), preexec_fn=os.setsid, env=new_env) conn = self._create_connection(open_port, timeout=timeout) @@ -696,6 +694,13 @@ def do_one_task(self, client, num_of_threads, gpu, lock, timeout=60.0, task_name return stop_run, next_client, end_run_client + def _get_new_sys_path(self): + new_sys_path = [] + for i in range(0, len(sys.path) - 1): + if sys.path[i]: + new_sys_path.append(sys.path[i]) + return new_sys_path + def _create_connection(self, open_port, timeout=60.0): conn = None start = time.time() diff --git a/nvflare/private/fed/app/simulator/simulator_worker.py b/nvflare/private/fed/app/simulator/simulator_worker.py index 4fc8b2d0e9..d0e3b8b371 100644 --- a/nvflare/private/fed/app/simulator/simulator_worker.py +++ b/nvflare/private/fed/app/simulator/simulator_worker.py @@ -146,9 +146,10 @@ def run(self, args, conn): client = self._create_client(args, build_ctx, deploy_args) - app_root = get_simulator_app_root(args.workspace, client.client_name) + app_root = get_simulator_app_root(args.simulator_root, client.client_name) app_custom_folder = os.path.join(app_root, "custom") - sys.path.append(app_custom_folder) + if os.path.isdir(app_custom_folder) and app_custom_folder not in sys.path: + sys.path.append(app_custom_folder) self.create_client_engine(client, deploy_args) @@ -235,8 +236,6 @@ def main(args): log_file = os.path.join(args.workspace, WorkspaceConstants.LOG_FILE_NAME) add_logfile_handler(log_file) - app_custom_folder = os.path.join(args.workspace, "custom") - sys.path.append(app_custom_folder) os.chdir(args.workspace) startup = os.path.join(args.workspace, WorkspaceConstants.STARTUP_FOLDER_NAME) os.makedirs(startup, exist_ok=True) diff --git a/tests/unit_test/private/fed/app/simulator/simulator_runner_test.py b/tests/unit_test/private/fed/app/simulator/simulator_runner_test.py index d9f0e55c8b..5b27740e03 100644 --- a/tests/unit_test/private/fed/app/simulator/simulator_runner_test.py +++ b/tests/unit_test/private/fed/app/simulator/simulator_runner_test.py @@ -11,19 +11,21 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. - +import copy import os import shutil +import sys import threading import time import uuid +from argparse import Namespace from tempfile import TemporaryDirectory from unittest.mock import Mock, patch import pytest from nvflare.apis.fl_constant import FLContextKey, MachineStatus, WorkspaceConstants -from nvflare.private.fed.app.simulator.simulator_runner import SimulatorRunner +from nvflare.private.fed.app.simulator.simulator_runner import SimulatorClientRunner, SimulatorRunner from nvflare.private.fed.utils.fed_utils import split_gpus @@ -155,3 +157,37 @@ def test_start_server_app(self, mock_deploy, mock_admin, mock_register, mock_cel runner.server.logger = Mock() runner.server.engine.asked_to_stop = True + + def test_get_new_sys_path_with_empty(self): + args = Namespace(workspace="/tmp") + args.set = [] + runner = SimulatorClientRunner(args, [], None, None, None) + old_sys_path = copy.deepcopy(sys.path) + sys.path.insert(0, "") + sys.path.append("/temp/test") + new_sys_path = runner._get_new_sys_path() + assert old_sys_path == new_sys_path + sys.path = old_sys_path + + def test_get_new_sys_path_with_multiple_empty(self): + args = Namespace(workspace="/tmp") + args.set = [] + runner = SimulatorClientRunner(args, [], None, None, None) + old_sys_path = copy.deepcopy(sys.path) + sys.path.insert(0, "") + if len(sys.path) > 2: + sys.path.insert(2, "") + sys.path.append("/temp/test") + new_sys_path = runner._get_new_sys_path() + assert old_sys_path == new_sys_path + sys.path = old_sys_path + + def test_get_new_sys_path(self): + args = Namespace(workspace="/tmp") + args.set = [] + runner = SimulatorClientRunner(args, [], None, None, None) + old_sys_path = copy.deepcopy(sys.path) + sys.path.append("/temp/test") + new_sys_path = runner._get_new_sys_path() + assert old_sys_path == new_sys_path + sys.path = old_sys_path From 70c385e0f6f10631f826ddeb408d4159c734028b Mon Sep 17 00:00:00 2001 From: Yuhong Wen Date: Wed, 15 May 2024 17:56:40 -0400 Subject: [PATCH 15/15] Moved the get_component_init_parameters to class_utils (#2578) * Moved the get_component_init_parameters to class_utils. * added docstring and unit test. --------- Co-authored-by: Holger Roth <6304754+holgerroth@users.noreply.github.com> --- nvflare/fuel/utils/class_utils.py | 25 +++++++++ nvflare/job_config/fed_job_config.py | 55 +++++++------------ .../unit_test/fuel/utils/class_utils_test.py | 49 +++++++++++++++++ 3 files changed, 95 insertions(+), 34 deletions(-) create mode 100644 tests/unit_test/fuel/utils/class_utils_test.py diff --git a/nvflare/fuel/utils/class_utils.py b/nvflare/fuel/utils/class_utils.py index 386b7582d7..ba00204cda 100644 --- a/nvflare/fuel/utils/class_utils.py +++ b/nvflare/fuel/utils/class_utils.py @@ -136,3 +136,28 @@ def get_module_name(self, class_name) -> Optional[str]: The module name if found. """ return self._class_table.get(class_name, None) + + +def _retrieve_parameters(class__, parameters): + constructor = class__.__init__ + constructor__parameters = inspect.signature(constructor).parameters + parameters.update(constructor__parameters) + if "args" in constructor__parameters.keys() and "kwargs" in constructor__parameters.keys(): + for item in class__.__bases__: + parameters.update(_retrieve_parameters(item, parameters)) + return parameters + + +def get_component_init_parameters(component): + """To retrieve the initialize parameters of an object from the class constructor. + + Args: + component: a class instance + + Returns: + + """ + class__ = component.__class__ + parameters = {} + _retrieve_parameters(class__, parameters) + return parameters diff --git a/nvflare/job_config/fed_job_config.py b/nvflare/job_config/fed_job_config.py index dc440a4941..8c37752611 100644 --- a/nvflare/job_config/fed_job_config.py +++ b/nvflare/job_config/fed_job_config.py @@ -21,6 +21,7 @@ from typing import Dict from nvflare import SimulatorRunner +from nvflare.fuel.utils.class_utils import get_component_init_parameters from nvflare.job_config.fed_app_config import FedAppConfig from nvflare.private.fed.app.fl_conf import FL_PACKAGES @@ -260,44 +261,30 @@ def _get_base_app(self, custom_dir, app, app_config): ) def _get_args(self, component, custom_dir): - parameters = self._get_init_parameters(component) - attrs = component.__dict__ args = {} - - for param in parameters: - attr_key = param if param in attrs.keys() else "_" + param - - if attr_key in ["args", "kwargs"]: - continue - - if attr_key in attrs.keys() and parameters[param].default != attrs[attr_key]: - if type(attrs[attr_key]).__name__ in dir(builtins): - args[param] = attrs[attr_key] - elif issubclass(attrs[attr_key].__class__, Enum): - args[param] = attrs[attr_key].value - else: - args[param] = { - "path": self._get_class_path(attrs[attr_key], custom_dir), - "args": self._get_args(attrs[attr_key], custom_dir), - } + if hasattr(component, "__dict__"): + parameters = get_component_init_parameters(component) + attrs = component.__dict__ + + for param in parameters: + attr_key = param if param in attrs.keys() else "_" + param + + if attr_key in ["args", "kwargs"]: + continue + + if attr_key in attrs.keys() and parameters[param].default != attrs[attr_key]: + if type(attrs[attr_key]).__name__ in dir(builtins): + args[param] = attrs[attr_key] + elif issubclass(attrs[attr_key].__class__, Enum): + args[param] = attrs[attr_key].value + else: + args[param] = { + "path": self._get_class_path(attrs[attr_key], custom_dir), + "args": self._get_args(attrs[attr_key], custom_dir), + } return args - def _get_init_parameters(self, component): - class__ = component.__class__ - parameters = {} - self._retrieve_parameters(class__, parameters) - return parameters - - def _retrieve_parameters(self, class__, parameters): - constructor = class__.__init__ - constructor__parameters = inspect.signature(constructor).parameters - parameters.update(constructor__parameters) - if "args" in constructor__parameters.keys() and "kwargs" in constructor__parameters.keys(): - for item in class__.__bases__: - parameters.update(self._retrieve_parameters(item, parameters)) - return parameters - def _get_filters(self, filters, custom_dir): r = [] for f in filters: diff --git a/tests/unit_test/fuel/utils/class_utils_test.py b/tests/unit_test/fuel/utils/class_utils_test.py new file mode 100644 index 0000000000..2f45d0c817 --- /dev/null +++ b/tests/unit_test/fuel/utils/class_utils_test.py @@ -0,0 +1,49 @@ +# Copyright (c) 2024, NVIDIA CORPORATION. All rights reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +import inspect + +from nvflare.fuel.utils.class_utils import get_component_init_parameters +from nvflare.private.fed.server.client_manager import ClientManager + + +class A: + def __init__(self, name: str = None): + self.name = name + + +class B(A): + def __init__(self, type: str = None, *args, **kwargs): + super().__init__(*args, **kwargs) + self.type = type + + +class TestClassUtils: + def test_get_component_init_parameters(self): + manager = ClientManager(project_name="Sample project", min_num_clients=1) + constructor = ClientManager.__init__ + expected_parameters = inspect.signature(constructor).parameters + parameters = get_component_init_parameters(manager) + + assert parameters == expected_parameters + + def test_nested_init_parameters(self): + expected_parameters = {} + constructor = B.__init__ + b = B(name="name", type="type") + expected_parameters.update(inspect.signature(constructor).parameters) + constructor = A.__init__ + expected_parameters.update(inspect.signature(constructor).parameters) + parameters = get_component_init_parameters(b) + + assert parameters == expected_parameters