安装

从Conda Forge安装

到目前为止,安装PyOpenCL最简单的方法是使用 Conda Forge . Conda Forge是一个社区维护的软件包存储库 Conda 包管理器。

在Linux或OS X上,以下指令集应该可以工作:

  1. 安装的版本 miniforgeminiconda 适合你的系统。您可以在您的用户帐户中安装这些软件,而不需要root/管理员权限。

    请注意,如果您的系统上已经安装了Continuum Anaconda,您可以直接使用它并执行以下操作 not 需要安装微型 Python 。

  2. source /WHERE/YOU/INSTALLED/MINICONDA/bin/activate root

  3. conda config --add channels conda-forge

  4. conda install pyopencl

Windows的类似步骤也应该起作用。

请注意,如果没有提供通过OpenCL访问硬件的OpenCL设备驱动程序(所谓的“ICD”,用于“可安装的客户端驱动程序”),PyOpenCL就没有乐趣(即无法运行代码)。如果你收到这样的错误信息 pyopencl.cffi_cl.LogicError: clGetPlatformIDs failed: <unknown error -1001> ,这意味着您没有安装OpenCL驱动程序。

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

需要注意的是OpenCL并不局限于gpu。事实上,使用OpenCL进行计算不需要特殊的硬件——您现有的CPU就足够了。在Linux或macOS上,键入:

  1. conda install pocl

安装基于CPU的OpenCL驱动程序。在Windows上,您可以安装 CPU OpenCL driver from Intel . 在macOS上,pocl可以提供比内置在操作系统中的OpenCL驱动程序显著的健壮性(有时还有性能)改进。

在Linux和macOS上,可以使用Oclgrind检测内存访问错误。

  1. conda install oclgrind

在Linux Intel Broadwell或具有Intel图形卡的较新处理器上,可以使用NEO。

  1. conda install intel-compute-runtime

在Linux Intel Sandybridge或更新的带有Intel图形卡的处理器上,可以使用Beignet。

  1. conda install beignet

现在可以运行基于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是PyOpenCL在Linux上从Conda Forge安装时使用的“icd加载程序”。它表示后面的代码 libOpenCL.so .

在macOS上,用于Conda Forge的PyOpenCL的打包依赖于 Khronos ICD Loader ,并且它的打包使得内置到操作系统中的OpenCL驱动程序除了手动安装的其他icd之外,还可以自动使用。

使用Linux控制盘从PyPI安装

PyOpenCL在PyPI中分配manylinux1轮。这些轮子与基于GLIBC>=2.5的发行版兼容。

在Linux上,键入

  1. pip install pyopencl

wheels附带了OCL-ICD,并配置为使用任何支持ICD接口的OpenCL实现 /etc/OpenCL/vendors

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

要用pocl安装pyopencl,一种基于CPU的实现方法,

  1. pip install pyopencl[pocl]

要用oclgrind安装pyopencl,OpenCL调试器需要,

  1. pip install pyopencl[oclgrind]

注解

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

从源安装

有关如何安装PyOpenCL的信息 从源头PyOpenCL Wiki ,但除非您有非常特殊的需求或希望自己修改PyOpenCL,否则这应该不是必需的。

提示

语法突出显示

您可以通过检查 this file .

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

IPython集成

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

%load_ext pyopencl.ipython_ext

然后使用 %%cl_kernel “细胞魔法”命令。看到了吗 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.Bufferpyopencl.Image 继承):

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

2013.2 新版功能.

用户可见的更改

版本2020.3

注解

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

版本2020.2

  • 删除python2支持。

  • 添加 allow_empty_ndrange 内核排队。

  • 错误修复。

版本2018.2

  • 使用pybind11。

  • 许多错误修复。

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

版本2018.1

  • 介绍 eliminate_empty_output_lists 的参数 pyopencl.algorithm.ListOfListsBuilder .

  • 许多错误修复。

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的复数从 float2double2 要自定义的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

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

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

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

常见问题

FAQ以协作方式维护在 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 详细的致谢。

基金

Andreas Klöckner关于 pyopencl 部分支持

  • 美国海军ONR授权号N00014-14-1-0117

  • 美国国家科学基金会,授权号DMS-1418961和CCF-1524433。

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 .