IntelPython · samaid · Nov 17, 2022 · Nov 17, 2022
diff --git a/docs/sources/conf.py b/docs/sources/conf.py
@@ -1,3 +1,32 @@
+# *****************************************************************************
+# Copyright (c) 2022, Intel Corporation All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+#     Redistributions of source code must retain the above copyright notice,
+#     this list of conditions and the following disclaimer.
+#
+#     Redistributions in binary form must reproduce the above copyright notice,
+#     this list of conditions and the following disclaimer in the documentation
+#     and/or other materials provided with the distribution.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+# THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+# PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
+# CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
+# OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
+# WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
+# OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
+# EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+# *****************************************************************************
+
+# coding: utf-8
+# Configuration file for the Sphinx documentation builder.
+
 # -- Project information -----------------------------------------------------
 
 project = 'Data Parallel Extensions for Python*'

diff --git a/docs/sources/ext_links.txt b/docs/sources/ext_links.txt
@@ -11,3 +11,4 @@
 .. _Data Parallel Extension for Numba*: https://intelpython.github.io/numba-dpex/latest/index.html
 .. _SYCL*: https://www.khronos.org/sycl/
 .. _Data Parallel Control: https://intelpython.github.io/dpctl/latest/index.html
+.. _Data Parallel Extension for Numpy*: https://intelpython.github.io/dpnp/
diff --git a/docs/sources/prerequisites_and_installation.rst b/docs/sources/prerequisites_and_installation.rst
@@ -34,9 +34,9 @@ Extensions for Python manually.
 You can skip this step if you already installed Intel® Distribution for Python or Intel® AI Analytics Toolkit.
 The easiest way to install Data Parallel Extensions for Python is to install numba-dpex:
 
-Conda: ``conda install numba_dpex``
+Conda: ``conda install numba-dpex``
 
-Pip: ``pip install numba_dpex``
+Pip: ``pip install numba-dpex``
 
 The above commands will install ``numba-dpex`` along with its dependencies, including ``dpnp``, ``dpctl``,
 and required compiler runtimes and drivers.
diff --git a/docs/sources/programming_dpep.rst b/docs/sources/programming_dpep.rst
@@ -3,3 +3,63 @@
 
 Programming with Data Parallel Extensions for Python
 ====================================================
+
+As we briefly outlined, **Data Parallel Extensions for Python** consist of three foundational packages:
+
+* the `Numpy*`_-like library, ``dpnp``;
+* the compiler extension for `Numba*`_, ``numba-dpex``
+* the library for managing devices, queues, and heterogeneous data, ``dpctl``.
+
+Their underlying implementation is based on `SYCL*`_ standard, which is a cross-platform abstraction layer
+for heterogeneous computing on data parallel devices, such as CPU, GPU, or domain specific accelerators.
+
+Scalars vs. 0-dimensional arrays
+********************************
+
+Primitive types such as Python’s and Numpy’s ``float``, ``int``, or ``complex``, used to represent scalars,
+have the host storage. In contrast, ``dpctl.tensor.usm_ndarray`` and ``dpnp.ndarray`` have USM storage
+and carry associated allocation queue. For the :ref:`Compute-Follows-Data` consistent behavior
+all ``dpnp`` operations that produce scalars will instead produce respective 0-dimensional arrays.
+
+That implies, that some code changes may be needed to replace scalar math operations with respective
+``dpnp`` array operations. See `Data Parallel Extension for Numpy*`_ - **API Reference** section for details.
+
+Data Parallel Extension for Numpy - dpnp
+****************************************
+
+The ``dpnp`` library is a bare minimum to start programming numerical codes for data parallel devices.
+You may already have a Python script written in `Numpy*`_. Being a drop-in replacement of (a subset of) `Numpy*`_,
+to execute your `Numpy*`_ script on GPU usually requires changing just a few lines of the code:
+
+.. literalinclude:: ../../examples/01-hello_dpnp.py
+   :language: python
+   :lines: 27-
+   :caption: Your first NumPy code running on GPU
+   :name: ex_01_hello_dpnp
+
+In this example ``np.asarray()`` creates an array on the default `SYCL*`_ device, which is ``"gpu"`` on systems
+with integrated or discrete GPU (it is ``"cpu"`` on systems that do not have GPU).
+The queue associated with this array is now carried with ``x``, and ``np.sum(x)`` will derive it from ``x``,
+and respective pre-compiled kernel implementing ``np.sum()`` will be submitted to that queue.
+The result ``y`` will be allocated on the device 0-dimensional array associated with that queue too.
+
+All ``dpnp`` array creation routines as well as random number generators have additional optional keyword arguments
+``device``, ``queue``, and ``usm_type``, using which you can explicitly specify on which device or queue you want
+the tensor data to be created along with USM memory type to be used (``"host"``, ``"device"``, or ``"shared"``).
+In the following example we create the array ``x`` on the GPU device, and perform a reduction sum on it:
+
+.. literalinclude:: ../../examples/02-dpnp_device.py
+   :language: python
+   :lines: 27-
+   :caption: Select device type while creating array
+   :name: ex_02_dpnp_device
+
+Data Parallel Extension for Numba - numba-dpex
+**********************************************
+
+`Numba*`_ is a powerful Just-In-Time (JIT) compiler that works best on `Numpy*`_ arrays, `Numpy*`_ functions, and loops.
+Data parallel loops is where the data parallelism resides. It allows leveraging all available CPU cores,
+SIMD instructions, and schedules those in a way that exploits maximum instruction-level parallelism.
+The ``numba-dpex`` extension allows to compile and offload data parallel regions to any data parallel device.
+It takes just a few lines to modify your CPU `Numba*`_ script to run on GPU.
+
diff --git a/examples/01-hello_dpnp.py b/examples/01-hello_dpnp.py
@@ -0,0 +1,30 @@
+# *****************************************************************************
+# Copyright (c) 2022, Intel Corporation All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+#     Redistributions of source code must retain the above copyright notice,
+#     this list of conditions and the following disclaimer.
+#
+#     Redistributions in binary form must reproduce the above copyright notice,
+#     this list of conditions and the following disclaimer in the documentation
+#     and/or other materials provided with the distribution.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+# THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+# PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
+# CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
+# OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
+# WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
+# OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
+# EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+# *****************************************************************************
+
+import dpnp as np
+
+x = np.asarray([1, 2, 3])
+y = np.sum(x)
diff --git a/examples/02-dpnp_device.py b/examples/02-dpnp_device.py
@@ -0,0 +1,34 @@
+# *****************************************************************************
+# Copyright (c) 2022, Intel Corporation All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+#     Redistributions of source code must retain the above copyright notice,
+#     this list of conditions and the following disclaimer.
+#
+#     Redistributions in binary form must reproduce the above copyright notice,
+#     this list of conditions and the following disclaimer in the documentation
+#     and/or other materials provided with the distribution.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+# THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+# PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
+# CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
+# OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
+# WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
+# OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
+# EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+# *****************************************************************************
+
+import dpnp as np
+
+try:
+    x = np.asarray([1, 2, 3], device=”gpu”)
+except:
+    print(“GPU device is not available”)
+
+y = np.sum(x)