Skip to content

Commit 738e352

Browse files
committed
Address the README review: runnable script example, scope, executors
- Make the script example self-contained (it used peak from the notebook example) and show to_numpy() in it. - Say that adaptive is meant for functions of a few parameters. - Explain what the loss function is and point to the built-in alternatives and the custom loss tutorial. - Say that the runners use all local cores by default, how to pass another executor, and link the parallelism tutorial. - Install with plain pip install adaptive; the [notebook] extra adds live plotting and pandas for to_dataframe(). - Development: add the test command; the notebook git filter needs nbconvert and only matters for example-notebook.ipynb. - Move the animation caption into the summary snippet, so the docs home page shows it too; label the conda downloads badge; fix the CQUAD link. - Parallelism tutorial: drop the stale claim that Windows defaults to distributed.Client; loky is the default everywhere.
1 parent 6d04d72 commit 738e352

2 files changed

Lines changed: 23 additions & 18 deletions

File tree

‎README.md‎

Lines changed: 23 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77
[![Python](https://img.shields.io/pypi/pyversions/adaptive.svg)](https://pypi.org/project/adaptive/)
88
[![Documentation](https://img.shields.io/readthedocs/adaptive)](https://adaptive.readthedocs.io/en/latest/)
99
[![Coverage](https://img.shields.io/codecov/c/github/python-adaptive/adaptive)](https://codecov.io/gh/python-adaptive/adaptive)
10-
[![Downloads](https://img.shields.io/conda/dn/conda-forge/adaptive.svg)](https://anaconda.org/conda-forge/adaptive)
10+
[![Downloads](https://img.shields.io/conda/dn/conda-forge/adaptive.svg?label=conda%20downloads)](https://anaconda.org/conda-forge/adaptive)
1111
[![DOI](https://img.shields.io/badge/doi-10.5281%2Fzenodo.1182437-blue.svg)](https://doi.org/10.5281/zenodo.1182437)
1212
[![Binder](https://mybinder.org/badge.svg)](https://mybinder.org/v2/gh/python-adaptive/adaptive/main?filepath=example-notebook.ipynb)
1313

@@ -20,13 +20,14 @@ You supply a function and its bounds, and `adaptive` evaluates it at the "best"
2020
With a few lines of code you can run the evaluations on a computing cluster, live-plot the data as it comes in, and fine-tune the sampling algorithm.
2121

2222
`adaptive` works best when each function evaluation takes *at least* ≈50 ms, because picking the next points has some overhead.
23+
It is meant for functions of a few parameters: with more dimensions, `LearnerND` quickly becomes slower and less effective.
2324

2425
Try the example notebook [on Binder](https://mybinder.org/v2/gh/python-adaptive/adaptive/main?filepath=example-notebook.ipynb) or read the [tutorial](https://adaptive.readthedocs.io/en/latest/tutorial/tutorial/).
2526

26-
<!-- --8<-- [end:summary] -->
27-
2827
With the same number of points, adaptive sampling resolves features that a homogeneous grid misses:
2928

29+
<!-- --8<-- [end:summary] -->
30+
3031
<p align="center">
3132
<img src="https://raw.githubusercontent.com/python-adaptive/adaptive/main/docs/_static/readme/learner1d.gif" width="43%" alt="Learner1D: homogeneous grid versus adaptive sampling of a sharp peak">
3233
<img src="https://raw.githubusercontent.com/python-adaptive/adaptive/main/docs/_static/readme/learner2d.gif" width="36%" alt="Learner2D: homogeneous grid versus adaptive triangulation of a ring">
@@ -59,11 +60,17 @@ In a script, use `BlockingRunner`, which returns once the goal is reached:
5960
```python
6061
from adaptive import BlockingRunner, Learner1D
6162

63+
64+
def peak(x, a=0.01):
65+
return x + a**2 / (a**2 + x**2)
66+
67+
6268
learner = Learner1D(peak, bounds=(-1, 1))
6369
BlockingRunner(learner, loss_goal=0.01)
70+
data = learner.to_numpy() # array with columns x, y
6471
```
6572

66-
Afterwards, `learner.to_numpy()` returns the data as a NumPy array, and `learner.to_dataframe()` as a pandas DataFrame.
73+
`learner.to_dataframe()` returns the same data as a pandas DataFrame (pandas comes with the `[notebook]` extra).
6774

6875
<!-- --8<-- [start:implemented-algorithms] -->
6976

@@ -74,7 +81,8 @@ A learner samples a function at the points in its parameter space that tell it t
7481
As it evaluates more points, it gets a better idea of where to sample next.
7582

7683
What the "best" points are depends on your application.
77-
`adaptive` makes reasonable default choices, but the details of the sampling are completely customizable.
84+
Each learner ranks candidate points with a *loss function*.
85+
The default losses put more points where the function changes quickly; you can pass a built-in alternative, such as `curvature_loss_function()` or `resolution_loss_function()`, or write your own (see the [custom loss tutorial](https://adaptive.readthedocs.io/en/latest/tutorial/tutorial.custom_loss/)).
7886

7987
The following learners are implemented:
8088

@@ -100,6 +108,9 @@ In addition to the learners, `adaptive` provides primitives for running the samp
100108
[ipyparallel](https://ipyparallel.readthedocs.io/en/latest/), and
101109
[distributed](https://distributed.readthedocs.io/en/latest/).
102110

111+
By default, both runners evaluate the function in parallel on all cores of the local machine, using loky.
112+
To use one of the others, pass it as `executor`, for example `Runner(learner, executor=distributed.Client())`; the [parallelism tutorial](https://adaptive.readthedocs.io/en/latest/tutorial/tutorial.parallelism/) has an example for each.
113+
103114
<!-- --8<-- [start:rest] -->
104115

105116
## Installation
@@ -115,10 +126,10 @@ conda install -c conda-forge adaptive
115126
or from PyPI:
116127

117128
```bash
118-
pip install "adaptive[notebook]"
129+
pip install adaptive
119130
```
120131

121-
The `[notebook]` extra installs the dependencies for live plotting and widgets in JupyterLab and Jupyter Notebook; no Jupyter extensions are needed.
132+
Add the `[notebook]` extra (`pip install "adaptive[notebook]"`) for live plotting and widgets in JupyterLab and Jupyter Notebook, and for `to_dataframe()`; no Jupyter extensions are needed.
122133

123134
### Faster triangulation (optional)
124135

@@ -143,20 +154,16 @@ pip install -e ".[notebook,test,other]"
143154

144155
We recommend a virtual environment, for example with [uv](https://docs.astral.sh/uv/) (`uv sync --extra notebook --extra test --extra other`) or Conda.
145156

146-
To avoid polluting the history with notebook output, set up the git filter by running
147-
148-
```bash
149-
python ipynb_filter.py
150-
```
151-
152-
in the repository.
153-
154157
We use [pre-commit](https://pre-commit.com) for a consistent code style; install the hooks with
155158

156159
```bash
157160
pre-commit install
158161
```
159162

163+
Run the tests with `pytest`.
164+
165+
If you edit `example-notebook.ipynb`, install `nbconvert` and run `python ipynb_filter.py` once, so git strips the notebook output on commit.
166+
160167
### Building the documentation
161168

162169
The documentation is built with [Zensical](https://zensical.org).
@@ -190,7 +197,7 @@ The algorithms are described in more detail in a [draft paper](https://github.co
190197

191198
We would like to give credits to the following people:
192199

193-
- 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.
200+
- Pedro Gonnet for his implementation of [CQUAD](https://www.gnu.org/software/gsl/doc/html/integration.html#cquad-doubly-adaptive-integration), "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.
194201
- Pauli Virtanen for his `AdaptiveTriSampling` script (no longer available online since SciPy Central went down), which served as inspiration for `adaptive.Learner2D`.
195202

196203
<!-- --8<-- [end:rest] -->

‎docs/notebooks/tutorial/tutorial.parallelism.md‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -45,8 +45,6 @@ runner.live_plot()
4545

4646
## `distributed.Client`
4747

48-
On Windows by default [`adaptive.Runner`][adaptive.Runner] uses a `distributed.Client`.
49-
5048
```python
5149
import distributed
5250

0 commit comments

Comments
 (0)