IntelPython · diptorupd · Jul 19, 2023 · Jul 19, 2023 · Jul 19, 2023
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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<int, int>(...)`_.
+
+.. _`dpnp_sum_c<int, int>(...)`: 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
@@ -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
@@ -1,4 +1,3 @@
-.. _writing_kernels:
 .. include:: ./../../ext_links.txt
 
 Writing Data Parallel Kernels