Start a guide on using TFF for FL research.

PiperOrigin-RevId: 277733805

docs/tff_for_research.md

@@ -0,0 +1,91 @@
+# Using TFF for Federated Learning Research
+
+**Note: This page is currently being populated**
+
+## Overview
+
+TFF is an extensible, powerful framework for conducting federated learning (FL)
+research by simulating federated computations on realistic proxy datasets. This
+page describes the main concepts and components that are relevant for research
+simulations, as well as detailed guidance for conducting different kinds of
+research in TFF.
+
+## The typical structure of research code in TFF
+
+A research FL simulation implemented in TFF typically consists of three main
+types of logic.
+
+1.  Individual pieces of TensorFlow code, typically `tf.function`s, that
+    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
+    [local training loop in Federated Averaging](https://github.com/tensorflow/federated/blob/master/tensorflow_federated/python/research/simple_fedavg/simple_fedavg.py#L126)
+    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_comutation`. For example, this
+    [orchestration for Federated Averaging](https://github.com/tensorflow/federated/blob/master/tensorflow_federated/python/research/simple_fedavg/simple_fedavg.py#L272).
+
+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 comptuations defined in 2. on those clients. For example,
+    [a Federated EMNIST experiment driver](https://github.com/tensorflow/federated/blob/master/tensorflow_federated/python/research/baselines/emnist/run_federated.py#L70).
+
+## Federated learning datasets
+
+TensorFlow federated
+[hosts multiple datasets](https://www.tensorflow.org/federated/api_docs/python/tff/simulation/da tasets)
+that are representative of the characteristics of real-world problems that could
+be solved with federated learning. Datasets include:
+
+*   [**StackOverflow**.](https://www.tensorflow.org/federated/api_docs/python/tff/simulation/datasets/stackoverflow/load_data)
+    A realistic text dataset for language modeling or supervised learning tasks,
+    with 342,477 unique users with 135,818,730 examples (sentences) in the
+    training set.
+
+*   [**Federated EMNIST**.](https://www.tensorflow.org/federated/api_docs/python/tff/simulation/datasets/emnist/load_data)
+    A federated pre-processing of the EMNIST character and digit dataset, where
+    each client corresponds to a different writer. The full train set contains
+    3400 users with 671,585 examples from 62 labels.
+
+*   [**Shakespeare**.](https://www.tensorflow.org/federated/api_docs/python/tff/simulation/datasets/shakespeare/load_data)
+    A smaller char-level text dataset based on the complete works of William
+    Shakespeare. The data set consists of 715 users (characters of Shakespeare
+    plays), where each example corresponds to a contiguous set of lines spoken
+    by the character in a given play.
+
+## High performance simulations
+
+<!-- TODO(b/143692319): Referent discussion in the in our paper. -->
+
+While the wall-clock time of an FL _simulation_ is not a relevant metric for
+evaluating algorithms (as simulation hardware isn't representative of real FL
+deployment environments), being able to run FL simulations quickly is critical
+for research productivity. Hence, TFF has invested heavily in providing
+high-performance single and multi-machine runtimes. Documentation is under
+development, but for now see the
+[High-performance simulations with TFF](https://github.com/tensorflow/federated/blob/master/docs/tutorials/simulations.ipynb)
+tutorial as well as instructions on
+[setting up simulations with TFF on GCP](https://github.com/tensorflow/federated/blob/master/docs/gcp_setup.md).
+For fast-single machine experiments, use
+
+```python
+tff.framework.set_default_executor(tff.framework.create_local_executor())
+```
+
+This should become the default soon.
+
+## TFF for different research areas
+
+### Federated optimization algorithms
+
+### Model and update compression
+
+### Meta-learning and multi-task learning
+
+### Differential privacy
+
+### Robustness and attacks