adaptive

Adaptive sampling is used to approximate functions by concentrating sample points in areas with sharp features or rapid changes. This allows for more accurate function representation and faster convergence compared to uniform sampling, especially when using fewer total points.

In the adaptive benchmarks, effectiveness is measured using an error ratio: the ratio of the error produced by a homogeneous (uniform) learner to the error produced by the adaptive learner.

Key Concepts:

• Adaptive Learner: Uses adaptive sampling to focus on complex regions.
• Homogeneous Learner: Uses a uniform grid of points.
• Benchmark Functions: The showcase includes 1D and 2D functions such as sharp peaks, Gaussian, sinusoidal, exponential decay, and Lorentzian functions.

A learner is the core abstraction in adaptive. It is responsible for sampling a function at the most 'interesting' locations within its parameter space. As more points are evaluated, the learner improves its model of the function to optimize subsequent sampling locations.

Available Learners:

• Learner1D: For 1D functions $f: \mathbb{R} \to \mathbb{R}^N$.
• Learner2D: For 2D functions $f: \mathbb{R}^2 \to \mathbb{R}^N$.
• LearnerND: For ND functions $f: \mathbb{R}^N \to \mathbb{R}^M$.
• AverageLearner: For random variables, allowing averaging of results over multiple evaluations.
• AverageLearner1D: For stochastic 1D functions, estimating the mean value at each point.
• IntegratorLearner: For integrating a 1D function $f: \mathbb{R} \to \mathbb{R}$.

Error in the benchmarks is estimated using the L1 norm of the difference between the true function values and the interpolated values.

The calculation process follows these steps:

1. Create an adaptive learner and a homogeneous learner for a benchmark function.
2. Complete the adaptive learning process.
3. Compare the interpolated values from the adaptive learner against the true function values evaluated at the specific points used by the homogeneous learner.
4. Calculate the L1 norm, which represents the average of the absolute differences between the true and interpolated values (specifically calculated as the square root of the mean of the squared differences).

The adaptive.Runner class supports parallel evaluation of functions by accepting an executor argument. It works with any framework that implements a PEP 3148 compliant executor that returns concurrent.futures.Future objects.

By default, adaptive.Runner uses loky.get_reusable_executor(), which is highly flexible because it uses cloudpickle for serialization. This allows you to use functions defined interactively (like in a Jupyter notebook), as well as closures and lambdas.

from loky import get_reusable_executor

ex = get_reusable_executor()
f = lambda x: x
learner = adaptive.Learner1D(f, bounds=(-1, 1))

runner = adaptive.Runner(learner, loss_goal=0.01, executor=ex)
runner.live_info()

By default, adaptive samples more points where the Euclidean distance between neighbors is large. To focus sampling on regions with high curvature, specify a curvature loss function using the loss_per_interval parameter in Learner1D.

Available loss functions from adaptive.learner.learner1D include:

• curvature_loss_function(): Focuses on high curvature regions.
• default_loss(): The standard Euclidean distance-based loss.
• uniform_loss(): Results in homogeneous sampling.

You can use adaptive.runner.simple for a non-parallel, blocking execution when testing different loss strategies.

By default, adaptive runners are non-deterministic because they evaluate functions in parallel and process results as they become available. To ensure reproducibility, you have two options:

1. Use adaptive.runner.simple: This is the simplest way to run a learner deterministically. It blocks execution until the learner is finished.
2. Use SequentialExecutor: If you want to keep using the non-blocking adaptive.Runner but require determinism, pass a SequentialExecutor to the executor argument.

# Option 1: Simple blocking deterministic runner
adaptive.runner.simple(learner, loss_goal=0.01)

# Option 2: Non-blocking deterministic runner
from adaptive.runner import SequentialExecutor
runner = adaptive.Runner(learner, executor=SequentialExecutor(), loss_goal=0.01)

To evaluate the effectiveness of adaptive sampling, you can compare its error against a 'homogeneous' (uniform) learner.

An error_ratio can be calculated as: error_ratio = uniform_error / learner_error

• An error_ratio > 1 indicates that the adaptive learner is more efficient (achieving lower error with the same number of points) than uniform sampling.
• An error_ratio close to 1 suggests that adaptive sampling provides little advantage over uniform sampling (common for smooth functions like Gaussians).

When running adaptive in a Jupyter notebook, adaptive.Runner operates in an asyncio task that runs concurrently with the kernel.

CRITICAL: If you block the IPython kernel (e.g., using a while loop or time.sleep), the runner will stop making progress.

Do NOT do this:

while not runner.task.done():
    pass

If you do not need live-updating plots and simply want to run the learner until completion in a blocking manner, use adaptive.BlockingRunner instead.

Runners can be configured to stop based on a goal function. This function accepts a learner object and returns True to stop the execution or False to continue.

You can provide a custom function or use built-in convenience parameters:

• loss_goal=x: Stops when the loss falls below threshold x.
• npoints_goal=n: Stops after n points have been sampled.

For more complex logic, you can use adaptive.runner.auto_goal or adaptive.runner.stop_after to generate these goal functions.

The functions used in the standard benchmark tutorials are analytical and computationally inexpensive.

Real-world application: While these benchmarks demonstrate the principle, adaptive sampling is most beneficial in real-world scenarios involving expensive simulations where function evaluations are computationally demanding or time-consuming. For more complex use cases, refer to the gallery.