cupy.ndarray

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

CUDA 设备上的多维数组。

此类实现了 numpy.ndarray 方法的一个子集。不同之处在于此类将数组内容分配在当前的 GPU 设备上。

参数:

• shape (tuple of ints) – 轴的长度。

• dtype – 数据类型。它必须是 numpy.dtype 的一个参数。

• memptr (cupy.cuda.MemoryPointer) – 指向数组内容头部的指针。

• strides (tuple of ints or None) – 内存中的数据步长。

• order ({'C', 'F'}) – 行优先 (C 风格) 或列优先 (Fortran 风格) 顺序。

变量:

• base (None or cupy.ndarray) – 从中创建此数组作为视图的基础数组。

• data (cupy.cuda.MemoryPointer) – 指向数组内容头部的指针。

• ~ndarray.dtype (numpy.dtype) –

  元素类型的 Dtype 对象。

  另请参阅

  数据类型对象 (dtype)

• ~ndarray.size (int) –

  此数组包含的元素数量。

  这等同于 shape 元组中各元素的乘积。

  另请参阅

  numpy.ndarray.size

方法

__getitem__()

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

支持基本索引和高级索引。

注意

当前不支持由多个布尔数组组成的 slices

注意

CuPy 处理越界索引的方式与 NumPy 不同。NumPy 通过引发错误来处理它们，而 CuPy 则对它们进行环绕处理。

示例

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

__setitem__()

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

支持基本索引和高级索引。

注意

当前不支持由多个布尔数组组成的 slices

注意

当使用整数数组索引时，CuPy 处理越界索引的方式与 NumPy 不同。NumPy 通过引发错误来处理它们，而 CuPy 则对它们进行环绕处理。

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

注意

当 slices 中的整数数组多次引用同一位置时，其行为与 NumPy 不同。在这种情况下，实际存储的值是未定义的。

>>> import cupy
>>> a = cupy.zeros((2,))
>>> i = cupy.arange(10000) % 2
>>> v = cupy.arange(10000).astype(cupy.float64)
>>> a[i] = v
>>> a  
array([9150., 9151.])

另一方面，NumPy 存储对应于引用重复位置的索引中最后一个索引的值。

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

__len__()

返回 len(self)。

__iter__()

实现 iter(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

返回沿给定轴的最大值的索引。

注意

dtype 和 keepdim 参数是 CuPy 特有的。它们不在 NumPy 中。

注意

axis 参数接受一个整数元组，但这仅限于 CuPy。NumPy 不支持。

另请参阅

有关完整文档，请参见 cupy.argmax()， numpy.ndarray.argmax()

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

返回沿给定轴的最小值的索引。

注意

dtype 和 keepdim 参数是 CuPy 特有的。它们不在 NumPy 中。

注意

axis 参数接受一个整数元组，但这仅限于 CuPy。NumPy 不支持。

另请参阅

有关完整文档，请参见 cupy.argmin()， numpy.ndarray.argmin()

argpartition(self, kth, axis=-1) → ndarray

返回用于部分排序数组的索引。

参数:

• kth (int or sequence of ints) – 用于分区的元素索引。如果提供 k-th 的序列，它将一次将由这些 k-th 索引的所有元素分区到它们的排序位置。

• axis (int or None) – 沿哪个轴排序。默认为 -1，表示沿最后一个轴排序。如果提供 None，则在排序前展平数组。

返回值:

与 a 类型和形状相同的数组。

返回类型:

cupy.ndarray

另请参阅

有关完整文档，请参见 cupy.argpartition()， numpy.ndarray.argpartition()

argsort(self, axis=-1) → ndarray

返回用于稳定排序数组的索引

参数:

axis (int or None) – 沿哪个轴排序。默认为 -1，表示沿最后一个轴排序。如果提供 None，则在排序前展平数组。

返回值:

排序数组的索引数组。

返回类型:

cupy.ndarray

另请参阅

有关完整文档，请参见 cupy.argsort()， numpy.ndarray.argsort()

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

将数组转换为给定的数据类型。

参数:

• dtype – 类型指定符。

• order ({'C', 'F', 'A', 'K'}) – 行优先 (C 风格) 或列优先 (Fortran 风格) 顺序。当 order 为 ‘A’ 时，如果 a 是列优先，则使用 ‘F’；否则使用 ‘C’。当 order 为 ‘K’ 时，它会尽可能地保持步长。

• copy (bool) – 如果为 False 且未发生类型转换，则此方法返回数组本身。否则，返回一个副本。

返回值:

如果 copy 为 False 且不需要类型转换，则返回数组本身。否则，返回数组的一个（可能已类型转换的）副本。

注意

此方法当前不支持 casting 和 subok 参数。

另请参阅

numpy.ndarray.astype()

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

clip(self, min=None, max=None, out=None) → ndarray

返回一个值被限制在 [min, max] 范围内的数组。

另请参阅

有关完整文档，请参见 cupy.clip()， numpy.ndarray.clip()

compress(self, condition, axis=None, out=None) → ndarray

返回此数组沿给定轴的选定切片。

警告

此函数可能会同步设备。

另请参阅

有关完整文档，请参见 cupy.compress()， numpy.ndarray.compress()

conj(self) → ndarray

conjugate(self) → ndarray

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

返回数组的副本。

此方法在当前设备中创建给定数组的副本。即使给定数组位于另一设备上，您也可以将其复制到当前设备。

参数:

order ({'C', 'F', 'A', 'K'}) – 行优先 (C 风格) 或列优先 (Fortran 风格) 顺序。当 order 为 ‘A’ 时，如果 a 是列优先，则使用 ‘F’；否则使用 ‘C’。当 order 为 ‘K’ 时，它会尽可能地保持步长。

另请参阅

有关完整文档，请参见 cupy.copy()， numpy.ndarray.copy()

cumprod(self, axis=None, dtype=None, out=None) → ndarray

返回数组沿给定轴的累积乘积。

另请参阅

有关完整文档，请参见 cupy.cumprod()， numpy.ndarray.cumprod()

cumsum(self, axis=None, dtype=None, out=None) → ndarray

返回数组沿给定轴的累积和。

另请参阅

有关完整文档，请参见 cupy.cumsum()， numpy.ndarray.cumsum()

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

返回指定对角线的视图。

另请参阅

有关完整文档，请参见 cupy.diagonal()， numpy.ndarray.diagonal()

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

返回与给定数组的点积。

另请参阅

有关完整文档，请参见 cupy.dot()， numpy.ndarray.dot()

dump(self, file)

将数组的 pickle 转储到文件中。

转储的文件可以通过 cupy.load() 读回为 cupy.ndarray。

dumps(self) → bytes

将数组的 pickle 转储到字符串。

fill(self, value)

用标量值填充数组。

参数:

value – 用于填充数组内容的标量值。

另请参阅

numpy.ndarray.fill()

flatten(self, order='C') → ndarray

返回展平为一维的数组副本。

参数:

order ({'C', 'F', 'A', 'K'}) – ‘C’ 表示按行优先 (C 风格) 顺序展平。‘F’ 表示按列优先 (Fortran 风格) 顺序展平。‘A’ 表示如果 self 在内存中是 Fortran 连续的，则按列优先顺序展平，否则按行优先顺序展平。‘K’ 表示按元素在内存中出现的顺序展平 self。默认值为 ‘C’。

返回值:

一维数组的副本。

返回类型:

cupy.ndarray

另请参阅

numpy.ndarray.flatten()

get(self, stream=None, order='C', out=None, blocking=True)

返回主机内存上的数组副本。

参数:

• stream (cupy.cuda.Stream) – CUDA stream 对象。如果给定，则使用此流执行复制。否则，使用当前流。

• order ({'C', 'F', 'A'}) – 主机数组所需的内存布局。当 order 为 ‘A’ 时，如果数组是 fortran 连续的则使用 ‘F’，否则使用 ‘C’。如果指定了 out，则忽略 order。

• out (numpy.ndarray) – 输出数组。为了实现异步复制，底层内存应该是锁页内存 (pinned memory)。

• blocking (bool) – 如果设置为 False，复制将在给定（如果给定）或当前流上异步运行，用户负责确保流的顺序。默认值为 True，因此复制是同步的（相对于主机）。

返回值:

主机内存上的数组副本。

返回类型:

numpy.ndarray

item(self)

将只有一个元素的数组转换为 Python 标量

返回值:

数组的元素。

返回类型:

int 或 float 或 complex

另请参阅

numpy.ndarray.item()

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

返回沿给定轴的最大值。

另请参阅

有关完整文档，请参见 cupy.amax()， numpy.ndarray.max()

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

返回沿给定轴的均值。

另请参阅

有关完整文档，请参见 cupy.mean()， numpy.ndarray.mean()

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

返回沿给定轴的最小值。

另请参阅

cupy.amin() 完整文档请参阅， numpy.ndarray.min()

nonzero(self) → tuple

返回非零元素的索引。

返回的数组包含该维度中非零元素的索引。

返回值:

非零元素的索引。

返回类型:

数组的元组

警告

此函数可能会同步设备。

另请参阅

numpy.nonzero()

partition(self, kth, int axis=-1)

对数组进行分区。

参数:

• kth (int or sequence of ints) – 用于分区的元素索引。如果提供 k-th 的序列，它将一次将由这些 k-th 索引的所有元素分区到它们的排序位置。

• axis (int) – 沿哪个轴进行排序。默认为 -1，表示沿最后一个轴进行排序。

另请参阅

cupy.partition() 完整文档请参阅， numpy.ndarray.partition()

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

返回沿给定轴的乘积。

另请参阅

cupy.prod() 完整文档请参阅， numpy.ndarray.prod()

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

返回沿给定轴的（最大值 - 最小值）。

另请参阅

cupy.ptp() 完整文档请参阅， numpy.ndarray.ptp()

put(self, indices, values, mode='wrap')

将数组的指定元素替换为给定值。

另请参阅

cupy.put() 完整文档请参阅， numpy.ndarray.put()

ravel(self, order='C') → ndarray

将数组展平为一维。

另请参阅

cupy.ravel() 完整文档请参阅， numpy.ndarray.ravel()

reduced_view(self, dtype=None) → ndarray

返回一个维度数最少的数组视图。

参数:

dtype – （已弃用）数据类型指定符。如果给出，则内存序列将重新解释为新类型。

返回值:

具有缩减维度的数组视图。

返回类型:

cupy.ndarray

repeat(self, repeats, axis=None)

返回沿某个轴重复数组的数组。

另请参阅

cupy.repeat() 完整文档请参阅， numpy.ndarray.repeat()

reshape(self, *shape, order='C')

返回具有不同形状和相同内容的数组。

另请参阅

cupy.reshape() 完整文档请参阅， numpy.ndarray.reshape()

round(self, decimals=0, out=None) → ndarray

返回一个数组，其值四舍五入到给定的小数位数。

另请参阅

cupy.around() 完整文档请参阅， numpy.ndarray.round()

scatter_add(self, slices, value)

将给定值添加到数组的指定元素。

另请参阅

cupyx.scatter_add() 完整文档请参阅。

scatter_max(self, slices, value)

将由索引指定的元素的最大值存储到数组中。

另请参阅

cupyx.scatter_max() 完整文档请参阅。

scatter_min(self, slices, value)

将由索引指定的元素的最小值存储到数组中。

另请参阅

cupyx.scatter_min() 完整文档请参阅。

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

查找应插入 v 的元素以保持顺序的索引。

完整文档请参阅 cupy.searchsorted()

返回

另请参阅

numpy.searchsorted()

set(self, arr, stream=None)

将主机内存上的数组复制到 cupy.ndarray。

参数:

• arr (numpy.ndarray) – 主机内存上的源数组。

• stream (cupy.cuda.Stream) – CUDA stream 对象。如果给定，则使用此流执行复制。否则，使用当前流。

sort(self, int axis=-1)

使用稳定排序算法就地对数组进行排序。

参数:

axis (int) – 沿哪个轴进行排序。默认为 -1，表示沿最后一个轴进行排序。

注意

由于其实现原因，ndarray.sort 当前仅支持拥有自己数据的数组，且不支持 kind 和 order 等参数，这些参数是 numpy.ndarray.sort 支持的。

另请参阅

cupy.sort() 完整文档请参阅， numpy.ndarray.sort()

squeeze(self, axis=None) → ndarray

返回一个移除大小为一的轴的视图。

另请参阅

cupy.squeeze() 完整文档请参阅， numpy.ndarray.squeeze()

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

返回沿给定轴的标准差。

另请参阅

cupy.std() 完整文档请参阅， numpy.ndarray.std()

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

返回沿给定轴的总和。

另请参阅

cupy.sum() 完整文档请参阅， numpy.ndarray.sum()

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

返回一个交换了两个轴的数组视图。

另请参阅

cupy.swapaxes() 完整文档请参阅， numpy.ndarray.swapaxes()

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

返回沿轴指定索引处的元素数组。

另请参阅

cupy.take() 完整文档请参阅， numpy.ndarray.take()

toDlpack(self)

零拷贝转换为 DLPack 张量。

DLPack 是此仓库中提出的开放内存张量结构：dmlc/dlpack。

此函数返回一个 PyCapsule 对象，其中包含从 ndarray 自身转换而来的 DLPack 张量指针。此函数不会将自身数据复制到输出 DLPack 张量，而是共享指向同一内存区域的指针。

返回值:

输出 DLPack 张量，封装在 PyCapsule 对象中。

返回类型:

dltensor (PyCapsule)

另请参阅

fromDlpack() 是从 DLPack 张量（封装在 PyCapsule 对象中）到 ndarray 的零拷贝转换方法。

警告

根据 DLPack v0.3 规范，（隐式）假定用户负责确保生产者和消费者在同一流上运行。在未来的 DLPack 版本中，此要求可能会放宽/更改。

示例

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

tobytes(self, order='C') → bytes

将数组转换为 Python 字节对象。

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

将数组写入文件。

另请参阅

numpy.ndarray.tofile()

tolist(self)

将数组转换为（可能是嵌套的）Python 列表。

返回值:

由数组元素组成的（可能是嵌套的）Python 列表。

返回类型:

list

另请参阅

numpy.ndarray.tolist()

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

返回数组沿对角线的总和。

另请参阅

cupy.trace() 完整文档请参阅， numpy.ndarray.trace()

transpose(self, *axes)

返回一个轴已排列的数组视图。

另请参阅

cupy.transpose() 完整文档请参阅， numpy.ndarray.reshape()

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

返回沿给定轴的方差。

另请参阅

cupy.var() 完整文档请参阅， numpy.ndarray.var()

view(self, dtype=None, type=None)

返回数组的视图。

参数:

dtype – 如果这与数组的数据类型不同，则返回的视图会将内存序列重新解释为此类型数组。

返回值:

数组视图。原始数组的引用存储在 base 属性中。

返回类型:

cupy.ndarray

另请参阅

numpy.ndarray.view()

__eq__(value, /)

返回 self==value。

__ne__(value, /)

返回 self!=value。

__lt__(value, /)

返回 self<value。

__le__(value, /)

返回 self<=value。

__gt__(value, /)

返回 self>value。

__ge__(value, /)

返回 self>=value。

__bool__()

如果 self 为 True，否则为 False

属性

T

数组的形状反转视图。

如果 ndim < 2，则这只是对数组本身的引用。

base

cstruct

数组的 C 表示。

此属性用于将数组发送到 CUDA 内核。返回的 C 结构类型对于不同的 dtype 和 ndim 是不同的。C 类型的定义写在 cupy/carray.cuh 中。

data

device

此数组所在的 CUDA 设备。

dtype

flags

包含内存布局信息的对象。

它仅包含 c_contiguous、f_contiguous 和 owndata 属性。所有这些都是只读的。也支持通过索引访问。

另请参阅

numpy.ndarray.flags

flat

imag

itemsize

每个元素的大小（字节）。

另请参阅

numpy.ndarray.itemsize

nbytes

所有元素的总大小（字节）。

它不计算元素之间的跳跃。

另请参阅

numpy.ndarray.nbytes

ndim

维数。

a.ndim 等效于 len(a.shape)。

另请参阅

numpy.ndarray.ndim

real

shape

轴的长度。

此属性的设置器涉及不复制的重塑。如果数组无法不复制地重塑，则会引发异常。

size

strides

轴的步长（字节）。

另请参阅

numpy.ndarray.strides