map-reduce-and-multiprocessing.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Map, Reduce, and Multiprocessing"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Multiprocessing capabilities can be an effective tool for speeding up a time-consuming workflow by making it possible to execute portions of the workflow in parallel across multiple CPU cores. However, for more complex workflows, data and control flow dependencies that can lead to race conditions can make implementation, debugging, and maintenance more challenging."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "One approach to consider when planning a new workflow is whether the workflow is amenable to a more functional implementation that leverages *map* and *reduce* operations (*i.e.,* whether it is compatible with the [MapReduce](https://en.wikipedia.org/wiki/MapReduce) paradigm). In practice, many common workflows that can be parallelized are also possible to implement in this paradigm. If this fits your workflow, you can take advantage of this to make your use multiprocessing solution simpler, more elegant, and easier to maintain."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Example Workflow with Map and Reduce"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Because Python supports the functional programming paradigm and has built-in [`map`](https://docs.python.org/3/library/functions.html#map) and [`reduce`](https://docs.python.org/3/library/functools.html#functools.reduce) functions, it is straightforward to prototype a solution to a problem using these building blocks."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "A popular use case used in introductory materials on frameworks that support the MapReduce paradigm is that of empirically estimating the value of $\\pi$. The formula for the area $A$ of a circle having radius $r$ is $A = \\pi r^2$, so the radius and area of a circle can be used to compute $\\pi = A/r^2$. Letting $r = \\frac{1}{2}$ yields\n",
    "\n",
    "$$\\pi = \\frac{A}{\\Big(\\frac{1}{2}\\Big)^2} = 4A.$$\n",
    "\n",
    "So to estimate $\\pi$, it is sufficient to multiply by $4$ the area of a circle having a radius of $\\frac{1}{2}$."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "A circle with a radius of $\\frac{1}{2}$ has a diameter of $1$ and so it fits perfectly inside a square having sides of length $1$ (and, thus, an area of $1 \\cdot 1 = 1$). This makes it is possible to estimate $A$ by generating random points inside a square of area $1$ and counting how many of these random points are also inside the circle of radius $\\frac{1}{2}$ that is inscribed perfectly inside that square."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Each random point has a probability of $\\frac{\\mathrm{area} \\ \\mathrm{of} \\ \\mathrm{circle}}{\\mathrm{area} \\ \\mathrm{of} \\ \\mathrm{square}} = \\frac{A}{1}$ of being inside the circle of area $A$. After generating $n$ random points, if $k$ of them are in the circle then the approximation below should hold:\n",
    "\n",
    "$$\\frac{A}{1} \\approx \\frac{k}{n}.$$\n",
    "\n",
    "This can then be used with the fact from the paragraph above to compute the approximation $\\pi \\approx 4 \\cdot \\frac{k}{n}$. The code block below builds a plot using [Matplotlib](https://matplotlib.org/) to provide a visual representation of how this estimate is computed."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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\n",
      "text/plain": [
       "<Figure size 432x432 with 1 Axes>"
      ]
     },
     "metadata": {
      "needs_background": "light"
     },
     "output_type": "display_data"
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "3.16\n"
     ]
    }
   ],
   "source": [
    "import matplotlib.pyplot as plt\n",
    "import matplotlib.pyplot as fig\n",
    "import matplotlib.patches as pch\n",
    "import numpy as np\n",
    "\n",
    "# Draw the Cartesian plane between (-0.6, -0,6) and (0.6, 0.6).\n",
    "fig = plt.figure(figsize=(6, 6))\n",
    "axes = fig.add_subplot(1, 1, 1)\n",
    "axes.set_xlim(-0.6, 0.6)\n",
    "axes.set_ylim(-0.6, 0.6)\n",
    "\n",
    "# Center at origin a circle of diameter 1 and a square of area 1.\n",
    "axes.add_patch(\n",
    "    plt.Circle(\n",
    "        (0, 0), radius=0.5, edgecolor='b', facecolor='None'\n",
    "    )\n",
    ")\n",
    "axes.add_patch(\n",
    "    pch.Rectangle(\n",
    "        (-0.5, -0.5), 1, 1, edgecolor='r', facecolor='None'\n",
    "    )\n",
    ")\n",
    "\n",
    "# Add random points and color them blue if they are in the circle.\n",
    "n = 200\n",
    "(x, y) = (-0.5 + np.random.rand(n), -0.5 + np.random.rand(n))\n",
    "colors = ['b' if (x[i]**2 + y[i]**2 <= 0.5**2) else 'r' for i in range(n)]\n",
    "plt.scatter(x, y, c=colors)\n",
    "\n",
    "# Show the plot and the fraction of points inside the circle.\n",
    "plt.show()\n",
    "print(4 * colors.count('b') / len(colors))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "To implement the same workflow using map and reduce operations, it is necessary to split the problem into two parts: (1) a step in which there is no dependency between the entries (*i.e.*, points) in the data, and (2) a step during which these entries need to be combined into a final result."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "One approach that can make a MapReduce-like workflow concise to implement is to ensure that the *representation* of a data entry and a partially aggregated set of entries is always the same. This makes it possible to have just a single function that can always take two partial results and combine it into a new, larger partial result. In this example, the representation reflects the final goal: a count of points that are *in* the circle and a count of *all* the points in the square (both inside and outside of the circle) that have been generated so far."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'circle': 314, 'square': 400}"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "{\n",
    "    \"circle\": 314, \n",
    "    \"square\": 400\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "The initial data entries are now just a special case of the above: a point inside the circle is represented as `{\"circle\":1, \"square\":1}` and a point outside the circle is represented as `{\"circle\":0, \"square\":1}`. You can now implement the function `trial` below that corresponds to the map step of the MapReduce-like workflow."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "def trial(instance):\n",
    "    from random import random\n",
    "    (x, y) = (-0.5 + random(), -0.5 + random())\n",
    "    return {\n",
    "        \"circle\": 1 if (x**2 + y**2 <= 0.5**2) else 0, \n",
    "        \"square\": 1\n",
    "      }"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "The function `combine` for the second step is now even simpler to implement. All you need is a function that combines two aggregated estimates into a new aggregated estimate."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "def combine(estimate_a, estimate_b):\n",
    "    return {\n",
    "        \"circle\": estimate_a[\"circle\"] + estimate_b[\"circle\"], \n",
    "        \"square\": estimate_a[\"square\"] + estimate_b[\"square\"]\n",
    "    }"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Using the `trial` and `combine` functions to implement a MapReduce-like workflow is then straightforward."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'circle': 3153, 'square': 4000}\n",
      "3.153\n"
     ]
    }
   ],
   "source": [
    "from functools import reduce\n",
    "estimate = reduce(combine, map(trial, range(4000)))\n",
    "print(estimate)\n",
    "print(4 * (estimate[\"circle\"] / estimate[\"square\"]))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Partial Application of Functions"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "A brief digression to review higher-order functions (something covered in a [previous article on decorators](https://python.supply/higher-order-functions-and-decorators)) will be useful for subsequent examples. Given a function that takes more than one argument, it is possible to turn that into a function that takes only the first argument and returns a new function that takes the rest of the arguments as inputs. As an example, consider the following addition function."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "def add(x, y):\n",
    "    return x + y"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "The following higher-order function can be used to transform it into a function that returns a function."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "def partial_(f, x):\n",
    "    def g(y):\n",
    "        return f(x, y)\n",
    "    return g"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "The example below illustrates how `partial_` works."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "5"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "add_ = partial_(add, 2)\n",
    "add_(3)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Python has a function [`partial`](https://docs.python.org/3/library/functools.html#functools.partial) in the built-in [functools](https://docs.python.org/3/library/functools.html) library that does exactly what `partial_` does in the above example."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "5"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from functools import partial\n",
    "add_ = partial(add, 2)\n",
    "add_(3)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "This is actually a special case of [currying](https://en.wikipedia.org/wiki/Currying), a topic that is usually covered in materials on the functional programming paradigm and associated techniques."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Multiprocessing"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Python's built-in [multiprocessing](https://docs.python.org/3/library/multiprocessing.html) library allows programmers to run multiple processes in parallel if the operating system and hardware support it."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Throughout the rest of this article, an auxiliary function is used that makes it easier to run the multiprocessing library within Jupyter Notebook. This function is a [decorator](https://python.supply/higher-order-functions-and-decorators) that stores the decorated function definition in a temporary module file so that the the multiprocessing library can load it."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "outputs": [],
   "source": [
    "def module(function):\n",
    "    import os\n",
    "    import importlib\n",
    "    import uuid\n",
    "    import inspect\n",
    "\n",
    "    directory = '/tmp/' + __name__ + '/'\n",
    "    module_name = 'tmp.' + __name__ + '.' + function.__name__\n",
    "    \n",
    "    if not os.path.exists('.' + directory):\n",
    "        os.makedirs('.' + directory)\n",
    "\n",
    "    filepath = '.' + directory + '/' + function.__name__ + \".py\"\n",
    "    with open(filepath, \"w\") as file:\n",
    "        definition = inspect.getsource(function)\n",
    "        lines = definition.split(\"\\n\")\n",
    "        if lines[0] == \"@module\":\n",
    "            definition = \"\\n\".join(lines[1:])\n",
    "        file.write(definition)\n",
    "\n",
    "    module = importlib.import_module(module_name, package=function.__name__)\n",
    "    return getattr(module, function.__name__)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "One of the simplest ways to use the multiprocessing library is to create a pool of processes and to instruct all the processes in that pool execute the same function."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "scrolled": true,
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[2, 4, 6, 8]\n"
     ]
    }
   ],
   "source": [
    "@module\n",
    "def double(x):\n",
    "    return x + x\n",
    "\n",
    "import multiprocessing as mp\n",
    "with mp.Pool(processes = mp.cpu_count()) as pool:\n",
    "    ys = pool.map(double, [1, 2, 3, 4])\n",
    "    print(ys)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "As you can see, the API is already fairly close to a MapReduce-like workflow. However, the workflow for approximating $\\pi$ (which is representative of other MapReduce-like workflows) requires that a single aggregated result value is computed at the end."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "One way to proceed is to split the point generation portion of the workflow across multiple processes, with each process computing its own estimate iteratively for its subset of the total number of trials. Once all the processes compute their individual estimates, the *reduce* portion of the workflow is split into two parts:\n",
    "\n",
    "* each process applies `reduce` to compute a single estimate for that process, and\n",
    "* a global `reduce` operation is applied across all the estimates returned by all the processes.\n",
    "\n",
    "An implementation of the functions that enable this approach is presented below."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "outputs": [],
   "source": [
    "@module\n",
    "def trial(instance):\n",
    "    from random import random\n",
    "    (x, y) = (-0.5 + random(), -0.5 + random())\n",
    "    return {\n",
    "        \"circle\": 1 if (x**2 + y**2 <= 0.5**2) else 0, \n",
    "        \"square\": 1\n",
    "      }\n",
    "\n",
    "@module\n",
    "def combine(estimate_a, estimate_b):\n",
    "    return {\n",
    "        \"circle\": estimate_a[\"circle\"] + estimate_b[\"circle\"], \n",
    "        \"square\": estimate_a[\"square\"] + estimate_b[\"square\"]\n",
    "    }"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "These functions can then be used in the following way:\n",
    "\n",
    "* use the [parts](https://pypi.org/project/parts/) library to split a range of integers `range(10000)` representing the number of single-point trials to run into a number of portions `mp.cpu_count()` corresponding to the number of processes that can be executed in parallel by the host environment;\n",
    "* for each range of integers, have each process handling its range apply `partial(map, trial)` to its list (which effectively maps `trial` across the list of integers available to that process and yields a list of estimates within that process);\n",
    "* once all processes finish creating their respective estimate lists (yielding a *list of lists* `es_per_process`), run another process for each estimate list in `es_per_process` that combines that list into a single combined estimate (each process does this by applying the function `partial(reduce, combine)` to its list of estimates); and\n",
    "* combine all the individual estimates returned by the processes into a single estimate using `reduce(combine, ...)`. \n",
    "\n",
    "The code block below implements this approach and outputs the resulting overall estimate."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "3.1452\n"
     ]
    }
   ],
   "source": [
    "from functools import partial, reduce\n",
    "from parts import parts\n",
    "\n",
    "with mp.Pool(processes = mp.cpu_count()) as pool:\n",
    "    es_per_process = pool.map(\n",
    "        partial(map, trial),\n",
    "        parts(range(10000), pool._processes)\n",
    "    )\n",
    "    e = reduce(\n",
    "        combine,\n",
    "        pool.map(partial(reduce, combine), es_per_process)\n",
    "    )\n",
    "    print(4*(e[\"circle\"] / e[\"square\"]))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "The [mr4mp](https://pypi.org/project/mr4mp/) library provides a thin wrapper API around the multiprocessing library to enable even more concise implementations of MapReduce-like workflows. Assuming the `trial` and `combine` functions have already been defined, the entire workflow can be implemented using just a few lines of code."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "3.1472\n"
     ]
    }
   ],
   "source": [
    "import mr4mp\n",
    "\n",
    "e = mr4mp.pool().mapreduce(trial, combine, range(10000))\n",
    "print(4 * (e[\"circle\"] / e[\"square\"]))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Further Reading"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "This article provides a template illustrating how certain workflows that are compatible with the MapReduce paradigm can be implemented to leverage multiprocessing in an extremely concise way without introducing unnecessary data or control flow dependencies and without requiring any explicit effort to achieve synchronization. Another common MapReduce use case involving a word-document index is [presented in the README](https://github.com/lapets/mr4mp#word-document-index) for the [mr4mp](https://pypi.org/project/mr4mp/) library."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "You can visit the [Python Wiki](https://wiki.python.org/moin/ParallelProcessing) to explore the rich ecosystem of other libraries that leverage either the existing multiprocessing support within Python or provide a similar API for other parallel and distributed computing infrastructures. One library that you might consider investigating if you want to use Python to leverage the full power of contemporary distributed programming paradigms and infrastructures (including MapReduce and beyond) is [PySpark](https://pypi.org/project/pyspark/)."
   ]
  }
 ],
 "metadata": {
  "anaconda-cloud": {},
  "celltoolbar": "Slideshow",
  "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.8.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}