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 accessible 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. ValueError 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.has_usm_memory(obj)

Determine and return a SYCL device accessible 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.