Multi-Dimensional Array (ndarray)

dpnp.ndarray is the DPNP counterpart of NumPy numpy.ndarray.

For the basic concept of ndarrays, please refer to the NumPy documentation.

dpnp.ndarray

alias of dpnp_array

dpnp.dpnp_array.dpnp_array

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

Constructing arrays

New arrays can be constructed using the routines detailed in Array Creation Routines, and also by using the low-level dpnp.ndarray constructor:

dpnp.ndarray

alias of dpnp_array

Indexing arrays

Arrays can be indexed using an extended Python slicing syntax, array[selection].

See also

Indexing routines.

Array attributes

Array attributes reflect information that is intrinsic to the array itself. Generally, accessing an array through its attributes allows you to get and sometimes set intrinsic properties of the array without creating a new array. The exposed attributes are the core parts of an array and only some of them can be reset meaningfully without creating a new array. Information on each attribute is given below.

Memory layout

The following attributes contain information about the memory layout of the array:

dpnp.ndarray.flags

Return information about the memory layout of the array.

dpnp.ndarray.shape

Tuple of array dimensions.

dpnp.ndarray.strides

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

dpnp.ndarray.ndim

Return the number of dimensions of an array.

dpnp.ndarray.data

Python object pointing to the start of USM memory allocation with the array's data.

dpnp.ndarray.size

Number of elements in the array.

dpnp.ndarray.itemsize

Size of one array element in bytes.

dpnp.ndarray.nbytes

Total bytes consumed by the elements of the array.

dpnp.ndarray.device

Return dpctl.tensor.Device object representing residence of the array data.

dpnp.ndarray.sycl_context

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

dpnp.ndarray.sycl_device

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

dpnp.ndarray.sycl_queue

Return dpctl.SyclQueue object associated with USM data.

dpnp.ndarray.usm_type

USM type of underlying memory.

Data type

The data type object associated with the array can be found in the dtype attribute:

dpnp.ndarray.dtype

Return NumPy's dtype corresponding to the type of the array elements.

Other attributes

dpnp.ndarray.T

View of the transposed array.

dpnp.ndarray.mT

View of the matrix transposed array.

dpnp.ndarray.real

The real part of the array.

dpnp.ndarray.imag

The imaginary part of the array.

dpnp.ndarray.flat

Return a flat iterator, or set a flattened version of self to value.

Special attributes

dpnp.ndarray.__sycl_usm_array_interface__

Give __sycl_usm_array_interface__ dictionary describing the array.

dpnp.ndarray.__usm_ndarray__

Property to support __usm_ndarray__ protocol.

Array methods

An dpnp.ndarray object has many methods which operate on or with the array in some fashion, typically returning an array result. These methods are briefly explained below. (Each method's docstring has a more complete description.)

For the following methods there are also corresponding functions in dpnp: all, any, argmax, argmin, argpartition, argsort, choose, clip, compress, copy, cumprod, cumsum, diagonal, imag, max, mean, min, nonzero, partition, prod, put, ravel, real, repeat, reshape, round, searchsorted, sort, squeeze, std, sum, swapaxes, take, trace, transpose, var.

Array conversion

dpnp.ndarray.item

Copy an element of an array to a standard Python scalar and return it.

dpnp.ndarray.astype

Copy the array with data type casting.

dpnp.ndarray.copy

Return a copy of the array.

dpnp.ndarray.view

New view of array with the same data.

dpnp.ndarray.fill

Fill the array with a scalar value.

dpnp.ndarray.get_array

Get dpctl.tensor.usm_ndarray object.

Shape manipulation

For reshape, resize, and transpose, the single tuple argument may be replaced with n integers which will be interpreted as an n-tuple.

dpnp.ndarray.reshape

Return an array containing the same data with a new shape.

dpnp.ndarray.transpose

Return a view of the array with axes transposed.

dpnp.ndarray.swapaxes

Interchange two axes of an array.

dpnp.ndarray.flatten

Return a copy of the array collapsed into one dimension.

dpnp.ndarray.ravel

Return a contiguous flattened array.

dpnp.ndarray.squeeze

Remove single-dimensional entries from the shape of an array.

Item selection and manipulation

For array methods that take an axis keyword, it defaults to None. If axis is None, then the array is treated as a 1-D array. Any other value for axis represents the dimension along which the operation should proceed.

dpnp.ndarray.take

Take elements from an array along an axis.

dpnp.ndarray.put

Put values of an array into another array along a given axis.

dpnp.ndarray.repeat

Repeat elements of an array.

dpnp.ndarray.choose

Use an array as index array to construct a new array from a set of choices.

dpnp.ndarray.sort

Sort an array in-place.

dpnp.ndarray.argsort

Return an ndarray of indices that sort the array along the specified axis.

dpnp.ndarray.partition

Return a partitioned copy of an array.

dpnp.ndarray.searchsorted

Find indices where elements of v should be inserted in a to maintain order.

dpnp.ndarray.nonzero

Return the indices of the elements that are non-zero.

dpnp.ndarray.compress

Select slices of an array along a given axis.

dpnp.ndarray.diagonal

Return specified diagonals.

Calculation

Many of these methods take an argument named axis. In such cases,

  • If axis is None (the default), the array is treated as a 1-D array and the operation is performed over the entire array. This behavior is also the default if self is a 0-dimensional array.

  • If axis is an integer, then the operation is done over the given axis (for each 1-D subarray that can be created along the given axis).

The parameter dtype specifies the data type over which a reduction operation (like summing) should take place. The default reduce data type is the same as the data type of self. To avoid overflow, it can be useful to perform the reduction using a larger data type.

For several methods, an optional out argument can also be provided and the result will be placed into the output array given. The out argument must be an dpnp.ndarray and have the same number of elements as the result array. It can have a different data type in which case casting will be performed.

dpnp.ndarray.max

Return the maximum along an axis.

dpnp.ndarray.argmax

Return array of indices of the maximum values along the given axis.

dpnp.ndarray.min

Return the minimum along a given axis.

dpnp.ndarray.argmin

Return array of indices to the minimum values along the given axis.

dpnp.ndarray.clip

Clip (limit) the values in an array.

dpnp.ndarray.conj

Complex-conjugate all elements.

dpnp.ndarray.conjugate

Return the complex conjugate, element-wise.

dpnp.ndarray.round

Return array with each element rounded to the given number of decimals.

dpnp.ndarray.trace

Return the sum along diagonals of the array.

dpnp.ndarray.sum

Return the sum along a given axis.

dpnp.ndarray.cumsum

Return the cumulative sum of the elements along the given axis.

dpnp.ndarray.mean

Return the average of the array elements.

dpnp.ndarray.var

Return the variance of the array elements, along given axis.

dpnp.ndarray.std

Return the standard deviation of the array elements, along given axis.

dpnp.ndarray.prod

Return the prod along a given axis.

dpnp.ndarray.cumprod

Return the cumulative product of the elements along the given axis.

dpnp.ndarray.all

Return True if all elements evaluate to True.

dpnp.ndarray.any

Return True if any of the elements of a evaluate to True.

Arithmetic, matrix multiplication, and comparison operations

Arithmetic and comparison operations on dpnp.ndarrays are defined as element-wise operations, and generally yield dpnp.ndarray objects as results.

Each of the arithmetic operations (+, -, *, /, //, %, divmod(), ** or pow(), <<, >>, &, ^, |, ~) and the comparisons (==, <, >, <=, >=, !=) is equivalent to the corresponding universal function (or ufunc for short) in DPNP. For more information, see the section on Universal Functions.

Comparison operators:

dpnp.ndarray.__lt__

Return \(\text{self < value}\).

dpnp.ndarray.__le__

Return \(\text{self <= value}\).

dpnp.ndarray.__gt__

Return \(\text{self > value}\).

dpnp.ndarray.__ge__

Return \(\text{self >= value}\).

dpnp.ndarray.__eq__

Return \(\text{self == value}\).

dpnp.ndarray.__ne__

Return \(\text{self != value}\).

Truth value of an array (bool()):

dpnp.ndarray.__bool__

True if self else False.

Note

Truth-value testing of an array invokes dpnp.ndarray.__bool__(), which raises an error if the number of elements in the array is not 1, because the truth value of such arrays is ambiguous. Use .any() and .all() instead to be clear about what is meant in such cases. (If you wish to check for whether an array is empty, use for example .size > 0.)

Unary operations:

dpnp.ndarray.__neg__

Return \(\text{-self}\).

dpnp.ndarray.__pos__

Return \(\text{+self}\).

dpnp.ndarray.__abs__

Return \(|\text{self}|\).

dpnp.ndarray.__invert__

Return \(\text{~self}\).

Arithmetic:

dpnp.ndarray.__add__

Return \(\text{self + value}\).

dpnp.ndarray.__sub__

Return \(\text{self - value}\).

dpnp.ndarray.__mul__

Return \(\text{self * value}\).

dpnp.ndarray.__truediv__

Return \(\text{self / value}\).

dpnp.ndarray.__floordiv__

Return \(\text{self // value}\).

dpnp.ndarray.__mod__

Return \(\text{self % value}\).

dpnp.ndarray.__pow__

Return \(\text{self ** value}\).

dpnp.ndarray.__lshift__

Return \(\text{self << value}\).

dpnp.ndarray.__rshift__

Return \(\text{self >> value}\).

dpnp.ndarray.__and__

Return \(\text{self & value}\).

dpnp.ndarray.__or__

Return \(\text{self | value}\).

dpnp.ndarray.__xor__

Return \(\text{self ^ value}\).

Arithmetic, reflected:

dpnp.ndarray.__radd__

Return \(\text{value + self}\).

dpnp.ndarray.__rsub__

Return \(\text{value - self}\).

dpnp.ndarray.__rmul__

Return \(\text{value * self}\).

dpnp.ndarray.__rtruediv__

Return \(\text{value / self}\).

dpnp.ndarray.__rfloordiv__

Return \(\text{value // self}\).

dpnp.ndarray.__rmod__

Return \(\text{value % self}\).

dpnp.ndarray.__rpow__

Return \(\text{value ** self}\).

dpnp.ndarray.__rlshift__

Return \(\text{value << self}\).

dpnp.ndarray.__rrshift__

Return \(\text{value >> self}\).

dpnp.ndarray.__rand__

Return \(\text{value & self}\).

dpnp.ndarray.__ror__

Return \(\text{value | self}\).

dpnp.ndarray.__rxor__

Return \(\text{value ^ self}\).

Arithmetic, in-place:

dpnp.ndarray.__iadd__

Return \(\text{self += value}\).

dpnp.ndarray.__isub__

Return \(\text{self -= value}\).

dpnp.ndarray.__imul__

Return \(\text{self *= value}\).

dpnp.ndarray.__itruediv__

Return \(\text{self /= value}\).

dpnp.ndarray.__ifloordiv__

Return \(\text{self //= value}\).

dpnp.ndarray.__imod__

Return \(\text{self %= value}\).

dpnp.ndarray.__ipow__

Return \(\text{self **= value}\).

dpnp.ndarray.__ilshift__

Return \(\text{self <<= value}\).

dpnp.ndarray.__irshift__

Return \(\text{self >>= value}\).

dpnp.ndarray.__iand__

Return \(\text{self &= value}\).

dpnp.ndarray.__ior__

Return \(\text{self |= value}\).

dpnp.ndarray.__ixor__

Return \(\text{self ^= value}\).

Matrix Multiplication:

dpnp.ndarray.__matmul__

Return \(\text{self @ value}\).

dpnp.ndarray.__rmatmul__

Return \(\text{value @ self}\).

dpnp.ndarray.__imatmul__

Return \(\text{self @= value}\).

Special methods

For standard library functions:

dpnp.ndarray.__copy__

Used if copy.copy() is called on an array.

Basic customization:

dpnp.ndarray.__new__

dpnp.ndarray.__array__

NumPy's array protocol method to disallow implicit conversion.

dpnp.ndarray.__array_namespace__

Return array namespace, member functions of which implement data API.

dpnp.ndarray.__dlpack__

Produce DLPack capsule.

dpnp.ndarray.__dlpack_device__

Give a tuple (device_type, device_id) corresponding to DLDevice entry in DLTensor in DLPack protocol.

Container customization: (see Indexing)

dpnp.ndarray.__len__

Return \(\text{len(self)}\).

dpnp.ndarray.__iter__

Return \(\text{iter(self)}\).

dpnp.ndarray.__getitem__

Return \(\text{self[key]}\).

dpnp.ndarray.__setitem__

Set \(\text{self[key]}\) to a value.

dpnp.ndarray.__contains__

Return \(\text{value in self}\).

Conversion; the operations int(), float(), complex() and operator.index(). They work only on arrays that have one element in them and return the appropriate scalar.

dpnp.ndarray.__index__

Convert a zero-dimensional array to a Python int object.

dpnp.ndarray.__int__

Convert a zero-dimensional array to a Python int object.

dpnp.ndarray.__float__

Convert a zero-dimensional array to a Python float object.

dpnp.ndarray.__complex__

Convert a zero-dimensional array to a Python complex object.

String representations:

dpnp.ndarray.__str__

Return \(\text{str(self)}\).

dpnp.ndarray.__repr__

Return \(\text{repr(self)}\).