@@ -14,7 +14,7 @@ Advanced Topics

     :hide-code:

     import adaptive

-    adaptive.notebook_extension(_inline_js=False)

+    adaptive.notebook_extension()

     import asyncio

     from functools import partial

@@ -297,12 +297,12 @@ raise the exception with the stack trace:

     runner.task.result()

-You can also check ``runner.tracebacks`` which is a mapping from

-point → traceback.

+You can also check ``runner.tracebacks`` which is a list of tuples with

+(point, traceback).

 .. jupyter-execute::

-    for point, tb in runner.tracebacks.items():

+    for point, tb in runner.tracebacks:

         print(f'point: {point}:\n {tb}')

 Logging runners

@@ -413,7 +413,7 @@ The simplest way to accomplish this is simply to use the

    learner = adaptive.Learner1D(f, (-1, 1))

-   adaptive.BlockingRunner(learner, goal=lambda: l: l.loss() < 0.1)

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

 If you use `asyncio` already in your script and want to integrate

 ``adaptive`` into it, then you can use the default `~adaptive.Runner` as you

@@ -10,8 +10,6 @@ Advanced Topics

     The complete source code of this tutorial can be found in

     :jupyter-download:notebook:`tutorial.advanced-topics`

-.. thebe-button:: Run the code live inside the documentation!

-

 .. jupyter-execute::

     :hide-code:

@@ -294,6 +294,7 @@ the runner stopped due to an exception then asking for the result will

 raise the exception with the stack trace:

 .. jupyter-execute::

+    :raises:

     runner.task.result()

@@ -10,6 +10,8 @@ Advanced Topics

     The complete source code of this tutorial can be found in

     :jupyter-download:notebook:`tutorial.advanced-topics`

+.. thebe-button:: Run the code live inside the documentation!

+

 .. jupyter-execute::

     :hide-code:

@@ -14,7 +14,7 @@ Advanced Topics

     :hide-code:

     import adaptive

-    adaptive.notebook_extension()

+    adaptive.notebook_extension(_inline_js=False)

     import asyncio

     from functools import partial

@@ -33,13 +33,10 @@ Saving and loading learners

 Every learner has a `~adaptive.BaseLearner.save` and `~adaptive.BaseLearner.load`

 method that can be used to save and load **only** the data of a learner.

-There are **two ways** of naming the files: 1. Using the ``fname``

-argument in ``learner.save(fname=...)`` 2. Setting the ``fname``

-attribute, like ``learner.fname = 'data/example.p`` and then

-``learner.save()``

+Use the ``fname`` argument in ``learner.save(fname=...)``.

-The second way *must be used* when saving the ``learner``\s of a

-`~adaptive.BalancingLearner`.

+Or, when using a `~adaptive.BalancingLearner` one can use either a callable

+that takes the child learner and returns a filename **or** a list of filenames.

 By default the resulting pickle files are compressed, to turn this off

 use ``learner.save(fname=..., compress=False)``

@@ -298,6 +298,15 @@ raise the exception with the stack trace:

     runner.task.result()

+

+You can also check ``runner.tracebacks`` which is a mapping from

+point → traceback.

+

+.. jupyter-execute::

+

+    for point, tb in runner.tracebacks.items():

+        print(f'point: {point}:\n {tb}')

+

 Logging runners

 ~~~~~~~~~~~~~~~

@@ -337,10 +346,16 @@ set of operations on another runner:

     learner.plot().Scatter.I.opts(style=dict(size=6)) * reconstructed_learner.plot()

-Timing functions

-~~~~~~~~~~~~~~~~

+Adding coroutines

+-----------------

+

+In the following example we'll add a `~asyncio.Task` that times the runner.

+This is *only* for demonstration purposes because one can simply

+check ``runner.elapsed_time()`` or use the ``runner.live_info()``

+widget to see the time since the runner has started.

-To time the runner you **cannot** simply use

+So let's get on with the example. To time the runner

+you **cannot** simply use

 .. code:: python

@@ -8,11 +8,10 @@ Advanced Topics

 .. seealso::

     The complete source code of this tutorial can be found in

-    :jupyter-download:notebook:`advanced-topics`

+    :jupyter-download:notebook:`tutorial.advanced-topics`

-.. execute::

+.. jupyter-execute::

     :hide-code:

-    :new-notebook: advanced-topics

     import adaptive

     adaptive.notebook_extension()

@@ -45,7 +44,7 @@ The second way *must be used* when saving the ``learner``\s of a

 By default the resulting pickle files are compressed, to turn this off

 use ``learner.save(fname=..., compress=False)``

-.. execute::

+.. jupyter-execute::

     # Let's create two learners and run only one.

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

@@ -54,16 +53,16 @@ use ``learner.save(fname=..., compress=False)``

     # Let's only run the learner

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

-.. execute::

+.. jupyter-execute::

     :hide-code:

     await runner.task  # This is not needed in a notebook environment!

-.. execute::

+.. jupyter-execute::

     runner.live_info()

-.. execute::

+.. jupyter-execute::

     fname = 'data/example_file.p'

     learner.save(fname)

@@ -74,7 +73,7 @@ use ``learner.save(fname=..., compress=False)``

 Or just (without saving):

-.. execute::

+.. jupyter-execute::

     control = adaptive.Learner1D(f, bounds=(-1, 1))

     control.copy_from(learner)

@@ -82,7 +81,7 @@ Or just (without saving):

 One can also periodically save the learner while running in a

 `~adaptive.Runner`. Use it like:

-.. execute::

+.. jupyter-execute::

     def slow_f(x):

         from time import sleep

@@ -93,17 +92,17 @@ One can also periodically save the learner while running in a

     runner = adaptive.Runner(learner, goal=lambda l: l.npoints > 100)

     runner.start_periodic_saving(save_kwargs=dict(fname='data/periodic_example.p'), interval=6)

-.. execute::

+.. jupyter-execute::

     :hide-code:

     await asyncio.sleep(6)  # This is not needed in a notebook environment!

     runner.cancel()

-.. execute::

+.. jupyter-execute::

     runner.live_info()  # we cancelled it after 6 seconds

-.. execute::

+.. jupyter-execute::

     # See the data 6 later seconds with

     !ls -lah data  # only works on macOS and Linux systems

@@ -137,7 +136,7 @@ something until its done?

 The simplest way to accomplish this is to use

 `adaptive.BlockingRunner`:

-.. execute::

+.. jupyter-execute::

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

     adaptive.BlockingRunner(learner, goal=lambda l: l.loss() < 0.01)

@@ -164,7 +163,7 @@ way with adaptive.

 The simplest way is to use `adaptive.runner.simple` to run your

 learner:

-.. execute::

+.. jupyter-execute::

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

@@ -180,7 +179,7 @@ If you want to enable determinism, want to continue using the

 non-blocking `adaptive.Runner`, you can use the

 `adaptive.runner.SequentialExecutor`:

-.. execute::

+.. jupyter-execute::

     from adaptive.runner import SequentialExecutor

@@ -188,16 +187,16 @@ non-blocking `adaptive.Runner`, you can use the

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

-.. execute::

+.. jupyter-execute::

     :hide-code:

     await runner.task  # This is not needed in a notebook environment!

-.. execute::

+.. jupyter-execute::

     runner.live_info()

-.. execute::

+.. jupyter-execute::

     runner.live_plot(update_interval=0.1)

@@ -215,29 +214,29 @@ cancelled.

 the runner. You can also stop the runner programatically using

 ``runner.cancel()``.

-.. execute::

+.. jupyter-execute::

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

     runner = adaptive.Runner(learner)

-.. execute::

+.. jupyter-execute::

     :hide-code:

     await asyncio.sleep(0.1)  # This is not needed in the notebook!

-.. execute::

+.. jupyter-execute::

     runner.cancel()  # Let's execute this after 0.1 seconds

-.. execute::

+.. jupyter-execute::

     runner.live_info()

-.. execute::

+.. jupyter-execute::

     runner.live_plot(update_interval=0.1)

-.. execute::

+.. jupyter-execute::

     print(runner.status())

@@ -253,7 +252,7 @@ gone wrong is that nothing will be happening.

 Let’s look at the following example, where the function to be learned

 will raise an exception 10% of the time.

-.. execute::

+.. jupyter-execute::

     def will_raise(x):

         from random import random

@@ -268,16 +267,16 @@ will raise an exception 10% of the time.

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

-.. execute::

+.. jupyter-execute::

     :hide-code:

     await asyncio.sleep(4)  # in 4 seconds it will surely have failed

-.. execute::

+.. jupyter-execute::

     runner.live_info()

-.. execute::

+.. jupyter-execute::

     runner.live_plot()

@@ -286,7 +285,7 @@ after a few points are evaluated.

 First we should check that the runner has really finished:

-.. execute::

+.. jupyter-execute::

     runner.task.done()

@@ -295,7 +294,7 @@ runner. This should be ``None`` if the runner stopped successfully. If

 the runner stopped due to an exception then asking for the result will

 raise the exception with the stack trace:

-.. execute::

+.. jupyter-execute::

     runner.task.result()

@@ -306,18 +305,18 @@ Runners do their job in the background, which makes introspection quite

 cumbersome. One way to inspect runners is to instantiate one with

 ``log=True``:

-.. execute::

+.. jupyter-execute::

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

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

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

                              log=True)

-.. execute::

+.. jupyter-execute::

     :hide-code:

     await runner.task  # This is not needed in a notebook environment!

-.. execute::

+.. jupyter-execute::

     runner.live_info()

@@ -329,12 +328,12 @@ non-deterministic order.

 This can be used with `adaptive.runner.replay_log` to perfom the same

 set of operations on another runner:

-.. execute::

+.. jupyter-execute::

     reconstructed_learner = adaptive.Learner1D(f, bounds=learner.bounds)

     adaptive.runner.replay_log(reconstructed_learner, runner.log)

-.. execute::

+.. jupyter-execute::

     learner.plot().Scatter.I.opts(style=dict(size=6)) * reconstructed_learner.plot()

@@ -356,7 +355,7 @@ not do anything when the kernel is blocked.

 Therefore you need to create an ``async`` function and hook it into the

 ``ioloop`` like so:

-.. execute::

+.. jupyter-execute::

     import asyncio

@@ -373,12 +372,12 @@ Therefore you need to create an ``async`` function and hook it into the

     timer = ioloop.create_task(time(runner))

-.. execute::

+.. jupyter-execute::

     :hide-code:

     await runner.task  # This is not needed in a notebook environment!

-.. execute::

+.. jupyter-execute::

     # The result will only be set when the runner is done.

     timer.result()

@@ -17,21 +17,98 @@ Advanced Topics

     import adaptive

     adaptive.notebook_extension()

+    import asyncio

     from functools import partial

     import random

     offset = random.uniform(-0.5, 0.5)

-    def f(x, offset=offset, wait=True):

-        from time import sleep

-        from random import random

-

+    def f(x, offset=offset):

         a = 0.01

-        if wait:

-            sleep(random())

         return x + a**2 / (a**2 + (x - offset)**2)

+Saving and loading learners

+---------------------------

+

+Every learner has a `~adaptive.BaseLearner.save` and `~adaptive.BaseLearner.load`

+method that can be used to save and load **only** the data of a learner.

+

+There are **two ways** of naming the files: 1. Using the ``fname``

+argument in ``learner.save(fname=...)`` 2. Setting the ``fname``

+attribute, like ``learner.fname = 'data/example.p`` and then

+``learner.save()``

+

+The second way *must be used* when saving the ``learner``\s of a

+`~adaptive.BalancingLearner`.

+

+By default the resulting pickle files are compressed, to turn this off

+use ``learner.save(fname=..., compress=False)``

+

+.. execute::

+

+    # Let's create two learners and run only one.

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

+    control = adaptive.Learner1D(f, bounds=(-1, 1))

+

+    # Let's only run the learner

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

+

+.. execute::

+    :hide-code:

+

+    await runner.task  # This is not needed in a notebook environment!

+

+.. execute::

+

+    runner.live_info()

+

+.. execute::

+

+    fname = 'data/example_file.p'

+    learner.save(fname)

+    control.load(fname)

+

+    (learner.plot().relabel('saved learner')

+     + control.plot().relabel('loaded learner'))

+

+Or just (without saving):

+

+.. execute::

+

+    control = adaptive.Learner1D(f, bounds=(-1, 1))

+    control.copy_from(learner)

+

+One can also periodically save the learner while running in a

+`~adaptive.Runner`. Use it like:

+

+.. execute::

+

+    def slow_f(x):

+        from time import sleep

+        sleep(5)

+        return x

+

+    learner = adaptive.Learner1D(slow_f, bounds=[0, 1])

+    runner = adaptive.Runner(learner, goal=lambda l: l.npoints > 100)

+    runner.start_periodic_saving(save_kwargs=dict(fname='data/periodic_example.p'), interval=6)

+

+.. execute::

+    :hide-code:

+

+    await asyncio.sleep(6)  # This is not needed in a notebook environment!

+    runner.cancel()

+

+.. execute::

+

+    runner.live_info()  # we cancelled it after 6 seconds

+

+.. execute::

+

+    # See the data 6 later seconds with

+    !ls -lah data  # only works on macOS and Linux systems

+

+

 A watched pot never boils!

 --------------------------

@@ -62,7 +139,7 @@ The simplest way to accomplish this is to use

 .. execute::

-    learner = adaptive.Learner1D(partial(f, wait=False), bounds=(-1, 1))

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

     adaptive.BlockingRunner(learner, goal=lambda l: l.loss() < 0.01)

     # This will only get run after the runner has finished

     learner.plot()

@@ -89,7 +166,7 @@ learner:

 .. execute::

-    learner = adaptive.Learner1D(partial(f, wait=False), bounds=(-1, 1))

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

     # blocks until completion

     adaptive.runner.simple(learner, goal=lambda l: l.loss() < 0.01)

@@ -107,7 +184,7 @@ non-blocking `adaptive.Runner`, you can use the

     from adaptive.runner import SequentialExecutor

-    learner = adaptive.Learner1D(partial(f, wait=False), bounds=(-1, 1))

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

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

@@ -146,12 +223,11 @@ the runner. You can also stop the runner programatically using

 .. execute::

     :hide-code:

-    import asyncio

-    await asyncio.sleep(3)  # This is not needed in the notebook!

+    await asyncio.sleep(0.1)  # This is not needed in the notebook!

 .. execute::

-    runner.cancel()  # Let's execute this after 3 seconds

+    runner.cancel()  # Let's execute this after 0.1 seconds

 .. execute::

@@ -195,7 +271,6 @@ will raise an exception 10% of the time.

 .. execute::

     :hide-code:

-    import asyncio

     await asyncio.sleep(4)  # in 4 seconds it will surely have failed

 .. execute::

new file mode 100644

@@ -0,0 +1,340 @@

+Advanced Topics

+===============

+

+.. note::

+   Because this documentation consists of static html, the ``live_plot``

+   and ``live_info`` widget is not live. Download the notebook

+   in order to see the real behaviour.

+

+.. seealso::

+    The complete source code of this tutorial can be found in

+    :jupyter-download:notebook:`advanced-topics`

+

+.. execute::

+    :hide-code:

+    :new-notebook: advanced-topics

+

+    import adaptive

+    adaptive.notebook_extension()

+

+    from functools import partial

+    import random

+

+    offset = random.uniform(-0.5, 0.5)

+

+    def f(x, offset=offset, wait=True):

+        from time import sleep

+        from random import random

+

+        a = 0.01

+        if wait:

+            sleep(random())

+        return x + a**2 / (a**2 + (x - offset)**2)

+

+

+A watched pot never boils!

+--------------------------

+

+`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.

+

+Notably: **if you block the IPython kernel, the runner will not do any

+work**.

+

+For example if you wanted to wait for a runner to complete, **do not

+wait in a busy loop**:

+

+.. code:: python

+

+   while not runner.task.done():

+       pass

+

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

+

+What to do if you don’t care about live plotting, and just want to run

+something until its done?

+

+The simplest way to accomplish this is to use

+`adaptive.BlockingRunner`:

+

+.. execute::

+

+    learner = adaptive.Learner1D(partial(f, wait=False), bounds=(-1, 1))

+    adaptive.BlockingRunner(learner, goal=lambda l: l.loss() < 0.01)

+    # This will only get run after the runner has finished

+    learner.plot()

+

+Reproducibility

+---------------

+

+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.

+

+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.

+

+Nevertheless it is still possible to run a learner in a deterministic

+way with adaptive.

+

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

+learner:

+

+.. execute::

+

+    learner = adaptive.Learner1D(partial(f, wait=False), bounds=(-1, 1))

+

+    # blocks until completion

+    adaptive.runner.simple(learner, goal=lambda l: l.loss() < 0.01)

+

+    learner.plot()

+

+Note that unlike `adaptive.Runner`, `adaptive.runner.simple`

+*blocks* until it is finished.

+

+If you want to enable determinism, want to continue using the

+non-blocking `adaptive.Runner`, you can use the

+`adaptive.runner.SequentialExecutor`:

+

+.. execute::

+

+    from adaptive.runner import SequentialExecutor

+

+    learner = adaptive.Learner1D(partial(f, wait=False), bounds=(-1, 1))

+

+    runner = adaptive.Runner(learner, executor=SequentialExecutor(), goal=lambda l: l.loss() < 0.01)

+

+.. execute::

+    :hide-code:

+

+    await runner.task  # This is not needed in a notebook environment!

+

+.. execute::

+

+    runner.live_info()

+

+.. execute::

+

+    runner.live_plot(update_interval=0.1)

+

+Cancelling a runner

+-------------------

+

+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.

+

+If no ``goal`` is provided to a runner then the runner will run until

+cancelled.

+

+``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()``.

+

+.. execute::

+

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

+    runner = adaptive.Runner(learner)

+

+.. execute::

+    :hide-code:

+

+    import asyncio

+    await asyncio.sleep(3)  # This is not needed in the notebook!

+

+.. execute::

+

+    runner.cancel()  # Let's execute this after 3 seconds

+

+.. execute::

+

+    runner.live_info()

+

+.. execute::

+

+    runner.live_plot(update_interval=0.1)

+

+.. execute::

+

+    print(runner.status())

+

+Debugging Problems

+------------------

+

+Runners work in the background with respect to the IPython kernel, which

+makes it convenient, but also means that inspecting errors is more

+difficult because exceptions will not be raised directly in the

+notebook. Often the only indication you will have that something has

+gone wrong is that nothing will be happening.

+

+Let’s look at the following example, where the function to be learned

+will raise an exception 10% of the time.

+

+.. execute::

+

+    def will_raise(x):

+        from random import random

+        from time import sleep

+

+        sleep(random())

+        if random() < 0.1:

+            raise RuntimeError('something went wrong!')

+        return x**2

+

+    learner = adaptive.Learner1D(will_raise, (-1, 1))

+    runner = adaptive.Runner(learner)  # without 'goal' the runner will run forever unless cancelled

+

+

+.. execute::

+    :hide-code:

+

+    import asyncio

+    await asyncio.sleep(4)  # in 4 seconds it will surely have failed

+

+.. execute::

+

+    runner.live_info()

+

+.. execute::

+

+    runner.live_plot()

+

+The above runner should continue forever, but we notice that it stops

+after a few points are evaluated.

+

+First we should check that the runner has really finished:

+

+.. execute::

+

+    runner.task.done()

+

+If it has indeed finished then we should check the ``result`` of the

+runner. This should be ``None`` if the runner stopped successfully. If

+the runner stopped due to an exception then asking for the result will

+raise the exception with the stack trace:

+

+.. execute::

+

+    runner.task.result()

+

+Logging runners

+~~~~~~~~~~~~~~~

+

+Runners do their job in the background, which makes introspection quite

+cumbersome. One way to inspect runners is to instantiate one with

+``log=True``:

+

+.. execute::

+

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

+    runner = adaptive.Runner(learner, goal=lambda l: l.loss() < 0.1,

+                             log=True)

+

+.. execute::

+    :hide-code:

+

+    await runner.task  # This is not needed in a notebook environment!

+

+.. execute::

+

+    runner.live_info()

+

+This gives a the runner a ``log`` attribute, which is a list of the

+``learner`` methods that were called, as well as their arguments. This

+is useful because executors typically execute their tasks in a

+non-deterministic order.

+

+This can be used with `adaptive.runner.replay_log` to perfom the same

+set of operations on another runner:

+

+.. execute::

+

+    reconstructed_learner = adaptive.Learner1D(f, bounds=learner.bounds)

+    adaptive.runner.replay_log(reconstructed_learner, runner.log)

+

+.. execute::

+

+    learner.plot().Scatter.I.opts(style=dict(size=6)) * reconstructed_learner.plot()

+

+Timing functions

+~~~~~~~~~~~~~~~~

+

+To time the runner you **cannot** simply use

+

+.. code:: python

+

+   now = datetime.now()

+   runner = adaptive.Runner(...)

+   print(datetime.now() - now)

+

+because this will be done immediately. Also blocking the kernel with

+``while not runner.task.done()`` will not work because the runner will

+not do anything when the kernel is blocked.

+

+Therefore you need to create an ``async`` function and hook it into the

+``ioloop`` like so:

+

+.. execute::

+

+    import asyncio

+

+    async def time(runner):

+        from datetime import datetime

+        now = datetime.now()

+        await runner.task

+        return datetime.now() - now

+

+    ioloop = asyncio.get_event_loop()

+

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

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

+

+    timer = ioloop.create_task(time(runner))

+

+.. execute::

+    :hide-code:

+

+    await runner.task  # This is not needed in a notebook environment!

+

+.. execute::

+

+    # The result will only be set when the runner is done.

+    timer.result()

+

+Using Runners from a script

+---------------------------

+