[doc] Hyperparameter Tuning Gallery Entry (#5786)

* mod_table

* Example fix for gallery

* lint

* nit

* nit

* fix

* gallery

* remove table for now

* training, object store, tune, actors, advanced

* start tf code

* first cut tf

* yapf

* pytorch

* add torch example

* torch

* parallel

* tune

* tuning

* reviewsready

* finetune

* fix

* move_code

* update conf

* compile

* init hyperparameter

* Start images

* overview

* extra

* fix

* works

* update-ps-example

* param_actor

* fix

* examples

* simple

* simplify_pong

* flake8 and run hyperopt

* add comments

* add comments

* add suggestion

* add suggestion

* suggestions

* add suggestion

* add suggestions

* fixed in wrong area

* last edit

* finish changes

* add line

* hyperparameter

doc/examples/plot_hyperparameter.py

@@ -14,6 +14,11 @@ their results to be ready.
     tuning library built using Ray's Actor API.
 
 .. _`Tune`: https://ray.readthedocs.io/en/latest/tune.html
+
+Setup: Dependencies
+-------------------
+First, import some dependencies and define functions to generate
+random hyperparameters and retrieve data.
 """
 import os
 import numpy as np
@@ -65,6 +70,13 @@ def get_data_loaders(batch_size):
         shuffle=True)
     return train_loader, test_loader
 
+#######################################################################
+# Setup: Defining the Neural Network
+# ----------------------------------
+#
+# We define a small neural network to use in training. In addition,
+# we created methods to train and test this neural network.
+
 
 class ConvNet(nn.Module):
     """Simple two layer Convolutional Neural Network."""
@@ -118,6 +130,16 @@ def test(model, test_loader, device=torch.device("cpu")):
 
     return correct / total
 
+#######################################################################
+# Evaluating the Hyperparameters
+# -------------------------------
+#
+# For a given configuration, the neural network created previously
+# will be trained and return the accuracy of the model. These trained
+# networks will then be tested for accuracy to find the best set of
+# hyperparameters.
+#
+# The ``@ray.remote`` decorator defines a remote process.
 
 @ray.remote
 def evaluate_hyperparameters(config):
@@ -130,6 +152,13 @@ def evaluate_hyperparameters(config):
     train(model, optimizer, train_loader)
     return test(model, test_loader)
 
+#######################################################################
+# Synchronous Evaluation of Randomly Generated Hyperparameters
+# ------------------------------------------------------------
+#
+# We will create multiple sets of random hyperparameters for our neural
+# network that will be evaluated in parallel.
+
 
 # Keep track of the best hyperparameters and the best accuracy.
 best_hyperparameters = None
@@ -141,13 +170,23 @@ remaining_ids = []
 # hyerparameters used for that experiment.
 hyperparameters_mapping = {}
 
-# Randomly generate sets of hyperparameters and launch a task to test each set.
+###########################################################################
+# Launch asynchronous parallel tasks for evaluating different
+# hyperparameters. ``accuracy_id`` is an ObjectID that acts as a handle to
+# the remote task. It is used later to fetch the result of the task
+# when the task finishes.
+
+# Randomly generate sets of hyperparameters and launch a task to evaluate it.
 for i in range(num_evaluations):
     hyperparameters = generate_hyperparameters()
     accuracy_id = evaluate_hyperparameters.remote(hyperparameters)
     remaining_ids.append(accuracy_id)
     hyperparameters_mapping[accuracy_id] = hyperparameters
 
+###########################################################################
+# Process each hyperparameter and corresponding accuracy in the order that
+# they finish to store the hyperparameters with the best accuracy.
+
 # Fetch and print the results of the tasks in the order that they complete.
 while remaining_ids:
     # Use ray.wait to get the object ID of the first task that completes.