Use Cython to speed up array iteration in NumPy

NumPy is understood for being quick, however may it go even quicker? Here is the way to use Cython to speed up array iterations in NumPy.

NumPy provides Python customers a wickedly quick library for working with information in matrixes. If you need, as an illustration, to generate a matrix populated with random numbers, you are able to do that in a fraction of the time it could soak up standard Python.

Nonetheless, there are occasions when even NumPy by itself is not quick sufficient. If you wish to carry out transformations on NumPy matrixes that are not obtainable in NumPy’s API, a typical strategy is to only iterate over the matrix in Python … and lose all of the efficiency advantages of utilizing NumPy within the first place.

Fortuitously, there’s a greater option to work instantly with NumPy information: Cython. By writing type-annotated Python code and compiling it to C, you’ll be able to iterate over NumPy arrays and work instantly with their information on the velocity of C.

This text walks by way of some key ideas for the way to use Cython with NumPy. Should you’re not already acquainted with Cython, learn up on the fundamentals of Cython and take a look at this easy tutorial for writing Cython code.

Write solely core computation code in Cython for NumPy

The most typical state of affairs for utilizing Cython with NumPy is one the place you wish to take a NumPy array, iterate over it, and carry out computations on every factor that may’t be completed readily in NumPy.

Cython works by letting you write modules in a type-annotated model of Python, that are then compiled to C and imported into your Python script like another module. In different phrases, you write one thing akin to a Python model of what you wish to accomplish, then velocity it up by including annotations that enable it to be translated into C.

To that finish, you need to solely use Cython for the a part of your program that does the precise computation. Every thing else that is not performance-sensitive—that’s, every thing that is not truly the loop that iterates over your information—ought to be written in common Python.

Why do that? Cython modules need to be recompiled every time they’re modified, which slows down the event course of. You do not wish to need to recompile your Cython modules each time you make adjustments that are not truly in regards to the a part of your program you are making an attempt to optimize.

Iterate by way of NumPy arrays in Cython, not Python

The final technique for working effectively with NumPy in Cython might be summed up in three steps:

1. Write features in Cython that settle for NumPy arrays as correctly typed objects. If you name the Cython operate in your Python code, ship the complete NumPy array object as an argument for that operate name.
2. Carry out all of the iteration over the thing in Cython.
3. Return a NumPy array out of your Cython module to your Python code.

So, do not do one thing like this:

for index in len(numpy_array):
    numpy_array[index] = cython_function(numpy_array[index])

Reasonably, do one thing like this:

returned_numpy_array = cython_function(numpy_array)

# in cython:

cdef cython_function(numpy_array):
    for merchandise in numpy_array:
        ...
    return numpy_array

I omitted sort data and different particulars from these samples, however the distinction ought to be clear. The precise iteration over the NumPy array ought to be completed fully in Cython, not by way of repeated calls to Cython for every factor within the array.

Go correctly typed NumPy arrays to Cython features

Any features that settle for a NumPy array as an argument ought to be correctly typed, in order that Cython is aware of the way to interpret the argument as a NumPy array (quick) reasonably than a generic Python object (sluggish).

Here is an instance of a Cython operate declaration that takes in a two-dimensional NumPy array:

def compute(int[:, ::1] array_1):

In Cython’s “pure Python” syntax, you’d use this annotation:

def compute(array_1: cython.int[:, ::1]):

The int[] annotation signifies an array of integers, doubtlessly a NumPy array. However to be as exact as potential, we have to point out the variety of dimensions within the array. For 2 dimensions, we might use int[:,:]; for 3, we might use int[:,:,:].

We additionally ought to point out the reminiscence structure for the array. By default in NumPy and Cython, arrays are specified by a contiguous style appropriate with C. ::1 is our final factor within the above pattern, so we use int[:,::1] as our signature. (For particulars on different reminiscence structure choices, see Cython’s documentation.)

These declarations inform Cython not simply that these are NumPy arrays, however the way to learn from them in probably the most environment friendly approach potential.

Use Cython memoryviews for quick entry to NumPy arrays

Cython has a function named typed memoryviews that provides you direct learn/write entry to many kinds of objects that work like arrays. That features—you guessed it—NumPy arrays.

To create a memoryview, you utilize the same syntax to the array declarations proven above:

# standard Cython
def compute(int[:, ::1] array_1):
    cdef int [:,:] view2d = array_1

# pure-Python mode    
def compute(array_1: cython.int[:, ::1]):
    view2d: int[:,:] = array_1

Notice that you just needn’t specify the reminiscence structure within the declaration, as that is detected routinely.

From this level on in your code, you’d learn from and write to view2d with the identical accessing syntax as you’ll the array_1 object (e.g., view2d). Any reads and writes are completed on to the underlying area of reminiscence that makes up the array (once more: quick), reasonably than by utilizing the object-accessor interfaces (once more: sluggish).

Index, do not iterate, by way of NumPy arrays

Python customers know by now the popular metaphor for stepping by way of the weather of an object is for merchandise in object:. You need to use this metaphor in Cython, as nicely, however it does not yield the absolute best velocity when working with a NumPy array or memoryview. For that, you may wish to use C-style indexing.

Here is an instance of the way to use indexing for NumPy arrays:

# standard Cython:
cimport cython
@cython.boundscheck(False)
@cython.wraparound(False)
def compute(int[:, ::1] array_1):
    # get the utmost dimensions of the array
    cdef Py_ssize_t x_max = array_1.form[0]
    cdef Py_ssize_t y_max = array_1.form[1]
    
    #create a memoryview
    cdef int[:, :] view2d = array_1

    # entry the memoryview by the use of our constrained indexes
    for x in vary(x_max):
        for y in vary(y_max):
            view2d[x,y] = one thing()


# pure-Python mode:  
import cython
@cython.boundscheck(False)
@cython.wraparound(False)
def compute(array_1: cython.int[:, ::1]):
    # get the utmost dimensions of the array
    x_max: cython.size_t = array_1.form[0]
    y_max: cython.size_t = array_1.form[1]
    
    #create a memoryview
    view2d: int[:,:] = array_1

    # entry the memoryview by the use of our constrained indexes
    for x in vary(x_max):
        for y in vary(y_max):
            view2d[x,y] = one thing()

On this instance, we use the NumPy array’s .form attribute to acquire its dimensions. We then use vary() to iterate by way of the memoryview with these dimensions as a constraint. We do not enable arbitrary entry to some a part of the array, for instance, by the use of a user-submitted variable, so there is no danger of going out of bounds.

You will additionally discover we’ve got @cython.boundscheck(False) and @cython.wraparound(False) decorators on our features. By default, Cython allows choices that guard towards making errors with array accessors, so you do not find yourself studying exterior the bounds of an array by mistake. The checks decelerate entry to the array, nevertheless, as a result of each operation must be bounds-checked. Utilizing the decorators disables these guards by making them pointless. We have already decided what the bounds of the array are, and we do not go previous them.