Move the examples folder to the root of the repository.

PiperOrigin-RevId: 622215249

docs/design/package_structure_overview.dot

@@ -5,7 +5,7 @@ digraph {
 
   subgraph cluster_users {
     research [href="https://github.com/google-research/federated/blob/master" target="_parent", fillcolor="#E2F3EB", color="#57BB8A"]
-    examples [href="https://github.com/tensorflow/federated/blob/main/tensorflow_federated/examples" target="_parent", fillcolor="#E2F3EB", color="#57BB8A"]
+    examples [href="https://github.com/tensorflow/federated/blob/main/examples" target="_parent", fillcolor="#E2F3EB", color="#57BB8A"]
     tests [href="https://github.com/tensorflow/federated/blob/main/tensorflow_federated/python/tests" target="_parent", fillcolor="#E2F3EB", color="#57BB8A"]
   }
 

docs/program/federated_program.md

@@ -7,7 +7,7 @@ especially its type system.
 For more information about federated program, see:
 
 *   [API Documentation](https://www.tensorflow.org/federated/api_docs/python/tff/program)
-*   [Examples](https://github.com/tensorflow/federated/blob/main/tensorflow_federated/examples/program)
+*   [Examples](https://github.com/tensorflow/federated/blob/main/examples/program)
 *   [Developer Guide](https://github.com/tensorflow/federated/blob/main/docs/program/guide.md)
 
 [TOC]

docs/program/guide.md

@@ -16,7 +16,7 @@ This section defines guidelines for how
 should be authored.
 
 See the example
-[program_logic.py](https://github.com/tensorflow/federated/blob/main/tensorflow_federated/examples/program/program_logic.py)
+[program_logic.py](https://github.com/tensorflow/federated/blob/main/examples/program/program_logic.py)
 for more information.
 
 ### Document Type Signatures
@@ -213,7 +213,7 @@ def program_logic(...) -> None:
 ### Tests
 
 **Do** provide unit tests for the program logic (e.g.
-[program_logic_test.py](https://github.com/tensorflow/federated/blob/main/tensorflow_federated/examples/program/program_logic_test.py)).
+[program_logic_test.py](https://github.com/tensorflow/federated/blob/main/examples/program/program_logic_test.py)).
 
 ## Program
 
@@ -222,14 +222,14 @@ This section defines guidelines for how a
 should be authored.
 
 See the example
-[program.py](https://github.com/tensorflow/federated/blob/main/tensorflow_federated/examples/program/program.py)
+[program.py](https://github.com/tensorflow/federated/blob/main/examples/program/program.py)
 for more information.
 
 ### Document the Program
 
 **Do** document the details of the program to the customer in the docstring of
 the module (e.g.
-[program.py](https://github.com/tensorflow/federated/blob/main/tensorflow_federated/examples/program/program.py)):
+[program.py](https://github.com/tensorflow/federated/blob/main/examples/program/program.py)):
 
 *   How to manually run the program.
 *   What platform, computations, and data sources are used in the program.

docs/tff_for_research.md

@@ -21,20 +21,20 @@ types of logic.
     encapsulate logic that runs in a single location (e.g., on clients or on a
     server). This code is typically written and tested without any `tff.*`
     references, and can be re-used outside of TFF. For example, the
-    [client training loop in Federated Averaging](https://github.com/tensorflow/federated/blob/main/tensorflow_federated/examples/simple_fedavg/simple_fedavg_tf.py#L184-L222)
+    [client training loop in Federated Averaging](https://github.com/tensorflow/federated/blob/main/examples/simple_fedavg/simple_fedavg_tf.py#L184-L222)
     is implemented at this level.
 
 1.  TensorFlow Federated orchestration logic, which binds together the
     individual `tf.function`s from 1. by wrapping them as `tff.tf_computation`s
     and then orchestrating them using abstractions like
     `tff.federated_broadcast` and `tff.federated_mean` inside a
     `tff.federated_computation`. See, for example, this
-    [orchestration for Federated Averaging](https://github.com/tensorflow/federated/blob/main/tensorflow_federated/examples/simple_fedavg/simple_fedavg_tff.py#L112-L140).
+    [orchestration for Federated Averaging](https://github.com/tensorflow/federated/blob/main/examples/simple_fedavg/simple_fedavg_tff.py#L112-L140).
 
 1.  An outer driver script that simulates the control logic of a production FL
     system, selecting simulated clients from a dataset and then executing
     federated computations defined in 2. on those clients. For example,
-    [a Federated EMNIST experiment driver](https://github.com/tensorflow/federated/blob/main/tensorflow_federated/examples/simple_fedavg/emnist_fedavg_main.py).
+    [a Federated EMNIST experiment driver](https://github.com/tensorflow/federated/blob/main/examples/simple_fedavg/emnist_fedavg_main.py).
 
 ## Federated learning datasets
 
@@ -114,17 +114,17 @@ TFF, depending on the desired level of customization.
 
 A minimal stand-alone implementation of the
 [Federated Averaging](https://arxiv.org/abs/1602.05629) algorithm is provided
-[here](https://github.com/tensorflow/federated/blob/main/tensorflow_federated/examples/simple_fedavg).
+[here](https://github.com/tensorflow/federated/blob/main/examples/simple_fedavg).
 The code includes
-[TF functions](https://github.com/tensorflow/federated/blob/main/tensorflow_federated/examples/simple_fedavg/simple_fedavg_tf.py)
+[TF functions](https://github.com/tensorflow/federated/blob/main/examples/simple_fedavg/simple_fedavg_tf.py)
 for local computation,
-[TFF computations](https://github.com/tensorflow/federated/blob/main/tensorflow_federated/examples/simple_fedavg/simple_fedavg_tff.py)
+[TFF computations](https://github.com/tensorflow/federated/blob/main/examples/simple_fedavg/simple_fedavg_tff.py)
 for orchestration, and a
-[driver script](https://github.com/tensorflow/federated/blob/main/tensorflow_federated/examples/simple_fedavg/emnist_fedavg_main.py)
+[driver script](https://github.com/tensorflow/federated/blob/main/examples/simple_fedavg/emnist_fedavg_main.py)
 on the EMNIST dataset as an example. These files can easily be adapted for
 customized applciations and algorithmic changes following detailed instructions
 in the
-[README](https://github.com/tensorflow/federated/blob/main/tensorflow_federated/examples/simple_fedavg/README.md).
+[README](https://github.com/tensorflow/federated/blob/main/examples/simple_fedavg/README.md).
 
 A more general implementation of Federated Averaging can be found
 [here](https://github.com/tensorflow/federated/blob/main/tensorflow_federated/python/learning/algorithms/fed_avg.py).
@@ -218,13 +218,13 @@ One approach is to let each client fine-tune a single global model (trained
 using federated learning) with their local data. This approach has connections
 to meta-learning, see, e.g., [this paper](https://arxiv.org/abs/1909.12488). An
 example of this approach is given in
-[`emnist_p13n_main.py`](https://github.com/tensorflow/federated/blob/main/tensorflow_federated/examples/personalization/emnist_p13n_main.py).
+[`emnist_p13n_main.py`](https://github.com/tensorflow/federated/blob/main/examples/personalization/emnist_p13n_main.py).
 To explore and compare different personalization strategies, you can:
 
 *   Define a personalization strategy by implementing a `tf.function` that
     starts from an initial model, trains and evaluates a personalized model
     using each client's local datasets. An example is given by
-    [`build_personalize_fn`](https://github.com/tensorflow/federated/blob/main/tensorflow_federated/examples/personalization/p13n_utils.py).
+    [`build_personalize_fn`](https://github.com/tensorflow/federated/blob/main/examples/personalization/p13n_utils.py).
 
 *   Define an `OrderedDict` that maps strategy names to the corresponding
     personalization strategies, and use it as the `personalize_fn_dict` argument

docs/tutorials/custom_federated_algorithm_with_tff_optimizers.ipynb

@@ -61,7 +61,7 @@
       "source": [
         "# Use TFF optimizers in custom iterative process\n",
         "\n",
-        "This is an alternative to the [Build Your Own Federated Learning Algorithm](building_your_own_federated_learning_algorithm.ipynb) tutorial and the [simple_fedavg](https://github.com/tensorflow/federated/tree/main/tensorflow_federated/examples/simple_fedavg) example to build a custom iterative process for the [federated averaging](https://arxiv.org/abs/1602.05629) algorithm. This tutorial will use [TFF optimizers](https://github.com/tensorflow/federated/tree/main/tensorflow_federated/python/learning/optimizers) instead of Keras optimizers.\n",
+        "This is an alternative to the [Build Your Own Federated Learning Algorithm](building_your_own_federated_learning_algorithm.ipynb) tutorial and the [simple_fedavg](https://github.com/tensorflow/federated/tree/main/examples/simple_fedavg) example to build a custom iterative process for the [federated averaging](https://arxiv.org/abs/1602.05629) algorithm. This tutorial will use [TFF optimizers](https://github.com/tensorflow/federated/tree/main/tensorflow_federated/python/learning/optimizers) instead of Keras optimizers.\n",
         "The TFF optimizer abstraction is desgined to be state-in-state-out to be easier to be incorporated in a TFF iterative process. The `tff.learning` APIs also accept TFF optimizers as input argument."
       ]
     },
@@ -124,7 +124,7 @@
       },
       "source": [
         "## Preparing data and model\n",
-        "The EMNIST data processing and model are very similar to the [simple_fedavg](https://github.com/tensorflow/federated/tree/main/tensorflow_federated/examples/simple_fedavg) example."
+        "The EMNIST data processing and model are very similar to the [simple_fedavg](https://github.com/tensorflow/federated/tree/main/examples/simple_fedavg) example."
       ]
     },
     {

docs/tutorials/random_noise_generation.ipynb

@@ -575,7 +575,7 @@
         "id": "x9kc6G0RIATV"
       },
       "source": [
-        "Now let us use the helper class and `tf.random.stateless_normal` to generate (nested structure of) random noise in TFF. The following code snippet looks a lot like a TFF iterative process, see [simple_fedavg](https://github.com/tensorflow/federated/blob/main/tensorflow_federated/examples/simple_fedavg/simple_fedavg_tff.py) as an example of expressing federated learning algorithm as TFF iterative process. The pseudo seed state here for random noise generation is `tf.Tensor` that can be easily transported in TFF and TF functions."
+        "Now let us use the helper class and `tf.random.stateless_normal` to generate (nested structure of) random noise in TFF. The following code snippet looks a lot like a TFF iterative process, see [simple_fedavg](https://github.com/tensorflow/federated/blob/main/examples/simple_fedavg/simple_fedavg_tff.py) as an example of expressing federated learning algorithm as TFF iterative process. The pseudo seed state here for random noise generation is `tf.Tensor` that can be easily transported in TFF and TF functions."
       ]
     },
     {

docs/tutorials/simulations_with_accelerators.ipynb

@@ -227,7 +227,7 @@
         "id": "QJZh5NoiG-hR"
       },
       "source": [
-        "We define a function preprocessing the EMNIST example following the [simple_fedavg](https://github.com/tensorflow/federated/tree/main/tensorflow_federated/examples/simple_fedavg) example. Note that the argument `client_epochs_per_round` controls the number of local epochs on clients in federated learning. "
+        "We define a function preprocessing the EMNIST example following the [simple_fedavg](https://github.com/tensorflow/federated/tree/main/examples/simple_fedavg) example. Note that the argument `client_epochs_per_round` controls the number of local epochs on clients in federated learning. "
       ]
     },
     {
@@ -342,7 +342,7 @@
         "id": "8OGBU1SLpyiR"
       },
       "source": [
-        "Now let us define the training loop for EMNIST. Note that `use_experimental_simulation_loop=True` in `tff.learning.algorithms.build_weighted_fed_avg` is suggested for performant TFF simulation, and required to take advantage of multi-GPUs on a single machine. See [simple_fedavg](https://github.com/tensorflow/federated/tree/main/tensorflow_federated/examples/simple_fedavg) example for how to define customized federated learning algorithm that has high performance on GPUs, one of the key features is to explicitly use `for ... iter(dataset)` for training loops. "
+        "Now let us define the training loop for EMNIST. Note that `use_experimental_simulation_loop=True` in `tff.learning.algorithms.build_weighted_fed_avg` is suggested for performant TFF simulation, and required to take advantage of multi-GPUs on a single machine. See [simple_fedavg](https://github.com/tensorflow/federated/tree/main/examples/simple_fedavg) example for how to define customized federated learning algorithm that has high performance on GPUs, one of the key features is to explicitly use `for ... iter(dataset)` for training loops. "
       ]
     },
     {

tensorflow_federated/examples/learning/federated_program/vizier/program.py → examples/learning/federated_program/vizier/program.py

@@ -36,9 +36,9 @@
 from vizier import pyvizier
 from vizier.client import client_abc
 
-from tensorflow_federated.examples.learning.federated_program.vizier import data_sources
-from tensorflow_federated.examples.learning.federated_program.vizier import learning_process
-from tensorflow_federated.examples.learning.federated_program.vizier import vizier_service
+from exampleslearning.federated_program.vizier import data_sources
+from exampleslearning.federated_program.vizier import learning_process
+from exampleslearning.federated_program.vizier import vizier_service
 
 
 _TOTAL_ROUNDS = 2

tensorflow_federated/examples/learning/federated_program/vizier/vizier_service_test.py → examples/learning/federated_program/vizier/vizier_service_test.py

@@ -17,7 +17,7 @@
 
 from absl.testing import absltest
 
-from tensorflow_federated.examples.learning.federated_program.vizier import vizier_service
+from exampleslearning.federated_program.vizier import vizier_service
 
 from vizier.service import clients
 from vizier.service import pyvizier

tensorflow_federated/examples/personalization/README.md → examples/personalization/README.md

@@ -39,7 +39,7 @@ an unbatched `tf.data.Dataset` for test, and an extra `context` object, trains a
 personalized model, and returns the evaluation metrics. Users can define
 whatever personalization strategies they like. An example of fine-tuning based
 personalization strategy is given by `build_personalize_fn` in
-[`p13n_utils`](https://github.com/tensorflow/federated/blob/main/tensorflow_federated/examples/personalization/p13n_utils.py).
+[`p13n_utils`](https://github.com/tensorflow/federated/blob/main/examples/personalization/p13n_utils.py).
 
 The
 [`tff.learning.build_personalization_eval_computation`](https://www.tensorflow.org/federated/api_docs/python/tff/learning/build_personalization_eval_computation)
@@ -49,7 +49,7 @@ time, starting from the same global model. Specifically, users define a
 and then pass it to the API as the `personalize_fn_dict` argument.
 
 In
-[our experiment](https://github.com/tensorflow/federated/blob/main/tensorflow_federated/examples/personalization/emnist_p13n_main.py),
+[our experiment](https://github.com/tensorflow/federated/blob/main/examples/personalization/emnist_p13n_main.py),
 we define and evaluate two fine-tuning based personalization strategies: one
 uses SGD and other other uses Adam optimizer.
 
@@ -60,7 +60,7 @@ The
 API has an argument `max_num_samples` with a default value 100. Metrics from at
 most `max_num_samples` clients (the clients are sampled without replacement)
 will be collected and returned. In
-[our experiment](https://github.com/tensorflow/federated/blob/main/tensorflow_federated/examples/personalization/emnist_p13n_main.py),
+[our experiment](https://github.com/tensorflow/federated/blob/main/examples/personalization/emnist_p13n_main.py),
 we set this value to be larger than the number of clients in the federated
 dataset, which means that metrics from all clients will be returned.
 
@@ -70,7 +70,7 @@ strategy names to the evaluation metrics of the corresponding personalization
 strategies. Each returned metric contains a list of scalars (each scalar comes
 from one sampled client). Metric values at the same position, e.g.,
 `metric_1[i]`, `metric_2[i]`, ..., corresponds to the same client. In
-[our experiment](https://github.com/tensorflow/federated/blob/main/tensorflow_federated/examples/personalization/emnist_p13n_main.py),
+[our experiment](https://github.com/tensorflow/federated/blob/main/examples/personalization/emnist_p13n_main.py),
 the baseline evaluation function is given by `evaluate_fn` in
-[`p13n_utils`](https://github.com/tensorflow/federated/blob/main/tensorflow_federated/examples/personalization/p13n_utils.py),
+[`p13n_utils`](https://github.com/tensorflow/federated/blob/main/examples/personalization/p13n_utils.py),
 which is the same evaluation function used by the personalization strategies.

tensorflow_federated/examples/personalization/emnist_p13n_main.py → examples/personalization/emnist_p13n_main.py

@@ -21,8 +21,8 @@
 import tensorflow as tf
 import tensorflow_federated as tff
 
-from tensorflow_federated.examples.personalization.p13n_utils import build_personalize_fn
-from tensorflow_federated.examples.personalization.p13n_utils import evaluate_fn
+from examplespersonalization.p13n_utils import build_personalize_fn
+from examplespersonalization.p13n_utils import evaluate_fn
 
 
 def _get_emnist_datasets() -> (

tensorflow_federated/examples/personalization/p13n_utils_test.py → examples/personalization/p13n_utils_test.py

@@ -18,7 +18,7 @@
 import tensorflow as tf
 import tensorflow_federated as tff
 
-from tensorflow_federated.examples.personalization import p13n_utils
+from examplespersonalization import p13n_utils
 
 _INPUT_DIM = 2
 _OUTPUT_DIM = 1

tensorflow_federated/examples/program/program.py → examples/program/program.py

@@ -55,8 +55,8 @@
 import tensorflow as tf
 import tensorflow_federated as tff
 
-from tensorflow_federated.examples.program import computations
-from tensorflow_federated.examples.program import program_logic
+from examplesprogram import computations
+from examplesprogram import program_logic
 
 _OUTPUT_DIR = flags.DEFINE_string('output_dir', None, 'The output path.')
 

tensorflow_federated/examples/program/program_logic_test.py → examples/program/program_logic_test.py

@@ -24,8 +24,8 @@
 import tensorflow as tf
 import tensorflow_federated as tff
 
-from tensorflow_federated.examples.program import computations
-from tensorflow_federated.examples.program import program_logic
+from examplesprogram import computations
+from examplesprogram import program_logic
 
 
 def _create_native_federated_context():