Resolve "(Learner1D) add possibility to use the direct neighbors in the loss"

Closes #119 (closed)

Currently works for one R^1 \to R^1

Still have to make it work for R^1 \to R^N

Also performance is actually quite good. As in: the learner slows down about 1.5 times. Going (on my laptop) from 3 seconds per 1000 points to 4.5 seconds per 1000 points.

Which, I believe, will be more than compensated by the fact that the chosen points are generally better

adaptive/learner/learner1D.py

@@ -17,29 +17,30 @@ from ..utils import cache_latest
 
 def use_nn_neighbors(n):
     """Decorator to specify how many neighboring intervals the loss function uses.
-    
-    This decorator can wrap around a loss function to let `~adaptive.Learner1D` 
-    know that you would like to look at the N-nearest neighboring intervals.
-    
-    The loss function is then guaranteed to receive the data of at least the 
-    nn-neighbors and a dict that tells you what the neighboring points of these 
-    are. And the `~Learner1D` will then make sure that the loss is updated
-    whenever one of the nn-neighbours changes.
+
+    Wraps loss functions to indicate that they expect intervals together
+    with ``n`` nearest neighbors
+
+    The loss function is then guaranteed to receive the data of at least the
+    N nearest neighbors (``nn_neighbors``) in a dict that tells you what the
+    neighboring points of these are. And the `~adaptive.Learner1D` will
+    then make sure that the loss is updated whenever one of the
+    ``nn_neighbors`` changes.
 
     Examples
     --------
 
-    This is a part of the curvature loss function
+    The next function is a part of the `get_curvature_loss` function.
 
     >>> @use_nn_neighbors(1)
     ... def triangle_loss(interval, scale, data, neighbors):
     ...     x_left, x_right = interval
     ...     xs = [neighbors[x_left][0], x_left, x_right, neighbors[x_right][1]]
-    ...     # at the boundary, neighbours[<left boundary x>] is (None, <some other x>)
-    ...     xs = [x for x in xs if x is not None] 
+    ...     # at the boundary, neighbors[<left boundary x>] is (None, <some other x>)
+    ...     xs = [x for x in xs if x is not None]
     ...     if len(xs) <= 2:
     ...         return (x_right - x_left) / scale[0]
-    ...     
+    ...
     ...     y_scale = scale[1] or 1
     ...     ys_scaled = [data[x] / y_scale for x in xs]
     ...     xs_scaled = [x / scale[0] for x in xs]
@@ -50,21 +51,16 @@ def use_nn_neighbors(n):
     Or you may define a loss that favours the (local) minima of a function.
 
     >>> @use_nn_neighbors(1)
-    ... def loss(interval, scale, data, neighbors):
+    ... def local_minima_resolving_loss(interval, scale, data, neighbors):
     ...     x_left, x_right = interval
     ...     n_left = neighbors[x_left][0]
     ...     n_right = neighbors[x_right][1]
-    ...     is_min = True
-    ...
-    ...     if n_left is not None and data[x_left] > data[n_left]:
-    ...         is_min = False
-    ...     if n_right is not None and data[x_right] > data[n_right]:
-    ...         is_min = False
-    ...     
     ...     loss = (x_right - x_left) / scale[0]
-    ...     
-    ...     if is_min: 
+    ...
+    ...     if not ((n_left is not None and data[x_left] > data[n_left])
+    ...         or (n_right is not None and data[x_right] > data[n_right])):
     ...         return loss * 100
+    ...
     ...     return loss
     """
     def _wrapped(loss_per_interval):
@@ -203,12 +199,6 @@ class Learner1D(BaseLearner):
         A function that returns the loss for a single interval of the domain.
         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.
-    nn_neighbors : int, optional, default: None
-        The number of neighboring intervals that the loss function
-        takes into account. If ``loss_per_interval`` doesn't use the neighbors
-        at all, then it should be 0. By default we try to access the
-        ``loss_per_interval.nn_neighbors`` attribute which is set for all
-        implemented loss functions.
 
     Attributes
     ----------
@@ -221,7 +211,11 @@ class Learner1D(BaseLearner):
     -----
     `loss_per_interval` takes 4 parameters: ``interval``,  ``scale``,
     ``data``, and ``neighbors``, and returns a scalar; the loss over
-    the interval.
+    the interval. The `loss_per_interval` function should also have
+    an attribute `nn_neighbors` that indicates how many of the neighboring
+    intervals to `interval` are used. If `loss_per_interval` doesn't
+    have such an attribute, it's assumed that is uses **no** neighboring
+    intervals. Also see the `use_nn_neighbors` decorator.
     interval : (float, float)
         The bounds of the interval.
     scale : (float, float)
@@ -232,6 +226,8 @@ class Learner1D(BaseLearner):
         to have values for both of the points in 'interval'.
     neighbors : dict(float → (float, float))
         A map containing points as keys to its neighbors as a tuple.
+        At the left ``x_left`` and right ``x_left`` most boundary it has
+        ``x_left: (None, float)`` and ``x_right: (float, None)``.
     """
 
     def __init__(self, function, bounds, loss_per_interval=None):