dpnp.dpnp_array.dpnp_array

class dpnp.dpnp_array.dpnp_array(shape, dtype=None, buffer=None, offset=0, strides=None, order='C', device=None, usm_type='device', sycl_queue=None)

Multi-dimensional array object.

This is a wrapper around dpctl.tensor.usm_ndarray that provides methods to be compliant with original NumPy.

Methods

__getitem__(key)

Return self[key].

__setitem__(key, val)

Set self[key] to value.

__len__()

Return len(self).

all(axis=None, out=None, keepdims=False, *, where=True)

Returns True if all elements evaluate to True.

Refer to dpnp.all for full documentation.

See also

dpnp.all

equivalent function

any(axis=None, out=None, keepdims=False, *, where=True)

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

Refer to dpnp.any for full documentation.

See also

dpnp.any

equivalent function

argmax(axis=None, out=None, *, keepdims=False)

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

Refer to dpnp.argmax for full documentation.

argmin(axis=None, out=None, *, keepdims=False)

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

Refer to dpnp.argmin for full documentation.

argsort(axis=-1, kind=None, order=None)

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

Refer to dpnp.argsort for full documentation.

asnumpy()

Copy content of the array into numpy.ndarray instance of the same shape and data type.

Returns:

An instance of numpy.ndarray populated with the array content.

Return type:

numpy.ndarray

astype(dtype, order='K', casting='unsafe', subok=True, copy=True, device=None)

Copy the array with data type casting.

Refer to dpnp.astype for full documentation.

Parameters:

• x1 ({dpnp.ndarray, usm_ndarray}) -- Array data type casting.

• dtype (dtype) -- Target data type.

• order ({"C", "F", "A", "K"}, optional) -- Row-major (C-style) or column-major (Fortran-style) order. When order is 'A', it uses 'F' if a is column-major and uses 'C' otherwise. And when order is 'K', it keeps strides as closely as possible.

• copy ({bool}, optional) -- If it is False and no cast happens, then this method returns the array itself. Otherwise, a copy is returned.

• casting ({'no', 'equiv', 'safe', 'same_kind', 'unsafe'}, optional) --

  Controls what kind of data casting may occur. Defaults to 'unsafe' for backwards compatibility.

  • 'no' means the data types should not be cast at all.

  • 'equiv' means only byte-order changes are allowed.

  • 'safe' means only casts which can preserve values are allowed.

  • 'same_kind' means only safe casts or casts within a kind, like float64 to float32, are allowed.

  • 'unsafe' means any data conversions may be done.

• copy -- By default, astype always returns a newly allocated array. If this is set to False, and the dtype, order, and subok requirements are satisfied, the input array is returned instead of a copy.

• device ({None, string, SyclDevice, SyclQueue}, optional) -- An array API concept of device where the output array is created. The device can be None (the default), an OneAPI filter selector string, an instance of dpctl.SyclDevice corresponding to a non-partitioned SYCL device, an instance of dpctl.SyclQueue, or a Device object returned by dpnp.dpnp_array.dpnp_array.device property. Default: None.

Returns:

arr_t -- Unless copy is False and the other conditions for returning the input array are satisfied, arr_t is a new array of the same shape as the input array, with dtype, order given by dtype, order.

Return type:

dpnp.ndarray

Limitations

Parameter subok is supported with default value. Otherwise NotImplementedError exception will be raised.

Examples

>>> import dpnp as np
>>> x = np.array([1, 2, 2.5])
>>> x
array([1. , 2. , 2.5])
>>> x.astype(int)
array([1, 2, 2])

choose(choices, out=None, mode='raise')

Construct an array from an index array and a set of arrays to choose from.

Refer to dpnp.choose for full documentation.

clip(min=None, max=None, out=None, **kwargs)

Clip (limit) the values in an array.

Refer to dpnp.clip for full documentation.

conj()

Complex-conjugate all elements.

Refer to dpnp.conjugate for full documentation.

conjugate()

Return the complex conjugate, element-wise.

Refer to dpnp.conjugate for full documentation.

copy(order='C', device=None, usm_type=None, sycl_queue=None)

Return a copy of the array.

Refer to dpnp.copy for full documentation.

Parameters:

• order ({"C", "F", "A", "K"}, optional) -- Memory layout of the newly output array. Default: "C".

• device ({None, string, SyclDevice, SyclQueue}, optional) -- An array API concept of device where the output array is created. The device can be None (the default), an OneAPI filter selector string, an instance of dpctl.SyclDevice corresponding to a non-partitioned SYCL device, an instance of dpctl.SyclQueue, or a Device object returned by dpnp.dpnp_array.dpnp_array.device property. Default: None.

• usm_type ({None, "device", "shared", "host"}, optional) -- The type of SYCL USM allocation for the output array. Default: None.

• sycl_queue ({None, SyclQueue}, optional) -- A SYCL queue to use for output array allocation and copying. The sycl_queue can be passed as None (the default), which means to get the SYCL queue from device keyword if present or to use a default queue. Default: None.

Returns:

out -- A copy of the array.

Return type:

dpnp.ndarray

See also

dpnp.copy

Similar function with different default behavior

dpnp.copyto

Copies values from one array to another.

Notes

This function is the preferred method for creating an array copy. The function dpnp.copy() is similar, but it defaults to using order "K".

Examples

>>> import dpnp as np
>>> x = np.array([[1, 2, 3], [4, 5, 6]], order='F')
>>> y = x.copy()
>>> x.fill(0)

>>> x
array([[0, 0, 0],
       [0, 0, 0]])

>>> y
array([[1, 2, 3],
       [4, 5, 6]])

>>> y.flags['C_CONTIGUOUS']
True

cumprod(axis=None, dtype=None, out=None)

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

Refer to dpnp.cumprod for full documentation.

cumsum(axis=None, dtype=None, out=None)

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

Refer to dpnp.cumsum for full documentation.

diagonal(offset=0, axis1=0, axis2=1)

Return specified diagonals.

Refer to dpnp.diagonal for full documentation.

See also

dpnp.diagonal

Equivalent function.

Examples

>>> import dpnp as np
>>> a = np.arange(4).reshape(2,2)
>>> a.diagonal()
array([0, 3])

dot(b, out=None)

Dot product of two arrays.

Refer to dpnp.dot for full documentation.

Examples

>>> import dpnp as np
>>> a = np.eye(2)
>>> b = np.ones((2, 2)) * 2
>>> a.dot(b)
array([[2., 2.],
       [2., 2.]])

This array method can be conveniently chained:

>>> a.dot(b).dot(b)
array([[8., 8.],
       [8., 8.]])

fill(value)

Fill the array with a scalar value.

For full documentation refer to numpy.ndarray.fill.

Parameters:

value ({dpnp.ndarray, usm_ndarray, scalar}) -- All elements of a will be assigned this value.

Examples

>>> import dpnp as np
>>> a = np.array([1, 2])
>>> a.fill(0)
>>> a
array([0, 0])
>>> a = np.empty(2)
>>> a.fill(1)
>>> a
array([1.,  1.])

flatten(order='C')

Return a copy of the array collapsed into one dimension.

For full documentation refer to numpy.ndarray.flatten.

Parameters:

order ({"C", "F"}, optional) --

Read the elements using this index order, and place the elements into the reshaped array using this index order.

• "C" means to read / write the elements using C-like index order, with the last axis index changing fastest, back to the first axis index changing slowest.

• "F" means to read / write the elements using Fortran-like index order, with the first index changing fastest, and the last index changing slowest.

Default: "C".

Returns:

out -- A copy of the input array, flattened to one dimension.

Return type:

dpnp.ndarray

See also

dpnp.ravel

Return a flattened array.

dpnp.flat

A 1-D flat iterator over the array.

Examples

>>> import dpnp as np
>>> a = np.array([[1, 2], [3, 4]])
>>> a.flatten()
array([1, 2, 3, 4])
>>> a.flatten("F")
array([1, 3, 2, 4])

get_array()

Get usm_ndarray object.

item(*args)

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

For full documentation refer to numpy.ndarray.item.

Parameters:

*args ({none, int, tuple of ints}) --

• none: in this case, the method only works for arrays with one element (a.size == 1), which element is copied into a standard Python scalar object and returned.

• int: this argument is interpreted as a flat index into the array, specifying which element to copy and return.

• tuple of ints: functions as does a single int argument, except that the argument is interpreted as an nd-index into the array.

Returns:

out -- A copy of the specified element of the array as a suitable Python scalar.

Return type:

Standard Python scalar object

Examples

>>> import dpnp as np
>>> np.random.seed(123)
>>> x = np.random.randint(9, size=(3, 3))
>>> x
array([[0, 0, 7],
       [6, 6, 6],
       [0, 7, 1]])
>>> x.item(3)
6
>>> x.item(7)
7
>>> x.item((0, 1))
0
>>> x.item((2, 2))
1

>>> x = np.array(5)
>>> x.item()
5

max(axis=None, out=None, keepdims=False, initial=None, where=True)

Return the maximum along an axis.

Refer to dpnp.max for full documentation.

mean(axis=None, dtype=None, out=None, keepdims=False, *, where=True)

Returns the average of the array elements.

Refer to dpnp.mean for full documentation.

min(axis=None, out=None, keepdims=False, initial=None, where=True)

Return the minimum along a given axis.

Refer to dpnp.min for full documentation.

nonzero()

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

Refer to dpnp.nonzero for full documentation.

partition(kth, axis=-1, kind='introselect', order=None)

Return a partitioned copy of an array.

Rearranges the elements in the array in such a way that the value of the element in kth position is in the position it would be in a sorted array.

All elements smaller than the kth element are moved before this element and all equal or greater are moved behind it. The ordering of the elements in the two partitions is undefined.

Refer to dpnp.partition for full documentation.

See also

dpnp.partition

Return a partitioned copy of an array.

Examples

>>> import dpnp as np
>>> a = np.array([3, 4, 2, 1])
>>> a.partition(3)
>>> a
array([1, 2, 3, 4])

prod(axis=None, dtype=None, out=None, keepdims=False, initial=None, where=True)

Returns the prod along a given axis.

Refer to dpnp.prod for full documentation.

put(indices, vals, /, *, axis=None, mode='wrap')

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

Refer to dpnp.put for full documentation.

ravel(order='C')

Return a contiguous flattened array.

Refer to dpnp.ravel for full documentation.

repeat(repeats, axis=None)

Repeat elements of an array.

Refer to dpnp.repeat for full documentation.

reshape(*shape, order='C', copy=None)

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

Refer to dpnp.reshape for full documentation.

Returns:

y -- This will be a new view object if possible; otherwise, it will be a copy.

Return type:

dpnp.ndarray

See also

dpnp.reshape

Equivalent function.

Notes

Unlike the free function dpnp.reshape, this method on ndarray allows the elements of the shape parameter to be passed in as separate arguments. For example, a.reshape(10, 11) is equivalent to a.reshape((10, 11)).

round(decimals=0, out=None)

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

Refer to dpnp.round for full documentation.

searchsorted(v, side='left', sorter=None)

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

Refer to dpnp.searchsorted for full documentation

sort(axis=-1, kind=None, order=None)

Sort an array in-place.

Refer to dpnp.sort for full documentation.

Note

axis in dpnp.sort could be integer or None. If None, the array is flattened before sorting. However, axis in dpnp.ndarray.sort can only be integer since it sorts an array in-place.

Examples

>>> import dpnp as np
>>> a = np.array([[1,4],[3,1]])
>>> a.sort(axis=1)
>>> a
array([[1, 4],
      [1, 3]])
>>> a.sort(axis=0)
>>> a
array([[1, 1],
      [3, 4]])

squeeze(axis=None)

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

Refer to dpnp.squeeze for full documentation

std(axis=None, dtype=None, out=None, ddof=0, keepdims=False, *, where=True)

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

Refer to dpnp.std for full documentation.

sum(axis=None, dtype=None, out=None, keepdims=False, initial=None, where=True)

Returns the sum along a given axis.

Refer to dpnp.sum for full documentation.

swapaxes(axis1, axis2)

Interchange two axes of an array.

Refer to dpnp.swapaxes for full documentation.

take(indices, axis=None, out=None, mode='wrap')

Take elements from an array along an axis.

Refer to dpnp.take for full documentation.

to_device(target_device)

Transfer array to target device.

trace(offset=0, axis1=0, axis2=1, dtype=None, out=None)

Return the sum along diagonals of the array.

Refer to dpnp.trace for full documentation.

transpose(*axes)

Returns a view of the array with axes transposed.

For full documentation refer to numpy.ndarray.transpose.

Parameters:

axes (None, tuple or list of ints, n ints, optional) --

• None or no argument: reverses the order of the axes.

• tuple or list of ints: i in the j-th place in the tuple/list means that the array’s i-th axis becomes the transposed array’s j-th axis.

• n ints: same as an n-tuple/n-list of the same integers (this form is intended simply as a “convenience” alternative to the tuple form).

Returns:

out -- View of the array with its axes suitably permuted.

Return type:

dpnp.ndarray

See also

dpnp.transpose

Equivalent function.

dpnp.ndarray.ndarray.T

Array property returning the array transposed.

dpnp.ndarray.reshape

Give a new shape to an array without changing its data.

Examples

>>> import dpnp as np
>>> a = np.array([[1, 2], [3, 4]])
>>> a
array([[1, 2],
       [3, 4]])
>>> a.transpose()
array([[1, 3],
       [2, 4]])
>>> a.transpose((1, 0))
array([[1, 3],
       [2, 4]])

>>> a = np.array([1, 2, 3, 4])
>>> a
array([1, 2, 3, 4])
>>> a.transpose()
array([1, 2, 3, 4])

var(axis=None, dtype=None, out=None, ddof=0, keepdims=False, *, where=True)

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

Refer to dpnp.var for full documentation.

__eq__(other)

Return self==value.

__ne__(other)

Return self!=value.

__lt__(other)

Return self<value.

__le__(other)

Return self<=value.

__gt__(other)

Return self>value.

__ge__(other)

Return self>=value.

Attributes

T

View of the transposed array.

device

dtype

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

flags

Return information about the memory layout of the array.

flat

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

imag

The imaginary part of the array.

For full documentation refer to numpy.ndarray.imag.

Examples

>>> import dpnp as np
>>> x = np.sqrt(np.array([1+0j, 0+1j]))
>>> x.imag
array([0.        , 0.70710677])

itemsize

Size of one array element in bytes.

mT

View of the matrix transposed array.

The matrix transpose is the transpose of the last two dimensions, even if the array is of higher dimension.

Raises:

ValueError -- If the array is of dimension less than 2.

Examples

>>> import dpnp as np
>>> a = np.array([[1, 2], [3, 4]])
>>> a
array([[1, 2],
       [3, 4]])
>>> a.mT
array([[1, 3],
       [2, 4]])

>>> a = np.arange(8).reshape((2, 2, 2))
>>> a
array([[[0, 1],
        [2, 3]],
       [[4, 5],
        [6, 7]]])
>>> a.mT
array([[[0, 2],
        [1, 3]],
       [[4, 6],
        [5, 7]]])

nbytes

Total bytes consumed by the elements of the array.

ndim

Return the number of dimensions of an array.

For full documentation refer to numpy.ndarray.ndim.

Returns:

number_of_dimensions -- The number of dimensions in a.

Return type:

int

See also

dpnp.ndim

Equivalent method for any array-like input.

dpnp.shape

Return the shape of an array.

dpnp.ndarray.shape

Return the shape of an array.

Examples

>>> import dpnp as np
>>> x = np.array([1, 2, 3])
>>> x.ndim
1
>>> y = np.zeros((2, 3, 4))
>>> y.ndim
3

real

The real part of the array.

For full documentation refer to numpy.ndarray.real.

Examples

>>> import dpnp as np
>>> x = np.sqrt(np.array([1+0j, 0+1j]))
>>> x.real
array([1.        , 0.70710677])

shape

Tuple of array dimensions.

The shape property is usually used to get the current shape of an array, but may also be used to reshape the array in-place by assigning a tuple of array dimensions to it. Unlike dpnp.reshape, only non-negative values are supported to be set as new shape. Reshaping an array in-place will fail if a copy is required.

For full documentation refer to numpy.ndarray.shape.

Note

Using dpnp.ndarray.reshape or dpnp.reshape is the preferred approach to set new shape of an array.

See also

dpnp.shape

Equivalent getter function.

dpnp.reshape

Function similar to setting shape.

dpnp.ndarray.reshape

Method similar to setting shape.

Examples

>>> import dpnp as np
>>> x = np.array([1, 2, 3, 4])
>>> x.shape
(4,)
>>> y = np.zeros((2, 3, 4))
>>> y.shape
(2, 3, 4)

>>> y.shape = (3, 8)
>>> y
array([[ 0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.],
       [ 0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.],
       [ 0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.]])
>>> y.shape = (3, 6)
...
TypeError: Can not reshape array of size 24 into (3, 6)

size

Number of elements in the array.

Returns:

element_count -- Number of elements in the array.

Return type:

int

See also

dpnp.size

Return the number of elements along a given axis.

dpnp.shape

Return the shape of an array.

dpnp.ndarray.shape

Return the shape of an array.

Examples

>>> import dpnp as np
>>> x = np.zeros((3, 5, 2), dtype=np.complex64)
>>> x.size
30

strides

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

For example, for strides (s1, s2, s3) and multi-index (i1, i2, i3) position of the respective element relative to zero multi-index element is s1*s1 + s2*i2 + s3*i3.

sycl_context

sycl_device

sycl_queue

usm_type