@@ -15,11 +15,19 @@

     "\n",

     "This is an introductory notebook that shows some basic use cases.\n",

     "\n",

-    "`adaptive` needs the following packages:\n",

+    "`adaptive` needs at least Python 3.6, and the following packages:\n",

     "\n",

-    "+ Python 3.6\n",

+    "+ `scipy`\n",

+    "+ `sortedcontainers`\n",

+    "\n",

+    "Additionally `adaptive` has lots of extra functionality that makes it simple to use from Jupyter notebooks.\n",

+    "This extra functionality depends on the following packages\n",

+    "\n",

+    "+ `ipykernel>=4.8.0`\n",

+    "+ `jupyter_client>=5.2.2`\n",

     "+ `holoviews`\n",

-    "+ `bokeh`"

+    "+ `bokeh`\n",

+    "+ `ipywidgets`"

    ]

   },

   {

@@ -105,7 +113,7 @@

    "source": [

     "# The end condition is when the \"loss\" is less than 0.1. In the context of the\n",

     "# 1D learner this means that we will resolve features in 'func' with width 0.1 or wider.\n",

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

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

     "runner.live_info()"

    ]

   },

@@ -222,12 +230,16 @@

    "outputs": [],

    "source": [

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

+    "\n",

     "import itertools\n",

+    "\n",

+    "# Create a learner and add data on homogeneous grid, so that we can plot it\n",

     "learner2 = adaptive.Learner2D(ring, bounds=learner.bounds)\n",

     "n = int(learner.npoints**0.5)\n",

     "xs, ys = [np.linspace(*bounds, n) for bounds in learner.bounds]\n",

     "xys = list(itertools.product(xs, ys))\n",

     "learner2.add_data(xys, map(partial(ring, wait=False), xys))\n",

+    "\n",

     "(learner2.plot(n).relabel('Homogeneous grid') + learner.plot().relabel('With adaptive') + \n",

     " learner2.plot(n, tri_alpha=0.4) + learner.plot(tri_alpha=0.4)).cols(2)"

    ]

@@ -258,7 +270,7 @@

     "def g(n):\n",

     "    import random\n",

     "    from time import sleep\n",

-    "    sleep(random.random() / 5)\n",

+    "    sleep(random.random() / 1000)\n",

     "    # Properly save and restore the RNG state\n",

     "    state = random.getstate()\n",

     "    random.seed(n)\n",

@@ -274,7 +286,7 @@

    "outputs": [],

    "source": [

     "learner = adaptive.AverageLearner(g, atol=None, rtol=0.01)\n",

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

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

     "runner.live_info()"

    ]

   },

@@ -284,7 +296,7 @@

    "metadata": {},

    "outputs": [],

    "source": [

-    "runner.live_plot()"

+    "runner.live_plot(update_interval=0.1)"

    ]

   },

   {

@@ -347,7 +359,11 @@

    "outputs": [],

    "source": [

     "from adaptive.runner import SequentialExecutor\n",

+    "\n",

     "learner = adaptive.IntegratorLearner(f24, bounds=(0, 3), tol=1e-10)\n",

+    "\n",

+    "# We use a SequentialExecutor, which runs the function to be learned in *this* process only. This means we don't pay\n",

+    "# the overhead of evaluating the function in another process.\n",

     "runner = adaptive.Runner(learner, executor=SequentialExecutor(), goal=lambda l: l.done())\n",

     "runner.live_info()"

    ]

@@ -390,7 +406,7 @@

    "cell_type": "markdown",

    "metadata": {},

    "source": [

-    "Some 1D functions return multiple numbers, such as the following function:"

+    "Sometimes you may want to learn a function with vector output:"

    ]

   },

   {

@@ -401,6 +417,8 @@

    "source": [

     "random.seed(0)\n",

     "offsets = [random.uniform(-0.8, 0.8) for _ in range(3)]\n",

+    "\n",

+    "# sharp peaks at random locations in the domain\n",

     "def f_levels(x, offsets=offsets):\n",

     "    a = 0.01\n",

     "    return np.array([offset + x + a**2 / (a**2 + (x - offset)**2)\n",

@@ -411,7 +429,7 @@

    "cell_type": "markdown",

    "metadata": {},

    "source": [

-    "This is again a function with sharp peaks at different x-values and with different constant backgrounds. To learn this function we can use a `Learner1D` as well."

+    "`adaptive` has you covered! The `Learner1D` can be used for such functions:"

    ]

   },

   {

@@ -420,25 +438,8 @@

    "metadata": {},

    "outputs": [],

    "source": [

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

-    "\n",

     "learner = adaptive.Learner1D(f_levels, bounds=(-1, 1))\n",

-    "runner = adaptive.Runner(learner, executor=SequentialExecutor(), goal=lambda l: l.loss() < 0.05)"

-   ]

-  },

-  {

-   "cell_type": "markdown",

-   "metadata": {},

-   "source": [

-    "In the plot below we see that the function gets more densely sampled around the peaks, which is the behaviour we want."

-   ]

-  },

-  {

-   "cell_type": "code",

-   "execution_count": null,

-   "metadata": {},

-   "outputs": [],

-   "source": [

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

     "runner.live_plot()"

    ]

   },

@@ -453,7 +454,7 @@

    "cell_type": "markdown",

    "metadata": {},

    "source": [

-    "The balancing learner is a \"meta-learner\" that takes a list of multiple leaners. The runner wil find find out which points of which child learner will improve the loss the most and send those to the executor.\n",

+    "The balancing learner is a \"meta-learner\" that takes a list of learners. When you request a point from the balancing learner, it will query all of its \"children\" to figure out which one will give the most improvement.\n",

     "\n",

     "The balancing learner can for example be used to implement a poor-man's 2D learner by using the `Learner1D`."

    ]

@@ -483,7 +484,7 @@

    "outputs": [],

    "source": [

     "plotter = lambda learner: hv.Overlay([L.plot() for L in learner.learners])\n",

-    "runner.live_plot(plotter=plotter)"

+    "runner.live_plot(plotter=plotter, update_interval=0.1)"

    ]

   },

   {

@@ -497,11 +498,9 @@

    "cell_type": "markdown",

    "metadata": {},

    "source": [

-    "Sometimes we want to learn functions that do not only return a single `float`, but instead return multiple values (even though we only want to learn one value.)\n",

+    "If the function that you want to learn returns a value along with some metadata, you can wrap your learner in an `adaptive.DataSaver`.\n",

     "\n",

-    "We can wrap our learners with a `adaptive.DataSaver` such that the learner will be able to handle functions that return results.\n",

-    "\n",

-    "Take for example this function where we want to remember the time that every point took:"

+    "In the following example the function to be learned returns its result and the execution time in a dictionary:"

    ]

   },

   {

@@ -523,11 +522,11 @@

     "    y = x + a**2 / (a**2 + x**2)\n",

     "    return {'y': y, 'waiting_time': waiting_time}\n",

     "\n",

-    "# Create the learner with the function that returns a `dict`\n",

-    "# Note that this learner cannot be passed to a runner.\n",

+    "# Create the learner with the function that returns a 'dict'\n",

+    "# This learner cannot be run directly, as Learner1D does not know what to do with the 'dict'\n",

     "_learner = adaptive.Learner1D(f_dict, bounds=(-1, 1))\n",

     "\n",

-    "# Wrap the learner in the `DataSavingLearner` and tell it which key it needs to learn\n",

+    "# Wrapping the learner with 'adaptive.DataSaver' and tell it which key it needs to learn\n",

     "learner = adaptive.DataSaver(_learner, arg_picker=itemgetter('y'))"

    ]

   },

@@ -544,14 +543,8 @@

    "metadata": {},

    "outputs": [],

    "source": [

-    "runner = adaptive.Runner(learner, goal=lambda l: l.learner.loss() < 0.01)"

-   ]

-  },

-  {

-   "cell_type": "markdown",

-   "metadata": {},

-   "source": [

-    "Because `learner` doesn't have a `plot` function we need to copy `_learner.plot` (or `learner.learner.plot`)"

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

+    "runner.live_info()"

    ]

   },

   {

@@ -560,8 +553,7 @@

    "metadata": {},

    "outputs": [],

    "source": [

-    "learner.plot = _learner.plot\n",

-    "runner.live_plot()"

+    "runner.live_plot(plotter=lambda l: l.learner.plot(), update_interval=0.1)"

    ]

   },

   {

@@ -586,7 +578,7 @@

     "collapsed": true

    },

    "source": [

-    "## Alternative executors"

+    "# Using multiple cores"

    ]

   },

   {

@@ -600,14 +592,14 @@

    "cell_type": "markdown",

    "metadata": {},

    "source": [

-    "### `concurrent.futures`"

+    "### [`concurrent.futures`](https://docs.python.org/3/library/concurrent.futures.html)"

    ]

   },

   {

    "cell_type": "markdown",

    "metadata": {},

    "source": [

-    "By default a runner creates a `ProcessPoolExecutor`, but you can also pass one explicitly e.g. to limit the number of workers:"

+    "By default `adaptive.Runner` creates a `ProcessPoolExecutor`, but you can also pass one explicitly e.g. to limit the number of workers:"

    ]

   },

   {

@@ -623,14 +615,14 @@

     "learner = adaptive.Learner1D(f, bounds=(-1, 1))\n",

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

     "runner.live_info()\n",

-    "runner.live_plot()"

+    "runner.live_plot(update_interval=0.1)"

    ]

   },

   {

    "cell_type": "markdown",

    "metadata": {},

    "source": [

-    "### IPyparallel"

+    "### [`ipyparallel`](https://ipyparallel.readthedocs.io/en/latest/intro.html)"

    ]

   },

   {

@@ -653,7 +645,7 @@

    "cell_type": "markdown",

    "metadata": {},

    "source": [

-    "### distributed"

+    "### [`distributed`](https://distributed.readthedocs.io/en/latest/)"

    ]

   },

   {

@@ -669,7 +661,7 @@

     "learner = adaptive.Learner1D(f, bounds=(-1, 1))\n",

     "runner = adaptive.Runner(learner, executor=client, goal=lambda l: l.loss() < 0.01)\n",

     "runner.live_info()\n",

-    "runner.live_plot()"

+    "runner.live_plot(update_interval=0.1)"

    ]

   },

   {

@@ -686,6 +678,110 @@

     "# Advanced Topics"

    ]

   },

+  {

+   "cell_type": "markdown",

+   "metadata": {},

+   "source": [

+    "## A watched pot never boils!"

+   ]

+  },

+  {

+   "cell_type": "markdown",

+   "metadata": {},

+   "source": [

+    "`adaptive.Runner` does its work in an `asyncio` task that runs concurrently with the IPython kernel, when using `adaptive` from a Jupyter notebook. This is advantageous because it allows us to do things like live-updating plots, however it can trip you up if you're not careful.\n",

+    "\n",

+    "Notably: **if you block the IPython kernel, the runner will not do any work**.\n",

+    "\n",

+    "For example if you wanted to wait for a runner to complete, **do not wait in a busy loop**:\n",

+    "```python\n",

+    "while not runner.task.done():\n",

+    "    pass\n",

+    "```\n",

+    "\n",

+    "If you do this then **the runner will never finish**."

+   ]

+  },

+  {

+   "cell_type": "markdown",

+   "metadata": {},

+   "source": [

+    "What to do if you don't care about live plotting, and just want to run something until its done?\n",

+    "\n",

+    "The simplest way to accomplish this is to use `adaptive.BlockingRunner`:"

+   ]

+  },

+  {

+   "cell_type": "code",

+   "execution_count": null,

+   "metadata": {},

+   "outputs": [],

+   "source": [

+    "learner = adaptive.Learner1D(f, bounds=(-1, 1))\n",

+    "adaptive.BlockingRunner(learner, goal=lambda l: l.loss() < 0.005)\n",

+    "# This will only get run after the runner has finished\n",

+    "learner.plot()"

+   ]

+  },

+  {

+   "cell_type": "markdown",

+   "metadata": {},

+   "source": [

+    "## Reproducibility"

+   ]

+  },

+  {

+   "cell_type": "markdown",

+   "metadata": {},

+   "source": [

+    "By default `adaptive` runners evaluate the learned function in parallel across several cores. The runners are also opportunistic, in that as soon as a result is available they will feed it to the learner and request another point to replace the one that just finished.\n",

+    "\n",

+    "Because the order in which computations complete is non-deterministic, this means that the runner behaves in a non-deterministic way. Adaptive makes this choice because in many cases the speedup from parallel execution is worth sacrificing the \"purity\" of exactly reproducible computations.\n",

+    "\n",

+    "Nevertheless it is still possible to run a learner in a deterministic way with adaptive.\n",

+    "\n",

+    "The simplest way is to use `adaptive.runner.simple` to run your learner:"

+   ]

+  },

+  {

+   "cell_type": "code",

+   "execution_count": null,

+   "metadata": {},

+   "outputs": [],

+   "source": [

+    "learner = adaptive.Learner1D(f, bounds=(-1, 1))\n",

+    "\n",

+    "# blocks until completion\n",

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

+    "\n",

+    "learner.plot()"

+   ]

+  },

+  {

+   "cell_type": "markdown",

+   "metadata": {},

+   "source": [

+    "Note that unlike `adaptive.Runner`, `adaptive.runner.simple` *blocks* until it is finished.\n",

+    "\n",

+    "If you want to enable determinism, want to continue using the non-blocking `adaptive.Runner`, you can use the `adaptive.runner.SequentialExecutor`:"

+   ]

+  },

+  {

+   "cell_type": "code",

+   "execution_count": null,

+   "metadata": {},

+   "outputs": [],

+   "source": [

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

+    "\n",

+    "learner = adaptive.Learner1D(f, bounds=(-1, 1))\n",

+    "\n",

+    "# blocks until completion\n",

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

+    "runner.live_info()\n",

+    "runner.live_plot(update_interval=0.1)"

+   ]

+  },

   {

    "cell_type": "markdown",

    "metadata": {},

@@ -699,7 +795,9 @@

    "source": [

     "Sometimes you want to interactively explore a parameter space, and want the function to be evaluated at finer and finer resolution and manually control when the calculation stops.\n",

     "\n",

-    "If no `goal` is provided to a runner then the runner will run until cancelled:"

+    "If no `goal` is provided to a runner then the runner will run until cancelled.\n",

+    "\n",

+    "`runner.live_info()` will provide a button that can be clicked to stop the runner. You can also stop the runner programatically using `runner.cancel()`."

    ]

   },

   {

@@ -710,7 +808,8 @@

    "source": [

     "learner = adaptive.Learner1D(f, bounds=(-1, 1))\n",

     "runner = adaptive.Runner(learner)\n",

-    "runner.live_plot()"

+    "runner.live_info()\n",

+    "runner.live_plot(update_interval=0.1)"

    ]

   },

   {

@@ -764,6 +863,7 @@

     "    \n",

     "learner = adaptive.Learner1D(will_raise, (-1, 1))\n",

     "runner = adaptive.Runner(learner)  # without 'goal' the runner will run forever unless cancelled\n",

+    "runner.live_info()\n",

     "runner.live_plot()"

    ]

   },

@@ -920,7 +1020,9 @@

    "cell_type": "markdown",

    "metadata": {},

    "source": [

-    "Runners can also be used from a Python script independently of the notebook:\n",

+    "Runners can also be used from a Python script independently of the notebook.\n",

+    "\n",

+    "The simplest way to accomplish this is simply to use the `BlockingRunner`:\n",

     "\n",

     "```python\n",

     "import adaptive\n",

@@ -930,17 +1032,14 @@

     "\n",

     "learner = adaptive.Learner1D(f, (-1, 1))\n",

     "\n",

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

-    "runner.run_sync()  # Block until completion.\n",

+    "adaptive.BlockingRunner(learner, goal=lambda: l: l.loss() < 0.1)\n",

     "```\n",

     "\n",

-    "Under the hood the runner uses [`asyncio`](https://docs.python.org/3/library/asyncio.html). You don't need to worry about this most of the time, unless your script uses asyncio itself. If this is the case you should be aware that instantiating a `Runner` schedules a new task on the current event loop, and you can simply\n",

-    "\n",

+    "If you use `asyncio` already in your script and want to integrate `adaptive` into it, then you can use the default `Runner` as you would from a notebook. If you want to wait for the runner to finish, then you can simply\n",

     "```python\n",

     "    await runner.task\n",

     "```\n",

-    "\n",

-    "inside a coroutine to await completion of the runner."

+    "from within a coroutine."

    ]

   }

  ],