add doc files

Author: basnijholt

README.rst

@@ -10,15 +10,15 @@ chat at https://gitter.im/python-adaptive/adaptive|
 
 **Tools for adaptive parallel sampling of mathematical functions.**
 
-``adaptive`` is an `open-source <LICENSE>`_ Python library designed to
+``adaptive`` is an open-source Python library designed to
 make adaptive parallel function evaluation simple. With ``adaptive`` you
 just supply a function with its bounds, and it will be evaluated at the
 “best” points in parameter space. With just a few lines of code you can
 evaluate functions on a computing cluster, live-plot the data as it
 returns, and fine-tune the adaptive sampling algorithm.
 
 Check out the ``adaptive`` example notebook
-`learner.ipynb <learner.ipynb>`_ (or run it `live on
+`learner.ipynb <https://github.com/python-adaptive/adaptive/blob/master/learner.ipynb>`_ (or run it `live on
 Binder <https://mybinder.org/v2/gh/python-adaptive/adaptive/master?filepath=learner.ipynb>`_)
 to see examples of how to use ``adaptive``.
 
@@ -127,7 +127,7 @@ We would like to give credits to the following people:
   Mathematical Software, 37 (3), art. no. 26, 2010.
 - Pauli Virtanen for his ``AdaptiveTriSampling`` script (no longer
   available online since SciPy Central went down) which served as
-  inspiration for the `Learner2D <adaptive/learner/learner2D.py>`_.
+  inspiration for the ``~adaptive.Learner2D``.
 
 For general discussion, we have a `Gitter chat
 channel <https://gitter.im/python-adaptive/adaptive>`_. If you find any

adaptive/__init__.py

@@ -8,15 +8,15 @@
 from . import runner
 from . import utils
 
-from .learner import (Learner1D, Learner2D, LearnerND, AverageLearner,
-                      BalancingLearner, make_datasaver, DataSaver,
-                      IntegratorLearner)
+from .learner import (BaseLearner, Learner1D, Learner2D, LearnerND,
+                      AverageLearner, BalancingLearner, make_datasaver,
+                      DataSaver, IntegratorLearner)
 
 with suppress(ImportError):
     # Only available if 'scikit-optimize' is installed
     from .learner import SKOptLearner
 
-from .runner import Runner, BlockingRunner
+from .runner import Runner, AsyncRunner, BlockingRunner
 
 from ._version import __version__
 del _version

adaptive/learner/average_learner.py

@@ -17,9 +17,9 @@ class AverageLearner(BaseLearner):
     Parameters
     ----------
     atol : float
-        Desired absolute tolerance
+        Desired absolute tolerance.
     rtol : float
-        Desired relative tolerance
+        Desired relative tolerance.
 
     Attributes
     ----------

adaptive/learner/balancing_learner.py

@@ -21,27 +21,32 @@ class BalancingLearner(BaseLearner):
 
     Parameters
     ----------
-    learners : sequence of BaseLearner
+    learners : sequence of `BaseLearner`
         The learners from which to choose. These must all have the same type.
     cdims : sequence of dicts, or (keys, iterable of values), optional
         Constant dimensions; the parameters that label the learners. Used
         in `plot`.
         Example inputs that all give identical results:
+
         - sequence of dicts:
+
             >>> cdims = [{'A': True, 'B': 0},
             ...          {'A': True, 'B': 1},
             ...          {'A': False, 'B': 0},
             ...          {'A': False, 'B': 1}]`
+
         - tuple with (keys, iterable of values):
+
             >>> cdims = (['A', 'B'], itertools.product([True, False], [0, 1]))
             >>> cdims = (['A', 'B'], [(True, 0), (True, 1),
             ...                       (False, 0), (False, 1)])
+
     strategy : 'loss_improvements' (default), 'loss', or 'npoints'
-        The points that the 'BalancingLearner' choses can be either based on:
+        The points that the `BalancingLearner` choses can be either based on:
         the best 'loss_improvements', the smallest total 'loss' of the
         child learners, or the number of points per learner, using 'npoints'.
         One can dynamically change the strategy while the simulation is
-        running by changing the 'learner.strategy' attribute.
+        running by changing the ``learner.strategy`` attribute.
 
     Notes
     -----
@@ -50,7 +55,7 @@ class BalancingLearner(BaseLearner):
     compared*. For the moment we enforce this restriction by requiring that
     all learners are the same type but (depending on the internals of the
     learner) it may be that the loss cannot be compared *even between learners
-    of the same type*. In this case the BalancingLearner will behave in an
+    of the same type*. In this case the `BalancingLearner` will behave in an
     undefined way.
     """
 
@@ -183,28 +188,34 @@ def plot(self, cdims=None, plotter=None, dynamic=True):
         cdims : sequence of dicts, or (keys, iterable of values), optional
             Constant dimensions; the parameters that label the learners.
             Example inputs that all give identical results:
+
             - sequence of dicts:
+
                 >>> cdims = [{'A': True, 'B': 0},
                 ...          {'A': True, 'B': 1},
                 ...          {'A': False, 'B': 0},
                 ...          {'A': False, 'B': 1}]`
+
             - tuple with (keys, iterable of values):
+
                 >>> cdims = (['A', 'B'], itertools.product([True, False], [0, 1]))
                 >>> cdims = (['A', 'B'], [(True, 0), (True, 1),
                 ...                       (False, 0), (False, 1)])
+
         plotter : callable, optional
             A function that takes the learner as a argument and returns a
-            holoviews object. By default learner.plot() will be called.
+            holoviews object. By default ``learner.plot()`` will be called.
         dynamic : bool, default True
-            Return a holoviews.DynamicMap if True, else a holoviews.HoloMap.
-            The DynamicMap is rendered as the sliders change and can therefore
-            not be exported to html. The HoloMap does not have this problem.
+            Return a `holoviews.core.DynamicMap` if True, else a
+            `holoviews.core.HoloMap`. The `~holoviews.core.DynamicMap` is
+            rendered as the sliders change and can therefore not be exported
+            to html. The `~holoviews.core.HoloMap` does not have this problem.
 
         Returns
         -------
-        dm : holoviews.DynamicMap object (default) or holoviews.HoloMap object
-            A DynamicMap (dynamic=True) or HoloMap (dynamic=False) with
-            sliders that are defined by 'cdims'.
+        dm : `holoviews.core.DynamicMap` (default) or `holoviews.core.HoloMap`
+            A `DynamicMap` (dynamic=True) or `HoloMap` (dynamic=False) with
+            sliders that are defined by `cdims`.
         """
         hv = ensure_holoviews()
         cdims = cdims or self._cdims_default
@@ -248,13 +259,13 @@ def remove_unfinished(self):
     def from_product(cls, f, learner_type, learner_kwargs, combos):
         """Create a `BalancingLearner` with learners of all combinations of
         named variables’ values. The `cdims` will be set correctly, so calling
-        `learner.plot` will be a `holoviews.HoloMap` with the correct labels.
+        `learner.plot` will be a `holoviews.core.HoloMap` with the correct labels.
 
         Parameters
         ----------
         f : callable
             Function to learn, must take arguments provided in in `combos`.
-        learner_type : BaseLearner
+        learner_type : `BaseLearner`
             The learner that should wrap the function. For example `Learner1D`.
         learner_kwargs : dict
             Keyword argument for the `learner_type`. For example `dict(bounds=[0, 1])`.

adaptive/learner/base_learner.py

@@ -11,14 +11,16 @@ class BaseLearner(metaclass=abc.ABCMeta):
     function : callable: X → Y
         The function to learn.
     data : dict: X → Y
-        'function' evaluated at certain points.
+        `function` evaluated at certain points.
         The values can be 'None', which indicates that the point
         will be evaluated, but that we do not have the result yet.
     npoints : int, optional
         The number of evaluated points that have been added to the learner.
         Subclasses do not *have* to implement this attribute.
 
-    Subclasses may define a 'plot' method that takes no parameters
+    Notes
+    -----
+    Subclasses may define a ``plot`` method that takes no parameters
     and returns a holoviews plot.
     """
 
@@ -75,9 +77,8 @@ def ask(self, n, tell_pending=True):
         n : int
             The number of points to choose.
         tell_pending : bool, default: True
-            If True, add the chosen points to this
-            learner's 'data' with 'None' for the 'y'
-            values. Set this to False if you do not
+            If True, add the chosen points to this learner's
+            `pending_points`. Set this to False if you do not
             want to modify the state of the learner.
         """
         pass

adaptive/learner/data_saver.py

@@ -8,18 +8,19 @@ class DataSaver:
 
     Parameters
     ----------
-    learner : Learner object
+    learner : `~adaptive.BaseLearner` instance
         The learner that needs to be wrapped.
     arg_picker : function
         Function that returns the argument that needs to be learned.
 
     Example
     -------
     Imagine we have a function that returns a dictionary
-    of the form: `{'y': y, 'err_est': err_est}`.
-
+    of the form: ``{'y': y, 'err_est': err_est}``.
+    
+    >>> from operator import itemgetter
     >>> _learner = Learner1D(f, bounds=(-1.0, 1.0))
-    >>> learner = DataSaver(_learner, arg_picker=operator.itemgetter('y'))
+    >>> learner = DataSaver(_learner, arg_picker=itemgetter('y'))
     """
 
     def __init__(self, learner, arg_picker):
@@ -46,28 +47,29 @@ def _ds(learner_type, arg_picker, *args, **kwargs):
 
 
 def make_datasaver(learner_type, arg_picker):
-    """Create a DataSaver of a `learner_type` that can be instantiated
+    """Create a `DataSaver` of a `learner_type` that can be instantiated
     with the `learner_type`'s key-word arguments.
 
     Parameters
     ----------
-    learner_type : BaseLearner
+    learner_type : `~adaptive.BaseLearner` type
         The learner type that needs to be wrapped.
     arg_picker : function
         Function that returns the argument that needs to be learned.
 
     Example
     -------
     Imagine we have a function that returns a dictionary
-    of the form: `{'y': y, 'err_est': err_est}`.
+    of the form: ``{'y': y, 'err_est': err_est}``.
 
-    >>> DataSaver = make_datasaver(Learner1D,
-    ...     arg_picker=operator.itemgetter('y'))
+    >>> from operator import itemgetter
+    >>> DataSaver = make_datasaver(Learner1D, arg_picker=itemgetter('y'))
     >>> learner = DataSaver(function=f, bounds=(-1.0, 1.0))
 
-    Or when using `BalacingLearner.from_product`:
+    Or when using `adaptive.BalancingLearner.from_product`:
+
     >>> learner_type = make_datasaver(adaptive.Learner1D,
-    ...     arg_picker=operator.itemgetter('y'))
+    ...     arg_picker=itemgetter('y'))
     >>> learner = adaptive.BalancingLearner.from_product(
     ...     jacobi, learner_type, dict(bounds=(0, 1)), combos)
     """

adaptive/learner/integrator_learner.py

@@ -330,7 +330,7 @@ def __init__(self, function, bounds, tol):
             The integral value in `self.bounds`.
         err : float
             The absolute error associated with `self.igral`.
-        max_ivals : int, default 1000
+        max_ivals : int, default: 1000
             Maximum number of intervals that can be present in the calculation
             of the integral. If this amount exceeds max_ivals, the interval
             with the smallest error will be discarded.

adaptive/learner/learner1D.py

@@ -94,17 +94,24 @@ class Learner1D(BaseLearner):
         If not provided, then a default is used, which uses the scaled distance
         in the x-y plane as the loss. See the notes for more details.
 
+    Attributes
+    ----------
+    data : dict
+        Sampled points and values.
+    pending_points : set
+        Points that still have to be evaluated.
+
     Notes
     -----
-    'loss_per_interval' takes 3 parameters: interval, scale, and function_values,
-    and returns a scalar; the loss over the interval.
+    `loss_per_interval` takes 3 parameters: ``interval``,  ``scale``, and
+    ``function_values``, and returns a scalar; the loss over the interval.
 
     interval : (float, float)
         The bounds of the interval.
     scale : (float, float)
         The x and y scale over all the intervals, useful for rescaling the
         interval loss.
-    function_values : dict(float -> float)
+    function_values : dict(float → float)
         A map containing evaluated function values. It is guaranteed
         to have values for both of the points in 'interval'.
     """
@@ -363,7 +370,7 @@ def tell_many(self, xs, ys, *, force=False):
                 x_left, x_right = ival
                 a, b = to_interpolate[-1] if to_interpolate else (None, None)
                 if b == x_left and (a, b) not in self.losses:
-                    # join (a, b) and (x_left, x_right) --> (a, x_right)
+                    # join (a, b) and (x_left, x_right) → (a, x_right)
                     to_interpolate[-1] = (a, x_right)
                 else:
                     to_interpolate.append((x_left, x_right))

adaptive/learner/learner2D.py

@@ -62,8 +62,8 @@ def uniform_loss(ip):
 
 
 def resolution_loss(ip, min_distance=0, max_distance=1):
-    """Loss function that is similar to the default loss function, but you can
-    set the maximimum and minimum size of a triangle.
+    """Loss function that is similar to the `default_loss` function, but you
+    can set the maximimum and minimum size of a triangle.
 
     Works with `~adaptive.Learner2D` only.
 
@@ -101,8 +101,8 @@ def resolution_loss(ip, min_distance=0, max_distance=1):
 
 def minimize_triangle_surface_loss(ip):
     """Loss function that is similar to the default loss function in the
-    `Learner1D`. The loss is the area spanned by the 3D vectors of the
-    vertices.
+    `~adaptive.Learner1D`. The loss is the area spanned by the 3D
+    vectors of the vertices.
 
     Works with `~adaptive.Learner2D` only.
 
@@ -206,15 +206,15 @@ class Learner2D(BaseLearner):
     pending_points : set
         Points that still have to be evaluated and are currently
         interpolated, see `data_combined`.
-    stack_size : int, default 10
+    stack_size : int, default: 10
         The size of the new candidate points stack. Set it to 1
         to recalculate the best points at each call to `ask`.
-    aspect_ratio : float, int, default 1
-        Average ratio of `x` span over `y` span of a triangle. If
-        there is more detail in either `x` or `y` the `aspect_ratio`
-        needs to be adjusted. When `aspect_ratio > 1` the
-        triangles will be stretched along `x`, otherwise
-        along `y`.
+    aspect_ratio : float, int, default: 1
+        Average ratio of ``x`` span over ``y`` span of a triangle. If
+        there is more detail in either ``x`` or ``y`` the ``aspect_ratio``
+        needs to be adjusted. When ``aspect_ratio > 1`` the
+        triangles will be stretched along ``x``, otherwise
+        along ``y``.
 
     Methods
     -------
@@ -239,13 +239,13 @@ class Learner2D(BaseLearner):
     This sampling procedure is not extremely fast, so to benefit from
     it, your function needs to be slow enough to compute.
 
-    'loss_per_triangle' takes a single parameter, 'ip', which is a
+    `loss_per_triangle` takes a single parameter, `ip`, which is a
     `scipy.interpolate.LinearNDInterpolator`. You can use the
-    *undocumented* attributes 'tri' and 'values' of 'ip' to get a
+    *undocumented* attributes ``tri`` and ``values`` of `ip` to get a
     `scipy.spatial.Delaunay` and a vector of function values.
     These can be used to compute the loss. The functions
-    `adaptive.learner.learner2D.areas` and
-    `adaptive.learner.learner2D.deviations` to calculate the
+    `~adaptive.learner.learner2D.areas` and
+    `~adaptive.learner.learner2D.deviations` to calculate the
     areas and deviations from a linear interpolation
     over each triangle.
     """
@@ -464,19 +464,21 @@ def plot(self, n=None, tri_alpha=0):
             Number of points in x and y. If None (default) this number is
             evaluated by looking at the size of the smallest triangle.
         tri_alpha : float
-            The opacity (0 <= tri_alpha <= 1) of the triangles overlayed on
-            top of the image. By default the triangulation is not visible.
+            The opacity ``(0 <= tri_alpha <= 1)`` of the triangles overlayed
+            on top of the image. By default the triangulation is not visible.
 
         Returns
         -------
-        plot : holoviews.Overlay or holoviews.HoloMap
-            A `holoviews.Overlay` of `holoviews.Image * holoviews.EdgePaths`.
-            If the `learner.function` returns a vector output, a
-            `holoviews.HoloMap` of the `holoviews.Overlay`s wil be returned.
+        plot : `holoviews.core.Overlay` or `holoviews.core.HoloMap`
+            A `holoviews.core.Overlay` of
+            ``holoviews.Image * holoviews.EdgePaths``. If the
+            `learner.function` returns a vector output, a
+            `holoviews.core.HoloMap` of the
+            `holoviews.core.Overlay`\s wil be returned.
 
         Notes
         -----
-        The plot object that is returned if `learner.function` returns a
+        The plot object that is returned if ``learner.function`` returns a
         vector *cannot* be used with the live_plotting functionality.
         """
         hv = ensure_holoviews()