2.6. 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.6.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.6.2. Array types¶
Numpy arrays of any of the scalar types above are supported, regardless of the shape or layout.
2.6.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.6.2.2. Attributes¶
The following attributes of Numpy arrays are supported:
2.6.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.sum()) are similarly supported.
2.6.2.4. Other methods¶
The following methods of Numpy arrays are supported:
- copy() (without arguments)
- reshape() (only the 1-argument form)
- sort() (without arguments)
- transpose() (without arguments, and without copying)
- view() (only the 1-argument form)
Warning
Sorting may be slightly slower than Numpy’s implementation.
2.6.3. Functions¶
2.6.3.1. Linear algebra¶
Basic linear algebra is supported on 1-D and 2-D contiguous arrays of floating-point and complex numbers.
- numpy.dot()
- numpy.vdot()
- On Python 3.5 and above, the matrix multiplication operator from PEP 465 (i.e. a @ b where a and b are 1-D or 2-D arrays).
Note
The implementation of these functions needs Scipy 0.16+ to be installed.
2.6.3.2. Other functions¶
The following top-level functions are supported:
- numpy.arange()
- numpy.empty()
- numpy.empty_like()
- numpy.eye()
- numpy.frombuffer() (only the 2 first arguments)
- numpy.full()
- numpy.full_like()
- numpy.identity()
- numpy.linspace() (only the 3-argument form)
- numpy.median() (only the first argument)
- numpy.ndenumerate
- numpy.ndindex
- numpy.ones()
- numpy.ones_like()
- numpy.round_()
- numpy.sinc()
- numpy.sort() (no optional arguments)
- numpy.where()
- numpy.zeros()
- numpy.zeros_like()
The following constructors are supported, only with a numeric input:
- 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
2.6.4. Modules¶
2.6.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, but only with scalar output: you can’t pass a size argument.
2.6.4.1.1. Initialization¶
- numpy.random.seed(): with an integer argument only
2.6.4.1.2. Simple random data¶
- numpy.random.rand(): only without argument
- numpy.random.randint()
- numpy.random.randn(): only without argument
- numpy.random.random()
- numpy.random.random_sample()
- numpy.random.ranf()
- numpy.random.sample()
2.6.4.1.3. Permutations¶
- numpy.random.shuffle(): the sequence argument must be a one-dimension Numpy array or buffer-providing object (such as a bytearray or array.array)
2.6.4.1.4. Distributions¶
- 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.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
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.6.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.6.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.6.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.6.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.6.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.6.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.6.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