Home

Awesome

logo Adaptive: Parallel Active Learning of Mathematical Functions :brain::1234:

<!-- badges-start -->

Binder Conda Coverage DOI Documentation Downloads GitHub Gitter PyPI

<!-- badges-end --> <!-- summary-start -->

Adaptive is an open-source Python library that streamlines adaptive parallel function evaluations. Rather than calculating all points on a dense grid, it intelligently selects the "best" points in the parameter space based on your provided function and bounds. With minimal code, you can perform evaluations on a computing cluster, display live plots, and optimize the adaptive sampling algorithm.

Adaptive is most efficient for computations where each function evaluation takes at least ≈50ms due to the overhead of selecting potentially interesting points.

To see Adaptive in action, try the example notebook on Binder or explore the tutorial on Read the Docs.

<!-- summary-end --> <details><summary><b><u>[ToC]</u></b> 📚</summary> <!-- START doctoc generated TOC please keep comment here to allow auto update --> <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --> <!-- END doctoc generated TOC please keep comment here to allow auto update --> </details> <!-- key-features-start -->

:star: Key features

<!-- key-features-end -->

:rocket: Example usage

Adaptively learning a 1D function and live-plotting the process in a Jupyter notebook:

from adaptive import notebook_extension, Runner, Learner1D

notebook_extension()


def peak(x, a=0.01):
    return x + a**2 / (a**2 + x**2)


learner = Learner1D(peak, bounds=(-1, 1))
runner = Runner(learner, loss_goal=0.01)
runner.live_info()
runner.live_plot()

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

:floppy_disk: Exporting Data

You can export the learned data as a NumPy array:

data = learner.to_numpy()

If you have Pandas installed, you can also export the data as a DataFrame:

df = learner.to_dataframe()
<!-- implemented-algorithms-start -->

:test_tube: Implemented Algorithms

The core concept in adaptive is the learner. A learner samples a function at the most interesting locations within its parameter space, allowing for optimal sampling of the function. As the function is evaluated at more points, the learner improves its understanding of the best locations to sample next.

The definition of the "best locations" depends on your application domain. While adaptive provides sensible default choices, the adaptive sampling process can be fully customized.

The following learners are implemented:

<!-- implemented-algorithms-end -->

Meta-learners (to be used with other learners):

In addition to learners, adaptive offers primitives for parallel sampling across multiple cores or machines, with built-in support for: concurrent.futures, mpi4py, loky, ipyparallel, and distributed.

<!-- rest-start -->

:package: Installation

adaptive works with Python 3.7 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 conda:

conda install -c conda-forge adaptive

adaptive is also available on PyPI:

pip install "adaptive[notebook]"

The [notebook] above will also install the optional dependencies for running adaptive inside a Jupyter notebook.

To use Adaptive in Jupyterlab, you need to install the following labextensions.

jupyter labextension install @jupyter-widgets/jupyterlab-manager
jupyter labextension install @pyviz/jupyterlab_pyviz

:wrench: Development

Clone the repository and run pip install -e ".[notebook,testing,other]" to add a link to the cloned repo into your Python path:

git clone git@github.com:python-adaptive/adaptive.git
cd adaptive
pip install -e ".[notebook,testing,other]"

We recommend using a Conda environment or a virtualenv for package management during Adaptive development.

To avoid polluting the history with notebook output, set up the git filter by running:

python ipynb_filter.py

in the repository.

To maintain consistent code style, we use pre-commit. Install it by running:

pre-commit install

in the repository.

:books: Citing

If you used Adaptive in a scientific work, please cite it as follows.

@misc{Nijholt2019,
  doi = {10.5281/zenodo.1182437},
  author = {Bas Nijholt and Joseph Weston and Jorn Hoofwijk and Anton Akhmerov},
  title = {\textit{Adaptive}: parallel active learning of mathematical functions},
  publisher = {Zenodo},
  year = {2019}
}

:page_facing_up: Draft Paper

If you're interested in the scientific background and principles behind Adaptive, we recommend taking a look at the draft paper that is currently being written. This paper provides a comprehensive overview of the concepts, algorithms, and applications of the Adaptive library.

:sparkles: Credits

We would like to give credits to the following people:

<!-- rest-end -->

For general discussion, we have a Gitter chat channel. If you find any bugs or have any feature suggestions please file a GitHub issue or submit a pull request.