安装#

从Conda Forge安装#

正在安装PyOpenCL#

到目前为止，安装PyOpenCL最简单的方法是使用 Conda Forge 。Conda Forge是社区维护的用于 Conda 包管理器。以下说明针对的是Linux和MacOS。适用于Windows的类似步骤也应该起作用。

安装一个版本的 miniforge 适合您的系统：：

curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"
bash ./Miniforge3-*.sh
# (answer questions, pick install location)

然后运行：：

source /WHERE/YOU/INSTALLED/MINIFORGE/bin/activate root
conda install pyopencl

您可以在您的用户帐户中安装这些软件，而不需要超级用户/管理员权限。

备注

这将安装一个基于Conda Forge的Conda环境。这不能与基于(更常见的) Python 的Conda环境互换。如果您有一个现有的Conda环境，仅仅遵循下面的说明可能不会起作用。相反，建议的方法是从头开始创建新的环境，从上面的mini forge开始。

通过(Py)OpenCL实现对CPU和GPU的访问#

请注意，如果没有提供通过OpenCL访问硬件的OpenCL设备驱动程序(即所谓的“ICD”，意为“可安装的客户端驱动程序”)，则PyOpenCL就没有乐趣(即无法运行代码)。如果您收到如下错误消息 pyopencl._cl.LogicError: clGetPlatformIDs failed: PLATFORM_NOT_FOUND_KHR ，这意味着已成功安装了PyOpenCL，但尚未安装OpenCL驱动程序。

注意，驱动程序（icd）是PyOpenCL的独立软件。它们可能由您的硬件供应商提供（例如Nvidia或AMD GPU）。如果您有这样的硬件，请参阅下面的说明，了解如何使用Conda Forge的PyOpenCL使这些硬件工作。

需要注意的是，OpenCL并不局限于GPU。事实上，使用OpenCL进行计算不需要特殊的硬件--您现有的CPU就足够了。在Linux或MacOS上，键入：：

conda install pocl

安装基于CPU的OpenCL驱动程序。在MacOS上，PoCL可以提供比操作系统内置的OpenCL驱动程序显著的健壮性(有时还有性能)改进。

在Linux和Windows上，您可以使用英特尔的CPU OpenCL运行时：

conda install intel-opencl-rt

在配备英特尔显卡的Linux Intel Broadwell或更新的处理器上，您可以使用neo：：

conda install intel-compute-runtime

在配备英特尔显卡的Linux Intel Sandybridge或更新的处理器上，您可以使用Beignet：：

conda install beignet

在Linux、Windows和MacOS上，您可以使用Oclgrind检测内存访问错误：

conda install oclgrind

现在可以运行基于PyOpenCL的代码了，比如 code examples 。

使用供应商提供的OpenCL驱动程序（主要在Linux上）#

上面的说明帮助您获得一个基本的OpenCL环境，该环境将独立于您是否有专用硬件（如gpu或fpga）可用。如果你 do 有这样的硬件，请继续阅读如何使其工作。

在Linux上，PyOpenCL通过查找扩展名为 .icd 在目录中。从Conda安装的PyOpenCL将在 /WHERE/YOU/INSTALLED/MINICONDA/etc/OpenCL/vendors . 它们只是简单的文本文件，包含提供OpenCL驱动程序的共享库的文件名或完全限定路径名。

备注

如果您在 Conda environment (即，如果命令行提示符上的环境指示符显示的是 (root) )，则可能需要使用如下所示的路径：

/WHERE/YOU/INSTALLED/MINICONDA/envs/ENVIRONMENTNAME/etc/OpenCL/vendors

请注意，您应该替换 ENVIRONMENTNAME 使用命令行提示符上括号之间显示的环境名称。此路径（对于当前活动的conda环境）可以从环境变量中获得 CONDA_PREFIX ，即

$CONDA_PREFIX/etc/OpenCL/vendors （一旦激活Conda环境）。

在Linux上，如果您安装了其他OpenCL驱动程序（例如GPU），那么这些驱动程序将在 /etc/OpenCL/vendors . 您可以使用以下命令使它们与Conda Forge中的PyOpenCL一起工作：

conda install ocl-icd-system

将确保这些系统范围的ICD在您的conda环境中也可见。另一种方法是，可以手动从 /etc/OpenCL/vendors 进入，例如。， $CONDA_PREFIX/etc/OpenCL/vendors .

如果您想了解更多信息，请参阅 ocl-icd 和它的文档。OCL-ICD是在Linux上从Conda Forge安装时由PyOpenCL使用的“ICD加载器”。它表示后面的代码 libOpenCL.so 。

在MacOS上，使用命令：：

conda install ocl_icd_wrapper_apple

将确保苹果提供的CPU和GPU实现可用。

在Windows上，为Conda Forge打包的PyOpenCL依赖于 Khronos ICD Loader ，并将其打包，以便使用注册表键在操作系统中注册的OpenCL驱动程序自动可用。

从PYPI控制盘安装#

PyOpenCL为大多数流行的OSS和Python版本分发轮子。要查看可用的版本，请访问 PyPI page for PyOpenCL 。

在Linux上，轮子带有 OCL-ICD 捆绑并配置为使用任何支持ICD接口的OpenCL实现，并在 /etc/OpenCL/vendors 。Windows和MacOS的车轮是使用Khronos Group的ICD Loader制造的。

要安装，请键入：：

pip install pyopencl

您还可以使用作为二进制轮子提供的pip安装以下基于CPU的OpenCL实现。请注意，必须使用pyopencl的轮子来安装pyopencl，以便识别这些轮子。

要使用PoCL安装pyopencl，基于CPU的实现需要执行以下操作：

pip install pyopencl[pocl]

要使用oclgrind安装pyopencl，OpenCL调试器执行以下操作：

pip install pyopencl[oclgrind]

备注

避免将Conda Forge和PyPI安装的部件混合。例如，从pip安装PyOpenCL，然后从Conda Forge安装OCL-ICD，可以重定向ICD加载程序，从而取消对系统范围ICD的访问。

通过Christoph Gohlke的双轮安装(Windows)#

克里斯托夫·戈尔克分发 binary wheels for PyOpenCL on Windows 。

从源安装#

有关如何安装PyOpenCL的信息 from source 仍然可以在 Former PyOpenCL Wiki ，但除非您有非常特定的需求或想要自己修改PyOpenCL，否则通常不需要这样做。

提示#

语法突出显示#

您可以通过查看以下内容来获得在Python中内联的OpenCL C的Vim语法突出显示 this file 。

请注意，包含源代码的三重引号字符串必须以 """//CL// ...""" 。

IPython集成#

PyOpenCL附带IPython集成，它允许您将PyOpenCL内核无缝集成到IPython笔记本中。只需使用以下命令加载PyOpenCL IPython扩展：

%load_ext pyopencl.ipython_ext

然后使用 %%cl_kernel 'cell-magic' command. See this notebook (它与PyOpenCL一起提供)用于演示。

方法传递用于生成程序可执行文件的生成选项。 -o 单元格第一行上的标志(位于 %%cl_kernel 指令)。例如：：

%%cl_kernel -o "-cl-fast-relaxed-math"

还有线条魔术： cl_load_edit_kernel 将文件加载到下一个单元格（添加 cl_kernel 到第一行）和 cl_kernel_from_file 它将编译一个文件的内核（就好像你将文件的内容复制并粘贴到一个带有 cl_kernel ). 这两种魔法都有选择 -f 指定文件和 -o 用于生成选项。

在 2014.1 版本加入.

指南#

API稳定性#

我认为PyOpenCL的API是“稳定的”。但这并不意味着它不能改变。但如果这样做了，您的代码通常会继续运行。不过，它可能会开始对您需要更改的内容发出警告，以保持与未来版本的兼容性。

如发布名称中的第一个数字所示，弃用警告将持续一整年。（“2014.1”中的“2014”），即2014.n中不推荐使用的函数通常将在2015.n（或更高版本）中删除。此外，稳定性承诺适用于作为已发布版本一部分的任何代码。它不适用于API的未记录位，也不适用于从git下载的未发布代码。

与OpenCL的C绑定的关系#

在将OpenCL的C接口绑定到Python时，我们尝试遵循以下准则：

  • 移除 cl_ ， CL_ 和 cl 来自数据类型、宏和函数名的前缀。

  • 跟随 PEP 8 ，即

    • 使函数名小写。

    • 如果数据类型或函数名由多个单词组成，请用下划线分隔这些单词。

  • get_info 功能变成了属性。

  • 对象创建尽可能由构造函数完成。（即尽量减少使用“工厂功能”）

  • 如果一个操作涉及两个或多个“复杂”对象（例如，一个内核排队涉及一个内核和一个队列），请拒绝猜测哪一个应该得到该操作的方法的诱惑。相反，只需将该命令保留为函数即可。

与其他OpenCL软件的互操作性#

几乎所有的东西 pyopencl 支持以下接口（此处显示为 pyopencl.MemoryObject ，从中 pyopencl.Buffer 和 pyopencl.Image 继承）：

这允许将指向OpenCL对象的C级指针检索为Python整数，然后可以将其传递给接口公开OpenCL对象的其他C库。它还允许将从其他软件获得的C级OpenCL对象转换为相应的 pyopencl 物体。

在 2013.2 版本加入.

用户可见的更改#

未发布#

备注

该版本目前正在开发中。您可以从PyOpenCL的 git repository 。

版本2022.2#

版本2020.2#

  • 删除python2支持。

  • 添加 allow_empty_ndrange 内核排队。

  • 错误修复。

版本2018.2#

  • 使用pybind11。

  • 许多错误修复。

  • 支持扫描内核中带有偏移量的数组。

版本2018.1#

2017.2版#

  • 许多错误修复。

2017.1版#

2016.2版#

2016.1版#

  • 这个 from_int_ptr 方法现在需要 保持 更方便所有权管理的参数。

  • 内核构建选项（如果作为列表传递）现在被正确引用。（这可能会破坏兼容性。）

  • 许多错误修复。（GL interop、Windows、事件回调等）

版本2015.2.4#

  • 使用mingwpy和vs2015修复Windows上的构建。

版本2015.2.3#

  • 再修复一个ubuntu14.x版本问题。

版本2015.2.2#

  • 修复与第1.1条的兼容性

  • 修复与Ubuntu 14.x的兼容性。

  • 各种错误修复

版本2015.2.1#

  • 修正全局内核启动参数

2015.2版#

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

    • 复杂*复杂

    • 真实+复杂

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

  • 基于CFFI重写包装层

  • Pypy兼容性

  • 通过Python启动程序代码生成更快的内核调用

  • PoCL兼容性

2015.1版#

  • 支持新型缓冲协议

  • 大量修复

2014.1版#

版本2013.2#

2013.1版#

备注

增加了 pyopencl.array.Array.__getitem__() 有意想不到的后果，因为 numpy bug 3375 。例如，此表达式：：

numpy.float32(5) * some_pyopencl_array

可能需要很长时间才能执行。这是因为 numpy 首先构建（计算设备）标量（！）的对象数组在它决定这可能不是个好主意并最终打电话给 pyopencl.array.Array.__rmul__ .

注意，只剩下 pyopencl.array.Array 通过 numpy 鳞片受到影响。python的数字类型 (float 不受影响，正确的乘法也不受影响。

如果一个曾经运行得很快的程序突然运行得非常慢，很可能是这个错误造成的。

这就是你能做的：

  • 使用python标量而不是 numpy 标量。

  • 如果可能的话，切换到右边的乘法。

  • 使用补丁 numpy . 请参阅上面链接的bug报告，以获取带有修复的pull请求。

  • 切换到的固定版本 numpy 何时可用。

2012.1版#

  • 支持复数。

  • 支持贝塞尔函数。（实验性）

  • 大量修复。

版本2011.2#

版本2011.1.2#

  • 更多错误修复。

版本2011.1.1#

  • 修复了python3兼容性。（作者：克里斯托夫·高尔克）

版本2011.1#

版本0.92#

版本0.91.5#

版本0.91.4#

一个错误修复版本。没有用户可见的更改。

版本0.91.3#

  • 所有参数都命名为 host_buffer 已重命名 霍斯特布夫 为了与 pyopencl.Buffer 0.91中引入的构造函数。兼容性代码已就位。

  • 这个 pyopencl.Image 构造函数不需要 形状 参数，如果给定 霍斯特布夫 有 hostbuf.shape .

  • 这个 pyopencl.Context 构造函数现在可以在没有参数的情况下调用。

版本0.91.2#

版本0.91.1#

版本0.91#

版本0.90.4#

  • 为Windows和OS X添加生成修复程序。

版本0.90.3#

  • 将GNU ISM固定在包装器的C++代码中。

版本0.90.2#

版本0.90.1#

  • 在Mac上修复建筑。

版本0.90#

  • 首次发布。

许可#

PyOpenCL根据MIT/X联盟许可证授权给您：

版权所有（c）2009-13 Andreas Klöckner和贡献者。

特此免费授予任何获得本软件及其相关文档文件（以下简称“本软件”）副本的人，允许其在不受限制的情况下处理本软件，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或出售本软件副本的权利，并允许他人向其提供软件的国家或地区，但须符合以下条件：

上述版权声明和本许可声明应包含在软件的所有副本或实质部分中。

本软件按“原样”提供，不作任何明示或暗示的保证，包括但不限于对适销性、特定用途适用性和非侵权性的保证。在任何情况下，无论是在合同诉讼、侵权诉讼或其他诉讼中，作者或版权持有人均不承担因本软件或本软件的使用或其他交易而产生、引起或与之相关的任何索赔、损害或其他责任。

PyOpenCL包含部分 Thrust 计算包(特别是扫描实现)。这些部件的许可如下：

版权所有2008-2011英伟达公司

根据Apache许可证2.0版（“许可证”）获得许可；除非符合许可证，否则不得使用此文件。您可以在以下网址获得许可证副本：

除非适用法律要求或书面同意，否则根据许可证分发的软件按“原样”分发，不提供任何形式的明示或暗示保证或条件。请参阅许可证，了解许可证下管理权限和限制的特定语言。

备注

如果您使用apache许可的部件，请注意这些部件可能与gpl2下独家许可的软件不兼容。（大多数软件被授权为GPL2或更高版本，在这种情况下这不是问题。）

PyOpenCL包括Random123随机数生成器套件的一部分：

版权所有2010-2012，D.E.Shaw Research。版权所有。

只要满足以下条件，允许以源形式和二进制形式重新分配和使用，不论是否修改：

  • 重新分发源代码必须保留上述版权声明、此条件列表和以下免责声明。

  • 以二进制形式重新分发时，必须在分发时提供的文档和/或其他材料中复制上述版权声明、此条件列表以及以下免责声明。

  • 未经事先书面许可，不得使用D.E.Shaw Research的名称或其贡献者的姓名来认可或推广从本软件衍生的产品。

本软件由版权所有人和贡献者“按原样”提供，任何明示或暗示的保证，包括但不限于对适销性和特定用途适用性的暗示保证，均不予承认。在任何情况下，版权所有人或贡献者均不对任何直接、间接、偶然、特殊、惩戒性或后果性损害（包括但不限于采购替代货物或服务；使用、数据或利润损失；或业务中断）负责，无论该损害是由何种原因引起的，还是根据任何责任理论，无论是在合同中，因使用本软件而产生的严格责任或侵权（包括疏忽或其他），即使已告知可能造成此类损害。

PyOpenCL包括RANLUXCL随机数生成器：

版权所有（c）2011 Ivar Ursin Nikolaisen

特此免费授予任何获得本软件及其相关文档文件（以下简称“本软件”）副本的人，允许其在不受限制的情况下处理本软件，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或出售本软件副本的权利，并允许他人向其提供软件的国家或地区，但须符合以下条件：

上述版权声明和本许可声明应包含在软件的所有副本或实质部分中。

本软件按“原样”提供，不作任何明示或暗示的保证，包括但不限于对适销性、特定用途适用性和非侵权性的保证。在任何情况下，无论是在合同诉讼、侵权诉讼或其他诉讼中，作者或版权持有人均不承担因本软件或本软件的使用或其他交易而产生、引起或与之相关的任何索赔、损害或其他责任。

常见问题#

常见问题以协作方式在 Wiki FAQ page 。

引用PyOpenCL#

我们不是要求您在与软件无关的工作中无缘无故地引用PyOpenCL。也就是说，如果您确实讨论了代码的一些开发方面，并想重点介绍一些PyOpenCL背后的思想，请随意引用 this article ：

Andreas Klóckner、Nicolas Pinto、Yunsup Lee、Bryan Catanzaro、Paul Ivanov、Ahmed Fasih、Pycuda和PyOpenCl:基于脚本的GPU运行时代码生成方法，并行计算，第38卷，第3期，2012年3月，第157-174页。

为了您的方便，这里有一个bibtex条目：

@article{kloeckner_pycuda_2012,
   author = {{Kl{\"o}ckner}, Andreas
        and {Pinto}, Nicolas
        and {Lee}, Yunsup
        and {Catanzaro}, B.
        and {Ivanov}, Paul
        and {Fasih}, Ahmed },
   title = "{PyCUDA and PyOpenCL: A Scripting-Based Approach to GPU Run-Time Code Generation}",
   journal = "Parallel Computing",
   volume = "38",
   number = "3",
   pages = "157--174",
   year = "2012",
   issn = "0167-8191",
   doi = "10.1016/j.parco.2011.09.001",
}

致谢#

贡献者#

太多了，无法列出。请参阅 commit log 以获取详细的确认。

基金#

关于Pytential的工作部分得到了以下支持

  • 美国国家科学基金会资助编号为DMS-1418961、DMS-1654756、SHF-1911019和OAC-1931577，以及

  • 美国国家核安全局能源部，获奖编号DE-NA0003963。

AK还感谢NVIDIA公司赠送的硬件礼物。

本报告所表达的观点和意见不一定反映供资机构的观点和意见。

文件交叉引用#

Numpy#

class numpy.int8#

见 numpy.generic .

class numpy.int32#

见 numpy.generic .

class numpy.float64#

见 numpy.generic .

OpenCL规范#

type cl_platform_id#

请参阅 CL specification 。

type cl_device_id#

请参阅 CL specification 。

type cl_context#

请参阅 CL specification 。

type cl_command_queue#

请参阅 CL specification 。

type cl_mem#

请参阅 CL specification 。

type cl_program#

请参阅 CL specification 。

type cl_kernel#

请参阅 CL specification 。

type cl_sampler#

请参阅 CL specification 。

type cl_event#

请参阅 CL specification 。

void clCreateCommandQueueWithProperties()#

请参阅 CL specification 。

void clCreateSamplerWithProperties()#

请参阅 CL specification 。

void clCreatePipe()#

请参阅 CL specification 。

内部类型#

class pyopencl._cl.Platform#

见 pyopencl.Platform .

class pyopencl._cl.Device#

见 pyopencl.Device .

class pyopencl._cl.CommandQueue#

见 pyopencl.CommandQueue .

class pyopencl._cl.Context#

见 pyopencl.Context .

class pyopencl._cl.Event#

见 pyopencl.Event .

class pyopencl._cl.SVMAllocation#

见 pyopencl.SVMAllocation .

class pyopencl._cl.MemoryMap#

见 pyopencl.MemoryMap .

class pyopencl._cl.Sampler#

见 pyopencl.Sampler .

class pyopencl._cl.Program#

见 pyopencl.Program .

class pyopencl._cl._Program#

见 pyopencl.Program .

class pyopencl._cl.Kernel#

见 pyopencl.Kernel .