documentation improvements

Author: basnijholt

AUTHORS.md

@@ -1,4 +1,4 @@
-# Adaptive Authors
+## Authors
 Below is a list of the contributors to Adaptive:
 
 + [Anton Akhmerov](<https://antonakhmerov.org>)

README.rst

@@ -1,12 +1,10 @@
 .. summary-start
 
-.. _logo-adaptive:
+|logo| adaptive
+===============
 
-|image0| adaptive
-=================
-
-|PyPI| |Conda| |Downloads| |pipeline status| |DOI| |Binder| |Join the
-chat at https://gitter.im/python-adaptive/adaptive| |Documentation Status|
+|PyPI| |Conda| |Downloads| |Pipeline status| |DOI| |Binder| |Gitter|
+|Documentation| |GitHub|
 
 **Tools for adaptive parallel sampling of mathematical functions.**
 
@@ -126,7 +124,9 @@ 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 ``~adaptive.Learner2D``.
+  inspiration for the `~adaptive.Learner2D`.
+
+.. credits-end
 
 For general discussion, we have a `Gitter chat
 channel <https://gitter.im/python-adaptive/adaptive>`_. If you find any
@@ -136,21 +136,23 @@ or submit a `merge
 request <https://gitlab.kwant-project.org/qt/adaptive/merge_requests>`_.
 
 .. references-start
-.. |image0| image:: https://gitlab.kwant-project.org/qt/adaptive/uploads/d20444093920a4a0499e165b5061d952/logo.png
+.. |logo| image:: https://adaptive.readthedocs.io/en/latest/_static/logo.png
 .. |PyPI| image:: https://img.shields.io/pypi/v/adaptive.svg
    :target: https://pypi.python.org/pypi/adaptive
-.. |Conda| image:: https://anaconda.org/conda-forge/adaptive/badges/installer/conda.svg
+.. |Conda| image:: https://img.shields.io/badge/install%20with-conda-green.svg
    :target: https://anaconda.org/conda-forge/adaptive
-.. |Downloads| image:: https://anaconda.org/conda-forge/adaptive/badges/downloads.svg
+.. |Downloads| image:: https://img.shields.io/conda/dn/conda-forge/adaptive.svg
    :target: https://anaconda.org/conda-forge/adaptive
-.. |pipeline status| image:: https://gitlab.kwant-project.org/qt/adaptive/badges/master/pipeline.svg
+.. |Pipeline status| image:: https://gitlab.kwant-project.org/qt/adaptive/badges/master/pipeline.svg
    :target: https://gitlab.kwant-project.org/qt/adaptive/pipelines
 .. |DOI| image:: https://zenodo.org/badge/113714660.svg
-   :target: https://zenodo.org/badge/latestdoi/113714660
+   :target: https://doi.org/10.5281/zenodo.1446400
 .. |Binder| image:: https://mybinder.org/badge.svg
    :target: https://mybinder.org/v2/gh/python-adaptive/adaptive/master?filepath=learner.ipynb
-.. |Join the chat at https://gitter.im/python-adaptive/adaptive| image:: https://img.shields.io/gitter/room/nwjs/nw.js.svg
+.. |Gitter| image:: https://img.shields.io/gitter/room/nwjs/nw.js.svg
    :target: https://gitter.im/python-adaptive/adaptive
-.. |Documentation Status| image:: https://readthedocs.org/projects/adaptive/badge/?version=latest
+.. |Documentation| image:: https://readthedocs.org/projects/adaptive/badge/?version=latest
    :target: https://adaptive.readthedocs.io/en/latest/?badge=latest
+.. |GitHub| image:: https://img.shields.io/github/stars/python-adaptive/adaptive.svg?style=social
+   :target: https://github.com/python-adaptive/adaptive/stargazers
 .. references-end

adaptive/learner/average_learner.py

@@ -27,6 +27,8 @@ class AverageLearner(BaseLearner):
         Sampled points and values.
     pending_points : set
         Points that still have to be evaluated.
+    npoints : int
+        Number of evaluated points.
     """
 
     def __init__(self, function, atol=None, rtol=None):
@@ -48,7 +50,7 @@ def __init__(self, function, atol=None, rtol=None):
 
     @property
     def n_requested(self):
-        return len(self.data) + len(self.pending_points)
+        return self.npoints + len(self.pending_points)
 
     def ask(self, n, tell_pending=True):
         points = list(range(self.n_requested, self.n_requested + n))
@@ -59,7 +61,7 @@ def ask(self, n, tell_pending=True):
                           - set(self.data)
                           - set(self.pending_points))[:n]
 
-        loss_improvements = [self.loss_improvement(n) / n] * n
+        loss_improvements = [self._loss_improvement(n) / n] * n
         if tell_pending:
             for p in points:
                 self.tell_pending(p)
@@ -81,10 +83,13 @@ def tell_pending(self, n):
 
     @property
     def mean(self):
+        """The average of all values in `data`."""
         return self.sum_f / self.npoints
 
     @property
     def std(self):
+        """The corrected sample standard deviation of the values
+        in `data`."""
         n = self.npoints
         if n < 2:
             return np.inf
@@ -106,7 +111,7 @@ def loss(self, real=True, *, n=None):
         return max(standard_error / self.atol,
                    standard_error / abs(self.mean) / self.rtol)
 
-    def loss_improvement(self, n):
+    def _loss_improvement(self, n):
         loss = self.loss()
         if np.isfinite(loss):
             return loss - self.loss(n=self.npoints + n)
@@ -118,6 +123,12 @@ def remove_unfinished(self):
         self.pending_points = set()
 
     def plot(self):
+        """Returns a histogram of the evaluated data.
+
+        Returns
+        -------
+        holoviews.element.Histogram
+            A histogram of the evaluated data."""
         hv = ensure_holoviews()
         vals = [v for v in self.data.values() if v is not None]
         if not vals:

adaptive/learner/balancing_learner.py

@@ -22,7 +22,7 @@ class BalancingLearner(BaseLearner):
 
     Parameters
     ----------
-    learners : sequence of `BaseLearner`
+    learners : sequence of `~adaptive.BaseLearner`\s
         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
@@ -42,6 +42,13 @@ class BalancingLearner(BaseLearner):
             >>> cdims = (['A', 'B'], [(True, 0), (True, 1),
             ...                       (False, 0), (False, 1)])
 
+    Attributes
+    ----------
+    learners : list
+        The sequence of `~adaptive.BaseLearner`\s.
+    function : callable
+        A function that calls the functions of the underlying learners.
+        Its signature is ``function(learner_index, point)``.
     strategy : 'loss_improvements' (default), 'loss', or 'npoints'
         The points that the `BalancingLearner` choses can be either based on:
         the best 'loss_improvements', the smallest total 'loss' of the
@@ -51,13 +58,13 @@ class BalancingLearner(BaseLearner):
 
     Notes
     -----
-    This learner compares the 'loss' calculated from the "child" learners.
+    This learner compares the `loss` calculated from the "child" learners.
     This requires that the 'loss' from different learners *can be meaningfully
     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
-    undefined way.
+    of the same type*. In this case the `~adaptive.BalancingLearner` will
+    behave in an undefined way. Change the `strategy` in that case.
     """
 
     def __init__(self, learners, *, cdims=None, strategy='loss_improvements'):
@@ -81,6 +88,12 @@ def __init__(self, learners, *, cdims=None, strategy='loss_improvements'):
 
     @property
     def strategy(self):
+        """Can be either 'loss_improvements' (default), 'loss', or 'npoints'
+        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."""
         return self._strategy
 
     @strategy.setter
@@ -122,7 +135,7 @@ def _ask_and_tell_based_on_loss(self, n):
         points = []
         loss_improvements = []
         for _ in range(n):
-            losses = self.losses(real=False)
+            losses = self._losses(real=False)
             max_ind = np.argmax(losses)
             xs, ls = self.learners[max_ind].ask(1)
             points.append((max_ind, xs[0]))
@@ -165,7 +178,7 @@ def tell_pending(self, x):
         self._loss.pop(index, None)
         self.learners[index].tell_pending(x)
 
-    def losses(self, real=True):
+    def _losses(self, real=True):
         losses = []
         loss_dict = self._loss if real else self._pending_loss
 
@@ -178,7 +191,7 @@ def losses(self, real=True):
 
     @cache_latest
     def loss(self, real=True):
-        losses = self.losses(real)
+        losses = self._losses(real)
         return max(losses)
 
     def plot(self, cdims=None, plotter=None, dynamic=True):
@@ -215,8 +228,8 @@ def plot(self, cdims=None, plotter=None, dynamic=True):
         Returns
         -------
         dm : `holoviews.core.DynamicMap` (default) or `holoviews.core.HoloMap`
-            A `DynamicMap` (dynamic=True) or `HoloMap` (dynamic=False) with
-            sliders that are defined by `cdims`.
+             A `DynamicMap` ``(dynamic=True)`` or `HoloMap`
+             ``(dynamic=False)`` with sliders that are defined by `cdims`.
         """
         hv = ensure_holoviews()
         cdims = cdims or self._cdims_default
@@ -295,7 +308,7 @@ def from_product(cls, f, learner_type, learner_kwargs, combos):
         Notes
         -----
         The order of the child learners inside `learner.learners` is the same
-        as `adaptive.utils.named_product(**combos)`.
+        as ``adaptive.utils.named_product(**combos)``.
         """
         learners = []
         arguments = named_product(**combos)
@@ -313,7 +326,7 @@ def save(self, folder, compress=True):
         folder : str
             Directory in which the learners's data will be saved.
         compress : bool, default True
-            Compress the data upon saving using 'gzip'. When saving
+            Compress the data upon saving using `gzip`. When saving
             using compression, one must load it with compression too.
 
         Notes
@@ -364,7 +377,7 @@ def load(self, folder, compress=True):
 
         Example
         -------
-        See the example in the 'BalancingLearner.save' doc-string.
+        See the example in the `BalancingLearner.save` doc-string.
         """
         for l in self.learners:
             l.load(os.path.join(folder, l.fname), compress=compress)

adaptive/learner/base_learner.py

@@ -20,6 +20,9 @@ class BaseLearner(metaclass=abc.ABCMeta):
     npoints : int, optional
         The number of evaluated points that have been added to the learner.
         Subclasses do not *have* to implement this attribute.
+    pending_points : set, optional
+        Points that have been requested but have not been evaluated yet.
+        Subclasses do not *have* to implement this attribute.
 
     Notes
     -----
@@ -118,10 +121,11 @@ def save(self, fname=None, compress=True):
 
         Notes
         -----
-        There are __two ways__ of naming the files:
-        1. Using the 'fname' argument in 'learner.save(fname='example.p')
-        2. Setting the 'fname' attribute, like
-           'learner.fname = "data/example.p"' and then 'learner.save()'.
+        There are **two ways** of naming the files:
+
+        1. Using the ``fname`` argument in ``learner.save(fname='example.p')``
+        2. Setting the ``fname`` attribute, like
+           ``learner.fname = "data/example.p"`` and then ``learner.save()``.
         """
         fname = fname or self.fname
         data = self._get_data()
@@ -142,7 +146,7 @@ def load(self, fname=None, compress=True):
 
         Notes
         -----
-        See the notes in the 'BaseLearner.save' doc-string.
+        See the notes in the `save` doc-string.
         """
         fname = fname or self.fname
         with suppress(FileNotFoundError, EOFError):
@@ -157,6 +161,9 @@ def __setstate__(self, state):
 
     @property
     def fname(self):
+        """Filename for the learner when it is saved (or loaded) using
+        `~adaptive.BaseLearner.save` (or `~adaptive.BaseLearner.load` ).
+        """
         # This is a property because then it will be availible in the DataSaver
         try:
             return self._fname

adaptive/learner/data_saver.py

@@ -35,11 +35,13 @@ def __init__(self, learner, arg_picker):
     def __getattr__(self, attr):
         return getattr(self.learner, attr)
 
+    @copy_docstring_from(BaseLearner.tell)
     def tell(self, x, result):
         y = self.arg_picker(result)
         self.extra_data[x] = result
         self.learner.tell(x, y)
 
+    @copy_docstring_from(BaseLearner.tell_pending)
     def tell_pending(self, x):
         self.learner.tell_pending(x)
 

adaptive/learner/integrator_learner.py

@@ -487,6 +487,7 @@ def _fill_stack(self):
 
     @property
     def npoints(self):
+        """Number of evaluated points."""
         return len(self.done_points)
 
     @property