@@ -965,50 +965,77 @@ cdef object _create_device(object device, object dl_device):
965
965
def from_dlpack (x , /, *, device = None , copy = None ):
966
966
""" from_dlpack(x, /, *, device=None, copy=None)
967
967
968
- Constructs :class:`dpctl.tensor.usm_ndarray` instance from a Python
969
- object ``x`` that implements ``__dlpack__`` protocol.
968
+ Constructs :class:`dpctl.tensor.usm_ndarray` or :class:`numpy.ndarray` instance
969
+ from a Python object ``x`` that implements ``__dlpack__`` protocol.
970
970
971
971
Args:
972
972
x (object):
973
973
A Python object representing an array that supports
974
974
``__dlpack__`` protocol.
975
975
device (Optional[str, :class:`dpctl.SyclDevice`, :class:`dpctl.SyclQueue`, :class:`dpctl.tensor.Device`, tuple([:class:`enum.IntEnum`, int])])):
976
- Array API concept of a device where the output array is to be placed.
977
- ``device`` can be ``None``, a oneAPI filter selector
978
- string, an instance of :class:`dpctl.SyclDevice` corresponding to
979
- a non-partitioned SYCL device, an instance of
980
- :class:`dpctl.SyclQueue`, a :class:`dpctl.tensor.Device` object
981
- returned by :attr:`dpctl.tensor.usm_ndarray.device`, or a
982
- 2-tuple matching the format of the output of the ``__dlpack_device__``
983
- method, an integer enumerator representing the device type followed by
984
- an integer representing the index of the device. The only supported
985
- :class:`dpctl.tensor.DLDeviceType` types are "kDLCPU" and
986
- "kDLOneAPI".
976
+ Device where the output array is to be placed. ``device`` keyword values can be:
977
+
978
+ * ``None``
979
+ The data remains on the same device.
980
+ * oneAPI filter selector string
981
+ SYCL device selected by :ref:`filter selector string <filter_selector_string>`.
982
+ * :class:`dpctl.SyclDevice`
983
+ explicit SYCL device that must correspond to
984
+ a non-partitioned SYCL device.
985
+ * :class:`dpctl.SyclQueue`
986
+ implies SYCL device targeted by the SYCL queue.
987
+ * :class:`dpctl.tensor.Device`
988
+ implies SYCL device `device.sycl_queue`. The `Device` object
989
+ is obtained via :attr:`dpctl.tensor.usm_ndarray.device`.
990
+ * ``(device_type, device_id)``
991
+ 2-tuple matching the format of the output of the ``__dlpack_device__``
992
+ method: an integer enumerator representing the device type followed by
993
+ an integer representing the index of the device.
994
+ The only supported :class:`dpctl.tensor.DLDeviceType` device types
995
+ are ``"kDLCPU"`` and ``"kDLOneAPI"``.
996
+
987
997
Default: ``None``.
998
+
988
999
copy (bool, optional)
989
1000
Boolean indicating whether or not to copy the input.
990
1001
991
1002
* If ``copy`` is ``True``, the input will always be
992
- copied.
1003
+ copied.
993
1004
* If ``False``, a ``BufferError`` will be raised if a
994
- copy is deemed necessary.
1005
+ copy is deemed necessary.
995
1006
* If ``None``, a copy will be made only if deemed
996
- necessary, otherwise, the existing memory buffer will
997
- be reused.
1007
+ necessary, otherwise, the existing memory buffer will
1008
+ be reused.
998
1009
999
1010
Default: ``None``.
1000
1011
1001
1012
Returns:
1002
- usm_ndarray:
1013
+ Alternative[ usm_ndarray, numpy.ndarray] :
1003
1014
An array containing the data in ``x``. When ``copy`` is
1004
1015
``None`` or ``False``, this may be a view into the original
1005
1016
memory.
1006
1017
1018
+ The type of the returned object
1019
+ depends on where the data backing up input object ``x`` resides.
1020
+ If it resides in a USM allocation on a SYCL device, the
1021
+ type :class:`dpctl.tensor.usm_ndarray` is returned, otherwise if it resides
1022
+ on ``"kDLCPU"`` device the type is :class:`numpy.ndarray`, and otherwise
1023
+ an exception is raised.
1024
+
1025
+ .. note::
1026
+
1027
+ If the return type is :class:`dpctl.tensor.usm_ndarray`, the associated
1028
+ SYCL queue is derived from the ``device`` keyword. When ``device``
1029
+ keyword value has type :class:`dpctl.SyclQueue`, the explicit queue
1030
+ instance is used, when ``device`` keyword value has type :class:`dpctl.tensor.Device`,
1031
+ the ``device.sycl_queue`` is used. In all other cases, the cached
1032
+ SYCL queue corresponding to the implied SYCL device is used.
1033
+
1007
1034
Raises:
1008
1035
TypeError:
1009
1036
if ``x`` does not implement ``__dlpack__`` method
1010
1037
ValueError:
1011
- if the input array resides on an unsupported device
1038
+ if data of the input object resides on an unsupported device
1012
1039
1013
1040
See https://dmlc.github.io/dlpack/latest/ for more details.
1014
1041
@@ -1031,7 +1058,9 @@ def from_dlpack(x, /, *, device=None, copy=None):
1031
1058
return self._array.__dlpack_device__()
1032
1059
1033
1060
C = Container(dpt.linspace(0, 100, num=20, dtype="int16"))
1061
+ # create usm_ndarray view
1034
1062
X = dpt.from_dlpack(C)
1063
+ # migrate content of the container to device of type kDLCPU
1035
1064
Y = dpt.from_dlpack(C, device=(dpt.DLDeviceType.kDLCPU, 0))
1036
1065
1037
1066
"""
0 commit comments