How to use Numba in Python queries

This guide will show you how to use Numba in your Python queries in Deephaven.

Numba is an open-source just-in-time (JIT) compiler for Python. It can be used to translate portions of Python code into optimized machine code using LLVM. The use of Numba can make your queries faster and more responsive.

What is just-in-time (JIT) compilation?

JIT compiles code into optimized machine code at runtime. When using Numba, you can specify which functions and blocks of code you want to be compiled at runtime. Compiling code blocks into optimized machine code adds some overhead, but subsequent function calls can be much faster. Thus, JIT can be powerful when used on functions that are complex, large, or will be used many times.

caution

JIT does not guarantee faster code. Sometimes, code cannot be optimized well by Numba and may actually run slower.

Usage

Numba decorators specify which blocks of code to JIT compile. Common Numba decorators include @jit and @vectorize. See http://numba.pydata.org/ for more details.

In the following example, @jit and @vectorize are used to JIT compile functionOne and functionTwo.

import math
from numba import jit, vectorize, double, int64

@jit
def functionOne(a, b):
    return math.sqrt(a**2 + b**2)

@vectorize([double(double, int64)])
def functionTwo(decimal_value, integer_value):
    return decimal_value * integer_value

Lazy compilation

If the Numba decorator is used without a function signature, Numba will infer the argument types at call time and generate optimized code based upon the inferred types. Numba will also compile separate specializations for different input types. The compilation is deferred to the first function call. This is called lazy compilation.

The example below uses lazy compilation on the function func. When the code is first run, the function is compiled to optimized machine code, which takes extra overhead and results in longer execution time. On the second function call, Python uses the already optimized machine code, which results in very fast execution.

import numpy as np
from numba import jit
import time

# Lazy optimized addition function
@jit
def func(x, y):
    return x + y

x = 0.01 * np.arange(100000)
y = 0.02 * np.arange(100000)

# This function call is slow.  It has to be compiled into optimized machine code.
start = time.time()
z1 = func(x, y)
end = time.time()
print("First function call took " + str(end - start) + " seconds.")

# This function call is fast.  It uses the previously JIT-compiled machine code.
start = time.time()
z2 = func(x, y)
end = time.time()
print("Second function call took " + str(end - start) + " seconds.")

Log

Eager compilation

If the Numba decorator is used with a function signature, Numba will compile the function when the function is defined. This is called eager compilation.

The example below uses eager compilation on the function func by specifying one or more function signatures. These function signatures denote the allowed input and output data types to and from the function. With eager compilation, the code is compiled into optimized machine code at the function definition. When the code is run the first time, it has already been compiled into optimized machine code, so it's just as fast as the second function call. If the compiled function is used with a data type not specified in the function signature, an error will occur.

from numba import vectorize, int64, double
import numpy as np
import time

# Eager compilation for the int64(int64, int64) and double(double, double) function signatures happens here
@vectorize([int64(int64, int64),
            double(double, double)])
def func(x, y):
    z = x + y
    return z

x1 = 0.01 * np.arange(10000)
y1 = 0.02 * np.arange(10000)
x2 = 1 * np.arange(10000)
y2 = 2 * np.arange(10000)

# Run it the first time on doubles
start = time.time()
z1 = func(x1, y1)
end = time.time()
print("Add vectors of doubles (first run): " + str(end - start) + " seconds.")

# Run it a second time on doubles
start = time.time()
z2 = func(x1, y1)
end = time.time()
print("Add vectors of doubles (second run): " + str(end - start) + " seconds.")

# Run it the first time on integers
start = time.time()
z3 = func(x2, y2)
end = time.time()
print("Add vectors of integers (first run): " + str(end - start) + " seconds.")

# Run it a second time on integers
start = time.time()
z4 = func(x2, y2)
end = time.time()
print("Add vectors of integers (second run): " + str(end - start) + " seconds.")

Log

caution

Eager compilation creates functions that only support specific function signatures. If these functions are applied to arguments of mismatched types, an error will occur.

@jit vs @vectorize

We've seen the @jit and @vectorize decorators used to optimize various functions. So far, they've been used without an explanation of how they differ. So, what is different about each decorator?

• @jit is a general-purpose decorator that can optimize a wide variety of different functions.
• @vectorize is a decorator meant to allow functions that operate on arrays to be written as if they operate on scalars.

This can be visualized with a simple example:

from numba import jit, vectorize, int64
import numpy as np

x = np.arange(5)
y = x + 5

@jit([int64(int64, int64)])
def jitAddArrays(x, y):
    return x + y

@vectorize([int64(int64, int64)])
def vectorizeAddArrays(x, y):
    return x + y

z1 = vectorizeAddArrays(x, y)

print(z1)

z2 = jitAddArrays(x, y)

print(z2)

Functions created using @vectorize can be applied to arrays. However, attempting to do the same with @jit results in an error.

Examples

Numpy matrix

The following example uses jit to calculate the element-wise sum of a 250x250 matrix. This is a total of 62,500 additions.

Here, the nopython=True option is used. This option produces faster, primitive-optimized code that does not need the Python interpreter to execute. Without this flag, Numba will fall back to the slower object mode in some circumstances.

This example looks at three cases:

• A regular function without JIT
• A JIT function that needs compilation
• A JIT function that is already compiled

The first time the JIT-enabled function is run on a matrix of integers, it's almost ten times slower than the standard function. However, after compilation, the JIT-enabled function is almost two hundred times faster!

from numba import jit
import numpy as np
import time

x = np.arange(62500).reshape(250, 250)
y = 0.01 * x

def calc(a):
    matrix_sum = 0.0
    for i in range(a.shape[0]):
        for j in range(a.shape[1]):
            matrix_sum += a[i, j]
    return matrix_sum

@jit(nopython=True)
def jitCalc(a):
    matrix_sum = 0.0
    for i in range(a.shape[0]):
        for j in range(a.shape[1]):
            matrix_sum += a[i, j]
    return matrix_sum

# Time without JIT
start = time.time()
calc(x)
end = time.time()
print("Execution time (without JIT) = %s" % (end - start))

# Time with compilation and JIT
start = time.time()
jitCalc(x)
end = time.time()
print("Execution time (JIT + compilation) = %s" % (end - start))

# Time with JIT (already compiled)
start = time.time()
jitCalc(x)
end = time.time()
print("Execution time (JIT) = %s" % (end - start))

Log

Using Deephaven tables

To show how the performance of @jit and @vectorize differ when applied to Deephaven tables, we will create identical functions that use these decorators. We then measure the performance of creating new columns in a 625,000 row table when using the functions.

from deephaven import empty_table
from numba import jit, vectorize, double, int64
import time

def addColumns(A, B):
    return A + B

@jit([int64(int64, int64)])
def jitAddColumns(A, B):
    return A + B

@vectorize([int64(int64, int64)])
def vectorizeAddColumns(A, B):
    return A + B

def cubicFunc(C):
    return 0.0025 * C**3 - 1.75 * C**2 - C + 10

@jit([double(int64)])
def jitCubicFunc(C):
    return 0.0025 * C**3 - 1.75 * C**2 - C + 10

@vectorize([double(int64)])
def vectorizeCubicFunc(C):
    return 0.0025 * C**3 - 1.75 * C**2 - C + 10

t = empty_table(625000).update(formulas=["A = ii", "B = ii"])

# Time column addition without Numba
start = time.time()
t2 = t.update(formulas=["C = addColumns(A, B)"])
end = time.time()
print("column addition - Execution time (without Numba) = %s" % (end - start))

# Time column addition with jit
start = time.time()
t3 = t.update(formulas=["C = jitAddColumns(A, B)"])
end = time.time()
print("column addition - Execution time (jit) = %s" % (end - start))

# Time column addition with vectorize
start = time.time()
t4 = t.update(formulas=["C = vectorizeAddColumns(A, B)"])
end = time.time()
print("column addition - Execution time (vectorize) = %s" % (end - start))

# Time cubic polynomial without Numba
start = time.time()
t5 = t2.update(formulas=["D = cubicFunc(C)"])
end = time.time()
print("cubic polynomial - Execution time (without Numba) = %s" % (end - start))

# Time cubic polynomial with jit
start = time.time()
t5 = t2.update(formulas=["D = jitCubicFunc(C)"])
end = time.time()
print("cubic polynomial - Execution time (jit) = %s" % (end - start))

# Time a cubic polynomial with vectorize
start = time.time()
t6 = t2.update(formulas=["D = vectorizeCubicFunc(C)"])
end = time.time()
print("cubic polynomial - Execution time (vectorize) = %s" % (end - start))

t

t2

t3

t4

t5

t6

The use of @jit with functions operating on Deephaven tables results in a very small performance increase over its standard counterparts. This performance increase is small enough to make the additional overhead of compiling the function into optimized machine code not worth it.

The use of @vectorize with functions operating on Deephaven tables results in a large performance increase over its standard counterparts. This performance increase is large enough to warrant the additional overhead associated with compiling the function into optimized machine code.

Related documentation

• How to select data in tables
• empty_table
• update