cupy.ndarray

class cupy.ndarray(shape, dtype=float, memptr=None, order='C')

Multi-dimensional array on a CUDA device.

This class implements a subset of methods of numpy.ndarray. The difference is that this class allocates the array content on the current GPU device.

Parameters:
  • shape (tuple of ints) – Length of axes.
  • dtype – Data type. It must be an argument of numpy.dtype.
  • memptr (cupy.cuda.MemoryPointer) – Pointer to the array content head.
  • order ({'C', 'F'}) – Row-major (C-style) or column-major (Fortran-style) order.
Variables:

Methods

__getitem__()

x.__getitem__(y) <==> x[y]

Supports both basic and advanced indexing.

Note

Currently, it does not support slices that consists of more than one boolean arrays

Note

CuPy handles out-of-bounds indices differently from NumPy. NumPy handles them by raising an error, but CuPy wraps around them.

Example

>>> a = cupy.arange(3)
>>> a[[1, 3]]
array([1, 0])
__setitem__()

x.__setitem__(slices, y) <==> x[slices] = y

Supports both basic and advanced indexing.

Note

Currently, it does not support slices that consists of more than one boolean arrays

Note

CuPy handles out-of-bounds indices differently from NumPy when using integer array indexing. NumPy handles them by raising an error, but CuPy wraps around them.

>>> import cupy
>>> x = cupy.arange(3)
>>> x[[1, 3]] = 10
>>> x
array([10, 10,  2])

Note

The behavior differs from NumPy when integer arrays in slices reference the same location multiple times. In that case, the value that is actually stored is undefined.

>>> import cupy
>>> a = cupy.zeros((2,))
>>> i = cupy.arange(10000) % 2
>>> v = cupy.arange(10000).astype(cupy.float)
>>> a[i] = v
>>> a  # doctest: +SKIP
array([9150., 9151.])

On the other hand, NumPy stores the value corresponding to the last index among the indices referencing duplicate locations.

>>> import numpy
>>> a_cpu = numpy.zeros((2,))
>>> i_cpu = numpy.arange(10000) % 2
>>> v_cpu = numpy.arange(10000).astype(numpy.float)
>>> a_cpu[i_cpu] = v_cpu
>>> a_cpu
array([9998., 9999.])
__len__()

Return len(self).

__copy__(self)
all(self, axis=None, out=None, keepdims=False) → ndarray
any(self, axis=None, out=None, keepdims=False) → ndarray
argmax(self, axis=None, out=None, dtype=None, keepdims=False) → ndarray

Returns the indices of the maximum along a given axis.

See also

cupy.argmax() for full documentation, numpy.ndarray.argmax()

argmin(self, axis=None, out=None, dtype=None, keepdims=False) → ndarray

Returns the indices of the minimum along a given axis.

See also

cupy.argmin() for full documentation, numpy.ndarray.argmin()

argpartition(self, kth, axis=-1)

Returns the indices that would partially sort an array.

Parameters:
  • kth (int or sequence of ints) – Element index to partition by. If supplied with a sequence of k-th it will partition all elements indexed by k-th of them into their sorted position at once.
  • axis (int or None) – Axis along which to sort. Default is -1, which means sort along the last axis. If None is supplied, the array is flattened before sorting.
Returns:

Array of the same type and shape as a.
Return type:

cupy.ndarray

See also

cupy.argpartition() for full documentation, numpy.ndarray.argpartition()

argsort(self, axis=-1)

Returns the indices that would sort an array with stable sorting

Parameters:axis (int or None) – Axis along which to sort. Default is -1, which means sort along the last axis. If None is supplied, the array is flattened before sorting.
Returns:Array of indices that sort the array.
Return type:cupy.ndarray

See also

cupy.argsort() for full documentation, numpy.ndarray.argsort()

astype(self, dtype, order='K', casting=None, subok=None, copy=True) → ndarray

Casts the array to given data type.

Parameters:
  • dtype – Type specifier.
  • order ({'C', 'F', 'A', 'K'}) – 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) – If it is False and no cast happens, then this method returns the array itself. Otherwise, a copy is returned.
Returns:

If copy is False and no cast is required, then the array itself is returned. Otherwise, it returns a (possibly casted) copy of the array.

Note

This method currently does not support casting, and subok arguments.

See also

numpy.ndarray.astype()

choose(self, choices, out=None, mode='raise')
clip(self, a_min=None, a_max=None, out=None) → ndarray

Returns an array with values limited to [a_min, a_max].

See also

cupy.clip() for full documentation, numpy.ndarray.clip()

conj(self) → ndarray
copy(self, order='C') → ndarray

Returns a copy of the array.

This method makes a copy of a given array in the current device. Even when a given array is located in another device, you can copy it to the current device.

Parameters:order ({'C', 'F', 'A', 'K'}) – 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.

See also

cupy.copy() for full documentation, numpy.ndarray.copy()

diagonal(self, offset=0, axis1=0, axis2=1) → ndarray

Returns a view of the specified diagonals.

See also

cupy.diagonal() for full documentation, numpy.ndarray.diagonal()

dot(self, ndarray b, ndarray out=None)

Returns the dot product with given array.

See also

cupy.dot() for full documentation, numpy.ndarray.dot()

dump(self, file)

Dumps a pickle of the array to a file.

Dumped file can be read back to cupy.ndarray by cupy.load().

dumps(self)

Dumps a pickle of the array to a string.

fill(self, value)

Fills the array with a scalar value.

Parameters:value – A scalar value to fill the array content.

See also

numpy.ndarray.fill()

flatten(self) → ndarray

Returns a copy of the array flatten into one dimension.

It currently supports C-order only.

Returns:A copy of the array with one dimension.
Return type:cupy.ndarray

See also

numpy.ndarray.flatten()

get(self, stream=None)

Returns a copy of the array on host memory.

Parameters:stream (cupy.cuda.Stream) – CUDA stream object. If it is given, the copy runs asynchronously. Otherwise, the copy is synchronous. The default uses CUDA stream object of the current context.
Returns:Copy of the array on host memory.
Return type:numpy.ndarray
max(self, axis=None, out=None, dtype=None, keepdims=False) → ndarray

Returns the maximum along a given axis.

See also

cupy.amax() for full documentation, numpy.ndarray.max()

mean(self, axis=None, dtype=None, out=None, keepdims=False) → ndarray

Returns the mean along a given axis.

See also

cupy.mean() for full documentation, numpy.ndarray.mean()

min(self, axis=None, out=None, dtype=None, keepdims=False) → ndarray

Returns the minimum along a given axis.

See also

cupy.amin() for full documentation, numpy.ndarray.min()

nonzero(self)

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

Returned Array is containing the indices of the non-zero elements in that dimension.

Returns:Indices of elements that are non-zero.
Return type:tuple of arrays

See also

numpy.nonzero()

partition(self, kth, axis=-1)

Partitions an array.

Parameters:
  • kth (int or sequence of ints) – Element index to partition by. If supplied with a sequence of k-th it will partition all elements indexed by k-th of them into their sorted position at once.
  • axis (int) – Axis along which to sort. Default is -1, which means sort along the last axis.

See also

cupy.partition() for full documentation, numpy.ndarray.partition()

prod(self, axis=None, dtype=None, out=None, keepdims=None) → ndarray

Returns the product along a given axis.

See also

cupy.prod() for full documentation, numpy.ndarray.prod()

ravel(self) → ndarray

Returns an array flattened into one dimension.

See also

cupy.ravel() for full documentation, numpy.ndarray.ravel()

reduced_view(self, dtype=None) → ndarray

Returns a view of the array with minimum number of dimensions.

Parameters:dtype – Data type specifier. If it is given, then the memory sequence is reinterpreted as the new type.
Returns:A view of the array with reduced dimensions.
Return type:cupy.ndarray
repeat(self, repeats, axis=None)

Returns an array with repeated arrays along an axis.

See also

cupy.repeat() for full documentation, numpy.ndarray.repeat()

reshape(self, *shape)

Returns an array of a different shape and the same content.

See also

cupy.reshape() for full documentation, numpy.ndarray.reshape()

scatter_add(self, slices, value)

Adds given values to specified elements of an array.

See also

cupyx.scatter_add() for full documentation.

set(self, arr, stream=None)

Copies an array on the host memory to cupy.ndarray.

Parameters:
  • arr (numpy.ndarray) – The source array on the host memory.
  • stream (cupy.cuda.Stream) – CUDA stream object. If it is given, the copy runs asynchronously. Otherwise, the copy is synchronous. The default uses CUDA stream object of the current context.
sort(self, axis=-1)

Sort an array, in-place with a stable sorting algorithm.

Parameters:axis (int) – Axis along which to sort. Default is -1, which means sort along the last axis.

Note

For its implementation reason, ndarray.sort currently supports only arrays with their own data, and does not support kind and order parameters that numpy.ndarray.sort does support.

See also

cupy.sort() for full documentation, numpy.ndarray.sort()

squeeze(self, axis=None) → ndarray

Returns a view with size-one axes removed.

See also

cupy.squeeze() for full documentation, numpy.ndarray.squeeze()

std(self, axis=None, dtype=None, out=None, ddof=0, keepdims=False) → ndarray

Returns the standard deviation along a given axis.

See also

cupy.std() for full documentation, numpy.ndarray.std()

sum(self, axis=None, dtype=None, out=None, keepdims=False) → ndarray

Returns the sum along a given axis.

See also

cupy.sum() for full documentation, numpy.ndarray.sum()

swapaxes(self, Py_ssize_t axis1, Py_ssize_t axis2) → ndarray

Returns a view of the array with two axes swapped.

See also

cupy.swapaxes() for full documentation, numpy.ndarray.swapaxes()

take(self, indices, axis=None, out=None) → ndarray

Returns an array of elements at given indices along the axis.

See also

cupy.take() for full documentation, numpy.ndarray.take()

tofile(self, fid, sep='', format='%s')

Writes the array to a file.

See also

numpy.ndarray.tolist()

tolist(self)

Converts the array to a (possibly nested) Python list.

Returns:The possibly nested Python list of array elements.
Return type:list

See also

numpy.ndarray.tolist()

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

Returns the sum along diagonals of the array.

See also

cupy.trace() for full documentation, numpy.ndarray.trace()

transpose(self, *axes)

Returns a view of the array with axes permuted.

See also

cupy.transpose() for full documentation, numpy.ndarray.reshape()

var(self, axis=None, dtype=None, out=None, ddof=0, keepdims=False) → ndarray

Returns the variance along a given axis.

See also

cupy.var() for full documentation, numpy.ndarray.var()

view(self, dtype=None) → ndarray

Returns a view of the array.

Parameters:dtype – If this is different from the data type of the array, the returned view reinterpret the memory sequence as an array of this type.
Returns:A view of the array. A reference to the original array is stored at the base attribute.
Return type:cupy.ndarray

See also

numpy.ndarray.view()

Attributes

T

Shape-reversed view of the array.

If ndim < 2, then this is just a reference to the array itself.

base
cstruct

C representation of the array.

This property is used for sending an array to CUDA kernels. The type of returned C structure is different for different dtypes and ndims. The definition of C type is written in cupy/carray.cuh.

data
device

CUDA device on which this array resides.

dtype
flags

Object containing memory-layout information.

It only contains c_contiguous, f_contiguous, and owndata attributes. All of these are read-only. Accessing by indexes is also supported.

See also

numpy.ndarray.flags

imag
itemsize

Size of each element in bytes.

See also

numpy.ndarray.itemsize

nbytes

Size of whole elements in bytes.

It does not count skips between elements.

See also

numpy.ndarray.nbytes

ndim

Number of dimensions.

a.ndim is equivalent to len(a.shape).

See also

numpy.ndarray.ndim

real
shape

Lengths of axes.

Setter of this property involves reshaping without copy. If the array cannot be reshaped without copy, it raises an exception.

size
strides

Strides of axes in bytes.

See also

numpy.ndarray.strides