@@ -448,22 +448,22 @@

    "cell_type": "markdown",

    "metadata": {},

    "source": [

-    "# Custom point choosing logic for 1D and 2D"

+    "# Custom adaptive logic for 1D and 2D"

    ]

   },

   {

    "cell_type": "markdown",

    "metadata": {},

    "source": [

-    "The `Learner1D` and `Learner2D` implement a certain logic for chosing points based on the existing data.\n",

+    "`Learner1D` and `Learner2D` both work on the principle of subdividing their domain into subdomains, and assigning a property to each subdomain, which we call the *loss*. The algorithm for choosing the best place to evaluate our function is then simply *take the subdomain with the largest loss and add a point in the center, creating new subdomains around this point*. \n",

     "\n",

-    "For some functions this default stratagy might not work, for example you'll run into trouble when you learn functions that contain divergencies.\n",

+    "The *loss function* that defines the loss per subdomain is the canonical place to define what regions of the domain are \"interesting\".\n",

+    "The default loss function for `Learner1D` and `Learner2D` is sufficient for a wide range of common cases, but it is by no means a panacea. For example, the default loss function will tend to get stuck on divergences.\n",

     "\n",

-    "Both the `Learner1D` and `Learner2D` allow you to use a custom loss function, which you specify as an argument in the learner. See the doc-string of `Learner1D` and `Learner2D` to see what `loss_per_interval` and `loss_per_triangle` need to return and take as input.\n",

+    "Both the `Learner1D` and `Learner2D` allow you to specify a *custom loss function*. Below we illustrate how you would go about writing your own loss function. The documentation for `Learner1D` and `Learner2D` specifies the signature that your loss function needs to have in order for it to work with `adaptive`.\n",

     "\n",

-    "As an example we implement a homogeneous sampling strategy (which of course is not the best way of handling divergencies).\n",

     "\n",

-    "Note that both these loss functions are also available from `adaptive.learner.learner1d.uniform_sampling` and `adaptive.learner.learner2d.uniform_sampling`."

+    "Say we want to properly sample a function that contains divergences. A simple (but naive) strategy is to *uniformly* sample the domain:\n"

    ]

   },

   {

@@ -473,6 +473,7 @@

    "outputs": [],

    "source": [

     "def uniform_sampling_1d(interval, scale, function_values):\n",

+    "    # Note that we never use 'function_values'; the loss is just the size of the subdomain\n",

     "    x_left, x_right = interval\n",

     "    x_scale, _ = scale\n",

     "    dx = (x_right - x_left) / x_scale\n",

@@ -492,7 +493,9 @@

    "metadata": {},

    "outputs": [],

    "source": [

-    "%%opts EdgePaths (color='w')\n",

+    "%%opts EdgePaths (color='w') Image [logz=True]\n",

+    "\n",

+    "from adaptive.runner import SequentialExecutor\n",

     "\n",

     "def uniform_sampling_2d(ip):\n",

     "    from adaptive.learner.learner2D import areas\n",

@@ -504,18 +507,32 @@

     "    return 1 / (x**2 + y**2)\n",

     "\n",

     "learner = adaptive.Learner2D(f_divergent_2d, [(-1, 1), (-1, 1)], loss_per_triangle=uniform_sampling_2d)\n",

-    "runner = adaptive.BlockingRunner(learner, goal=lambda l: l.loss() < 0.02)\n",

-    "learner.plot(tri_alpha=0.3)"

+    "\n",

+    "# this takes a while, so use the async Runner so we know *something* is happening\n",

+    "runner = adaptive.Runner(learner, goal=lambda l: l.loss() < 0.02)\n",

+    "runner.live_info()\n",

+    "runner.live_plot(update_interval=0.2,\n",

+    "                 plotter=lambda l: l.plot(tri_alpha=0.3).relabel('1 / (x^2 + y^2) in log scale'))"

+   ]

+  },

+  {

+   "cell_type": "markdown",

+   "metadata": {},

+   "source": [

+    "The uniform sampling strategy is a common case to benchmark against, so the 1D and 2D versions are included in `adaptive` as `adaptive.learner.learner1D.uniform_sampling` and `adaptive.learner.learner2D.uniform_sampling`."

    ]

   },

   {

    "cell_type": "markdown",

    "metadata": {},

    "source": [

-    "#### Doing better\n",

-    "Of course we can improve on the the above result, since just homogeneous sampling is usually the dumbest way to sample.\n",

+    "### Doing better\n",

+    "\n",

+    "Of course, using `adaptive` for uniform sampling is a bit of a waste!\n",

+    "\n",

+    "Let's see if we can do a bit better. Below we define a loss per subdomain that scales with the degree of nonlinearity of the function (this is very similar to the default loss function for `Learner2D`), but which is 0 for subdomains smaller than a certain area, and infinite for subdomains larger than a certain area.\n",

     "\n",

-    "The loss function (slightly more general version) below is available as `adaptive.learner.learner2D.resolution_loss`."

+    "A loss defined in this way means that the adaptive algorithm will first prioritise subdomains that are too large (infinite loss). After all subdomains are appropriately small it will prioritise places where the function is very nonlinear, but will ignore subdomains that are too small (0 loss)."

    ]

   },

   {

@@ -529,13 +546,17 @@

     "def resolution_loss(ip, min_distance=0, max_distance=1):\n",

     "    \"\"\"min_distance and max_distance should be in between 0 and 1\n",

     "    because the total area is normalized to 1.\"\"\"\n",

+    "\n",

     "    from adaptive.learner.learner2D import areas, deviations\n",

+    "\n",

     "    A = areas(ip)\n",

     "\n",

-    "    # `deviations` returns an array of the same length as the\n",

-    "    # vector your function to be learned returns, so 1 in this case.\n",

-    "    # Its value represents the deviation from the linear estimate based\n",

-    "    # on the gradients inside each triangle.\n",

+    "    # 'deviations' returns an array of shape '(n, len(ip))', where\n",

+    "    # 'n' is the  is the dimension of the output of the learned function\n",

+    "    # In this case we know that the learned function returns a scalar,\n",

+    "    # so 'deviations' returns an array of shape '(1, len(ip))'.\n",

+    "    # It represents the deviation of the function value from a linear estimate\n",

+    "    # over each triangular subdomain.\n",

     "    dev = deviations(ip)[0]\n",

     "    \n",

     "    # we add terms of the same dimension: dev == [distance], A == [distance**2]\n",

@@ -556,6 +577,15 @@

     "learner.plot(tri_alpha=0.3).relabel('1 / (x^2 + y^2) in log scale')"

    ]

   },

+  {

+   "cell_type": "markdown",

+   "metadata": {},

+   "source": [

+    "Awesome! We zoom in on the singularity, but not at the expense of sampling the rest of the domain a reasonable amount.\n",

+    "\n",

+    "The above strategy is available as `adaptive.learner.learner2D.resolution_loss`."

+   ]

+  },

   {

    "cell_type": "markdown",

    "metadata": {},