OpenCL运行时：程序和内核#

程序#

PYOPENCL_NO_CACHE#

默认情况下，在调用时，PyOpenCL将使用OpenCL运行时返回的缓存(在磁盘上)“二进制文件” Program.build() 在用源代码构建的程序上。(这将取决于正在使用的ICD由此节省了多少编译工作。)通过设置环境变量 PYOPENCL_NO_CACHE 设置为任何非空值，则取消此缓存。不会执行额外的内存缓存。要在内存中保留内核的编译版本，只需保留 Program 和/或 Kernel 物体。

PyOpenCL还将缓存“Invoker”，这是为加快向内核传递参数和将其排队而生成的一小段Python代码。

在 2013.1 版本加入.

PYOPENCL_BUILD_OPTIONS#: 在环境变量中找到的任何选项 PYOPENCL_BUILD_OPTIONS 将附加到选项在里面 Program.build() .

在 2013.1 版本加入.

class pyopencl.Program(context, src)[源代码]#

class pyopencl.Program(context, devices, binaries)

binaries 中的每个条目必须包含一个二进制文件 devices 。如果 src 是一种 bytes 对象以有效的 SPIR-V 魔术数字，它将移交给OpenCL实现作为这样，而不是作为OpenCL C源代码。(支持Spir-V需要OpenCL 2.1。)

在 2016.2 版本发生变更: 添加对SPIR-V的支持。

info#: 的小写版本 program_info 常量可以用作此类实例上的属性，以直接查询信息属性。

get_info(param)[源代码]#: 见 program_info 对于价值 param .

get_build_info(device, param)[源代码]#: 见 program_build_info 对于价值 param .

build(options=[], devices=None, cache_dir=None)[源代码]#

选项是编译器标志的字符串。退换商品 self .

如果 cache_dir 不是无构建的二进制文件，而是缓存在具有给定路径的磁盘缓存中。如果通过 cache_dir 是None，但此程序的上下文是用not None cacheu dir创建的-它将用作缓存目录。如果通过 cache_dir 是None并且上下文是用None cache创建的u dir:生成的二进制文件将缓存在名为 pyopencl-compiler-cache-vN-uidNAME-pyVERSION 在返回的目录中 tempfile.gettempdir() .

另见 PYOPENCL_NO_CACHE ， PYOPENCL_BUILD_OPTIONS .

在 2011.1 版本发生变更: 选项现在可能也是 list 属于 str .

compile(self, options=[], devices=None, headers=[])[源代码]#

参数:: headers -- 元组列表 （姓名、课程） .

仅适用于CL 1.2。

在 2011.2 版本加入.

kernel_name#

您可以使用 program.kernel_name 要获得一个 Kernel 对象从程序中删除。请注意，这种类型的每次查找都会生成一个新的内核对象，因此 won't 工作：：

prg.sum.set_args(a_g, b_g, res_g)
ev = cl.enqueue_nd_range_kernel(queue, prg.sum, a_np.shape, None)

相反，可以使用（推荐的、无状态的）调用接口：

sum_knl = prg.sum
sum_knl(queue, a_np.shape, None, a_g, b_g, res_g)

或者长长的、有状态的方式，如果您喜欢：

sum_knl.set_args(a_g, b_g, res_g)
ev = cl.enqueue_nd_range_kernel(queue, sum_knl, a_np.shape, None)

下面的方法也可以使用，但是请注意，对于高效的内核入队来说很重要的一些缓存被附加到 Kernel 对象，并且这些缓存在以下使用模式中将无效：：

prg.sum(queue, a_np.shape, None, a_g, b_g, res_g)

请注意 Program 必须建造（参见 build() )为了让它简单地通过属性查找工作。

备注

这个 program_info 属性位于相同的名称空间中，并优先于 Kernel 姓名。

all_kernels()[源代码]#: 返回所有 Kernel 中的对象 Program .

set_specialization_constant(spec_id, buffer)#: 仅适用于CL 2.2及更新版本。

在 2020.3 版本加入.

static from_int_ptr(int_ptr_value, retain=True)[源代码]#

int_ptr#: 返回一个整数，该整数与基础 cl_program 。使用 from_int_ptr() 以转回为一个Python对象。

在 2013.2 版本加入.

Instances of this class are hashable, and two instances of this class may be compared using "==" and "!=". (Hashability was added in version 2011.2.) Two objects are considered the same if the underlying OpenCL object is the same, as established by C pointer equality.

pyopencl.create_program_with_built_in_kernels(context, devices, kernel_names)[源代码]#: 仅适用于CL 1.2。

在 2011.2 版本加入.

pyopencl.link_program(context, programs, options=[], devices=None)[源代码]#: 仅适用于CL 1.2。

在 2011.2 版本加入.

pyopencl.unload_platform_compiler(platform)#: 仅适用于CL 1.2。

在 2011.2 版本加入.

内核#

class pyopencl.Kernel(program, name)#

info#: 的小写版本 kernel_info 常量可以用作此类实例上的属性，以直接查询信息属性。

clone()#: 仅适用于CL 2.1。

在 2020.3 版本加入.

get_info(param)[源代码]#: 见 kernel_info 对于价值 param .

get_work_group_info(param, device)[源代码]#: 见 kernel_work_group_info 对于价值 param .

get_arg_info(arg_index, param)#

见 kernel_arg_info 对于价值 param .

仅在OpenCL1.2及更新版本中可用。

get_sub_group_info(self, device, param, input_value=None)#

当OpenCL规范要求 input_value 属于 size_t ，这些可以直接作为数字传递。当它要求的时候 input_value 属于 size_t * ，可以传递一个整数元组。

仅在OpenCL2.1及更新版本中可用。

在 2020.3 版本加入.

set_arg(self, index, arg)#

arg 可能是

None ：这可能会被认为是 __global 内存引用以传递 NULL 指向内核的指针。
任何满足Python缓冲区接口的东西，尤其是 numpy.ndarray ， str 或 numpy 的大小的标量，例如 numpy.int32 或 numpy.float64 .

备注

注意Python自己的 int 或 float 对象不能在盒子外工作。看到了吗 Kernel.set_scalar_arg_dtypes() 为了让他们工作。或者，标准库模块 struct 可用于将Python的本机数字类型转换为 str .
的实例 MemoryObject . （例如。 Buffer ， Image 等）
的实例 LocalMemory .
的实例 Sampler .
的实例 CommandQueue . （仅限CL 2.0及以上）

set_args(self, *args)[源代码]#: 援引 set_arg() 在每个元素上 args 反过来。

在 0.92 版本加入.

set_scalar_arg_dtypes(arg_dtypes)[源代码]#

通知包装器标量的大小类型 Kernel 论据。对于每个论点， arg_dtypes 包含一个条目。对于非标量，这必须是 None . 对于标量，它必须是用户可以接受的对象 numpy.dtype 构造函数，指示相应的标量参数属于该类型。

在使用正确的信息调用这个函数之后，最合适的数字类型将自动转换为内核调用的正确类型。

备注

此方法设置的信息附加到单个内核实例。每次使用时都会创建新的内核实例 program.kernel 属性访问。因此，以下措施将不起作用：

prg = cl.Program(...).build()
prg.kernel.set_scalar_arg_dtypes(...)
prg.kernel(queue, n_globals, None, args)

__call__(queue, global_size, local_size, *args, global_offset=None, wait_for=None, g_times_l=False, allow_empty_ndrange=False)[源代码]#

使用 enqueue_nd_range_kernel() 在使用 set_args() 依次设置每个参数。有关详细信息，请参阅文档 set_arg() 查看允许哪些参数类型。

global_size and local_size are tuples of identical length, with between one and three entries. global_size specifies the overall size of the computational grid: one work item will be launched for every integer point in the grid. local_size specifies the workgroup size, which must evenly divide the global_size in a dimension-by-dimension manner. None may be passed for local_size, in which case the implementation will use an implementation-defined workgroup size. If g_times_l is True, the global size will be multiplied by the local size. (which makes the behavior more like Nvidia CUDA) In this case, global_size and local_size also do not have to have the same number of entries.

allow_empty_ndrange is a bool indicating how an empty NDRange is to be treated, where "empty" means that one or more entries of global_size or local_size are zero. OpenCL itself does not allow enqueueing kernels over empty NDRanges. Setting this flag to True enqueues a marker with a wait list (clEnqueueMarkerWithWaitList) to obtain the synchronization effects that would have resulted from the kernel enqueue. Setting allow_empty_ndrange to True requires OpenCL 1.2 or newer.

Returns a new pyopencl.Event. wait_for may either be None or a list of pyopencl.Event instances for whose completion this command waits before starting exeuction.

备注

__call__() 是 not 线程安全。它使用以下命令设置参数 set_args() 然后跑起来 enqueue_nd_range_kernel() 。另一个线程可能会在做同样的事情时与它竞争，结果还不确定。该问题继承自C级OpenCL API。推荐的解决方案是创建一个内核(即访问 prg.kernel_name 这对应于创建新的内核)。

中讨论了涉及隐式锁的解决方案，并决定不使用该解决方案。 October 2012 。

在 0.92 版本发生变更: local_size 已从关键字参数提升为第三个位置参数。在0.92发布周期中，旧关键字参数的用法将继续被接受，但会发出警告。这是一个向后兼容的更改(勉强！)因为 local_size 因为第三个位置参数只能是 tuple 或 None 。 tuple 实例永远不会有效 Kernel 参数，以及 None 作为参数是有效的，但它在包装器中的处理有一个错误(现已修复)，使其无法工作。

在 2011.1 版本发生变更: 增加了 g_times_l 关键字arg。

在 2020.2 版本发生变更: 增加了 allow_empty_ndrange 关键字参数。

capture_call(output_file, queue, global_size, local_size, *args, global_offset=None, wait_for=None, g_times_l=False)[源代码]#

此方法支持与 __call__() ，但是它没有调用内核，而是编写了一个自包含的PyOpenCL程序 文件名 再现了这种召唤。数据和内核源代码将打包在 文件名 的源代码。

这主要是作为调试辅助。例如，它可以用来自动化为观察到的问题创建一个小型的、自包含的测试用例的任务。它还可以帮助将行为不端的内核与潜在的大型或耗时的外部代码分离开来。

参数:: output_file -- 生成的代码要写入的文件名或类似文件的文件。

要使用，只需更改：

evt = my_kernel(queue, gsize, lsize, arg1, arg2, ...)

到：

evt = my_kernel.capture_call("bug.py", queue, gsize, lsize, arg1, arg2, ...)

在 2013.1 版本加入.

static from_int_ptr(int_ptr_value: int, retain: bool = True) → pyopencl._cl.Kernel#: (静态方法)返回引用C-Level的新的Python对象 cl_kernel 对象指向的位置上的 int_ptr_value 。相关的 clRetain* 函数将在以下情况下被调用 retain 为真。如果对象的前一个所有者将 not 释放引用， retain 应设置为 False ，以有效地将所有权转移到 pyopencl 。

在 2013.2 版本加入.

在 2016.1 版本发生变更: retain 添加了。

int_ptr#: 返回一个整数，该整数与基础 cl_kernel 。使用 from_int_ptr() 以转回为一个Python对象。

在 2013.2 版本加入.

class pyopencl.LocalMemory(size)#

要传递的帮助器类 __local 内核的内存参数。

在 0.91.2 版本加入.

size#: 要提供的本地缓冲区的大小（以字节为单位）。

pyopencl.enqueue_nd_range_kernel(queue, kernel, global_work_size, local_work_size, global_work_offset=None, wait_for=None, g_times_l=False, allow_empty_ndrange=False)#

Returns a new pyopencl.Event. wait_for may either be None or a list of pyopencl.Event instances for whose completion this command waits before starting exeuction.

在 2011.1 版本发生变更: 增加了 g_times_l 关键字arg。

在 2020.2 版本发生变更: 增加了 allow_empty_ndrange 关键字参数。