Installation

Installation information is maintained collaboratively on the PyOpenCL Wiki.

Tips

Syntax highlighting

You can obtain Vim syntax highlighting for OpenCL C inlined in Python by checking this file.

Note that the triple-quoted strings containing the source must start with “”“//CL// ...”“”.

IPython integration

PyOpenCL comes with IPython integration, which lets you seamlessly integrate PyOpenCL kernels into your IPython notebooks. Simply load the PyOpenCL IPython extension using:

%load_ext pyopencl.ipython_ext

and then use the %%cl_kernel ‘cell-magic’ command. See this notebook (which ships with PyOpenCL) for a demonstration.

You can pass build options to be used for building the program executable by using the -o flag on the first line of the cell (next to the %%cl_kernel directive). For example: %%cl_kernel -o “-cl-fast-relaxed-math”`.

There are also line magics: cl_load_edit_kernel which will load a file into the next cell (adding cl_kernel to the first line) and cl_kernel_from_file which will compile kernels from a file (as if you copy-and-pasted the contents of the file to a cell with cl_kernel). Both of these magics take options -f to specify the file and optionally -o for build options.

New in version 2014.1.

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 year, as identified by the first number in the release name. (the “2014” in “2014.1”) I.e. a function that was deprecated in 2014.n will generally be removed in 2015.n (or perhaps later). 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.

Interoperability with other OpenCL software

Just about every object in pyopencl supports the following interface (here shown as an example for pyopencl.MemoryObject, from which pyopencl.Buffer and pyopencl.Image inherit):

This allows retrieving the C-level pointer to an OpenCL object as a Python integer, which may then be passed to other C libraries whose interfaces expose OpenCL objects. It also allows turning C-level OpenCL objects obtained from other software to be turned into the corresponding pyopencl objects.

New in version 2013.2.

User-visible Changes

Version 2016.3

Note

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

Version 2016.2

Version 2016.1

  • The from_int_ptr methods now take a retain parameter for more convenient ownership management.
  • Kernel build options (if passed as a list) are now properly quoted. (This is a potentially compatibility-breaking change.)
  • Many bug fixes. (GL interop, Windows, event callbacks and more)

Version 2015.2.4

  • Fix building on Windows, using mingwpy and VS 2015.

Version 2015.2.3

  • Fix one more Ubuntu 14.x build issue.

Version 2015.2.2

  • Fix compatibility with CL 1.1
  • Fix compatibility with Ubuntu 14.x.
  • Various bug fixes

Version 2015.2.1

  • Fix global_offset kernel launch parameter

Version 2015.2

  • [INCOMPATIBLE] Changed PyOpenCL’s complex numbers from float2 and double2 OpenCL vector types to custom struct. This was changed because it very easily introduced bugs where

    • complex*complex
    • real+complex

    look like they may do the right thing, but silently do the wrong thing.

  • Rewrite of the wrapper layer to be based on CFFI

  • Pypy compatibility

  • Faster kernel invocation through Python launcher code generation

  • POCL compatibility

Version 2015.1

  • Support for new-style buffer protocol
  • Numerous fixes

Version 2014.1

  • ipython-integration
  • Bug fixes

Version 2013.2

Version 2013.1

Note

The addition of pyopencl.array.Array.__getitem__() has an unintended consequence due to numpy bug 3375. For instance, this expression:

numpy.float32(5) * some_pyopencl_array

may take a very long time to execute. This is because numpy first builds an object array of (compute-device) scalars (!) before it decides that that’s probably not such a bright idea and finally calls pyopencl.array.Array.__rmul__().

Note that only left arithmetic operations of pyopencl.array.Array by numpy scalars are affected. Python’s number types (float etc.) are unaffected, as are right multiplications.

If a program that used to run fast suddenly runs extremely slowly, it is likely that this bug is to blame.

Here’s what you can do:

  • Use Python scalars instead of numpy scalars.
  • Switch to right multiplications if possible.
  • Use a patched numpy. See the bug report linked above for a pull request with a fix.
  • Switch to a fixed version of numpy when available.

Version 2012.1

  • Support for complex numbers.
  • Support for Bessel functions. (experimental)
  • Numerous fixes.

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

Version 0.92

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

Version 0.91.1

Version 0.91

  • Add OpenCL Runtime: OpenGL 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

Version 0.90.1

  • Fix building on the Mac.

Version 0.90

  • Initial release.

License

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

Copyright (c) 2009-13 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

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 parts of the Random123 suite of random number generators:

Copyright 2010-2012, D. E. Shaw Research. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  • Redistributions of source code must retain the above copyright notice, this list of conditions, and the following disclaimer.
  • Redistributions in binary form must reproduce the above copyright notice, this list of conditions, and the following disclaimer in the documentation and/or other materials provided with the distribution.
  • Neither the name of D. E. Shaw Research nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

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

Acknowledgments

Contributors

Too many to list. Please see the commit log for detailed acknowledgments.

Funding

Andreas Klöckner’s work on pyopencl was supported in part by

  • US Navy ONR grant number N00014-14-1-0117
  • the US National Science Foundation under grant numbers DMS-1418961 and CCF-1524433.

AK also gratefully acknowledges a hardware gift from Nvidia Corporation. The views and opinions expressed herein do not necessarily reflect those of the funding agencies.