![\"Numba](\"https://numba.pydata.org/_static/numba-blue-horizontal-rgb.svg\"\n",)
\n",
"\n",
"This notebook combines [Numba](https://numba.pydata.org/), a high performance Python compiler, with Dask Arrays.\n",
"\n",
"In particular we show off two Numba features, and how they compose with Dask:\n",
"\n",
"1. Numba's [stencil decorator](https://numba.pydata.org/numba-doc/dev/user/stencil.html)\n",
"2. NumPy's [Generalized Universal Functions](https://numpy.org/doc/stable/reference/c-api/generalized-ufuncs.html)\n",
"\n",
"*This was originally published as a blogpost [here](https://blog.dask.org/2019/04/09/numba-stencil)*"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Introduction to Numba Stencils\n",
"\n",
"Many array computing functions operate only on a local region of the array. This is common in image processing, signals processing, simulation, the solution of differential equations, anomaly detection, time series analysis, and more. Typically we write code that looks like the following:"
]
},
{
"cell_type": "code",
"execution_count": 1,
"metadata": {
"execution": {
"iopub.execute_input": "2022-07-27T19:17:13.217150Z",
"iopub.status.busy": "2022-07-27T19:17:13.216643Z",
"iopub.status.idle": "2022-07-27T19:17:13.226587Z",
"shell.execute_reply": "2022-07-27T19:17:13.226051Z"
}
},
"outputs": [],
"source": [
"def _smooth(x):\n",
" out = np.empty_like(x)\n",
" for i in range(1, x.shape[0] - 1):\n",
" for j in range(1, x.shape[1] - 1):\n",
" out[i, j] = (x[i + -1, j + -1] + x[i + -1, j + 0] + x[i + -1, j + 1] +\n",
" x[i + 0, j + -1] + x[i + 0, j + 0] + x[i + 0, j + 1] +\n",
" x[i + 1, j + -1] + x[i + 1, j + 0] + x[i + 1, j + 1]) // 9\n",
"\n",
" return out"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Or something similar. The `numba.stencil` decorator makes this a bit easier to write down. You just write down what happens on every element, and Numba handles the rest.\n",
"\n"
]
},
{
"cell_type": "code",
"execution_count": 2,
"metadata": {
"execution": {
"iopub.execute_input": "2022-07-27T19:17:13.229734Z",
"iopub.status.busy": "2022-07-27T19:17:13.229350Z",
"iopub.status.idle": "2022-07-27T19:17:13.726508Z",
"shell.execute_reply": "2022-07-27T19:17:13.725749Z"
}
},
"outputs": [],
"source": [
"import numba\n",
"\n",
"@numba.stencil\n",
"def _smooth(x):\n",
" return (x[-1, -1] + x[-1, 0] + x[-1, 1] +\n",
" x[ 0, -1] + x[ 0, 0] + x[ 0, 1] +\n",
" x[ 1, -1] + x[ 1, 0] + x[ 1, 1]) // 9"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"When we run this function on a NumPy array, we find that it is slow, operating at Python speeds."
]
},
{
"cell_type": "code",
"execution_count": 3,
"metadata": {
"execution": {
"iopub.execute_input": "2022-07-27T19:17:13.730835Z",
"iopub.status.busy": "2022-07-27T19:17:13.730264Z",
"iopub.status.idle": "2022-07-27T19:17:16.786054Z",
"shell.execute_reply": "2022-07-27T19:17:16.785503Z"
}
},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"368 ms ± 1.85 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)\n"
]
}
],
"source": [
"import numpy as np\n",
"x = np.ones((100, 100))\n",
"\n",
"%timeit _smooth(x)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"But if we JIT compile this function with Numba, then it runs more quickly."
]
},
{
"cell_type": "code",
"execution_count": 4,
"metadata": {
"execution": {
"iopub.execute_input": "2022-07-27T19:17:16.789631Z",
"iopub.status.busy": "2022-07-27T19:17:16.789221Z",
"iopub.status.idle": "2022-07-27T19:17:17.286562Z",
"shell.execute_reply": "2022-07-27T19:17:17.285613Z"
}
},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"175 µs ± 25.4 µs per loop (mean ± std. dev. of 7 runs, 1 loop each)\n"
]
}
],
"source": [
"@numba.njit\n",
"def smooth(x):\n",
" return _smooth(x)\n",
"\n",
"%timeit smooth(x)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"For those counting, that’s over 1000x faster!\n",
"\n",
"*Note: this function already exists as `scipy.ndimage.uniform_filter`, which operates at the same speed.*"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Dask Array\n",
"\n",
"In these applications people often have many such arrays and they want to apply this function over all of them. In principle they could do this with a for loop.\n",
"\n"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"```python\n",
"from glob import glob\n",
"import skimage.io\n",
"\n",
"for fn in glob('/path/to/*.png'):\n",
" img = skimage.io.imread(fn)\n",
" out = smooth(img)\n",
" skimage.io.imsave(fn.replace('.png', '.out.png'), out)\n",
"```"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"If they wanted to then do this in parallel they would maybe use the multiprocessing or concurrent.futures modules. If they wanted to do this across a cluster then they could rewrite their code with PySpark or some other system.\n",
"\n",
"Or, they could use Dask array, which will handle both the pipelining and the parallelism (single machine or on a cluster) all while still looking mostly like a NumPy array.\n",
"\n"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"```python\n",
"import dask_image\n",
"x = dask_image.imread('/path/to/*.png') # a large lazy array of all of our images\n",
"y = x.map_blocks(smooth, dtype='int8')\n",
"```"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"And then because each of the chunks of a Dask array are just NumPy arrays, we can use the [map_blocks](https://docs.dask.org/en/latest/generated/dask.array.map_blocks.html) function to apply this function across all of our images, and then save them out.\n",
"\n",
"This is fine, but lets go a bit further, and discuss generalized universal functions from NumPy."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Because we don't have a stack of images nearby, we're going to make a random array with similar structure."
]
},
{
"cell_type": "code",
"execution_count": 5,
"metadata": {
"execution": {
"iopub.execute_input": "2022-07-27T19:17:17.290327Z",
"iopub.status.busy": "2022-07-27T19:17:17.290118Z",
"iopub.status.idle": "2022-07-27T19:17:17.578607Z",
"shell.execute_reply": "2022-07-27T19:17:17.577955Z"
}
},
"outputs": [
{
"data": {
"text/html": [
"\n",
"
| \n",
" \n", " \n", " | \n", "
\n",
"
| \n",
" \n", " \n", " | \n", "
Client-bb5807ea-0de0-11ed-a0f1-000d3a8f7959
\n", "| Connection method: Cluster object | \n", "Cluster type: distributed.LocalCluster | \n", " \n", "
| \n", " Dashboard: http://10.1.1.64:8787/status\n", " | \n", "\n", " |
9d67a1da
\n", "| \n", " Dashboard: http://10.1.1.64:8787/status\n", " | \n", "\n", " Workers: 1\n", " | \n", "
| \n", " Total threads: 4\n", " | \n", "\n", " Total memory: 3.73 GiB\n", " | \n", "
| Status: running | \n", "Using processes: False | \n", "
Scheduler-0774d2ab-c891-4a84-bc8b-4727c390aa3c
\n", "| \n", " Comm: inproc://10.1.1.64/8433/1\n", " | \n", "\n", " Workers: 1\n", " | \n", "
| \n", " Dashboard: http://10.1.1.64:8787/status\n", " | \n", "\n", " Total threads: 4\n", " | \n", "
| \n", " Started: Just now\n", " | \n", "\n", " Total memory: 3.73 GiB\n", " | \n", "
| \n", " Comm: inproc://10.1.1.64/8433/4\n", " | \n", "\n", " Total threads: 4\n", " | \n", "
| \n", " Dashboard: http://10.1.1.64:46077/status\n", " | \n", "\n", " Memory: 3.73 GiB\n", " | \n", "
| \n", " Nanny: None\n", " | \n", "\n", " |
| \n", " Local directory: /home/runner/work/dask-examples/dask-examples/applications/dask-worker-space/worker-ebsbpsit\n", " | \n", "