From 79d698ee112eb305e0d8843d128a4489f62246ab Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fran=C3=A7ois=20Boulogne?= <fboulogne sciunto org>
Date: Fri, 27 Jun 2014 21:40:37 -0400
Subject: [PATCH] add user guide parallelization

---
 doc/source/user_guide/parallelization.txt | 60 +++++++++++++++++++++++
 1 file changed, 60 insertions(+)
 create mode 100755 doc/source/user_guide/parallelization.txt

diff --git a/doc/source/user_guide/parallelization.txt b/doc/source/user_guide/parallelization.txt
new file mode 100755
index 00000000..d4ffe59b
--- /dev/null
+++ b/doc/source/user_guide/parallelization.txt
@@ -0,0 +1,60 @@
+=========================
+How to parallelize loops?
+=========================
+
+In image processing, we frequently apply the same algorithm
+on a large batch of images. Let us define an example.
+
+.. code-block:: python
+
+    from skimage import data, color
+    from skimage.restoration import denoise_tv_chambolle
+    from skimage.feature import hog
+
+    def tasks(image):
+        """
+        Apply some functions.
+        """
+        image = denoise_tv_chambolle(image, weight=0.1, multichannel=True)
+        fd, hog_image = hog(color.rgb2gray(image), orientations=8,
+                            pixels_per_cell=(16, 16), cells_per_block=(1, 1),
+                            visualise=True)
+
+
+    # Prepare images
+    hubble = data.hubble_deep_field()
+    width = 10
+    pics = [hubble[:,slice:slice+width] for slice in range(0, 1000, width)]
+
+To call the function ``tasks`` on each element of the list ``pics``, it is
+usual to write a for loop. To measure the execution time of this loop, a function
+is defined and called with ``timeit``.
+
+.. code-block:: python
+
+    def classic_loop():
+        for image in pics:
+            tasks(image)
+
+    import timeit
+    print("classic_loop():", timeit.timeit("classic_loop()", setup="from __main__ import (classic_loop, tasks, pics)", number=1))
+
+Another equivalent way to code this loop is to use a comprehension list which has the same efficiency.
+
+.. code-block:: python
+
+    def comprehension_loop():
+        [tasks(image) for image in pics]
+
+    print("comprehension_loop():", timeit.timeit("comprehension_loop()", setup="from __main__ import (comprehension_loop, tasks, pics)", number=1))
+
+``joblib`` is a library providing an easy way to parallelize for loops once we have a comprehension list.
+The number of jobs can be specified.
+
+.. code-block:: python
+
+    from joblib import Parallel, delayed
+    def joblib_loop():
+        Parallel(n_jobs=4)(delayed(tasks)(i) for i in pics)
+
+    print("joblib_loop():", timeit.timeit("joblib_loop()", setup="from __main__ import (joblib_loop, tasks, pics)", number=1))