.. ......................................
.. UHDAS/CODAS restructured text document
.. ......................................

Additional Python functionality
===============================


(1) CODAS Extension code
~~~~~~~~~~~~~~~~~~~~~~~~~


If you do this step, your code will be able to read a CODAS database,
or uhdas "rbin" and "gbin" files with Python.  Work is underway to
develop Python tools to read single-ping ADCP data from RDI ADCPs.

**In the "near" future, this step will be required.**

Instructions:


(a) Get Cython

       `Cython <http://www.cython.org/>`_
       is a language that is written in python, and that is almost
       python, but that produces C code for compilation into python
       extensions.  Hence it provides a way to get C speed for
       critical code paths, and to access C modules and libraries
       from Python.  We have recently switched to Cython from Pyrex,
       its predecessor.

       We are using cython for several extensions in
       pycurrents, including the python interface to codas
       databases.  Although it is not yet required, quick_adcp will
       increasingly take advantage of this interface, and will in
       the future require it.

(b) Install Cython

       Cython is  easy to install.  Get the zip or tar archive and
       put it in a "downloads" location.  Unpack it and read the
       INSTALL.txt. It will probably direct you to do this (on unix
       systems you'll have to be root)


::

         python setup.py install



(c) Compile the CODAS extension code in "pycurrents"




In a shell prompt in the "pycurrents" directory, type

::

          python runsetup.py



(2) Work in progress...
~~~~~~~~~~~~~~~~~~~~~~~~~

If you proceed with the instructions in this section, you will also be
able to make plots such as these, using matplotlib:


(thumbnails are links to larger images)




.. -------------------------------------------
.. |nb150_shallow| image:: nb150_shallowT.png
                   :alt: "vector plot with topography, made with python"
.. _nb150_shallow: nb150_shallow.png
.. -------------------------------------------


.. -------------------------------------------
.. |os75nb_loncont| image:: os75nb_loncontT.png
                   :alt:  "contour plot vs/ longitude, made with python"
.. _os75nb_loncont: os75nb_loncont.png
.. -------------------------------------------


.. -------------------------------------------
.. |nb150_lastens| image:: nb150_lastensT.png
                   :alt: "profile plot, made with python"
.. _nb150_lastens: nb150_lastens.png
.. -------------------------------------------


+-------------------+
| |nb150_shallow|_  |
+-------------------+
| |os75nb_loncont|_ |
+-------------------+
| |nb150_lastens|_  |
+-------------------+




Numpy
~~~~~

`NumPy <http://www.scipy.org>`_ is the core numerical array
extension for Python, and it is central to our shift from Matlab to
Python.  `Download <http://www.scipy.org/Download>`_ and install
version 1.3 or later.  Versions available from linux distributions
will generally be old, so install from the tarball or from the svn
repository.  Binary versions are available for OSX and Windows; use
those, but pay attention to the instructions regarding Python
versions.

NOTE:: If you are installing from source, you must install Numpy
       before installing Matplotlib


Matplotlib
~~~~~~~~~~

Matplotlib is the plotting
tool we will use. Installation from  source is quite
easy on linux but can be difficult on OSX and Windows.
Increasing effort is going into improving both the ease of
installation from source and the availability of up-to-date
binary packages for OSX and Windows.


- download and install the latest
  `matplotlib <http://matplotlib.sourceforge.net>`_
  and its mapping toolbox,
  `basemap <http://matplotlib.sourceforge.net/users/toolkits.html>`_
  to be able to generate pictures like the above.


iPython
~~~~~~~

iPython is an extremely useful python shell which interacts well
with matplotlib.  You can get it `here <http://ipython.scipy.org/moin/>`_


Scipy: OPTIONAL
~~~~~~~~~~~~~~~~


Scipy is a sprawling, uneven library that can take advantage of many
external libraries and of a Fortran compiler.  We are trying to NOT
rely on scipy.

However, if you want to be able to read matlab binary files ("\*.mat")
from python, download and install `scipy <http://www.scipy.org>`_.
Simple functionality like reading "mat" files doesn't require any of
the fancy parts.