PySchedCL API documentation

pyschedcl.pyschedcl module

class pyschedcl.pyschedcl.HostEvents(kernel_name='', kernel_id='', dispatch_id='', dispatch_start=None, dispatch_end=None, create_buf_start=None, create_buf_end=None, write_start=None, write_end=None, ndrange_start=None, ndrange_end=None, read_start=None, read_end=None)[source]

Bases: object

Class for storing timing information of various events associated with a kernel.

Variables:
  • dispatch_start – Start Timestamp for dispatch function
  • dispatch_end – End Timestamp for dispatch function
  • create_buf_start – Start Timestamp for Creation of Buffers
  • create_buf_end – End Timestamp for Creation of Buggers
  • write_start – Start TimeStamp for Enqueuing Write Buffer Commands on Command Queue
  • write_end – End Timestamp for Writing of Buffers to Device
  • ndrange_start – Start TimeStamp for Launching Kernel
  • ndrange_end – End Timestamp for when kernel execution is finished on device
  • read_start – Start TimeStamp for Enqueuing Read Buffer Commands on Command Queue
  • read_end – End TimeStamp for Reading of Buffers from Device to Host
  • kernel_name – Name of kernel
  • kernel_id – Unique id for kernel
  • dispatch_id – Dispatch id for kernel
class pyschedcl.pyschedcl.Kernel(src, dataset=1024, partition=None, identifier=None)[source]

Bases: object

Class to handle all operations performed on OpenCL kernel.

Variables:
  • dataset – An integer representing size of the data on which kernel will be dispatched.
  • id – An id that is used identify a kernel uniquely.
  • eco – A dictionary mapping between size of dataset and Estimated Computation Overhead
  • name – Name of the Kernel
  • src – Path to the Kernel source file.
  • partition – An integer denoting the partition class of the kernel.
  • work_dimension – Work Dimension of the Kernel.
  • global_work_size – A list denoting global work dimensions along different axes.
  • local_work_size – A list denoting local work dimensions along different axes.
  • buffer_info – Properties of Buffers
  • input_buffers – Dictionaries containing actual cl.Buf f er objects.
  • output_buffers – Dictionaries containing actual cl.Buf f er objects.
  • io_buffers – Dictionaries containing actual cl.Buf f er objects.
  • data – Numpy Arrays maintaining the input and output data of the kernels.
  • buffer_deps – Dictionary mapping containing buffer dependencies.
  • variable_args – Data corresponding to Variable arguments of the kernel.
  • local_args – Information regarding Local Arguments of the kernel.
  • objects (kernel) – Dictionary mapping between devices and compiled and built pyopencl.Kernel objects.
  • events – Dictionary containing pyschedcl.KEvents.
  • source – String containing contents of kernel file.
  • clevents – Dictionary containing pyopencl.Events.
build_kernel(gpus, cpus, ctxs)[source]

Builds Kernels from the directory kernel_src/ for each device and stores binaries in self.kernel_objects dict.

Parameters:
  • gpus (list of pyopencl.device objects) – List of OpenCL GPU Devices
  • cpus (list of pyopencl.device objects) – List of OpenCL GPU Devices
  • ctxs (dict) – Dictionary of contexts keyed by device types
Returns:

Dictionary of key: value pairs where key is device type and value is the device specific binary compiled for the kernel
Return type:

dict
create_buffers(ctx, obj, size_percent=100, offset_percent=0, **kwargs)[source]

Creates buffers for a Context while respecting partition information provided for every buffer associated with the kernel.

Parameters:
  • ctx (pyopencl.Context) – PyOpenCL Context for either a CPU or a GPU device
  • obj (String) – Device Type
  • size_percent (Float) – Size of valid buffer space for device
  • offset_percent – Offset parameter representing
  • kwargs –
dispatch(gpu, cpu, ctxs, cmd_qs, dep=None, partition=None, callback=<function blank_fn>)[source]

Dispatches Kernel with given partition class value (0,1,2,...,10). 0 is for complete CPU and 10 is for complete GPU.

Parameters:
  • gpu (Integer) – Denotes the index of GPU device in cmd_qs[‘gpu’] list or is -1 if we don’t want to use device of this type.
  • cpu (Integer) – Denotes the index of CPU device in cmd_qs[‘cpu’] list or is -1 if we don’t want to use device of this type.
  • ctxs (dict) – Dictionary of Contexts for CPU and GPU devices.
  • cmd_qs (dict) – Dictionary of list of Command Queues
  • dep – PyOpenCL Event on which subsequent write operations will be dependent on stored in a list
  • partition (Integer) – Integer from 0 to 10 or None denoting partition class value.
  • callback – A function that will run on the host side once the kernel completes execution on the device. Handle unexpected arguments.
Returns:

Tuple with first element being the starting time (host side) of dispatch and second element being list of kernel events for both CPU and GPU devices
Return type:

Tuple
dispatch_multiple(gpus, cpus, ctxs, cmd_qs, dep=None, partition=None, callback=<function blank_fn>)[source]

Dispatch Kernel across multiple devices with given partition class value (0,1,2,...,10). 0 is for complete CPU and 10 is for complete GPU.

Parameters:
  • gpus (list) – A list of gpu device ids
  • cpus (list) – A list of cpu device ids
  • ctxs (dict) – Dictionary of Contexts for CPU and GPU devices.
  • cmd_qs (dict) – Dictionary of list of Command Queues
  • dep – PyOpenCL Event on which subsequent write operations will be dependent on stored in a list
  • partition (Integer) – Integer from 0 to 10 or None denoting partition class value.
  • callback – A function that will run on the host side once the kernel completes execution on the device. Handle unexpected arguments.
Returns:

Tuple with the first element being the starting time (host side) of dispatch and second element being list of kernel events for both CPU and GPU devices
Return type:

Tuple
enqueue_nd_range_kernel(queue, q_id, obj, size_percent=100, offset_percent=0, deps=None, **kwargs)[source]

Enqueues ND Range Kernel Operation for a kernel

Parameters:
  • queue (pyopencl.CommandQueue) – OpenCL Command Queue
  • q_id (Integer) – Framework specific id assigned to Command Queue
  • obj (String) – OpenCL Device Type
  • size_percent (Integer) – Percentage of problem space to be processed
  • offset_percent (Integer) – Percentage for offset required for selection of host array space to be copied to buffer
  • deps (list of pyopencl.Event Objects) – PyOpenCL Event on which subsequent ndrange operations will be dependent on stored in a list
  • kwargs –
Returns:

Barrier Event signifying end of ndrange operation
Return type:

pyopencl.event
enqueue_read_buffers(queue, q_id, obj, size_percent=100, offset_percent=0, deps=None, callback=<function blank_fn>, **kwargs)[source]

Enqueue Read Buffer operations for a kernel.

Parameters:
  • queue (pyopencl.CommandQueue) – OpenCL Command Queue
  • q_id (Integer) – Framework specific id assigned to Command Queue
  • obj (String) – OpenCL Device Type
  • size_percent (Integer) – Percentage of problem space to be processed
  • offset_percent (Integer) – Percentage for offset required for selection of host array space to be copied to buffer
  • deps (list of pyopencl.Event Objects) – PyOpenCL Event on which subsequent ndrange operations will be dependent on stored in a list
  • callback (python function) – Custom callback function
  • kwargs –
Returns:

Barrier Event signifying end of read operation
Return type:

pyopencl.event
enqueue_write_buffers(queue, q_id, obj, size_percent=100, offset_percent=0, deps=None, **kwargs)[source]

Enqueues list of write buffer operations to the OpenCL Runtime.

Parameters:
  • queue (pyopencl.CommandQueue) – Command Queue for a CPU or a GPU device
  • q_id (Integer) – ID of queue
  • obj (String) – Device Type (CPU or GPU)
  • size_percent (Integer) – Percentage of problem space to be processed
  • offset_percent (Integer) – Percentage for offset required for selection of host array space to be copied to buffer
  • deps (list of pyopencl.Event Objects) – Initial PyOpenCL Event on which subsequent write operations will be dependent stored in a list
  • kwargs –
Returns:

Barrier Event signifying end of write operation
Return type:

pyopencl.event
eval_vargs(partition=None, size_percent=0, offset_percent=0, reverse=False, exact=-1, total=100)[source]

Method to evaluate kernel arguments. Evaluates variable kernel arguments from the specification file if they are an expression against size percent.

Parameters:
  • partition (Integer) – Partition Class Value
  • size_percent (Integer) – Percentage of problem space to be processed on device
  • offset_percent (Integer) – Offset Percentage required
  • reverse (Boolean) – Flag for inverting size and offset calculations for respective devices
  • exact – Flag that states whether percentage of problem space is greater than 50 or not (0 for percent < 50, 1 for percent >= 50)
  • type – Integer
  • total (Integer) – Percentage of total problem space (Default value: 100)
get_buffer(pos)[source]

Returns cl.Buffer objects given its parameter position in the kernel.

Parameters: pos – Position of buffer argument in list of kernel arguments
Type: Integer
Returns: PyOpenCL Buffer Object for selected buffer
Return type: pyopencl.Buffer
get_buffer_info(pos)[source]

Returns buffer information stored in Kernel specification file for buffer at given position in Kernel Arguments. Used to make reusable buffers.

Parameters: pos (Integer) – Position of buffer argument in list of kernel arguments
Returns: Returns a dictionary of key:value pairs representing information of selected buffer in self.buffer_info
Return type: dict
get_buffer_info_location(pos)[source]

Returns buffer_info location at given position. Used to make reusable buffers.

Parameters: pos (Integer) – Position of buffer argument in list of kernel arguments
Returns: Tuple(key, i) where key represents type of buffer access and i represents the id for that buffer in self.buffer_info[key]
Return type: Tuple
get_data(pos)[source]

Returns the data of a particular kernel argument given its parameter position in the kernel. Used to load dependent data.

Parameters: pos (Integer) – Position of buffer argument in list of kernel arguments
Returns: Data stored in buffer specified by parameter position in kernel
Return type: Numpy array
get_device_requirement()[source]
get_num_global_work_items()[source]

Returns the total number of global work items based on global work size.

Returns: Total number of global work items considering all dimensions
Return type: Integer
get_partition_multiples()[source]

Determines partition multiples based on work dimension. This method returns a list of numbers based on global work size and local work size according to which the partition sizes will be determined.

Returns: List of integers representing partition multiples for each dimension
get_slice_values(buffer_info, size_percent, offset_percent, **kwargs)[source]

Returns Element offset, size based on size_percent, offset_percent.

Parameters:
  • buffer_info (dict) – Dictionary of key:value pairs representing information of one buffer
  • size_percent (Float) – Size of buffer to be processed (in percentage)
  • offset_percent (Float) – Offset for given buffer (in percentage)
  • kwargs –
Returns:

Tuple representing element offset and number of elements
Return type:

Tuple
load_data(data)[source]

Populates all host input arrays with given data.

Parameters: data (dict) – Dictionary structure comprising user defined data for host input arrays
random_data(low=0, hi=4096)[source]

Generates random data numpy arrays according to buffer type so that it can be enqueued to buffer. Can be used for testing. Will not generate random data for those buffers that are already enqueued. Creates empty arrays for read-only buffers. Populates values for self.data dictionary.

Parameters:
  • low (Integer) – Lower value of data array size
  • hi (Integer) – Higher value of data array size
release_buffers(obj)[source]

Releases all buffers of a Kernel Object for a particular device given in obj

Parameters: obj (String) – Specifies Kernel object
release_host_arrays()[source]

Forcefully releases all host array data after completion of a kernel task

set_kernel_args(obj)[source]

Sets Kernel Arguments (Buffers and Variable Arguments).

Parameters: obj (String) – Device Type (cpu or gpu)
pyschedcl.pyschedcl.blank_fn(*args, **kwargs)[source]

Does nothing. Used as dummy function for callback events.

pyschedcl.pyschedcl.build_kernel_from_info(info_file_name, gpus, cpus, ctxs)[source]

Create Kernel object from info.

Parameters:
  • info_file_name (String) – Name of OpenCL Kernel Specification File (JSON)
  • gpus (list of pyopencl.device objects) – List of OpenCL GPU devices
  • cpus (list of pyopencl.device objects) – List of OpenCL CPU devices
  • ctxs (dict) – Dictionary of contexts keyed by device types
Returns:

Dictionary of key: value pairs where key is device type and value is the device specific binary compiled for the kernel
Return type:

dict
pyschedcl.pyschedcl.compare_and_swap(testval, newval)[source]

Software test and lock routine used for enforcing mutual exclusion across multiple callback threads.

Parameters:
  • testval (list) – List representing testing lock value
  • newval (list) – List representing new lock value
Returns:

Returns list representing old lock value.
Return type:

list
pyschedcl.pyschedcl.create_command_queue_for_each(devs, ctx)[source]

Creates command queue for a specified number of devices belonging to a context provided as argument

Parameters:
  • devs (List of pyopencl.device objects) – List of OpenCL devices
  • ctx – OpenCL Context
Rtype ctx:

pyopencl.context object
Returns:

List of OpenCL Command Queues
Return type:

list of pyopencl.CommandQueue objects
pyschedcl.pyschedcl.ctype(dtype)[source]

Convert a string datatype to corresponding Numpy datatype. User can also define new datatypes using user_defined parameter.

Parameters: dtype (String) – Datatype name
Returns: Numpy Datatype corresponding to dtype
pyschedcl.pyschedcl.dump_device_history()[source]

Dumps device history to debug.log file.

pyschedcl.pyschedcl.generate_unique_id()[source]

Generates and returns a unique id string.

Returns: Unique ID
Return type: String
pyschedcl.pyschedcl.get_multiple_devices(platform, dev_type, num_devs)[source]

Get Multiple Devices given a platform and dev type.

Parameters:
  • platform (pyopencl.platform object) – OpenCL Platform pertaining to some vendor
  • dev_type (pyopencl.device_type object) – Device Type (CPU or GPU)
  • num_devs (Integer) – Number of Devices
Returns:

List of OpenCL devices
Return type:

list of pyopencl.device objects
pyschedcl.pyschedcl.get_platform(vendor_name)[source]

Gets platform given a vendor name

Parameters: vendor_name (string) – Name of OpenCL Vendor
Returns: OpenCL platform related with vendor name
Return type: PyOpenCL platform object
pyschedcl.pyschedcl.get_single_device(platform, dev_type)[source]

Get Single Device given a platform and dev type.

Parameters:
  • platform (pyopencl.platform object) – OpenCL platform pertaining to some vendor
  • dev_type (pyopencl.device_type object) – Device Type (CPU or GPU)
Returns:

List containing one OpenCL device
Return type:

List containing one pyopencl.device object
pyschedcl.pyschedcl.get_sub_devices(platform, dev_type, num_devs, total_compute=16)[source]

Get Sub Devices given a platform and dev type.

Parameters:
  • platform (pyopencl.platform object) – OpenCL platform pertaining to some vendor
  • dev_type (pyopencl.device_type object) – Device Type (CPU or GPU)
  • num_devs (Integer) – Number of devices
  • total_compute (Integer) – Total Number of Compute Units for an OpenCL device
Returns:

List of OpenCL subdevices for a particular device
Return type:

list of pyopencl.device objects
pyschedcl.pyschedcl.host_initialize(num_gpus=4, num_cpus=2, local=False, cpu_platform='Intel(R) OpenCL', gpu_platform='NVIDIA CUDA')[source]

Set local=True if your device doesn’t support GPU. But you still want to pretend as if you have one.

Parameters:
  • num_gpus (Integer) – Number of GPU Devices
  • num_cpus (Integer) – Number of CPU Devices
  • local (Boolean) – Flag for Specifying whether platform supports GPU or not
  • cpu_platform (String) – CPU Platform Name
  • gpu_platform (String) – GPU Platform Name
Returns:

Returns a tuple comprising command queue dictionary, context dictionary and list of OpenCL CPU and GPU devices.
Return type:

Tuple
pyschedcl.pyschedcl.host_synchronize(cmd_qs, events)[source]

Ensures that all operations in all command queues and associated events have finished execution

Parameters:
  • cmd_qs (dict) – Dictionary of list of Command Queues
  • events (list of pyopencl.events) – List of OpenCL Events
pyschedcl.pyschedcl.make_ctype(dtype)[source]

Creates a vector datatype.

Parameters: dtype (String) – Datatype name
Returns: numpy datatype corresponding to dtype
pyschedcl.pyschedcl.make_user_defined_dtype(ctxs, name, definition)[source]
pyschedcl.pyschedcl.multiple_round(elms, percent, multiples, **kwargs)[source]

Partitions such that the partitioned datasets are multiples of given number.

Parameters:
  • elms (Integer) – Total number of elements of buffer
  • percent (Integer) – Percentage of problem space to be processed by one device
  • multiples (list of integers) – List of integers representing partition multiples for each dimension
  • kwargs –
Returns:

Percentage of buffer space to be partitioned for one device
Return type:

Integer
pyschedcl.pyschedcl.notify_callback(kernel, device, dev_no, event_type, events, host_event_info, callback=<function blank_fn>)[source]

A wrapper function that generates and returns a call-back function based on parameters. This callback function is run whenever a enqueue operation finishes execution. User can suitably modify callback functions to carry out further processing run after completion of enqueue read buffers operation indicating completion of a kernel task.

Parameters:
  • kernel (pyschedcl.Kernel object) – Kernel Object
  • device (String) – Device Type (CPU or GPU)
  • dev_no (Integer) – PySchedCL specific device id
  • event_type (String) – Event Type (Write, NDRange, Read)
  • events (list of pyopencl.Event objects) – List of Events associated with an Operation
  • host_event_info (HostEvents) – HostEvents object associated with Kernel
  • callback (python function) – Custom Callback function for carrying out further post processing if required.
pyschedcl.pyschedcl.part_round(elms, percent, exact=-1, total=100, *args, **kwargs)

Partitions dataset in a predictable way.

Parameters:
  • elms (Integer) – Total Number of elements
  • percent – Percentage of problem space to be processed on one device
  • type – Integer
  • exact – Flag that states whether percentage of problem space is greater than 50 or not (0 for percent < 50, 1 for percent >= 50)
  • type – Integer
  • total (Integer) – Percentage of total problem space (Default value: 100)
Returns:

Number of elements of partitioned dataset
Return type:

Integer
pyschedcl.pyschedcl.partition_round(elms, percent, exact=-1, total=100, *args, **kwargs)[source]

Partitions dataset in a predictable way.

Parameters:
  • elms (Integer) – Total Number of elements
  • percent – Percentage of problem space to be processed on one device
  • type – Integer
  • exact – Flag that states whether percentage of problem space is greater than 50 or not (0 for percent < 50, 1 for percent >= 50)
  • type – Integer
  • total (Integer) – Percentage of total problem space (Default value: 100)
Returns:

Number of elements of partitioned dataset
Return type:

Integer
pyschedcl.pyschedcl.plot_gantt_chart_graph(device_history, filename)[source]

Plots Gantt Chart and Saves as png.

Parameters:
  • device_history (dict) – Dictionary Structure containing timestamps of every kernel on every device
  • filename (String) – Name of file where the Gantt chart is saved. The plot is saved in gantt_charts folder.
pyschedcl.pyschedcl.test_and_set(testval, newval)[source]

Software test and lock routine used for enforcing mutual exclusion across callback threads and main host thread while accessing ready queue and device counters.

Parameters:
  • testval (list) – List representing testing lock value
  • newval (list) – List representing new lock value
Returns:

Returns list representing old lock value.
Return type:

list