OpenCL Runtime: Platforms, Devices and Contexts

Platform

pyopencl.get_platforms()

Return a list of Platform instances.

class pyopencl.Platform
info

Lower case versions of the platform_info constants may be used as attributes on instances of this class to directly query info attributes.

get_info(param)

See platform_info for values of param.

get_devices(device_type=device_type.ALL)

Return a list of devices matching device_type. See device_type for values of device_type.

Changed in version 2013.2: This used to raise an exception if no matching devices were found. Now, it will simply return an empty list.

from_int_ptr(int_ptr_value, retain=True)

Constructs a pyopencl handle from a C-level pointer (given as the integer int_ptr_value). If retain is True (the defauult) pyopencl will call clRetainXXX on the provided object. If the previous owner of the object will not release the reference, retain should be set to False, to effectively transfer ownership to pyopencl.

Changed in version 2016.1: retain added

int_ptr

Instances of this class are hashable, and two instances of this class may be compared using “==” and ”!=”. (Hashability was added in version 2011.2.) Two objects are considered the same if the underlying OpenCL object is the same, as established by C pointer equality.

Device

class pyopencl.Device
info

Lower case versions of the device_info constants may be used as attributes on instances of this class to directly query info attributes.

get_info(param)

See device_info for values of param.

from_int_ptr(int_ptr_value, retain=True)

Constructs a pyopencl handle from a C-level pointer (given as the integer int_ptr_value). If retain is True (the defauult) pyopencl will call clRetainXXX on the provided object. If the previous owner of the object will not release the reference, retain should be set to False, to effectively transfer ownership to pyopencl.

Changed in version 2016.1: retain added

int_ptr
create_sub_devices(properties)

properties is an array of one (or more) of the forms:

[ dpp.EQUALLY, 8]
[ dpp.BY_COUNTS, 5, 7, 9, dpp.PARTITION_BY_COUNTS_LIST_END]
[ dpp.BY_NAMES, 5, 7, 9, dpp.PARTITION_BY_NAMES_LIST_END]
[ dpp.BY_AFFINITY_DOMAIN, dad.L1_CACHE]

where dpp represents device_partition_property and dad represent device_affinity_domain.

PROPERTIES_LIST_END_EXT is added automatically.

Only available with CL 1.2.

New in version 2011.2.

Two instances of this class may be compared using ==” and ”!=”.

Context

class pyopencl.Context(devices=None, properties=None, dev_type=None, cache_dir=None)

Create a new context. properties is a list of key-value tuples, where each key must be one of context_properties. At most one of devices and dev_type may be not None, where devices is a list of Device instances, and dev_type is one of the device_type constants. If neither is specified, a context with a dev_type of device_type.DEFAULT is created.

If cache_dir is not None - it will be used as default cache_dir for all its’ Program instances builds (see also Program.build()).

Note

Calling the constructor with no arguments will fail for recent CL drivers that support the OpenCL ICD. If you want similar, just-give-me-a-context-already behavior, we recommend create_some_context(). See, e.g. this explanation by AMD.

Note

Because of how OpenCL changed in order to support Installable Client Drivers (ICDs) in OpenCL 1.1, the following will look reasonable but often actually not work:

import pyopencl as cl
ctx = cl.Context(dev_type=cl.device_type.ALL)

Instead, make sure to choose a platform when choosing a device by type:

import pyopencl as cl

platforms = cl.get_platforms()
ctx = cl.Context(
        dev_type=cl.device_type.ALL,
        properties=[(cl.context_properties.PLATFORM, platforms[0])])

Note

For context_properties.CL_GL_CONTEXT_KHR, context_properties.CL_EGL_DISPLAY_KHR, context_properties.CL_GLX_DISPLAY_KHR, context_properties.CL_WGL_HDC_KHR, and context_properties.CL_CGL_SHAREGROUP_KHR context_properties.CL_CGL_SHAREGROUP_APPLE the value in the key-value pair is a PyOpenGL context or display instance.

Changed in version 0.91.2: Constructor arguments dev_type added.

info

Lower case versions of the context_info constants may be used as attributes on instances of this class to directly query info attributes.

get_info(param)

See context_info for values of param.

from_int_ptr(int_ptr_value, retain=True)

Constructs a pyopencl handle from a C-level pointer (given as the integer int_ptr_value). If retain is True (the defauult) pyopencl will call clRetainXXX on the provided object. If the previous owner of the object will not release the reference, retain should be set to False, to effectively transfer ownership to pyopencl.

Changed in version 2016.1: retain added

int_ptr

Instances of this class are hashable, and two instances of this class may be compared using “==” and ”!=”. (Hashability was added in version 2011.2.) Two objects are considered the same if the underlying OpenCL object is the same, as established by C pointer equality.

pyopencl.create_some_context(interactive=True, answers=None, cache_dir=None)

Create a Context ‘somehow’.

If multiple choices for platform and/or device exist, interactive is True, and sys.stdin.isatty() is also True, then the user is queried about which device should be chosen. Otherwise, a device is chosen in an implementation-defined manner.