dpnp.from_dlpack

dpnp.from_dlpack(x, /, *, device=None, copy=None)[source]

Constructs dpnp.ndarray or numpy.ndarray instance from a Python object x that implements __dlpack__ protocol.

For full documentation refer to numpy.from_dlpack.

Parameters:

  • x (object) -- A Python object representing an array that implements the __dlpack__ and __dlpack_device__ methods.

  • device ({None, string, tuple, device}, optional) --

    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 dpnp.DLDeviceType device types are "kDLCPU" and "kDLOneAPI".

    Default: None.

  • copy ({bool, None}, 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:

out -- 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 dpnp.ndarray is returned, otherwise if it resides on "kDLCPU" device the type is numpy.ndarray, and otherwise an exception is raised.

Return type:

{dpnp.ndarray, numpy.ndarray}

Raises:

  • TypeError -- if obj does not implement __dlpack__ method

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

Notes

If the return type is dpnp.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.

Examples

>>> import dpnp as np
>>> import numpy
>>> x = numpy.arange(10)
>>> # create a view of the numpy array "x" in dpnp:
>>> y = np.from_dlpack(x)