Added examples/README.md, and more readme files to sub-directories

Also added `dpctl/tensor/__init__.pxd` so that one can do `cimport dpctl.tensor`.
Used that in `cython/usm_memory` example.

Author: oleksandr-pavlyk

dpctl/tensor/__init__.pxd

@@ -0,0 +1,24 @@
+#                      Data Parallel Control (dpctl)
+#
+# 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.
+# 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.
+
+""" This file declares the extension types and functions for the Cython API
+    implemented in _usmarray.pyx file.
+"""
+
+# distutils: language = c++
+# cython: language_level=3
+
+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/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.

examples/cython/usm_memory/blackscholes/blackscholes.pyx

@@ -21,7 +21,7 @@ cimport numpy as cnp
 from cython cimport floating
 
 cimport dpctl as c_dpctl
-cimport dpctl.tensor._usmarray as c_dpt
+cimport dpctl.tensor as c_dpt
 from dpctl.sycl cimport queue as dpcpp_queue
 from dpctl.sycl cimport unwrap_queue
 

examples/pybind11/README.md

@@ -0,0 +1 @@
+# Examples of data-parallel Python extensions written with pybind11