================
Getting the Code
================

.. _installation:

Installation
============

.. warning:: At the present time, binary packages are not supplied.  The success of the
   :ref:`installation script <installation_script>` has largely removed the need
   for binaries.

YT comes with a handy installation script.  This script will download and
install all the necessary dependencies -- from Python to YT -- and then provide
you with some information about how to modify your environment variables to
ensure it is loaded properly.

To get a copy of the YT install script for Linux and Unix machines, you can
obtain it from the subversion repository.

.. code-block:: bash

   $ svn export http://svn.enzotools.org/yt/branches/yt-1.5/doc/install_script.sh

If you're running on Mac OSX, there is a different install script to run.

.. code-block:: bash

   $ svn export http://svn.enzotools.org/yt/branches/yt-1.5/doc/install_script_osx.sh

Typically these scripts can just be run directly, but inside there are several
options.  Specifically, they can optionally install wxPython for GUI support,
ZLIB (typically a good idea on 64-bit systems) and Mercurial (a great idea if
you use `the barn <http://barn.enzotools.org>`_!)  These options are all
explained in :ref:`installation_script`.

.. _installation_script:

Using the Installation Script
-----------------------------

.. note:: The installation script is now the preferred means of installing a
   full set of packages -- but if you are comfortable with python, feel free to
   install the code yourself!

In the ``doc/`` directory in the yt source distribution, there is a script,
``install_script.sh``, designed to set up a full installation of yt, along with
all the necessary dependencies.  You can run this script from within a checkout
of yt or an expanded tarball.  If you are running on Mac OSX, you should run
``install_script_osx.sh`` instead.

.. note:: For convenience, yt will be installed in 'develop' mode, which means
   any changes in the source directory will be included the next time you
   import yt!

There are several variabels you can set inside this script.

   ``DEST_DIR``
     This is the location to which all source code will be downloaded and
     resulting built libraries installed.
   ``HDF5_DIR``
     If you wish to link against existing HDF5 (*shared*) libraries, put the
     root path to the installation here.  Statically linked libraries will not
     work.
   ``INST_WXPYTHON``
     This is a boolean, set to 0 or 1, that governs whether or not wxPython
     should be installed.
   ``INST_ZLIB``
     This is a boolean, set to 0 or 1, that governs whether or not zlib
     should be installed.
   ``INST_HG``
     This is a boolean, set to 0 or 1, that governs whether or not mercurial
     should be installed.  This is useful if you want to use scripts from
     `the barn <http://barn.enzotools.org/>`_.
   ``YT_DIR``
     If you've got a source checkout of YT somewhere else, point to it with
     this!

.. warning:: If you run into problems, particularly anything involving
   ``-fPIC``, it is likely that there's a problem with static libraries.
   Try asking the installer script to install HDF5 and ZLIB.

Notes on Common Installation Locations
======================================

Ranger (TACC)
-------------

YT installs out of the box on Ranger using the installation script.  Zlib must
be built by the script.  The ``pgi`` module must first be swapped out for the
``gcc/4.3.2`` module.  This set of commands has been reported to work for this
purpose:

.. code-block:: bash

   $ module unload mvapich-devel
   $ module swap pgi gcc
   $ module load mvapich-devel

Furthermore, errors citing ``GLIBC`` following logging out and logging back in
can usually be solved by swapping out ``gcc`` for ``pgi`` again.

Kraken (NICS)
-------------

YT installs out of the box on Kraken using the installation script.  Zlib must 
be built by the script.  Before you begin, you must also ensure that the GNU
programming environment is being used:

.. code-block:: bash

   $ module swap PrgEnv-pgi PrgEnv-gnu

If you are going to try to run ``yt`` on the compute nodes, be aware that --
while it does work -- it will take a bit of effort because the compute nodes
run Compute Node Linux.  As a result, all the libraries have to be compiled
statically -- including all of Python and ``yt``!

Stephen Skory has written a guide to getting Python compiled and running on the
compute nodes `on the wiki <http://yt.enzotools.org/wiki/CrayXT5Installation>`_.

Verne (NICS)
------------

YT installs out of the box on Verne using the installation script.  Zlib must 
be built by the script.  Before you begin, you must also ensure that the GNU
programming environment is being used:

.. code-block:: bash

   $ module swap PE-pgi PE-gnu

Orange (SLAC)
-------------

YT installs out of the box if you either have the KIPAC ``gfortran``
installation in your path or use the ``NUMPY_ARGS="--fcompiler=fake"`` option
as in the script.

Red (SLAC)
----------

YT installs out of the box if you use the ``NUMPY_ARGS="--fcompiler=fake"``
option as in the script.

Cobalt (NCSA)
-------------

YT installs out of the box on Cobalt using the installation script.  However,
Zlib and HDF5 must both be installed via the installation script or linking
errors will ensue.  The GCC module, as opposed to the Intel Compiler module,
should be loaded, but this may not be a hard requirement.

OS X
----

OS X installation can be tricky.  It is best to use the
``install_script_osx.sh`` file, which will download fresh Python packages along
with all dependencies.  The `Enthought Python Distribution
<http://www.enthought.com/products/epd.php>`_ is also a means of obtaining all
these dependencies; if you use EPD, you will have to set up the file
``hdf5.cfg`` to point to the correct HDF5 installation from EPD.  Users have
reported some degree of success.  Future versions of YT will leverage packages
included in the EPD.

Installing by Hand
==================

If you've ever installed a python package by hand before, YT should be easy to
install.  You will need to install the prequisites first.  A driving factor in
the development of yt over the months leading to release 1.5 has been the
reduction of dependencies.  To that extent, only a few packages are required
for the base usage, and a GUI toolkit if you are going to use the graphical
user interface, Reason.

 * `Python <http://python.org/>`_, at least version 2.4, but preferably 2.5 or
   2.6.
 * `HDF5 <http://www.hdfgroup.org/>`_, the data storage backend used by Enzo
   and yt (if you can run Enzo, this is already installed!)
 * `NumPy <http://numpy.scipy.org/>`_, the fast numerical backend for Python
 * `MatPlotLib <http://matplotlib.sf.net/>`_, the plotting package
 * `wxPython <http://www.wxpython.org/>`_, the GUI toolkit (optional)

(If you are only interested in manipulating data without any graphical plotting
or interfaces, you only need to install HDF5, NumPy, and Python!)

Instructions for installing these packages is, unfortunately, beyond the scope
of this document.  However, there are copious directions on how to do so
elsewhere.  You may also consider installing the
`Enthought Python Distribution <http://www.enthought.com/products/epd.php>`_,
which includes all of the necessary packages.

You'll need to create a file in the YT directory called ``hdf5.cfg`` which
points at the base of your HDF5 installation tree -- usually this will be
something like ``/usr/local/``.  Underneath this directory YT will look for
``include`` and ``lib`` directories containing the HDF5 files.

Once these dependencies have been met, YT can be installed in the standard
manner:

.. code-block:: bash

   $ cd yt/
   $ python2.6 setup.py install --prefix=/some/where/

Starting up YT
==============

'Starting up YT' is a bit of a misnomer -- there are many entry points to data
analysis with YT.  The simplest possible way to access YT is with the
:ref:`command-line-tool`.  You can try this out just by typing

.. code-block:: bash

   $ yt

and following the help instructions!
