2.7. Supported NumPy features

One objective of Numba is having a seamless integration with NumPy. NumPy arrays provide an efficient storage method for homogeneous sets of data. NumPy dtypes provide type information useful when compiling, and the regular, structured storage of potentially large amounts of data in memory provides an ideal memory layout for code generation. Numba excels at generating code that executes on top of NumPy arrays.

NumPy support in Numba comes in many forms:

  • Numba understands calls to NumPy ufuncs and is able to generate equivalent native code for many of them.
  • NumPy arrays are directly supported in Numba. Access to Numpy arrays is very efficient, as indexing is lowered to direct memory accesses when possible.
  • Numba is able to generate ufuncs and gufuncs. This means that it is possible to implement ufuncs and gufuncs within Python, getting speeds comparable to that of ufuncs/gufuncs implemented in C extension modules using the NumPy C API.

The following sections focus on the Numpy features supported in nopython mode, unless otherwise stated.

2.7.1. Scalar types

Numba supports the following Numpy scalar types:

  • Integers: all integers of either signedness, and any width up to 64 bits
  • Booleans
  • Real numbers: single-precision (32-bit) and double-precision (64-bit) reals
  • Complex numbers: single-precision (2x32-bit) and double-precision (2x64-bit) complex numbers
  • Datetimes and timestamps: of any unit
  • Character sequences (but no operations are available on them)
  • Structured scalars: structured scalars made of any of the types above and arrays of the types above

The following scalar types and features are not supported:

  • Arbitrary Python objects
  • Half-precision and extended-precision real and complex numbers
  • Nested structured scalars the fields of structured scalars may not contain other structured scalars

The operations supported on scalar Numpy numbers are the same as on the equivalent built-in types such as int or float. You can use a type’s constructor to convert from a different type or width.

Structured scalars support attribute getting and setting, as well as member lookup using constant strings.

See also

Numpy scalars reference.

2.7.2. Array types

Numpy arrays of any of the scalar types above are supported, regardless of the shape or layout.

2.7.2.1. Array access

Arrays support normal iteration. Full basic indexing and slicing is supported. A subset of advanced indexing is also supported: only one advanced index is allowed, and it has to be a one-dimensional array (it can be combined with an arbitrary number of basic indices as well).

See also

Numpy indexing reference.

2.7.2.2. Attributes

The following attributes of Numpy arrays are supported:

2.7.2.2.1. The flags object

The object returned by the flags attribute supports the contiguous, c_contiguous and f_contiguous attributes.

2.7.2.2.2. The flat object

The object returned by the flat attribute supports iteration and indexing, but be careful: indexing is very slow on non-C-contiguous arrays.

2.7.2.2.3. The real and imag attributes

Numpy supports these attributes regardless of the dtype but Numba chooses to limit their support to avoid potential user error. For numeric dtypes, Numba follows Numpy’s behavior. The real attribute returns a view of the real part of the complex array and it behaves as an identity function for other numeric dtypes. The imag attribute returns a view of the imaginary part of the complex array and it returns a zero array with the same shape and dtype for other numeric dtypes. For non-numeric dtypes, including all structured/record dtypes, using these attributes will result in a compile-time (TypingError) error. This behavior differs from Numpy’s but it is chosen to avoid the potential confusion with field names that overlap these attributes.

2.7.2.3. Calculation

The following methods of Numpy arrays are supported in their basic form (without any optional arguments):

The corresponding top-level Numpy functions (such as numpy.prod()) are similarly supported.

2.7.2.4. Other methods

The following methods of Numpy arrays are supported:

  • argsort() (without arguments)
  • astype() (only the 1-argument form)
  • copy() (without arguments)
  • dot() (only the 1-argument form)
  • flatten() (no order argument; ‘C’ order only)
  • item() (without arguments)
  • itemset() (only the 1-argument form)
  • ravel() (no order argument; ‘C’ order only)
  • reshape() (only the 1-argument form)
  • sort() (without arguments)
  • sum() (with or without the axis argument)
    • If the axis argument is a compile-time constant, all valid values are supported. An out-of-range value will result in a LoweringError at compile-time.
    • If the axis argument is not a compile-time constant, only values from 0 to 3 are supported. An out-of-range value will result in a runtime exception.
  • transpose()
  • view() (only the 1-argument form)

Warning

Sorting may be slightly slower than Numpy’s implementation.

2.7.3. Functions

2.7.3.1. Linear algebra

Basic linear algebra is supported on 1-D and 2-D contiguous arrays of floating-point and complex numbers:

Note

The implementation of these functions needs Scipy 0.16+ to be installed.

2.7.3.2. Reductions

The following reduction functions are supported:

2.7.3.3. Other functions

The following top-level functions are supported:

The following constructors are supported, both with a numeric input (to construct a scalar) or a sequence (to construct an array):

  • numpy.bool_
  • numpy.complex64
  • numpy.complex128
  • numpy.float32
  • numpy.float64
  • numpy.int8
  • numpy.int16
  • numpy.int32
  • numpy.int64
  • numpy.intc
  • numpy.intp
  • numpy.uint8
  • numpy.uint16
  • numpy.uint32
  • numpy.uint64
  • numpy.uintc
  • numpy.uintp

The following machine parameter classes are supported, with all purely numerical attributes:

2.7.3.4. Literal arrays

Neither Python nor Numba has actual array literals, but you can construct arbitrary arrays by calling numpy.array() on a nested tuple:

a = numpy.array(((a, b, c), (d, e, f)))

(nested lists are not yet supported by Numba)

2.7.4. Modules

2.7.4.1. random

Numba supports top-level functions from the numpy.random module, but does not allow you to create individual RandomState instances. The same algorithms are used as for the standard random module (and therefore the same notes apply), but with an independent internal state: seeding or drawing numbers from one generator won’t affect the other.

The following functions are supported.

2.7.4.1.1. Initialization

2.7.4.1.3. Permutations

2.7.4.1.4. Distributions

Warning

The size argument is not supported in the following functions.

Note

Calling numpy.random.seed() from non-Numba code (or from object mode code) will seed the Numpy random generator, not the Numba random generator.

Note

The generator is not thread-safe when releasing the GIL.

Also, under Unix, if creating a child process using os.fork() or the multiprocessing module, the child’s random generator will inherit the parent’s state and will therefore produce the same sequence of numbers (except when using the “forkserver” start method under Python 3.4 and later).

2.7.4.2. stride_tricks

The following function from the numpy.lib.stride_tricks module is supported:

  • as_strided() (the strides argument is mandatory, the subok argument is not supported)

2.7.5. Standard ufuncs

One objective of Numba is having all the standard ufuncs in NumPy understood by Numba. When a supported ufunc is found when compiling a function, Numba maps the ufunc to equivalent native code. This allows the use of those ufuncs in Numba code that gets compiled in nopython mode.

2.7.5.1. Limitations

Right now, only a selection of the standard ufuncs work in nopython mode. Following is a list of the different standard ufuncs that Numba is aware of, sorted in the same way as in the NumPy documentation.

2.7.5.2. Math operations

UFUNC MODE
name object mode nopython mode
add Yes Yes
subtract Yes Yes
multiply Yes Yes
divide Yes Yes
logaddexp Yes Yes
logaddexp2 Yes Yes
true_divide Yes Yes
floor_divide Yes Yes
negative Yes Yes
power Yes Yes
remainder Yes Yes
mod Yes Yes
fmod Yes Yes
abs Yes Yes
absolute Yes Yes
fabs Yes Yes
rint Yes Yes
sign Yes Yes
conj Yes Yes
exp Yes Yes
exp2 Yes Yes
log Yes Yes
log2 Yes Yes
log10 Yes Yes
expm1 Yes Yes
log1p Yes Yes
sqrt Yes Yes
square Yes Yes
reciprocal Yes Yes
conjugate Yes Yes

2.7.5.3. Trigonometric functions

UFUNC MODE
name object mode nopython mode
sin Yes Yes
cos Yes Yes
tan Yes Yes
arcsin Yes Yes
arccos Yes Yes
arctan Yes Yes
arctan2 Yes Yes
hypot Yes Yes
sinh Yes Yes
cosh Yes Yes
tanh Yes Yes
arcsinh Yes Yes
arccosh Yes Yes
arctanh Yes Yes
deg2rad Yes Yes
rad2deg Yes Yes
degrees Yes Yes
radians Yes Yes

2.7.5.4. Bit-twiddling functions

UFUNC MODE
name object mode nopython mode
bitwise_and Yes Yes
bitwise_or Yes Yes
bitwise_xor Yes Yes
bitwise_not Yes Yes
invert Yes Yes
left_shift Yes Yes
right_shift Yes Yes

2.7.5.5. Comparison functions

UFUNC MODE
name object mode nopython mode
greater Yes Yes
greater_equal Yes Yes
less Yes Yes
less_equal Yes Yes
not_equal Yes Yes
equal Yes Yes
logical_and Yes Yes
logical_or Yes Yes
logical_xor Yes Yes
logical_not Yes Yes
maximum Yes Yes
minimum Yes Yes
fmax Yes Yes
fmin Yes Yes

2.7.5.6. Floating functions

UFUNC MODE
name object mode nopython mode
isfinite Yes Yes
isinf Yes Yes
isnan Yes Yes
signbit Yes Yes
copysign Yes Yes
nextafter Yes Yes
modf Yes No
ldexp Yes (*) Yes
frexp Yes No
floor Yes Yes
ceil Yes Yes
trunc Yes Yes
spacing Yes Yes

(*) not supported on windows 32 bit