Merge pull request #2465 from gabrieldemarmiesse/simplifying_memoryview_numpy

Changed the numpy tutorial to make is faster to understand.

.gitignore

@@ -28,6 +28,8 @@ Tools/*.elc
 *.swp
 *~
 
+.ipynb_checkpoints
+
 tags
 TAGS
 MANIFEST

docs/examples/userguide/numpy_tutorial/compute_fused_types.pyx

+# cython: infer_types=True
+import numpy as np
+cimport cython
+
+ctypedef fused my_type:
+    int
+    double
+    long long
+
+
+cdef my_type clip(my_type a, my_type min_value, my_type max_value):
+    return min(max(a, min_value), max_value)
+
+
+@cython.boundscheck(False)
+@cython.wraparound(False)
+def compute(my_type[:, ::1] array_1, my_type[:, ::1] array_2, my_type a, my_type b, my_type c):
+     
+    x_max = array_1.shape[0]
+    y_max = array_1.shape[1]
+    
+    assert tuple(array_1.shape) == tuple(array_2.shape)
+
+    if my_type is int:
+        dtype = np.intc
+    elif my_type is double:
+        dtype = np.double
+    elif my_type is cython.longlong:
+        dtype = np.longlong
+
+    result = np.zeros((x_max, y_max), dtype=dtype)
+    cdef my_type[:, ::1] result_view = result
+
+    cdef my_type tmp
+    cdef Py_ssize_t x, y
+
+    for x in range(x_max):
+        for y in range(y_max):
+
+            tmp = clip(array_1[x, y], 2, 10)
+            tmp = tmp * a + array_2[x, y] * b
+            result_view[x, y] = tmp + c
+
+    return result

docs/examples/userguide/numpy_tutorial/compute_infer_types.pyx

+# cython: infer_types=True
+import numpy as np
+cimport cython
+
+DTYPE = np.intc
+
+
+cdef int clip(int a, int min_value, int max_value):
+    return min(max(a, min_value), max_value)
+
+
+@cython.boundscheck(False)
+@cython.wraparound(False)
+def compute(int[:, ::1] array_1, int[:, ::1] array_2, int a, int b, int c):
+     
+    x_max = array_1.shape[0]
+    y_max = array_1.shape[1]
+    
+    assert tuple(array_1.shape) == tuple(array_2.shape)
+
+    result = np.zeros((x_max, y_max), dtype=DTYPE)
+    cdef int[:, ::1] result_view = result
+
+    cdef int tmp
+    cdef Py_ssize_t x, y
+
+    for x in range(x_max):
+        for y in range(y_max):
+
+            tmp = clip(array_1[x, y], 2, 10)
+            tmp = tmp * a + array_2[x, y] * b
+            result_view[x, y] = tmp + c
+
+    return result

docs/examples/userguide/numpy_tutorial/compute_memview.pyx

+import numpy as np
+
+DTYPE = np.intc
+
+
+cdef int clip(int a, int min_value, int max_value):
+    return min(max(a, min_value), max_value)
+
+
+def compute(int[:, :] array_1, int[:, :] array_2, int a, int b, int c):
+     
+    cdef Py_ssize_t x_max = array_1.shape[0]
+    cdef Py_ssize_t y_max = array_1.shape[1]
+
+    # array_1.shape is now a C array, no it's not possible
+    # to compare it simply by using == without a for-loop.
+    # To be able to compare it to array_2.shape easily,
+    # we convert them both to Python tuples.
+    assert tuple(array_1.shape) == tuple(array_2.shape)
+
+    result = np.zeros((x_max, y_max), dtype=DTYPE)
+    cdef int[:, :] result_view = result
+
+    cdef int tmp
+    cdef Py_ssize_t x, y
+
+    for x in range(x_max):
+        for y in range(y_max):
+
+            tmp = clip(array_1[x, y], 2, 10)
+            tmp = tmp * a + array_2[x, y] * b
+            result_view[x, y] = tmp + c
+
+    return result

docs/examples/userguide/numpy_tutorial/compute_prange.pyx

+# distutils: extra_compile_args=-fopenmp
+# distutils: extra_link_args=-fopenmp
+import numpy as np
+cimport cython
+from cython.parallel import prange
+
+ctypedef fused my_type:
+    int
+    double
+    long long
+
+
+# We declare our plain c function nogil
+cdef my_type clip(my_type a, my_type min_value, my_type max_value) nogil:
+    return min(max(a, min_value), max_value)
+
+
+@cython.boundscheck(False)
+@cython.wraparound(False)
+def compute(my_type[:, ::1] array_1, my_type[:, ::1] array_2, my_type a, my_type b, my_type c):
+
+    cdef Py_ssize_t x_max = array_1.shape[0]
+    cdef Py_ssize_t y_max = array_1.shape[1]
+
+    assert tuple(array_1.shape) == tuple(array_2.shape)
+
+    if my_type is int:
+        dtype = np.intc
+    elif my_type is double:
+        dtype = np.double
+    elif my_type is cython.longlong:
+        dtype = np.longlong
+
+    result = np.zeros((x_max, y_max), dtype=dtype)
+    cdef my_type[:, ::1] result_view = result
+
+    cdef my_type tmp
+    cdef Py_ssize_t x, y
+
+    # We use prange here.
+    for x in prange(x_max, nogil=True):
+        for y in range(y_max):
+
+            tmp = clip(array_1[x, y], 2, 10)
+            tmp = tmp * a + array_2[x, y] * b
+            result_view[x, y] = tmp + c
+
+    return result

docs/examples/userguide/numpy_tutorial/compute_py.py

+import numpy as np
+
+
+def clip(a, min_value, max_value):
+    return min(max(a, min_value), max_value)
+
+
+def compute(array_1, array_2, a, b, c):
+    """
+    This function must implement the formula
+    np.clip(array_1, 2, 10) * a + array_2 * b + c
+
+    array_1 and array_2 are 2D.
+    """
+    x_max = array_1.shape[0]
+    y_max = array_1.shape[1]
+
+    assert array_1.shape == array_2.shape
+
+    result = np.zeros((x_max, y_max), dtype=array_1.dtype)
+
+    for x in range(x_max):
+        for y in range(y_max):
+            tmp = clip(array_1[x, y], 2, 10)
+            tmp = tmp * a + array_2[x, y] * b
+            result[x, y] = tmp + c
+
+    return result

docs/examples/userguide/numpy_tutorial/convolve_typed.pyx → docs/examples/userguide/numpy_tutorial/compute_typed.pyx

@@ -5,49 +5,46 @@ import numpy as np
 # type info object.
 DTYPE = np.intc
 
-def naive_convolve(f, g):
-    if g.shape[0] % 2 != 1 or g.shape[1] % 2 != 1:
-        raise ValueError("Only odd dimensions on filter supported")
-    assert f.dtype == DTYPE and g.dtype == DTYPE
+# cdef means here that this function is a plain C function (so faster).
+# To get all the benefits, we type the arguments and the return value.
+cdef int clip(int a, int min_value, int max_value):
+    return min(max(a, min_value), max_value)
+
+
+def compute(array_1, array_2, int a, int b, int c):
+    
     # The "cdef" keyword is also used within functions to type variables. It
     # can only be used at the top indentation level (there are non-trivial
     # problems with allowing them in other places, though we'd love to see
     # good and thought out proposals for it).
+    cdef Py_ssize_t x_max = array_1.shape[0]
+    cdef Py_ssize_t y_max = array_1.shape[1]
+    
+    assert array_1.shape == array_2.shape
+    assert array_1.dtype == DTYPE
+    assert array_2.dtype == DTYPE
 
-    # Py_ssize_t is the proper C type for Python array indices.
-    cdef Py_ssize_t x, y, s, t, v, w, s_from, s_to, t_from, t_to
-
-    cdef Py_ssize_t vmax = f.shape[0]
-    cdef Py_ssize_t wmax = f.shape[1]
-    cdef Py_ssize_t smax = g.shape[0]
-    cdef Py_ssize_t tmax = g.shape[1]
-    cdef Py_ssize_t smid = smax // 2
-    cdef Py_ssize_t tmid = tmax // 2
-    cdef Py_ssize_t xmax = vmax + 2*smid
-    cdef Py_ssize_t ymax = wmax + 2*tmid
-    h = np.zeros([xmax, ymax], dtype=DTYPE)
+    result = np.zeros((x_max, y_max), dtype=DTYPE)
+    
     # It is very important to type ALL your variables. You do not get any
     # warnings if not, only much slower code (they are implicitly typed as
     # Python objects).
-    # For the value variable, we want to use the same data type as is
+    # For the "tmp" variable, we want to use the same data type as is
     # stored in the array, so we use int because it correspond to np.intc.
-    # NB! An important side-effect of this is that if "value" overflows its
+    # NB! An important side-effect of this is that if "tmp" overflows its
     # datatype size, it will simply wrap around like in C, rather than raise
     # an error like in Python.
-    cdef int value
-    for x in range(xmax):
-        for y in range(ymax):
-            # Cython has built-in C functions for min and max.
-            # This makes the following lines very fast.
-            s_from = max(smid - x, -smid)
-            s_to = min((xmax - x) - smid, smid + 1)
-            t_from = max(tmid - y, -tmid)
-            t_to = min((ymax - y) - tmid, tmid + 1)
-            value = 0
-            for s in range(s_from, s_to):
-                for t in range(t_from, t_to):
-                    v = x - smid + s
-                    w = y - tmid + t
-                    value += g[smid - s, tmid - t] * f[v, w]
-            h[x, y] = value
-    return h
\ No newline at end of file
+
+    cdef int tmp
+
+    # Py_ssize_t is the proper C type for Python array indices.
+    cdef Py_ssize_t x, y
+
+    for x in range(x_max):
+        for y in range(y_max):
+
+            tmp = clip(array_1[x, y], 2, 10)
+            tmp = tmp * a + array_2[x, y] * b
+            result[x, y] = tmp + c
+
+    return result

docs/examples/userguide/numpy_tutorial/convolve_fused_types.pyx

-# cython: infer_types=True
-import numpy as np
-cimport cython
-
-ctypedef fused my_type:
-    int
-    double
-    long
-
-@cython.boundscheck(False)
-@cython.wraparound(False)
-cpdef naive_convolve(my_type [:,:] f, my_type [:,:] g):
-    if g.shape[0] % 2 != 1 or g.shape[1] % 2 != 1:
-        raise ValueError("Only odd dimensions on filter supported")
-
-    vmax = f.shape[0]
-    wmax = f.shape[1]
-    smax = g.shape[0]
-    tmax = g.shape[1]
-    smid = smax // 2
-    tmid = tmax // 2
-    xmax = vmax + 2*smid
-    ymax = wmax + 2*tmid
-
-    if my_type is int:
-        dtype = np.intc
-    elif my_type is double:
-        dtype = np.double
-    else:
-        dtype = np.long
-
-    h_np =  np.zeros([xmax, ymax], dtype=dtype)
-    cdef my_type [:,:] h = h_np
-
-    cdef my_type value
-    for x in range(xmax):
-        for y in range(ymax):
-            s_from = max(smid - x, -smid)
-            s_to = min((xmax - x) - smid, smid + 1)
-            t_from = max(tmid - y, -tmid)
-            t_to = min((ymax - y) - tmid, tmid + 1)
-            value = 0
-            for s in range(s_from, s_to):
-                for t in range(t_from, t_to):
-                    v = x - smid + s
-                    w = y - tmid + t
-                    value += g[smid - s, tmid - t] * f[v, w]
-            h[x, y] = value
-    return h_np
\ No newline at end of file

docs/examples/userguide/numpy_tutorial/convolve_infer_types.pyx

-# cython: infer_types=True
-import numpy as np
-cimport cython
-
-DTYPE = np.intc
-
-@cython.boundscheck(False)
-@cython.wraparound(False)
-def naive_convolve(int [:,::1] f, int [:,::1] g):
-    if g.shape[0] % 2 != 1 or g.shape[1] % 2 != 1:
-        raise ValueError("Only odd dimensions on filter supported")
-
-    vmax = f.shape[0]
-    wmax = f.shape[1]
-    smax = g.shape[0]
-    tmax = g.shape[1]
-    smid = smax // 2
-    tmid = tmax // 2
-    xmax = vmax + 2*smid
-    ymax = wmax + 2*tmid
-
-    h_np =  np.zeros([xmax, ymax], dtype=DTYPE)
-    cdef int [:,::1] h = h_np
-
-    cdef int value
-    for x in range(xmax):
-        for y in range(ymax):
-            s_from = max(smid - x, -smid)
-            s_to = min((xmax - x) - smid, smid + 1)
-            t_from = max(tmid - y, -tmid)
-            t_to = min((ymax - y) - tmid, tmid + 1)
-            value = 0
-            for s in range(s_from, s_to):
-                for t in range(t_from, t_to):
-                    v = x - smid + s
-                    w = y - tmid + t
-                    value += g[smid - s, tmid - t] * f[v, w]
-            h[x, y] = value
-    return h_np
\ No newline at end of file

docs/examples/userguide/numpy_tutorial/convolve_memview.pyx

-import numpy as np
-
-DTYPE = np.intc
-
-# It is possible to declare types in the function declaration.
-def naive_convolve(int [:,:] f, int [:,:] g):
-    if g.shape[0] % 2 != 1 or g.shape[1] % 2 != 1:
-        raise ValueError("Only odd dimensions on filter supported")
-
-    # We don't need to check for the type of NumPy array here because
-    # a check is already performed when calling the function.
-    cdef Py_ssize_t x, y, s, t, v, w, s_from, s_to, t_from, t_to
-    cdef Py_ssize_t vmax = f.shape[0]
-    cdef Py_ssize_t wmax = f.shape[1]
-    cdef Py_ssize_t smax = g.shape[0]
-    cdef Py_ssize_t tmax = g.shape[1]
-    cdef Py_ssize_t smid = smax // 2
-    cdef Py_ssize_t tmid = tmax // 2
-    cdef Py_ssize_t xmax = vmax + 2*smid
-    cdef Py_ssize_t ymax = wmax + 2*tmid
-
-    h_np =  np.zeros([xmax, ymax], dtype=DTYPE)
-    cdef int [:,:] h = h_np
-
-    cdef int value
-    for x in range(xmax):
-        for y in range(ymax):
-            s_from = max(smid - x, -smid)
-            s_to = min((xmax - x) - smid, smid + 1)
-            t_from = max(tmid - y, -tmid)
-            t_to = min((ymax - y) - tmid, tmid + 1)
-            value = 0
-            for s in range(s_from, s_to):
-                for t in range(t_from, t_to):
-                    v = x - smid + s
-                    w = y - tmid + t
-                    value += g[smid - s, tmid - t] * f[v, w]
-            h[x, y] = value
-    return h_np
\ No newline at end of file

docs/examples/userguide/numpy_tutorial/convolve_py.py

-from __future__ import division
-import numpy as np
-def naive_convolve(f, g):
-    # f is an image and is indexed by (v, w)
-    # g is a filter kernel and is indexed by (s, t),
-    #   it needs odd dimensions
-    # h is the output image and is indexed by (x, y),
-    #   it is not cropped
-    if g.shape[0] % 2 != 1 or g.shape[1] % 2 != 1:
-        raise ValueError("Only odd dimensions on filter supported")
-    # smid and tmid are number of pixels between the center pixel
-    # and the edge, ie for a 5x5 filter they will be 2.
-    #
-    # The output size is calculated by adding smid, tmid to each
-    # side of the dimensions of the input image.
-    vmax = f.shape[0]
-    wmax = f.shape[1]
-    smax = g.shape[0]
-    tmax = g.shape[1]
-    smid = smax // 2
-    tmid = tmax // 2
-    xmax = vmax + 2*smid
-    ymax = wmax + 2*tmid
-    # Allocate result image.
-    h = np.zeros([xmax, ymax], dtype=f.dtype)
-    # Do convolution
-    for x in range(xmax):
-        for y in range(ymax):
-            # Calculate pixel value for h at (x,y). Sum one component
-            # for each pixel (s, t) of the filter g.
-            s_from = max(smid - x, -smid)
-            s_to = min((xmax - x) - smid, smid + 1)
-            t_from = max(tmid - y, -tmid)
-            t_to = min((ymax - y) - tmid, tmid + 1)
-            value = 0
-            for s in range(s_from, s_to):
-                for t in range(t_from, t_to):
-                    v = x - smid + s
-                    w = y - tmid + t
-                    value += g[smid - s, tmid - t] * f[v, w]
-            h[x, y] = value
-    return h