diff --git a/docs/backups/docker.rst b/docs/backups/docker.rst index 5b24f78f55..62ccc207f2 100644 --- a/docs/backups/docker.rst +++ b/docs/backups/docker.rst @@ -1,4 +1,3 @@ -.. _docker: .. include:: ./../ext_links.txt Docker Support diff --git a/docs/source/user_guide/caching.rst b/docs/source/user_guide/caching.rst index 62c8b8379a..e7b89cb669 100644 --- a/docs/source/user_guide/caching.rst +++ b/docs/source/user_guide/caching.rst @@ -1,9 +1,7 @@ -.. _caching: .. include:: ./../ext_links.txt - -Caching Mechanism in Numba-dpex -================================ +Caching Mechanism in ``numba-dpex`` +=================================== Caching is done by saving the compiled kernel code, the ELF object of the executable code. By using the kernel code, cached kernels have minimal overhead @@ -25,7 +23,7 @@ new kernel arrives to be cached and if the size is already on the maximum limit, the algorithm evicts the LRU kernel to make room for the MRU kernel. The evicted item will be serialized and pickled into a file using Numba's caching mechanism. -Everytime whenever a kernel needs to be retrieved from the cache, the mechanism +Every time whenever a kernel needs to be retrieved from the cache, the mechanism will look for the kernel in the cache and will be loaded if it's already present. However, if the program is seeking for a kernel that has been evicted, the algorithm will load it from the file and enqueue in the cache. @@ -38,11 +36,11 @@ i.e. ``NUMBA_CACHE_DIR`` etc. However we add three more environment variables to control the caching mechanism. - In order to specify cache capacity, one can use ``NUMBA_DPEX_CACHE_SIZE``. -By default, it's set to 10. + By default, it's set to 10. -- ``NUMBA_DPEX_ENABLE_CACHE`` can be used to enable/disable the caching mechanism. -By default it's enabled, i.e. set to 1. +- ``NUMBA_DPEX_ENABLE_CACHE`` can be used to enable/disable the caching + mechanism. By default it's enabled, i.e. set to 1. - In order to enable the debugging messages related to caching, one can set -``NUMBA_DPEX_DEBUG_CACHE`` to 1. All environment variables are defined in -:file:`numba_dpex/config.py`. + ``NUMBA_DPEX_DEBUG_CACHE`` to 1. All environment variables are defined in + :file:`numba_dpex/config.py`. diff --git a/docs/source/user_guide/debugging/altering.rst b/docs/source/user_guide/debugging/altering.rst index fb222c9bff..c7813a3b49 100644 --- a/docs/source/user_guide/debugging/altering.rst +++ b/docs/source/user_guide/debugging/altering.rst @@ -1,4 +1,4 @@ -.. _altering: +.. include:: ./../../ext_links.txt Altering Execution ================== diff --git a/docs/source/user_guide/debugging/backtrace.rst b/docs/source/user_guide/debugging/backtrace.rst index ffc1be6995..6935df4f51 100644 --- a/docs/source/user_guide/debugging/backtrace.rst +++ b/docs/source/user_guide/debugging/backtrace.rst @@ -1,4 +1,4 @@ -.. _backtrace: +.. include:: ./../../ext_links.txt Backtrace ========== diff --git a/docs/source/user_guide/debugging/breakpoints.rst b/docs/source/user_guide/debugging/breakpoints.rst index 7920c63feb..bb6b2504cf 100644 --- a/docs/source/user_guide/debugging/breakpoints.rst +++ b/docs/source/user_guide/debugging/breakpoints.rst @@ -1,3 +1,5 @@ +.. include:: ./../../ext_links.txt + Breakpoints =========== diff --git a/docs/source/user_guide/debugging/common_issues.rst b/docs/source/user_guide/debugging/common_issues.rst index 0579554371..a214a9883d 100644 --- a/docs/source/user_guide/debugging/common_issues.rst +++ b/docs/source/user_guide/debugging/common_issues.rst @@ -1,3 +1,5 @@ +.. include:: ./../../ext_links.txt + Common issues and tips ====================== diff --git a/docs/source/user_guide/debugging/data.rst b/docs/source/user_guide/debugging/data.rst index 7eaed11212..0926a8020e 100644 --- a/docs/source/user_guide/debugging/data.rst +++ b/docs/source/user_guide/debugging/data.rst @@ -1,3 +1,5 @@ +.. include:: ./../../ext_links.txt + Examining Data ============== diff --git a/docs/source/user_guide/debugging/debugging_environment.rst b/docs/source/user_guide/debugging/debugging_environment.rst index 321ccf0db3..abedd0840d 100644 --- a/docs/source/user_guide/debugging/debugging_environment.rst +++ b/docs/source/user_guide/debugging/debugging_environment.rst @@ -1,4 +1,4 @@ -.. _debugging-environment: +.. include:: ./../../ext_links.txt Configure debugging environment ================================= diff --git a/docs/source/user_guide/debugging/features.rst b/docs/source/user_guide/debugging/features.rst index 80ac81c4f6..e6d95e6983 100644 --- a/docs/source/user_guide/debugging/features.rst +++ b/docs/source/user_guide/debugging/features.rst @@ -1,3 +1,5 @@ +.. include:: ./../../ext_links.txt + Supported Features ================== diff --git a/docs/source/user_guide/debugging/frame_info.rst b/docs/source/user_guide/debugging/frame_info.rst index 31904072b1..bd2b9e1f76 100644 --- a/docs/source/user_guide/debugging/frame_info.rst +++ b/docs/source/user_guide/debugging/frame_info.rst @@ -1,3 +1,5 @@ +.. include:: ./../../ext_links.txt + Information About a Frame ========================= diff --git a/docs/source/user_guide/debugging/limitations.rst b/docs/source/user_guide/debugging/limitations.rst index 5e5ba34a1b..e061148c9f 100644 --- a/docs/source/user_guide/debugging/limitations.rst +++ b/docs/source/user_guide/debugging/limitations.rst @@ -1,3 +1,5 @@ +.. include:: ./../../ext_links.txt + Limitations =========== diff --git a/docs/source/user_guide/debugging/local_variables.rst b/docs/source/user_guide/debugging/local_variables.rst index d99ae2096a..6bb61d6637 100644 --- a/docs/source/user_guide/debugging/local_variables.rst +++ b/docs/source/user_guide/debugging/local_variables.rst @@ -1,3 +1,5 @@ +.. include:: ./../../ext_links.txt + Debugging Local Variables ========================= diff --git a/docs/source/user_guide/debugging/numba-0.55.rst b/docs/source/user_guide/debugging/numba-0.55.rst index 706e1ec5b8..846a37472f 100644 --- a/docs/source/user_guide/debugging/numba-0.55.rst +++ b/docs/source/user_guide/debugging/numba-0.55.rst @@ -1,3 +1,5 @@ +.. include:: ./../../ext_links.txt + Debugging Features in Numba 0.55 ================================ diff --git a/docs/source/user_guide/debugging/set_up_machine.rst b/docs/source/user_guide/debugging/set_up_machine.rst index 015ea9ad9a..a42666859c 100644 --- a/docs/source/user_guide/debugging/set_up_machine.rst +++ b/docs/source/user_guide/debugging/set_up_machine.rst @@ -1,3 +1,5 @@ +.. include:: ./../../ext_links.txt + Set up the machine for debugging ==================================== diff --git a/docs/source/user_guide/debugging/stepping.rst b/docs/source/user_guide/debugging/stepping.rst index 536140ed3c..a2b9127776 100644 --- a/docs/source/user_guide/debugging/stepping.rst +++ b/docs/source/user_guide/debugging/stepping.rst @@ -1,3 +1,5 @@ +.. include:: ./../../ext_links.txt + Stepping ======== diff --git a/docs/source/user_guide/debugging/symbols.rst b/docs/source/user_guide/debugging/symbols.rst index 5c74798807..0586ec9c7b 100644 --- a/docs/source/user_guide/debugging/symbols.rst +++ b/docs/source/user_guide/debugging/symbols.rst @@ -1,3 +1,5 @@ +.. include:: ./../../ext_links.txt + Examining the Symbol Table ========================== diff --git a/docs/source/user_guide/dpnp_offload.rst b/docs/source/user_guide/dpnp_offload.rst index 2a8eb68326..37b2afd961 100644 --- a/docs/source/user_guide/dpnp_offload.rst +++ b/docs/source/user_guide/dpnp_offload.rst @@ -1,8 +1,102 @@ -.. _dpnp_offload: .. include:: ./../ext_links.txt -Compiling and Offloading DPNP -============================== +Compiling and Offloading ``dpnp`` Functions +=========================================== + +Data Parallel Extension for NumPy* (``dpnp``) is a drop-in ``NumPy*`` +replacement library. The library is developed using SYCL and oneMKL. +``numba-dpex`` relies on ``dpnp`` to support offloading ``NumPy`` library +functions to SYCL devices. For ``NumPy`` functions that are offloaded using +``dpnp``, ``numba-dpex`` generates library calls directly to ``dpnp``'s +`low-level API`_ inside the generated LLVM IR. + +.. _low-level API: https://github.com/IntelPython/dpnp/tree/master/dpnp/backend + +.. _integration-dpnp-backend: + +During compiling a Python function decorated with the ``numba.njit`` decorator, +``numba-dpex`` substitutes ``NumPy`` function calls with corresponding ``dpnp`` +low-level API function calls. The substitution happens transparent to an +end-user and is implemented as a renaming pass in ``numba-dpex``'s pass +pipeline. + +.. code-block:: python + + import numpy as np + from numba import njit + import dpctl + + + @njit + def foo(a): + return np.sum(a) # this call will be replaced with the dpnp.sum function + + + a = np.arange(42) + + with dpctl.device_context(): + result = foo(a) + + print(result) + +:samp:`np.sum(a)` will be replaced with `dpnp_sum_c(...)`_. + +.. _`dpnp_sum_c(...)`: https://github.com/IntelPython/dpnp/blob/ef404c0f284b0c508ed1e556e140f02f76ae5551/dpnp/backend/kernels/dpnp_krnl_reduction.cpp#L58 + +The following sections go over as aspects of the dpnp integration inside +numba-dpex. + +.. _dpnp-integration-repository-map: + +Repository map +-------------- + +- The code for numba-dpex's dpnp integration resides in the + :file:`numba_dpex/dpnp_iface` sub-module. +- Tests resides in :file:`numba_dpex/tests/njit_tests/dpnp`. +- Helper pass resides in :file:`numba_dpex/rename_numpy_functions_pass.py`. + +.. _dpnp-integration-architecture: + +Design +------ + +The rewrite logic to substitute NumPy functions with dpnp function calls in the +Numba IR is implemented by the :class:`RewriteOverloadedNumPyFunctionsPass` +pass. The :mod:`numba_dpex.dpnp_iface.stubs` module defines a set of `stub` +classes for each of the NumPy functions calls that are currently substituted +out. The outline of a stub class is as follows: + +.. code-block:: python + + # numba_dpex/dpnp_iface/stubs.py - imported in numba_dpex.__init__.py + + + class dpnp(Stub): + class sum(Stub): # stub function + pass + +Each stub is provided with a concrete implementation to generates the actual +code using Numba's ``overload`` function API. E.g., + +.. code-block:: python + + @overload(stubs.dpnp.sum) + def dpnp_sum_impl(a): + ... + +The complete implementation is in +:file:`numba_dpex/dpnp_iface/dpnp_transcendentalsimpl.py`. + +Parallel Range +-------------- + +``numba-dpex`` implements the ability to run loops in parallel, +similar to OpenMP parallel for loops and Numba*’s ``prange``. The loop- +body is scheduled in seperate threads, and they execute in a ``nopython`` numba +context. ``prange`` automatically takes care of data privatization: + + - prange, reduction prange - blackscholes, math example diff --git a/docs/source/user_guide/kernel_programming/device-functions.rst b/docs/source/user_guide/kernel_programming/device-functions.rst index 3aad63e086..0ad5a10441 100644 --- a/docs/source/user_guide/kernel_programming/device-functions.rst +++ b/docs/source/user_guide/kernel_programming/device-functions.rst @@ -1,5 +1,3 @@ -.. _device-functions: - Writing Device Functions ======================== diff --git a/docs/source/user_guide/kernel_programming/writing_kernels.rst b/docs/source/user_guide/kernel_programming/writing_kernels.rst index b06edad752..90566dcfd1 100644 --- a/docs/source/user_guide/kernel_programming/writing_kernels.rst +++ b/docs/source/user_guide/kernel_programming/writing_kernels.rst @@ -1,4 +1,3 @@ -.. _writing_kernels: .. include:: ./../../ext_links.txt Writing Data Parallel Kernels