Installation information is maintained collaboratively on the PyOpenCL Wiki.
Too many to list. Please see the commit log for detailed acknowledgments.
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// ...”“”.
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
). Boths of these magics take options -f
to specify the file and optionally -o
for build options.
New in version 2014.1.
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.
We’ve tried to follow these guidelines when binding the OpenCL’s C interface to Python:
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.
Note
This version is currently under development. You can get snapshots from PyOpenCL’s git repository
from_int_ptr
methods now take a retain parameter for more convenient
ownership management.[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
look like they may do the right thing, but sliently 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
pyopencl.array.Array.map_to_host()
.pyopencl.enqueue_map_buffer()
and
pyopencl.enqueue_map_image()
.pyopencl.ImageFormat
was made comparable and hashable.pyopencl.reduction
supports slicing (contributed by Alex Nitz)Vastly improved Prefix Sums (“scan”).
Add pyopencl.tools.match_dtype_to_c_struct()
,
for better integration of the CL and numpy
type systems.
More/improved Bessel functions. See the source.
Add PYOPENCL_NO_CACHE
environment variable to aid debugging.
(e.g. with AMD’s CPU implementation, see
their programming guide)
Deprecated pyopencl.tools.register_dtype()
in favor of
pyopencl.tools.get_or_register_dtype()
.
Clean up the pyopencl.array.Array
constructor interface.
Deprecate pyopencl.array.DefaultAllocator
.
Deprecate pyopencl.tools.CLAllocator
.
Introduce pyopencl.tools.DeferredAllocator
, pyopencl.tools.ImmediateAllocator
.
Allow arrays whose beginning does not coincide with the beginning of their
pyopencl.array.Array.data
pyopencl.Buffer
.
See pyopencl.array.Array.base_data
and pyopencl.array.Array.offset
.
Note that not all functions in PyOpenCL support such arrays just yet. These
will fail with pyopencl.array.ArrayHasOffsetError
.
Add pyopencl.array.Array.__getitem__()
and pyopencl.array.Array.__setitem__()
,
supporting generic slicing.
It is possible to create non-contiguous arrays using this functionality. Most operations (elementwise etc.) will not work on such arrays.
Note also that some operations (specifically, reductions and scans) on sliced arrays that start past the beginning of the original array will fail for now. This will be fixed in a future release.
pyopencl.CommandQueue
may be used as a context manager (in a with
statement)
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:
numpy
scalars.numpy
. See the bug report linked above for a pull
request with a fix.numpy
when available.pyopencl.enqueue_migrate_mem_object()
.pyopencl.image_from_array()
.pyopencl.array.Array
operations.
Henrik Andresen at a PyOpenCL workshop at DTU
first noticed the strange timings.pyopencl.tools.context_dependent_memoize()
to the documented
functionality.pyopencl.clrandom
on RANLUXCL,
add functionality.pyopencl.NannyEvent
objects.pyopencl.characterize
.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.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()
.pyopencl.reduction
.pyopencl.scan
.pyopencl.MemoryObject.get_host_array()
.pyopencl.array.to_device()
,
pyopencl.array.zeros()
,
pyopencl.array.arange()
.pyopencl.array.Array
more flexible (cqa argument.)pyopencl.array.vec
.pyopencl.array.Array.strides
, pyopencl.array.Array.flags
.
Allow the creation of arrys in C and Fortran order.pyopencl.enqueue_copy()
. Deprecate all other transfer functions.pyopencl.Kernel.set_args()
.pyopencl.Kernel.__call__()
changed to
emphasize the importance of local_size.pyopencl.Kernel.set_scalar_arg_dtypes()
.pyopencl.array.Array()
and related functionality.pyopencl.ImageFormat.channel_count
,
pyopencl.ImageFormat.dtype_size
,
pyopencl.ImageFormat.itemsize
.pyopencl.enqueue_copy_buffer()
.pyopencl.create_some_context()
.pyopencl.enqueue_barrier()
, which was previously missing.A bugfix release. No user-visible changes.
pyopencl.Buffer
constructor introduced in 0.91.
Compatibility code is in place.pyopencl.Image
constructor does not need a shape parameter if the
given hostbuf has hostbuf.shape.pyopencl.Context
constructor can now be called without parameters.pyopencl.Program.build()
now captures build logs and adds them
to the exception text.pyopencl.create_context_from_type()
in favor of second
form of pyopencl.Context
constructorpyopencl.LocalMemory
.pyopencl.Kernel.set_arg()
.pyopencl.Sampler
.pyopencl.Device
, pyopencl.Platform
,
pyopencl.Context
now have nicer string representations.Image.shape
. (suggested by David Garcia)pyopencl.ImageFormat.__repr__()
.pyopencl.addressing_mode.to_string()
and colleagues.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.pyopencl.create_image_2d()
,
pyopencl.create_image_3d()
in favor of the pyopencl.Image
constructor.pyopencl.create_program_with_source()
,
pyopencl.create_program_with_binary()
in favor of the pyopencl.Program
constructor.pyopencl.create_buffer()
,
pyopencl.create_host_buffer()
in favor of the pyopencl.Buffer
constructor.pyopencl.MemoryObject.get_image_info()
now actually exists.pyopencl.MemoryObject.image.info
.pyopencl.ImageFormat
. (suggested by David Garcia)pyopencl.Platform.get_info()
.pyopencl.CommandQueue
.
Also fix related documentation.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 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.
The FAQ is maintained collaboratively on the Wiki FAQ page.
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",
}