% Installation instructions.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\chapter{Installation instructions}


% Dependencies.
%~~~~~~~~~~~~~~

\section{Dependencies}

The following packages need to be installed before using relax:
\begin{description}
  \item[\href{http://python.org/}{Python}\index{Python}:]  Version 2.5 or higher.
  \item[\href{http://numpy.scipy.org/}{NumPy}\index{NumPy}:]  Version 1.6 or higher.
    This package is used for most of the numerical calculations within relax.
  \item[\href{http://www.scipy.org/}{SciPy}\index{SciPy}:]  Version 0.7.1 or higher.
    This package is optional.
    It is required only for the frame order theory analyses.
  \item[\href{http://wxpython.org/}{wxPython}\index{wxPython}:]  Version 2.8 or higher.
    This package is also optional.
    It is required for the operation of the graphical user interface (GUI)\index{User interface!GUI}.
  \item[\href{http://mpi4py.scipy.org/}{mpi4py}\index{MPI!mpi4py}:]  Version 1.2 or higher.
    This optional dependency is essential for running relax in MPI multi-processor mode.
\end{description}

Older versions of these packages may work, use them at your own risk.
If, for older dependency versions, errors do occur please submit a bug report to the bug tracker\index{bug!tracker} at \href{https://gna.org/bugs/?group=relax}{https://gna.org/bugs/?group=relax}.
That way a solution may be created for the next relax release.

Note that only the official Python distribution from \href{http://python.org}{http://python.org} is supported.
If you use the Enthought Python Distribution (EPD) or other non-official distributions you may encounter problems with the relax C modules, the graphical user interface, or other issues.
These alternative distributions are to be used at your own risk.
Any issues encountered will not be considered as relax bugs.


% Installation.
%~~~~~~~~~~~~~~

\section{Installation}
\index{installation|textbf}


% The precompiled verses source distribution.
\subsection{The source releases}
\label{sect: source releases}

Two types of software packages are available for download -- the precompiled and source distribution.
Currently only relaxation curve-fitting requires compilation to function and all other features of relax will be fully functional without compilation.
If relaxation curve-fitting is required but no precompiled version of relax exists for your operating system or architecture then, if a C compiler is present, the C code can be compiled into the shared objects files \file{*.so}, \file{*.pyd} or \file{*.dylib} which are loaded as modules into relax\index{C module compilation}.
To build these modules the Scons\index{SCons|textbf} system from \href{http://scons.org/}{http://scons.org/} is required.
This software requires the Python and numpy header files installed.
Once Scons is installed type

\example{\$ scons}
\index{SCons|textbf}

in the base directory where relax has been installed and the C modules should, hopefully, compile without any problems.
Otherwise please submit a bug report to the bug tracker\index{bug!tracker} at \href{https://gna.org/bugs/?group=relax}{https://gna.org/bugs/?group=relax}.



% Installation on GNU/Linux.
\subsection{Installation on GNU/Linux}
\index{Operating system!GNU/Linux|textbf}

To install the program relax on a GNU/Linux system download either the precompiled distribution\index{distribution archive} labelled \file{relax-x.x.x.GNU-Linux.\textit{arch}.tar.bz2} matching your machine architecture or the source distribution \file{relax-x.x.x.src.tar.bz2}.
A number of installation methods are possible.
The simplest way is to switch to the user ``root'', unpack and decompress the archive within the \directory{\ossep{}usr\ossep{}local} directory by typing, for instance

\example{\$ tar jxvf relax-x.x.x.GNU-Linux.i686.tar.bz2}
\index{tar}

then create a symbolic link in \directory{\ossep{}usr\ossep{}local\ossep{}bin} by moving to that directory and typing

\example{\$ ln -s ../relax/relax .}
\index{symbolic link}

and finally possibly creating the byte-compiled Python \file{*.pyc} files to speed up the start time of relax by typing

\example{\$ python -m compileall .}

in the relax base directory.
Alternatively if the Scons system is installed, by typing as the root user

\example{\$ scons install}
\index{SCons!install|textbf}

in the relax base directory, a directory in \directory{\ossep{}usr\ossep{}local\ossep{}} called \file{relax} will be created, all the uncompressed and untarred files will be copied into this directory, a symbolic link in \directory{\ossep{}usr\ossep{}local\ossep{}bin} to the file \directory{\ossep{}usr\ossep{}local\ossep{}relax\ossep{}relax} will be created, and then finally the Python \file{*.pyc} files will be byte-compiled.
To change the installation path to a non-standard location the Scons script \file{sconstruct} in the base relax directory should be modified by changing the variable \prompt{INSTALL\osus{}PATH} to point to the desired location.



% Installation on MS Windows.
\subsection{Installation on MS Windows}
\index{Operating system!MS Windows|textbf}

In addition to the above dependencies, running relax on MS Windows requires a number of additional programs.
These include:
\begin{description}
  \item[\href{https://pypi.python.org/pypi/pyreadline}{pyreadline}\index{pyreadline}:]  Any version.
  \item[\href{http://starship.python.net/crew/theller/ctypes/}{ctypes}\index{ctypes}:]  The pyreadline package requires ctypes.
\end{description}

To install, simply download the pre-compiled binary distribution \file{relax-x.x.x.Win32.zip} or the source distribution \file{relax-x.x.x.src.zip} and extract the files to \directory{C:$\backslash$Program Files$\backslash$relax-x.x.x}.
Then add this directory to the system environment path (in Windows XP, right click on \gui{My Computer}, go to \gui{Properties}, click on the \gui{Advanced} tab, and click on the \guibutton{Environment Variables} button.
Then double click on the \gui{Path} system variable and add the text \guistring{;C:$\backslash$Program Files$\backslash$relax-x.x.x} to the end of variable value field.
The Python installation must also be located on the path (add the text \guistring{;C:$\backslash$Python27}, changing the text to point to the correct directory, to the field).
To run the program from any directory inside the Windows command prompt (or dos prompt) type:

\example{C:$\backslash$> relax}


Note that the pre-compiled binary distribution was built using a specific Python version and that that version may need to be installed for the modules to be loaded.
More details are given on the \href{http://www.nmr-relax.com/download.html}{download} webpage.


% Installation on Mac OS X.
\subsection{Installation on Mac OS X}
\index{Operating system!Mac OS X|textbf}

There are three ways of installing relax on a Mac.
These are described at \href{http://www.nmr-relax.com/download.html}{http://www.nmr-relax.com/download.html} and are the pre-compiled relax application, the Fink or the source releases.

\subsubsection{The relax application}

The stand-alone relax application requires none of the dependencies listed above to be installed.
It is a universal binary compiled for the i386, x86-64 and PPC CPU architectures (fat3) using the Mac OS X 10.5 framework.
It should therefore run on Leopard, Snow Leopard, and Lion.
This very large bundle does not require system administrator access to run.

\subsubsection{Fink}

Certain relax versions are available for Mac OS X within the Fink project.
These can be installed for Python 2.7 with the command:

\example{> fink install relax-py27}

The relax releases packaged within Fink can been browsed at \href{http://pdb.finkproject.org/pdb/browse.php?name=relax}{http://pdb.finkproject.org/pdb/browse.php?name=relax}.
If the desired version is not available, please download the relevant source package below or contact the fink project using the ``Maintainer'' email address given in the relax fink pages.

Note that when installing via fink, all the dependencies will be automatically selected and installed as well.
Although automatic, when starting from scratch that there could be well over 250 source packages that need to be compiled (to set up the full GNU compilation chain and other libraries which are then required to build Python, numpy, scipy, etc.).
This may take anywhere between 2 days to over a week (don't forget to mention this fact to your poor sys-admin).

The fink relax packages for different Python versions are \href{http://pdb.finkproject.org/pdb/package.php/relax-py27}{relax-py27}, \href{http://pdb.finkproject.org/pdb/package.php/relax-py26}{relax-py26}, \href{http://pdb.finkproject.org/pdb/package.php/relax-py25}{relax-py25} and \href{http://pdb.finkproject.org/pdb/package.php/relax-py24}{relax-py24}.

\subsubsection{Source release}

See Section~\ref{sect: source releases} on page~\pageref{sect: source releases}.


% Installation on your OS.
\subsection{Installation on your OS}

For all others systems, please use the source distribution files and the Scons software to build the C modules.



% Running a non-compiled version.
\subsection{Running a non-compiled version}

Compilation of the C code is not essential for running relax, however certain features of the program will be disabled.
Currently only the exponential curve-fitting for determining the $\Rone$ and $\Rtwo$ relaxation rates requires compilation.
To run relax without compilation install the dependencies detailed above, download the source distribution which should be named \file{relax-x.x.x.src.tar.bz2}, extract the files, and then run the file called \file{relax} in the base directory.



% Optional programs.
%~~~~~~~~~~~~~~~~~~~

\section{Optional programs}

The following is a list of programs which can be used by relax although they are not essential for normal use.


% Grace.
\subsection{Grace}
\index{software!Grace|textbf}

Grace is a program for plotting two dimensional data sets in a professional looking manner.
It is used to visualise parameter values.
It can be downloaded from \href{http://plasma-gate.weizmann.ac.il/Grace/}{http://plasma-gate.weizmann.ac.il/Grace/}.


% OpenDX.
\subsection{OpenDX}
\index{software!OpenDX|textbf}

Version 4.1.3 or compatible.
OpenDX is used for viewing the output of the space mapping function and is executed by passing the command \prompt{dx} to the command line with various options.
The program is designed for visualising multidimensional data and can be found at \href{http://www.opendx.org/}{http://www.opendx.org/}.


% Molmol.
\subsection{Molmol}
\index{software!MOLMOL|textbf}

Molmol is used for viewing the PDB structures loaded into the program and to display parameter values mapped onto the structure.


% PyMOL.
\subsection{PyMOL}
\index{software!PyMOL|textbf}

PDB structures can also be viewed using PyMOL.
This program can also be used to display geometric objects generated by relax for representing physical concepts such as the diffusion tensor and certain cone diffusion models.


% Dasha.
\subsection{Dasha}
\index{software!Dasha|textbf}

Dasha is a program used for model-free analysis of NMR relaxation data.
It can be used as an optimisation engine to replace the minimisation algorithms implemented within relax.


% Modelfree4.
\subsection{Modelfree4}
\index{software!Modelfree|textbf}

Art Palmer's Modelfree4 program is also designed for model-free analysis and can be used as an optimisation engine to replace relax's high precision minimisation algorithms.
