IntelPython · samaid · Nov 5, 2021 · Nov 5, 2021 · Nov 5, 2021 · Nov 5, 2021
@@ -7,24 +7,23 @@ About dpctl
 
 <img align="left" src="https://spec.oneapi.io/oneapi-logo-white-scaled.jpg" alt="oneAPI logo" />
 
-`dpctl` (data parallel control) is a lightweight [Python package](https://intelpython.github.io/dpctl) exposing a
-subset of the Intel(R) oneAPI DPC++ [runtime classes](https://www.khronos.org/registry/SYCL/specs/sycl-2020/html/sycl-2020.html#_sycl_runtime_classes)
-that is distributed as part of [Intel(R) Distribution for Python*](https://software.intel.com/content/www/us/en/develop/tools/oneapi/components/distribution-for-python.html) and
-is included in Intel(R) [oneAPI](https://oneapi.io) [Base ToolKit](https://software.intel.com/content/www/us/en/develop/tools/oneapi/base-toolkit.html).
-`dpctl` lets Python users query SYCL platforms, discover and represent SYCL devices, and construct SYCL queues to control data-parallel code execution on [Intel(R) XPUs](https://www.intel.com/content/www/us/en/newsroom/news/xpu-vision-oneapi-server-gpu.html) from Python.
-
-`dpctl` features classes representing [SYCL unified shared memory](https://www.khronos.org/registry/SYCL/specs/sycl-2020/html/sycl-2020.html#sec:usm)
-allocations as well as higher-level objects such as [`dpctl.tensor.usm_ndarray`](https://intelpython.github.io/dpctl/latest/docfiles/dpctl.tensor_api.html#module-dpctl.tensor) on top of USM allocations.
-
-`dpctl` assists authors of Python native extensions written in C,
-Cython, or pybind11 to use its `dpctl.SyclQueue` object to indicate the offload
-target as well as objects in `dpctl.memory` and `dpctl.tensor` submodules to
-represent USM allocations that are accessible from within data-parallel code executed
-on the target queue.
-
-`dpctl.tensor` submodule provides an array container representing an array in a
-strided layout on top of a USM allocation. The submodule provides an array-API
-conforming oneAPI DPC++ powered library to manipulate the array container.
+Data Parallel Control `dpctl` is the Python library that controls multiple devices of a platform, features classes for 
+unified shared memory (USM) management, and implements tensor array API on top of it. It is a foundational part of 
+a larger family of libraries and tools for Data Parallel Python (DPPY) aimed to program XPUs the same way as CPUs.
+
+The library is available via [conda](https://anaconda.org/intel/dpctl) and [pip](https://pypi.org/project/dpctl/).
+It also comes with [Intel(R) Distribution for Python*](https://software.intel.com/content/www/us/en/develop/tools/oneapi/components/distribution-for-python.html)
+
+The `dpctl` library is built upon [SYCL standard](https://www.khronos.org/sycl/) and implements a subset of [runtime 
+classes specifications](https://www.khronos.org/registry/SYCL/specs/sycl-2020/html/sycl-2020.html#_sycl_runtime_classes),
+which allow users to query SYCL platforms, discover and represent SYCL devices, and construct SYCL queues for execution
+of data-parallel code.
+
+The library also assists authors of Python native extensions written in C, Cython, or pybind11 to access objects 
+representing devices, queues, memory, and tensor array APIs.
+
+Please refer to [Getting Started and API Reference documentation](https://intelpython.github.io/dpctl) for more 
+information. 
 
 Requirements
 ============

@@ -14,25 +14,26 @@ Sub-modules
     :mod:`dpctl.memory`
         USM allocators and deallocators and classes that implement Python's
         `buffer protocol`_.
+    :mod:`dpctl.tensor`
+        Implementation of different types of tensor classes that use USM memory.
     :mod:`dpctl.program`
-        Experimental wrappers for SYCL 1.2 ``program`` and ``kernel`` classes.
+        Experimental wrappers for SYCL 1.2 `Program`<https://sycl.readthedocs.io/en/latest/iface/program.html>
+        and `Kernel`<https://sycl.readthedocs.io/en/latest/iface/kernel.html> classes.
         The module is going to be refactored in the future to support SYCL
-        2020's ``kernel_bundle`` feature and the wrapper for the ``program``
+        2020's ``sycl::kernel_bundle`` feature and the wrapper for the ``sycl::program``
         class is going to be removed.
-    :mod:`dpctl.tensor`
-        Implementation of different types of tensor classes that use USM memory.
 
 Classes
 -------
 
 .. toctree::
     :maxdepth: 1
 
-    dpctl.SyclContext : A Python class representing `sycl::context` <dpctl_pyapi/SyclContext>
-    dpctl.SyclDevice : A Python class representing `sycl::device` <dpctl_pyapi/SyclDevice>
-    dpctl.SyclEvent : A Python class representing `sycl::event` <dpctl_pyapi/SyclEvent>
-    dpctl.SyclPlatform : A Python class representing `sycl::platform` <dpctl_pyapi/SyclPlatform>
-    dpctl.SyclQueue : A Python class representing `sycl::queue` <dpctl_pyapi/SyclQueue>
+    `dpctl.SyclPlatform`<dpctl_pyapi/SyclPlatform> : A Python class representing `SYCL Platforms`<https://sycl.readthedocs.io/en/latest/iface/platform.html>
+    `dpctl.SyclDevice`<dpctl_pyapi/SyclDevice> : A Python class representing `SYCL Devices`<https://sycl.readthedocs.io/en/latest/iface/device.html>
+    `dpctl.SyclQueue`<dpctl_pyapi/SyclQueue> : A Python class representing `SYCL Queues`<https://sycl.readthedocs.io/en/latest/iface/queue.html>
+    `dpctl.SyclContext`<dpctl_pyapi/SyclContext> : A Python class representing `SYCL Contexts`<https://sycl.readthedocs.io/en/latest/iface/context.html>
+    `dpctl.SyclEvent`<dpctl_pyapi/SyclEvent> : A Python class representing `SYCL Events`<https://sycl.readthedocs.io/en/latest/iface/event.html>
 
 Enumerations
 ------------
@@ -53,17 +54,17 @@ Exceptions
 Device Selection Functions
 --------------------------
 
-.. autofunction:: get_devices
-.. autofunction:: select_accelerator_device
-.. autofunction:: select_cpu_device
-.. autofunction:: select_default_device
-.. autofunction:: select_gpu_device
-.. autofunction:: select_host_device
 .. autofunction:: get_num_devices
+.. autofunction:: get_devices
+.. autofunction:: has_host_device
 .. autofunction:: has_cpu_devices
 .. autofunction:: has_gpu_devices
 .. autofunction:: has_accelerator_devices
-.. autofunction:: has_host_device
+.. autofunction:: select_default_device
+.. autofunction:: select_cpu_device
+.. autofunction:: select_gpu_device
+.. autofunction:: select_host_device
+.. autofunction:: select_accelerator_device
 
 Queue Management Functions
 --------------------------

@@ -1,17 +1,14 @@
-Welcome to Data-parallel Control (dpctl)'s documentation!
-=========================================================
+Data-Parallel Control - The Library That Controls XPUs
+=======================================================
 
-The data-parallel control (dpctl) library provides C and Python bindings for
-`SYCL 2020 <https://www.khronos.org/registry/SYCL/specs/sycl-2020/html/sycl-2020.html>`_.
-The SYCL 2020 features supported by dpctl are limited to those included by
-Intel's DPCPP compiler and specifically cover the SYCL runtime classes described
-in `Section 4.6 <https://www.khronos.org/registry/SYCL/specs/sycl-2020/html/sycl-2020.html#_sycl_runtime_classes>`_
-of the SYCL 2020 specification. Apart from the bindings for these runtime
-classes, dpctl includes bindings for SYCL USM memory allocators and
-deallocators. Dpctl's Python API provides classes that implement
-`Python buffer protocol <https://docs.python.org/3/c-api/buffer.html>`_
-using SYCL USM memory; making it possible to create Python objects that are
-backed by SYCL USM memory.
+Data Parallel Control ``dpctl`` is the Python library that controls multiple devices of a platform, features classes for
+unified shared memory (USM) management, and implements tensor array API on top of it. It is a foundational part of
+a larger family of libraries and tools for Data Parallel Python (DPPY) aimed to program XPUs the same way as CPUs.
 
-Dpctl also supports the DPCPP ``ONEAPI::filter_selector`` extension and has
-experimental support for SYCL's ``kernel`` and ``program`` classes.
+The ``dpctl`` library is built upon `SYCL standard`<https://www.khronos.org/sycl/> and implements a subset of
+`runtime classes specifications`<https://www.khronos.org/registry/SYCL/specs/sycl-2020/html/sycl-2020.html#_sycl_runtime_classes>,
+which allow users to query SYCL platforms, discover and represent SYCL devices, and construct SYCL queues for execution
+of data-parallel code.
+
+The library also assists authors of Python native extensions written in C, Cython, or pybind11 to access objects
+representing devices, queues, memory, and tensor array APIs.
@@ -56,7 +56,7 @@ Dpctl can also be istalled from Pypi.
 
 .. code-block:: bash
 
-    python -m pip install --index-url https://pypi.anaconda.org/intel/simple -extra-index-url https://pypi.org/simple dpctl
+    python -m pip install --index-url https://pypi.anaconda.org/intel/simple --extra-index-url https://pypi.org/simple dpctl
 
 .. note::
 

@@ -213,7 +213,7 @@ cpdef get_current_backend():
 @contextmanager
 def device_context(arg):
     """
-    Yields a SYCL queue corresponding to the input filter string.
+    Yields a SYCL queue corresponding to the input queue object, device object, or device filter selector string.
 
     This context manager "activates", *i.e.*, sets as the currently usable
     queue, the SYCL queue defined by the argument `arg`.
@@ -223,25 +223,22 @@ def device_context(arg):
     usable queue on exiting the context manager.
 
     Args:
-
-        queue_str (str) : A string corresponding to the DPC++ filter selector.
+        arg : A :class:`dpctl.SyclQueue` object, or a :class:`dpctl.SyclDevice` object, or a filter selector string
 
     Yields:
-        :class:`.SyclQueue`: A SYCL queue corresponding to the specified
-        filter string.
+        :class:`.SyclQueue`: A SYCL queue corresponding to the specified input device, queue, or filter string.
 
     Raises:
         SyclQueueCreationError: If the SYCL queue creation failed.
 
     :Example:
-        To create a scope within which the Level Zero GPU number 0 is active,
-        a programmer needs to do the following.
+        The following example sets current queue targeting specific device indicated with filter selector string in the scope of `with` block:
 
         .. code-block:: python
 
             import dpctl
             with dpctl.device_context("level0:gpu:0"):
-                pass
+                do_something_on_gpu0()
 
     """
     ctxt = None