cupy.ndarray¶

class
cupy.
ndarray
(shape, dtype=float, memptr=None, strides=None, order='C')¶ Multidimensional 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.
strides (tuple of ints or None) – Strides of data in memory.
order ({'C', 'F'}) – Rowmajor (Cstyle) or columnmajor (Fortranstyle) order.
 Variables
base (None or cupy.ndarray) – Base array from which this array is created as a view.
data (cupy.cuda.MemoryPointer) – Pointer to the array content head.
dtype (numpy.dtype) –
Dtype object of element type.
See also
Number of elements this array holds.
This is equivalent to product over the shape tuple.
See also
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 arraysNote
CuPy handles outofbounds 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 arraysNote
CuPy handles outofbounds 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 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).

__iter__
()¶ Implement iter(self).

__copy__
(self)¶

argmax
(self, axis=None, out=None, dtype=None, keepdims=False) → ndarray¶ Returns the indices of the maximum along a given axis.
Note
dtype
andkeepdim
arguments are specific to CuPy. They are not in NumPy.Note
axis
argument accepts a tuple of ints, but this is specific to CuPy. NumPy does not support it.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.
Note
dtype
andkeepdim
arguments are specific to CuPy. They are not in NumPy.Note
axis
argument accepts a tuple of ints, but this is specific to CuPy. NumPy does not support it.See also
cupy.argmin()
for full documentation,numpy.ndarray.argmin()

argpartition
(self, kth, axis= 1) → ndarray¶ 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 kth it will partition all elements indexed by kth 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
See also
cupy.argpartition()
for full documentation,numpy.ndarray.argpartition()

argsort
(self, axis= 1) → ndarray¶ 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
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'}) – Rowmajor (Cstyle) or columnmajor (Fortranstyle) order. When
order
is ‘A’, it uses ‘F’ ifa
is columnmajor and uses ‘C’ otherwise. And whenorder
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
, andsubok
arguments.See also

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()

compress
(self, condition, axis=None, out=None) → ndarray¶ Returns selected slices of this array along given axis.
Warning
This function may synchronize the device.
See also
cupy.compress()
for full documentation,numpy.ndarray.compress()

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'}) – Rowmajor (Cstyle) or columnmajor (Fortranstyle) order. When
order
is ‘A’, it uses ‘F’ ifa
is columnmajor 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()

cumprod
(self, axis=None, dtype=None, out=None) → ndarray¶ Returns the cumulative product of an array along a given axis.
See also
cupy.cumprod()
for full documentation,numpy.ndarray.cumprod()

cumsum
(self, axis=None, dtype=None, out=None) → ndarray¶ Returns the cumulative sum of an array along a given axis.
See also
cupy.cumsum()
for full documentation,numpy.ndarray.cumsum()

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
bycupy.load()
.

fill
(self, value)¶ Fills the array with a scalar value.
 Parameters
value – A scalar value to fill the array content.
See also

flatten
(self) → ndarray¶ Returns a copy of the array flatten into one dimension.
It currently supports Corder only.
 Returns
A copy of the array with one dimension.
 Return type
See also

get
(self, stream=None, order='C', out=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.
order ({'C', 'F', 'A'}) – The desired memory layout of the host array. When
order
is ‘A’, it uses ‘F’ if the array is fortrancontiguous and ‘C’ otherwise. Theorder
will be ignored ifout
is specified.out (numpy.ndarray) – Output array. In order to enable asynchronous copy, the underlying memory should be a pinned memory.
 Returns
Copy of the array on host memory.
 Return type

item
(self)¶ Converts the array with one element to a Python scalar
See also

max
(self, axis=None, out=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, keepdims=False) → ndarray¶ Returns the minimum along a given axis.
See also
cupy.amin()
for full documentation,numpy.ndarray.min()

nonzero
(self) → tuple¶ Return the indices of the elements that are nonzero.
Returned Array is containing the indices of the nonzero elements in that dimension.
 Returns
Indices of elements that are nonzero.
 Return type
tuple of arrays
Warning
This function may synchronize the device.
See also

partition
(self, kth, int axis=1)¶ Partitions an array.
 Parameters
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()

ptp
(self, axis=None, out=None, keepdims=False) → ndarray¶ Returns (maximum  minimum) along a given axis.
See also
cupy.ptp()
for full documentation,numpy.ndarray.ptp()

put
(self, indices, values, mode='wrap')¶ Replaces specified elements of an array with given values.
See also
cupy.put()
for full documentation,numpy.ndarray.put()

ravel
(self, order='C') → 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 – (Deprecated) 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

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, order='C')¶ Returns an array of a different shape and the same content.
See also
cupy.reshape()
for full documentation,numpy.ndarray.reshape()

round
(self, decimals=0, out=None) → ndarray¶ Returns an array with values rounded to the given number of decimals.
See also
cupy.around()
for full documentation,numpy.ndarray.round()

scatter_add
(self, slices, value)¶ Adds given values to specified elements of an array.
See also
cupyx.scatter_add()
for full documentation.

scatter_max
(self, slices, value)¶ Stores a maximum value of elements specified by indices to an array.
See also
cupyx.scatter_max()
for full documentation.

scatter_min
(self, slices, value)¶ Stores a minimum value of elements specified by indices to an array.
See also
cupyx.scatter_min()
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, int axis=1)¶ Sort an array, inplace 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 supportkind
andorder
parameters thatnumpy.ndarray.sort
does support.See also
cupy.sort()
for full documentation,numpy.ndarray.sort()

squeeze
(self, axis=None) → ndarray¶ Returns a view with sizeone 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()

toDlpack
(self)¶ Zerocopy conversion to a DLPack tensor.
DLPack is a open in memory tensor structure proposed in this repository: dmlc/dlpack.
This function returns a
PyCapsule
object which contains a pointer to a DLPack tensor converted from the own ndarray. This function does not copy the own data to the output DLpack tensor but it shares the pointer which is pointing to the same memory region for the data. Returns
 Output DLPack tensor which is
encapsulated in a
PyCapsule
object.
 Return type
dltensor (
PyCapsule
)
See also
fromDlpack()
is a method for zerocopy conversion from a DLPack tensor (which is encapsulated in aPyCapsule
object) to andarray
Warning
As of the DLPack v0.3 specification, it is (implicitly) assumed that the user is responsible to ensure the Producer and the Consumer are operating on the same stream. This requirement might be relaxed/changed in a future DLPack version.
Example
>>> import cupy >>> array1 = cupy.array([0, 1, 2], dtype=cupy.float32) >>> dltensor = array1.toDlpack() >>> array2 = cupy.fromDlpack(dltensor) >>> cupy.testing.assert_array_equal(array1, array2)

tofile
(self, fid, sep='', format='%s')¶ Writes the array to a file.
See also

tolist
(self)¶ Converts the array to a (possibly nested) Python list.
 Returns
The possibly nested Python list of array elements.
 Return type
See also

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
See also

__eq__
(value, /)¶ Return self==value.

__ne__
(value, /)¶ Return self!=value.

__lt__
(value, /)¶ Return self<value.

__le__
(value, /)¶ Return self<=value.

__gt__
(value, /)¶ Return self>value.

__ge__
(value, /)¶ Return self>=value.

__bool__
()¶ self != 0
Attributes

T
¶ Shapereversed 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 memorylayout information.
It only contains
c_contiguous
,f_contiguous
, andowndata
attributes. All of these are readonly. Accessing by indexes is also supported.See also

flat
¶

imag
¶

itemsize
¶ Size of each element in bytes.
See also

nbytes
¶ Total size of all elements in bytes.
It does not count skips between elements.
See also

ndim
¶ Number of dimensions.
a.ndim
is equivalent tolen(a.shape)
.See also

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