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: int, retain: bool = True) → pyopencl._cl.Platform¶: (static method) Return a new Python object referencing the C-level cl_platform_id object at the location pointed to by int_ptr_value. The relevant clRetain* function will be called if retain is True.If the previous owner of the object will not release the reference, retain should be set to False, to effectively transfer ownership to pyopencl.

Added in version 2013.2.

Changed in version 2016.1: retain added.

int_ptr¶: Return an integer corresponding to the pointer value of the underlying cl_platform_id. Use from_int_ptr() to turn back into a Python object.

Added in version 2013.2.

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¶

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

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: int, retain: bool = True) → pyopencl._cl.Device¶: (static method) Return a new Python object referencing the C-level cl_device_id object at the location pointed to by int_ptr_value. The relevant clRetain* function will be called if retain is True.If the previous owner of the object will not release the reference, retain should be set to False, to effectively transfer ownership to pyopencl.

Added in version 2013.2.

Changed in version 2016.1: retain added.

int_ptr¶: Return an integer corresponding to the pointer value of the underlying cl_device_id. Use from_int_ptr() to turn back into a Python object.

Added in version 2013.2.

hashable_model_and_version_identifier¶

An unspecified data type that can be used to (as precisely as possible, given identifying information available in OpenCL) identify a given model and software stack version of a compute device. Note that this identifier does not differentiate between different instances of the same device installed in a single host.

The returned data type is hashable.

Added in version 2020.1.

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.

Added in version 2011.2.

device_and_host_timer()¶

Returns:: a tuple (device_timestamp, host_timestamp).

Only available with CL 2.0.

Added in version 2020.3.

host_timer()¶: Only available with CL 2.0.

Added in version 2020.3.

pyopencl.choose_devices(interactive: bool | None = None, answers: list[str] | None = None) → list[Device][source]¶

Choose Device instances ‘somehow’.

Parameters:

interactive – If multiple choices for platform and/or device exist, interactive is True (or None and sys.stdin.isatty() returns True), then the user is queried about which device should be chosen. Otherwise, a device is chosen in an implementation-defined manner.
answers – A sequence of strings that will be used to answer the platform/device selection questions.

Returns:

a list of Device instances.

Context¶

class pyopencl.Context(devices=None, properties=None, dev_type=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.

Note

Calling the constructor with no arguments may fail for CL drivers that support the OpenCL ICD (which applies to most modern systems). If you want similar, just-give-me-a-context-already behavior, we recommend create_some_context().

See e.g. this explanation by AMD:

What has changed?

In previous beta releases functions such as clGetDeviceIDs() and clCreateContext() accepted a NULL value for the platform parameter. This release no longer allows this - the platform must be a valid one obtained by using the platform API.

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: int, retain: bool = True) → pyopencl._cl.Context¶: (static method) Return a new Python object referencing the C-level cl_context object at the location pointed to by int_ptr_value. The relevant clRetain* function will be called if retain is True.If the previous owner of the object will not release the reference, retain should be set to False, to effectively transfer ownership to pyopencl.

Added in version 2013.2.

Changed in version 2016.1: retain added.

int_ptr¶: Return an integer corresponding to the pointer value of the underlying cl_context. Use from_int_ptr() to turn back into a Python object.

Added in version 2013.2.

set_default_device_command_queue(dev, queue)¶

pyopencl.create_some_context(interactive: bool | None = None, answers: list[str] | None = None) → Context[source]¶

Create a Context ‘somehow’.

Parameters:

interactive – If multiple choices for platform and/or device exist, interactive is True (or None and sys.stdin.isatty() returns True), then the user is queried about which device should be chosen. Otherwise, a device is chosen in an implementation-defined manner.
answers – A sequence of strings that will be used to answer the platform/device selection questions.

Returns:

an instance of Context.