numba_dpex.utils.array_utils module

This module provides utilities to interact with USM memory.

numba_dpex.utils.array_utils.as_usm_obj(obj, queue=None, usm_type='shared', copy=True)

Determine and return a SYCL device accesible object.

We try to determine if the provided object defines a valid __sycl_usm_array_interface__ dictionary. If not, we create a USM memory of usm_type and try to copy the data obj holds. Only numpy.ndarray is supported currently as obj if the object is not already allocated using USM.

Args:

obj: Object to be tested and data copied from. usm_type: USM type used in case obj is not already allocated using USM. queue (dpctl.SyclQueue): SYCL queue to be used to allocate USM

memory in case obj is not already USM allocated.

copy (bool): Flag to determine if we copy data from obj.

Returns:

A Python object allocated using USM memory.

Raises:
TypeError:

  1. If obj is not allocated on USM memory or is not of type numpy.ndarray, TypeError is raised.

  2. If queue is not of type dpctl.SyclQueue.

ValueError:

  1. In case obj is not USM allocated, users need to pass the SYCL queue to be used for creating new memory. ValuieError is raised if queue argument is not provided.

  2. If usm_type is not valid.

  3. If dtype of the passed ndarray(obj) is not supported.

numba_dpex.utils.array_utils.copy_from_numpy_to_usm_obj(usm_allocated, obj)

Copy from supported objects to USM allocated data.

This function copies the data of a supported Python type (only numpy.ndarray is supported at this point) into object that defines a __sycl_usm_array_interface__ attribute. For more information please refer to the specification of __sycl_usm_array_interface__: https://github.com/IntelPython/dpctl/wiki/Zero-copy-data-exchange-using-SYCL-USM#sycl-usm-array-interface

Args:
usm_allocated: An object that should define a

__sycl_usm_array_interface__ dictionary. A TypeError is thrown if the object does not have such an attribute.

obj (numpy.ndarray): Numpy ndarray, the data will be copied into.

Raises:

TypeError: If any argument is not of permitted type. ValueError:

  1. If size of data does not match.

  2. If obj is not C-contiguous.

numba_dpex.utils.array_utils.copy_to_numpy_from_usm_obj(usm_allocated, obj)

Copy from USM allocated data to supported objects.

Args:
usm_allocated: An object that should define a

__sycl_usm_array_interface__ dictionary. A TypeError is thrown if the object does not have such an attribute.

obj (numpy.ndarray): Numpy ndarray, the data will be copied into.

Raises:

TypeError: If any argument is not of permitted type. ValueError: If size of data does not match.

numba_dpex.utils.array_utils.get_info_from_suai(obj)

Convenience function to gather information from __sycl_usm_array_interface__.

Args:

obj: Array with SUAI attribute.

Returns:

usm_mem: USM memory object. total_size: Total number of items in the array. shape: Shape of the array. ndim: Total number of dimensions. itemsize: Size of each item. strides: Stride of the array. dtype: Dtype of the array.

numba_dpex.utils.array_utils.has_usm_memory(obj)

Determine and return a SYCL device accesible object.

as_usm_memory() converts Python object with __sycl_usm_array_interface__ property to one of MemoryUSMShared, MemoryUSMDevice, or MemoryUSMHost instances. For more information please refer: https://github.com/IntelPython/dpctl/blob/0.8.0/dpctl/memory/_memory.pyx#L673

Args:

obj: Object to be tested and data copied from.

Returns:

A Python object allocated using USM memory if argument is already allocated using USM (zero-copy), None otherwise.