Feature/asarray

[oleksandr-pavlyk]

Closes #640 . Adds dpctl.tensor.asarray and dpctl.tensor.empty.

dpctl.tensor.empty(shape, dtype="f8", order="C", device=None, usm_type="device", sycl_queue=None)

Create an empty dpctl.tensor.usm_ndarray object of requested dtype and based on request USM allocation type on specified array-API device, and of requested layout specified by order keyword.

Instead of specifying array-API device keyword, sycl_queue can be used to specify the target of allocation instead.

dpctl.tensor.asarray(obj, dtype=None, copy=None, order="K", device=None, usm_type=None, sycl_queue=None)

Converts Python object obj to usm_ndarray object. Support objects are:

1. usm_ndarray instances
2. numpy.ndarray instances
3. Python objects exposing __sycl_usm_array_interface__.
4. Python sequences of Python scalars

[coveralls]

Coverage increased (+0.4%) to 74.788% when pulling 12d6693 on feature/asarray into 749be95 on master.

[reazulhoque]

@oleksandr-pavlyk Do we have a test where we are testing the equality of shape of new array created using asarray and the shape is multi-dimensional? Can you please point me to it?

[oleksandr-pavlyk]

Is this good enough?

In [1]: import dpctl, dpctl.tensor as dpt

In [2]: dpt.asarray([[1, 2, 3], [4,5,6]], dtype="d").shape
Out[2]: (2, 3)

In [3]: X = dpt.asarray([[1, 2, 3], [4,5,6]], dtype="d", device="cpu", usm_type="device")

In [4]: Y = dpt.asarray(X, device="gpu", usm_type="shared")

In [5]: X.shape == Y.shape
Out[5]: True

In [6]: X.sycl_device
Out[6]: <dpctl.SyclDevice [backend_type.opencl, device_type.cpu,  Intel(R) Core(TM) i7-10710U CPU @ 1.10GHz] at 0x7f8836ab93b0>

In [7]: Y.sycl_device
Out[7]: <dpctl.SyclDevice [backend_type.level_zero, device_type.gpu,  Intel(R) UHD Graphics [0x9bca]] at 0x7f8858a49870>

[PokhodenkoSA]

The description of this PR has more documentation than functions docstrings you created in code.

[densmirn]

Seems ValueError is more suitable here.

[oleksandr-pavlyk]

I disagree, in my mind the check is asking if copy is of bool type, or of None type.

[github-actions]

View rendered docs @ https://intelpython.github.io/dpctl/pulls/646/index.html

[oleksandr-pavlyk]

@diptorupd @densmirn @reazulhoque @Alexander-Makaryev @PokhodenkoSA

This PR is now feature complete and changed from draft to "ready for review".
I added docstrings, added CHANGELOG, added tests (guides by coverage).

I cleaned up commit history to reduce it from 32 commits to 10 commit,
I do not consider it a good use of our time to split this PR into any number of smaller PRs.

[oleksandr-pavlyk]

The description of this PR has more documentation than functions docstrings you created in code.

I added docstrings.

[reazulhoque]

Tested manually with DuckUSMArray to make sure integration with Numba-dppy is working correctly.

[github-actions]

Deleted rendered PR docs from intelpython.github.com/dpctl, latest should be updated shortly. 🤞