Numba

https://numba.readthedocs.io/en/stable/
Admin
Numba is a just-in-time compiler for Python that translates Python code to machine code, enabling...
Tokens:574,278
Snippets:6,793
Trust Score:8.3
Update:1 month ago
Show doc for...
Tokens:
Raw
### Build and install Numba from source

Source: https://numba.readthedocs.io/en/stable/_sources/user/installing.rst.txt

Execute the setup script from the top level of the source tree to install Numba.

```bash
$ python setup.py install
```

--------------------------------

### Importing Numba and consumer library

Source: https://numba.readthedocs.io/en/stable/cuda/cuda_array_interface.html

Initial setup for the synchronization example.

```python
from numba import cuda, int32, void
import other_cai_library
```

--------------------------------

### Install documentation dependencies

Source: https://numba.readthedocs.io/en/stable/_sources/developer/contributing.rst.txt

Use conda to install the necessary packages for building the Numba documentation.

```bash
$ conda install sphinx numpydoc sphinx_rtd_theme
```

--------------------------------

### Non-square Matrix Multiplication Example

Source: https://numba.readthedocs.io/en/stable/cuda/examples.html

Demonstrates how to adjust blockspergrid for non-square matrix multiplication in CUDA. The example includes the setup of host arrays, transfer to device, kernel execution, and verification against NumPy's matrix multiplication.

```python
 1x_h = np.arange(115).reshape([5, 23])
 2y_h = np.ones([23, 7])
 3z_h = np.zeros([5, 7])
 4
 5x_d = cuda.to_device(x_h)
 6y_d = cuda.to_device(y_h)
 7z_d = cuda.to_device(z_h)
 8
 9threadsperblock = (TPB, TPB)
10grid_y_max = max(x_h.shape[0], y_h.shape[0])
11grid_x_max = max(x_h.shape[1], y_h.shape[1])
12blockspergrid_x = math.ceil(grid_x_max / threadsperblock[0])
13blockspergrid_y = math.ceil(grid_y_max / threadsperblock[1])
14blockspergrid = (blockspergrid_x, blockspergrid_y)
15
16fast_matmul[blockspergrid, threadsperblock](x_d, y_d, z_d)
17z_h = z_d.copy_to_host()
18print(z_h)
19print(x_h @ y_h)
```

```text
$ python nonsquare_matmul.py
[[ 253.  253.  253.  253.  253.  253.  253.]
[ 782.  782.  782.  782.  782.  782.  782.]
[1311. 1311. 1311. 1311. 1311. 1311. 1311.]
[1840. 1840. 1840. 1840. 1840. 1840. 1840.]
[2369. 2369. 2369. 2369. 2369. 2369. 2369.]]
[[ 253.  253.  253.  253.  253.  253.  253.]
[ 782.  782.  782.  782.  782.  782.  782.]
[1311. 1311. 1311. 1311. 1311. 1311. 1311.]
[1840. 1840. 1840. 1840. 1840. 1840. 1840.]
[2369. 2369. 2369. 2369. 2369. 2369. 2369.]]
```

--------------------------------

### Usage of install_timer

Source: https://numba.readthedocs.io/en/stable/developer/event_api.html

Demonstrates the equivalent usage pattern for installing a timing listener using a context manager.

```python
>>> with install_listener(kind, TimingListener()) as res:
>>>    ...
```

--------------------------------

### Initialize Simulation Data

Source: https://numba.readthedocs.io/en/stable/cuda/examples.html

Setup the problem size, initial temperature distribution, and device buffers for the simulation.

```python
 1# Use an odd problem size.
 2# This is so there can be an element truly in the "middle" for symmetry.
 3size = 1001
 4data = np.zeros(size)
 5
 6# Middle element is made very hot
 7data[500] = 10000
 8buf_0 = cuda.to_device(data)
 9
10# This extra array is used for synchronization purposes
11buf_1 = cuda.device_array_like(buf_0)
12
13niter = 10000
```

--------------------------------

### Import necessary libraries for CUDA vector addition

Source: https://numba.readthedocs.io/en/stable/_sources/cuda/examples.rst.txt

Imports required for the vector addition example. Ensure Numba and CUDA are installed.

```python
from numba import cuda
import numpy as np
import math
```

--------------------------------

### Using parallel_diagnostics with level 4

Source: https://numba.readthedocs.io/en/stable/_sources/user/parallel.rst.txt

This example demonstrates how to use the `parallel_diagnostics` method with a verbosity level of 4 to get detailed information about Numba's parallelization transforms for a given function.

```python
@njit(parallel=True)
def test(x):
    n = x.shape[0]
    a = np.sin(x)
    b = np.cos(a * a)
    acc = 0
    for i in prange(n - 2):
        for j in prange(n - 1):
            acc += b[i] + b[j + 1]
    return acc

test(np.arange(10))

test.parallel_diagnostics(level=4)
```

--------------------------------

### Usage of install_recorder

Source: https://numba.readthedocs.io/en/stable/developer/event_api.html

Demonstrates the equivalent usage pattern for installing a recording listener using a context manager.

```python
>>> with install_listener(kind, RecordingListener()) as res:
>>>    ...
```

--------------------------------

### 2D Kernel Instantiation Example

Source: https://numba.readthedocs.io/en/stable/_sources/cuda/kernels.rst.txt

Illustrates how to manually calculate the grid and block dimensions for launching a 2D kernel. Uses `math.ceil` to ensure all array elements are covered.

```python
threadsperblock = (16, 16)
blockspergrid_x = math.ceil(an_array.shape[0] / threadsperblock[0])
blockspergrid_y = math.ceil(an_array.shape[1] / threadsperblock[1])
blockspergrid = (blockspergrid_x, blockspergrid_y)
increment_a_2D_array[blockspergrid, threadsperblock](an_array)
```

--------------------------------

### Standalone AOT Compilation Example

Source: https://numba.readthedocs.io/en/stable/_sources/user/pycc.rst.txt

This snippet demonstrates how to use Numba's `CC` class for Ahead-of-Time compilation. It defines functions with explicit signatures and compiles them into a standalone extension module named 'my_module'. Ensure `setuptools` is installed for compilation.

```python
from numba.pycc import CC

cc = CC('my_module')
# Uncomment the following line to print out the compilation steps
#cc.verbose = True

@cc.export('multf', 'f8(f8, f8)')
@cc.export('multi', 'i4(i4, i4)')
def mult(a, b):
    return a * b

@cc.export('square', 'f8(f8)')
def square(a):
    return a ** 2

if __name__ == "__main__":
    cc.compile()
```

--------------------------------

### Full workflow for device array usage

Source: https://numba.readthedocs.io/en/stable/cuda/memory.html

Demonstrates the complete cycle of creating a device array, running a kernel, and copying the result back to the host.

```python
import numpy as np
from numba import cuda

arr = np.arange(1000)
d_arr = cuda.to_device(arr)

my_kernel[100, 100](d_arr)

result_array = d_arr.copy_to_host()
```

--------------------------------

### Set and Get Parallel Chunk Size

Source: https://numba.readthedocs.io/en/stable/_sources/user/parallel.rst.txt

Demonstrates setting a specific chunk size (4) outside a parallel region, which is reset to 0 inside the `prange` loop. If the `prange` is not executed in parallel, the chunk size inside would remain 4. This example uses `set_parallel_chunksize` and `get_parallel_chunksize`.

```python
from numba import prange, set_parallel_chunksize, get_parallel_chunksize


def func1():
    set_parallel_chunksize(4)
    print(f"Outside prange: {get_parallel_chunksize()}")
    for i in prange(10):
        # The chunk size is reset to 0 upon entering a parallel region
        # and restored upon exiting.
        if i == 0:
            print(f"Inside prange: {get_parallel_chunksize()}")
    print(f"After prange: {get_parallel_chunksize()}")

def func2():
    set_parallel_chunksize(8)
    print(f"Outside prange: {get_parallel_chunksize()}")
    for i in prange(10):
        if i == 0:
            print(f"Inside prange: {get_parallel_chunksize()}")
    print(f"After prange: {get_parallel_chunksize()}")


func1()
func2()
```

--------------------------------

### Install numba-cuda with conda

Source: https://numba.readthedocs.io/en/stable/_sources/cuda/overview.rst.txt

Install the numba-cuda package from the conda-forge channel using conda. This is an alternative installation method for users who prefer conda.

```bash
conda install conda-forge::numba-cuda
```

--------------------------------

### Launch kernel using forall

Source: https://numba.readthedocs.io/en/stable/cuda/examples.html

The forall method automatically configures the grid for a 1D launch based on the data size.

```python
f.forall(len(a))(a, b, c)
print(c.copy_to_host())
```

--------------------------------

### Build and preview documentation

Source: https://numba.readthedocs.io/en/stable/_sources/developer/contributing.rst.txt

Commands to build the HTML documentation from source files and open the result in a browser.

```bash
$ make html
$ open _build/html/index.html
```

--------------------------------

### Install Numba via pip

Source: https://numba.readthedocs.io/en/stable/user/installing.html

Use pip to install Numba and its dependencies. This method includes bundled llvmlite components, so a separate LLVM installation is not required.

```bash
$ pip install numba
```

--------------------------------

### List available CPU options with llc

Source: https://numba.readthedocs.io/en/stable/reference/envvars.html

Use the LLVM llc command-line tool to inspect available CPU models and features for configuration.

```bash
llc -march=x86 -mattr=help
```

--------------------------------

### Install Numba with pip

Source: https://numba.readthedocs.io/en/stable/_sources/user/installing.rst.txt

Install Numba and its dependencies using pip from PyPI.

```bash
$ pip install numba
```

--------------------------------

### Install Numba using Pip

Source: https://numba.readthedocs.io/en/stable/_sources/user/5minguide.rst.txt

Use this command to install Numba if you are using pip.

```bash
pip install numba
```

--------------------------------

### Example using numba.jit()

Source: https://numba.readthedocs.io/en/stable/developer/inlining.html

Demonstrates basic inlining behavior using the numba.jit decorator.

```python
from numba import jit

@jit(inline='always')
def foo(x):
    return x + 1

@jit
def bar(x):
    return foo(x) * 2
```

--------------------------------

### Install numba-cuda with Conda

Source: https://numba.readthedocs.io/en/stable/_sources/reference/deprecation.rst.txt

Install the `numba-cuda` package from the `conda-forge` channel using conda.

```bash
conda install conda-forge::numba-cuda
```

--------------------------------

### Register Numba Extension in setup.py

Source: https://numba.readthedocs.io/en/stable/_sources/extending/entrypoints.rst.txt

Add the 'entry_points' argument to your setup() function in setup.py to register an initialization function for Numba extensions. Numba specifically looks for the 'init' entry point within the 'numba_extensions' group.

```python
setup(
    ...,
    entry_points={
        "numba_extensions": [
            "init = numba_scipy:_init_extension",
        ],
    },
    ...
)
```

--------------------------------

### GDB Session Example

Source: https://numba.readthedocs.io/en/stable/_sources/user/troubleshoot.rst.txt

This example demonstrates a typical gdb session after hitting a breakpoint set by numba.gdb(). It shows stepping through code, listing source lines, inspecting variables, setting new breakpoints, and continuing execution.

```none
$ NUMBA_OPT=0 NUMBA_EXTEND_VARIABLE_LIFETIMES=1 python demo_gdb.py
...
Breakpoint 1, 0x00007fb75238d830 in numba_gdb_breakpoint () from numba/_helperlib.cpython-39-x86_64-linux-gnu.so
(gdb) s
Single stepping until exit from function numba_gdb_breakpoint,
which has no line number information.
0x00007fb75233e1cf in numba::misc::gdb_hook::hook_gdb::_3clocals_3e::impl_242[abi:c8tJTIeFCjyCbUFRqqOAK_2f6h0phxApMogijRBAA_3d](StarArgTuple) ()
(gdb) s
Single stepping until exit from function _ZN5numba4misc8gdb_hook8hook_gdb12_3clocals_3e8impl_242B44c8tJTIeFCjyCbUFRqqOAK_2f6h0phxApMogijRBAA_3dE12StarArgTuple,
which has no line number information.
__main__::foo_241[abi:c8tJTC_2fWgEeGLSgydRTQUgiqKEZ6gEoDvQJmaQIA](long long) (a=123) at demo_gdb.py:7
7           c = a * 2.34
(gdb) l
2
3       @njit(debug=True)
4       def foo(a):
5           b = a + 1
6           gdb() # instruct Numba to attach gdb at this location and pause execution
7           c = a * 2.34
8           d = (a, b, c)
9           print(a, b, c, d)
10
11      r= foo(123)
(gdb) p a
$1 = 123
(gdb) p b
$2 = 124
(gdb) p c
$3 = 0
(gdb) b 9
Breakpoint 2 at 0x7fb73d1f7287: file demo_gdb.py, line 9.
(gdb) c
Continuing.

Breakpoint 2, __main__::foo_241[abi:c8tJTC_2fWgEeGLSgydRTQUgiqKEZ6gEoDvQJmaQIA](long long) (a=123) at demo_gdb.py:9
9           print(a, b, c, d)
(gdb) info locals
b = 124
c = 287.81999999999999
d = {f0 = 123, f1 = 124, f2 = 287.81999999999999}
```

--------------------------------

### Build Numba from source

Source: https://numba.readthedocs.io/en/stable/_sources/developer/contributing.rst.txt

Clone the repository and build the Numba C extensions in-place for development.

```bash
$ git clone git@github.com:numba/numba.git
$ cd numba
$ python setup.py build_ext --inplace
```

--------------------------------

### Verify llvmlite installation

Source: https://numba.readthedocs.io/en/stable/_sources/developer/contributing.rst.txt

Check the installed version of llvmlite within the active Python environment.

```python
$ python
Python 3.10.3 (main, Mar 28 2022, 04:26:28) [Clang 12.0.0 ] on darwin
Type "help", "copyright", "credits" or "license" for more information.

>>> import llvmlite
>>> llvmlite.__version__
0.39.0dev0+61.gf27ac6f
```

--------------------------------

### Literal type inference example

Source: https://numba.readthedocs.io/en/stable/developer/literal.html

Example showing how Numba infers a literal type for a variable.

```python
def foo(x):
    a = 123
    return bar(x, a)
```

--------------------------------

### Complete FFI integration example

Source: https://numba.readthedocs.io/en/stable/cuda/cuda_ffi.html

Full Python implementation showing the declaration of a foreign device function and its usage within a Numba CUDA kernel.

```python
 1from numba import cuda
 2import numpy as np
 3import os
 4
 5# Declaration of the foreign function
 6mul = cuda.declare_device('mul_f32_f32', 'float32(float32, float32)')
 7
 8# Path to the source containing the foreign function
 9# (here assumed to be in a subdirectory called "ffi")
10basedir = os.path.dirname(os.path.abspath(__file__))
11functions_cu = os.path.join(basedir, 'ffi', 'functions.cu')
12
13# Kernel that links in functions.cu and calls mul
14@cuda.jit(link=[functions_cu])
def multiply_vectors(r, x, y):
    i = cuda.grid(1)

    if i < len(r):
        r[i] = mul(x[i], y[i])

# Generate random data
22N = 32
23np.random.seed(1)
24x = np.random.rand(N).astype(np.float32)
25y = np.random.rand(N).astype(np.float32)
26r = np.zeros_like(x)
27
28# Run the kernel
29multiply_vectors[1, 32](r, x, y)
30
31# Sanity check - ensure the results match those expected
32np.testing.assert_array_equal(r, x * y)
```

--------------------------------

### Install TBB via Pip

Source: https://numba.readthedocs.io/en/stable/user/threading-layer.html

Command to install the TBB library using pip for Numba environments.

```bash
$ pip install tbb
```

--------------------------------

### CuPy Plugin Allocation and Free Example

Source: https://numba.readthedocs.io/en/stable/proposals/external-memory-management.html

Demonstrates a simple allocation and free operation using the prototype CuPy plugin.

```python
from nbep7.cupy_mempool import use_cupy_mm_for_numba
import numpy as np

from numba import cuda

use_cupy_mm_for_numba()

a = np.zeros(10)
d_a = cuda.to_device(a)
del(d_a)
```

```text
Allocated 80 bytes at 7f004d400000
Freeing 80 bytes at 7f004d400000
```

--------------------------------

### Install numba-cuda with conda

Source: https://numba.readthedocs.io/en/stable/cuda/overview.html

Use this command to install the numba-cuda package from the conda-forge channel using conda.

```bash
conda install conda-forge::numba-cuda
```

--------------------------------

### Manual Grid Configuration for 2D Kernel

Source: https://numba.readthedocs.io/en/stable/cuda/kernels.html

Shows how to manually calculate the grid and block dimensions required to launch the 2D increment kernel.

```python
threadsperblock = (16, 16)
blockspergrid_x = math.ceil(an_array.shape[0] / threadsperblock[0])
blockspergrid_y = math.ceil(an_array.shape[1] / threadsperblock[1])
blockspergrid = (blockspergrid_x, blockspergrid_y)
increment_a_2D_array[blockspergrid, threadsperblock](an_array)
```

--------------------------------

### Install numba-cuda with pip

Source: https://numba.readthedocs.io/en/stable/cuda/overview.html

Use this command to install the numba-cuda package using the pip package manager.

```bash
pip install numba-cuda
```

--------------------------------

### Install Intel TBB with Conda

Source: https://numba.readthedocs.io/en/stable/_sources/user/threading-layer.rst.txt

Install Intel TBB libraries using the conda package manager.

```bash
$ conda install tbb
```

--------------------------------

### JIT Decorator Usage

Source: https://numba.readthedocs.io/en/stable/_sources/reference/jit-compilation.rst.txt

Demonstrates the usage of the @jit decorator with signatures and without.

```APIDOC
## @jit decorator usage examples

### Description
Examples showing how to use the `@jit` decorator with explicit type signatures and with default behavior.

### Code Examples

#### With signatures:
```python
@jit(["int32(int32)", "float32(float32)"], nopython=True)
def f(x):
    ... 
```

#### Without signatures (equivalent to @jit()):
```python
@jit
def f(x):
    ... 
```

#### Equivalent to:
```python
@jit()
def f(x):
    ... 
```
```

--------------------------------

### Install Numba using Conda

Source: https://numba.readthedocs.io/en/stable/_sources/user/5minguide.rst.txt

Use this command to install Numba if you are using the Anaconda Python distribution.

```bash
conda install numba
```
Tokens:
Raw