Skip to content

Updated from_dlpack docstring #1919

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
oleksandr-pavlyk merged 2 commits into from
Dec 3, 2024
Merged

Updated from_dlpack docstring #1919

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
34296a8
Updated from_dlpack docstring
oleksandr-pavlyk Dec 3, 2024
ef407d2
Fixed typos pointed in PR feedback
oleksandr-pavlyk Dec 3, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Next Next commit
Updated from_dlpack docstring 
Closes gh-1917.

The change to docstring documents that `tensor.from_dlpack` may return
numpy.ndarray or tensor.usm_ndarray and stipulates when that may happen.
  • Loading branch information
@oleksandr-pavlyk
oleksandr-pavlyk committed Dec 3, 2024
commit 34296a82cb48cd0e313950cf3f6de19e407ff895
65 changes: 46 additions & 19 deletions dpctl/tensor/_dlpack.pyx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -965,41 +965,66 @@ cdef object _create_device(object device, object dl_device):
def from_dlpack(x, /, *, device=None, copy=None):
Comment thread
oleksandr-pavlyk marked this conversation as resolved.
"""from_dlpack(x, /, *, device=None, copy=None)

Constructs :class:`dpctl.tensor.usm_ndarray` instance from a Python
object ``x`` that implements ``__dlpack__`` protocol.
Constructs :class:`dpctl.tensor.usm_ndarray` or :class:`numpy.ndarray` instance
from a Python object ``x`` that implements ``__dlpack__`` protocol.

Args:
x (object):
A Python object representing an array that supports
``__dlpack__`` protocol.
device (Optional[str, :class:`dpctl.SyclDevice`, :class:`dpctl.SyclQueue`, :class:`dpctl.tensor.Device`, tuple([:class:`enum.IntEnum`, int])])):
Array API concept of a device where the output array is to be placed.
``device`` can be ``None``, a oneAPI filter selector
string, an instance of :class:`dpctl.SyclDevice` corresponding to
a non-partitioned SYCL device, an instance of
:class:`dpctl.SyclQueue`, a :class:`dpctl.tensor.Device` object
returned by :attr:`dpctl.tensor.usm_ndarray.device`, or a
2-tuple matching the format of the output of the ``__dlpack_device__``
method, an integer enumerator representing the device type followed by
an integer representing the index of the device. The only supported
:class:`dpctl.tensor.DLDeviceType` types are "kDLCPU" and
"kDLOneAPI".
Device where the output array is to be placed. ``device`` keyword values can be:

* ``None``
The data remains on the same device. If the data backing up
input object ``x`` resides on ``"kDLCPU"`` device, the return
type would be :class:`numpy.ndarray`, otherwise the return
type would be :class:`dpctl.tensor.usm_ndarray`.
Comment thread
oleksandr-pavlyk marked this conversation as resolved.
Outdated
* oneAPI filter selector string
SYCL device selected by :ref:`filter selector string <filter_selector_string>`.
* :class:`dpctl.SyclDevice`
explicit SYCL device that must correspond to
a non-partitioned SYCL device.
* :class:`dpctl.SyclQueue`
implies SYCL device targeted by the SYCL queue.
* :class:`dpctl.tensor.Device`
implies SYCL device `device.sycl_queue`. The `Device` object
is obtained via :attr:`dpctl.tensor.usm_ndarray.device`.
* ``(device_type, device_id)``
2-tuple matching the format of the output of the ``__dlpack_device__``
method: an integer enumerator representing the device type followed by
an integer representing the index of the device.
The only supported :class:`dpctl.tensor.DLDeviceType` device types
are ``"kDLCPU"`` and ``"kDLOneAPI"``. If ``"kDLCPU"`` requested, the
output type is :class:`numpy.ndarray`, otherwise it is
:class:`dpctl.tensor.usm_ndarray`.

Default: ``None``.

.. note::

If the return type if :class:`dpctl.tensor.usm_ndarray`, the associated
Comment thread
oleksandr-pavlyk marked this conversation as resolved.
Outdated
SYCL queue is derived from the ``device`` keyword. When ``device``
keyword value has type :class:`dpctl.SyclQueue`, the explicit queue
instance is used, when ``device`` keyword value has type :class:`dpctl.tensor.Device`,
the ``device.sycl_queue`` is used. In all other cases, the cached
SYCL queue corresponding the implied SYCL device is used.
Comment thread
oleksandr-pavlyk marked this conversation as resolved.
Outdated

copy (bool, optional)
Boolean indicating whether or not to copy the input.

* If ``copy`` is ``True``, the input will always be
copied.
copied.
* If ``False``, a ``BufferError`` will be raised if a
copy is deemed necessary.
copy is deemed necessary.
* If ``None``, a copy will be made only if deemed
necessary, otherwise, the existing memory buffer will
be reused.
necessary, otherwise, the existing memory buffer will
be reused.

Default: ``None``.

Returns:
usm_ndarray:
Alternative[usm_ndarray, numpy.ndarray]:
An array containing the data in ``x``. When ``copy`` is
``None`` or ``False``, this may be a view into the original
memory.
Expand All @@ -1008,7 +1033,7 @@ def from_dlpack(x, /, *, device=None, copy=None):
TypeError:
if ``x`` does not implement ``__dlpack__`` method
ValueError:
if the input array resides on an unsupported device
if data of the input object resides on an unsupported device

See https://dmlc.github.io/dlpack/latest/ for more details.

Expand All @@ -1031,7 +1056,9 @@ def from_dlpack(x, /, *, device=None, copy=None):
return self._array.__dlpack_device__()

C = Container(dpt.linspace(0, 100, num=20, dtype="int16"))
# create usm_ndarray view
X = dpt.from_dlpack(C)
# migrate content of the container to device of type kDLCPU
Y = dpt.from_dlpack(C, device=(dpt.DLDeviceType.kDLCPU, 0))

"""
Expand Down