cldrive

cldrive

Run arbitrary OpenCL kernels.

Attributes

__version__ : str
PEP 440 compiliant package version.
cldrive.assert_or_raise(stmt, exception, *exception_args, **exception_kwargs)[source]

If the statement is false, raise the given exception.

Return type:None

cldrive.args

Attributes

NUMPY_TYPES : Dict[str, np.dtype]
A lookup table mapping OpenCL data type names to the corresponding numpy data type.
NUMPY_TYPES : Dict[np.dtype, str]
The inverse lookup table of NUMPY_TYPES.
class cldrive.args.ArgumentExtractor(*args, **kwargs)[source]

Extract kernel arguments from an OpenCL AST.

Raises:

ValueError

If source contains more than one kernel definition.

Attributes

args (List[KernelArg]) List of KernelArg instances.
name (str) Kernel name.

Methods

generic_visit(node) Called if no explicit visitor function exists for a node.
visit(node) Visit a node.
visit_FuncDef(node)
class cldrive.args.KernelArg(ast)[source]

OpenCL kernel argument representation.

exception cldrive.args.OpenCLPreprocessError(command, stdout, stderr)[source]

Raised if pre-processor fails fails.

Attributes

command (str) Pre-processor invocation
stdout (str) Pre-processor output
stderr (str) Pre-processor error output
exception cldrive.args.OpenCLValueError[source]

Raised if there is an invalid value OpenCL code

cldrive.args.extract_args(src)[source]

Extract kernel arguments for an OpenCL kernel.

Accepts the source code for an OpenCL kernel and returns a list of its arguments.

Parameters:

src : str

The OpenCL kernel source.
Returns:

List[KernelArg]

A list of the kernel’s arguments, in order.
Raises:

LookupError

If the source contains no OpenCL kernel definitions, or more than one.

ValueError

If one of the kernel’s parameter types are unsupported.

Examples

>>> args = extract_args("void kernel A(global float *a, const int b) {}")
>>> args
[global float * a, const int b]
>>> args[0].typename
'float'
>>> args[0].address_space
'global'
>>> args[1].is_pointer
False

>>> extract_args("void kernel A() {}")
[]

>>> extract_args("void /@&&& syn)")  
Traceback (most recent call last):
...
OpenCLValueError

>>> extract_args("")  
Traceback (most recent call last):
...
LookupError

>>> extract_args("void kernel A() {} void kernel B() {}")  
Traceback (most recent call last):
...
LookupError
cldrive.args.kernel_name(src)[source]

Extract the name of an OpenCL kernel.

Accepts the source code for an OpenCL kernel and returns its name.

Parameters:

src : str

The OpenCL kernel source.
Returns:

str

The kernel name.
Raises:

LookupError

If the source contains no OpenCL kernel definitions, or more than one.

Examples

>>> kernel_name("void kernel foo() {}")
'foo'
>>> kernel_name("void kernel A(global float *a, const int b) {}")
'A'
Return type:str
cldrive.args.parse(src)[source]

Parse OpenCL source code.

Parameters:

src : str

OpenCL kernel source.
Returns:

FileAST

Parsed AST.
Raises:

OpenCLValueError

The source is not well formed, e.g. it contains a syntax error, or invalid types.

:rtype: :class:`~pycparser.c_ast.FileAST`

cldrive.cgen

cldrive.cgen.emit_c(env, src, inputs, gsize, lsize, timeout=-1, optimizations=True, profiling=False, debug=False, compile_only=False, create_kernel=True)[source]

Generate C code to drive kernel.

Parameters:

env : OpenCLEnvironment

The OpenCL environment to run the kernel in.

src : str

The OpenCL kernel source.

inputs : np.array

The input data to the kernel.

optimizations : bool, optional

Whether to enable or disbale OpenCL compiler optimizations.

profiling : bool, optional

If true, print OpenCLevent times for data transfers and kernel executions to stderr.

timeout : int, optional

Cancel execution if it has not completed after this many seconds. A value <= 0 means never time out.

debug : bool, optional

If true, silence the OpenCL compiler.

compile_only: bool, optional

If true, generate code only to compile the kernel, not to generate inputs and run it.

create_kernel: bool, optional

If ‘compile_only’ parameter is set, this parameter determines whether to create a kernel object after compilation. This requires a kernel name.
Returns:

str

Code which can be compiled using a C compiler to drive the kernel.
Raises:

ValueError

If input types are incorrect.

TypeError

If an input is of an incorrect type.

LogicError

If the input types do not match OpenCL kernel types.

PorcelainError

If the OpenCL subprocess exits with non-zero return code.

RuntimeError

If OpenCL program fails to build or run.

Examples

TODO

Return type:<built-in function array>
cldrive.cgen.escape_c_string(s)[source]

quote and return the given string

Return type:str

cldrive.env

cldrive.env.all_envs(devtype='all')[source]

Iterate over all available OpenCL environments on a system.

Parameters:

devtype : str, optional

OpenCL device type to filter by, one of: {all,cpu,gpu}.
Returns:

Iterator[OpenCLEnvironment]

An iterator over all available OpenCL environments.

rtype:Iterator[OpenCLEnvironment]
cldrive.env.clinfo(file=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='UTF-8'>)[source]

Print a summary of available OpenCL devices.

Return type:None
cldrive.env.device_type(device)[source]

Get the type of an OpenCL device.

Parameters:

device : cl.Device

Pyopencl device object.
Returns:

str

OpenCL device type.
Raises:

TypeError:

If parameter is of invalid type.

Examples

On a GPU device: >>> opencl_version(device1) # doctest: +SKIP “GPU”

On a CPU device: >>> opencl_version(device2) # doctest: +SKIP “CPU”

Using oclgrind: >>> opencl_version(device) # doctest: +SKIP “Emulator”

Return type:str
cldrive.env.has_cpu()[source]

Determine if there is a CPU OpenCL device available.

Returns:

bool

True if device available, else False.

rtype:bool
cldrive.env.has_gpu()[source]

Determine if there is a CPU OpenCL device available.

Returns:

bool

True if device available, else False.

rtype:bool
cldrive.env.host_os()[source]

Get the type and version of the host operating system.

Returns:

str

Formatted <system> <release> <arch>, where <system> is the operating system type, <release> is the release version, and <arch> is 32 or 64 bit.

rtype:str
cldrive.env.make_env(platform=None, device=None, devtype='all')[source]

Create an OpenCL context and device queue.

Iterates over the available OpenCL platforms and devices looking for a device matching the requested platform ID, or platform and device ID, or device type. Constructs and returns an OpenCL context and queue for the matching device. Note that OpenCL profiling is enabled.

Parameters:

platform : str, optional

OpenCL Platform name. If not provided, any available platform may be used.

device : str, optional

OpenCL Device name. If not provided, any available device may be used.

devtype : str, optional

OpenCL device type to use, one of: {all,cpu,gpu}.
Returns:

OpenCLEnvironment

A named tuple consisting of the platform and device name.
Raises:

LookupError

If no matching device found.

RuntimeError

In case an OpenCL API call fails.

Examples

To generate an environment for the first available device: >>> make_env() # doctest: +SKIP Device: ..., Platform: ...

To generate an environment for a GPU device: >>> make_env(devtype=”gpu”) # doctest: +SKIP Device: ..., Platform: ...

To generate an environment for a specific device: >>> make_env(platform=”NVIDIA CUDA”, device=”GeForce GTX 1080”) # doctest: +SKIP Device: GeForce GTX 1080, Platform: NVIDIA CUDA

Return type:OpenCLEnvironment
cldrive.env.opencl_version(platform)[source]

Get supported OpenCL version of a platform.

Parameters:

platform : cl.Platform

Pyopencl platform object.
Returns:

str

OpenCL version supported by platform.
Raises:

TypeError:

If parameter is of invalid type.

LookupError:

If the OpenCL version cannot be determined from the output of CL_PLATFORM_VERSION.

Examples

With a platform that supports OpenCL 1.2: >>> opencl_version(platform1) # doctest: +SKIP “1.2”

With a platform that supports OpenCL 2.0: >>> opencl_version(platform2) # doctest: +SKIP “2.0”

Return type:str

cldrive.data

class cldrive.data.Generator[source]

An enumeration.

Methods

ARANGE(x)
ONES(shape[, dtype, order])
RAND
ZEROS
cldrive.data.make_data(src, size, data_generator, scalar_val=None)[source]

Generate data for OpenCL kernels.

Creates a numpy array for each OpenCL argument, except arguments with the ‘local’ qualifier, since those are instantiated.

Returns:

np.array

The generated data.
Raises:

TypeError

If any of the input arguments are of incorrect type.

ValueError

If any of the arguments cannot be interpreted.

Examples

>>> make_data("kernel void A(global int* a, const int b) {}", 3, Generator.ZEROS)
array([array([0, 0, 0], dtype=int32), array([3], dtype=int32)], dtype=object)

>>> make_data("kernel void A(global int* a, const int b) {}", 3, Generator.ONES)
array([array([1, 1, 1], dtype=int32), array([3], dtype=int32)], dtype=object)

>>> make_data("kernel void A(global int* a, const int b) {}", 3, Generator.ARANGE)
array([array([0, 1, 2], dtype=int32), array([3], dtype=int32)], dtype=object)

Use scalar_val parameter to fix the value of scalar arguments:

>>> make_data("kernel void A(global int* a, const int b) {}", 3, Generator.ARANGE, scalar_val=100)
array([array([0, 1, 2], dtype=int32), array([100], dtype=int32)], dtype=object)
Return type:<built-in function array>

cldrive.driver

class cldrive.driver.ArgTuple(hostdata, devdata)

Attributes

devdata Alias for field number 1
hostdata Alias for field number 0

Methods

count(...)
index((value, [start, ...) Raises ValueError if the value is not present.
devdata

Alias for field number 1

hostdata

Alias for field number 0

class cldrive.driver.NDRange[source]

A 3 dimensional NDRange tuple. Has components x,y,z.

Examples

>>> NDRange(1, 2, 3)
[1, 2, 3]

>>> NDRange(1, 2, 3).product
6

>>> NDRange(10, 10, 10) > NDRange(10, 9, 10)
True

Attributes

x Alias for field number 0
y Alias for field number 1
z Alias for field number 2

Methods

count(...)
from_str() Parse an NDRange from a string of format ‘x,y,z’.
index((value, [start, ...) Raises ValueError if the value is not present.
static from_str()[source]

Parse an NDRange from a string of format ‘x,y,z’.

Parameters:

string : str

Comma separated NDRange values.
Returns:

NDRange

Parsed NDRange.
Raises:

ValueError:

If the string does not contain three comma separated integers.

Examples

>>> NDRange.from_str('10,11,3')
[10, 11, 3]

>>> NDRange.from_str('10,11,3,1')  
Traceback (most recent call last):
...
ValueError
Return type:NDRange
product

linear product is x * y * z

Return type:int
exception cldrive.driver.PorcelainError(status)[source]

raised if porcelain subprocess exits with non-zero return code

exception cldrive.driver.Timeout(timeout)[source]

thrown if kernel executions fails to complete before timeout

cldrive.driver.drive(env, src, inputs, gsize, lsize, timeout=-1, optimizations=True, profiling=False, debug=False)[source]

Drive an OpenCL kernel.

Executes an OpenCL kernel on the given environment, over the given inputs. Execution is performed in a subprocess.

Parameters:

env : OpenCLEnvironment

The OpenCL environment to run the kernel in.

src : str

The OpenCL kernel source.

inputs : np.array

The input data to the kernel.

optimizations : bool, optional

Whether to enable or disbale OpenCL compiler optimizations.

profiling : bool, optional

If true, print OpenCLevent times for data transfers and kernel executions to stderr.

timeout : int, optional

Cancel execution if it has not completed after this many seconds. A value <= 0 means never time out.

debug : bool, optional

If true, silence the OpenCL compiler.
Returns:

np.array

A numpy array of the same shape as the inputs, with the values after running the OpenCL kernel.
Raises:

ValueError

If input types are incorrect.

TypeError

If an input is of an incorrect type.

LogicError

If the input types do not match OpenCL kernel types.

PorcelainError

If the OpenCL subprocess exits with non-zero return code.

RuntimeError

If OpenCL program fails to build or run.

Examples

A simple kernel which doubles its inputs:

>>> src = "kernel void A(global int* a) { a[get_global_id(0)] *= 2; }"
>>> inputs = [[1, 2, 3, 4, 5]]
>>> drive(make_env(), src, inputs, gsize=(5,1,1), lsize=(1,1,1)) 
array([[ 2,  4,  6,  8, 10]], dtype=int32)
Return type:<built-in function array>

Command Line Interface

usage: cldrive [-h] [--version] [--clinfo] [-p <platform name>]
               [-d <device name>] [--devtype <devtype>] [-s <size>]
               [-i <{rand,arange,zeros,ones}>] [--scalar-val <float>]
               [-g <global size>] [-l <local size>] [-t <timeout>] [--no-opts]
               [--profiling] [--debug] [-b]

Reads an OpenCL kernel from stdin, generates data for it, executes it on a
suitable device, and prints the outputs. Copyright (C) 2017 Chris Cummins
<chrisc.101@gmail.com>. <https://github.com/ChrisCummins/cldrive>

optional arguments:
  -h, --help            show this help message and exit
  --version             show version information and exit
  --clinfo              list available OpenCL devices and exit
  -p <platform name>, --platform <platform name>
                        use OpenCL platform with name, e.g. 'NVIDIA CUDA'
  -d <device name>, --device <device name>
                        use OpenCL device with name, e.g. 'GeForce GTX 1080'
  --devtype <devtype>   use any OpenCL device of type {all,cpu,gpu} (default:
                        all)
  -s <size>, --size <size>
                        size of input arrays to generate (default: 64)
  -i <{rand,arange,zeros,ones}>, --generator <{rand,arange,zeros,ones}>
                        input generator to use, one of:
                        {rand,arange,zeros,ones} (default: arange)
  --scalar-val <float>  values to assign to scalar inputs (default: <size>
                        argumnent)
  -g <global size>, --gsize <global size>
                        comma separated NDRange for global size (default:
                        64,1,1)
  -l <local size>, --lsize <local size>
                        comma separated NDRange for local (workgroup) size
                        (default: 32,1,1)
  -t <timeout>, --timeout <timeout>
                        error if execution has not completed after this many
                        seconds(default: off)
  --no-opts             disable OpenCL optimizations (on by default)
  --profiling           enable kernel and transfer profiling
  --debug               enable more verbose OpenCL copmilation and execution
  -b, --binary          Print outputs as a pickled binary numpy array

Indices and tables