Welcome to PyOpenCL’s documentation!

PyOpenCL gives you easy, Pythonic access to the OpenCL parallel computation API. What makes PyOpenCL special?

  • Object cleanup tied to lifetime of objects. This idiom, often called RAII in C++, makes it much easier to write correct, leak- and crash-free code.
  • Completeness. PyOpenCL puts the full power of OpenCL’s API at your disposal, if you wish. Every obscure get_info() query and all CL calls are accessible.
  • Automatic Error Checking. All errors are automatically translated into Python exceptions.
  • Speed. PyOpenCL’s base layer is written in C++, so all the niceties above are virtually free.
  • Helpful Documentation. You’re looking at it. ;)
  • Liberal license. PyOpenCL is open-source under the MIT license and free for commercial, academic, and private use.

Here’s an example, to give you an impression:

#!/usr/bin/env python
# -*- coding: utf-8 -*-

import numpy as np
import pyopencl as cl

a_np = np.random.rand(50000).astype(np.float32)
b_np = np.random.rand(50000).astype(np.float32)

ctx = cl.create_some_context()
queue = cl.CommandQueue(ctx)

mf = cl.mem_flags
a_g = cl.Buffer(ctx, mf.READ_ONLY | mf.COPY_HOST_PTR, hostbuf=a_np)
b_g = cl.Buffer(ctx, mf.READ_ONLY | mf.COPY_HOST_PTR, hostbuf=b_np)

prg = cl.Program(ctx, """
__kernel void sum(__global const float *a_g, __global const float *b_g, __global float *res_g) {
  int gid = get_global_id(0);
  res_g[gid] = a_g[gid] + b_g[gid];
}
""").build()

res_g = cl.Buffer(ctx, mf.WRITE_ONLY, a_np.nbytes)
prg.sum(queue, a_np.shape, None, a_g, b_g, res_g)

res_np = np.empty_like(a_np)
cl.enqueue_copy(queue, res_np, res_g)

# Check on CPU with Numpy:
print(res_np - (a_np + b_np))
print(np.linalg.norm(res_np - (a_np + b_np)))

(You can find this example as examples/demo.py in the PyOpenCL source distribution.)

Tutorials

Software that works with or enhances PyOpenCL

  • Bogdan Opanchuk’s reikna offers a variety of GPU-based algorithms (FFT, random number generation, matrix multiplication) designed to work with pyopencl.array.Array objects.
  • Gregor Thalhammer’s gpyfft provides a Python wrapper for the OpenCL FFT library clFFT from AMD.

If you know of a piece of software you feel that should be on this list, please let me know, or, even better, send a patch!

Indices and tables