From b756857461ae7837ba4dbb0cfdb211bac84a5a9c Mon Sep 17 00:00:00 2001 From: samaid Date: Fri, 5 Nov 2021 09:00:52 -0500 Subject: [PATCH 1/8] Update README.md Intro section enhancements --- README.md | 35 +++++++++++++++++------------------ 1 file changed, 17 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 22e170adc4..801977ef0c 100644 --- a/README.md +++ b/README.md @@ -7,24 +7,23 @@ About dpctl 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 ============ From aefb4e5b8c5a7441ffc89e665c57e8d02fff1364 Mon Sep 17 00:00:00 2001 From: samaid Date: Fri, 5 Nov 2021 11:46:16 -0500 Subject: [PATCH 2/8] Update _sycl_queue_manager.pyx Improved device_context(arg) API reference documentation --- dpctl/_sycl_queue_manager.pyx | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/dpctl/_sycl_queue_manager.pyx b/dpctl/_sycl_queue_manager.pyx index 53d5058d04..73a3ac327a 100644 --- a/dpctl/_sycl_queue_manager.pyx +++ b/dpctl/_sycl_queue_manager.pyx @@ -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 device object, the queue object, or the filter 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:`.SyclDevice` object, or a :class:`.SyclQueue` 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 activates Level Zero GPU number 0 by respective filter selector string: .. code-block:: python import dpctl with dpctl.device_context("level0:gpu:0"): - pass + do_something_on_gpu0() """ ctxt = None From 21fcca817a5a8a246fb99c795160df145efde3b8 Mon Sep 17 00:00:00 2001 From: samaid <55950596+samaid@users.noreply.github.com> Date: Fri, 5 Nov 2021 11:57:29 -0500 Subject: [PATCH 3/8] Update dpctl/_sycl_queue_manager.pyx Co-authored-by: Oleksandr Pavlyk --- dpctl/_sycl_queue_manager.pyx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dpctl/_sycl_queue_manager.pyx b/dpctl/_sycl_queue_manager.pyx index 73a3ac327a..b668f4398e 100644 --- a/dpctl/_sycl_queue_manager.pyx +++ b/dpctl/_sycl_queue_manager.pyx @@ -213,7 +213,7 @@ cpdef get_current_backend(): @contextmanager def device_context(arg): """ - Yields a SYCL queue corresponding to the input device object, the queue object, or the 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`. From f334dad7fa707d1bb50389634cdf811a05d1c04d Mon Sep 17 00:00:00 2001 From: samaid <55950596+samaid@users.noreply.github.com> Date: Fri, 5 Nov 2021 11:57:52 -0500 Subject: [PATCH 4/8] Update dpctl/_sycl_queue_manager.pyx Co-authored-by: Oleksandr Pavlyk --- dpctl/_sycl_queue_manager.pyx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dpctl/_sycl_queue_manager.pyx b/dpctl/_sycl_queue_manager.pyx index b668f4398e..a2aa794231 100644 --- a/dpctl/_sycl_queue_manager.pyx +++ b/dpctl/_sycl_queue_manager.pyx @@ -223,7 +223,7 @@ def device_context(arg): usable queue on exiting the context manager. Args: - arg : A :class:`.SyclDevice` object, or a :class:`.SyclQueue` object, or a filter selector string + 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 input device, queue, or filter string. From ec323b53e01b6b3f0a3a162762ebb1f3794c13d0 Mon Sep 17 00:00:00 2001 From: samaid <55950596+samaid@users.noreply.github.com> Date: Fri, 5 Nov 2021 12:11:18 -0500 Subject: [PATCH 5/8] Update dpctl/_sycl_queue_manager.pyx Co-authored-by: Oleksandr Pavlyk --- dpctl/_sycl_queue_manager.pyx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dpctl/_sycl_queue_manager.pyx b/dpctl/_sycl_queue_manager.pyx index a2aa794231..91e69396f7 100644 --- a/dpctl/_sycl_queue_manager.pyx +++ b/dpctl/_sycl_queue_manager.pyx @@ -232,7 +232,7 @@ def device_context(arg): SyclQueueCreationError: If the SYCL queue creation failed. :Example: - The following example activates Level Zero GPU number 0 by respective filter selector string: + The following example sets current queue targeting specific device indicated with filter selector string in the scope of `with` block: .. code-block:: python From 7b1a8ad2083c1b5e22fcf5d498f5b7f6e6603ef9 Mon Sep 17 00:00:00 2001 From: samaid Date: Fri, 5 Nov 2021 12:15:12 -0500 Subject: [PATCH 6/8] Fixed pip install instruction Added extra dash for extra-index-url --- docs/docfiles/user_guides/QuickStart.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docfiles/user_guides/QuickStart.rst b/docs/docfiles/user_guides/QuickStart.rst index bc3df723dd..f19af4d527 100644 --- a/docs/docfiles/user_guides/QuickStart.rst +++ b/docs/docfiles/user_guides/QuickStart.rst @@ -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:: From 636d8b263b5034dd7b1afcff240dc9850781b3c3 Mon Sep 17 00:00:00 2001 From: samaid Date: Fri, 5 Nov 2021 12:18:15 -0500 Subject: [PATCH 7/8] Update intro.rst Made Intro section less SYCL centric. Main goal is to avoid references to SYCL as much as possible. Otherwise we will end up teaching Python users DPC++. I understand that references to SYCL in dpctl are unavoidable but still I truly believe we can educate general Python users how to use XPU without the need to read SYCL specs --- docs/docfiles/intro.rst | 27 ++++++++++++--------------- 1 file changed, 12 insertions(+), 15 deletions(-) diff --git a/docs/docfiles/intro.rst b/docs/docfiles/intro.rst index 115749b3da..55da37e55e 100644 --- a/docs/docfiles/intro.rst +++ b/docs/docfiles/intro.rst @@ -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 `_. -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 `_ -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 `_ -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` and implements a subset of +`runtime classes specifications`, +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. \ No newline at end of file From 89ad7dba2af716acf2e5042e5ef008dfaae42606 Mon Sep 17 00:00:00 2001 From: samaid Date: Fri, 5 Nov 2021 12:24:16 -0500 Subject: [PATCH 8/8] Update dpctl_pyapi.rst Rearranged the order of classes and functions to make the documentation flow more logical. Provided actual links to the SYCL Reference Manual describing Programs and Kernels. --- docs/docfiles/dpctl_pyapi.rst | 33 +++++++++++++++++---------------- 1 file changed, 17 insertions(+), 16 deletions(-) diff --git a/docs/docfiles/dpctl_pyapi.rst b/docs/docfiles/dpctl_pyapi.rst index dc0dc0fac9..4b9ec30fef 100644 --- a/docs/docfiles/dpctl_pyapi.rst +++ b/docs/docfiles/dpctl_pyapi.rst @@ -14,13 +14,14 @@ 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` + and `Kernel` 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 ------- @@ -28,11 +29,11 @@ Classes .. toctree:: :maxdepth: 1 - dpctl.SyclContext : A Python class representing `sycl::context` - dpctl.SyclDevice : A Python class representing `sycl::device` - dpctl.SyclEvent : A Python class representing `sycl::event` - dpctl.SyclPlatform : A Python class representing `sycl::platform` - dpctl.SyclQueue : A Python class representing `sycl::queue` + `dpctl.SyclPlatform` : A Python class representing `SYCL Platforms` + `dpctl.SyclDevice` : A Python class representing `SYCL Devices` + `dpctl.SyclQueue` : A Python class representing `SYCL Queues` + `dpctl.SyclContext` : A Python class representing `SYCL Contexts` + `dpctl.SyclEvent` : A Python class representing `SYCL Events` 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 --------------------------