PyCL is yet another OpenCL wrapper for Python. Its primary goal is simple: wrap OpenCL in such a way that as many Python implementations can use it as feasible. It is currently tested on CPython 2.{5,6,7}, 3.2, and PyPy 1.5. It is known to largely not work on Jython, whose ctypes library is still immature.
To achieve this, we eschew extension modules and dependencies outside of the standard library. Ideally things like NumPy arrays and PIL images should Just Work, but they shouldn’t be required.
If you’re looking to get actual work done in OpenCL, this probably isn’t the distribution for you... yet. Before considering using PyCL for anything, give PyOpenCL a look. Its API is stable, its wrapper layer is fast C++, and it has fairly reasonable dependencies.
If you’re looking to contribute, or just get the latest development release, take a look at our repository.
Brief usage example:
>>> from array import array
>>> source = '''
... kernel void mxplusb(float m, global float *x, float b, global float *out) {
... int i = get_global_id(0);
... out[i] = m*x[i]+b;
... }
... '''
>>> ctx = clCreateContext()
>>> queue = clCreateCommandQueue(ctx)
>>> program = clCreateProgramWithSource(ctx, source).build()
>>> kernel = program['mxplusb']
>>> kernel.argtypes = (cl_float, cl_mem, cl_float, cl_mem)
>>> x = array('f', range(100))
>>> x_buf, in_evt = buffer_from_pyarray(queue, x, blocking=False)
>>> y_buf = x_buf.empty_like_this()
>>> run_evt = kernel(2, x_buf, 5, y_buf).on(queue, len(x), wait_for=in_evt)
>>> y, evt = buffer_to_pyarray(queue, y_buf, wait_for=run_evt, like=x)
>>> evt.wait()
>>> y[0:10]
array('f', [5.0, 7.0, 9.0, 11.0, 13.0, 15.0, 17.0, 19.0, 21.0, 23.0])
For Numpy users, see buffer_from_ndarray() and buffer_to_ndarray().
Additionally, if run as a script, will print out a summary of your platforms and devices.
Most of the C typedefs are available as subclasses of Python ctypes datatypes. The spelling might be slightly different.
The various enumeration and bitfield types have attributes representing their defined constants (e.g. CL_DEVICE_TYPE_GPU). These constants are also available at the module level, in case you can’t remember what type CL_QUEUED is supposed to be. They are all somewhat magical in that they’ll make a reasonable effort to pretty-print themselves:
>>> CL_DEVICE_TYPE_GPU | CL_DEVICE_TYPE_CPU
CL_DEVICE_TYPE_CPU | CL_DEVICE_TYPE_GPU
>>> cl_mem_info(0x1100)
CL_MEM_TYPE
The types representing various object-like datastructures often have attributes so that you can view their infos without needing to call the appropriate clGetThingInfo function. They may have other methods and behaviors.
One last note about the datatypes: despite any appearance of magic and high-level function, these are just ctypes objects. It is entirely possible for you to assign things to the value attribute of the enum/bitfield constants or of object-like items. Overwriting constants and clobbering pointers is generally a bad idea, though, so you should probably avoid it. (I tried vetoing assignment to .value, but PyPy didn’t like that. So you’re on your own.)
Wrapped OpenCL functions have their usual naming convention (clDoSomething). These are’t the naked C function pointers - you will find that the argument lists, return types, and exception raising are more in line with Python. Check the docstrings. That said, you can refer to the function pointer itself with the wrapped function’s call attribute, which is how the functions themselves do it. The function pointer itself has argument type, return type, and error checking added in the usual ctypes manner.
The list of wrapped functions is very incomplete. Feel free to contribute if you need a function that hasn’t been wrapped yet.
There are currently no plans to provide wrappers for OpenCL extensions (like OpenGL interop). Maybe later.
Bitfield used by clCreateContextFromType() to create a context from one or more matching device types.
See also cl_device.type and clGetDeviceInfo()
A status code returned by most OpenCL functions. Exceptions exist for each error code and will be raised in the event that the code is flagged by any wrapper function. The exception names are formed by removing the ‘CL’, title-casing the words, removing the underscores, and appending ‘Error’ to the end. Some of these are a little redundant, like BuildProgramFailureError.
And no, there is no SuccessError.
- CL_PROFILING_INFO_NOT_AVAILABLE¶
- CL_INVALID_KERNEL_DEFINITION¶
- CL_INVALID_VALUE¶
- CL_INVALID_PROGRAM_EXECUTABLE¶
- CL_INVALID_IMAGE_SIZE¶
- CL_INVALID_WORK_DIMENSION¶
- CL_INVALID_EVENT¶
- CL_BUILD_PROGRAM_FAILURE¶
- CL_INVALID_WORK_GROUP_SIZE¶
- CL_MEM_COPY_OVERLAP¶
- CL_INVALID_PROGRAM¶
- CL_INVALID_COMMAND_QUEUE¶
- CL_DEVICE_NOT_AVAILABLE¶
- CL_INVALID_QUEUE_PROPERTIES¶
- CL_INVALID_CONTEXT¶
- CL_INVALID_KERNEL_ARGS¶
- CL_OUT_OF_HOST_MEMORY¶
- CL_INVALID_BUILD_OPTIONS¶
- CL_INVALID_KERNEL¶
- CL_IMAGE_FORMAT_MISMATCH¶
- CL_INVALID_GL_OBJECT¶
- CL_MISALIGNED_SUB_BUFFER_OFFSET¶
- CL_INVALID_OPERATION¶
- CL_INVALID_PLATFORM¶
- CL_INVALID_DEVICE_TYPE¶
- CL_INVALID_PROPERTY¶
- CL_INVALID_ARG_VALUE¶
- CL_INVALID_GLOBAL_WORK_SIZE¶
- CL_INVALID_EVENT_WAIT_LIST¶
- CL_OUT_OF_RESOURCES¶
- CL_INVALID_DEVICE¶
- CL_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST¶
- CL_INVALID_ARG_SIZE¶
- CL_INVALID_BUFFER_SIZE¶
- CL_DEVICE_NOT_FOUND¶
- CL_INVALID_WORK_ITEM_SIZE¶
- CL_INVALID_MIP_LEVEL¶
- CL_INVALID_MEM_OBJECT¶
- CL_SUCCESS¶
- CL_INVALID_SAMPLER¶
- CL_INVALID_HOST_PTR¶
- CL_MAP_FAILURE¶
- CL_COMPILER_NOT_AVAILABLE¶
- CL_INVALID_BINARY¶
- CL_INVALID_KERNEL_NAME¶
- CL_MEM_OBJECT_ALLOCATION_FAILURE¶
- CL_INVALID_IMAGE_FORMAT_DESCRIPTOR¶
- CL_IMAGE_FORMAT_NOT_SUPPORTED¶
- CL_INVALID_ARG_INDEX¶
- CL_INVALID_GLOBAL_OFFSET¶
The set of possible parameter names used with the clGetPlatformInfo() function.
The set of possible parameter names used with the clGetDeviceInfo() function.
- CL_DEVICE_IMAGE2D_MAX_HEIGHT¶
- CL_DEVICE_IMAGE_SUPPORT¶
- CL_DEVICE_MIN_DATA_TYPE_ALIGN_SIZE¶
- CL_DEVICE_MEM_BASE_ADDR_ALIGN¶
- CL_DEVICE_ENDIAN_LITTLE¶
- CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE¶
- CL_DEVICE_GLOBAL_MEM_CACHELINE_SIZE¶
- CL_DEVICE_PREFERRED_VECTOR_WIDTH_LONG¶
- CL_DEVICE_PREFERRED_VECTOR_WIDTH_SHORT¶
- CL_DEVICE_PREFERRED_VECTOR_WIDTH_INT¶
- CL_DEVICE_NATIVE_VECTOR_WIDTH_LONG¶
- CL_DEVICE_GLOBAL_MEM_SIZE¶
- CL_DEVICE_MAX_COMPUTE_UNITS¶
- CL_DEVICE_VENDOR¶
- CL_DEVICE_PREFERRED_VECTOR_WIDTH_HALF¶
- CL_DRIVER_VERSION¶
- CL_DEVICE_DOUBLE_FP_CONFIG¶
- CL_DEVICE_NATIVE_VECTOR_WIDTH_HALF¶
- CL_DEVICE_PROFILING_TIMER_RESOLUTION¶
- CL_DEVICE_MAX_READ_IMAGE_ARGS¶
- CL_DEVICE_QUEUE_PROPERTIES¶
- CL_DEVICE_TYPE¶
- CL_DEVICE_MAX_WORK_GROUP_SIZE¶
- CL_DEVICE_IMAGE3D_MAX_DEPTH¶
- CL_DEVICE_NATIVE_VECTOR_WIDTH_DOUBLE¶
- CL_DEVICE_MAX_CONSTANT_ARGS¶
- CL_DEVICE_IMAGE3D_MAX_HEIGHT¶
- CL_DEVICE_PREFERRED_VECTOR_WIDTH_DOUBLE¶
- CL_DEVICE_EXTENSIONS¶
- CL_DEVICE_NATIVE_VECTOR_WIDTH_SHORT¶
- CL_DEVICE_GLOBAL_MEM_CACHE_TYPE¶
- CL_DEVICE_PLATFORM¶
- CL_DEVICE_PREFERRED_VECTOR_WIDTH_CHAR¶
- CL_DEVICE_ADDRESS_BITS¶
- CL_DEVICE_COMPILER_AVAILABLE¶
- CL_DEVICE_LOCAL_MEM_SIZE¶
- CL_DEVICE_AVAILABLE¶
- CL_DEVICE_NATIVE_VECTOR_WIDTH_FLOAT¶
- CL_DEVICE_NATIVE_VECTOR_WIDTH_INT¶
- CL_DEVICE_HOST_UNIFIED_MEMORY¶
- CL_DEVICE_GLOBAL_MEM_CACHE_SIZE¶
- CL_DEVICE_IMAGE3D_MAX_WIDTH¶
- CL_DEVICE_VERSION¶
- CL_DEVICE_NATIVE_VECTOR_WIDTH_CHAR¶
- CL_DEVICE_IMAGE2D_MAX_WIDTH¶
- CL_DEVICE_SINGLE_FP_CONFIG¶
- CL_DEVICE_PROFILE¶
- CL_DEVICE_HALF_FP_CONFIG¶
- CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS¶
- CL_DEVICE_NAME¶
- CL_DEVICE_OPENCL_C_VERSION¶
- CL_DEVICE_ERROR_CORRECTION_SUPPORT¶
- CL_DEVICE_MAX_MEM_ALLOC_SIZE¶
- CL_DEVICE_MAX_CLOCK_FREQUENCY¶
- CL_DEVICE_MAX_WORK_ITEM_SIZES¶
- CL_DEVICE_EXECUTION_CAPABILITIES¶
- CL_DEVICE_VENDOR_ID¶
- CL_DEVICE_MAX_WRITE_IMAGE_ARGS¶
- CL_DEVICE_PREFERRED_VECTOR_WIDTH_FLOAT¶
- CL_DEVICE_MAX_PARAMETER_SIZE¶
- CL_DEVICE_MAX_SAMPLERS¶
- CL_DEVICE_LOCAL_MEM_TYPE¶
One of the possible return types from clGetDeviceInfo(). Bitfield identifying the floating point capabilities of the device.
One of the possible return types from clGetDeviceInfo(). Describes the nature of the device’s cache, if any.
One of the possible return types from clGetDeviceInfo(). Describes where ‘local’ memory lives in the device. Presumably, CL_GLOBAL means the device’s local memory lives in the same address space as its global memory.
One of the possible return types from clGetDeviceInfo(). Bitfield identifying what kind of kernels can be executed. All devices can execute OpenCL C kernels, but some have their own native kernel types as well.
Bitfield representing the properties of a command queue.
If you find yourself looking at an array of these and need to make any sense of them... good luck! It’s a list of key-value pairs, null-terminated. The keys are unsigned ints representing enum constants. CL_CONTEXT_PLATFORM (0x1084) is the most common one you’ll see. I believe the rest are parts of extensions, such as the OpenGL interop extension.
The meaning of the odd elements depends entirely on the enum that came just before it. In the case of CL_CONTEXT_PLATFORM, the value represents a pointer to a cl_platform object.
Parameter names understood by clGetContextInfo().
Note that cl_context_inf.CL_CONTEXT_PLATFORM does not technically belong here, and the C-level code won’t accept it. The wrapped version of clGetContextInfo() will, however, recognize it and extract the appropriate value from the context’s properties list.
Parameter names understood by clGetCommandQueueInfo()
Bitfield used when constructing a memory object. Indicates both the read/write status of the memory as well as how the memory interacts with whatever host pointer was provided. See the OpenCL docs for clCreateBuffer() for more information.
Possible return type for clGetMemObjectInfo(). Indicates the type of the memory object.
Parameter names accepted by clGetMemObjectInfo()
Parameter type for clCreateSubBuffer() that indicates how the subbuffer will be described.
The only supported value is CL_BUFFER_CREATE_TYPE_REGION, which indicates the subbuffer will be a contiguous region as defined by a cl_buffer_region struct.
- CL_BUFFER_CREATE_TYPE_REGION¶
Addressing mode for sampler objects. Returned by clGetSamplerInfo().
Read/write flags used for applying memory mappings to memory objects. See clEnqueueMapBuffer() and clEnqueueMapImage().
Parameter names for clGetProgramInfo()
Parameter names for clGetProgramBuildInfo()
Returned by clGetProgramBuildInfo(). Indicates build status for the program on the specified device.
Parameter names for clGetKernelInfo()
Parameter names for clGetKernelWorkGroupInfo()
Parameter names for clGetEventInfo()
Command types recorded on events and returned by clGetEventInfo().
- CL_COMMAND_NDRANGE_KERNEL¶
- CL_COMMAND_COPY_BUFFER¶
- CL_COMMAND_RELEASE_GL_OBJECTS¶
- CL_COMMAND_COPY_IMAGE¶
- CL_COMMAND_READ_BUFFER_RECT¶
- CL_COMMAND_COPY_BUFFER_RECT¶
- CL_COMMAND_WRITE_BUFFER¶
- CL_COMMAND_MARKER¶
- CL_COMMAND_WRITE_IMAGE¶
- CL_COMMAND_ACQUIRE_GL_OBJECTS¶
- CL_COMMAND_COPY_BUFFER_TO_IMAGE¶
- CL_COMMAND_READ_BUFFER¶
- CL_COMMAND_READ_IMAGE¶
- CL_COMMAND_UNMAP_MEM_OBJECT¶
- CL_COMMAND_NATIVE_KERNEL¶
- CL_COMMAND_MAP_IMAGE¶
- CL_COMMAND_COPY_IMAGE_TO_BUFFER¶
- CL_COMMAND_MAP_BUFFER¶
- CL_COMMAND_USER¶
- CL_COMMAND_WRITE_BUFFER_RECT¶
- CL_COMMAND_TASK¶
Status of the command associated with an event, returned by clGetEventInfo().
Parameter names for clGetEventProfilingInfo(). Indicates the point in time of the event’s life that should be queried.
Represents image formats. See clCreateImage2D().
A cl_channel_order value
A cl_channel_type value
Structure/Union member
Structure/Union member
A buffer region has two fields: origin and size. Both are of type size_t.
See clCreateSubBuffer() for usage.
Structure/Union member
Structure/Union member
The base class from which all of the (generated) OpenCL errors are descended. These exceptions correspond to the cl_errnum status codes.
An OpenCL Event object. Returned by functions that add commands to a cl_command_queue, and often accepted (singly or in lists) by the wait_for argument of these functions to impose ordering.
Use wait() to wait for a particular event to complete, or clWaitForEvents() to wait for several of them at once.
These objects participate in OpenCL’s reference counting scheme.
The type of command this event is linked to. See cl_command_type.
| Parameters: | param_name – An instance of cl_event_info. |
|---|
Event information can be more easily obtained by querying the properties of the event object, which in turn will call this function.
Represents an OpenCL Platform. Should not be directly instantiated by users of PyCL. Use clGetPlatformIDs() or the platform attribute of some OpenCL objects to procure a cl_platform instance.
Returns a list of cl_platform objects available on your system. It should probably not be possible for this list to be empty if you are able to call this function.
>>> clGetPlatformIDs()
(<cl_platform '...'>...)
| Parameters: | param_name – One of cl_platform_info. |
|---|
cl_platform objects have attributes that will call this for you, so you should probably use those instead of calling this directly.
>>> plat = clGetPlatformIDs()[0]
>>> clGetPlatformInfo(plat, CL_PLATFORM_VERSION)
'OpenCL ...'
>>> plat.version
'OpenCL ...'
Note that CL_PLATFORM_EXTENSIONS returns a string while the extensions attribute returns a list:
>>> clGetPlatformInfo(plat, CL_PLATFORM_EXTENSIONS)
'...'
>>> plat.extensions
[...]
Represents an OpenCL Device belonging to some platform. Should not be directly instantiated by users of PyCL. Use clGetDeviceIDs() or the devices attribute of some OpenCL objects to procure a cl_device instances.
Same as calling clGetDeviceInfo() with CL_DEVICE_ADDRESS_BITS
Same as calling clGetDeviceInfo() with CL_DEVICE_AVAILABLE
Same as calling clGetDeviceInfo() with CL_DEVICE_COMPILER_AVAILABLE
Same as calling clGetDeviceInfo() with CL_DEVICE_DOUBLE_FP_CONFIG
Same as calling clGetDeviceInfo() with CL_DEVICE_ENDIAN_LITTLE
Same as calling clGetDeviceInfo() with CL_DEVICE_ERROR_CORRECTION_SUPPORT
Same as calling clGetDeviceInfo() with CL_DEVICE_EXECUTION_CAPABILITIES
Same as calling clGetDeviceInfo() with CL_DEVICE_GLOBAL_MEM_CACHE_SIZE
Same as calling clGetDeviceInfo() with CL_DEVICE_GLOBAL_MEM_CACHE_TYPE
Same as calling clGetDeviceInfo() with CL_DEVICE_GLOBAL_MEM_CACHELINE_SIZE
Same as calling clGetDeviceInfo() with CL_DEVICE_GLOBAL_MEM_SIZE
Same as calling clGetDeviceInfo() with CL_DEVICE_HALF_FP_CONFIG
Same as calling clGetDeviceInfo() with CL_DEVICE_HOST_UNIFIED_MEMORY
Same as calling clGetDeviceInfo() with CL_DEVICE_IMAGE2D_MAX_HEIGHT
Same as calling clGetDeviceInfo() with CL_DEVICE_IMAGE2D_MAX_WIDTH
Same as calling clGetDeviceInfo() with CL_DEVICE_IMAGE3D_MAX_DEPTH
Same as calling clGetDeviceInfo() with CL_DEVICE_IMAGE3D_MAX_HEIGHT
Same as calling clGetDeviceInfo() with CL_DEVICE_IMAGE3D_MAX_WIDTH
Same as calling clGetDeviceInfo() with CL_DEVICE_IMAGE_SUPPORT
Same as calling clGetDeviceInfo() with CL_DEVICE_LOCAL_MEM_SIZE
Same as calling clGetDeviceInfo() with CL_DEVICE_LOCAL_MEM_TYPE
Same as calling clGetDeviceInfo() with CL_DEVICE_MAX_CLOCK_FREQUENCY
Same as calling clGetDeviceInfo() with CL_DEVICE_MAX_COMPUTE_UNITS
Same as calling clGetDeviceInfo() with CL_DEVICE_MAX_CONSTANT_ARGS
Same as calling clGetDeviceInfo() with CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE
Same as calling clGetDeviceInfo() with CL_DEVICE_MAX_MEM_ALLOC_SIZE
Same as calling clGetDeviceInfo() with CL_DEVICE_MAX_PARAMETER_SIZE
Same as calling clGetDeviceInfo() with CL_DEVICE_MAX_READ_IMAGE_ARGS
Same as calling clGetDeviceInfo() with CL_DEVICE_MAX_SAMPLERS
Same as calling clGetDeviceInfo() with CL_DEVICE_MAX_WORK_GROUP_SIZE
Same as calling clGetDeviceInfo() with CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS
Same as calling clGetDeviceInfo() with CL_DEVICE_MAX_WORK_ITEM_SIZES
Same as calling clGetDeviceInfo() with CL_DEVICE_MAX_WRITE_IMAGE_ARGS
Same as calling clGetDeviceInfo() with CL_DEVICE_MEM_BASE_ADDR_ALIGN
Same as calling clGetDeviceInfo() with CL_DEVICE_MIN_DATA_TYPE_ALIGN_SIZE
Same as calling clGetDeviceInfo() with CL_DEVICE_NAME
Same as calling clGetDeviceInfo() with CL_DEVICE_NATIVE_VECTOR_WIDTH_CHAR
Same as calling clGetDeviceInfo() with CL_DEVICE_NATIVE_VECTOR_WIDTH_DOUBLE
Same as calling clGetDeviceInfo() with CL_DEVICE_NATIVE_VECTOR_WIDTH_FLOAT
Same as calling clGetDeviceInfo() with CL_DEVICE_NATIVE_VECTOR_WIDTH_HALF
Same as calling clGetDeviceInfo() with CL_DEVICE_NATIVE_VECTOR_WIDTH_INT
Same as calling clGetDeviceInfo() with CL_DEVICE_NATIVE_VECTOR_WIDTH_LONG
Same as calling clGetDeviceInfo() with CL_DEVICE_NATIVE_VECTOR_WIDTH_SHORT
Same as calling clGetDeviceInfo() with CL_DEVICE_OPENCL_C_VERSION
Same as calling clGetDeviceInfo() with CL_DEVICE_PLATFORM
Same as calling clGetDeviceInfo() with CL_DEVICE_PREFERRED_VECTOR_WIDTH_CHAR
Same as calling clGetDeviceInfo() with CL_DEVICE_PREFERRED_VECTOR_WIDTH_DOUBLE
Same as calling clGetDeviceInfo() with CL_DEVICE_PREFERRED_VECTOR_WIDTH_FLOAT
Same as calling clGetDeviceInfo() with CL_DEVICE_PREFERRED_VECTOR_WIDTH_HALF
Same as calling clGetDeviceInfo() with CL_DEVICE_PREFERRED_VECTOR_WIDTH_INT
Same as calling clGetDeviceInfo() with CL_DEVICE_PREFERRED_VECTOR_WIDTH_LONG
Same as calling clGetDeviceInfo() with CL_DEVICE_PREFERRED_VECTOR_WIDTH_SHORT
Same as calling clGetDeviceInfo() with CL_DEVICE_PROFILE
Same as calling clGetDeviceInfo() with CL_DEVICE_PROFILING_TIMER_RESOLUTION
Same as calling clGetDeviceInfo() with CL_DEVICE_QUEUE_PROPERTIES
Same as calling clGetDeviceInfo() with CL_DEVICE_SINGLE_FP_CONFIG
Same as calling clGetDeviceInfo() with CL_DEVICE_TYPE
Same as calling clGetDeviceInfo() with CL_DEVICE_VENDOR
Same as calling clGetDeviceInfo() with CL_DEVICE_VENDOR_ID
Same as calling clGetDeviceInfo() with CL_DEVICE_VERSION
| Parameters: |
|
|---|
>>> clGetDeviceIDs()
(<cl_device '...'>...)
| Parameters: |
|
|---|
cl_device objects have attributes that will call this for you, so you should probably use those instead of calling this directly.
>>> d = clGetDeviceIDs()[0]
>>> clGetDeviceInfo(d, CL_DEVICE_NAME)
'...'
>>> clGetDeviceInfo(d, CL_DEVICE_TYPE)
CL_DEVICE_TYPE_...
>>> d.available
True
>>> d.max_work_item_sizes
(...)
Note that CL_DEVICE_EXTENSIONS returns a string while the extensions attribute returns a list:
>>> clGetDeviceInfo(d, CL_DEVICE_EXTENSIONS)
'...'
>>> d.extensions
[...]
Represents an OpenCL Context instance.
Use clCreateContext() or clCreateContextFromType() to create a new context.
Participates in OpenCL’s reference counting scheme.
Create a context with the given devices and platform.
| Parameters: |
|
|---|
If you just need a context and don’t care what you get, calling with no arguments should hopefully get you something usable.
>>> clCreateContext()
<cl_context ...>
>>> one_device = clGetDeviceIDs()[0]
>>> clCreateContext(devices = [one_device])
<cl_context ...>
Like clCreateContext(), but works by device type instead of expecting you to list the desired devices. This can, for instance, be used to create a context with GPU devices without the user having to pick a platform and inspect its device list.
| Parameters: |
|
|---|
If you just need a context and don’t care what you get, calling with no arguments should hopefully get you something usable.
>>> clCreateContextFromType(CL_DEVICE_TYPE_CPU | CL_DEVICE_TYPE_GPU)
<cl_context ...>
Retrieve context info.
| Parameters: |
|
|---|
cl_context objects have attributes that will call this for you, so you should probably use those instead of calling this directly.
>>> ctx = clCreateContext()
>>> clGetContextInfo(ctx, CL_CONTEXT_DEVICES)
(<cl_device ...>...)
>>> ctx.platform
<cl_platform ...>
>>> ctx.reference_count
1
>>> ctx.properties
<...cl_context_properties_Array...>
Represents an OpenCL Command Queue instance. Should not be directly instantiated by users of PyCL. Use clCreateCommandQueue() to create a new queue.
The context associated with the command queue. (cl_context)
Command queue property bitfield. (cl_command_queue_properties)
| Parameters: |
|
|---|
| Parameters: |
|
|---|
>>> q = clCreateCommandQueue()
>>> q.context
<cl_context ...>
>>> q.device
<cl_device ...>
>>> q.properties
NONE
>>> q.reference_count
1
Represents an OpenCL memory object, typically a buffer or image.
Use clCreateBuffer() or similar to make them.
Memory objects are reference counted.
Pointer to host address associated with this memory object at the time of creation. The meaning varies depending on the flags. (type is void*)
The cl_mem_flags the object was created with.
The cl_context the memory belongs to.
| Parameters: |
|
|---|
See also buffer_from_ndarray(), buffer_from_pyarray()
Read from a cl_mem buffer into host memory.
| Parameters: |
|
|---|---|
| Returns: |
See also buffer_to_ndarray() and buffer_to_pyarray().
>>> ctx = clCreateContext()
>>> queue = clCreateCommandQueue(ctx)
>>> array1 = (cl_int * 8)() # 32 bytes
>>> for i in range(8): array1[i] = i
>>> m = clCreateBuffer(ctx, 32)
>>> clEnqueueWriteBuffer(queue, m, array1, 32)
<cl_event ...>
>>> array2 = (cl_int * 8)()
>>> clEnqueueReadBuffer(queue, m, array2, 32)
<cl_event ...>
>>> [x.value for x in array2]
[0, 1, 2, 3, 4, 5, 6, 7]
Write to a cl_mem buffer from a location in host memory.
See clEnqueueReadBuffer() for the meanings of the parameters.
| Parameters: |
|
|---|
Memory objects have properties that will retrieve these values for you, so you should probably use those.
Represents an OpenCL program, a container for kernels.
Use clCreateProgramWithSource() or clCreateProgramWithBinary() to make a program.
Remember to call build() to compile source programs.
You can retrieve a kernel like so: >>> my_kernel = my_program[‘my_kernel’] # doctest: +SKIP
Programs participate in reference counting.
Calls clBuildProgram() on the program, passing along any arguments you provide. The program itself will be returned, so you can use this idiom:
>>> source = 'kernel void foo(float bar) {}'
>>> ctx = clCreateContext()
>>> prog = clCreateProgramWithSource(ctx, source).build()
Sizes, in bytes, of the binaries for each of the devices the program is compiled for.
Retrieves the cl_program_build_status for one of more devices. See also clGetProgramBuildInfo()
Retrieves the build options, as a string, for one of more devices. See also clGetProgramBuildInfo().
Returns the build log, as a string, for one or more devices. Mostly useful for checking compiler errors. See also clGetProgramBuildInfo().
| Parameters: |
|
|---|
| Parameters: |
|
|---|
If a list of devices is provided, info will be returned for each of them in a list.
If no device is specified, all devices associated with the program will be used.
The build_status(), build_options(), and build_log() methods of program objects are equivalent to using this, so they may be preferable.
| Parameters: |
|
|---|
Remember to call build() on the program.
Compiles a source program to run on one or more devices.
| Parameters: |
|
|---|
If the build fails, it will raise a ProgramBuildFailureError with details.
Represents an OpenCL kernel found in a cl_program.
After compiling a program, the kernels will be accessible as items whose keys are the kernel names.
Kernels are reference counted.
The cl_program this kernel lives in.
The cl_context this kernel lives in.
Sets one of the kernel’s arguments.
| Parameters: |
|
|---|
This does some extra work to try to ensure that the data is in a form suitable for the lower-level clSetKernelArg() call. The OpenCL API doesn’t give us much help in determining what type an argument should be, so if possible you should set the elements of the kernel’s argtypes field to a list of types. The types should be either cl_mem, localmem, a scalar type such as cl_int, or a ctypes structure type.
Represents the data types of the kernel function arguments. There is no way to ask OpenCL for this information, so short of actually parsing the C code the only way to fill this in is to infer it from the way the user tries to call the kernel.
Since this is error prone, we encourage you to fill in the list yourself.
Enqueue the kernel (hopefully after setting its arguments) upon a command queue. This is essetially a shortcut for clEnqueueNDRangeKernel().
The maximum size of workgroups for this kernel on the specified device.
The work group size specified by the kernel source, if any. Otherwise, will return (0,0,0).
The amount of local memory that would be used by this kernel on the given device with its current argument set.
| Parameters: |
|
|---|
Using the the program[kernel_name] syntax is preferable.
| Parameters: |
|
|---|
Kernel objects have properties that call this function, so it is probably preferable to use those instead.
| Parameters: |
|
|---|
Retrieves information about the kernel specific to a particular device that it might be run on. This information is also available through specific methods of kernel objects, which may be preferable to calling this.
When a kernel defines an argument to be in local memory, no value can be passed in to that argument. Instead, the size of the local memory is specified. While you could do this directly with clSetKernelArg(), localmem allows you to set this using the kernel call syntax. So if you had a kernel whose third argument was a local memory pointer, you could set the arguments like so:
>>> mykernel(x, y, localmem(1024))
localmem is also accepted in argtypes, in which case the kernel can be called using just the desired size:
>>> mykernel.argtypes = (cl_mem, cl_mem, localmem)
>>> mykernel(x, y, 1024)
| Parameters: |
|
|---|
Unlike most of the wrappers in PyCL, this one doesn’t do much to help you out. Use cl_kernel.setarg() if you want some help setting individual arguments. Calling the kernel object itself with the desired argument sequence is more preferable still. Set cl_kernel.argtypes if it can’t guess the types properly.
Enqueue a kernel for execution. The kernel’s arguments should be set already. For a more idiomatic calling syntax, set the kernel arguments by calling it and use its on() method to queue it.
| Parameters: |
|
|---|---|
| Returns: | cl_event which will identify when the kernel has completed. |
Note that the OpenCL clEnqueueTask() function is equivalent to calling this function with the default gsize, lsize, and offset values, so we haven’t bothered to wrap it.
Creates (or simply writes to) an OpenCL buffer using the contents of a Numpy array.
| Parameters: |
|
|---|---|
| Returns: | (buf, evt), where evt is the cl_event returned by the write operation. |
Any additional provided keyword arguments are passed along to clEnqueueWriteBuffer().
Reads from an OpenCL buffer into an ndarray.
| Parameters: |
|
|---|---|
| Returns: | (ary, evt), where evt is the cl_event returned by the read operation. |
Any further keyword arguments are passed directly to clEnqueueReadBuffer().
Essentially the same as buffer_from_ndarray(), except that it accepts arrays from the array module in Python’s standard library.
Essentially the same as buffer_to_ndarray(), except that it produces arrays from the array module in Python’s standard library. The dtype and shape parameters are replaced:
| Parameters: |
|
|---|