=====
Numba
=====

As an open source Python JITc, Numba is especially efficient with NumPy and other scientific computations.

It will be useful in the cases where:

* a method is called really often
* you love NumPy arrays
* you want to perform some parallelization


Crash course
============

Numba works by using a decorator on your methods. There is mainly two of them:

* ``@jit``
* ``@njit`` which is an alias for ``@jit(nopython=True)``

Simply import the decorator and add it to your methods:

.. code-block:: python

  from numba import njit
  @njit()
  def fast_slow_method():
    # some time consuming action
    stuff()

That's it !

Now you have more time to read a few more information ;)

Why a *non-python* mode exists when we are working with Python ?
----------------------------------------------------------------

Great question and the answer is not that long. Numba is trying to provide a compiled version of the decorated method
without using Python. But sometimes, Numba won't be able to compile the code, for example if Pandas Dataframes are
involved. In this case, the compiler will compile what he can and the interpreter will be called for the remaining code.

This is called the ``object`` mode.

.. note::
   So if you want best performances, always call ``@njit``

*Okay but why is* ``@jit`` *existing if it does not provide best performances ?*

Because you may not want to receive an exception if the ``@njit`` fails to provide a compiled method. You can see it as
"try to do as no-python and if you fail, fallback to hybrid mode".


Ahead Of Time compilation (AOT compilation)
-------------------------------------------

If you read the doc (or StackOverflow answers) you may see stuff about methods signatures. This is only useful in the 
case of AOT compilation. For JITc **Numba doesn't care** of signatures (not exactly but it won't give you a performance
boost).


Tips and tricks
===============

Some basic pitfalls that you may encounter of misc tips:

* Always remember that Numba must "see the method" a first time, then the compiled version will be used
  
  * A ``%timeit`` measure with a great deviation (or a deceiving result) may indicate this ;)

* Try to maximize the use of NumPy arrays, it will spare you some time costly conversion
* You can cache a jitted method with ``@njit(cache=True)``


Finally, head to the 5 minutes `guide <https://numba.readthedocs.io/en/stable/user/5minguide.html#>`_ which is a nice
starting point.

:tag:`JITc`
:tag:`JIT`
:tag:`numba`
:tag:`Python`