Run Your Python Code as much as 80x Sooner Utilizing the Cython Library

glorious language for fast prototyping and code growth, however one factor I usually hear folks say about utilizing it’s that it’s sluggish to execute. This can be a specific ache level for information scientists and ML engineers, as they usually carry out computationally intensive operations, akin to matrix multiplication, gradient descent calculations or picture processing.

Over time, Python has developed internally to handle a few of these points by introducing new options to the language, akin to multi-threading or rewriting current performance for improved efficiency. Nonetheless, Python’s use of the World Interpreter Lock (GIL) usually hamstrung efforts like this. 

Many exterior libraries have additionally been written to bridge this perceived efficiency hole between Python and compiled languages akin to Java. Maybe essentially the most used and well-known of those is the NumPy library. Applied within the C language, NumPy was designed from the bottom as much as assist a number of CPU cores and super-fast numerical and array processing.

There are options to NumPy, and in a latest TDS article, I launched the numexpr library, which, in lots of use circumstances, may even outperform NumPy. For those who’re fascinated by studying extra, I’ll embody a hyperlink to that story on the finish of this text.

One other exterior library that may be very efficient is Numba. Numba utilises a Simply-in-Time (JIT) compiler for Python, which interprets a subset of Python and NumPy code into quick machine code at runtime. It’s designed to speed up numerical and scientific computing duties by leveraging LLVM (Low-Stage Digital Machine) compiler infrastructure. 

On this article, I wish to focus on one other runtime-enhancing exterior library, Cython. It’s probably the most performant Python libraries but in addition one of many least understood and used. I feel that is a minimum of partially as a result of you need to get your arms a bit bit soiled and make some modifications to your unique code. However for those who observe the easy four-step plan I’ll define beneath, the efficiency advantages you’ll be able to obtain will make it greater than worthwhile.

What’s Cython?

For those who haven’t heard of Cython, it’s a superset of Python designed to offer C-like efficiency with code written primarily in Python. It permits for changing Python code into C code, which may then be compiled into shared libraries that may be imported into Python identical to common Python modules. This course of ends in the efficiency advantages of C whereas sustaining the readability of Python. 

I’ll showcase the precise advantages you’ll be able to obtain by changing your code to make use of Cython, inspecting three use circumstances and offering the 4 steps required to transform your current Python code, together with comparative timings for every run.

Establishing a growth surroundings

Earlier than persevering with, we should always arrange a separate growth surroundings for coding to maintain our undertaking dependencies separate. I’ll be utilizing WSL2 Ubuntu for Home windows and a Jupyter Pocket book for code growth. I take advantage of the UV bundle supervisor to arrange my growth surroundings, however be happy to make use of no matter instruments and strategies swimsuit you.

$ uv init cython-test
$ cd cython-test
$ uv venv
$ supply .venv/bin/activate
(cython-test) $ uv pip set up cython jupyter numpy pillow matplotlib

Now, sort ‘jupyter pocket book’ into your command immediate. It’s best to see a pocket book open in your browser. If that doesn’t occur robotically, what you’ll seemingly see is a screenful of data after operating the Jupyter Pocket book command. Close to the underside of that, there shall be a URL you must copy and paste into your browser to provoke the Jupyter Pocket book.
Your URL shall be completely different to mine, but it surely ought to look one thing like this:-

http://127.0.0.1:8888/tree?token=3b9f7bd07b6966b41b68e2350721b2d0b6f388d248cc69d

Instance 1 – Dashing up for loops

Earlier than we begin utilizing Cython, let’s start with an everyday Python perform and time how lengthy it takes to run. This shall be our base benchmark.

We’ll code a easy double-for-loop perform that takes a couple of seconds to run, then use Cython to hurry it up and measure the variations in runtime between the 2 strategies.

Right here is our baseline commonplace Python code.

# sum_of_squares.py
import timeit

# Outline the usual Python perform
def slow_sum_of_squares(n):
    complete = 0
    for i in vary(n):
        for j in vary(n):
            complete += i * i + j * j
    return complete

# Benchmark the Python perform
print("Python perform execution time:")
print("timeit:", timeit.timeit(
        lambda: slow_sum_of_squares(20000),
        quantity=1))

On my system, the above code produces the next output.

Python perform execution time:
13.135973724005453

Let’s see how a lot of an enchancment Cython makes of it.

The four-step plan for efficient Cython use.

Utilizing Cython to spice up your code run-time in a Jupyter Pocket book is a straightforward 4-step course of.

Don’t fear for those who’re not a Pocket book consumer, as I’ll present learn how to convert common Python .py recordsdata to make use of Cython afterward.

1/ Within the first cell of your pocket book, load the Cython extension by typing this command.

%load_ext Cython

2/ For any subsequent cells that comprise Python code that you just want to run utilizing cython, add the %%cython magic command earlier than the code. For instance,

%%cython
def myfunction():
    and so on ...
        ...

3/ Perform definitions that comprise parameters should be accurately typed.

4/ Lastly, all variables should be typed appropriately by utilizing the cdef directive. Additionally, the place it is smart, use features from the usual C library (out there in Cython utilizing the from libc.stdlib directive).

Taking our unique Python code for instance, that is what it must appear like to be able to run in a pocket book utilizing cython after making use of all 4 steps above.

%%cython
def fast_sum_of_squares(int n):
    cdef int complete = 0
    cdef int i, j
    for i in vary(n):
        for j in vary(n):
            complete += i * i + j * j
    return complete

import timeit
print("Cython perform execution time:")
print("timeit:", timeit.timeit(
        lambda: fast_sum_of_squares(20000),
        quantity=1))

As I hope you’ll be able to see, the fact of changing your code is way simpler than the 4 procedural steps required may recommend.

The runtime of the above code was spectacular. On my system, this new cython code produces the next output.

Cython perform execution time:
0.15829777799808653

That’s an over 80x speed-up.

Instance 2 — Calculate pi utilizing Monte Carlo 

For our second instance, we’ll study a extra advanced use case, the inspiration of which has quite a few real-world functions.

An space the place Cython can present important efficiency enchancment is in numerical simulations, notably these involving heavy computation, akin to Monte Carlo (MC) simulations. Monte Carlo simulations contain operating many iterations of a random course of to estimate the properties of a system. MC applies to all kinds of examine fields, together with local weather and atmospheric science, pc graphics, AI search and quantitative finance. It’s nearly at all times a really computationally intensive course of.

As an instance, we’ll use Monte Carlo in a simplified method to calculate the worth of Pi. This can be a well-known instance the place we take a sq. with a aspect size of 1 unit and inscribe 1 / 4 circle inside it with a radius of 1 unit, as proven right here.

The ratio of the realm of the quarter circle to the realm of the sq. is, clearly, (Pi/4). 

So, if we contemplate many random (x,y) factors that each one lie inside or on the bounds of the sq., as the entire variety of these factors tends to infinity, the ratio of factors that lie on or contained in the quarter circle to the entire variety of factors tends in direction of Pi /4. We then multiply this worth by 4 to acquire the worth of Pi itself.

Right here is a few typical Python code you may use to mannequin this.

import random
import time

def monte_carlo_pi(num_samples):
    inside_circle = 0
    for _ in vary(num_samples):
        x = random.uniform(0, 1)
        y = random.uniform(0, 1)
        if (x**2) + (y**2) <= 1:  
            inside_circle += 1
    return (inside_circle / num_samples) * 4

# Benchmark the usual Python perform
num_samples = 100000000

start_time = time.time()
pi_estimate = monte_carlo_pi(num_samples)
end_time = time.time()

print(f"Estimated Pi (Python): {pi_estimate}")
print(f"Execution Time (Python): {end_time - start_time} seconds")

Working this produced the next timing consequence.

Estimated Pi (Python): 3.14197216
Execution Time (Python): 20.67279839515686 seconds

Now, right here is the Cython implementation we get by following our four-step course of.

%%cython
import cython
import random
from libc.stdlib cimport rand, RAND_MAX

@cython.boundscheck(False)
@cython.wraparound(False)
def monte_carlo_pi(int num_samples):
    cdef int inside_circle = 0
    cdef int i
    cdef double x, y
    
    for i in vary(num_samples):
        x = rand() / RAND_MAX
        y = rand() / RAND_MAX
        if (x**2) + (y**2) <= 1:
            inside_circle += 1
            
    return (inside_circle / num_samples) * 4

import time

num_samples = 100000000

# Benchmark the Cython perform
start_time = time.time()
pi_estimate = monte_carlo_pi(num_samples)
end_time = time.time()

print(f"Estimated Pi (Cython): {pi_estimate}")
print(f"Execution Time (Cython): {end_time - start_time} seconds")

And right here is the brand new output.

Estimated Pi (Cython): 3.1415012
Execution Time (Cython): 1.9987852573394775 seconds

As soon as once more, that’s a fairly spectacular 10x speed-up for the Cython model.

One factor we did on this code instance that we didn’t within the different is import some exterior libraries from the C commonplace library. That was the road,

from libc.stdlib cimport rand, RAND_MAX

The cimport command is a Cython key phrase used to import C features, variables, constants, and kinds. We used it to import optimised C language variations of the equal random.uniform() Python features.

Instance 3— picture manipulation

For our last instance, we’ll do some picture manipulation. Particularly, some picture convolution, which is a standard operation in picture processing. There are lots of use circumstances for picture convolution. We’re going to make use of it to attempt to sharpen the marginally blurry picture proven beneath.

First, right here is the common Python code.

from PIL import Picture
import numpy as np
from scipy.sign import convolve2d
import time
import os
import matplotlib.pyplot as plt

def sharpen_image_color(picture):

    # Begin timing
    start_time = time.time()
    
    # Convert picture to RGB in case it isn't already
    picture = picture.convert('RGB')
    
    # Outline a sharpening kernel
    kernel = np.array([[0, -1, 0],
                       [-1, 5, -1],
                       [0, -1, 0]])
    
    # Convert picture to numpy array
    image_array = np.array(picture)
    
    # Debugging: Test enter values
    print("Enter array values: Min =", image_array.min(), "Max =", image_array.max())
    
    # Put together an empty array for the sharpened picture
    sharpened_array = np.zeros_like(image_array)
    
    # Apply the convolution kernel to every channel (assuming RGB picture)
    for i in vary(3):
        channel = image_array[:, :, i]
        # Carry out convolution
        convolved_channel = convolve2d(channel, kernel, mode='similar', boundary='wrap')
        
        # Clip values to be within the vary [0, 255]
        convolved_channel = np.clip(convolved_channel, 0, 255)
        
        # Retailer again within the sharpened array
        sharpened_array[:, :, i] = convolved_channel.astype(np.uint8)
    
    # Debugging: Test output values
    print("Sharpened array values: Min =", sharpened_array.min(), "Max =", sharpened_array.max())
    
    # Convert array again to picture
    sharpened_image = Picture.fromarray(sharpened_array)
    
    # Finish timing
    length = time.time() - start_time
    print(f"Processing time: {length:.4f} seconds")
    
    return sharpened_image

# Appropriate path for WSL2 accessing Home windows filesystem
image_path = '/mnt/d/photos/taj_mahal.png'

picture = Picture.open(image_path)

# Sharpen the picture
sharpened_image = sharpen_image_color(picture)

if sharpened_image:
    # Present utilizing PIL's built-in present technique (for debugging)
    #sharpened_image.present(title="Sharpened Picture (PIL Present)")

    # Show the unique and sharpened photos utilizing Matplotlib
    fig, axs = plt.subplots(1, 2, figsize=(15, 7))

    # Authentic picture
    axs[0].imshow(picture)
    axs[0].set_title("Authentic Picture")
    axs[0].axis('off')

    # Sharpened picture
    axs[1].imshow(sharpened_image)
    axs[1].set_title("Sharpened Picture")
    axs[1].axis('off')

    # Present each photos aspect by aspect
    plt.present()
else:
    print("Didn't generate sharpened picture.")

The output is that this.

Enter array values: Min = 0 Max = 255
Sharpened array values: Min = 0 Max = 255
Processing time: 0.1034 seconds

Let’s see if Cython can beat that run time of 0.1034 seconds.

%%cython
# cython: language_level=3
# distutils: define_macros=NPY_NO_DEPRECATED_API=NPY_1_7_API_VERSION

import numpy as np
cimport numpy as np
import cython

@cython.boundscheck(False)
@cython.wraparound(False)
def sharpen_image_cython(np.ndarray[np.uint8_t, ndim=3] image_array):
    # Outline sharpening kernel
    cdef int kernel[3][3]
    kernel[0][0] = 0
    kernel[0][1] = -1
    kernel[0][2] = 0
    kernel[1][0] = -1
    kernel[1][1] = 5
    kernel[1][2] = -1
    kernel[2][0] = 0
    kernel[2][1] = -1
    kernel[2][2] = 0
    
    # Declare variables outdoors of loops
    cdef int peak = image_array.form[0]
    cdef int width = image_array.form[1]
    cdef int channel, i, j, ki, kj
    cdef int worth
    
    # Put together an empty array for the sharpened picture
    cdef np.ndarray[np.uint8_t, ndim=3] sharpened_array = np.zeros_like(image_array)

    # Convolve every channel individually
    for channel in vary(3):  # Iterate over RGB channels
        for i in vary(1, peak - 1):
            for j in vary(1, width - 1):
                worth = 0  # Reset worth at every pixel
                # Apply the kernel
                for ki in vary(-1, 2):
                    for kj in vary(-1, 2):
                        worth += kernel[ki + 1][kj + 1] * image_array[i + ki, j + kj, channel]
                # Clip values to be between 0 and 255
                sharpened_array[i, j, channel] = min(max(worth, 0), 255)

    return sharpened_array

# Python a part of the code
from PIL import Picture
import numpy as np
import time as py_time  # Renaming the Python time module to keep away from battle
import matplotlib.pyplot as plt

# Load the enter picture
image_path = '/mnt/d/photos/taj_mahal.png'
picture = Picture.open(image_path).convert('RGB')

# Convert the picture to a NumPy array
image_array = np.array(picture)

# Time the sharpening with Cython
start_time = py_time.time()
sharpened_array = sharpen_image_cython(image_array)
cython_time = py_time.time() - start_time

# Convert again to a picture for displaying
sharpened_image = Picture.fromarray(sharpened_array)

# Show the unique and sharpened picture
plt.determine(figsize=(12, 6))
plt.subplot(1, 2, 1)
plt.imshow(picture)
plt.title("Authentic Picture")

plt.subplot(1, 2, 2)
plt.imshow(sharpened_image)
plt.title("Sharpened Picture")

plt.present()

# Print the time taken for Cython processing
print(f"Processing time with Cython: {cython_time:.4f} seconds")

The output is,

Each packages carried out properly, however Cython was almost 25 instances quicker.

What about operating Cython outdoors a Pocket book surroundings?

Thus far, all the pieces I’ve proven you assumes you’re operating your code inside a Jupyter Pocket book. The explanation I did that is that it’s the simplest method to introduce Cython and get some code up and operating rapidly. Whereas the Pocket book surroundings is extraordinarily widespread amongst Python builders, an enormous quantity of Python code remains to be contained in common .py recordsdata and run from a terminal utilizing the Python command.

If that’s your major mode of coding and operating Python scripts, the %load_ext and %%cython IPython magic instructions gained’t work since these are solely understood by Jupyter/IPython.

So, right here’s learn how to adapt my four-step Cython conversion course of for those who’re operating your code as an everyday Python script.

Let’s take my first sum_of_squares instance to showcase this.

1/ Create a .pyx file as a substitute of utilizing %%cython

Transfer your Cython-enhanced code right into a file named, for instance:-

sum_of_squares.pyx

# sun_of_squares.pyx
def fast_sum_of_squares(int n):
    cdef int complete = 0
    cdef int i, j
    for i in vary(n):
        for j in vary(n):
            complete += i * i + j * j
    return complete

All we did was take away the %%cython directive and the timing code (which is able to now be within the calling perform)

2/ Create a setup.py file to compile your .pyx file

# setup.py
from setuptools import setup
from Cython.Construct import cythonize

setup(
    identify="cython-test",
    ext_modules=cythonize("sum_of_squares.pyx", language_level=3),
    py_modules=["sum_of_squares"],  # Explicitly state the module
    zip_safe=False,
)

3/ Run the setup.py file utilizing this command,

$ python setup.py build_ext --inplace
operating build_ext
copying construct/lib.linux-x86_64-cpython-311/sum_of_squares.cpython-311-x86_64-linux-g

4/ Create an everyday Python module to name our Cython code, as proven beneath, after which run it.

# fundamental.py
import time, timeit
from sum_of_squares import fast_sum_of_squares

begin = time.time()
consequence = fast_sum_of_squares(20000)

print("timeit:", timeit.timeit(
        lambda: fast_sum_of_squares(20000),
        quantity=1))

$ python fundamental.py

timeit: 0.14675087109208107

Abstract

Hopefully, I’ve satisfied you of the efficacy of utilizing the Cython library in your code. Though it may appear a bit sophisticated at first sight, with a bit effort, you will get unimaginable efficiency enhancements to your run instances over utilizing common Python, even when utilizing quick numerical libraries akin to NumPy. 

I supplied a four-step course of to transform your common Python code to make use of Cython for operating inside Jupyter Pocket book environments. Moreover, I defined the steps required to run Cython code from the command line outdoors a Pocket book surroundings.

Lastly, I bolstered the above by showcasing examples of changing common Python code to make use of Cython.

Within the three examples I confirmed, we achieved positive aspects of 80x, 10x and 25x speed-ups, which isn’t too shabby in any respect.

As promised, here’s a hyperlink to my earlier TDS article on utilising the numexpr library to speed up Python code.