*************
 Introduction
*************

.. _prerequisites:

===============
 Prerequisites
===============
In order to use the PyMMF package libraries, you should have the
following installed and working.

Enthought Python Distribution
=============================
This is not a strict requirement, but most of following dependencies
will be satisfied if you use the `Enthought Python Distribution`_
(EPD_).  This is a recommended way of installing a current version of
python and most of the required tools.

There is one major caveat however.  You must have a binary compatible
compiler and libraries installed on your system corresponding to the
version used to compile the EPD_.  In particular, if you have a 64 bit
OS (with the corresponding 64 bit libraries), then you probably need
to install the 64 bit version of EPD_ to make use of the extension
packages and compiled code.

If you can't get the correct EPD_ distribution, then you may have to
install a compatible compiler and compile a version of the standard
libraries compatible with what EPD_ was compiled with in order to use
these features.  (See my `Gobo`_ install package for some ideas about
how you might do this without root access.)

I suspect that if you purchase one of the subscriptions, then you will
receive some support with this.  (Note that the EPD_ is now available in
both 32 and 64 bit versions for academic use.)

.. _Enthought Python Distribution: http://www.enthought.com/products/epd.php
.. _EPD: http://www.enthought.com/products/epd.php
.. _Gobo: http://bitbucket.org/mforbes/gobo/src


EPD Components
==============
The EPD_ provides far more than required by this package: here are the
specifics.  First the required components provided by the EPD_.


**Python** (http://www.python.org/)
  Version 2.5 or higher (tested with 2.5.2).  I have not attempted to
  use version 3.0 or higher yet and won't until `numpy`_ and `scipy`_ have
  fully migrated. 

**setuptools** (http://peak.telecommunity.com/DevCenter/setuptools)
  This allows you to `easy_install` lots of python goodies, and is
  used by the `setup.py` installation script.  This will be installed
  automatically if you do not have it.

**NumPy** (http://numpy.scipy.org/)
  For optimal performance, this should be built with
  optimized BLAS and LAPACK libraries.  I have had some problems with
  this on 64 bit platforms though using `ATLAS`_ in the past, although
  the Enthought distribution seems to work now.

.. _numpy: http://numpy.scipy.org/
.. _ATLAS: http://math-atlas.sourceforge.net/

**SciPy** (http://www.scipy.org/)
  This also depends on the FFTW_ if you want good performance.

.. _scipy: http://numpy.scipy.org/
.. _FFTW: http://www.fftw.org/

**matplotlib** (http://matplotlib.sourceforge.net/)
  This has a few other requirements, including the zlib_ and
  freetype_ libraries.  You will also need to have some sort of GUI
  toolkit installed such as wxPython_, GTK_ etc.  Note that Python
  comes with its own TkInter_ GUI toolkit, so this interface should be
  provided across all platforms.

.. _zlib: http://www.zlib.net/
.. _freetype: http://www.freetype.org/
.. _wxPython: http://www.wxpython.org
.. _GTK: http://www.gtk.org
.. _TkInter: http://wiki.python.org/moin/TkInter

**PyTables** (http://www.pytables.org/)
  This is required by :mod:`mmf.archive.Archive` to efficiently store
  large arrays of data.  It is only required if the `datafile` option
  is specified along with the `pytables` option.  This is
  easy-installable after installing the hdf5_ library but may require
  an up to date version of PyRex_ (which is also easy-installable).

.. _hdf5: http://www.hdfgroup.org/HDF5/
.. _PyRex: http://www.cosc.canterbury.ac.nz/greg.ewing/python/Pyrex/

**nose** (http://somethingaboutorange.com/mrl/projects/nose/)
  This is a testing framework.  Not strictly required, but
  to run my unit tests you need this.  SciPy and NumPy are switching
  to this, so it should be easy to get and install.

Other Components
================
The following requirements are not met by the EPD_.  You will need to
install these in addition to get the full functionality.

**Parallel Python** (http://www.parallelpython.com/)
  Provides a way of controlling many processes.  Used in
  ``mmf.async.pp_mmf``.

**pexpect** (http://www.noah.org/wiki/Pexpect)
  Provides a nice interface for controlling other processes.  Used in
  ``mmf.async.pp_mmf``.

**winpdb** (http://winpdb.org/)
  This is a GUI and pdb replacement that allows for remote debugging.
  I use it in :mod:`mmf.async.remote_debug`.  Importing :mod:`mmf`
  will insert a signal handler that will start the debugging server so
  that ``winpdb`` can be used to debug the process.  See
  :mod:`mmf.async.remote_debug` for more details.

**pygsl** (http://pygsl.sourceforge.net/)
  Sometimes I use the Python wrappers for the GNU
  Scientific Library (GSL_).  This has some additional useful
  functionality, esp. some special functions and series summation
  functions.  I use this for doing lattice sums for implementing the
  DFT in a box.

.. _GSL: http://www.gnu.org/software/gsl/

**bvp** (http://pav.iki.fi/software/bvp/index.html)
  The module :mod:`mmf.math.ode.deq` uses Pauli Virtanen' wrapper for 
  the COLNEW_ boundary value problem solver by U. Ascher and G. Bader.

.. _COLNEW: http://www.netlib.org/ode/colnew.f

**cvxopt** (http://abel.ee.ucla.edu/cvxopt/)
  This provides optimizers for convex optimization.  I don't use this much, but
  was playing with it in :mod:`mmf.math.integrate.integrate_1d.quadrature`.

**scikits.delaunay** (http://scikits.appspot.com/delaunay)
  This is required for the multidimensional tabulation algorithm in
  :mod:`mmf.math.interp`::

     svn checkout http://svn.scipy.org/svn/scikits/trunk/delaunay

There are some routines in this package written in C++ or Fortran, so
you may need to run the files :file:`setup.py` with the ``build`` or
``build_ext`` options and link the resulting library to the same
directory that :file:`setup.py` was in, for example::

    $ cd /python/mmf/math/integrate
    $ python setup.py build_ext
    <output suppressed>
    $ ln -s build/lib.macosx-10.3-i386-2.5/_dcuhre.so .

**Sphinx** (http://sphinx.pocoo.org/, http://bitbucket.org/birkenfeld/sphinx/)
  This documentation is built using the Sphinx documentation
  generation system.  Some features of the present documentation
  require using the modified version I distribute here:

  http://bitbucket.org/mforbes/sphinx-mmf/

  A few extensions require additional packages, including the
  following:

  **GraphVis** (http://graphviz.org/)
    For building inheritance diagrams and a few other graphs
  
  **LaTeX**
    For typesetting math using the ``pngmath`` extension.  This can
    also benefit from the preview-latex package:

      http://www.gnu.org/software/auctex/preview-latex.html

  **numpydoc**
    This can be installed from the numpy source tree as a separate
    package::

      $ svn checkout http://svn.scipy.org/svn/numpy/trunk/doc/sphinxext numpydoc
      $ cd numpydoc
      $ python setup.py install

============
 Installing
============
Right now I recommend installing this bye issuing::
  
  python setup.py develop

in the top level directory (containing the ``setup.py`` file).
You should also be able to install this package by running::

  python setup.py build
  python setup.py install

but I have not tested this yet.  (In particular, some of the
components such as ``contrib`` in the top level directory will
probably not get installed.)