{
"cells": [
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# Adaptive"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"[`adaptive`](https://gitlab.kwant-project.org/qt/adaptive-evaluation) is a package for adaptively sampling functions with support for parallel evaluation.\n",
"\n",
"This is an introductory notebook that shows some basic use cases.\n",
"\n",
"`adaptive` needs the following packages:\n",
"\n",
"+ Python 3.6\n",
"+ `holoviews`\n",
"+ `bokeh`"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"import adaptive\n",
"adaptive.notebook_extension()\n",
"\n",
"# Import modules that are used in multiple cells\n",
"import holoviews as hv\n",
"import numpy as np\n",
"from functools import partial\n",
"import random"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# 1D function learner"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"We start with the most common use-case: sampling a 1D function $\\ f: ℝ → ℝ$.\n",
"\n",
"We will use the following function, which is a smooth (linear) background with a sharp peak at a random location:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"offset = random.uniform(-0.5, 0.5)\n",
"\n",
"def f(x, offset=offset, wait=True):\n",
" from time import sleep\n",
" from random import random\n",
"\n",
" a = 0.01\n",
" if wait:\n",
" sleep(random()*10)\n",
" return x + a**2 / (a**2 + (x - offset)**2)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"We start by initializing a 1D \"learner\", which will suggest points to evaluate, and adapt its suggestions as more and more points are evaluated."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"learner = adaptive.Learner1D(f, bounds=(-1, 1))"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Next we create a \"runner\" that will request points from the learner and evaluate 'f' on them.\n",
"\n",
"By default the runner will evaluate the points in parallel using local processes ([`concurrent.futures.ProcessPoolExecutor`](https://docs.python.org/3/library/concurrent.futures.html#processpoolexecutor))."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"# The end condition is when the \"loss\" is less than 0.1. In the context of the\n",
"# 1D learner this means that we will resolve features in 'func' with width 0.1 or wider.\n",
"runner = adaptive.Runner(learner, goal=lambda l: l.loss() < 0.01)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"When instantiated in a Jupyter notebook the runner does its job in the background and does not block the IPython kernel.\n",
"We can use this to create a plot that updates as new data arrives:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"adaptive.live_plot(runner)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"We can now compare the adaptive sampling to a homogeneous sampling with the same number of points:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"if not runner.task.done():\n",
" raise RuntimeError('Wait for the runner to finish before executing the cells below!')"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"learner2 = adaptive.Learner1D(f, bounds=learner.bounds)\n",
"\n",
"xs = np.linspace(*learner.bounds, len(learner.data))\n",
"learner2.add_data(xs, map(partial(f, wait=False), xs))\n",
"\n",
"learner.plot() + learner2.plot()"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# 2D function learner"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Besides 1D functions, we can also learn 2D functions: $\\ f: ℝ^2 → ℝ$"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"def ring(xy, wait=True):\n",
" import numpy as np\n",
" from time import sleep\n",
" from random import random\n",
" if wait:\n",
" sleep(random())\n",
" x, y = xy\n",
" a = 0.2\n",
" return x + np.exp(-(x**2 + y**2 - 0.75**2)**2/a**4)\n",
"\n",
"learner = adaptive.Learner2D(ring, bounds=[(-1, 1), (-1, 1)])"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"runner = adaptive.Runner(learner, goal=lambda l: l.loss() < 0.01)"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"(adaptive.live_plot(runner) +\n",
" adaptive.live_plot(runner, plotter=lambda l: l.plot(triangles_alpha=1).Contours) +\n",
" adaptive.live_plot(runner, plotter=lambda l: l.plot(triangles_alpha=0.2)))"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"import itertools\n",
"learner2 = adaptive.Learner2D(ring, bounds=learner.bounds)\n",
"xs = np.linspace(*learner.bounds[0], learner.n**0.5)\n",
"ys = np.linspace(*learner.bounds[1], learner.n**0.5)\n",
"xys = list(itertools.product(xs, ys))\n",
"learner2.add_data(xys, map(partial(ring, wait=False), xys))\n",
"learner2.plot().relabel('Homogeneous grid') + learner.plot().relabel('With adaptive')"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# Averaging learner"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"The next type of learner averages a function until the uncertainty in the average meets some condition.\n",
"\n",
"This is useful for sampling a random variable. The function passed to the learner must formally take a single parameter,\n",
"which should be used like a \"seed\" for the (pseudo-) random variable (although in the current implementation the seed parameter can be ignored by the function)."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"def g(n):\n",
" import random\n",
" from time import sleep\n",
" sleep(random.random() / 5)\n",
" # Properly save and restore the RNG state\n",
" state = random.getstate()\n",
" random.seed(n)\n",
" val = random.gauss(0.5, 1)\n",
" random.setstate(state)\n",
" return val"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"learner = adaptive.AverageLearner(g, atol=None, rtol=0.01)\n",
"runner = adaptive.Runner(learner, goal=lambda l: l.loss() < 1)\n",
"adaptive.live_plot(runner)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# 1D integration learner with `cquad`"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"This learner learns a 1D function and calculates the integral and error of the integral with it. It is based on Pedro Gonnet's [implementation](https://www.academia.edu/1976055/Adaptive_quadrature_re-revisited).\n",
"\n",
"Let's try the following function with cusps (that is difficult to integrate):"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"def f24(x):\n",
" return np.floor(np.exp(x))\n",
"\n",
"xs = np.linspace(0, 3, 200)\n",
"hv.Scatter((xs, [f24(x) for x in xs]))"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Just to prove that this really is a difficult to integrate function, let's try a familiar function integrator `scipy.integrate.quad`, which will give us warnings that it encounters difficulties."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"import scipy.integrate\n",
"scipy.integrate.quad(f24, 0, 3)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"We initialize a learner again and pass the bounds and relative tolerance we want to reach. Then in the `Runner` we pass `goal=lambda l: l.done()` where `learner.done()` is `True` when the relative tolerance has been reached."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"from adaptive.runner import SequentialExecutor\n",
"learner = adaptive.IntegratorLearner(f24, bounds=(0, 3), tol=1e-10)\n",
"runner = adaptive.Runner(learner, executor=SequentialExecutor(), goal=lambda l: l.done())"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Now we could do the live plotting again, but lets just wait untill the runner is done."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"if not runner.task.done():\n",
" raise RuntimeError('Wait for the runner to finish before executing the cells below!')"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"print('The integral value is {} with the corresponding error of {}'.format(learner.igral, learner.err))\n",
"learner.plot()"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# 1D learner with vector output: `f:ℝ → ℝ^N`"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Some 1D functions return multiple numbers, such as the following function:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"random.seed(0)\n",
"offsets = [random.uniform(-0.8, 0.8) for _ in range(3)]\n",
"def f_levels(x, offsets=offsets):\n",
" a = 0.01\n",
" return np.array([offset + x + a**2 / (a**2 + (x - offset)**2)\n",
" for offset in offsets])"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"This is again a function with sharp peaks at different x-values and with different constant backgrounds. To learn this function we can use a `Learner1D` as well."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"from adaptive.runner import SequentialExecutor\n",
"\n",
"learner = adaptive.Learner1D(f_levels, bounds=(-1, 1))\n",
"runner = adaptive.Runner(learner, SequentialExecutor(), goal=lambda l: l.loss() < 0.05)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"In the plot below we see that the function gets more densely sampled around the peaks, which is the behaviour we want."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"adaptive.live_plot(runner)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# Balancing learner"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"The balancing learner is a \"meta-learner\" that takes a list of multiple leaners. The runner wil find find out which points of which child learner will improve the loss the most and send those to the executor.\n",
"\n",
"The balancing learner can for example be used to implement a poor-man's 2D learner by using the `Learner1D`."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"def f(x, offset):\n",
" a = 0.01\n",
" return x + a**2 / (a**2 + (x - offset)**2)\n",
"\n",
"learners = [adaptive.Learner1D(partial(f, offset=random.uniform(-1, 1)),\n",
" bounds=(-1, 1)) for i in range(10)]\n",
"\n",
"bal_learner = adaptive.BalancingLearner(learners)\n",
"runner = adaptive.Runner(bal_learner, goal=lambda l: l.loss() < 0.01)"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"plotter = lambda learner: hv.Overlay([L.plot() for L in learner.learners])\n",
"adaptive.live_plot(runner, plotter=plotter)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# DataSaver"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Sometimes we want to learn functions that do not only return a single `float`, but instead return multiple values (even though we only want to learn one value.)\n",
"\n",
"We can wrap our learners with a `adaptive.DataSaver` such that the learner will be able to handle functions that return results.\n",
"\n",
"Take for example this function where we want to remember the time that every point took:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"from operator import itemgetter\n",
"\n",
"def f_dict(x):\n",
" \"\"\"The function evaluation takes roughly the time we `sleep`.\"\"\"\n",
" import random\n",
" from time import sleep\n",
"\n",
" waiting_time = random.random()\n",
" sleep(waiting_time)\n",
" a = 0.01\n",
" y = x + a**2 / (a**2 + x**2)\n",
" return {'y': y, 'waiting_time': waiting_time}\n",
"\n",
"# Create the learner with the function that returns a `dict`\n",
"# Note that this learner cannot be passed to a runner.\n",
"_learner = adaptive.Learner1D(f_dict, bounds=(-1, 1))\n",
"\n",
"# Wrap the learner in the `DataSavingLearner` and tell it which key it needs to learn\n",
"learner = adaptive.DataSaver(_learner, arg_picker=itemgetter('y'))"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"`learner.learner` is the original learner, so `learner.learner.loss()` will call the correct loss method."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"runner = adaptive.Runner(learner, goal=lambda l: l.learner.loss() < 0.01)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Because `learner` doesn't have a `plot` function we need to copy `_learner.plot` (or `learner.learner.plot`)"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"learner.plot = _learner.plot\n",
"adaptive.live_plot(runner)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Now the `DataSavingLearner` will have an dictionary attribute `extra_data` that has `x` as key and the data that was returned by `learner.function` as values."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"learner.extra_data"
]
},
{
"cell_type": "markdown",
"metadata": {
"collapsed": true
},
"source": [
"## Alternative executors"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Often you will want to evaluate the function on some remote computing resources. `adaptive` works out of the box with any framework that implements a [PEP 3148](https://www.python.org/dev/peps/pep-3148/) compliant executor that returns `concurrent.futures.Future` objects."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### `concurrent.futures`"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"By default a runner creates a `ProcessPoolExecutor`, but you can also pass one explicitly e.g. to limit the number of workers:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"from concurrent.futures import ProcessPoolExecutor\n",
"\n",
"executor = ProcessPoolExecutor(max_workers=4)\n",
"\n",
"learner = adaptive.Learner1D(f, bounds=(-1, 1))\n",
"runner = adaptive.Runner(learner, executor=executor, goal=lambda l: l.loss() < 0.1)\n",
"adaptive.live_plot(runner)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### IPyparallel"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"import ipyparallel\n",
"\n",
"client = ipyparallel.Client()\n",
"# f is a closure, so we have to use cloudpickle -- this is independent of 'adaptive'\n",
"client[:].use_cloudpickle()\n",
"\n",
"learner = adaptive.Learner1D(f, bounds=(-1, 1))\n",
"runner = adaptive.Runner(learner, executor=client, goal=lambda l: l.loss() < 0.1)\n",
"adaptive.live_plot(runner)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"---"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# Advanced Topics"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Cancelling a runner"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Sometimes you want to interactively explore a parameter space, and want the function to be evaluated at finer and finer resolution and manually control when the calculation stops.\n",
"\n",
"If no `goal` is provided to a runner then the runner will run until cancelled:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"learner = adaptive.Learner1D(f, bounds=(-1, 1))\n",
"runner = adaptive.Runner(learner)\n",
"adaptive.live_plot(runner)"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"runner.task.cancel()"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Debugging Problems "
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Runners work in the background with respect to the IPython kernel, which makes it convenient, but also means that inspecting errors is more difficult because exceptions will not be raised directly in the notebook. Often the only indication you will have that something has gone wrong is that nothing will be happening.\n",
"\n",
"Let's look at the following example, where the function to be learned will raise an exception 10% of the time."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"def will_raise(x):\n",
" from random import random\n",
" from time import sleep\n",
" \n",
" sleep(random())\n",
" if random() < 0.1:\n",
" raise RuntimeError('something went wrong!')\n",
" return x**2\n",
" \n",
"learner = adaptive.Learner1D(will_raise, (-1, 1))\n",
"runner = adaptive.Runner(learner) # without 'goal' the runner will run forever unless cancelled\n",
"adaptive.live_plot(runner)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"The above runner should continue forever, but we notice that it stops after a few points are evaluated.\n",
"\n",
"First we should check that the runner has really finished:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"runner.task.done()"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"If it has indeed finished then we should check the `result` of the runner. This should be `None` if the runner stopped successfully. If the runner stopped due to an exception then asking for the result will raise the exception with the stack trace:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"runner.task.result()"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Logging runners"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Runners do their job in the background, which makes introspection quite cumbersome. One way to inspect runners is to instantiate one with `log=True`:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"learner = adaptive.Learner1D(f, bounds=(-1, 1))\n",
"runner = adaptive.Runner(learner, goal=lambda l: l.loss() < 0.1,\n",
" log=True)\n",
"adaptive.live_plot(runner)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"This gives a the runner a `log` attribute, which is a list of the `learner` methods that were called, as well as their arguments. This is useful because executors typically execute their tasks in a non-deterministic order.\n",
"\n",
"This can be used with `adaptive.runner.replay_log` to perfom the same set of operations on another runner:\n"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"reconstructed_learner = adaptive.Learner1D(f, bounds=learner.bounds)\n",
"adaptive.runner.replay_log(reconstructed_learner, runner.log)"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"learner.plot().opts(style=dict(size=6)) * reconstructed_learner.plot()"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Timing functions"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"To time the runner you **cannot** simply use \n",
"```python\n",
"now = datetime.now()\n",
"runner = adaptive.Runner(...)\n",
"print(datetime.now() - now)\n",
"```\n",
"because this will be done immediately. Also blocking the kernel with `while not runner.task.done()` will not work because the runner will not do anything when the kernel is blocked.\n",
"\n",
"Therefore you need to create an `async` function and hook it into the `ioloop` like so:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"import asyncio\n",
"\n",
"async def time(runner):\n",
" from datetime import datetime\n",
" now = datetime.now()\n",
" await runner.task\n",
" return datetime.now() - now\n",
"\n",
"ioloop = asyncio.get_event_loop()\n",
"\n",
"learner = adaptive.Learner1D(f, bounds=(-1, 1))\n",
"runner = adaptive.Runner(learner, goal=lambda l: l.loss() < 0.01)\n",
"\n",
"timer = ioloop.create_task(time(runner))"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"# The result will only be set when the runner is done.\n",
"timer.result()"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Using Runners from a script "
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Runners can also be used from a Python script independently of the notebook:\n",
"\n",
"```python\n",
"import adaptive\n",
"\n",
"def f(x):\n",
" return x\n",
"\n",
"learner = adaptive.Learner1D(f, (-1, 1))\n",
"\n",
"runner = adaptive.Runner(learner, goal=lambda: l: l.loss() < 0.1)\n",
"runner.run_sync() # Block until completion.\n",
"```\n",
"\n",
"Under the hood the runner uses [`asyncio`](https://docs.python.org/3/library/asyncio.html). You don't need to worry about this most of the time, unless your script uses asyncio itself. If this is the case you should be aware that instantiating a `Runner` schedules a new task on the current event loop, and you can simply\n",
"\n",
"```python\n",
" await runner.task\n",
"```\n",
"\n",
"inside a coroutine to await completion of the runner."
]
}
],
"metadata": {
"anaconda-cloud": {},
"kernelspec": {
"display_name": "Python 3",
"language": "python",
"name": "python3"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.6.3"
}
},
"nbformat": 4,
"nbformat_minor": 1
}