Support `dpctl.asarray()`

[PokhodenkoSA]

Please make dpctl to support asarray() function which converts containers with __sycl_usm_array_interface__ to dpctl native container.

[oleksandr-pavlyk]

It needs to be in the same namespace as the usm_ndarray, i.e. dpctl.tensor.asarray.

[oleksandr-pavlyk]

Specs for asarray:

• in array-API spec: asarray
• in NumPy: numpy.asarray

With #646, the dpctl.tensor.asarray has the following signature:

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

The obj is an object to be converted to an array. asarray supports:

• an instance of dpctl.tensor.usm_ndarray
• an object with __sycl_usm_array_interface__
• an instance of numpy.ndarray
• Python scalar, a (possibly nested) sequence of Python scalars
• an object supporting Python buffer protocol

N.B.: presently sequences of usm_ndarray objects are not supported, nor are sequences mixing objects with SYCL allocations and objects with host allocations.

obj that does not fall into any of the above categories, but implements __dlpack__ protocol could be imported with dpctl.tensor.from_dlpack function (array-API spec).

device and sycl_queue keywords are exclusive (use one or another) unless they represent the same queue.

device keyword can be None, a valid filter selector string, non-partitioned dpctl.SyclDevice, or dpctl.SyclQueue instance, or the object output by usm_ary.device.

sycl_queue can be either None, or instance of dpctl.SyclQueue. In the case when device=None and sycl_queue=None, array will be created on device selected by SYCL's default_selector.

usm_type can be None, "device", "shared", or "host". usm_type=None is understood as keep the usm_type in case when obj is an instance of usm_ndarray, or has __sycl_usm_array_interface__, or use usm_type="device" otherwise.

[PokhodenkoSA]

@oleksandr-pavlyk
Thank you for the description.
I will integrate it in numba-dppy (IntelPython/numba-dpex#634).
It looks like a documentation. Is it a part of documentation already?