Improve Task Runner Examples and Documentation (#943)

* Cleaning up Task Runner quickstart, and updating documentation Signed-off-by: Patrick Foley <[email protected]> * Fixing some spelling errors Signed-off-by: Patrick Foley <[email protected]> * Update docs/get_started/quickstart.rst Co-authored-by: Niroop Ammbashankar <[email protected]> * Update docs/get_started/quickstart.rst Co-authored-by: Niroop Ammbashankar <[email protected]> * Address PR feedback and fix additional examples Signed-off-by: Patrick Foley <[email protected]> * Fix lint issues Signed-off-by: Patrick Foley <[email protected]> --------- Signed-off-by: Patrick Foley <[email protected]> Co-authored-by: Niroop Ammbashankar <[email protected]>
securefederatedai · Jul 9, 2024 · 16f2604 · 16f2604
1 parent 00c428e
commit 16f2604
Show file tree

Hide file tree

Showing 20 changed files with 878 additions and 591 deletions.
diff --git a/docs/about/features_index/taskrunner.rst b/docs/about/features_index/taskrunner.rst
@@ -7,20 +7,16 @@
 Task Runner API
 ================
 
+Let's take a deeper dive into the Task Runner API. If you haven't already, we suggest checking out the :ref:`quick_start` for a primer on doing a simple experiment on a single node.
 
-An overview of this workflow is shown below.
+The steps to transition from a local experiment to a distributed federation can be understood best with the following diagram.
 
 .. figure:: ../../images/openfl_flow.png
 
-.. centered:: Overview of the Aggregator-Based Workflow
+.. centered:: Overview of a Task Runner experiment distributed across multiple nodes
+:
 
-There are two ways to run federation without Director:
-
-- `Bare Metal Approach`_
-- `Docker Approach`_
-
-
-This workflow uses short-lived components in a federation, which is terminated when the experiment is finished. The components are as follows:
+The Task Runner API uses short-lived components in a federation, which is terminated when the experiment is finished. The components are as follows:
 
 - The *Collaborator* uses a local dataset to train a global model and the *Aggregator* receives model updates from *Collaborators* and aggregates them to create the new global model.
 - The *Aggregator* is framework-agnostic, while the *Collaborator* can use any deep learning frameworks, such as `TensorFlow <https://www.tensorflow.org/>`_\* \  or `PyTorch <https://pytorch.org/>`_\*\.
@@ -504,8 +500,8 @@ In fact, the :code:`get_model()` method returns a **TaskRunner** object loaded w
 .. _running_the_federation_docker:
 
 
-Docker Approach
----------------
+Running inside Docker
+---------------------
 
 There are two ways you can run |productName| with Docker\*\.
 
@@ -571,4 +567,4 @@ Option 2: Deploy Your Workspace in a Docker Container
 
 .. toctree
 ..    overview.how_can_intel_protect_federated_learning
-..    overview.what_is_intel_federated_learning
+..    overview.what_is_intel_federated_learning
diff --git a/docs/get_started/examples.rst b/docs/get_started/examples.rst
@@ -7,29 +7,46 @@
 Examples for Running a Federation
 =================================
 
-|productName| currently offers three ways to set up and run experiments with a federation: 
-the Task Runner API, the Interactive API, and the experimental workflow interface. 
+|productName| currently offers four ways to set up and run experiments with a federation: 
+the Task Runner API, Python Native API, the Interactive API, and the Workflow API. 
+the Task Runner API is advised for production scenarios where the workload needs to be verified prior to execution, whereas the python native API provides a clean python interface on top of it intended for simulation purposes.
 The Interactive API introduces a convenient way to set up a federation and brings “long-lived” components in a federation (“Director” and “Envoy”), 
-while the Task Runner API workflow is advised for scenarios where the workload needs to be verified prior to execution. In contrast, the experimental workflow interface 
-is introduce to provide significant flexility to researchers and developers in the construction of federated learning experiments.
+while the Task Runner API workflow is advised for scenarios where the workload needs to be verified prior to execution. In contrast, the currently experimental Workflow API
+is introduced to provide significant flexility to researchers and developers in the construction of federated learning experiments.
+
+As OpenFL nears it's 2.0 release, we expect to consolidate these APIs and make the Workflow API the primary interface going forward. See our `roadmap <https://github.com/securefederatedai/openfl/blob/develop/ROADMAP.md>`_ for more details. 
 
 -------------------------
 Task Runner API
 -------------------------
-Formulate the experiment as a series of tasks, or a flow.
+Formulate the experiment as a series of tasks coordinated by a Federated Learning Plan
 
-See :ref:`taskrunner_pytorch_mnist`
+See :ref:`running_the_task_runner`
 
 .. toctree::
     :hidden:
     :maxdepth: 1
 
-    examples/taskrunner_pytorch_mnist
+    :ref:`running_the_task_runner`
+
+-------------------------
+Python Native API
+-------------------------
+Intended for quick simulation purposes
+
+See :ref:`python_native_pytorch_mnist`
+
+.. toctree::
+    :hidden:
+    :maxdepth: 1
+
+    examples/python_native_pytorch_mnist
+
 
 -------------------------
 Interactive API
 -------------------------
-Setup long-lived components to run many experiments in series.
+Setup long-lived components to run many experiments
 
 See :ref:`interactive_tensorflow_mnist`
 
@@ -55,4 +72,4 @@ See :ref:`workflowinterface_pytorch_mnist`
 
 .. note:: 
 
-    Please visit `repository <https://github.com/securefederatedai/openfl/tree/develop/openfl-tutorials>`_ for a full list of tutorials
+    Please visit `repository <https://github.com/securefederatedai/openfl/tree/develop/openfl-tutorials>`_ for a full list of tutorials
diff --git a/...ted/examples/taskrunner_pytorch_mnist.rst → .../examples/python_native_pytorch_mnist.rst b/...ted/examples/taskrunner_pytorch_mnist.rst → .../examples/python_native_pytorch_mnist.rst
@@ -1,13 +1,13 @@
 .. # Copyright (C) 2020-2023 Intel Corporation
 .. # SPDX-License-Identifier: Apache-2.0
 
-.. _taskrunner_pytorch_mnist:
+.. _python_native_pytorch_mnist:
 
 ==========================================
-Task Runner API: Federated PyTorch MNIST
+Python Native API: Federated PyTorch MNIST
 ==========================================
 
-In this tutorial, we will set up a federation and train a basic PyTorch model on the MNIST dataset using the task runner API.
+In this tutorial, we will set up a federation and train a basic PyTorch model on the MNIST dataset using the Python Native API.
 See `full notebook <https://github.com/securefederatedai/openfl/blob/f1657abe88632d542504d6d71ca961de9333913f/openfl-tutorials/Federated_Pytorch_MNIST_Tutorial.ipynb>`_.
 
 .. note::
@@ -170,4 +170,4 @@ If we want to pass in custom plan settings, we can easily do that with the overr
 .. code-block:: python 
 
     #Save final model
-    final_fl_model.save_native('final_pytorch_model')
+    final_fl_model.save_native('final_pytorch_model')