|
| 1 | +<!-- badges-start --> |
| 2 | + |
| 3 | +#  adaptive |
| 4 | + |
| 5 | +[](https://mybinder.org/v2/gh/python-adaptive/adaptive/master?filepath=example-notebook.ipynb) |
| 6 | +[](https://anaconda.org/conda-forge/adaptive) |
| 7 | +[](https://codecov.io/gh/python-adaptive/adaptive) |
| 8 | +[](https://doi.org/10.5281/zenodo.1182437) |
| 9 | +[](https://adaptive.readthedocs.io/en/latest/?badge=latest) |
| 10 | +[](https://anaconda.org/conda-forge/adaptive) |
| 11 | +[](https://github.com/python-adaptive/adaptive/stargazers) |
| 12 | +[](https://gitter.im/python-adaptive/adaptive) |
| 13 | +[](https://dev.azure.com/python-adaptive/adaptive/_build/latest?definitionId=6?branchName=master) |
| 14 | +[](https://pypi.python.org/pypi/adaptive) |
| 15 | + |
| 16 | +> *Adaptive*: parallel active learning of mathematical functions. |
| 17 | +
|
| 18 | +<!-- badges-end --> |
| 19 | + |
| 20 | +<!-- summary-start --> |
| 21 | + |
| 22 | +`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, rather than unnecessarily computing *all* points on a dense grid. |
| 23 | +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. |
| 24 | + |
| 25 | +`adaptive` excels on computations where each function evaluation takes *at least* ≈50ms due to the overhead of picking potentially interesting points. |
| 26 | + |
| 27 | +Run the `adaptive` example notebook [live on Binder](https://mybinder.org/v2/gh/python-adaptive/adaptive/master?filepath=example-notebook.ipynb) to see examples of how to use `adaptive` or visit the [tutorial on Read the Docs](https://adaptive.readthedocs.io/en/latest/tutorial/tutorial.html). |
| 28 | + |
| 29 | +<!-- summary-end --> |
| 30 | + |
| 31 | +## Implemented algorithms |
| 32 | + |
| 33 | +The core concept in `adaptive` is that of a *learner*. |
| 34 | +A *learner* samples a function at the best places in its parameter space to get maximum “information” about the function. |
| 35 | +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. |
| 36 | + |
| 37 | +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. |
| 38 | + |
| 39 | +The following learners are implemented: |
| 40 | + |
| 41 | +<!-- not-in-documentation-start --> |
| 42 | + |
| 43 | +- `Learner1D`, for 1D functions `f: ℝ → ℝ^N`, |
| 44 | +- `Learner2D`, for 2D functions `f: ℝ^2 → ℝ^N`, |
| 45 | +- `LearnerND`, for ND functions `f: ℝ^N → ℝ^M`, |
| 46 | +- `AverageLearner`, for random variables where you want to average the result over many evaluations, |
| 47 | +- `AverageLearner1D`, for stochastic 1D functions where you want to estimate the mean value of the function at each point, |
| 48 | +- `IntegratorLearner`, for when you want to intergrate a 1D function `f: ℝ → ℝ`. |
| 49 | +- `BalancingLearner`, for when you want to run several learners at once, selecting the “best” one each time you get more points. |
| 50 | + |
| 51 | +Meta-learners (to be used with other learners): |
| 52 | + |
| 53 | +- `BalancingLearner`, for when you want to run several learners at once, selecting the “best” one each time you get more points, |
| 54 | +- `DataSaver`, for when your function doesn't just return a scalar or a vector. |
| 55 | + |
| 56 | +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 |
| 57 | +[concurrent.futures](https://docs.python.org/3/library/concurrent.futures.html), |
| 58 | +[mpi4py](https://mpi4py.readthedocs.io/en/stable/mpi4py.futures.html), |
| 59 | +[loky](https://loky.readthedocs.io/en/stable/), |
| 60 | +[ipyparallel](https://ipyparallel.readthedocs.io/en/latest/), and |
| 61 | +[distributed](https://distributed.readthedocs.io/en/latest/). |
| 62 | + |
| 63 | +## Examples |
| 64 | + |
| 65 | +Adaptively learning a 1D function (the `gif` below) and live-plotting the process in a Jupyter notebook is as easy as |
| 66 | + |
| 67 | +```python |
| 68 | +from adaptive import notebook_extension, Runner, Learner1D |
| 69 | + |
| 70 | +notebook_extension() |
| 71 | + |
| 72 | + |
| 73 | +def peak(x, a=0.01): |
| 74 | + return x + a**2 / (a**2 + x**2) |
| 75 | + |
| 76 | + |
| 77 | +learner = Learner1D(peak, bounds=(-1, 1)) |
| 78 | +runner = Runner(learner, goal=lambda l: l.loss() < 0.01) |
| 79 | +runner.live_info() |
| 80 | +runner.live_plot() |
| 81 | +``` |
| 82 | + |
| 83 | +<img src="https://user-images.githubusercontent.com/6897215/38739170-6ac7c014-3f34-11e8-9e8f-93b3a3a3d61b.gif" width='20%'> </img> <img src="https://user-images.githubusercontent.com/6897215/35219611-ac8b2122-ff73-11e7-9332-adffab64a8ce.gif" width='40%'> </img> <img src="https://user-images.githubusercontent.com/6897215/47256441-d6d53700-d480-11e8-8224-d1cc49dbdcf5.gif" width='20%'> </img> |
| 84 | + |
| 85 | +<!-- not-in-documentation-end --> |
| 86 | + |
| 87 | +## Installation |
| 88 | + |
| 89 | +`adaptive` works with Python 3.7 and higher on Linux, Windows, or Mac, and provides optional extensions for working with the Jupyter/IPython Notebook. |
| 90 | + |
| 91 | +The recommended way to install adaptive is using `conda`: |
| 92 | + |
| 93 | +```bash |
| 94 | +conda install -c conda-forge adaptive |
| 95 | +``` |
| 96 | + |
| 97 | +`adaptive` is also available on PyPI: |
| 98 | + |
| 99 | +```bash |
| 100 | +pip install "adaptive[notebook]" |
| 101 | +``` |
| 102 | + |
| 103 | +The `[notebook]` above will also install the optional dependencies for running `adaptive` inside a Jupyter notebook. |
| 104 | + |
| 105 | +To use Adaptive in Jupyterlab, you need to install the following labextensions. |
| 106 | + |
| 107 | +```bash |
| 108 | +jupyter labextension install @jupyter-widgets/jupyterlab-manager |
| 109 | +jupyter labextension install @pyviz/jupyterlab_pyviz |
| 110 | +``` |
| 111 | + |
| 112 | +## Development |
| 113 | + |
| 114 | +Clone the repository and run `pip install -e ".[notebook,testing,other]"` to add a link to the cloned repo into your Python path: |
| 115 | + |
| 116 | +```bash |
| 117 | +git clone [email protected]:python-adaptive/adaptive.git |
| 118 | +cd adaptive |
| 119 | +pip install -e ".[notebook,testing,other]" |
| 120 | +``` |
| 121 | + |
| 122 | +We highly recommend using a Conda environment or a virtualenv to manage the versions of your installed packages while working on `adaptive`. |
| 123 | + |
| 124 | +In order to not pollute the history with the output of the notebooks, please setup the git filter by executing |
| 125 | + |
| 126 | +```bash |
| 127 | +python ipynb_filter.py |
| 128 | +``` |
| 129 | + |
| 130 | +in the repository. |
| 131 | + |
| 132 | +We implement several other checks in order to maintain a consistent code style. We do this using [pre-commit](https://pre-commit.com), execute |
| 133 | + |
| 134 | +```bash |
| 135 | +pre-commit install |
| 136 | +``` |
| 137 | + |
| 138 | +in the repository. |
| 139 | + |
| 140 | +## Citing |
| 141 | + |
| 142 | +If you used Adaptive in a scientific work, please cite it as follows. |
| 143 | + |
| 144 | +```bib |
| 145 | +@misc{Nijholt2019, |
| 146 | + doi = {10.5281/zenodo.1182437}, |
| 147 | + author = {Bas Nijholt and Joseph Weston and Jorn Hoofwijk and Anton Akhmerov}, |
| 148 | + title = {\textit{Adaptive}: parallel active learning of mathematical functions}, |
| 149 | + publisher = {Zenodo}, |
| 150 | + year = {2019} |
| 151 | +} |
| 152 | +``` |
| 153 | + |
| 154 | +## Credits |
| 155 | + |
| 156 | +We would like to give credits to the following people: |
| 157 | + |
| 158 | +- 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. |
| 159 | +- Pauli Virtanen for his `AdaptiveTriSampling` script (no longer available online since SciPy Central went down) which served as inspiration for the `adaptive.Learner2D`. |
| 160 | + |
| 161 | +<!-- credits-end --> |
| 162 | + |
| 163 | +For general discussion, we have a [Gitter chat channel](https://gitter.im/python-adaptive/adaptive). If you find any bugs or have any feature suggestions please file a GitHub [issue](https://github.com/python-adaptive/adaptive/issues/new) or submit a [pull request](https://github.com/python-adaptive/adaptive/pulls). |
| 164 | + |
| 165 | +<!-- references-start --> |
| 166 | + |
| 167 | +<!-- references-end --> |
0 commit comments