The Array Class

class pyopencl.array.DefaultAllocator(context, flags=pyopencl.mem_flags.READ_WRITE)

An Allocator that uses pyopencl.Buffer with the given flags.

__call__(self, size)
class pyopencl.array.Array(context, shape, dtype, order="C", allocator=None, base=None, data=None, queue=None)

A numpy.ndarray work-alike that stores its data and performs its computations on the compute device. shape and dtype work exactly as in numpy. Arithmetic methods in Array support the broadcasting of scalars. (e.g. array+5) If the

allocator is a callable that, upon being called with an argument of the number of bytes to be allocated, returns an object that can be cast to an int representing the address of the newly allocated memory. (See DefaultAllocator.)

data
The pyopencl.MemoryObject instance created for the memory that backs this Array.
shape
The tuple of lengths of each dimension in the array.
dtype
The numpy.dtype of the items in the GPU array.
size
The number of meaningful entries in the array. Can also be computed by multiplying up the numbers in shape.
mem_size
The total number of entries, including padding, that are present in the array.
nbytes
The size of the entire array in bytes. Computed as size times dtype.itemsize.
__len__()
Returns the size of the leading dimension of self.
set(ary, queue=None, async=False)

Transfer the contents the numpy.ndarray object ary onto the device.

ary must have the same dtype and size (not necessarily shape) as self.

get(queue=None, ary=None, async=False)
Transfer the contents of self into ary or a newly allocated numpy.ndarray. If ary is given, it must have the right size (not necessarily shape) and dtype.
__str__()
__repr__()
mul_add(self, selffac, other, otherfac, queue=None):
Return selffac*self + otherfac*other.
__add__(other)
__sub__(other)
__iadd__(other)
__isub__(other)
__neg__(other)
__mul__(other)
__div__(other)
__rdiv__(other)
__pow__(other)
__abs__()
Return a Array containing the absolute value of each element of self.
fill(scalar, queue=None)
Fill the array with scalar.
astype(dtype, queue=None)
Return self, cast to dtype.

Constructing Array Instances

pyopencl.array.to_device(context, queue, ary, allocator=None, async=False)

Return a Array that is an exact copy of the numpy.ndarray instance ary.

See Array for the meaning of allocator.

pyopencl.array.empty(context, shape, dtype, order="C", allocator=None, base=None, data=None, queue=None)
A synonym for the Array constructor.
pyopencl.array.zeros(context, queue, shape, dtype, order="C", allocator=None)
Same as empty(), but the Array is zero-initialized before being returned.
pyopencl.array.empty_like(other_ary)
Make a new, uninitialized Array having the same properties as other_ary.
pyopencl.array.zeros_like(other_ary)
Make a new, zero-initialized Array having the same properties as other_ary.
pyopencl.array.arange(context, queue, start, stop, step, dtype=None)

Create a Array filled with numbers spaced step apart, starting from start and ending at stop.

For floating point arguments, the length of the result is ceil((stop - start)/step). This rule may result in the last element of the result being greater than stop.

dtype, if not specified, is taken as the largest common type of start, stop and step.

pyopencl.array.take(a, indices, out=None, queue=None)
Return the Array [a[indices[0]], ..., a[indices[n]]]. For the moment, a must be a type that can be bound to a texture.

Conditionals

pyopencl.array.if_positive(criterion, then_, else_, out=None, queue=None)
Return an array like then_, which, for the element at index i, contains then_[i] if criterion[i]>0, else else_[i]. (added in 0.94)
pyopencl.array.maximum(a, b, out=None, queue=None)
Return the elementwise maximum of a and b. (added in 0.94)
pyopencl.array.minimum(a, b, out=None, queue=None)
Return the elementwise minimum of a and b. (added in 0.94)

Elementwise Functions on Arrray Instances

The pyopencl.clmath module contains exposes array versions of the C functions available in the OpenCL standard. (See table 6.8 in the spec.)

pyopencl.clmath.acos(array, queue=None)
pyopencl.clmath.acosh(array, queue=None)
pyopencl.clmath.acospi(array, queue=None)
pyopencl.clmath.asin(array, queue=None)
pyopencl.clmath.asinh(array, queue=None)
pyopencl.clmath.asinpi(array, queue=None)
pyopencl.clmath.atan(array, queue=None)
pyopencl.clmath.atanh(array, queue=None)
pyopencl.clmath.atanpi(array, queue=None)
pyopencl.clmath.cbrt(array, queue=None)
pyopencl.clmath.ceil(array, queue=None)
pyopencl.clmath.cos(array, queue=None)
pyopencl.clmath.cosh(array, queue=None)
pyopencl.clmath.cospi(array, queue=None)
pyopencl.clmath.erfc(array, queue=None)
pyopencl.clmath.erf(array, queue=None)
pyopencl.clmath.exp(array, queue=None)
pyopencl.clmath.exp2(array, queue=None)
pyopencl.clmath.exp10(array, queue=None)
pyopencl.clmath.expm1(array, queue=None)
pyopencl.clmath.fabs(array, queue=None)
pyopencl.clmath.floor(array, queue=None)
pyopencl.clmath.fmod(arg, mod, queue=None)
Return the floating point remainder of the division arg/mod, for each element in arg and mod.
pyopencl.clmath.frexp(arg, queue=None)
Return a tuple (significands, exponents) such that arg == significand * 2**exponent.
pyopencl.clmath.ilogb(array, queue=None)
pyopencl.clmath.ldexp(significand, exponent, queue=None)
Return a new array of floating point values composed from the entries of significand and exponent, paired together as result = significand * 2**exponent.
pyopencl.clmath.lgamma(array, queue=None)
pyopencl.clmath.log(array, queue=None)
pyopencl.clmath.log2(array, queue=None)
pyopencl.clmath.log10(array, queue=None)
pyopencl.clmath.log1p(array, queue=None)
pyopencl.clmath.logb(array, queue=None)
pyopencl.clmath.modf(arg, queue=None)
Return a tuple (fracpart, intpart) of arrays containing the integer and fractional parts of arg.
pyopencl.clmath.nan(array, queue=None)
pyopencl.clmath.rint(array, queue=None)
pyopencl.clmath.round(array, queue=None)
pyopencl.clmath.sin(array, queue=None)
pyopencl.clmath.sinh(array, queue=None)
pyopencl.clmath.sinpi(array, queue=None)
pyopencl.clmath.sqrt(array, queue=None)
pyopencl.clmath.tan(array, queue=None)
pyopencl.clmath.tanh(array, queue=None)
pyopencl.clmath.tanpi(array, queue=None)
pyopencl.clmath.tgamma(array, queue=None)
pyopencl.clmath.trunc(array, queue=None)

Generating Arrays of Random Numbers

pyopencl.clrandom.rand(context, queue, shape, dtype)
Return an array of shape filled with random values of dtype in the range [0,1).

Single-pass Custom Expression Evaluation

Warning

The following functionality is included in this documentation in the hope that it may be useful, but its interface may change in future revisions. Feedback is welcome.

Evaluating involved expressions on pyopencl.array.Array instances can be somewhat inefficient, because a new temporary is created for each intermediate result. The functionality in the module pyopencl.elementwise contains tools to help generate kernels that evaluate multi-stage expressions on one or several operands in a single pass.

class pyopencl.elementwise.ElementwiseKernel(context, arguments, operation, name="kernel", options=[])

Generate a kernel that takes a number of scalar or vector arguments and performs the scalar operation on each entry of its arguments, if that argument is a vector.

arguments is specified as a string formatted as a C argument list. operation is specified as a C assignment statement, without a semicolon. Vectors in operation should be indexed by the variable i.

name specifies the name as which the kernel is compiled, and options are passed unmodified to pyopencl.Program.build().

__call__(*args)
Invoke the generated scalar kernel. The arguments may either be scalars or GPUArray instances.

Here’s a usage example:

import pyopencl as cl
import pyopencl.array as cl_array
import numpy

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

n = 10
a_gpu = cl_array.to_device(
        ctx, queue, numpy.random.randn(n).astype(numpy.float32))
b_gpu = cl_array.to_device(
        ctx, queue, numpy.random.randn(n).astype(numpy.float32))

from pyopencl.elementwise import ElementwiseKernel
lin_comb = ElementwiseKernel(ctx,
        "float a, float *x, "
        "float b, float *y, "
        "float *z",
        "z[i] = a*x[i] + b*y[i]",
        "linear_combination")

c_gpu = cl_array.empty_like(a_gpu)
lin_comb(5, a_gpu, 6, b_gpu, c_gpu)

import numpy.linalg as la
assert la.norm((c_gpu - (5*a_gpu+6*b_gpu)).get()) < 1e-5

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

Fast Fourier Transforms

Bogdan Opanchuk’s pyfft package offers a variety of GPU-based FFT implementations.