dpctl.tensor.from_dlpack

dpctl.tensor.from_dlpack(x, /, *, device=None, copy=None)

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

Parameters:

  • x (object) – A Python object representing an array that supports __dlpack__ protocol.

  • device (Optional[str, dpctl.SyclDevice, dpctl.SyclQueue, dpctl.tensor.Device, tuple([enum.IntEnum, int])])) –

    Device where the output array is to be placed. device keyword values can be:

    • None

      The data remains on the same device.

    • oneAPI filter selector string

      SYCL device selected by filter selector string.

    • dpctl.SyclDevice

      explicit SYCL device that must correspond to a non-partitioned SYCL device.

    • dpctl.SyclQueue

      implies SYCL device targeted by the SYCL queue.

    • dpctl.tensor.Device

      implies SYCL device device.sycl_queue. The Device object is obtained via 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 dpctl.tensor.DLDeviceType device types are "kDLCPU" and "kDLOneAPI".

    Default: None.

  • copy (bool, optional) –

    Boolean indicating whether or not to copy the input.

    • If copy is True, the input will always be copied.

    • If False, a BufferError will be raised if a copy is deemed necessary.

    • If None, a copy will be made only if deemed necessary, otherwise, the existing memory buffer will be reused.

    Default: None.

Returns:

An array containing the data in x. When copy is None or False, this may be a view into the original memory.

The type of the returned object depends on where the data backing up input object x resides. If it resides in a USM allocation on a SYCL device, the type dpctl.tensor.usm_ndarray is returned, otherwise if it resides on "kDLCPU" device the type is numpy.ndarray, and otherwise an exception is raised.

Note

If the return type is dpctl.tensor.usm_ndarray, the associated SYCL queue is derived from the device keyword. When device keyword value has type dpctl.SyclQueue, the explicit queue instance is used, when device keyword value has type dpctl.tensor.Device, the device.sycl_queue is used. In all other cases, the cached SYCL queue corresponding to the implied SYCL device is used.

Return type:

Alternative[usm_ndarray, numpy.ndarray]

Raises:

  • TypeError – if x does not implement __dlpack__ method

  • ValueError – if data of the input object resides on an unsupported device

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

Example:
import dpctl
import dpctl.tensor as dpt

class Container:
    "Helper class implementing `__dlpack__` protocol"
    def __init__(self, array):
        self._array = array

    def __dlpack__(self, stream=None):
        return self._array.__dlpack__(stream=stream)

    def __dlpack_device__(self):
        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))