.. Irvine Lab Python Modules documentation master file, created by
   sphinx-quickstart on Thu May 22 16:53:29 2014.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Irvine Lab Python Modules
=========================

.. toctree::
    :maxdepth: 2
    :numbered:
	
    cine.rst
    colormaps.rst
    dxf.rst
    geometry_extractor.rst
    misc.rst
    mesh.rst
    movies.rst
    networks.rst
    path.rst
    pyopencl_scripts.rst
    raw.rst
    science_plot_style.rst
    simple_cl.rst
    vector.rst


Installation and Usage
======================

To download and install the package on OS X, clone the ilpm repository from the server using
SmartGit (recommended).
If you do not have SmartGit already, download it <a class="reference external" href="http://www.syntevo.com/smartgit/download">here</a>.
Then follow the tutorial on
<a class="reference internal" href="./how_to_use_git_repo.html">this page</a>.
If you must use a command line to pull the repo instead of SmartGit, you may run the following commands
(*this will require your password to install, as well as a log-in to the Git
server*)::

    $ git clone ssh://<YOUR_NAME>@immenseirvine.uchicago.edu/git/ilpm
    $ cd ilpm
    $ sudo python setup.py develop
    
Updates can be installed running the following command from the ``ilpm`` directory::

    $ git pull

*If you have installed the module in develop mode, as above, you don't need
to re-run setup to use the new version.*

Again, we recommend using SmartGit instead of the above.
    
Once the package has been installed, all the sub-modules will be available
as members of the ``ilpm`` package.  For example:

.. code-block:: python

    from ilpm import cine  #module will appear as 'cine'
    import ilpm.mesh       #module will appear as 'ilpm.mesh'
    
    c = cine.Cine('my_movie.cine')
    
    m = ilpm.mesh.load_mesh('some_mesh.ply')
    
Dependencies
============
There are several external modules used by ILPM:

    * Numpy/Scipy
    * Matplotlib
    * Python Image Library
    * `PySide <http://qt-project.org/wiki/PySide>`_ (used by ``view``)
    * `PyOpenGL <http://pyopengl.sourceforge.net/>`_ (used by ``view``)
    * `PyOpenCL <http://mathema.tician.de/software/pyopencl/>`_
      (used by ``simple_cl``, ``path``, and ``geometry_extractor``)
    * seaborn (to install, ``pip install seaborn``)
    
All but the last three can be obtained by installing
`Enthought Canopy <https://www.enthought.com/downloads/>`_.

On OSX, PyOpenGL and PyOpenCL can be installed using ``easy_install``::

    $ sudo easy_install pyopengl
    $ sudo easy_install pyopencl

This *might* work on a Windows or Linux system, provided OpenCL and OpenGL are
present.


Example scripts and pedagogical materials
=========================================
Also included in the ILPM distribution is a copy of ffmpeg which has been found to be very stable. Example usage is::

    subprocess.call(['./ffmpeg', '-framerate', str(int(framerate)), '-i', imgname + '_%06d.png', 'moviename.mov',
                     '-vcodec', 'libx264', '-profile:v', 'main', '-crf', '12', '-threads', '0',
                     '-r', '30', '-pix_fmt', 'yuv420p'])

Additionally, there are example scripts for using PyOpenCL in ILPM, located in the ``pyopencl_scripts subdirectory``. They include
    * pyopencl_example_four_task_kernel.py
    * simple_cl_example.py

The first code uses PyOpenCL, which is a python wrapper for OpenCL. The second uses an additional wrapper (module) called simple_cl, which is part of ILPM (written by Dustin).
Since these are scripts, not modules, they do not have a doc page, but are heavily commented. A good resource for
learning more about what they accomplish is here: http://www.drdobbs.com/open-source/easy-opencl-with-python/240162614

A quick guide would be to copy the codes ``rk4_python_example.py`` and ``simple_cl_example_spring_lattice_constvBC_breakbonds.py`` to a new directory, then run the following two lines from that directory. 
The first runs the python rk4 example, while the second does the same thing in PyOpenCL. 
The second is about 100 times faster. 
You should get a ``.mov`` video and some txt files as the output. The beta parameter is the damping, and modii sets how often to write the output to disk::
	
	python rk4_python_example.py -n_steps 1000 -modii 100 -rootdir ./example_dir/ -beta 0.1
	python simple_cl_example_spring_lattice_constvBC_breakbonds.py -n_steps 1000 -modii 100 -rootdir ./examplecl_dir/ -beta 0.1

Note that ``seaborn`` is required for either, and OpenCL is required for the latter.