add docs for the SequenceLearner

Author: basnijholt

adaptive/learner/sequence_learner.py

@@ -52,7 +52,7 @@ class SequenceLearner(BaseLearner):
     Notes
     -----
     From primitive tests, the `~adaptive.SequenceLearner` appears to have a
-    similar performance to `ipyparallel`\s `load_balanced_view().map`. With
+    similar performance to `ipyparallel`\s ``load_balanced_view().map``. With
     the added benefit of having results in the local kernel already.
     """
 
@@ -120,7 +120,7 @@ def done(self):
         return not self._to_do_indices and not self.pending_points
 
     def result(self):
-        """Get back the data in the same order as ``sequence``."""
+        """Get the function values in the same order as ``sequence``."""
         if not self.done():
             raise Exception("Learner is not yet complete.")
         return list(self.data.values())

docs/source/reference/adaptive.learner.sequence_learner.rst

@@ -0,0 +1,7 @@
+adaptive.SequenceLearner
+========================
+
+.. autoclass:: adaptive.SequenceLearner
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/source/reference/adaptive.rst

@@ -14,6 +14,7 @@ Learners
     adaptive.learner.learner1D
     adaptive.learner.learner2D
     adaptive.learner.learnerND
+    adaptive.learner.sequence_learner
     adaptive.learner.skopt_learner
 
 Runners

docs/source/tutorial/tutorial.SequenceLearner.rst

@@ -0,0 +1,66 @@
+Tutorial `~adaptive.SequenceLearner`
+---------------------------------
+
+.. 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:`tutorial.SequenceLearner`
+
+.. jupyter-execute::
+    :hide-code:
+
+    import adaptive
+    adaptive.notebook_extension(_inline_js=False)
+
+    import holoviews as hv
+    import numpy as np
+
+This learner will learn a sequence. It simply returns
+the points in the provided sequence when asked.
+
+This is useful when your problem cannot be formulated in terms of
+another adaptive learner, but you still want to use Adaptive's
+routines to run, (periodically) save, and plot.
+
+.. jupyter-execute::
+
+    from adaptive import SequenceLearner
+
+    def f(x):
+        return int(x) ** 2
+
+    seq = np.linspace(-15, 15, 1000)
+    learner = SequenceLearner(f, seq)
+
+    runner = adaptive.Runner(learner, SequenceLearner.done)
+    # that goal is same as `lambda learner: learner.done()`
+
+.. jupyter-execute::
+    :hide-code:
+
+    await runner.task  # This is not needed in a notebook environment!
+
+.. jupyter-execute::
+
+    runner.live_info()
+
+.. jupyter-execute::
+
+    def plotter(learner):
+        data = learner.data if learner.data else []
+        return hv.Scatter(data)
+
+    runner.live_plot(plotter=plotter)
+
+``learner.data`` contains a dictionary that maps the index of the point of ``learner.sequence`` to the value at that point.
+
+To get the values in the same order as the input sequence (``learner.sequence``) use
+
+.. jupyter-execute::
+
+    result = learner.result()
+    print(result[:10])  # print the 10 first values

docs/source/tutorial/tutorial.rst

@@ -40,6 +40,7 @@ We recommend to start with the :ref:`Tutorial `~adaptive.Learner1D``.
     tutorial.DataSaver
     tutorial.IntegratorLearner
     tutorial.LearnerND
+    tutorial.SequenceLearner
     tutorial.SKOptLearner
     tutorial.parallelism
     tutorial.advanced-topics