Merge pull request #1108 from IntelPython/doc-cleanup-pass

Examples clean-up

Author: oleksandr-pavlyk

.flake8

@@ -29,7 +29,6 @@ per-file-ignores =
     dpctl/tensor/numpy_usm_shared.py: F821
     dpctl/tests/_cython_api.pyx: E999, E225, E227, E402
     dpctl/utils/_compute_follows_data.pyx: E999, E225, E227
-    examples/cython/sycl_buffer/_buffer_example.pyx: E999, E225, E402
-    examples/cython/sycl_direct_linkage/_buffer_example.pyx: E999, E225, E402
-    examples/cython/usm_memory/blackscholes.pyx: E999, E225, E226, E402
+    examples/cython/sycl_buffer/syclbuffer/_buffer_example.pyx: E999, E225, E402
+    examples/cython/usm_memory/blackscholes/blackscholes.pyx: E999, E225, E226, E402
     examples/cython/use_dpctl_sycl/use_dpctl_sycl/_cython_api.pyx: E999, E225, E226, E402

.github/workflows/conda-package.yml

@@ -423,31 +423,25 @@ jobs:
           CHANNELS="-c $GITHUB_WORKSPACE/channel -c dppy/label/dev -c intel -c main --override-channels"
           export PACKAGE_VERSION=$(python -c "${VER_SCRIPT1} ${VER_SCRIPT2}")
           conda install -n examples -y ${CHANNELS} dpctl=${PACKAGE_VERSION} dpnp">=0.10.1" || exit 1
-      - name: Build and run examples with native extensions
+      - name: Build and run examples of pybind11 extensions
         shell: bash -l {0}
         run: |
           source $CONDA/etc/profile.d/conda.sh
           export OCL_ICD_FILENAMES=libintelocl.so
           conda activate examples
           conda list
           cd examples/pybind11
-          for d in $(ls)
+          for d in $(find . -maxdepth 1 -type d -not -path ".")
           do
             pushd $d
             export MKLROOT=${CONDA_PREFIX}
             export TBBROOT=${CONDA_PREFIX}
             conda activate --stack build_env
-            if [ -e CMakeLists.txt ]
-            then
-               CC=icx CXX=icpx python setup.py build_ext --inplace -G Ninja -- \
-                    -DTBB_LIBRARY_DIR=${TBBROOT}/lib \
-                    -DMKL_LIBRARY_DIR=${MKLROOT}/lib \
-                    -DMKL_INCLUDE_DIR=${MKLROOT}/include \
-                    -DTBB_INCLUDE_DIR=${TBBROOT}/include || exit 1
-            else
-               CC=icx CXX=icpx CFLAGS="-fsycl" LDSHARED="dpcpp -shared" \
-                    python setup.py build_ext --inplace || exit 1
-            fi
+            CC=icx CXX=icpx python setup.py build_ext --inplace -G Ninja -- \
+                -DTBB_LIBRARY_DIR=${TBBROOT}/lib \
+                -DMKL_LIBRARY_DIR=${MKLROOT}/lib \
+                -DMKL_INCLUDE_DIR=${MKLROOT}/include \
+                -DTBB_INCLUDE_DIR=${TBBROOT}/include || exit 1
             conda deactivate
             if [ -e tests ]
             then
@@ -457,24 +451,32 @@ jobs:
             fi
             popd
           done
-          cd ../cython
-          for d in $(ls)
+      - name: Build and run examples of Cython extensions
+        shell: bash -l {0}
+        run: |
+          source $CONDA/etc/profile.d/conda.sh
+          export OCL_ICD_FILENAMES=libintelocl.so
+          conda activate examples
+          conda list
+          cd examples/cython
+          for d in $(find . -maxdepth 1 -type d -not -path ".")
           do
             pushd $d
             conda activate --stack build_env
-            CC=dpcpp CXX=dpcpp LDSHARED="dpcpp -shared" \
-                   python setup.py build_ext --inplace || exit 1
+            python setup.py build_ext --inplace || exit 1
             conda deactivate
-            if [ -e tests ]
-            then
-               LD_LIBRARY_PATH=${CONDA_PREFIX}/lib python -m pytest tests || exit 1
-            else
-               LD_LIBRARY_PATH=${CONDA_PREFIX}/lib python run.py || exit 1
-            fi
+            python -m pytest tests || exit 1
             popd
           done
-          cd ../c
-          for d in $(ls)
+      - name: Build and run examples of C-extensions
+        shell: bash -l {0}
+        run: |
+          source $CONDA/etc/profile.d/conda.sh
+          export OCL_ICD_FILENAMES=libintelocl.so
+          conda activate examples
+          conda list
+          cd examples/c
+          for d in $(find . -maxdepth 1 -type d -not -path ".")
           do
             pushd $d
             conda activate --stack build_env

README.md

@@ -19,7 +19,7 @@ The compute kernel can be a code:
 * that is part of a library, such as oneMKL
 
 The `dpctl` library is built upon the [SYCL
-standard](https://www.khronos.org/sycl/). It also implements Python
+standard](https://www.khronos.org/sycl/). It implements Python
 bindings for a subset of the standard [runtime
 classes](https://www.khronos.org/registry/SYCL/specs/sycl-2020/html/sycl-2020.html#_sycl_runtime_classes) that allow users to:
 * query platforms
@@ -57,7 +57,7 @@ To get the library from the latest oneAPI release, follow the
 instructions from Intel(R) [oneAPI installation
 guide](https://www.intel.com/content/www/us/en/developer/articles/guide/installation-guide-for-oneapi-toolkits.html).
 
-> **NOTE:** You need to install the Intel(R) oneAPI Basekit to get
+> **NOTE:** You need to install the Intel(R) oneAPI AI Analytics Tookit to get
 >IDP and `dpctl`.
 
 
@@ -85,42 +85,38 @@ To try out the current master, install it from our
 development channel on Anaconda cloud:
 
 ```bash
-conda install dpctl -c dppy\label\dev
+conda install dpctl -c dppy/label/dev
 ```
 
 # Building
 
 Refer to our [Documentation](https://intelpython.github.io/dpctl) for more information on
 setting up a development environment and building `dpctl` from the source.
 
-# Running Examples
 
-Find our examples [here](examples).
+# Examples
 
-To run these examples, use:
+Our examples are located in the [examples/](examples) folder and are organized in sub-folders. Examples
+in the [Python/](examples/python) folder demonstrate how to inspect the heterogeneous platform,
+select a device, create an execution queue, and how to control device memory allocation and
+execution placement.
 
-```bash
-for script in `ls examples/python/`;
-    do echo "executing ${script}";
-    python examples/python/${script};
-done
-```
-
-##  Cython extensions
-See examples of building Cython extensions with DPC++ compiler that interoperates
-with `dpctl` in the [cython folder](examples\cython).
+Examples in [Cython/](examples/cython), [C/](examples/c), and [Pybind11](examples/pybind11) folders
+demonstrate creation of SYCL-powered native Python extensions. Please refer to each folder's README
+document for directions on how to build and use each example.
 
-To build these examples, run:
-```bash
-CC=icx CXX=dpcpp python setup.py build_ext --inplace
-```
-To execute extensions, refer to the `run.py` script in each folder.
 
 # Running Tests
 
-Tests are located [here](dpctl/tests).
+Tests are located in folder [dpctl/tests](dpctl/tests).
 
 To run the tests, use:
 ```bash
 pytest --pyargs dpctl
 ```
+
+Running full test suite requires working C++ compiler. To run the test suite without one, use:
+
+```bash
+pytest --pyargs dpctl -k "not test_cython_api"
+```

examples/cython/sycl_direct_linkage/run.py renamed to dpctl/tensor/__init__.pxd

@@ -1,6 +1,6 @@
 #                      Data Parallel Control (dpctl)
 #
-# Copyright 2020-2022 Intel Corporation
+# Copyright 2020-2023 Intel Corporation
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -14,13 +14,11 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-import numpy as np
-import syclbuffer_naive as sb
+""" This file declares the extension types and functions for the Cython API
+    implemented in _usmarray.pyx file.
+"""
 
-X = np.random.randn(20, 10)
+# distutils: language = c++
+# cython: language_level=3
 
-# compute column-wise total with NumPy's own host code
-print(X.sum(axis=0))
-
-# compute column-wise total with SYCL extension
-print(sb.columnwise_total(X))
+from dpctl.tensor._usmarray cimport *

examples/README.md

@@ -0,0 +1,48 @@
+# Examples of using `dpctl`
+
+The `dpctl` is a foundational package facilitating use of [SYCL](sycl) to extend Python's reach to heterogeneous systems.
+
+## Python
+
+The `dpctl` provides Python API to SYCL runtime permitting user to
+inspect the heterogeneous [platform],
+[select](device_seelection) amongst available devices,
+query [properties](device_descriptors) of created devices,
+and construct [queues] to specify execution placement of offloaded computation.
+
+Additionally, `dpctl.tensor` submodule allows to create ND-arrays on devices and manipulate them using `dpctl.tensor` library of array computation operations specified in [Python Array API standard](array_api).
+
+Examples of this functionality are located in the [python](python) folder.
+
+## Cython
+
+The `dpctl` integrates with [Cython], a native extension generator, to facilitate building
+SYCL-powered Python extensions.
+
+Examples of Python extensions written using Cython are located in the [cython](cython) folder.
+
+## Pybind11
+
+Since [SYCL](sycl) is based on C++, [pybind11] is a natural tool of choice to author SYCL-powered
+Python extensions. The `dpctl` provides `dpctl4pybind11.hpp` integration header to provide natural
+mapping between SYCL C++ classes and `dpctl` Python types.
+
+Examples of Python extensions created with `pybind11` are located in the [pybind11](pybind11) folder.
+
+## C
+
+The `dpctl` implements `DPCTLSyclInterface` C library and C-API to work with Python objects and types
+implemented in `dpctl`. Use integration headers `dpctl_sycl_interface.h` and `dpctl_capi.h` to access
+this functionality.
+
+Examples of Python extensions created using C are located in [c](c) folder.
+
+
+[platform]: https://intelpython.github.io/dpctl/latest/docfiles/user_guides/manual/dpctl/platforms.html
+[device_selection]: https://intelpython.github.io/dpctl/latest/docfiles/user_guides/manual/dpctl/device_selection.html
+[device_descriptors]: https://intelpython.github.io/dpctl/latest/docfiles/user_guides/manual/dpctl/devices.html#device-aspects-and-information-descriptors
+[queues]: https://intelpython.github.io/dpctl/latest/docfiles/user_guides/manual/dpctl/queues.html
+[array_api]: https://data-apis.org/array-api/
+[sycl]: https://registry.khronos.org/SYCL/
+[Cython]: https://cython.org/
+[pybind11]: https://pybind11.readthedocs.io

examples/c/README.md

@@ -0,0 +1,8 @@
+# Examples C-based Python extensions using `dpctl`
+
+The `dpctl` implements `DPCTLSyclInterface` C library as well as provides C-API to work with Python objects
+and types implemented in `dpctl`. Use integration headers `dpctl_sycl_interface.h` and `dpctl_capi.h` to access
+this functionality.
+
+Use `python -m dpctl --includes` to get include compiler options and `python -m dpctl --library` to get linking options to link
+to `SyclInterface` library.

examples/c/py_sycl_ls/README.md

@@ -0,0 +1,19 @@
+# Python module to enumerate SYCL devices
+
+## Building
+
+```bash
+python setup.py build_ext --inplace
+```
+
+## Testing
+
+```
+pytest -m tests
+```
+
+## Running
+
+```
+python -m py_sycl_ls
+```

examples/c/py_sycl_ls/setup.py

@@ -15,7 +15,6 @@
 # limitations under the License.
 
 import os.path
-import sysconfig
 
 from setuptools import Extension, setup
 
@@ -41,7 +40,6 @@
             ],
             include_dirs=[
                 dpctl.get_include(),
-                os.path.join(sysconfig.get_paths()["include"], ".."),
             ],
             library_dirs=[
                 os.path.join(dpctl.get_include(), ".."),

examples/c/py_sycl_ls/src/py_sycl-ls.c

@@ -27,9 +27,7 @@
 // clang-format off
 #include "Python.h"
 #include "dpctl_capi.h"
-#include "syclinterface/dpctl_sycl_platform_interface.h"
-#include "syclinterface/dpctl_sycl_platform_manager.h"
-#include "syclinterface/dpctl_utils.h"
+#include "dpctl_sycl_interface.h"
 // clang-format on
 
 PyObject *sycl_ls(PyObject *self_unused, PyObject *args)

examples/cython/README.md

@@ -0,0 +1,9 @@
+# Examples of data-parallel Python extensions written in Cython
+
+The `dpctl` package provides Cython definition files for types it defines.
+
+Use `cimport dpctl as c_dpctl`, `cimport dpctl.memory as c_dpm`, or `cimport dpctl.tensor as c_dpt`
+to use these definitions.
+
+Cython definition fille `dpctl.sycl` provides incomplete definitions of core SYCL runtime classes as
+well as conversion routine between `SyclInterface` reference types and SYCL runtime classes.