/[escript]/trunk/doc/user/Installation.tex
ViewVC logotype

Diff of /trunk/doc/user/Installation.tex

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1940 by ksteube, Thu Oct 2 06:51:48 2008 UTC revision 1941 by ksteube, Tue Oct 28 07:51:49 2008 UTC
# Line 15  Line 15 
15  \chapter{Installation}  \chapter{Installation}
16  \label{INSTALL}  \label{INSTALL}
17    
18  Visit \url{http://iservo.edu.au/twiki/bin/view/ESSCC/EsysUser} for more information.  We offer binary distributions for some systems and source code distributions for others.
19    The binary distributions include Escript/Finley itself and all required packages.
20    The required third-party software packages are included in compliance with their copyrights.
21    
22  \section{Software Needed for Installation}  Complete information is available at
23    \url{https://shake200.esscc.uq.edu.au/twiki/bin/view/ESSCC/EsysInstallationGuide}.
24    
 \begin{itemize}  
    \item scons  0.96.91 or newer (see \url{http://www.scons.org/})  
    \item python  2.3.4 or higher (see \url{http://www.python.org/})  
    \item numarray  0.9 or higher (see \url{http://www.stsci.edu/resources/software_hardware/numarray})  
    \item python boost boost  1.31.0 or higher (see \url{http://www.boost.org/})  
    \item g++ (see \url{http://gcc.gnu.org/}) or Intel c++  compiler (see \\  
 \url{http://www.intel.com/cd/software/products/asmo-na/eng/compilers/}).  
 \end{itemize}  
   
 \subsection{Optional Libraries}  
 These libraries are optional at compile time. By default, they are switched off.  
 \begin{itemize}  
    \item parallel direct solver from the SGI SCSL library (see \url{http://www.sgi.com/products/software/scsl.html})  
    \item parallel direct solver from Intel MKL library which is included with the Intel compilers (see \url{http://www.intel.com/cd/software/products/asmo-na/eng/perflib/mkl/}).  
 \end{itemize}  
   
 \subsection{Optional Software}  
   
 \begin{itemize}  
    \item visualization with our pyvisi interface to VTK:  
       \item vtk  4.2.1 or newer with with python interface (see \url{http://public.kitware.com/VTK/}).  
    \item Alternatives for off-line visualization:  
       \begin{itemize}  
       \item mayavi (see \url{http://mayavi.sourceforge.net/}).  
       \item opendx (see \url{http://www.opendx.org/}).  
       \end{itemize}  
    \item Alternatives for on-line visualization:  
 \begin{itemize}  
       \item gnuplot  with with python interface (see \url{http://www.gnuplot.info/}).  
       \item  povray (see \url{http://www.povray.org/}).  
 \end{itemize}  
 \end{itemize}  
   
 \section{Get the Source Code}  
   
 You can download the complete source code, examples and release tests from \url{https://shake200.esscc.uq.edu.au/twiki/bin/view/ESSCC/EsysUser}.  
 Files can be downloaded as *.zip or *.tar.gz files.  
 This software is distributed under the Open Software License version 3.0 (see \url{http://www.opensource.org/licenses/osl-3.0.php}).  
   
 \subsection{Unpack zip File}  
 Use the commands  
   
 \begin{verbatim}  
   mkdir <my esys dir>  
   mv escript*.zip <my esys dir>  
   cd <my esys dir>  
   unzip escript*.zip  
 \end{verbatim}  
   
 to unzip the source files into the directory  \verb|<my esys dir>|.  
   
 \subsection{Unpack tar File}  
     
 Use the commands  
   
 \begin{verbatim}  
   mkdir <my esys dir>  
   mv escript*.tar.gz <my esys dir>  
   cd <my esys dir>  
   tar xzf escript*.tar.gz  
 \end{verbatim}  
   
 to unpack the source files into the directory \verb|<my esys dir>|.  
   
 \section{Installation}  
   
 The installation is started by  
 \begin{verbatim}  
   cd <my esys dir>  
   scons usedebug=no  
 \end{verbatim}  
 By default the configuration for Linux is used. If there is a file \verb|scons/<hostname>_options.py| it will contain values to over-ride the default settings. Use =scons/ess_options.py= as a staring point to create a file for your machine. If you want to use personalized settings in a file called =myoptions.py= you can run  
 \begin{verbatim}  
   cd <my esys dir>  
   scons usedebug=no options_file=myoptions.py  
 \end{verbatim}  
 You can also over-ride individual settings through the command line:  
 \begin{verbatim}  
    cd <my esys dir>  
   scons usedebug=no libinstall=/usr/lib  
 \end{verbatim}  
 This will install the libraries into the directory \verb|/usr/lib|.  
   
 Help on options is available with:  
 \begin{verbatim}  
   cd <my esys dir>  
   scons -h  
 \end{verbatim}  
 To uninstall the software use  
 \begin{verbatim}  
   cd <my esys dir>  
   scons -c  
 \end{verbatim}  
   
 If you have more than one processor available for compilation you can use the -j option to tell scons to do parallel compiles:  
 \begin{verbatim}  
    cd <my esys dir>  
    scons usedebug=no -j 8  
 \end{verbatim}  
 \section{Running Release Tests}  
 You can run the test suite of approximately 30,000 unit tests in a few hours with  
 \begin{verbatim}  
    cd <my esys dir>  
    scons usedebug=no all_tests  
 \end{verbatim}  
   
 \section{Environment Setup}  
 To make esys accessible from python you have to set  
 \begin{verbatim}  
 export PYTHONPATH=<my esys dir>:${PYTHONPATH}  
 export LD_LIBRARY_PATH=<my esys dir>/lib:${LD_LIBRARY_PATH}  
 \end{verbatim}  
   
 If you build \esys with  
 \begin{verbatim}  
    cd <my esys dir>  
    scons usedebug=no prefix=/usr  
 \end{verbatim}  
 then your libraries and python modules will be installed in system directories and you will  
 not have to set LD_LIBRARY_PATH and PYTHONPATH (assuming python is installed in  
 /usr/lib/python/site-modules).  
   
 Now you are ready to test your setup by running one of the supplied examples  
 \begin{verbatim}  
 cd <my esys dir>/doc/examples  
 python poisson.py  
 \end{verbatim}  
   
 \subsection{OpenMP Support}  
   
 If your system and compiler support OpenMP parallelization and OpenMP parallelization has been switched on during compilation you need to set the following environment variable to run scripts in parallel (in this case with four threads):  
 \begin{verbatim}  
 export OMP_NUM_THREADS=4  
 cd <my esys dir>/doc/examples  
 python poisson.py  
 \end{verbatim}  
   
 \subsection{MPI Support}  
   
 If you wish to use MPI parallelization, and it has been switched on during compilation with usempi=yes, you need to use the following commands to run scripts in parallel (in this case with four CPUs):  
 \begin{verbatim}  
 cd <my esys dir>/doc/examples  
 mpirun -np 4 <my esys dir>/lib/pythonMPI poisson.py  
 \end{verbatim}  
   
 When running an MPI job the standard output of process zero goes to the screen, while the standard output of the other processes  
 is automatically redirected to files with names like stdout_cpu_0001.out.  
   
 A python script can obtain the MPI rank and size in two ways.  
 The global number of MPI processes and rank (relative to MPI_COMM_WORLD) are available through  
 \begin{verbatim}  
 iam = getMPIRankWorld()  
 nPE = getMPISizeWorld()  
 \end{verbatim}  
   
 The rank and size relative to a particular domain object (which may be limited to run on a subset of the  
 total list of MPI processes in future versions of Escript) are available through  
 \begin{verbatim}  
 iam = domain.getMPIRank()  
 nPE = domain.getMPISize()  
 \end{verbatim}  
   
 \section{Getting Help}  
25  Please direct any questions you might have to \url{mailto:esys@esscc.uq.edu.au}.  Please direct any questions you might have to \url{mailto:esys@esscc.uq.edu.au}.
26    

Legend:
Removed from v.1940  
changed lines
  Added in v.1941

  ViewVC Help
Powered by ViewVC 1.1.26