doc: Better introduction to tutorials

Write some better introduction for the tutorials, so users can better
understand what the expected outcome of the tutorial is.

Author: luator

docs/tutorials/grid_search.rst

@@ -2,12 +2,50 @@
 Tutorial: Basic Grid Search
 ***************************
 
-In this tutorial, we learn how to set up cluster_utils to run a basic grid search on an
-arbitrary optimization function.  It does not cover all available options but instead
-shows the minimal steps needed to get started.
+In this tutorial you will learn
+
+- how to write a simple script that can be executed by cluster-utils, and
+- how to configure cluster-utils to run a grid search over a few parameters on your
+  script.
+
+It does not cover all available options but instead shows the minimal steps needed to
+get started.
 
 --------
 
+
+What is grid search?
+====================
+
+For grid search, you specify a list of parameters and, for each of them, a list of
+values to check.  cluster-utils will then execute your script with all possible
+combinations of parameter values and collect the resulting metrics (e.g. the reward
+achieved by a policy trained with the given parameters).
+In the end, you will get an overview of the results and a list of parameter values that
+performed best with respect to your metric.
+
+In the example below, we use the Rosenbrock function::
+
+   f(x,y) = (1 - x)² + 100 · (y - x²)²
+
+For each of the two parameters ``x`` and ``y``, we will check the values ``[0.0, 0.5,
+1.0, 1.5, 2.0]``.  That is, a total of 25 jobs will be run with the following parameter
+values:
+
+.. csv-table::
+   :header-rows: 1
+
+   x,y
+   0.0,0.0
+   0.0,0.5
+   0.0,1.0
+   0.0,1.5
+   0.0,2.0
+   0.5,0.0
+   0.5,0.5
+   ...,...
+
+
 Prepare your code
 =================
 

docs/tutorials/hp_optimization.rst

@@ -2,14 +2,30 @@
 Tutorial: Basic Hyperparameter Optimization
 *******************************************
 
-In this tutorial, we learn how to set up cluster_utils to run a basic hyperparameter
-optimization on an arbitrary optimization function.  It does not cover all available
-options but instead shows the minimal steps needed to get started.
+In this tutorial, we reuse the script with the Rosenbrock function from
+:doc:`grid_search`, but instead of a simple grid search, we run a more sophisticated
+hyperparameter optimization on it.
+
+Again, this tutorial does not cover all available options but instead shows the minimal
+steps needed to get started.
 
 .. note:: If you haven't done so, please read :doc:`grid_search` first.
 
 --------
 
+
+What is hyperparameter optimization
+===================================
+
+In the previous tutorial, we used ``grid_search`` to do an exhaustive search over a
+discrete set of possible parameter values.  In this tutorial, we will use
+``hp_optimization``, which instead samples parameter values them from continuous
+distributions, based on results of previous jobs.
+
+When given enough iterations, this ideally converges towards good values for the
+hyperparameters (w.r.t. to the metric you specified).
+
+
 Prepare your code
 =================
 

docs/usage.rst

@@ -5,6 +5,11 @@ Usage
 Run Batch of Jobs
 =================
 
+.. note::
+
+   If you are new to cluster_utils, we recommend that you start with
+   :doc:`tutorials/grid_search`.
+
 cluster_utils provides two main commands to run batches of jobs on the cluster:
 
 - ``grid_search``:  Simple grid search over specified parameter ranges.