Installation

Installation information is maintained collaboratively on the PyOpenCL Wiki.

Acknowledgments

• James Snyder provided patches to make PyOpenCL work on OS X 10.6.
• Roger Pau Monné supplied the example examples/benchmark-all.py.
• David Garcia contributed significantly to PyOpenCL’s API design and reported many bugs.
• Michal Januszewski sent a patch.
• Achim Gottinger submitted a fix for an example.
• Andrew Karpushin provided a fix for a whole class of crash bugs in PyOpenCL.
• Paolo Simone Gasparello, Keith Brafford, and Ian Johnson provided much help in getting OpenCL-OpenGL interoperability to work.
• Sean True allowed access to a test machine to ensure compatibility with OS X Lion.
• Tomasz Rybak did many great things for PyOpenCL, not the least of which is packaging for Debian and Ubuntu.

Guidelines

API Stability

I consider PyOpenCL’s API “stable”. That doesn’t mean it can’t change. But if it does, your code will generally continue to run. It may however start spewing warnings about things you need to change to stay compatible with future versions.

Deprecation warnings will be around for a whole release cycle, as identified by the second number in the release name. (the “90” in “0.90”) Further, the stability promise applies for any code that’s part of a released version. It doesn’t apply to undocumented bits of the API, and it doesn’t apply to unreleased code downloaded from git.

Relation with OpenCL’s C Bindings

We’ve tried to follow these guidelines when binding the OpenCL’s C interface to Python:

• Remove the cl_, CL_ and cl prefix from data types, macros and function names.
• Follow PEP 8, i.e.
  • Make function names lowercase.
  • If a data type or function name is composed of more than one word, separate the words with a single underscore.
• get_info functions become attributes.
• Object creation is done by constructors, to the extent possible. (i.e. minimize use of “factory functions”)
• If an operation involves two or more “complex” objects (like e.g. a kernel enqueue involves a kernel and a queue), refuse the temptation to guess which one should get a method for the operation. Instead, simply leave that command to be a function.

User-visible Changes

Version 2012.1

Note

This version is currently under development. You can get snapshots from PyOpenCL’s git version control.

• Support for complex numbers.

Version 2011.2

• Add pyopencl.enqueue_migrate_mem_object().
• Add pyopencl.image_from_array().
• IMPORTANT BUGFIX: Kernel caching was broken for all the 2011.1.x releases, with severe consequences on the execution time of pyopencl.array.Array operations. Henrik Andresen at a PyOpenCL workshop at DTU first noticed the strange timings.
• All comparable PyOpenCL objects are now also hashable.
• Add pyopencl.tools.context_dependent_memoize() to the documented functionality.
• Base pyopencl.clrandom on RANLUXCL, add functionality.
• Add pyopencl.NannyEvent objects.
• Add pyopencl.characterize.
• Ensure compatibility with OS X Lion.
• Add pyopencl.tools.register_dtype() to enable scan/reduction on struct types.
• pyopencl.enqueue_migrate_mem_object() was renamed pyopencl.enqueue_migrate_mem_object_ext(). pyopencl.enqueue_migrate_mem_object() now refers to the OpenCL 1.2 function of this name, if available.
• pyopencl.create_sub_devices() was renamed pyopencl.create_sub_devices_ext(). pyopencl.create_sub_devices() now refers to the OpenCL 1.2 function of this name, if available.
• Alpha support for OpenCL 1.2.

Version 2011.1.2

• More bug fixes.

Version 2011.1.1

• Fixes for Python 3 compatibility. (with work by Christoph Gohlke)

Version 2011.1

• All is_blocking parameters now default to True to avoid crashy-by-default behavior. (suggested by Jan Meinke) In particular, this change affects pyopencl.enqueue_read_buffer(), pyopencl.enqueue_write_buffer(), pyopencl.enqueue_read_buffer_rect(), pyopencl.enqueue_write_buffer_rect(), pyopencl.enqueue_read_image(), pyopencl.enqueue_write_image(), pyopencl.enqueue_map_buffer(), pyopencl.enqueue_map_image().
• Add pyopencl.reduction.
• Add Reductions.
• Add pyopencl.scan.
• Add pyopencl.MemoryObject.get_host_array().
• Deprecate context arguments of pyopencl.array.to_device(), pyopencl.array.zeros(), pyopencl.array.arange().
• Make construction of pyopencl.array.Array more flexible (cqa argument.)
• Add Memory Pools.
• Add vector types, see pyopencl.array.vec.
• Add pyopencl.array.Array.strides, pyopencl.array.Array.flags. Allow the creation of arrys in C and Fortran order.
• Add pyopencl.enqueue_copy(). Deprecate all other transfer functions.
• Add support for numerous extensions, among them device fission.
• Add a compiler cache.
• Add the ‘g_times_l’ keyword arg to kernel execution.

Version 0.92

• Add support for OpenCL 1.1.
• Add support for the cl_khr_gl_sharing extension, leading to working GL interoperability.
• Add pyopencl.Kernel.set_args().
• The call signature of pyopencl.Kernel.__call__() changed to emphasize the importance of local_size.
• Add pyopencl.Kernel.set_scalar_arg_dtypes().
• Add support for the cl_nv_device_attribute_query extension.
• Add pyopencl.array.Array() and related functionality.
• Make build not depend on Boost C++.

Version 0.91.5

• Add pyopencl.ImageFormat.channel_count, pyopencl.ImageFormat.dtype_size, pyopencl.ImageFormat.itemsize.
• Add missing pyopencl.enqueue_copy_buffer().
• Add pyopencl.create_some_context().
• Add pyopencl.enqueue_barrier(), which was previously missing.

Version 0.91.4

A bugfix release. No user-visible changes.

Version 0.91.3

• All parameters named host_buffer were renamed hostbuf for consistency with the pyopencl.Buffer constructor introduced in 0.91. Compatibility code is in place.
• The pyopencl.Image constructor does not need a shape parameter if the given hostbuf has hostbuf.shape.
• The pyopencl.Context constructor can now be called without parameters.

Version 0.91.2

• pyopencl.Program.build() now captures build logs and adds them to the exception text.
• Deprecate pyopencl.create_context_from_type() in favor of second form of pyopencl.Context constructor
• Introduce pyopencl.LocalMemory.
• Document kernel invocation and pyopencl.Kernel.set_arg().

Version 0.91.1

• Fixed a number of bugs, notably involving pyopencl.Sampler.
• pyopencl.Device, pyopencl.Platform, pyopencl.Context now have nicer string representations.
• Add Image.shape. (suggested by David Garcia)

Version 0.91

• Add GL Interoperability.
• Add a test suite.
• Fix numerous get_info bugs. (reports by David Garcia and the test suite)
• Add pyopencl.ImageFormat.__repr__().
• Add pyopencl.addressing_mode.to_string() and colleagues.
• The pitch arguments to pyopencl.create_image_2d(), pyopencl.create_image_3d(), pyopencl.enqueue_read_image(), and pyopencl.enqueue_write_image() are now defaulted to zero. The argument order of enqueue_{read,write}_image has changed for this reason.
• Deprecate pyopencl.create_image_2d(), pyopencl.create_image_3d() in favor of the pyopencl.Image constructor.
• Deprecate pyopencl.create_program_with_source(), pyopencl.create_program_with_binary() in favor of the pyopencl.Program constructor.
• Deprecate pyopencl.create_buffer(), pyopencl.create_host_buffer() in favor of the pyopencl.Buffer constructor.
• pyopencl.MemoryObject.get_image_info() now actually exists.
• Add pyopencl.MemoryObject.image.info.
• Fix API tracing.
• Add constructor arguments to pyopencl.ImageFormat. (suggested by David Garcia)

Version 0.90.4

• Add build fixes for Windows and OS X.

Version 0.90.3

• Fix a GNU-ism in the C++ code of the wrapper.

Version 0.90.2

• Fix pyopencl.Platform.get_info().
• Fix passing properties to pyopencl.CommandQueue. Also fix related documentation.

Version 0.90.1

• Fix building on the Mac.

Version 0.90

• Initial release.

Licensing

PyOpenCL is licensed to you under the MIT/X Consortium license:

Copyright (c) 2009-11 Andreas Klöckner and Contributors.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

PyOpenCL includes derivatives of parts of the Thrust computing package (in particular the scan implementation). These parts are licensed as follows:

Copyright 2008-2011 NVIDIA Corporation

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

<http://www.apache.org/licenses/LICENSE-2.0>

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Note

If you use Apache-licensed parts, be aware that these may be incompatible with software licensed exclusively under GPL2. (Most software is licensed as GPL2 or later, in which case this is not an issue.)

PyOpenCL includes the RANLUXCL random number generator:

Copyright (c) 2011 Ivar Ursin Nikolaisen

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Frequently Asked Questions

The FAQ is maintained collaboratively on the Wiki FAQ page.

Citing PyOpenCL

We are not asking you to gratuitously cite PyOpenCL in work that is otherwise unrelated to software. That said, if you do discuss some of the development aspects of your code and would like to highlight a few of the ideas behind PyOpenCL, feel free to cite this article:

Andreas Klöckner, Nicolas Pinto, Yunsup Lee, Bryan Catanzaro, Paul Ivanov, Ahmed Fasih, PyCUDA and PyOpenCL: A scripting-based approach to GPU run-time code generation, Parallel Computing, Volume 38, Issue 3, March 2012, Pages 157-174.

Here’s a Bibtex entry for your convenience:

@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",
}