Checking in new documentation in doc_sources/

Author: oleksandr-pavlyk

docs/doc_sources/_static/.gitignore

@@ -0,0 +1 @@
+*~

docs/doc_sources/_templates/autosummary/base.rst

@@ -0,0 +1,5 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. auto{{ objtype }}:: {{ objname }}

docs/doc_sources/_templates/autosummary/class.rst

@@ -0,0 +1,30 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+
+
+.. autoclass:: {{ name }}
+
+   {% block methods %}
+
+   {% if methods %}
+   .. rubric:: {{ _('Methods') }}
+
+   .. autosummary::
+   {% for item in methods %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Attributes') }}
+
+   .. autosummary::
+   {% for item in attributes %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}

docs/doc_sources/_templates/autosummary/elementwise.rst

@@ -0,0 +1,12 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+{% if objtype == "data" %}
+.. auto{{ objtype }}:: {{ objname }}
+    :no-value:
+{% endif %}
+
+{% if objtype == "function" %}
+.. auto{{ objtype }}:: {{ objname }}
+{% endif %}

docs/doc_sources/_templates/autosummary/module.rst

@@ -0,0 +1,60 @@
+{{ fullname | escape | underline}}
+
+.. automodule:: {{ fullname }}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Module Attributes') }}
+
+   .. autosummary::
+   {% for item in attributes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block functions %}
+   {% if functions %}
+   .. rubric:: {{ _('Functions') }}
+
+   .. autosummary::
+   {% for item in functions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block classes %}
+   {% if classes %}
+   .. rubric:: {{ _('Classes') }}
+
+   .. autosummary::
+   {% for item in classes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block exceptions %}
+   {% if exceptions %}
+   .. rubric:: {{ _('Exceptions') }}
+
+   .. autosummary::
+   {% for item in exceptions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+{% block modules %}
+{% if modules %}
+.. rubric:: Modules
+
+.. autosummary::
+   :toctree:
+   :recursive:
+{% for item in modules %}
+   {{ item }}
+{%- endfor %}
+{% endif %}
+{% endblock %}

docs/doc_sources/_templates/autosummary/usmmemory.rst

@@ -0,0 +1,32 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+
+
+.. autoclass:: {{ name }}
+
+   {% block methods %}
+
+   {% if methods %}
+   .. rubric:: {{ _('Methods') }}
+
+   .. autosummary::
+   {% for item in methods %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   :special-members: __sycl_usm_array_interface__
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Attributes') }}
+
+   .. autosummary::
+   {% for item in attributes %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}

docs/doc_sources/beginners_guides/device_info.rst

@@ -0,0 +1,59 @@
+.. _beginners_guide_device_info:
+
+Obtaining information about device
+==================================
+
+An instance of :py:class:`SyclDevice` provides access to a collection of information
+descriptors characterizing underlying ``sycl::device``.
+
+Information of Boolean nature is exposed via ``has_aspect_*`` properties.
+Other descriptions are exposed as properties of the instance.
+
+.. code-block:: python
+    :caption: Example: Obtaining information about a device
+
+    import dpctl
+
+    # create default-selected device
+    dev = dpctl.SyclDevice()
+
+    # number of compute units
+    cu = dev.max_compute_units
+    # maximal supported size of a work-group
+    max_wg = dev.max_work_group_size
+    # size of shared local memory in bytes
+    loc_mem_sz = dev.local_mem_size
+
+    # name of the device
+    dname = dev.name
+    # maximal clock frequency in MHz
+    freq = dev.max_clock_frequency
+
+
+.. currentmodule:: dpctl.utils
+
+For Intel GPU devices, additional architectural information can be access with :py:func:`intel_device_info` function:
+
+.. code-block:: python
+    :caption: Example: Intel GPU-specific information
+
+    In [1]: import dpctl, dpctl.utils
+
+    In [2]: d_gpu = dpctl.SyclDevice()
+
+    # Output for Iris Xe integerate GPU, with PCI ID 0x9a49
+    # (corresponding decimal value: 39497)
+    In [3]: dpctl.utils.intel_device_info(d_gpu)
+    Out[3]:
+    {'device_id': 39497,
+    'gpu_eu_count': 96,
+    'gpu_hw_threads_per_eu': 7,
+    'gpu_eu_simd_width': 8,
+    'gpu_slices': 1,
+    'gpu_subslices_per_slice': 12,
+    'gpu_eu_count_per_subslice': 8}
+
+Please refer to "Intel(R) Xe GPU Architecture" section of the "`oneAPI GPU Optimization Guide <gpu_opt_guide_>`_"
+for detailed explanation of these architectural descriptors.
+
+.. _gpu_opt_guide: https://www.intel.com/content/www/us/en/docs/oneapi/optimization-guide-gpu/

docs/doc_sources/beginners_guides/device_selection.rst

@@ -0,0 +1,63 @@
+.. _beginners_guide_device_selection:
+
+Device selection
+================
+
+DPC++ runtime provides a way to select a device with a highest score to for a set of selection scroring strategies.
+Amongst these are a default selector, CPU selector, GPU selector, as well as filter-string selector.
+
+Using fixed device selectors
+----------------------------
+
+:py:mod:`dpctl` exposes device selection using fixed selectors as free functions:
+
+.. currentmodule:: dpctl
+
+.. list-table::
+
+    * - :py:func:`select_default_device`
+      - :py:func:`select_gpu_device`
+    * - :py:func:`select_cpu_device`
+      - :py:func:`select_accelerator_device`
+
+Selecting device based on aspects
+---------------------------------
+
+In addition, a :py:func:`select_device_with_aspects` permits selecting a device based on aspects it is required to have:
+
+.. code-block:: python
+    :caption: Example: Selecting devices based on their aspects
+
+    import dpctl
+
+    # select a device that support float64 data type
+    dev1 = dpctl.select_device_with_aspects("fp64")
+
+    # select a device that supports atomic operations on 64-bit types
+    # in USM-shared allocations
+    dev2 = dpctl.select_device_with_aspects(
+        ["atomic64", "usm_atomic_shared_allocations"]
+    )
+
+An aspect string ``asp`` is valid if ``hasattr(dpctl.SyclDevice, "has_aspect_" + asp)`` evaluates to ``True``.
+
+Selecting device using filter selector string
+---------------------------------------------
+
+:py:class:`SyclDevice` may also be created using :ref:`filter selector string <filter_selector_string>` specified
+as argument to the class constructor:
+
+.. code-block:: python
+    :caption: Example: Creating device based on filter-selector string
+
+    import dpctl
+
+    # create any GPU device
+    dev_gpu = dpctl.SyclDevice("gpu")
+
+    # take second device GPU device in the list of GPU devices
+    # 0-based number is used
+    dev_gpu1 = dpctl.SyclDevice("gpu:1")
+
+    # create GPU device, or CPU if GPU is not available
+    dev_gpu_or_cpu = dpctl.SyclDevice("gpu,cpu")

docs/doc_sources/beginners_guides/enumerating_devices.rst

@@ -0,0 +1,109 @@
+.. _beginners_guide_enumerating_devices:
+
+Enumerating available devices
+=============================
+
+
+
+Listing platform from command-line
+-----------------------------------
+
+:py:mod:`dpctl` provides command-line interface to list available platforms:
+
+.. code-block:: bash
+    :caption: List platforms with detailed information on devices
+
+    python -m dpctl --full-list
+
+A sample output of executing such a command on a laptop:
+
+.. code-block:: text
+    :caption: Sample output of running ``python -m dpctl --full-list``
+
+    Platform  0 ::
+        Name        Intel(R) FPGA Emulation Platform for OpenCL(TM)
+        Version     OpenCL 1.2 Intel(R) FPGA SDK for OpenCL(TM), Version 20.3
+        Vendor      Intel(R) Corporation
+        Backend     opencl
+        Num Devices 1
+        # 0
+            Name                Intel(R) FPGA Emulation Device
+            Version             2024.17.2.0.22_223154
+            Filter string       opencl:accelerator:0
+    Platform  1 ::
+        Name        Intel(R) OpenCL
+        Version     OpenCL 3.0 LINUX
+        Vendor      Intel(R) Corporation
+        Backend     opencl
+        Num Devices 1
+        # 0
+            Name                11th Gen Intel(R) Core(TM) i7-1185G7 @ 3.00GHz
+            Version             2024.17.2.0.22_223154
+            Filter string       opencl:cpu:0
+    Platform  2 ::
+        Name        Intel(R) OpenCL Graphics
+        Version     OpenCL 3.0
+        Vendor      Intel(R) Corporation
+        Backend     opencl
+        Num Devices 1
+        # 0
+            Name                Intel(R) Graphics [0x9a49]
+            Version             23.52.28202.26
+            Filter string       opencl:gpu:0
+    Platform  3 ::
+        Name        Intel(R) Level-Zero
+        Version     1.3
+        Vendor      Intel(R) Corporation
+        Backend     ext_oneapi_level_zero
+        Num Devices 1
+        # 0
+            Name                Intel(R) Graphics [0x9a49]
+            Version             1.3.28202
+            Filter string       level_zero:gpu:0
+
+.. currentmodule:: dpctl
+
+Command-line interface is useful for verifying that drivers are installed correctly.
+It is implemented using :py:func:`lsplatform` function.
+
+.. note::
+    The output on your particular heterogeneous system may vary, depending on available hardware and drivers installed.
+
+Listing devices programmatically
+--------------------------------
+
+Devices can also be discovered programmatically, either by using :py:func:`lsplatform` to :py:func:`print`` the listing or
+by using :py:func:`get_devices` to obtain a list of :py:class:`SyclDevice` objects suitable for further processing.
+
+.. code-block:: python
+    :caption: Example: Obtaining list of available devices for processing
+
+    import dpctl
+
+    # get all available devices
+    devices = dpctl.get_devices()
+
+    # get memory of each in GB
+    {d.name: d.global_mem_size // (1024 ** 3) for d in devices}
+
+
+Interaction with DPC++ environment variables
+--------------------------------------------
+
+:py:mod:`dpctl` relies on DPC++ runtime for device discovery and is :ref:`subject <beginners_guide_env_variables>` to
+environment variables that influence behavior of the runtime.
+Setting ``ONEAPI_DEVICE_SELECTOR`` environment variable (see the `list of environment variables <dpcpp_env_vars_>`_
+recognized by oneAPI DPC++ runtime for additional details) may restrict the set of devices visible to DPC++ runtime, and hence to :py:mod:`dpctl`
+
+.. _dpcpp_env_vars: https://intel.github.io/llvm-docs/EnvironmentVariables.html
+
+.. code-block:: bash
+    :caption: Example: Setting ``ONEAPI_DEVICE_SELECTOR=*:cpu`` renders GPU devices unavailable even if they are present
+
+    export ONEAPI_DEVICE_SELECTOR=*:cpu
+    # would only show CPU device
+    python -m dpctl -f
+
+    unset ONEAPI_DEVICE_SELECTOR
+    # all available devices are available now
+    python -m dpctl -f