Fixes and clean ups for the device page of the user guide.

Diptorup Deb · Diptorup Deb · commit 9ded2dde987a · 2021-12-20T20:26:17.000-06:00
diff --git a/docs/conf.in b/docs/conf.in
@@ -1,23 +1,43 @@
+#                       Data Parallel Control (dpctl)
+#
+#  Copyright 2020-2021 Intel Corporation
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
+import os
+import sys
+
 from docutils.parsers.rst import directives
 from sphinx.ext.autosummary import Autosummary, get_documenter
 from sphinx.util.inspect import safe_getattr
 
 import dpctl
 
+sys.path.insert(0, os.path.abspath("."))
+
+import extlinks_gen as urlgen
+
 # -- Project information -----------------------------------------------------
 
 project = "Data-parallel Control (dpctl)"
-copyright = "2020, Intel Corp."
+copyright = "2020-21, Intel Corp."
 author = "Intel Corp."
 
 version = dpctl.__version__.strip(".dirty")
@@ -31,14 +51,15 @@ release = dpctl.__version__.strip(".dirty")
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    "sphinx.ext.todo",
-    "sphinx.ext.coverage",
-    "sphinx.ext.viewcode",
-    "sphinx.ext.githubpages",
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
+    "sphinx.ext.coverage",
+    "sphinx.ext.extlinks",
+    "sphinx.ext.githubpages",
     "sphinx.ext.napoleon",
-    "sphinxcontrib.programoutput"
+    "sphinx.ext.todo",
+    "sphinx.ext.viewcode",
+    "sphinxcontrib.programoutput",
 ]
 
 todo_include_todos = True
@@ -210,3 +231,7 @@ class AutoAutoSummary(Autosummary):
 
 def setup(app):
     app.add_directive("autoautosummary", AutoAutoSummary)
+
+
+# A dictionary of urls
+extlinks = urlgen.create_extlinks()
diff --git a/docs/docfiles/urls.json b/docs/docfiles/urls.json
@@ -0,0 +1,5 @@
+{
+    "sycl_aspects": "https://www.khronos.org/registry/SYCL/specs/sycl-2020/html/sycl-2020.html#table.device.aspect",
+    "sycl_device_info": "https://www.khronos.org/registry/SYCL/specs/sycl-2020/html/sycl-2020.html#_device_information_descriptors",
+    "numa_domain": "https://en.wikipedia.org/wiki/Non-uniform_memory_access"
+}
diff --git a/docs/docfiles/urls.rst b/docs/docfiles/urls.rst
@@ -6,11 +6,12 @@
 .. _SYCL 2020 spec: https://www.khronos.org/registry/SYCL/specs/sycl-2020/html/sycl-2020.html
 .. _sycl::platform: https://sycl.readthedocs.io/en/latest/iface/platform.html
 .. _sycl::device_selector: https://sycl.readthedocs.io/en/latest/iface/device-selector.html
-.. _sycl device: https://sycl.readthedocs.io/en/latest/iface/device.html
+.. _sycl::device: https://sycl.readthedocs.io/en/latest/iface/device.html
 .. _sycl queue: https://sycl.readthedocs.io/en/latest/iface/queue.html
 .. _sycl event: https://sycl.readthedocs.io/en/latest/iface/event.html
 .. _sycl context: https://sycl.readthedocs.io/en/latest/iface/context.html
 .. _oneAPI: https://www.oneapi.io/
 .. _oneAPI filter selection extension: https://github.com/intel/llvm/blob/sycl/sycl/doc/extensions/FilterSelector/FilterSelector.adoc
 .. _DPCPP environment variables: https://github.com/intel/llvm/blob/sycl/sycl/doc/EnvironmentVariables.md
 .. _SYCL 2020 aspects: https://www.khronos.org/registry/SYCL/specs/sycl-2020/html/sycl-2020.html#table.device.aspect
+.. _SYCL device info: https://www.khronos.org/registry/SYCL/specs/sycl-2020/html/sycl-2020.html#_device_information_descriptors
diff --git a/docs/docfiles/user_guides/manual/dpctl/device_selection.rst b/docs/docfiles/user_guides/manual/dpctl/device_selection.rst
@@ -5,7 +5,7 @@ Device Selection
 ################
 
 Device selection refers to programmatically selecting a single device from
-the set of  `devices`_ available on the system.
+the set of  :ref:`devices <devices>` available on the system.
 
 Selecting a Specific Type of Device
 -----------------------------------
@@ -93,7 +93,7 @@ A possible output for the example :ref:`fig-adv-device-selection` may be:
 
     The device listing including the device number value remain stable for
     a given system unless the driver configuration is changed or the SYCL
-    runtime setting is changed using the **SYCL_DEVICE_FILTER** environment
+    runtime setting is changed using the ``SYCL_DEVICE_FILTER`` environment
     variable. Please refer `oneAPI filter selection extension`_ for more detail.
 
 Advanced Device Selection
diff --git a/docs/docfiles/user_guides/manual/dpctl/devices.rst b/docs/docfiles/user_guides/manual/dpctl/devices.rst
@@ -4,45 +4,70 @@
 Device
 ######
 
-The :class:`dpctl.SyclDevice` class is an abstract representation of a
-data-parallel computation device. A device can be a CPU, GPU, FPGA, or other
-type of accelerator.
+A device is an abstract representation for an XPU. The :class:`dpctl.SyclDevice`
+class represents a device and is a wrapper over the `sycl::device`_ SYCL runtime
+class.
+
 
 Listing Devices
 ---------------
 
-:py:mod:`dpctl` has a fixed number of :ref:`root devices<RootDevice>` which does not vary as the application executes.
-
-Function :func:`dpctl.get_devices` can be used to retrieve these devices. This list is determined by
+:py:mod:`dpctl` provides the :func:`dpctl.get_devices` utility function to list
+the available devices on a user's system. The function only lists
+:class:`dpctl.SyclDevice` instances. The list of devices returned depends on
 available hardware, installed drivers, as well as by
-`environment variables <DPCPP environment variables>`_
-influencing SYCL runtime such as ``SYCL_DEVICE_FILTER`` or ``SYCL_DEVICE_ALLOWLIST``. Thanks for SYCL runtime
-determinism, this list does not change from run to run provided all other conditions stay the same.
-
-The list can be filtered based on ``backend`` and ``device_type`` keywords. The 0-based ordinal position
-of a device in the output of ``dpctl.get_devices`` corresponds to device id in the filter selector string.
-For example, ``"opencl:gpu:0"`` refers to the first device in the list returned by
-``dpctl.get_devices(backend="opencl", device_type="gpu")``. If such a list is empty device construction call
-``dpctl.SyclDevice("opencl:gpu:0")`` will raise a ``ValueError``.
-
-Device Aspects and Properties
------------------------------
-
-:class:`dpctl.SyclDevice` exposes various Python properties describing device's aspects and characteristics.
-
-`Aspects <SYCL 2020 aspects>`_ are boolean characterstics of the device.
-Property ``dev.has_aspect_fp16`` returns a boolean expression indicating whether a particular device has
-aspect ``"fp16"``, indicating whether it supposts IEEE-754 half-precision floating point type.
-
-Non-boolean characteristics as exposed as :class:`dpctl.SyclDevice` instance properties with a
-non-boolean value type. For example, ``dev.name`` returns a string with a name of the device, while
-``dev.max_compute_units`` returns a positive integer reflecting the number of parallel compute units
-available to the device.
-
-The list of available properties can be retrieved programmatically, or found in documentation page of
-:class:`dpctl.SyclDevice` class.
+`environment variables <DPCPP environment variables>`_ influencing SYCL runtime
+such as ``SYCL_DEVICE_FILTER`` or ``SYCL_DEVICE_ALLOWLIST``.
+
+.. _fig-listing-devices:
+
+.. literalinclude:: ../../../../../examples/python/device_selection.py
+    :language: python
+    :lines: 20-22, 107-131
+    :caption: Listing Available Devices
+    :linenos:
+
+A possible output for the example :ref:`fig-listing-devices` may be:
+
+.. program-output:: python ../examples/python/device_selection.py -r list_devices
+
+The example :ref:`fig-listing-devices` demonstrates the usage of
+:func:`dpctl.get_devices`. The list can be filtered based on
+:class:`dpctl.backend`` and :class:`dpctl.device_type`. The 0-based ordinal
+position of a device in the output of :func:`dpctl.get_devices` corresponds to
+the ``device id`` value in the filter selector string corresponding to the
+device. For example, ``"opencl:cpu:0"`` refers to the first device in the list
+returned by ``dpctl.get_devices(backend="opencl", device_type="cpu")``. If such
+a list is empty, device construction call ``dpctl.SyclDevice("opencl:gpu:0")``
+will raise a ``ValueError``.
+
+.. Note::
+
+    Unless the system configuration changes, the list of devices returned by
+    :func:`dpctl.get_devices` and the relative ordering of devices in the list
+    is stable for every call to the function, even across different runs of an
+    application.
+
+Device Aspects and Information Descriptors
+------------------------------------------
+
+A device can have various *aspects* and *information descriptors* that describe
+its hardware characteristics. :sycl_aspects:`Aspects <>` are boolean
+characteristics of the device, whereas
+:sycl_device_info:`information descriptors <>` are non-boolean characteristics
+that provide more verbose information about the device.
+:class:`dpctl.SyclDevice` exposes various Python properties that describe a
+device's aspects and information descriptors. For example, the property
+``has_aspect_fp16`` returns a boolean expression indicating whether a
+particular device has aspect ``"fp16"``, indicating whether it supports the
+IEEE-754 half-precision floating point type. Whereas, the ``name`` property is
+an information descriptor that returns a string with the name of the device.
+
+.. _fig-available-properties:
 
 .. code-block:: Python
+    :caption: Listing Available Device Aspects and Information Descriptors
+    :linenos:
 
     import dpctl
     import inspect
@@ -55,47 +80,56 @@ The list of available properties can be retrieved programmatically, or found in
     print(len(get_properties(dpctl.SyclDevice, "name")))
     # Output: 52
 
+The example :ref:`fig-available-properties` demonstrates a programmatic way of
+listing all the aspects and information descriptor properties in
+:class:`dpctl.SyclDevice`.
+
 .. _sec-devices-sub-devices:
 
 Sub-devices
 -----------
 
-Certain devices supporting such capability can be partitioned into multiple devices
-by calling :func:`dpctl.SyclDevice.create_sub_devices`, which returns a list of created
-sub-device instances of type :class:`dpctl.SyclDevice`. These instances can be partitioned
-further.
+It is possible for a device to be partitioned into "sub-devices". A sub-device
+represents a sub-set of the computational units within a device that are grouped
+based on some hardware criteria. For example, a two socket CPU device may be
+partitioned into two sub-devices, where each sub-device represents a separate
+:numa_domain:`NUMA domain <>`. Depending on the hardware characteristics and
+the capabilities of the SYCL runtime, a sub-device may be partitioned further.
 
-The requested partitioning is indicated with use of required ``partition`` keyword, which
-can be a positive integers (indicating equal partitioning with each sub-device having
-the requested number of parallel compute units), a list of positive integers
-(indicating the requested number of parallel compute units in each sub-device), or
-a string indicate partitioning by affinity domain (creating sub-devices sharing a common
-resource, such as certain low level cache). Use ``partition="next_partitionable"``
-to partition along the next level of architectural hierarchy.
+For devices that support partitioning, the
+:func:`dpctl.SyclDevice.create_sub_devices` can be used to create a list of
+sub-devices. The requested partitioning scheme is indicated with use of the
+required ``partition`` keyword. Several types of partitioning schemes are
+available:
 
-A sub-device's parent device can be retrived using ``dev.parent_device`` property.
-When called on a root device, ``root_dev.parent_device`` returns ``None``.
+* **Equal partitioning**
+    The partitioning scheme is specified as a list of positive integers
+    indicating a partitioning with each sub-device having the requested number
+    of parallel compute units.
 
-For non-partitioned devices, its corresponding filter selector string can be retrieved
-using ``dev.filter_string`` which returns a fully specified triplet. Method
-:func:`dpctl.SyclDevice.get_filter_string` can be used to obtain a partially
-qualified filter selector string.
+* **Affinity partitioning**
+    The partitioning scheme is specified as a string indicating an affinity
+    domain used to create sub-devices that sharing a common resource, such as
+    certain hardware cache levels.
 
-.. code-block:: Python
+.. Note::
 
-    import dpctl
-    dev = dpctl.SyclDevice()
+    Use ``partition="next_partitionable"`` to partition along the next level of
+    architectural hierarchy.
+
+The following example shows the partitioning of a CPU device into sub-devices
+using the equal partitioning scheme.
+
+.. _fig-partition-cpu:
 
-    print(dev.filter_string)
+.. literalinclude:: ../../../../../examples/python/subdevices.py
+    :language: python
+    :lines: 17, 34-59
+    :caption: Partitioning a CPU device
+    :linenos:
 
-    # The following prints fully qualified string same as dev.filter_string
-    # possible output: "opencl:cpu:0"
-    print(dev.get_filter_string())
+A possible output for the example :ref:`fig-listing-devices` may be:
 
-    # do not include backend
-    # possible output: "cpu:0"
-    print(dev.get_filter_string(include_backend=False))
+.. program-output:: python ../examples/python/subdevices.py -r subdivide_root_cpu_device
 
-    # include neither backend, nor device Type
-    # possible output: "1"
-    print(dev.get_filter_string(include_backend=False, include_device_type=False)
+.. include:: ../../../urls.rst
diff --git a/docs/docfiles/user_guides/manual/dpctl/platforms.rst b/docs/docfiles/user_guides/manual/dpctl/platforms.rst
@@ -4,12 +4,9 @@
 Platform
 ########
 
-In dpctl, the class :class:`dpctl.SyclPlatform` represents a platform and
-abstracts the `sycl::platform`_ SYCL runtime class. A platform abstracts one or
-more XPU that is connected to the host and that can be used for computation. The
-platforms queryable using dpctl depends on the device drivers that are installed
-on a system. A single driver may control multiple physical XPU, thus a platform
-may also consist of multiple XPUs.
+A platform abstracts a device driver for one or more XPU that is connected to
+a host. The :class:`dpctl.SyclPlatform` class represents a platform and
+abstracts the `sycl::platform`_ SYCL runtime class.
 
 Listing Available Platforms
 ---------------------------
@@ -20,8 +17,7 @@ example it is possible to print out metadata about a platform.
 
 .. literalinclude:: ../../../../../examples/python/lsplatform.py
     :language: python
-    :start-after: # START
-    :end-before: # END
+    :lines: 20-41
     :linenos:
 
 The example can be executed as follows:
diff --git a/docs/extlinks_gen.py b/docs/extlinks_gen.py
@@ -0,0 +1,36 @@
+#                       Data Parallel Control (dpctl)
+#
+#  Copyright 2020-2021 Intel Corporation
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+import json
+
+
+def create_extlinks():
+    """Reads a JSON file to create a dictionary of urls in the format supported
+    by the sphinx.ect.extlinks extension.
+
+    Returns:
+        dict: A dictionary that is understood by the extlinks Sphinx extension.
+
+    """
+    extlinks = {}
+
+    with open("docfiles/urls.json") as urls_json:
+        urls = json.load(urls_json)
+        for url in urls:
+            url_value = urls[url]
+            extlinks[url] = (url_value + "%s", None)
+
+    return extlinks
diff --git a/examples/python/_runner.py b/examples/python/_runner.py
@@ -55,7 +55,7 @@ def run_examples(example_description, glbls_dict):
             print("Available examples:")
             print(", ".join(fns))
         else:
-            print("No examples are availble.")
+            print("No examples are available.")
         exit(0)
     if args.run == "all":
         fns = []
diff --git a/examples/python/device_selection.py b/examples/python/device_selection.py
