@@ -6,33 +6,44 @@

 **Tools for adaptive parallel evaluation of functions.**

-Adaptive is an [open-source](LICENSE) Python library designed to make adaptive parallel function evaluation simple. With adaptive, you can adaptively sample functions by only supplying (in general) a function and its bounds, and run it on a cluster in a few lines of code. Since `adaptive` knows the problem it is solving, it can plot the data for you (even live as the data returns) without any boilerplate. 

+`adaptive` is an [open-source](LICENSE) 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 Binder](https://mybinder.org/v2/gh/python-adaptive/adaptive/master?filepath=learner.ipynb)) to see examples of how to use `adaptive`.

+Check out the `adaptive` [example notebook `learner.ipynb`](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`.

 **WARNING: `adaptive` is still in an early alpha development stage**

-## Implemented algorithms / learners

-We introduce the concept of a "learner", which is an object that knows:

-* the function it is trying to "learn"

-* the bounds of the function domain that you are interested in

-* the data that has been calculated (which could be empty at the start)

+## Implemented algorithms

+The core concept in `adaptive` is that of a "learner". A "learner" samples

+a function at the best places in its parameter space to get maximum

+"information" about the function. As it evaluates the function

+at more and more points in the parameter space, it gets a better idea of where

+the best places are to sample next.

-Using this information, a learner can return as many suggested points as are requested.

-Adding more data to the learner means that the newly suggested points will become better and better.

+Of course, what qualifies as the "best places" will depend on your application domain!

+`adaptive` makes some reasonable default choices, but the details of the adaptive

+sampling are completely customizable.

-The following learners are implemented

-* `Learner1D` which learns a 1D function `f: ℝ → ℝ^N`

-* `Learner2D` which learns a 2D function `f: ℝ^2 → ℝ^N`

-* `AverageLearner` which learns a 0D function that has a source of randomness

-* `IntegratorLearner` which learns the integral value of a 1D function `f: ℝ → ℝ` up to a specified tolerance

-* `BalancingLearner` which takes a list of learners and suggests points of the learners that improve the loss (quality) the most

+

+The following learners are implemented:

+* `Learner1D`, for 1D functions `f: ℝ → ℝ^N`

+* `Learner2D`, for 2D functions `f: ℝ^2 → ℝ^N`

+* `AverageLearner`, For stochastic functions where you want to average the result over many evaluations

+* `IntegratorLearner`, for when you want to intergrate a 1D function `f: ℝ → ℝ`

+* `BalancingLearner`, for when you want to run several learners at once, selecting the "best" one each time you get more points

+

+In addition to the learners, `adaptive` also provides primitives for running

+the sampling across several cores and even several machines, with built-in support

+for [`concurrent.futures`](https://docs.python.org/3/library/concurrent.futures.html),

+[`ipyparallel`](https://ipyparallel.readthedocs.io/en/latest/)

+and [`distributed`](https://distributed.readthedocs.io/en/latest/).

 ## Installation

-Adaptive works with Python 3.5 and higher on Linux, Windows, or Mac, and provides optional extensions for working with the Jupyter/IPython Notebook.

+`adaptive` works with Python 3.5 and higher on Linux, Windows, or Mac, and provides optional extensions for working with the Jupyter/IPython Notebook.

 The recommended way to install adaptive is using `pip`:

 ```bash

@@ -53,7 +64,7 @@ in the repository.

 ## Credits

 We would like to give credits to the following people:

 - Pedro Gonnet for his implementation of [`CQUAD`](https://www.gnu.org/software/gsl/manual/html_node/CQUAD-doubly_002dadaptive-integration.html), "Algorithm 4" as described in "Increasing the Reliability of Adaptive Quadrature Using Explicit Interpolants", P. Gonnet, ACM Transactions on Mathematical Software, 37 (3), art. no. 26, 2010.

-- Christoph Groth for his Python implementation of [`CQUAD`](https://gitlab.kwant-project.org/cwg/python-cquad) which served as inspiration for the [`IntegratorLearner`](adaptive/learner/integrator_learner.py)

+- Christoph Groth for his Python implementation of [`CQUAD`](https://gitlab.kwant-project.org/cwg/python-cquad) which served as basis for the [`IntegratorLearner`](adaptive/learner/integrator_learner.py)

 - 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)

 For general discussion, we have a [chat channel](https://chat.quantumtinkerer.tudelft.nl/external/channels/adaptive). If you find any bugs or have any feature suggestions please file a GitLab [issue](https://gitlab.kwant-project.org/qt/adaptive/issues/new?issue) or submit a [merge request](https://gitlab.kwant-project.org/qt/adaptive/merge_requests).