@numba.jit(signature=None, nopython=False, nogil=False, cache=False, forceobj=False, parallel=False, error_model='python', locals={})¶Compile the decorated function on-the-fly to produce efficient machine code. All parameters all optional.
If present, the signature is either a single signature or a list of signatures representing the expected Types and signatures of function arguments and return values. Each signature can be given in several forms:
(numba.int32, numba.double)) representing the types of the
function’s arguments; Numba will then infer an appropriate return
type from the arguments.numba.void(numba.int32, numba.double))."void(int32, double)". All type names used in the string are assumed
to be defined in the numba.types module.nopython and nogil are boolean flags. locals is a mapping of local variable names to Types and signatures.
This decorator has several modes of operation:
TypeError if
no appropriate conversion is available for the function arguments. If
converting succeeds, the compiled machine code is executed with the
converted arguments and the return value is converted back according to
the signature.(numba.int64, numba.int64)). If no suitable specialization
exists, a new specialization is compiled on-the-fly, stored for later
use, and executed with the converted arguments.If true, nopython forces the function to be compiled in nopython mode. If not possible, compilation will raise an error.
If true, forceobj forces the function to be compiled in object mode. Since object mode is slower than nopython mode, this is mostly useful for testing purposes.
If true, nogil tries to release the global interpreter lock inside the compiled function. The GIL will only be released if Numba can compile the function in nopython mode, otherwise a compilation warning will be printed.
If true, cache enables a file-based cache to shorten compilation times
when the function was already compiled in a previous invocation.
The cache is maintained in the __pycache__ subdirectory of
the directory containing the source file; if the current user is not
allowed to write to it, though, it falls back to a platform-specific
user-wide cache directory (such as $HOME/.cache/numba on Unix
platforms).
If true, parallel enables the automatic parallelization of a number of common Numpy constructs as well as the fusion of adjacent parallel operations to maximize cache locality.
The error_model option controls the divide-by-zero behavior. Setting it to ‘python’ causes divide-by-zero to raise exception like CPython. Setting it to ‘numpy’ causes divide-by-zero to set the result to +/-inf or nan.
Not all functions can be cached, since some functionality cannot be
always persisted to disk. When a function cannot be cached, a
warning is emitted; use NUMBA_WARNINGS to see it.
The locals dictionary may be used to force the Types and signatures of particular local variables, for example if you want to force the use of single precision floats at some point. In general, we recommend you let Numba’s compiler infer the types of local variables by itself.
Here is an example with two signatures:
@jit(["int32(int32)", "float32(float32)"], nopython=True)
def f(x): ...
Not putting any parentheses after the decorator is equivalent to calling the decorator without any arguments, i.e.:
@jit
def f(x): ...
is equivalent to:
@jit()
def f(x): ...
The decorator returns a Dispatcher object.
Note
If no signature is given, compilation errors will be raised when the actual compilation occurs, i.e. when the function is first called with some given argument types.
Note
Compilation can be influenced by some dedicated Environment variables.
@numba.generated_jit(nopython=False, nogil=False, cache=False, forceobj=False, locals={})¶Like the jit() decorator, but calls the decorated function at
compile-time, passing the types of the function’s arguments.
The decorated function must return a callable which will be compiled as
the function’s implementation for those types, allowing flexible kinds of
specialization.
The generated_jit() decorator returns a Dispatcher object.
Dispatcher¶The class of objects created by calling jit() or
generated_jit(). You shouldn’t try to create such an object
in any other way. Calling a Dispatcher object calls the compiled
specialization for the arguments with which it is called, letting it
act as an accelerated replacement for the Python function which was compiled.
In addition, Dispatcher objects have the following methods and attributes:
py_func¶The pure Python function which was compiled.
inspect_types(file=None, pretty=False)¶Print out a listing of the function source code annotated line-by-line with the corresponding Numba IR, and the inferred types of the various variables. If file is specified, printing is done to that file object, otherwise to sys.stdout. If pretty is set to True then colored ANSI will be produced in a terminal and HTML in a notebook.
See also
inspect_llvm(signature=None)¶Return a dictionary keying compiled function signatures to the human readable LLVM IR generated for the function. If the signature keyword is specified a string corresponding to that individual signature is returned.
inspect_asm(signature=None)¶Return a dictionary keying compiled function signatures to the human-readable native assembler code for the function. If the signature keyword is specified a string corresponding to that individual signature is returned.
inspect_cfg(signature=None, show_wrapped)¶Return a dictionary keying compiled function signatures to the control-flow graph objects for the function. If the signature keyword is specified a string corresponding to that individual signature is returned.
The control-flow graph objects can be stringified (str or repr)
to get the textual representation of the graph in DOT format. Or, use
its .display(filename=None, view=False) method to plot the graph.
The filename option can be set to a specific path for the rendered
output to write to. If view option is True, the plot is opened by
the system default application for the image format (PDF). In IPython
notebook, the returned object can be plot inlined.
Usage:
@jit
def foo():
...
# opens the CFG in system default application
foo.inspect_cfg(foo.signatures[0]).display(view=True)
recompile()¶Recompile all existing signatures. This can be useful for example if a global or closure variable was frozen by your function and its value in Python has changed. Since compiling isn’t cheap, this is mainly for testing and interactive use.
@numba.vectorize(*, signatures=[], identity=None, nopython=True, target='cpu', forceobj=False, cache=False, locals={})¶Compile the decorated function and wrap it either as a Numpy
ufunc or a Numba DUFunc. The optional
nopython, forceobj and locals arguments have the same meaning
as in numba.jit().
signatures is an optional list of signatures expressed in the
same form as in the numba.jit() signature argument. If
signatures is non-empty, then the decorator will compile the user
Python function into a Numpy ufunc. If no signatures are given,
then the decorator will wrap the user Python function in a
DUFunc instance, which will compile the user
function at call time whenever Numpy can not find a matching loop
for the input arguments. signatures is required if target is
"parallel".
identity is the identity (or unit) value of the function being
implemented. Possible values are 0, 1, None, and the string
"reorderable". The default is None. Both None and
"reorderable" mean the function has no identity value;
"reorderable" additionally specifies that reductions along multiple
axes can be reordered.
If there are several signatures, they must be ordered from the more specific to the least specific. Otherwise, Numpy’s type-based dispatching may not work as expected. For example, the following is wrong:
@vectorize(["float64(float64)", "float32(float32)"])
def f(x): ...
as running it over a single-precision array will choose the float64
version of the compiled function, leading to much less efficient
execution. The correct invocation is:
@vectorize(["float32(float32)", "float64(float64)"])
def f(x): ...
target is a string for backend target; Available values are “cpu”, “parallel”, and “cuda”. To use a multithreaded version, change the target to “parallel” (which requires signatures to be specified):
@vectorize(["float64(float64)", "float32(float32)"], target='parallel')
def f(x): ...
For the CUDA target, use “cuda”:
@vectorize(["float64(float64)", "float32(float32)"], target='cuda')
def f(x): ...
The compiled function can be cached to reduce future compilation time. It is enabled by setting cache to True. Only the “cpu” and “parallel” targets support caching.
@numba.guvectorize(signatures, layout, *, identity=None, nopython=True, target='cpu', forceobj=False, cache=False, locals={})¶Generalized version of numba.vectorize(). While
numba.vectorize() will produce a simple ufunc whose core
functionality (the function you are decorating) operates on scalar
operands and returns a scalar value, numba.guvectorize()
allows you to create a Numpy ufunc whose core function takes array
arguments of various dimensions.
The additional argument layout is a string specifying, in symbolic
form, the dimensionality and size relationship of the argument types
and return types. For example, a matrix multiplication will have
a layout string of "(m,n),(n,p)->(m,p)". Its definition might
be (function body omitted):
@guvectorize(["void(float64[:,:], float64[:,:], float64[:,:])"],
"(m,n),(n,p)->(m,p)")
def f(a, b, result):
"""Fill-in *result* matrix such as result := a * b"""
...
If one of the arguments should be a scalar, the corresponding layout
specification is () and the argument will really be given to
you as a zero-dimension array (you have to dereference it to get the
scalar value). For example, a one-dimension moving average
with a parameterable window width may have a layout string of "(n),()->(n)".
Note that any output will be given to you preallocated as an additional function argument: your code has to fill it with the appropriate values for the function you are implementing.
If your function doesn’t take an output array, you should omit the “arrow”
in the layout string (e.g. "(n),(n)").
See also
Specification of the layout string as supported by Numpy. Note that Numpy uses the term “signature”, which we unfortunately use for something else.
The compiled function can be cached to reduce future compilation time. It is enabled by setting cache to True. Only the “cpu” and “parallel” targets support caching.
numba.DUFunc¶The class of objects created by calling numba.vectorize()
with no signatures.
DUFunc instances should behave similarly to Numpy
ufunc objects with one important difference:
call-time loop generation. When calling a ufunc, Numpy looks at
the existing loops registered for that ufunc, and will raise a
TypeError if it cannot find a loop that it cannot
safely cast the inputs to suit. When calling a DUFunc, Numba
delegates the call to Numpy. If the Numpy ufunc call fails, then
Numba attempts to build a new loop for the given input types, and
calls the ufunc again. If this second call attempt fails or a
compilation error occurs, then DUFunc passes along the exception to
the caller.
See also
The “Dynamic universal functions” section in the user’s
guide demonstrates the call-time behavior of
DUFunc, and discusses the impact of call order
on how Numba generates the underlying ufunc.
ufunc¶The actual Numpy ufunc object being built by the
DUFunc instance. Note that the
DUFunc object maintains several important data
structures required for proper ufunc functionality (specifically
the dynamically compiled loops). Users should not pass the
ufunc value around without ensuring the
underlying DUFunc will not be garbage collected.
nout¶The number of DUFunc outputs. See ufunc.nout.
nargs¶The total number of possible DUFunc arguments (should be
nin + nout).
See ufunc.nargs.
ntypes¶The number of input types supported by the DUFunc. See ufunc.ntypes.
types¶A list of the supported types given as strings. See ufunc.types.
identity¶The identity value when using the ufunc as a reduction. See ufunc.identity.
reduce(A, *, axis, dtype, out, keepdims)¶Reduces A’s dimension by one by applying the DUFunc along one axis. See ufunc.reduce.
accumulate(A, *, axis, dtype, out)¶Accumulate the result of applying the operator to all elements. See ufunc.accumulate.
reduceat(A, indices, *, axis, dtype, out)¶Performs a (local) reduce with specified slices over a single axis. See ufunc.reduceat.
outer(A, B)¶Apply the ufunc to all pairs (a, b) with a in A, and b in B. See ufunc.outer.
Note
Vectorized functions can, in rare circumstances, show unexpected warnings or errors.
@numba.cfunc(signature, nopython=False, cache=False, locals={})¶Compile the decorated function on-the-fly to produce efficient machine code. The compiled code is wrapped in a thin C callback that makes it callable using the natural C ABI.
The signature is a single signature representing the signature of the
C callback. It must have the same form as in jit().
The decorator does not check that the types in the signature have
a well-defined representation in C.
nopython and cache are boolean flags. locals is a mapping of
local variable names to Types and signatures. They all have the same
meaning as in jit().
The decorator returns a CFunc object.
Note
C callbacks currently do not support object mode.
CFunc¶The class of objects created by cfunc(). CFunc
objects expose the following attributes and methods:
address¶The address of the compiled C callback, as an integer.
cffi¶A cffi function pointer instance, to be passed as an argument to
cffi-wrapped functions. The pointer’s type is void *, so
only minimal type checking will happen when passing it to cffi.
ctypes¶A ctypes callback instance, as if it were created using
ctypes.CFUNCTYPE().
native_name¶The name of the compiled C callback.
inspect_llvm()¶Return the human-readable LLVM IR generated for the C callback.
native_name is the name under which this callback is defined
in the IR.