GitList
Browse code

add introduction notebook

Joseph Weston authored on 23/08/2017 15:16:39
Showing 1 changed files
learner.ipynb
History View file @ 9e09108
... ... 
@@ -7,6 +7,47 @@
7 7 
     "# Adaptive"
8 8 
    ]
9 9 
   },
10 
+  {
11 
+   "cell_type": "markdown",
12 
+   "metadata": {},
13 
+   "source": [
14 
+    "[`adaptive`](https://gitlab.kwant-project.org/basnijholt/adaptive-evaluation) is a package for adaptively sampling functions with support for parallel evaluation.\n",
15 
+    "\n",
16 
+    "This is an introductory notebook that shows some basic use cases.\n",
17 
+    "\n",
18 
+    "`adaptive` needs the following packages:\n",
19 
+    "\n",
20 
+    "+ Python 3.6\n",
21 
+    "+ holowiews\n",
22 
+    "+ bokeh"
23 
+   ]
24 
+  },
25 
+  {
26 
+   "cell_type": "code",
27 
+   "execution_count": null,
28 
+   "metadata": {},
29 
+   "outputs": [],
30 
+   "source": [
31 
+    "import adaptive\n",
32 
+    "adaptive.notebook_extension()"
33 
+   ]
34 
+  },
35 
+  {
36 
+   "cell_type": "markdown",
37 
+   "metadata": {},
38 
+   "source": [
39 
+    "# 1D function learner"
40 
+   ]
41 
+  },
42 
+  {
43 
+   "cell_type": "markdown",
44 
+   "metadata": {},
45 
+   "source": [
46 
+    "We start with the most common use-case: sampling a 1D function $\\ f: ℝ → ℝ$.\n",
47 
+    "\n",
48 
+    "We will use the following function, which is a smooth (linear) background with a sharp peak at a random location:"
49 
+   ]
50 
+  },
10 51 
   {
11 52 
    "cell_type": "code",
12 53 
    "execution_count": null,
... ... 
@@ -15,45 +56,99 @@
15 56 
    },
16 57 
    "outputs": [],
17 58 
    "source": [
18 
-    "import adaptive\n",
19 
-    "adaptive.notebook_extension()\n",
59 
+    "import functools\n",
60 
+    "from random import random\n",
20 61 
     "\n",
21 
-    "def func(x, wait=True):\n",
22 
-    "    \"\"\"Function with a sharp peak on a smooth background\"\"\"\n",
23 
-    "    import numpy as np\n",
62 
+    "offset = random() - 0.5\n",
63 
+    "\n",
64 
+    "def f(x, offset=0, wait=True):\n",
24 65 
     "    from time import sleep\n",
25 
-    "    from random import randint\n",
66 
+    "    from random import random\n",
26 67 
     "\n",
27 
-    "    x = np.asarray(x)\n",
28 
-    "    a = 0.001\n",
68 
+    "    a = 0.01\n",
29 69 
     "    if wait:\n",
30 
-    "        sleep(np.random.randint(0, 2) / 10)\n",
31 
-    "    return x + a**2/(a**2 + (x)**2)"
70 
+    "        sleep(random())\n",
71 
+    "    return x + a**2 / (a**2 + (x - offset)**2)"
32 72 
    ]
33 73 
   },
34 74 
   {
35 75 
    "cell_type": "markdown",
76 
+   "metadata": {},
77 
+   "source": [
78 
+    "We start by initializing a 1D \"learner\", which will suggest points to evaluate, and adapt its suggestions as more and more points are evaluated."
79 
+   ]
80 
+  },
81 
+  {
82 
+   "cell_type": "code",
83 
+   "execution_count": null,
36 84 
    "metadata": {
37 85 
     "collapsed": true
38 86 
    },
87 
+   "outputs": [],
39 88 
    "source": [
40 
-    "## Local Process Pool (default)"
89 
+    "learner = adaptive.learner.Learner1D(f, bounds=(-1.0, 1.0))"
90 
+   ]
91 
+  },
92 
+  {
93 
+   "cell_type": "markdown",
94 
+   "metadata": {},
95 
+   "source": [
96 
+    "Next we create a \"runner\" that will request points from the learner and evaluate 'func' on them.\n",
97 
+    "\n",
98 
+    "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))."
41 99 
    ]
42 100 
   },
43 101 
   {
44 102 
    "cell_type": "code",
45 103 
    "execution_count": null,
46 104 
    "metadata": {
47 
-    "collapsed": true,
48 
-    "scrolled": false
105 
+    "collapsed": true
106 
+   },
107 
+   "outputs": [],
108 
+   "source": [
109 
+    "# The end condition is when the \"loss\" is less than 0.1. In the context of the\n",
110 
+    "# 1D learner this means that we will resolve features in 'func' with width 0.1 or wider.\n",
111 
+    "runner = adaptive.Runner(learner, goal=lambda l: l.loss() < 0.1)"
112 
+   ]
113 
+  },
114 
+  {
115 
+   "cell_type": "markdown",
116 
+   "metadata": {},
117 
+   "source": [
118 
+    "When instantiated in a Jupyter notebook the runner does its job in the background and does not block the IPython kernel.\n",
119 
+    "We can use this to create a plot that updates as new data arrives:"
120 
+   ]
121 
+  },
122 
+  {
123 
+   "cell_type": "code",
124 
+   "execution_count": null,
125 
+   "metadata": {
126 
+    "collapsed": true
49 127 
    },
50 128 
    "outputs": [],
51 129 
    "source": [
52 
-    "learner = adaptive.learner.Learner1D(func, bounds=(-1.01, 1.0))\n",
53 
-    "runner = adaptive.Runner(learner, goal=lambda l: l.loss(real=True) < 0.01)\n",
54 130 
     "adaptive.live_plot(runner)"
55 131 
    ]
56 132 
   },
133 
+  {
134 
+   "cell_type": "markdown",
135 
+   "metadata": {},
136 
+   "source": [
137 
+    "We can now compare the adaptive sampling to a homogeneous sampling with the same number of points:"
138 
+   ]
139 
+  },
140 
+  {
141 
+   "cell_type": "code",
142 
+   "execution_count": null,
143 
+   "metadata": {
144 
+    "collapsed": true
145 
+   },
146 
+   "outputs": [],
147 
+   "source": [
148 
+    "if not runner.task.done():\n",
149 
+    "    raise RuntimeError('Wait for the runner to finish before executing the cells below!')"
150 
+   ]
151 
+  },
57 152 
   {
58 153 
    "cell_type": "code",
59 154 
    "execution_count": null,
... ... 
@@ -62,23 +157,118 @@
62 157 
    },
63 158 
    "outputs": [],
64 159 
    "source": [
65 
-    "# Same function evaluated on homogeneous grid with same amount of points\n",
66 
-    "from functools import partial\n",
67 160 
     "import numpy as np\n",
68 161 
     "\n",
69 
-    "learner2 = adaptive.learner.Learner1D(func, bounds=(-1.01, 1.0))\n",
70 
-    "xs = np.linspace(-1.01, 1.0, len(learner.data))\n",
71 
-    "learner2.add_data(xs, map(partial(func, wait=False), xs))\n",
162 
+    "learner2 = adaptive.learner.Learner1D(f, bounds=(-1.01, 1.0))\n",
163 
+    "\n",
164 
+    "xs = np.linspace(-1.0, 1.0, len(learner.data))\n",
165 
+    "learner2.add_data(xs, map(functools.partial(func, wait=False), xs))\n",
166 
+    "\n",
72 167 
     "learner2.plot()"
73 168 
    ]
74 169 
   },
75 170 
   {
76 171 
    "cell_type": "markdown",
172 
+   "metadata": {},
173 
+   "source": [
174 
+    "# Averaging learner"
175 
+   ]
176 
+  },
177 
+  {
178 
+   "cell_type": "markdown",
179 
+   "metadata": {},
180 
+   "source": [
181 
+    "The next type of learner averages a function until the uncertainty in the average meets some condition.\n",
182 
+    "\n",
183 
+    "This is useful for sampling a random variable. The function passed to the learner must formally take a single parameter,\n",
184 
+    "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)."
185 
+   ]
186 
+  },
187 
+  {
188 
+   "cell_type": "code",
189 
+   "execution_count": null,
77 190 
    "metadata": {
78 191 
     "collapsed": true
79 192 
    },
193 
+   "outputs": [],
80 194 
    "source": [
81 
-    "## ipyparallel"
195 
+    "def g(n):\n",
196 
+    "    import random\n",
197 
+    "    from time import sleep\n",
198 
+    "    sleep(random.random() / 5)\n",
199 
+    "    # Properly save and restore the RNG state\n",
200 
+    "    state = random.getstate()\n",
201 
+    "    random.seed(n)\n",
202 
+    "    val = random.gauss(0.5, 1)\n",
203 
+    "    random.setstate(state)\n",
204 
+    "    return val"
205 
+   ]
206 
+  },
207 
+  {
208 
+   "cell_type": "code",
209 
+   "execution_count": null,
210 
+   "metadata": {
211 
+    "scrolled": false
212 
+   },
213 
+   "outputs": [],
214 
+   "source": [
215 
+    "learner = adaptive.AverageLearner(g, None, 0.03)\n",
216 
+    "runner = adaptive.Runner(learner, goal=lambda l: l.loss() < 1)\n",
217 
+    "adaptive.live_plot(runner)"
218 
+   ]
219 
+  },
220 
+  {
221 
+   "cell_type": "markdown",
222 
+   "metadata": {
223 
+    "collapsed": true
224 
+   },
225 
+   "source": [
226 
+    "## Alternative executors"
227 
+   ]
228 
+  },
229 
+  {
230 
+   "cell_type": "markdown",
231 
+   "metadata": {},
232 
+   "source": [
233 
+    "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."
234 
+   ]
235 
+  },
236 
+  {
237 
+   "cell_type": "markdown",
238 
+   "metadata": {},
239 
+   "source": [
240 
+    "### `concurrent.futures`"
241 
+   ]
242 
+  },
243 
+  {
244 
+   "cell_type": "markdown",
245 
+   "metadata": {},
246 
+   "source": [
247 
+    "By default a runner creates a `ProcessPoolExecutor`, but you can also pass one explicitly e.g. to limit the number of workers:"
248 
+   ]
249 
+  },
250 
+  {
251 
+   "cell_type": "code",
252 
+   "execution_count": null,
253 
+   "metadata": {
254 
+    "collapsed": true
255 
+   },
256 
+   "outputs": [],
257 
+   "source": [
258 
+    "from concurrent.futures import ProcessPoolExecutor\n",
259 
+    "\n",
260 
+    "executor = ProcessPoolExecutor(max_workers=4)\n",
261 
+    "\n",
262 
+    "learner = adaptive.learner.Learner1D(f, bounds=(-1, 1))\n",
263 
+    "runner = adaptive.Runner(learner, executor=executor, goal=lambda l: l.loss() < 0.1)\n",
264 
+    "adaptive.live_plot(runner)"
265 
+   ]
266 
+  },
267 
+  {
268 
+   "cell_type": "markdown",
269 
+   "metadata": {},
270 
+   "source": [
271 
+    "### IPyparallel"
82 272 
    ]
83 273 
   },
84 274 
   {
... ... 
@@ -92,10 +282,11 @@
92 282 
     "import ipyparallel\n",
93 283 
     "\n",
94 284 
     "client = ipyparallel.Client()\n",
285 
+    "# f is a closure, so we have to use cloudpickle -- this is independent of 'adaptive'\n",
286 
+    "client[:].use_cloudpickle()\n",
95 287 
     "\n",
96 
-    "# Initialize the learner\n",
97 
-    "learner = adaptive.learner.Learner1D(func)\n",
98 
-    "runner = adaptive.Runner(learner, client, goal=lambda l: l.loss() < 0.1)\n",
288 
+    "learner = adaptive.learner.Learner1D(f, bounds=(-1, 1))\n",
289 
+    "runner = adaptive.Runner(learner, executor=client, goal=lambda l: l.loss() < 0.1)\n",
99 290 
     "adaptive.live_plot(runner)"
100 291 
    ]
101 292 
   },
... ... 
@@ -103,7 +294,119 @@
103 294 
    "cell_type": "markdown",
104 295 
    "metadata": {},
105 296 
    "source": [
106 
-    "## 0D Learner"
297 
+    "---"
298 
+   ]
299 
+  },
300 
+  {
301 
+   "cell_type": "markdown",
302 
+   "metadata": {},
303 
+   "source": [
304 
+    "# Advanced Topics"
305 
+   ]
306 
+  },
307 
+  {
308 
+   "cell_type": "markdown",
309 
+   "metadata": {},
310 
+   "source": [
311 
+    "## Cancelling a runner"
312 
+   ]
313 
+  },
314 
+  {
315 
+   "cell_type": "markdown",
316 
+   "metadata": {},
317 
+   "source": [
318 
+    "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",
319 
+    "\n",
320 
+    "If no `goal` is provided to a runner then the runner will run until cancelled:"
321 
+   ]
322 
+  },
323 
+  {
324 
+   "cell_type": "code",
325 
+   "execution_count": null,
326 
+   "metadata": {
327 
+    "collapsed": true
328 
+   },
329 
+   "outputs": [],
330 
+   "source": [
331 
+    "learner = adaptive.learner.Learner1D(f, bounds=(-1.0, 1.0))\n",
332 
+    "runner = adaptive.Runner(learner)\n",
333 
+    "adaptive.live_plot(runner)"
334 
+   ]
335 
+  },
336 
+  {
337 
+   "cell_type": "code",
338 
+   "execution_count": null,
339 
+   "metadata": {
340 
+    "collapsed": true
341 
+   },
342 
+   "outputs": [],
343 
+   "source": [
344 
+    "runner.task.cancel()"
345 
+   ]
346 
+  },
347 
+  {
348 
+   "cell_type": "markdown",
349 
+   "metadata": {},
350 
+   "source": [
351 
+    "## Debugging Problems "
352 
+   ]
353 
+  },
354 
+  {
355 
+   "cell_type": "markdown",
356 
+   "metadata": {},
357 
+   "source": [
358 
+    "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",
359 
+    "\n",
360 
+    "Let's look at the following example, where the function to be learned will raise an exception 10% of the time."
361 
+   ]
362 
+  },
363 
+  {
364 
+   "cell_type": "code",
365 
+   "execution_count": null,
366 
+   "metadata": {
367 
+    "collapsed": true
368 
+   },
369 
+   "outputs": [],
370 
+   "source": [
371 
+    "def will_raise(x):\n",
372 
+    "    from random import random\n",
373 
+    "    from time import sleep\n",
374 
+    "    \n",
375 
+    "    sleep(random())\n",
376 
+    "    if random() < 0.1:\n",
377 
+    "        raise RuntimeError('something went wrong!')\n",
378 
+    "    return x**2\n",
379 
+    "    \n",
380 
+    "learner = adaptive.Learner1D(will_raise, (-1, 1))\n",
381 
+    "runner = adaptive.Runner(learner)  # without 'goal' the runner will run forever unless cancelled\n",
382 
+    "adaptive.live_plot(runner)"
383 
+   ]
384 
+  },
385 
+  {
386 
+   "cell_type": "markdown",
387 
+   "metadata": {},
388 
+   "source": [
389 
+    "The above runner should continue forever, but we notice that it stops after a few points are evaluated.\n",
390 
+    "\n",
391 
+    "First we should check that the runner has really finished:"
392 
+   ]
393 
+  },
394 
+  {
395 
+   "cell_type": "code",
396 
+   "execution_count": null,
397 
+   "metadata": {
398 
+    "collapsed": true
399 
+   },
400 
+   "outputs": [],
401 
+   "source": [
402 
+    "runner.task.done()"
403 
+   ]
404 
+  },
405 
+  {
406 
+   "cell_type": "markdown",
407 
+   "metadata": {},
408 
+   "source": [
409 
+    "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:"
107 410 
    ]
108 411 
   },
109 412 
   {
... ... 
@@ -115,15 +418,41 @@
115 418 
    },
116 419 
    "outputs": [],
117 420 
    "source": [
118 
-    "def func(x):\n",
119 
-    "    import random\n",
120 
-    "    import numpy as np\n",
121 
-    "    from time import sleep\n",
122 
-    "    sleep(np.random.randint(0, 2))\n",
123 
-    "    return random.gauss(0.05, 1)\n",
421 
+    "runner.task.result()"
422 
+   ]
423 
+  },
424 
+  {
425 
+   "cell_type": "markdown",
426 
+   "metadata": {},
427 
+   "source": [
428 
+    "## Using Runners from a script "
429 
+   ]
430 
+  },
431 
+  {
432 
+   "cell_type": "markdown",
433 
+   "metadata": {},
434 
+   "source": [
435 
+    "Runners can also be used from a Python script independently of the notebook:\n",
436 
+    "\n",
437 
+    "```python\n",
438 
+    "import adaptive\n",
439 
+    "\n",
440 
+    "def f(x):\n",
441 
+    "    return x\n",
442 
+    "\n",
443 
+    "learner = adaptive.Learner1D(f, (-1, 1))\n",
444 
+    "\n",
445 
+    "runner = adaptive.Runner(learner, goal=lambda: l: l.loss() < 0.1)\n",
446 
+    "runner.run_sync()  # Block until completion.\n",
447 
+    "```\n",
448 
+    "\n",
449 
+    "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",
450 
+    "\n",
451 
+    "```python\n",
452 
+    "    await runner.task\n",
453 
+    "```\n",
124 454 
     "\n",
125 
-    "learner = adaptive.learner.AverageLearner(func, None, 0.1)\n",
126 
-    "runner = adaptive.Runner(learner, goal=lambda l: l.loss() < 1)"
455 
+    "inside a coroutine to await completion of the runner."
127 456 
    ]
128 457 
   }
129 458 
  ],