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:
The following sections focus on the Numpy features supported in nopython mode, unless otherwise stated.
Numba supports the following Numpy scalar types:
The following scalar types and features are not supported:
The operations supported on NumPy scalars are almost 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. In addition you can use
the view(np.<dtype>) method to bitcast all int and float types
within the same width. However, you must define the scalar using a NumPy
constructor within a jitted function. For example, the following will work:
>>> import numpy as np
>>> from numba import njit
>>> @njit
... def bitcast():
... i = np.int64(-1)
... print(i.view(np.uint64))
...
>>> bitcast()
18446744073709551615
Whereas the following will not work:
>>> import numpy as np
>>> from numba import njit
>>> @njit
... def bitcast(i):
... print(i.view(np.uint64))
...
>>> bitcast(np.int64(-1))
---------------------------------------------------------------------------
TypingError Traceback (most recent call last)
...
TypingError: Failed in nopython mode pipeline (step: ensure IR is legal prior to lowering)
'view' can only be called on NumPy dtypes, try wrapping the variable with 'np.<dtype>()'
File "<ipython-input-3-fc40aaab84c4>", line 3:
def bitcast(i):
print(i.view(np.uint64))
Structured scalars support attribute getting and setting, as well as member lookup using constant strings.
See also
Numpy scalars reference.
Numpy arrays of any of the scalar types above are supported, regardless of the shape or layout.
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.
The following attributes of Numpy arrays are supported:
flags object¶The object returned by the flags attribute supports
the contiguous, c_contiguous and f_contiguous attributes.
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.
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.
The following methods of Numpy arrays are supported in their basic form (without any optional arguments):
all()any()argmax()argmin()conj()conjugate()cumprod()cumsum()max()mean()min()nonzero()prod()std()take()var()The corresponding top-level Numpy functions (such as numpy.prod())
are similarly supported.
The following methods of Numpy arrays are supported:
argsort() (kind key word argument supported for
values 'quicksort' and 'mergesort')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)repeat() (no axis argument)reshape() (only the 1-argument form)sort() (without arguments)sum() (with or without the axis and/or dtype
arguments.)axis only supports integer values.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.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.dtypes are supported in the dtype parameter.
timedelta arrays can be used as input arrays but timedelta is not
supported as dtype parameter.dtype is given, it determines the type of the internal
accumulator. When it is not, the selection is made automatically based on
the input array’s dtype, mostly following the same rules as NumPy.
However, on 64-bit Windows, Numba uses a 64-bit accumulator for integer
inputs (int64 for int32 inputs and uint64 for uint32
inputs), while NumPy would use a 32-bit accumulator in those cases.transpose()view() (only the 1-argument form)Warning
Sorting may be slightly slower than Numpy’s implementation.
Basic linear algebra is supported on 1-D and 2-D contiguous arrays of floating-point and complex numbers:
numpy.dot()numpy.kron() (‘C’ and ‘F’ order only)numpy.outer()numpy.trace() (only the first argument).numpy.vdot()a @ b where a and b are 1-D or 2-D arrays).numpy.linalg.cholesky()numpy.linalg.cond() (only non string values in p).numpy.linalg.det()numpy.linalg.eig() (only running with data that does not cause a domain
change is supported e.g. real input -> real
output, complex input -> complex output).numpy.linalg.eigh() (only the first argument).numpy.linalg.eigvals() (only running with data that does not cause a
domain change is supported e.g. real input -> real output,
complex input -> complex output).numpy.linalg.eigvalsh() (only the first argument).numpy.linalg.inv()numpy.linalg.lstsq()numpy.linalg.matrix_power()numpy.linalg.matrix_rank()numpy.linalg.norm() (only the 2 first arguments and only non string
values in ord).numpy.linalg.pinv()numpy.linalg.qr() (only the first argument).numpy.linalg.slogdet()numpy.linalg.solve()numpy.linalg.svd() (only the 2 first arguments).Note
The implementation of these functions needs Scipy 0.16+ to be installed.
The following reduction functions are supported:
numpy.diff() (only the 2 first arguments)numpy.median() (only the first argument)numpy.nancumprod() (only the first argument, requires NumPy >= 1.12))numpy.nancumsum() (only the first argument, requires NumPy >= 1.12))numpy.nanmax() (only the first argument)numpy.nanmean() (only the first argument)numpy.nanmedian() (only the first argument)numpy.nanmin() (only the first argument)numpy.nanpercentile() (only the 2 first arguments,
requires NumPy >= 1.11, complex dtypes unsupported)numpy.nanquantile() (only the 2 first arguments, requires NumPy >= 1.15,
complex dtypes unsupported)numpy.nanprod() (only the first argument)numpy.nanstd() (only the first argument)numpy.nansum() (only the first argument)numpy.nanvar() (only the first argument)numpy.percentile() (only the 2 first arguments, requires NumPy >= 1.10,
complex dtypes unsupported)numpy.quantile() (only the 2 first arguments, requires NumPy >= 1.15,
complex dtypes unsupported)The following top-level functions are supported:
numpy.append()numpy.arange()numpy.argsort() (kind key word argument supported for values
'quicksort' and 'mergesort')numpy.array() (only the 2 first arguments)numpy.array_equal()numpy.asarray() (only the 2 first arguments)numpy.asfortranarray() (only the first argument)numpy.atleast_1d()numpy.atleast_2d()numpy.atleast_3d()numpy.bartlett()numpy.bincount() (only the 2 first arguments)numpy.blackman()numpy.column_stack()numpy.concatenate()numpy.convolve() (only the 2 first arguments)numpy.copy() (only the first argument)numpy.corrcoef() (only the 3 first arguments, requires NumPy >= 1.10 and
SciPy >= 0.16; extreme value handling per NumPy 1.11+)numpy.correlate() (only the 2 first arguments)numpy.count_nonzero() (axis only supports scalar values)numpy.cov() (only the 5 first arguments, requires NumPy >= 1.10 and SciPy >= 0.16)numpy.cross() (only the 2 first arguments; at least one of the input
arrays should have shape[-1] == 3)shape[-1] == 2 for both inputs, please replace your
numpy.cross() call with numba.numpy_extensions.cross2d().numpy.delete() (only the 2 first arguments)numpy.diag()numpy.digitize()numpy.dstack()numpy.dtype() (only the first argument)numpy.ediff1d()numpy.empty() (only the 2 first arguments)numpy.empty_like() (only the 2 first arguments)numpy.expand_dims()numpy.extract()numpy.eye()numpy.fill_diagonal()numpy.flatten() (no order argument; ‘C’ order only)numpy.flatnonzero()numpy.frombuffer() (only the 2 first arguments)numpy.full() (only the 3 first arguments)numpy.full_like() (only the 3 first arguments)numpy.hamming()numpy.hanning()numpy.histogram() (only the 3 first arguments)numpy.hstack()numpy.identity()numpy.kaiser()numpy.interp() (only the 3 first arguments; requires NumPy >= 1.10)numpy.linspace() (only the 3-argument form)numpy.ndenumeratenumpy.ndindexnumpy.nditer (only the first argument)numpy.ones() (only the 2 first arguments)numpy.ones_like() (only the 2 first arguments)numpy.partition() (only the 2 first arguments)numpy.ptp() (only the first argument)numpy.ravel() (no order argument; ‘C’ order only)numpy.repeat() (no axis argument)numpy.reshape() (no order argument; ‘C’ order only)numpy.roll() (only the 2 first arguments; second argument shift
must be an integer)numpy.roots()numpy.round_()numpy.searchsorted() (only the 3 first arguments)numpy.select() (only using homogeneous lists or tuples for the first
two arguments, condlist and choicelist). Additionally, these two arguments
can only contain arrays (unlike Numpy that also accepts tuples).numpy.shape()numpy.sinc()numpy.sort() (no optional arguments)numpy.stack()numpy.take() (only the 2 first arguments)numpy.transpose()numpy.trapz() (only the 3 first arguments)numpy.tri() (only the 3 first arguments; third argument k must be an integer)numpy.tril() (second argument k must be an integer)numpy.tril_indices() (all arguments must be integer)numpy.tril_indices_from() (second argument k must be an integer)numpy.triu() (second argument k must be an integer)numpy.triu_indices() (all arguments must be integer)numpy.triu_indices_from() (second argument k must be an integer)numpy.unique() (only the first argument)numpy.vander()numpy.vstack()numpy.where()numpy.zeros() (only the 2 first arguments)numpy.zeros_like() (only the 2 first arguments)The following constructors are supported, both with a numeric input (to construct a scalar) or a sequence (to construct an array):
numpy.bool_numpy.complex64numpy.complex128numpy.float32numpy.float64numpy.int8numpy.int16numpy.int32numpy.int64numpy.intcnumpy.intpnumpy.uint8numpy.uint16numpy.uint32numpy.uint64numpy.uintcnumpy.uintpThe following machine parameter classes are supported, with all purely numerical attributes:
numpy.iinfonumpy.finfo (machar attribute not supported)numpy.MachAr (with no arguments to the constructor)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)
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.
numpy.random.seed(): with an integer argument onlynumpy.random.choice(): the optional p argument (probabilities
array) is not supportednumpy.random.permutation()numpy.random.shuffle(): the sequence argument must be a one-dimension
Numpy array or buffer-providing object (such as a bytearray
or array.array)Warning
The size argument is not supported in the following functions.
numpy.random.beta()numpy.random.binomial()numpy.random.chisquare()numpy.random.exponential()numpy.random.f()numpy.random.gamma()numpy.random.geometric()numpy.random.gumbel()numpy.random.hypergeometric()numpy.random.laplace()numpy.random.logistic()numpy.random.lognormal()numpy.random.logseries()numpy.random.multinomial()numpy.random.negative_binomial()numpy.random.normal()numpy.random.pareto()numpy.random.poisson()numpy.random.power()numpy.random.rayleigh()numpy.random.standard_cauchy()numpy.random.standard_exponential()numpy.random.standard_gamma()numpy.random.standard_normal()numpy.random.standard_t()numpy.random.triangular()numpy.random.uniform()numpy.random.vonmises()numpy.random.wald()numpy.random.weibull()numpy.random.zipf()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
Since version 0.28.0, the generator is thread-safe and fork-safe. Each thread and each process will produce independent streams of random numbers.
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)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.
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.
| 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 |
| gcd | Yes | Yes |
| lcm | Yes | Yes |
| 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 |
| 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 |
| 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 |
| 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