Simple PyCULA Tutorial
======================

Example
--------

So how does it all work?  This example uses the PyCULA host routine to find some eigenvalues::

    # import PyCULA module
    from PyCULA.cula import *

    #initialize cula
    culaInitialize()

    #make a numpy array; you may use float32 or float64 dtypes
    cat = numpy.array([[1,2],[3,4]], dtype=numpy.float32)
    print cat

    #run PyCULA routine; print results
    lamb = gpu_eigenvalues(cat)
    print lamb

    #shutdown PyCULA
    culaShutdown()

As a matter of fact, using any of CULA's host interface functions via PyCULA in python should be this simple.

Naming Scheme
-------------

PyCULA is a complete set of wrappers for CULA and in addition provides a simplified pythonic interface wherever possible.  This means that although you may manually plug in all your data and parameters directly into the CULA C function using ctypes (blah), we have used the magic of python to do most of that tedious work for you by providing our more sophisticated gpu_* wrappers. If you use PyCULA's gpu_* functions most calls are as simple as passing array objects.

For ease of use, we follow CULA's naming convention.  An example CULA routine is 'gesv', which we would wrap as gpu_gesv.  Sometimes a function is popular (like gpu_geev or gpu_gesvd) we give it alternative names which are easier to remember like gpu_eigenvalues and gpu_svd respectively.  You may use whichever.


Getting Help
------------

First, take the time to at least skim the tutorials, because it is likely your question may be addressed.  Otherwise, try the search bar to your left, or if you know the function try our interactive help in the interpreter::

    >>>from PyCULA.cula import *
    >>>help(gpu_svd)

        Help on function gpu_svd in module PyCULA.cula:

        gpu_svd(A, left_vectors=False, right_vectors=False)
            Takes numpy.array A and computes the SVD, returns Singular Values (optionally left/right vectors) as np.arrays.

            Keyword arguments:
            A -- input matrix
            left_vectors -- default == False; computes left singular vectors
            right_vectors -- default == False; computes right singular vectors

            Refer to CULA docs regarding gesvd for specific application.
        (END) 

For more advanced tutorials, keep reading.