What is PyCL?¶
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.
Installation¶
It’s on PyPI, so installation should be as easy as:
pip install pycl
-or-
easy_install pycl
But it’s a single module and there’s nothing to compile, so downloading it from PyPI or the repository and using it directly works too.
To actually use it, though, you’ll need an OpenCL platform installed. If you’re on Mac OS X 10.6 or later, you’re already done. Otherwise, download and install an appropriate platform from AMD, Intel, or NVIDIA.
Module API Reference¶
Brief usage example:
from pycl import *
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(10))
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()
print y
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.CL_DEVICE_TYPE_GPU | cl_device_type.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.
-
class
pycl.
cl_device_type
[source]¶ Bitfield used by
clCreateContextFromType()
to create a context from one or more matching device types.See also
cl_device.type
andclGetDeviceInfo()
-
class
pycl.
cl_errnum
[source]¶ 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_INVALID_KERNEL_NAME
¶
-
CL_INVALID_GL_SHAREGROUP_REFERENCE_KHR
¶
-
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_MAP_FAILURE
¶
-
CL_INVALID_KERNEL
¶
-
CL_INVALID_GLOBAL_WORK_SIZE
¶
-
CL_IMAGE_FORMAT_MISMATCH
¶
-
CL_KERNEL_ARG_INFO_NOT_AVAILABLE
¶
-
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_LINKER_NOT_AVAILABLE
¶
-
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_COMPILE_PROGRAM_FAILURE
¶
-
CL_COMPILER_NOT_AVAILABLE
¶
-
CL_INVALID_BINARY
¶
-
CL_DEVICE_PARTITION_FAILED
¶
-
CL_MEM_OBJECT_ALLOCATION_FAILURE
¶
-
CL_INVALID_IMAGE_FORMAT_DESCRIPTOR
¶
-
CL_LINK_PROGRAM_FAILURE
¶
-
CL_IMAGE_FORMAT_NOT_SUPPORTED
¶
-
CL_INVALID_ARG_INDEX
¶
-
CL_INVALID_GLOBAL_OFFSET
¶
-
-
class
pycl.
cl_platform_info
[source]¶ The set of possible parameter names used with the
clGetPlatformInfo()
function.
-
class
pycl.
cl_device_info
[source]¶ The set of possible parameter names used with the
clGetDeviceInfo()
function.-
CL_DEVICE_IMAGE2D_MAX_HEIGHT
¶
-
CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS
¶
-
CL_DEVICE_IMAGE_SUPPORT
¶
-
CL_DEVICE_MIN_DATA_TYPE_ALIGN_SIZE
¶
-
CL_DEVICE_PARTITION_AFFINITY_DOMAIN
¶
-
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_REFERENCE_COUNT
¶
-
CL_DEVICE_VENDOR
¶
-
CL_DEVICE_IMAGE_MAX_BUFFER_SIZE
¶
-
CL_DEVICE_PREFERRED_VECTOR_WIDTH_HALF
¶
-
CL_DRIVER_VERSION
¶
-
CL_DEVICE_DOUBLE_FP_CONFIG
¶
-
CL_DEVICE_NATIVE_VECTOR_WIDTH_HALF
¶
-
CL_DEVICE_IMAGE_PITCH_ALIGNMENT
¶
-
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_IMAGE_MAX_ARRAY_SIZE
¶
-
CL_DEVICE_MAX_CONSTANT_ARGS
¶
-
CL_DEVICE_IMAGE3D_MAX_HEIGHT
¶
-
CL_DEVICE_PREFERRED_VECTOR_WIDTH_DOUBLE
¶
-
CL_DEVICE_ADDRESS_BITS
¶
-
CL_DEVICE_EXTENSIONS
¶
-
CL_DEVICE_NATIVE_VECTOR_WIDTH_SHORT
¶
-
CL_DEVICE_BUILT_IN_KERNELS
¶
-
CL_DEVICE_GLOBAL_MEM_CACHE_TYPE
¶
-
CL_DEVICE_NATIVE_VECTOR_WIDTH_DOUBLE
¶
-
CL_DEVICE_PLATFORM
¶
-
CL_DEVICE_PREFERRED_VECTOR_WIDTH_CHAR
¶
-
CL_DEVICE_PARTITION_TYPE
¶
-
CL_DEVICE_PARENT_DEVICE
¶
-
CL_DEVICE_IMAGE_BASE_ADDRESS_ALIGNMENT
¶
-
CL_DEVICE_LINKER_AVAILABLE
¶
-
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_PRINTF_BUFFER_SIZE
¶
-
CL_DEVICE_PARTITION_MAX_SUB_DEVICES
¶
-
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_PREFERRED_INTEROP_USER_SYNC
¶
-
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_PARTITION_PROPERTIES
¶
-
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
¶
-
-
class
pycl.
cl_device_fp_config
[source]¶ One of the possible return types from
clGetDeviceInfo()
. Bitfield identifying the floating point capabilities of the device.
-
class
pycl.
cl_device_mem_cache_type
[source]¶ One of the possible return types from
clGetDeviceInfo()
. Describes the nature of the device’s cache, if any.
-
class
pycl.
cl_device_local_mem_type
[source]¶ 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.
-
class
pycl.
cl_device_exec_capabilities
[source]¶ 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.
-
class
pycl.
cl_device_partition_property
[source]¶ -
CL_DEVICE_PARTITION_BY_COUNTS
¶
-
CL_DEVICE_PARTITION_EQUALLY
¶
-
CL_DEVICE_PARTITION_BY_COUNTS_LIST_END
¶
-
CL_DEVICE_PARTITION_BY_AFFINITY_DOMAIN
¶
-
-
class
pycl.
cl_device_affinity_domain
[source]¶ -
CL_DEVICE_AFFINITY_DOMAIN_L2_CACHE
¶
-
CL_DEVICE_AFFINITY_DOMAIN_NUMA
¶
-
CL_DEVICE_AFFINITY_DOMAIN_L3_CACHE
¶
-
CL_DEVICE_AFFINITY_DOMAIN_L1_CACHE
¶
-
CL_DEVICE_AFFINITY_DOMAIN_L4_CACHE
¶
-
CL_DEVICE_AFFINITY_DOMAIN_NEXT_PARTITIONABLE
¶
-
-
class
pycl.
cl_command_queue_properties
[source]¶ Bitfield representing the properties of a command queue.
-
class
pycl.
cl_context_properties
[source]¶ 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.
-
class
pycl.
cl_context_info
[source]¶ 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 ofclGetContextInfo()
will, however, recognize it and extract the appropriate value from the context’s properties list.
-
class
pycl.
cl_command_queue_info
[source]¶ Parameter names understood by
clGetCommandQueueInfo()
-
class
pycl.
cl_mem_flags
[source]¶ 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.
-
class
pycl.
cl_mem_object_type
[source]¶ Possible return type for
clGetMemObjectInfo()
. Indicates the type of the memory object.
-
class
pycl.
cl_mem_info
[source]¶ Parameter names accepted by
clGetMemObjectInfo()
-
class
pycl.
cl_mem_migration_flags
[source]¶ The set of possible parameter names used with the
clEnqueueMigrateMemObjects()
function.
-
class
pycl.
cl_buffer_create_type
[source]¶ 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 acl_buffer_region
struct.-
CL_BUFFER_CREATE_TYPE_REGION
¶
-
-
class
pycl.
cl_addressing_mode
[source]¶ Addressing mode for sampler objects. Returned by
clGetSamplerInfo()
.
-
class
pycl.
cl_map_flags
[source]¶ Read/write flags used for applying memory mappings to memory objects. See
clEnqueueMapBuffer()
andclEnqueueMapImage()
.
-
class
pycl.
cl_program_info
[source]¶ Parameter names for
clGetProgramInfo()
-
class
pycl.
cl_program_build_info
[source]¶ Parameter names for
clGetProgramBuildInfo()
-
class
pycl.
cl_build_status
[source]¶ Returned by
clGetProgramBuildInfo()
. Indicates build status for the program on the specified device.
-
class
pycl.
cl_kernel_info
[source]¶ Parameter names for
clGetKernelInfo()
-
class
pycl.
cl_kernel_work_group_info
[source]¶ Parameter names for
clGetKernelWorkGroupInfo()
-
class
pycl.
cl_event_info
[source]¶ Parameter names for
clGetEventInfo()
-
class
pycl.
cl_command_type
[source]¶ 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
¶
-
-
class
pycl.
cl_command_execution_status
[source]¶ Status of the command associated with an event, returned by
clGetEventInfo()
.
-
class
pycl.
cl_profiling_info
[source]¶ Parameter names for
clGetEventProfilingInfo()
. Indicates the point in time of the event’s life that should be queried.
-
class
pycl.
cl_image_format
[source]¶ Represents image formats. See
clCreateImage2D()
.-
image_channel_order
¶ A
cl_channel_order
value
-
image_channel_data_type
¶ A
cl_channel_type
value
-
-
class
pycl.
cl_buffer_region
[source]¶ A buffer region has two fields:
origin
andsize
. Both are of typesize_t
.See
clCreateSubBuffer()
for usage.
-
exception
pycl.
OpenCLError
[source]¶ The base class from which all of the (generated) OpenCL errors are descended. These exceptions correspond to the
cl_errnum
status codes.
-
class
pycl.
cl_event
[source]¶ An OpenCL Event object. Returned by functions that add commands to a
cl_command_queue
, and often accepted (singly or in lists) by thewait_for
argument of these functions to impose ordering.Use
wait()
to wait for a particular event to complete, orclWaitForEvents()
to wait for several of them at once.These objects participate in OpenCL’s reference counting scheme.
-
queue
¶ The queue this event was emitted from.
-
context
¶ The context this event exists within.
-
type
¶ The type of command this event is linked to. See
cl_command_type
.
-
status
¶ Execution status of the command the event is linked to. See
cl_command_exec_status
.
-
reference_count
¶ Reference count for OpenCL garbage collection.
-
-
pycl.
clGetEventInfo
(event, param_name)[source]¶ 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.
-
class
pycl.
cl_platform
[source]¶ Represents an OpenCL Platform. Should not be directly instantiated by users of PyCL. Use
clGetPlatformIDs()
or theplatform
attribute of some OpenCL objects to procure a cl_platform instance.-
name
¶ Name of the platform. (str)
-
vendor
¶ Vendor that distributes the platform. (str)
-
version
¶ Platform version. Likely starts with ‘OpenCL 1.1’. (str)
-
extensions
¶ Platform extensions supported. (list of str) Note that devices have their own set of extensions which should be inspected separately.
-
profile
¶ One of ‘FULL_PROFILE’ or ‘EMBEDDED_PROFILE’.
-
devices
¶ All devices available on this platform. (list of cl_device)
-
-
pycl.
clGetPlatformIDs
()[source]¶ 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 '...'>...)
-
pycl.
clGetPlatformInfo
(platform, param_name)[source]¶ 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_info.CL_PLATFORM_VERSION) 'OpenCL ...' >>> plat.version 'OpenCL ...'
Note that
CL_PLATFORM_EXTENSIONS
returns a string while theextensions
attribute returns a list:>>> clGetPlatformInfo(plat, cl_platform_info.CL_PLATFORM_EXTENSIONS) '...' >>> plat.extensions [...]
-
class
pycl.
cl_device
[source]¶ Represents an OpenCL Device belonging to some platform. Should not be directly instantiated by users of PyCL. Use
clGetDeviceIDs()
or thedevices
attribute of some OpenCL objects to procure a cl_device instances.-
address_bits
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_ADDRESS_BITS
-
available
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_AVAILABLE
-
built_in_kernels
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_BUILT_IN_KERNELS
-
compiler_available
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_COMPILER_AVAILABLE
-
double_fp_config
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_DOUBLE_FP_CONFIG
-
endian_little
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_ENDIAN_LITTLE
-
error_correction_support
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_ERROR_CORRECTION_SUPPORT
-
execution_capabilities
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_EXECUTION_CAPABILITIES
-
global_mem_cache_size
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_GLOBAL_MEM_CACHE_SIZE
-
global_mem_cache_type
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_GLOBAL_MEM_CACHE_TYPE
-
global_mem_cacheline_size
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_GLOBAL_MEM_CACHELINE_SIZE
-
global_mem_size
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_GLOBAL_MEM_SIZE
-
half_fp_config
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_HALF_FP_CONFIG
-
host_unified_memory
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_HOST_UNIFIED_MEMORY
-
image2d_max_height
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_IMAGE2D_MAX_HEIGHT
-
image2d_max_width
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_IMAGE2D_MAX_WIDTH
-
image3d_max_depth
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_IMAGE3D_MAX_DEPTH
-
image3d_max_height
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_IMAGE3D_MAX_HEIGHT
-
image3d_max_width
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_IMAGE3D_MAX_WIDTH
-
image_base_address_alignment
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_IMAGE_BASE_ADDRESS_ALIGNMENT
-
image_max_array_size
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_IMAGE_MAX_ARRAY_SIZE
-
image_max_buffer_size
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_IMAGE_MAX_BUFFER_SIZE
-
image_pitch_alignment
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_IMAGE_PITCH_ALIGNMENT
-
image_support
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_IMAGE_SUPPORT
-
linker_available
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_LINKER_AVAILABLE
-
local_mem_size
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_LOCAL_MEM_SIZE
-
local_mem_type
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_LOCAL_MEM_TYPE
-
max_clock_frequency
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_MAX_CLOCK_FREQUENCY
-
max_compute_units
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_MAX_COMPUTE_UNITS
-
max_constant_args
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_MAX_CONSTANT_ARGS
-
max_constant_buffer_size
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_MAX_CONSTANT_BUFFER_SIZE
-
max_mem_alloc_size
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_MAX_MEM_ALLOC_SIZE
-
max_parameter_size
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_MAX_PARAMETER_SIZE
-
max_read_image_args
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_MAX_READ_IMAGE_ARGS
-
max_samplers
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_MAX_SAMPLERS
-
max_work_group_size
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_MAX_WORK_GROUP_SIZE
-
max_work_item_dimensions
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_MAX_WORK_ITEM_DIMENSIONS
-
max_work_item_sizes
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_MAX_WORK_ITEM_SIZES
-
max_write_image_args
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_MAX_WRITE_IMAGE_ARGS
-
mem_base_addr_align
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_MEM_BASE_ADDR_ALIGN
-
min_data_type_align_size
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_MIN_DATA_TYPE_ALIGN_SIZE
-
name
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_NAME
-
native_vector_width_char
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_NATIVE_VECTOR_WIDTH_CHAR
-
native_vector_width_double
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_NATIVE_VECTOR_WIDTH_DOUBLE
-
native_vector_width_float
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_NATIVE_VECTOR_WIDTH_FLOAT
-
native_vector_width_half
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_NATIVE_VECTOR_WIDTH_HALF
-
native_vector_width_int
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_NATIVE_VECTOR_WIDTH_INT
-
native_vector_width_long
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_NATIVE_VECTOR_WIDTH_LONG
-
native_vector_width_short
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_NATIVE_VECTOR_WIDTH_SHORT
-
opencl_c_version
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_OPENCL_C_VERSION
-
parent_device
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_PARENT_DEVICE
-
partition_affinity_domain
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_PARTITION_AFFINITY_DOMAIN
-
partition_max_sub_devices
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_PARTITION_MAX_SUB_DEVICES
-
partition_properties
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_PARTITION_PROPERTIES
-
partition_type
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_PARTITION_TYPE
-
platform
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_PLATFORM
-
preferred_interop_user_sync
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_PREFERRED_INTEROP_USER_SYNC
-
preferred_vector_width_char
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_PREFERRED_VECTOR_WIDTH_CHAR
-
preferred_vector_width_double
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_PREFERRED_VECTOR_WIDTH_DOUBLE
-
preferred_vector_width_float
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_PREFERRED_VECTOR_WIDTH_FLOAT
-
preferred_vector_width_half
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_PREFERRED_VECTOR_WIDTH_HALF
-
preferred_vector_width_int
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_PREFERRED_VECTOR_WIDTH_INT
-
preferred_vector_width_long
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_PREFERRED_VECTOR_WIDTH_LONG
-
preferred_vector_width_short
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_PREFERRED_VECTOR_WIDTH_SHORT
-
printf_buffer_size
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_PRINTF_BUFFER_SIZE
-
profile
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_PROFILE
-
profiling_timer_resolution
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_PROFILING_TIMER_RESOLUTION
-
queue_properties
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_QUEUE_PROPERTIES
-
reference_count
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_REFERENCE_COUNT
-
single_fp_config
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_SINGLE_FP_CONFIG
-
type
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_TYPE
-
vendor
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_VENDOR
-
vendor_id
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_VENDOR_ID
-
version
¶ Same as calling
clGetDeviceInfo()
withCL_DEVICE_VERSION
-
-
pycl.
clGetDeviceIDs
(platform=None, device_type=CL_DEVICE_TYPE_ALL)[source]¶ Parameters: - platform – The
cl_platform
whose devices you are interested in. If none is provided, the first platform on the system is used. - device_type – A
cl_device_type
bitfield indicating which devices should be listed. By default, all are listed.
>>> clGetDeviceIDs() (<cl_device '...'>...)
- platform – The
-
pycl.
clGetDeviceInfo
(device, param_name)[source]¶ Parameters: - device – A
cl_device
. - param_name – The
cl_device_info
item to be queried.
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_info.CL_DEVICE_NAME) '...' >>> clGetDeviceInfo(d, cl_device_info.CL_DEVICE_TYPE) CL_DEVICE_TYPE_... >>> d.available True >>> d.max_work_item_sizes (...)
Note that
CL_DEVICE_EXTENSIONS
returns a string while theextensions
attribute returns a list:>>> clGetDeviceInfo(d, cl_device_info.CL_DEVICE_EXTENSIONS) '...' >>> d.extensions [...]
- device – A
-
class
pycl.
cl_context
[source]¶ Represents an OpenCL Context instance.
Use
clCreateContext()
orclCreateContextFromType()
to create a new context.Participates in OpenCL’s reference counting scheme.
-
platform
¶ Retrieve the platform this context was made using. (cl_platform)
-
reference_count
¶ Reference count for OpenCL’s internal garbage collector. (int) Using
clReleaseContext()
via pycl is an excellent way to generate segmentation faults.
-
num_devices
¶ Number of devices present in this particular context. (int)
-
properties
¶ Low-level ctypes array that is probably not user-interpretable.
-
-
pycl.
clCreateContext
(devices=None, platform=None, other_props=None)[source]¶ Create a context with the given devices and platform.
Parameters: - devices – A list of devices. If None, the first device from the given platform is used.
- platform – If no platform or devices are provided, the first platform found will be used. If a device list is provided but no platform, the platform will be recovered from the devices.
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 ...>
-
pycl.
clCreateContextFromType
(device_type=CL_DEVICE_TYPE_DEFAULT, platform=None, other_props=None)[source]¶ 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: - device_type – A
cl_device_type
field indicating which types of devices should be included. - platform – A
cl_platform
. If no platform is provided, each platform will be tried in turn until a context with the specified device type can created.
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 ...>
- device_type – A
-
pycl.
clGetContextInfo
(context, param_name)[source]¶ Retrieve context info.
Parameters: - context –
cl_context
. - param_name – One of the
cl_context_info
values.
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_info.CL_CONTEXT_DEVICES) (<cl_device ...>...) >>> ctx.platform <cl_platform ...> >>> ctx.reference_count 1 >>> ctx.properties <...cl_context_properties_Array...>
- context –
-
class
pycl.
cl_command_queue
[source]¶ Represents an OpenCL Command Queue instance. Should not be directly instantiated by users of PyCL. Use
clCreateCommandQueue()
to create a new queue.-
context
¶ The context associated with the command queue. (
cl_context
)
-
properties
¶ Command queue property bitfield. (
cl_command_queue_properties
)
-
reference_count
¶ Reference count for OpenCL’s garbage collector. (int)
-
-
pycl.
clCreateCommandQueue
(context=None, device=None, properties=None)[source]¶ Parameters: - context –
cl_context
. If not provided, one will be generated for you by callingclCreateContext()
with no arguments. (it can later be retrieved via thecontext
attribute) - device – The
cl_device
that will be fed by this queue. If no device is provided, the first device in the context will be used. - properties – A
cl_command_queue_properties
bitfield.
- context –
-
pycl.
clGetCommandQueueInfo
(queue, param_name)[source]¶ Parameters: - queue –
cl_command_queue
. - param_name – One of the
cl_command_queue_info
values.
>>> q = clCreateCommandQueue() >>> q.context <cl_context ...> >>> q.device <cl_device ...> >>> q.properties NONE >>> q.reference_count 1
- queue –
-
class
pycl.
cl_mem
[source]¶ Represents an OpenCL memory object, typically a buffer or image.
See the individual types (
cl_buffer
andcl_image
) for details. PyCL should probably never give you a direct instance of this class - treat it as abstract.Memory objects are reference counted.
-
size
¶ Memory size, in bytes.
-
reference_count
¶ Reference count for OpenCL garbage collector.
-
map_count
¶ Number of memory maps currently active for this object.
-
hostptr
¶ Pointer to host address associated with this memory object at the time of creation. The meaning varies depending on the flags. (type is
void*
)
-
flags
¶ The
cl_mem_flags
the object was created with.
-
type
¶ The
cl_mem_type
of the object.
-
context
¶ The
cl_context
the memory belongs to.
-
-
class
pycl.
cl_buffer
[source]¶ A subclass of
cl_mem
representing memory buffers. Create these withclCreateBuffer()
orclCreateSubBuffer()
-
base
¶ Base memory object (for sub-buffers)
-
offset
¶ Offset, in bytes, from origin (for sub-buffers)
-
-
class
pycl.
cl_image
[source]¶ A subclass of
cl_mem
representing 2D or 3D images. Create these withclCreateImage2D()
orclCreateImage3D()
.
-
pycl.
clCreateBuffer
(context, size, flags=CL_MEM_READ_WRITE, host_ptr=None)[source]¶ Parameters: - context –
cl_context
that will own this memory. - size – Desired size (in bytes) of the memory.
- flags –
cl_mem_flags
to control the memory. - host_ptr –
void*
to associated with this memory. The meaning of the association depends on the flags. (An integer representation of a pointer is fine).
See also
buffer_from_ndarray()
,buffer_from_pyarray()
- context –
-
pycl.
clEnqueueReadBuffer
(queue, mem, pointer, size=None, blocking=True, offset=0, wait_for=None)[source]¶ Read from a
cl_mem
buffer into host memory.Parameters: - queue –
cl_command_queue
to queue it on. - mem –
cl_mem
to read from. Must be a buffer. - pointer –
void*
pointer, the address to start writing into. (An integer representation of the pointer is fine). - size – Number of bytes to read. If not specified, the entire buffer is read out, which might be hazardous if the place you’re writing it to isn’t big enough.
- blocking – Wait for the transfer to complete. Default is True. If False, you can use the returned event to check its status.
- offset – Offset in the buffer at which to start reading. Default is 0.
- wait_for –
cl_event
(or a list of them) that must complete before the memory transfer will commence.
Returns: See also
buffer_to_ndarray()
andbuffer_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]
- queue –
-
pycl.
clEnqueueWriteBuffer
(queue, mem, pointer, size=None, blocking=True, offset=0, wait_for=None)[source]¶ Write to a
cl_mem
buffer from a location in host memory.See
clEnqueueReadBuffer()
for the meanings of the parameters.
-
pycl.
clEnqueueFillBuffer
(queue, mem, pattern, offset=0, size=None, wait_for=None)[source]¶ Enqueues a command to fill a buffer object with a pattern of a given pattern size.
TODO: Automatically determine pattern_size, perhaps in a wrapper function?
-
pycl.
clGetMemObjectInfo
(mem, param_name)[source]¶ Parameters: - mem –
cl_mem
- param_name – One of the
cl_mem_info
values.
Memory objects have properties that will retrieve these values for you, so you should probably use those.
- mem –
-
class
pycl.
cl_program
[source]¶ Represents an OpenCL program, a container for kernels.
Use
clCreateProgramWithSource()
orclCreateProgramWithBinary()
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.
-
build
(*args, **kw)[source]¶ 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()
-
context
¶ Returns the context the program exists within.
-
reference_count
¶ Reference count for OpenCL garbage collector.
-
num_devices
¶ Number of devices the program exists on.
-
devices
¶ Devices on which the program exists.
-
source
¶ Program’s source code, if available.
-
binary_sizes
¶ Sizes, in bytes, of the binaries for each of the devices the program is compiled for.
-
binaries
¶ Acquires the binaries for each device.
-
build_status
(device=None)[source]¶ Retrieves the
cl_program_build_status
for one of more devices. See alsoclGetProgramBuildInfo()
-
build_options
(device=None)[source]¶ Retrieves the build options, as a string, for one of more devices. See also
clGetProgramBuildInfo()
.
-
build_log
(device=None)[source]¶ Returns the build log, as a string, for one or more devices. Mostly useful for checking compiler errors. See also
clGetProgramBuildInfo()
.
-
-
pycl.
clGetProgramInfo
(program, param_name)[source]¶ Parameters: - program –
cl_program
- param_name – One of the
cl_program_info
values.
- program –
-
pycl.
clGetProgramBuildInfo
(program, param_name, device=None)[source]¶ Parameters: - program – The
cl_program
to check. - param_name – One of the
cl_program_build_info
values. - device – A
cl_device
instance, or list of them.
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()
, andbuild_log()
methods of program objects are equivalent to using this, so they may be preferable.- program – The
-
pycl.
clCreateProgramWithSource
(context, source)[source]¶ Parameters: - context – Context in which the program will exist
- source – Source code, as a string.
Remember to call
build()
on the program.
-
pycl.
clBuildProgram
(program, options=None, devices=None)[source]¶ Compiles a source program to run on one or more devices.
Parameters: - program – The
cl_program
to build. - options – (optional) string with compiler options. See your OpenCL spec and platform provider’s docs for possible values.
- devices – A list of devices to compile the program for. If not provided, it will be built for all devices in the context.
If the build fails, it will raise a
ProgramBuildFailureError
with details.- program – The
-
class
pycl.
cl_kernel
[source]¶ 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.
-
name
¶ Name of the kernel function.
-
program
¶ The
cl_program
this kernel lives in.
-
context
¶ The
cl_context
this kernel lives in.
-
num_args
¶ Number of arguments required to call this kernel.
-
reference_count
¶ Reference count for OpenCL garbage collector.
-
setarg
(index, value=None, size=None)[source]¶ Sets one of the kernel’s arguments.
Parameters: - index – 0-based argument number to set.
- value – Value to set it to. Can be a
cl_mem
, a Python int or float, or alocalmem
object to indicate local memory allocation. - size – The size of the parameter, in bytes. PyCL will
attempt to guess if you don’t tell it here or by setting
argtypes
. Guessing is bad.
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’sargtypes
field to a list of types. The types should be eithercl_mem
,localmem
, a scalar type such ascl_int
, or a ctypes structure type.
-
argtypes
¶ 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.
-
on
(queue, *args, **kw)[source]¶ Enqueue the kernel (hopefully after setting its arguments) upon a command queue. This is essetially a shortcut for
clEnqueueNDRangeKernel()
.
-
work_group_size
(device=None)[source]¶ The maximum size of workgroups for this kernel on the specified device.
-
compile_work_group_size
(device=None)[source]¶ The work group size specified by the kernel source, if any. Otherwise, will return (0,0,0).
-
local_mem_size
(device=None)[source]¶ The amount of local memory that would be used by this kernel on the given device with its current argument set.
-
-
pycl.
clCreateKernel
(program, kernel_name)[source]¶ Parameters: - program –
cl_program
- kernel_name – String naming a kernel function in the program.
Using the the
program[kernel_name]
syntax is preferable.- program –
-
pycl.
clGetKernelInfo
(kernel, param_name)[source]¶ Parameters: - kernel –
cl_kernel
- param_name – One of the
cl_kernel_info
values.
Kernel objects have properties that call this function, so it is probably preferable to use those instead.
- kernel –
-
pycl.
clGetKernelWorkGroupInfo
(kernel, param_name, device=None)[source]¶ Parameters: - kernel –
cl_kernel
- param_name – One of the
cl_kernel_work_group_info
values. - device –
cl_device
. If no device is specified, the first device in the kernel’s context is queried.
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.
- kernel –
-
class
pycl.
localmem
(size)[source]¶ 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)
-
pycl.
clSetKernelArg
(kernel, index, value=None, size=None)[source]¶ Parameters: - kernel –
cl_kernel
- index – 0-based argument index to set.
- value – Should be None or a pointer to a ctypes
scalar or a
cl_mem
object. Does not acceptlocalmem
. - size – Size in bytes of the referenced value. That is,
if the argument is a 32-bit integer, this should be 4. If
the argument is a
cl_mem
, it should besizeof(cl_mem)
.
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. Setcl_kernel.argtypes
if it can’t guess the types properly.- kernel –
-
pycl.
clEnqueueNDRangeKernel
(queue, kernel, gsize=(1, ), lsize=None, offset=None, wait_for=None)[source]¶ 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: - queue –
cl_command_queue
to enqueue it upon. - kernel – The
cl_kernel
object you want to run. - gsize – Global work size. A 1-, 2-, or 3-tuple of integers indicating the dimensions of the work to be done. A scalar is fine too. Default is a single work item.
- lsize – Local work size. Should have the same dimension as
gsize
. If None (the default), OpenCL will pick a size for you. - offset – Global work item offset. By default, the global id of
work items start at 0 in each dimension. Provide a tuple of the same
dimension as
gsize
to offset the ids. - wait_for – A
cl_event
or list of them that should complete prior to this kernel’s execution.
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.- queue –
-
pycl.
buffer_from_ndarray
(queue, ary, buf=None, **kw)[source]¶ Creates (or simply writes to) an OpenCL buffer using the contents of a Numpy array.
Parameters: - queue –
cl_command_queue
to enqueue the write to. - ary –
numpy.ndarray
object, or other object implementing the array interface. We haven’t wrapped the rectangular read/write functions yet, so if the array isn’t contiguous, a copy will be made. Note that the entirety of the provided array will be written, so be sure to slice it down to just the part you want to write. - buf –
cl_mem
object. If not provided, one the size of the array will be created. In any event, it should hopefully be large enough to hold the provided array.
Returns: (buf, evt)
, whereevt
is thecl_event
returned by the write operation.Any additional provided keyword arguments are passed along to
clEnqueueWriteBuffer()
.- queue –
-
pycl.
buffer_to_ndarray
(queue, buf, out=None, like=None, dtype='uint8', shape=None, **kw)[source]¶ Reads from an OpenCL buffer into an ndarray.
Parameters: - queue – The queue to put the read operation on.
- buf – The
cl_mem
to read from - out – The
numpy.ndarray
to read into. If not provided, one will be created based on the following arguments. Unlikebuffer_from_array()
, this must currently be an actual contiguousndarray
object. - like – Only relevant if no out array is provided. The new array will have the same shape and dtype as this value.
- dtype – Only relevant if no out array or
like
parameter are provided. Anumpy.dtype
or anything that can pass for one. Defaults to'uint8'
. - shape – Only relevant if no out array or
like
parameter are provided. Integer or tuple determining the array’s shape. If no shape is given, the array will be 1d and will have a number of elements based on the buffer’s size and the itemsize of the dtype.
Returns: (ary, evt)
, whereevt
is thecl_event
returned by the read operation.Any further keyword arguments are passed directly to
clEnqueueReadBuffer()
.
-
pycl.
buffer_from_pyarray
(queue, ary, buf=None, **kw)[source]¶ Essentially the same as
buffer_from_ndarray()
, except that it accepts arrays from thearray
module in Python’s standard library.
-
pycl.
buffer_to_pyarray
(queue, buf, out=None, like=None, typecode='B', length=None, **kw)[source]¶ Essentially the same as
buffer_to_ndarray()
, except that it produces arrays from thearray
module in Python’s standard library. Thedtype
andshape
parameters are replaced:Parameters: - typecode – A character indicating the array typecode. See the documentation for the mappings to C data types. The default is ‘B’, for unsigned bytes.
- length – The number of elements that should be in the array. If not provided, it will be determined based on the buffer size and the size of the selected typecode.