dpctl.tensor.usm_ndarray

class dpctl.tensor.usm_ndarray(shape, dtype=None, strides=None, buffer='device', offset=0, order='C', buffer_ctor_kwargs=dict(), array_namespace=None)

An array object represents a multidimensional tensor of numeric elements stored in a USM allocation on a SYCL device.

Arg:

shape (int, tuple):

Shape of the array to be created.

dtype (str, dtype):

Array data type, i.e. the type of array elements. If dtype has the value None, it is determined by default floating point type supported by target device. The supported types are

• bool

  boolean type

• int8, int16, int32, int64,

  signed integer types

• uint8, uint16, uint32, uint64,

  unsigned integer types

• float16

  half-precision floating type, supported if target device’s property has_aspect_fp16 is True

• float32, complex64

  single-precision real and complex floating types

• float64, complex128

  double-precision real and complex floating types, supported if target device’s property has_aspect_fp64 is True.

Default: None.

strides (tuple, optional):

Strides of the array to be created in elements. If strides has the value None, it is determined by the shape of the array and the requested order. Default: None.

buffer (str, object, optional):

A string corresponding to the type of USM allocation to make, or a Python object representing a USM memory allocation, i.e. dpctl.memory.MemoryUSMDevice, dpctl.memory.MemoryUSMShared, or dpctl.memory.MemoryUSMHost. Recognized strings are "device", "shared", or "host". Additional arguments to the USM memory alloctors can be passed in a dictionary specified via buffer_ctor_kwrds keyword parameter. Default: "device".

offset (int, optional):

Offset of the array element with all zero indexes relative to the start of the provided buffer in elements. The argument is ignored if the buffer value is a string and the memory is allocated by the constructor. Default: 0.

order ({“C”, “F”}, optional):

The memory layout of the array when constructing using a new allocation. Value "C" corresponds to C-contiguous, or row-major memory layout, while value "F" corresponds to F-contiguous, or column-major layout. Default: "C".

buffer_ctor_kwargs (dict, optional):

Dictionary with keyword parameters to use when creating a new USM memory allocation. See dpctl.memory.MemoryUSMShared for supported keyword arguments.

array_namespace (module, optional):

Array namespace module associated with this array. Default: None.

buffer can be "shared", "host", "device" to allocate new device memory by calling respective constructor with the specified buffer_ctor_kwrds; buffer can be an instance of dpctl.memory.MemoryUSMShared, dpctl.memory.MemoryUSMDevice, or dpctl.memory.MemoryUSMHost; buffer can also be another dpctl.tensor.usm_ndarray instance, in which case its underlying MemoryUSM* buffer is used.

Attributes:

T	Returns transposed array for 2D array, raises ValueError otherwise.
device	Returns data-API object representing residence of the array data.
dtype	Returns NumPy's dtype corresponding to the type of the array elements.
flags	Returns dpctl.tensor._flags object.
imag	Returns imaginary component for arrays with complex data-types and returns zero array for all other data-types.
itemsize	Size of array element in bytes.
mT	Returns array where the last two dimensions are transposed.
nbytes	Total bytes consumed by the elements of the array.
ndim	Gives the number of indices needed to address elements of this array.
real	Returns real component for arrays with complex data-types and returns itself for all other data-types.
shape	Elements of the shape tuple give the lengths of the respective array dimensions.
size	Number of elements in the array.
strides	Returns memory displacement in array elements, upon unit change of respective index.
sycl_context	Returns dpctl.SyclContext object to which USM data is bound.
sycl_device	Returns dpctl.SyclDevice object on which USM data was allocated.
sycl_queue	Returns dpctl.SyclQueue object associated with USM data.
usm_data	Gives USM memory object underlying usm_array instance.
usm_type	USM type of underlying memory.

Public methods:

to_device(target_device)

Transfers this array to specified target device.

Private methods:

_set_namespace(mod)

Sets array namespace to given module mod.

Attributes

usm_ndarray.T

Returns transposed array for 2D array, raises ValueError otherwise.

usm_ndarray._byte_bounds

Returns a 2-tuple with pointers to the end-points of the array

usm_ndarray._element_offset

Returns the offset of the zero-index element of the array, in elements, relative to the start of memory allocation

usm_ndarray._pointer

Returns USM pointer for data allocation encoded as integer

usm_ndarray.device

Returns data-API object representing residence of the array data.

usm_ndarray.dtype

Returns NumPy’s dtype corresponding to the type of the array elements.

usm_ndarray.flags

Returns dpctl.tensor._flags object.

usm_ndarray.imag

Returns imaginary component for arrays with complex data-types and returns zero array for all other data-types.

usm_ndarray.itemsize

Size of array element in bytes.

usm_ndarray.mT

Returns array where the last two dimensions are transposed.

usm_ndarray.nbytes

Total bytes consumed by the elements of the array.

usm_ndarray.ndim

Gives the number of indices needed to address elements of this array.

usm_ndarray.real

Returns real component for arrays with complex data-types and returns itself for all other data-types.

usm_ndarray.shape

Elements of the shape tuple give the lengths of the respective array dimensions.

usm_ndarray.size

Number of elements in the array.

usm_ndarray.strides

Returns memory displacement in array elements, upon unit change of respective index.

E.g. for strides (s1, s2, s3) and multi-index (i1, i2, i3)

a[i1, i2, i3] == (&a[0,0,0])[ s1*s1 + s2*i2 + s3*i3]

usm_ndarray.sycl_context

Returns dpctl.SyclContext object to which USM data is bound.

usm_ndarray.sycl_device

Returns dpctl.SyclDevice object on which USM data was allocated.

usm_ndarray.sycl_queue

Returns dpctl.SyclQueue object associated with USM data.

usm_ndarray.usm_data

Gives USM memory object underlying usm_array instance.

usm_ndarray.usm_type

USM type of underlying memory. Can be "device", "shared", or "host".

See: https://docs.oneapi.com/versions/latest/dpcpp/iface/usm.html

Public methods

dpctl.tensor.usm_ndarray.to_device(target_device)

Transfers this array to specified target device.

Example:

import dpctl
import dpctl.tensor as dpt

x = dpt.full(10**6, 2, dtype="int64")
q_prof = dpctl.SyclQueue(
    x.sycl_device, property="enable_profiling")
# return a view with profile-enabled queue
y = x.to_device(q_prof)
timer = dpctl.SyclTimer()
with timer(q_prof):
    z = y * y
print(timer.dt)

Parameters:

target_device (object) – Array API concept of target device. It can be a oneAPI filter selector string, an instance of dpctl.SyclDevice corresponding to a non-partitioned SYCL device, an instance of dpctl.SyclQueue, or a dpctl.tensor.Device object returned by dpctl.tensor.usm_array.device.

Returns:

A view if data copy is not required, and a copy otherwise. If copying is required, it is done by copying from the original allocation device to the host, followed by copying from host to the target device.

Return type:

usm_ndarray

Private methods

dpctl.tensor.usm_ndarray._set_namespace(self, mod)

Sets array namespace to given module mod.