Expanded tensor_intro to cover moving data between host and device

Added user_guides/execution_model

Moved license from user_guides/ to top-level.

Author: oleksandr-pavlyk

docs/doc_sources/beginners_guides/index.rst

@@ -4,6 +4,18 @@
 Beginner's guides
 =================
 
+Introduction
+------------
+
+:mod:`dpctl` brings the standard-based execution model to program a heterogeneous system
+to Python through invocations of oneAPI-based native libraries, their Python interfaces,
+or by using DPC++-based Python native extensions built using :mod:`dpctl` integration with
+Python native extension generators.
+
+The :py:mod:`dpctl` runtime is built on top of the C++ SYCL-2020 standard as implemented in
+`Intel(R) oneAPI DPC++ compiler <dpcpp_compiler>`_ and is designed to be both vendor and
+architecture agnostic.
+
 Installation
 ------------
 
@@ -15,12 +27,6 @@ Working with devices
 
 * :ref:`Managing devices <beginners_guide_managing_devices>`
 
-..
-    * :ref:`Enumerating available devices <beginners_guide_enumerating_devices>`
-    * :ref:`Selecting a device <beginners_guide_device_selection>`
-    * :ref:`Querying information about device <beginners_guide_device_info>`
-    * :ref:`Can I influence which device is the default one? <beginners_guide_env_variables>`
-
 Introduction to array library
 -----------------------------
 
@@ -29,7 +35,8 @@ Introduction to array library
 Miscellaneous
 -------------
 
-* History of ``"dpctl"`` :ref:`name <beginners_guide_why_dpctl>`?
+* History of ``"dpctl"`` :ref:`name <beginners_guide_why_dpctl>`
+* Frequenty asked questions
 
 .. toctree::
     :hidden:

docs/doc_sources/beginners_guides/tensor_intro.rst

@@ -70,12 +70,11 @@ A created instance of :class:`usm_ndarray` has an associated :class:`dpctl.SyclQ
 using :attr:`dpctl.tensor.usm_ndarray.sycl_queue` property. The underlying USM allocation
 is allocated on :class:`dpctl.SyclDevice` and is bound to :class:`dpctl.SyclContext` targeted by this queue.
 
+.. _dpctl_tensor_compute_follows_data:
 
 Execution model
 ---------------
 
-.. _dpctl_tensor_compute_follows_data:
-
 When one of more instances of ``usm_ndarray`` objects are passed to a function in :py:mod:`dpctl.tensor` other than creation function,
 a "compute follows data" execution model is followed.
 
@@ -92,6 +91,7 @@ each one corresponds to the same underlying ``sycl::queue`` object. In such a ca
 If input arrays do not conform to the compute-follows-data requirements, :py:exc:`dpctl.utils.ExecutionPlacementError` is raised.
 User must explicitly migrate the data to unambiguously control the execution placement.
 
+.. _dpctl_tensor_array_migration:
 
 Migrating arrays
 ----------------
@@ -227,3 +227,61 @@ following this convention:
 
     # r3 has value "host"
     r3 = get_coerced_usm_type(["host", "host", "host"])
+
+Sharing data between devices and Python
+---------------------------------------
+
+Python objects, such as sequences of :class:`int`, :class:`float`, or :class:`complex` objects,
+or NumPy arrays can be converted to :class:`dpctl.tensor.usm_ndarray` using :func:`dpctl.tensor.asarray`
+function.
+
+.. code-block:: python
+
+    >>> from dpctl import tensor as dpt
+    >>> import numpy as np
+    >>> import mkl_random
+
+    >>> # Sample from true random number generator
+    >>> rs = mkl_random.RandomState(brng="nondeterm")
+    >>> x_np = rs.uniform(-1, 1, size=(6, 512)).astype(np.float32)
+
+    >>> # copy data to USM-device (default) allocated array
+    >>> x_usm = dpt.asarray(x_np)
+    >>> dpt.max(x_usm, axis=1)
+    usm_ndarray([0.9998379 , 0.9963589 , 0.99818915, 0.9975991 , 0.9999802 ,
+                0.99851537], dtype=float32)
+    >>> np.max(x_np, axis=1)
+    array([0.9998379 , 0.9963589 , 0.99818915, 0.9975991 , 0.9999802 ,
+          0.99851537], dtype=float32)
+
+The content of :class:`dpctl.tensor.usm_ndarray` may be copied into
+a NumPy array using :func:`dpctl.tensor.asnumpy` function:
+
+.. code-block:: python
+
+    from dpctl import tensor as dpt
+    import numpy as np
+
+    def sieve_pass(r : dpt.usm_ndarray, v : dpt.usm_ndarray) -> dpt.usm_ndarray:
+        "Single pass of sieve of Eratosthenes"
+        m = dpt.min(r[r > v])
+        r[ (r > m) & (r % m == 0) ] = 0
+        return m
+
+    def sieve(n : int) -> dpt.usm_ndarray:
+        "Find primes <=n using sieve of Erathosthenes"
+        idt = dpt.int32
+        s = dpt.concat((
+          dpt.arange(2, 3, dtype=idt),
+          dpt.arange(3, n + 1, 2, dtype=idt)
+        ))
+        lb = dpt.zeros(tuple(), dtype=idt)
+        while lb * lb < n + 1:
+            lb = sieve_pass(s, lb)
+        return s[s > 0]
+
+    # get prime numbers <= a million into NumPy array
+    # to save to disk
+    ps_np = dpt.asnumpy(sieve(10**6))
+
+    np.savetxt("primes.txt", ps_np, fmt="%d")

docs/doc_sources/contributor_guides/building.rst

@@ -57,58 +57,86 @@ After building the Conda package, install it by executing:
 
     conda install dpctl
 
-.. note::
-
-    You can face issues with conda-build version 3.20. Use conda-build
-    3.18 instead.
-
 
 Build and Install with scikit-build
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 To build using Python ``setuptools`` and ``scikit-build``, install the following Python packages:
 
-    - ``cython``
-    - ``numpy``
-    - ``cmake``
-    - ``scikit-build``
-    - ``ninja``
-    - ``gtest`` (optional to run C API tests)
-    - ``gmock`` (optional to run C API tests)
-    - ``pytest`` (optional to run Python API tests)
+- ``cython``
+- ``numpy``
+- ``cmake``
+- ``scikit-build``
+- ``ninja``
+- ``gtest`` (optional to run C API tests)
+- ``gmock`` (optional to run C API tests)
+- ``pytest`` (optional to run Python API tests)
 
 Once the prerequisites are installed, building using ``scikit-build`` involves the usual steps.
 
 To build and install, run:
 
-.. code-block:: bash
+.. tab-set::
+
+    .. tab-item:: Linux
+        :sync: lnx
+
+        .. code-block:: bash
+
+            python setup.py install -- -G Ninja -DCMAKE_C_COMPILER:PATH=icx -DCMAKE_CXX_COMPILER:PATH=icpx
 
-    python setup.py install -- -G Ninja -DCMAKE_C_COMPILER:PATH=icx -DCMAKE_CXX_COMPILER:PATH=icpx
+    .. tab-item:: Windows
+        :sync: win
+
+        .. code-block:: bat
+
+            python setup.py install -- -G Ninja -DCMAKE_C_COMPILER:PATH=icx -DCMAKE_CXX_COMPILER:PATH=icx
 
 
 To develop, run:
 
-.. code-block:: bash
+.. tab-set::
 
-    python setup.py develop -G Ninja -DCMAKE_C_COMPILER:PATH=icx -DCMAKE_CXX_COMPILER:PATH=icpx
+    .. tab-item:: Linux
+        :sync: lnx
 
-On Windows OS, use ``icx`` for both C and CXX compilers.
+        .. code-block:: bash
 
-To develop on Linux OS, use the driver script:
+            python setup.py develop -G Ninja -DCMAKE_C_COMPILER:PATH=icx -DCMAKE_CXX_COMPILER:PATH=icpx
 
-.. code-block:: bash
+    .. tab-item:: Windows
+        :sync: win
+
+        .. code-block:: bat
 
-    python scripts/build_locally.py
+            python setup.py develop -G Ninja -DCMAKE_C_COMPILER:PATH=icx -DCMAKE_CXX_COMPILER:PATH=icx
 
 
-Building Using Custom dpcpp
+Developing can be streamlined using the driver script:
+
+.. tab-set::
+
+    .. tab-item:: Linux
+        :sync: lnx
+
+        .. code-block:: bash
+
+            python scripts/build_locally.py --verbose
+
+    .. tab-item:: Windows
+        :sync: win
+
+        .. code-block:: bat
+
+            python scripts/build_locally.py --verbose
+
+
+Building Using Custom DPC++
 ---------------------------
 
 You can build dpctl from the source using the `DPC++ toolchain <https://github.com/intel/llvm/blob/sycl/sycl/doc/GetStartedGuide.md>`_
 instead of the DPC++ compiler that comes with oneAPI.
 
-Do this, to enable support for CUDA devices.
-
 Following steps in the `Build and install with scikit-build`_ use a command-line option to set
 the relevant CMake variables, for example:
 

docs/doc_sources/index.rst

@@ -4,11 +4,11 @@ Data Parallel Control
 
 .. _DpctlIntroduction:
 
-Python package :py:mod:`dpctl` enables Python users to engage with multiple
+Python package :py:mod:`dpctl` enables Python users to engage multiple
 compute devices commonly available in modern consumer- and server-grade
 computers using industry-standard :sycl_execution_model:`SYCL execution model <>`
-facilitated by Intel(R) oneAPI :dpcpp_compiler:`DPC++ compiler <>` implementing
-:sycl_spec_2020:`SYCL 2020 standard <>`.
+facilitated by :sycl_spec_2020:`SYCL 2020 standard <>`-compliant
+Intel(R) oneAPI :dpcpp_compiler:`DPC++ compiler <>`.
 
 :py:mod:`dpctl` provides a reference data-parallel implementation of
 array library :py:mod:`dpctl.tensor` conforming to Python Array API specification.
@@ -86,3 +86,4 @@ take place.
    user_guides/index
    api_reference/index
    contributor_guides/index
+   license

docs/doc_sources/user_guides/license.rst renamed to docs/doc_sources/license.rst

@@ -58,8 +58,8 @@ Definitions
 * **Unified Shared Memory**
    Unified Shared Memory (USM) refers to pointer-based device memory management.
    USM allocations are bound to context. It means, a pointer representing
-   USM allocation can be unambiguously mapped to the data it represents only
-   if the associated context is known. USM allocations are accessible by
+   USM allocation can be unambiguously mapped to the data it represents *only
+   if* the associated context is known. USM allocations are accessible by
    computational kernels that are executed on a device, provided that the
    allocation is bound to the same context that is used to construct the queue
    where the kernel is scheduled for execution.