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

See also

Available array data types

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)}\).