simple_cl Module
================
   
This module provides a convenient method for working with openCL via pyopencl,
by simplifying access to devices, allowing precision to be determined on the
fly and by providing common complex variable functions.

It also simplifies function calls be assuming that the desired number of
work-groups and work-items is the number of compute units and max workgroup
size, respectively.  This means the looping needs to be handled in the kernel,
as in the example below.

Overview
--------

.. currentmodule:: ilpm.simple_cl

.. autosummary:: 
    CLSession
    acquire_opencl_devices
    is_job_done
    get_device_info


Example Usage
-------------

.. code-block:: python

    from ilpm import simple_cl
    import numpy as np
    import time
    
    NP = 10**6
    REPEATS = 10
    
    #Here we are creating the an OpenCL context on the CPU.  Why bother?  This
    #  causes the code execution to be multithreaded, which should speed it up!
    ctx = simple_cl.CLSession(device='cpu', use_doubles=False)
    
    #OpenCL code
    ctx.compile('''
        __kernel void dot_product(__global REAL* a, __global REAL* b, int np, __global REAL* result)
        {
            for(int i = get_global_id(0); i < np; i += get_global_size(0)) {
            result[i] = dot(get_3D(a, i), get_3D(b, i));
            }
        }''')
    
    #Initial data
    a = np.random.rand(NP, 3)
    b = np.random.rand(NP, 3)
    
    #Create version of data on device
    a_cl = ctx.to_device(a)
    b_cl = ctx.to_device(b)
    result_cl = ctx.empty(NP)
    
    #Run in OpenCL
    start = time.time()
    for n in range(REPEATS):
        event = ctx.dot_product(a_cl, b_cl, NP, result_cl)
    event.wait()
    print 'OpenCL: %5.1f ms' % ((time.time() - start)*1E3)
    
    result = result_cl.get()
    
    
    #Run in numpy
    start = time.time()
    for n in range(REPEATS):
        result_n = (a*b).sum(-1)
    print ' Numpy: %5.1f ms' % ((time.time() - start)*1E3)
    
    
    #Find error; note that the OpenCL version is single precision, as we specified
    #  use_doubles=False on the context creation.  This causes an error equal to
    #  the single precision size.
    print 'Dot product error:', np.abs(result_n - result).sum() / NP

Say you want to run your code on the computer's GPU, not its CPU. This option is available with all high end recent Macs (maybe not the Macbook Airs?).
How would I find out my GPU's name to use it in my code? I'll do it below without using simple_cl.

.. code-block:: python
    import pyopencl as cl
    # Get the platform, like <pyopencl.Platform 'Apple' at 0x7fff0000>
    platform = cl.get_platforms()[0]
    # Then look at the names of devices
    device_list = platform.get_devices()
    
We can choose from the list. For instance, my MBP has 3 devices: the CPU, an Iris graphics card, and an AMD graphics card. So I could say

    ctx = simple_cl.CLSession( device = 'AMD Radeon R9 M370X Compute Engine', use_doubles=True)
    


Classes and Functions
---------------------
    
.. automodule:: ilpm.simple_cl
    :members: 
    :show-inheritance: