add tutorials

Author: basnijholt

adaptive/notebook_integration.py

@@ -20,7 +20,7 @@ def notebook_extension():
     try:
         import ipywidgets
         import holoviews
-        holoviews.notebook_extension('bokeh')
+        holoviews.notebook_extension('bokeh', logo=False)
         _plotting_enabled = True
     except ModuleNotFoundError:
         warnings.warn("holoviews and (or) ipywidgets are not installed; plotting "

adaptive/runner.py

@@ -264,7 +264,7 @@ class BlockingRunner(BaseRunner):
         of cores available in `executor`.
     log : bool, default: False
         If True, record the method calls made to the learner by this runner.
-    shutdown_executor : Bool, default: False
+    shutdown_executor : bool, default: False
         If True, shutdown the executor when the runner has completed. If
         `executor` is not provided then the executor created internally
         by the runner is shut down, regardless of this parameter.
@@ -367,7 +367,7 @@ class AsyncRunner(BaseRunner):
         of cores available in `executor`.
     log : bool, default: False
         If True, record the method calls made to the learner by this runner.
-    shutdown_executor : Bool, default: False
+    shutdown_executor : bool, default: False
         If True, shutdown the executor when the runner has completed. If
         `executor` is not provided then the executor created internally
         by the runner is shut down, regardless of this parameter.

docs/.gitignore

@@ -1 +1,2 @@
 build/*
+source/_static/holoviews.*

docs/environment.yml

@@ -16,3 +16,4 @@ dependencies:
   - scikit-optimize
   - pip:
       - sphinx_rtd_theme
+      - git+https://github.com/basnijholt/jupyter-sphinx.git@widgets_execute

docs/source/conf.py

@@ -47,6 +47,7 @@
     'sphinx.ext.mathjax',
     'sphinx.ext.viewcode',
     'sphinx.ext.napoleon',
+    'jupyter_sphinx.execute',
 ]
 
 source_parsers = {}
@@ -113,13 +114,52 @@
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'adaptivedoc'
 
+
 # -- Extension configuration -------------------------------------------------
 
 default_role = 'autolink'
 
-intersphinx_mapping = {'python': ('https://docs.python.org/3', None),
-                       'distributed': ('https://distributed.readthedocs.io/en/stable/', None),
-                       'holoviews': ('https://holoviews.org/', None),
-                       'ipyparallel': ('https://ipyparallel.readthedocs.io/en/stable/', None),
-                       'scipy': ('https://docs.scipy.org/doc/scipy/reference', None),
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3', None),
+    'distributed': ('https://distributed.readthedocs.io/en/stable/', None),
+    'holoviews': ('https://holoviews.org/', None),
+    'ipyparallel': ('https://ipyparallel.readthedocs.io/en/stable/', None),
+    'scipy': ('https://docs.scipy.org/doc/scipy/reference', None),
 }
+
+
+# -- Add Holoviews js and css ------------------------------------------------
+
+def setup(app):
+    from holoviews.plotting import Renderer
+
+    hv_js, hv_css = Renderer.html_assets(
+        extras=False, backends=[], script=True)
+
+    fname_css = 'holoviews.css'
+    fname_js = 'holoviews.js'
+    static_dir = 'source/_static'
+
+    os.makedirs(static_dir, exist_ok=True)
+
+    with open(f'{static_dir}/{fname_css}', 'w') as f:
+        hv_css = hv_css.split('<style>')[1].replace('</style>', '')
+        f.write(hv_css)
+
+    with open(f'{static_dir}/{fname_js}', 'w') as f:
+        f.write(hv_js)
+
+    app.add_stylesheet(fname_css)
+    app.add_javascript(fname_js)
+
+    dependencies = {**Renderer.core_dependencies, **Renderer.extra_dependencies}
+    for name, type_url in dependencies.items():
+        if name in ['bootstrap']:
+            continue
+
+        for url in type_url.get('js', []):
+            app.add_javascript(url)
+        for url in type_url.get('css', []):
+            app.add_stylesheet(url)
+
+    app.add_javascript("https://unpkg.com/@jupyter-widgets/html-manager@0.14.4/dist/embed-amd.js")

docs/source/index.rst

@@ -17,4 +17,5 @@
    :hidden:
 
    rest_of_readme
+   tutorial/tutorial
    reference/adaptive

docs/source/reference/adaptive.rst

@@ -22,6 +22,7 @@ Runners
     adaptive.runner.Runner
     adaptive.runner.AsyncRunner
     adaptive.runner.BlockingRunner
+    adaptive.runner.extras
 
 Other
 -----

docs/source/reference/adaptive.runner.extras.rst

@@ -0,0 +1,18 @@
+adaptive.runner.simple
+======================
+
+Simple executor
+---------------
+
+.. autofunction:: adaptive.runner.simple
+
+Sequential excecutor
+--------------------
+
+.. autofunction:: adaptive.runner.SequentialExecutor
+
+
+Replay log
+----------
+
+.. autofunction:: adaptive.runner.replay_log

docs/source/tutorial/tutorial.AverageLearner.rst

@@ -0,0 +1,57 @@
+Tutorial `~adaptive.AverageLearner`
+-----------------------------------
+
+.. 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:`AverageLearner`
+
+.. execute::
+    :hide-code:
+    :new-notebook: AverageLearner
+
+    import adaptive
+    adaptive.notebook_extension()
+
+The next type of learner averages a function until the uncertainty in
+the average meets some condition.
+
+This is useful for sampling a random variable. The function passed to
+the learner must formally take a single parameter, which should be used
+like a “seed” for the (pseudo-) random variable (although in the current
+implementation the seed parameter can be ignored by the function).
+
+.. execute::
+
+    def g(n):
+        import random
+        from time import sleep
+        sleep(random.random() / 1000)
+        # Properly save and restore the RNG state
+        state = random.getstate()
+        random.seed(n)
+        val = random.gauss(0.5, 1)
+        random.setstate(state)
+        return val
+
+.. execute::
+
+    learner = adaptive.AverageLearner(g, atol=None, rtol=0.01)
+    runner = adaptive.Runner(learner, goal=lambda l: l.loss() < 2)
+
+.. 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)

docs/source/tutorial/tutorial.BalancingLearner.rst

@@ -0,0 +1,83 @@
+Tutorial `~adaptive.BalancingLearner`
+-------------------------------------
+
+.. 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:`BalancingLearner`
+
+.. execute::
+    :hide-code:
+    :new-notebook: BalancingLearner
+
+    import adaptive
+    adaptive.notebook_extension()
+
+    import holoviews as hv
+    import numpy as np
+    from functools import partial
+    import random
+
+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.
+
+The balancing learner can for example be used to implement a poor-man’s
+2D learner by using the `~adaptive.Learner1D`.
+
+.. execute::
+
+    def h(x, offset=0):
+        a = 0.01
+        return x + a**2 / (a**2 + (x - offset)**2)
+
+    learners = [adaptive.Learner1D(partial(h, offset=random.uniform(-1, 1)),
+                bounds=(-1, 1)) for i in range(10)]
+
+    bal_learner = adaptive.BalancingLearner(learners)
+    runner = adaptive.Runner(bal_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::
+
+    plotter = lambda learner: hv.Overlay([L.plot() for L in learner.learners])
+    runner.live_plot(plotter=plotter, update_interval=0.1)
+
+Often one wants to create a set of ``learner``\ s for a cartesian
+product of parameters. For that particular case we’ve added a
+``classmethod`` called ``~adaptive.BalancingLearner.from_product``.
+See how it works below
+
+.. execute::
+
+    from scipy.special import eval_jacobi
+
+    def jacobi(x, n, alpha, beta): return eval_jacobi(n, alpha, beta, x)
+
+    combos = {
+        'n': [1, 2, 4, 8],
+        'alpha': np.linspace(0, 2, 3),
+        'beta': np.linspace(0, 1, 5),
+    }
+
+    learner = adaptive.BalancingLearner.from_product(
+        jacobi, adaptive.Learner1D, dict(bounds=(0, 1)), combos)
+
+    runner = adaptive.BlockingRunner(learner, goal=lambda l: l.loss() < 0.01)
+
+    # The `cdims` will automatically be set when using `from_product`, so
+    # `plot()` will return a HoloMap with correctly labeled sliders.
+    learner.plot().overlay('beta').grid().select(y=(-1, 3))