Skip to content

Commit 4c077ac

Browse files
Merge pull request #1919 from IntelPython/update-from-dlpack-docs
Updated from_dlpack docstring
2 parents 295c532 + ef407d2 commit 4c077ac

File tree

1 file changed

+48
-19
lines changed

1 file changed

+48
-19
lines changed

dpctl/tensor/_dlpack.pyx

Lines changed: 48 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -965,50 +965,77 @@ cdef object _create_device(object device, object dl_device):
965965
def from_dlpack(x, /, *, device=None, copy=None):
966966
"""from_dlpack(x, /, *, device=None, copy=None)
967967
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.
970970
971971
Args:
972972
x (object):
973973
A Python object representing an array that supports
974974
``__dlpack__`` protocol.
975975
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+
987997
Default: ``None``.
998+
988999
copy (bool, optional)
9891000
Boolean indicating whether or not to copy the input.
9901001
9911002
* If ``copy`` is ``True``, the input will always be
992-
copied.
1003+
copied.
9931004
* If ``False``, a ``BufferError`` will be raised if a
994-
copy is deemed necessary.
1005+
copy is deemed necessary.
9951006
* 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.
9981009
9991010
Default: ``None``.
10001011
10011012
Returns:
1002-
usm_ndarray:
1013+
Alternative[usm_ndarray, numpy.ndarray]:
10031014
An array containing the data in ``x``. When ``copy`` is
10041015
``None`` or ``False``, this may be a view into the original
10051016
memory.
10061017
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+
10071034
Raises:
10081035
TypeError:
10091036
if ``x`` does not implement ``__dlpack__`` method
10101037
ValueError:
1011-
if the input array resides on an unsupported device
1038+
if data of the input object resides on an unsupported device
10121039
10131040
See https://dmlc.github.io/dlpack/latest/ for more details.
10141041
@@ -1031,7 +1058,9 @@ def from_dlpack(x, /, *, device=None, copy=None):
10311058
return self._array.__dlpack_device__()
10321059
10331060
C = Container(dpt.linspace(0, 100, num=20, dtype="int16"))
1061+
# create usm_ndarray view
10341062
X = dpt.from_dlpack(C)
1063+
# migrate content of the container to device of type kDLCPU
10351064
Y = dpt.from_dlpack(C, device=(dpt.DLDeviceType.kDLCPU, 0))
10361065
10371066
"""

0 commit comments

Comments
 (0)