多维数组

本模块中的功能提供了类似于 numpy 数组，但所有操作都在CL计算设备上执行。

数据类型

PyOpenCL提供了 numpy 类型系统，表示为 numpy.dtype ，以及OpenCL中可用的类型。所有简单的标量类型都直接映射到对应的CL类型。

向量类型

class pyopencl.array.vec

OpenCL支持的所有向量类型，例如 float3 和 long4 以下列形式提供 numpy 此类中的数据类型。这些 numpy.dtype 实例的字段名称为 x ， y ， z ，以及 w 就像他们的OpenCL同行一样。它们既可以用于向内核传递参数，也可以用于在内核和Python代码之间来回传递数据。对于每种类型，一个 make_type 还提供了功能(例如 make_float3(x, y, z) )。

如果要构造预初始化的向量类型，有三个新函数可供选择：

• zeros_type()

• ones_type()

• filled_type(fill_value)

在 2014.1 版本加入.

在 2014.1 版本发生变更: 这个 make_type 对于每个组件，函数都有一个默认值(0)。依赖缺省值已被弃用。或者指定所有组件，或者使用上面提到的构建向量的一种新风格。

自定义数据类型

如果要在提供操作源代码的数组操作中使用自己的（struct/union/whatever）数据类型，请在 序言 传递给 pyopencl.elementwise.ElementwiseKernel ， pyopencl.reduction.ReductionKernel （或类似），并使用以下函数让PyOpenCL了解它们：

pyopencl.tools.get_or_register_dtype(c_names, dtype=None)

获取或注册 numpy.dtype 与字符串列表中的C类型名称相关联 c_names 。如果 dtype 是 None ，则不执行注册，并且 numpy.dtype 一定已经注册过了。如果是，则返回它。如果没有， TypeNameNotKnown 都被养大了。

如果 dtype 不是 None ，则尝试注册。如果 c_names 已知并注册到完全相同的 numpy.dtype 对象，则返回先前注册类型的先前dtype对象。如果 c_names 都是未知的，类型是注册的。如果其中一个 c_names 已知，但注册到不同的类型，则会引发错误。在后一种情况下，类型可能最终被部分注册，并且任何进一步的行为都是未定义的。

在 2012.2 版本加入.

exception pyopencl.tools.TypeNameNotKnown

在 2013.1 版本加入.

pyopencl.tools.register_dtype(dtype, name)

在 2013.1 版本发生变更: 此函数已被弃用。建议您针对新接口进行开发， get_or_register_dtype() .

pyopencl.tools.dtype_to_ctype(dtype)

返回注册的C名称 D型 .

此函数有助于为结构化对象生成C/OpenCL声明 numpy.dtype 实例：

pyopencl.tools.match_dtype_to_c_struct(device, name, dtype, context=None)

返回元组 (dtype, c_decl) 中的C结构声明 c_decl 和结构 numpy.dtype 实例 dtype 具有相同的内存布局。

请注意 dtype 可以根据传入的值进行修改，例如插入填充。

(作为对实现的备注，此例程在给定的 device 以确保 numpy 并且C偏移量和大小匹配。)

在 2013.1 版本加入.

此示例说明此函数的用法：

>>> import numpy as np
>>> import pyopencl as cl
>>> import pyopencl.tools
>>> ctx = cl.create_some_context()
>>> dtype = np.dtype([("id", np.uint32), ("value", np.float32)])
>>> dtype, c_decl = pyopencl.tools.match_dtype_to_c_struct(
...     ctx.devices[0], 'id_val', dtype)
>>> print c_decl
typedef struct {
  unsigned id;
  float value;
} id_val;
>>> print dtype
[('id', '<u4'), ('value', '<f4')]
>>> cl.tools.get_or_register_dtype('id_val', dtype)

如此示例所示，调用 get_or_register_dtype() 关于修改后的 dtype 由此函数返回，而不是原始函数。

有关如何使用自定义结构化类型的更完整示例，请参见 examples/demo-struct-reduce.py 在PyOpenCL分布中。

复数

PyOpenCL的 Array 类型只需使用相应的 numpy 类型。

如果您想在自己的内核中使用这个支持，下面是如何继续的：由于opencl1.2（和更早版本）没有指定本机复数支持，PyOpenCL可以解决这个缺陷。说：：

#include <pyopencl-complex.h>

在您的内核中，您会得到复杂的类型 cfloat_t and cdouble_t, along with functions defined on them such as cfloat_mul(a, b) or cdouble_log(z). Elementwise kernels automatically include the header if your kernel has complex input or output. See the source file 获取可供选择的精确列表。

如果您需要双精度支持，请：

#define PYOPENCL_DEFINE_CDOUBLE

在包括收割台之前，由于DP支撑显然无法可靠地自动检测。

在引擎盖下，复杂类型是在标题中定义的结构类型。理想情况下，只能通过提供的函数访问结构，而不能直接访问。

在 2012.1 版本加入.

在 2015.2 版本发生变更: [[INCOMPATIBLE]] 将PyOpenCL的复数从 float2 和 double2 要自定义的OpenCL矢量类型 struct . 这是改变了，因为它很容易引入错误的地方

• 复杂*复杂

• 真实+复杂

look 就像他们做了正确的事，却默默地做了错误的事。

这个 Array 等级

class pyopencl.array.Array(cq: Context | CommandQueue | None, shape: Tuple[int, ...] | int, dtype: Any, order: str = 'C', allocator: AllocatorBase | None = None, data: Any = None, offset: int = 0, strides: Tuple[int, ...] | None = None, events: List[Event] | None = None, _flags: Any = None, _fast: bool = False, _size: int | None = None, _context: Context | None = None, _queue: CommandQueue | None = None)

A numpy.ndarray 在计算设备上存储其数据并执行其计算的类似工作。 shape 和 dtype 完全按照中的方式工作 numpy 。中的算术方法 Array 支持标量播放。(例如： array + 5 )。

cq 必须是一个 CommandQueue 或者是 Context 。

如果是队列， cq 指定默认情况下数组执行其计算的队列。如果不需要默认队列(从而不需要重载操作符和许多其他细节)，则传递一个 Context 。

allocator 可能是 None 或一个可调用函数，当使用要分配的字节数的参数调用该函数时，该函数返回 pyopencl.Buffer 对象。(A) pyopencl.tools.MemoryPool 实例是要在此处传递的对象的一个有用示例。)

在 2011.1 版本发生变更: 已重命名 context 至 cqa ，使其具有通用性。

所有超越的争论 order 应被视为仅限关键字。

在 2015.2 版本发生变更: 已重命名 context 至 cq ，不允许通过它的分配器。

data

这个 pyopencl.MemoryObject 实例为支持此操作的内存创建 Array 。

在 2013.1 版本发生变更: 如果非零值为 offset 已为此数组指定，则此操作将失败，并显示 ArrayHasOffsetError 。

base_data

这个 pyopencl.MemoryObject 实例为支持此操作的内存创建 Array 。不像 data ，其基址为 base_data 允许不同于数组的开头。实际开始是的基地址 base_data 加 offset 字节。

不像 data ，正在检索 base_data 总是成功的。

在 2013.1 版本加入.

offset

看见 base_data 。

在 2013.1 版本加入.

shape

数组中每个维度的长度的元组。

ndim

中的维度数 shape 。

dtype

这个 numpy.dtype GPU数组中的项的。

size

数组中有意义的条目数。也可以通过将 shape 。

nbytes

整个数组的大小，以字节为单位。计算方式为 size 《泰晤士报》 dtype.itemsize 。

strides

遍历数组时在每个维度中单步执行的字节数组。

flags

具有属性的对象 c_contiguous ， f_contiguous 和 forc ，它可用于查询邻接属性，类似于 numpy.ndarray.flags 。

方法

with_queue(queue)

退回一份 self 将默认队列设置为 queue 。

None 允许作为的值 queue 。

在 2013.1 版本加入.

__len__()

对象的前导维度的大小。 self 。

reshape(*shape, **kwargs)

返回包含具有新形状的相同数据的数组。

ravel(order='C')

返回包含相同数据的展平数组。

view(dtype=None)

返回具有相同数据的数组的视图。如果 dtype 与当前数据类型不同，则将重新解释内存的实际字节数。

squeeze()

返回删除了长度为1的维度的数组的视图。

在 2015.2 版本加入.

transpose(axes=None)

排列数组的维度。

参数:

axes -- 整型列表，可选。默认情况下，反转尺寸，否则根据给定值置换轴。

返回:

Array 排列了轴的阵列的视图。

在 2015.2 版本加入.

T

set(ary, queue=None, async_=None, **kwargs)

将内容转移到 numpy.ndarray 对象 ary 放到设备上。

ary 必须具有与相同的数据类型和大小(不一定是形状) self 。

async_ 是一个布尔值，指示是否允许函数在传输完成之前返回。为避免同步错误，缺省设置为 False 。

在 2017.2.1 版本发生变更: Python3.7使 async 保留关键字。在较老的 Python 上，我们将继续接受 async 但是，作为一个参数，应该将其视为已弃用。 async_ 是新的官方拼写。

get(queue=None, ary=None, async_=None, **kwargs)

将内容转移到 self vt.进入，进入 ary 或新分配的 numpy.ndarray 。如果 ary ，则它必须具有相同的形状和数据类型。

在 2019.1.2 版本发生变更: 通过以下方式呼叫 async_=True 已弃用，取而代之的 get_async() 。由返回的事件 pyopencl.enqueue_copy() 现在存储在 events 以确保数据在复制完成之前不会被修改。

在 2015.2 版本发生变更: ary 不建议使用不同形状的。

在 2017.2.1 版本发生变更: Python3.7使 async 保留关键字。在较老的 Python 上，我们将继续接受 async 但是，作为一个参数，应该将其视为已弃用。 async_ 是新的官方拼写。

get_async(queue=None, ary=None, **kwargs)

的异步版本 get() 它返回一个元组 (ary, event) 包含主机阵列 ary 以及 pyopencl.NannyEvent event 返回者 pyopencl.enqueue_copy() 。

在 2019.1.2 版本加入.

copy(queue=<class 'pyopencl.array._copy_queue'>)

参数:

queue -- 这个 CommandQueue 用于返回的数组。

在 2017.1.2 版本发生变更: 更新返回数组的队列。

在 2013.1 版本加入.

__str__()

返回str(Self)。

__repr__()

返回epr(Self)。

mul_add(selffac, other, otherfac, queue=None)

返回 selffac * self + otherfac * other 。

__add__(other)

添加具有数组的数组或具有标量的数组。

__sub__(other)

从数组中减去数组，或从数组中减去标量。

__iadd__(other)

__isub__(other)

__pos__()

__neg__()

__mul__(other)

__div__(other)

将数组除以数组或标量，即 self / other 。

__rdiv__(other)

将数组除以标量或数组，即 other / self 。

__pow__(other)

按标量求幂或按元素求幂 Array 。

__and__(other)

__xor__(other)

__or__(other)

返回self|Value。

__iand__(other)

__ixor__(other)

__ior__(other)

__abs__()

返回一个 Array 的元素的绝对值 self 。

__invert__()

fill(value, queue=None, wait_for=None)

用以下内容填充数组 scalar 。

返回:

self 。

astype(dtype, queue=None)

退回一份 self ，投射到 dtype 。

real

在 2012.1 版本加入.

imag

在 2012.1 版本加入.

conj()

在 2012.1 版本加入.

conjugate()

在 2012.1 版本加入.

__getitem__(index)

在 2013.1 版本加入.

__setitem__(subscript, value)

将切片设置为 self 已确定 subscript 至 value 。

value 允许为：

• A Array 相同的 shape 而且(目前) strides ，但具有潜在的不同 dtype 。

• A numpy.ndarray 相同的 shape 而且(目前) strides ，但具有潜在的不同 dtype 。

• 一个标量。

目前不支持非标量广播。

在 2013.1 版本加入.

setitem(subscript, value, queue=None, wait_for=None)

喜欢 __setitem__() ，但能够指定一个 queue 和 wait_for 。

在 2013.1 版本加入.

在 2013.2 版本发生变更: 增列 wait_for 。

map_to_host(queue=None, flags=None, is_blocking=True, wait_for=None)

如果 is_blocking ，则返回一个 numpy.ndarray 对应于与相同的内存 self 。

如果 is_blocking 不为真，则返回元组 (ary, evt) ，在哪里 ary 是上述数组。

主机阵列通过以下方式获得 pyopencl.enqueue_map_buffer() 。有关更多详细信息，请参阅那里。

参数:

flags -- 一种组合 pyopencl.map_flags 。默认为读写。

在 2013.2 版本加入.

比较，条件句，任何，全部

在 2013.2 版本加入.

布尔数组存储为 numpy.int8 因为 bool 在OpenCL规范中具有未指定的大小。

__bool__()

仅适用于设备标量。(即“数组”和 shape == () )

any(queue=None, wait_for=None)

all(queue=None, wait_for=None)

__eq__(other)

返回self==值。

__ne__(other)

返回自我！=值。

__lt__(other)

返回self<Value。

__le__(other)

返回self<=Value。

__gt__(other)

返回self>Value。

__ge__(other)

返回self>=值。

事件管理

如果从无序队列中使用数组，则它需要注意自己的操作顺序。本节中的设施使这一点成为可能。

在 2014.1.1 版本加入.

events

一份名单 pyopencl.Event 此数组的当前内容所依赖的。用户代码可以读取，但不应直接修改此列表。要更新此列表，请改用以下方法。

add_event(evt)

增列 evt 至 events 。如果 events 太长，此方法可能会隐式等待 events 并将它们从名单中删除。

finish()

等待的全部内容 events ，清除它。

exception pyopencl.array.ArrayHasOffsetError(val='The operation you are attempting does not yet support arrays that start at an offset from the beginning of their buffer.')

在 2013.1 版本加入.

构造 Array 实例

pyopencl.array.to_device(queue, ary, allocator=None, async_=None, array_queue=<class 'pyopencl.array._same_as_transfer'>, **kwargs)

返回一个 Array 这是一个完全相同的副本 numpy.ndarray 实例 ary 。

参数:

array_queue -- 这个 CommandQueue 它将存储在结果数组中。通过传递以下方法来确保没有与数组关联的隐式队列 None 。

看见 Array 对于…的意义 allocator 。

在 2015.2 版本发生变更: array_queue 添加了参数。

在 2017.2.1 版本发生变更: Python3.7使 async 保留关键字。在较老的 Python 上，我们将继续接受 async 但是，作为一个参数，应该将其视为已弃用。 async_ 是新的官方拼写。

pyopencl.array.empty(queue, shape, dtype, order='C', allocator=None, data=None)

的同义词 Array 建造师。

pyopencl.array.zeros(queue, shape, dtype, order='C', allocator=None)

相同于 empty() ，但是 Array 在返回之前是零初始化的。

在 2011.1 版本发生变更: context 参数已弃用。

pyopencl.array.empty_like(ary, queue=<class 'pyopencl.array._copy_queue'>, allocator=None)

创建新的、未初始化的 Array 具有与的相同的特性 other_ary 。

pyopencl.array.zeros_like(ary)

创建一个新的、零初始化的 Array 具有与的相同的特性 other_ary 。

pyopencl.array.arange(queue, [start, ]stop, [step, ]**kwargs)

创建 Array 用空格的数字填充 step 分开，从开始 start 并在以下位置结束 stop 。如果不给， start 默认为0， step 默认为1。

对于浮点参数，结果的长度为 ceil((stop - start)/step) 。此规则可能会导致结果的最后一个元素大于 stop 。

dtype 是必需的关键字参数。

在 2011.1 版本发生变更: context 参数已弃用。

在 2011.2 版本发生变更: allocator 添加了关键字参数。

pyopencl.array.take(a, indices, out=None, queue=None, wait_for=None)

返回 Array [a[indices[0]], ..., a[indices[n]]] 。就目前而言， a 必须是可以绑定到纹理的类型。

pyopencl.array.concatenate(arrays, axis=0, queue=None, allocator=None)

在 2013.1 版本加入.

备注

返回的数组与列表中的第一个数组类型相同。

pyopencl.array.stack(arrays, axis=0, queue=None)

沿新的轴合并一系列数组。

参数:

• arrays -- 一系列 Array 。

• axis -- 结果数组中新轴的维度的索引。可以为-1，以使新轴成为最后一个尺寸。

返回:

Array

操纵 Array 实例

pyopencl.array.transpose(a, axes=None)

排列数组的维度。

参数:

• a -- Array

• axes -- 整型列表，可选。默认情况下，反转尺寸，否则根据给定值置换轴。

返回:

Array 排列了轴的阵列的视图。

pyopencl.array.reshape(a, shape)

在不更改数组数据的情况下为数组赋予新形状。

在 2015.2 版本加入.

条件句

pyopencl.array.if_positive(criterion, then_, else_, out=None, queue=None)

返回如下数组 then_ ，对于索引处的元素 i ，包含 then_[i] 如果 criterion[i]>0 、其他 else_[i] 。

pyopencl.array.maximum(a, b, out=None, queue=None)

返回的元素最大值 a 和 b 。

pyopencl.array.minimum(a, b, out=None, queue=None)

返回元素式的最小值 a 和 b 。

逻辑运算

pyopencl.array.logical_and(x1, x2, /, out=None, queue=None)

返回以元素为单位的逻辑与 x1 和 x2 。

pyopencl.array.logical_or(x1, x2, /, out=None, queue=None)

返回的按元素执行的逻辑或 x1 和 x2 。

pyopencl.array.logical_not(x, /, out=None, queue=None)

返回元素方式的逻辑NOT OF x 。

约简

pyopencl.array.sum(a, dtype=None, queue=None, slice=None, initial=<no value>)

在 2011.1 版本加入.

pyopencl.array.all(a, queue=None, wait_for=None)

pyopencl.array.any(a, queue=None, wait_for=None)

pyopencl.array.dot(a, b, dtype=None, queue=None, slice=None)

在 2011.1 版本加入.

pyopencl.array.vdot(a, b, dtype=None, queue=None, slice=None)

喜欢 numpy.vdot() 。

在 2013.1 版本加入.

pyopencl.array.subset_dot(subset, a, b, dtype=None, queue=None, slice=None)

在 2011.1 版本加入.

pyopencl.array.max(a, queue=None, initial=<no value>)

在 2011.1 版本加入.

pyopencl.array.min(a, queue=None, initial=<no value>)

在 2011.1 版本加入.

pyopencl.array.subset_max(subset, a, queue=None, slice=None)

在 2011.1 版本加入.

pyopencl.array.subset_min(subset, a, queue=None, slice=None)

在 2011.1 版本加入.

另见 总和和计数（“减少”） .

上的元素级函数 Array 实例

这个 pyopencl.clmath 模块包含OpenCL标准中可用的C函数的数组版本。（见本规范表6.8）

pyopencl.clmath.acos(array, queue=None)

pyopencl.clmath.acosh(array, queue=None)

pyopencl.clmath.acospi(array, queue=None)

pyopencl.clmath.asin(array, queue=None)

pyopencl.clmath.asinh(array, queue=None)

pyopencl.clmath.asinpi(array, queue=None)

pyopencl.clmath.atan(array, queue=None)

pyopencl.clmath.atan2(y, x, queue=None)

在 2013.1 版本加入.

pyopencl.clmath.atanh(array, queue=None)

pyopencl.clmath.atanpi(array, queue=None)

pyopencl.clmath.atan2pi(y, x, queue=None)

在 2013.1 版本加入.

pyopencl.clmath.cbrt(array, queue=None)

pyopencl.clmath.ceil(array, queue=None)

pyopencl.clmath.cos(array, queue=None)

pyopencl.clmath.cosh(array, queue=None)

pyopencl.clmath.cospi(array, queue=None)

pyopencl.clmath.erfc(array, queue=None)

pyopencl.clmath.erf(array, queue=None)

pyopencl.clmath.exp(array, queue=None)

pyopencl.clmath.exp2(array, queue=None)

pyopencl.clmath.exp10(array, queue=None)

pyopencl.clmath.expm1(array, queue=None)

pyopencl.clmath.fabs(array, queue=None)

pyopencl.clmath.floor(array, queue=None)

pyopencl.clmath.fmod(arg, mod, queue=None)

返回除法的浮点余数 arg / mod 中的每个元素 arg 和 mod 。

pyopencl.clmath.frexp(arg, queue=None)

返回元组 (significands, exponents) 以至于 arg == significand * 2**exponent 。

pyopencl.clmath.ilogb(array, queue=None)

pyopencl.clmath.ldexp(significand, exponent, queue=None)

返回由以下条目组成的新的浮点值数组 significand 和 exponent ，配对为 result = significand * 2**exponent 。

pyopencl.clmath.lgamma(array, queue=None)

pyopencl.clmath.log(array, queue=None)

pyopencl.clmath.log2(array, queue=None)

pyopencl.clmath.log10(array, queue=None)

pyopencl.clmath.log1p(array, queue=None)

pyopencl.clmath.logb(array, queue=None)

pyopencl.clmath.modf(arg, queue=None)

返回一个 tuple (fracpart, intpart) 的整数部分和小数部分的数组 arg 。

pyopencl.clmath.nan(array, queue=None)

pyopencl.clmath.rint(array, queue=None)

pyopencl.clmath.round(array, queue=None)

pyopencl.clmath.sin(array, queue=None)

pyopencl.clmath.sinh(array, queue=None)

pyopencl.clmath.sinpi(array, queue=None)

pyopencl.clmath.sqrt(array, queue=None)

pyopencl.clmath.tan(array, queue=None)

pyopencl.clmath.tanh(array, queue=None)

pyopencl.clmath.tanpi(array, queue=None)

pyopencl.clmath.tgamma(array, queue=None)

pyopencl.clmath.trunc(array, queue=None)

生成随机数数组

PyOpenCL现在包含并使用了一些 Random123 random number generators 作者：D.E.Shaw Research。除了可以通过上面的便利函数使用之外，还可以通过以下方式在通过PyOpenCL编译的任何代码中使用它们：

#include <pyopencl-random123/philox.cl>
#include <pyopencl-random123/threefry.cl>

请参阅 Philox source 以及 Threefry source 获取一些文档，如果您计划直接使用Random123。

备注

PyOpenCL之前记录了对RANLUXCL随机数生成器的支持 (https://bitbucket.org/ivarun/ranluxcl 作者声明：[by Ivar Ursin Nikolaisen]由于这些生成器的速度普遍较慢，该支持现在已弃用，并将从2018.x系列的PyOpenCL中删除。鼓励所有用户切换到Random123生成器之一， PhiloxGenerator 或 ThreefryGenerator 。

class pyopencl.clrandom.PhiloxGenerator(context, key=None, counter=None, seed=None)

在 2016.2 版本加入.

fill_uniform(ary, a=0, b=1, queue=None)

uniform(*args, **kwargs)

创建一个新的空数组，应用 fill_uniform() 为它干杯。

fill_normal(ary, mu=0, sigma=1, queue=None)

填充 ary 均值为正态分布的数 mu 和标准差 sigma 。

normal(*args, **kwargs)

创建一个新的空数组，应用 fill_normal() 为它干杯。

class pyopencl.clrandom.ThreefryGenerator(context, key=None, counter=None, seed=None)

在 2016.2 版本加入.

fill_uniform(ary, a=0, b=1, queue=None)

uniform(*args, **kwargs)

创建一个新的空数组，应用 fill_uniform() 为它干杯。

fill_normal(ary, mu=0, sigma=1, queue=None)

填充 ary 均值为正态分布的数 mu 和标准差 sigma 。

normal(*args, **kwargs)

创建一个新的空数组，应用 fill_normal() 为它干杯。

pyopencl.clrandom.rand(queue, shape, dtype, luxury=None, a=0, b=1)

返回一个数组 shape 填充有随机值的 dtype 在这个范围内 \([a, b)\) 。

pyopencl.clrandom.fill_rand(result, queue=None, luxury=None, a=0, b=1)

填充 result 具有范围内的随机值 \([0, 1)\) 。