Feature/dlpack (#682)

* Added tensor._dlpack extension, vendored dlpack header

Added dlpack's license file in include/dlpack/

Added note in README.md about the location of the origin LICENSE file
from which the copy was made

Add _dlpack.pyx to flake exception file

Implemented to_dlpack_capsule/from_dlpack_capsule functions

* Implemented usm_ndarray.__dlpack__, usm_ndarray.__dlpack_device__

* Implemented from_dlpack(array)

* Exported dpctl.tensor.from_dlpack

* DLManagedTensor lifetime management implemented per array-API specs

1. The pycapsule destructor only calls DLManagedTensor.deleter is the name is "dltensor"
2. Code consuming the DLPack capsule renamed the capsule (to avoid destructor calling
   the deleter) and instead creates an internal object to do that and uses
   that internal object as the base of _Memory object

`from_dlpack_capsule` function should handle NULL data field
For zero-elements arrays in DLPack, allocate 1 element

Proper support for strides added.

Expanded docstring of `dpctl.tensor.from_dlpack`

* Adding test_usm_ndarray_dlpack

Test should anticipate that dlpack roundtripping changes
bool dtype to uint8

Adding test for `from_dlpack` input validation

* dlpack support noted in changelog

* Addressed PR feedback

1. Added docstrings
2. Exported DLPackCreationError in `_dlpack.pxd`
3. Added validation in `__dlpack_device__` to raise an error
   if device_id came back -1 (not-found)
4. `to_dlpack_capsule(usm_ary)` raises DLPackCreationError
   if the array context is not the default context (the one created
   in dpctl.SyclQueue(dev) call)

* Make sure that dpctl/tensor/include/dlpack is included in the layout

* fixed typo in docstring

* Addressed docstrings/formatting PR feedback

* Applied consistent style for references

Author: oleksandr-pavlyk

.flake8

@@ -23,6 +23,7 @@ per-file-ignores =
     dpctl/memory/_memory.pyx: E999, E225, E226, E227
     dpctl/program/_program.pyx: E999, E225, E226, E227
     dpctl/tensor/_usmarray.pyx: E999, E225, E226, E227
+    dpctl/tensor/_dlpack.pyx: E999, E225, E226, E227
     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

CHANGELOG.md

@@ -8,6 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 - `dpctl.tensor.asarray`, `dpctl.tensor.empty` implemented (#646).
+- `dpctl.tensor.usm_ndarray` adds support for DLPack protocol. `dpctl.tensor.from_dlpack` implemented (#682).
 
 ### Changed
 - dpctl-capi is now renamed to `libsyclinterface` (#666).

MANIFEST.in

@@ -1,5 +1,6 @@
 include versioneer.py
 recursive-include dpctl/include *.h
+recursive-include dpctl/tensor/include *
 recursive-include dpctl *.pxd
 include dpctl/_sycl_context.h
 include dpctl/_sycl_context_api.h

dpctl/tensor/__init__.py

@@ -34,6 +34,7 @@
 from dpctl.tensor._copy_utils import copy_to_numpy as asnumpy
 from dpctl.tensor._copy_utils import copy_to_numpy as to_numpy
 from dpctl.tensor._ctors import asarray, empty
+from dpctl.tensor._dlpack import from_dlpack
 from dpctl.tensor._reshape import reshape
 from dpctl.tensor._usmarray import usm_ndarray
 
@@ -47,4 +48,5 @@
     "from_numpy",
     "to_numpy",
     "asnumpy",
+    "from_dlpack",
 ]

dpctl/tensor/_dlpack.pxd

@@ -0,0 +1,41 @@
+#                       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.
+
+# distutils: language = c++
+# cython: language_level=3
+# cython: linetrace=True
+
+from ._usmarray cimport usm_ndarray
+
+
+cdef extern from './include/dlpack/dlpack.h' nogil:
+    int device_CPU 'kDLCPU'
+    int device_oneAPI 'kDLOneAPI'
+    int device_OpenCL 'kDLOpenCL'
+
+
+cpdef object to_dlpack_capsule(usm_ndarray array) except +
+cpdef usm_ndarray from_dlpack_capsule(object dltensor) except +
+
+cpdef from_dlpack(array)
+
+cdef class DLPackCreationError(Exception):
+    """
+    A DLPackCreateError exception is raised when constructing
+    DLPack capsule from `usm_ndarray` based on a USM allocation
+    on a partitioned SYCL device.
+    """
+    pass