/[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 737 by ksteube, Wed Jun 14 04:00:41 2006 UTC revision 1567 by ksteube, Thu May 22 22:52:41 2008 UTC
# Line 1  Line 1 
1    %
2  % $Id$  % $Id$
3  %  %
4  %           Copyright © 2006 by ACcESS MNRF  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
5  %               \url{http://www.access.edu.au  %
6  %         Primary Business: Queensland, Australia.  %           Copyright 2003-2007 by ACceSS MNRF
7  %   Licensed under the Open Software License version 3.0  %       Copyright 2007 by University of Queensland
8  %      http://www.opensource.org/licenses/osl-3.0.php  %
9    %                http://esscc.uq.edu.au
10    %        Primary Business: Queensland, Australia
11    %  Licensed under the Open Software License version 3.0
12    %     http://www.opensource.org/licenses/osl-3.0.php
13  %  %
14    %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
15    %
16    
17  \chapter{Installation}  \chapter{Installation}
18  \label{INSTALL}  \label{INSTALL}
19    
20  Visit \url{http://iservo.edu.au/twiki/bin/view/ESSCC/EsysUser} for more information.  Visit \url{http://iservo.edu.au/twiki/bin/view/ESSCC/EsysUser} for more information.
21    
22  \section{Software needed for installation}  \section{Software Needed for Installation}
23    
24  \begin{itemize}  \begin{itemize}
25     \item scons  0.96.91 or newer, see \url{http://www.scons.org/}     \item scons  0.96.91 or newer (see \url{http://www.scons.org/})
26     \item python  2.3.4 or higher, see \url{http://www.python.org/}     \item python  2.3.4 or higher (see \url{http://www.python.org/})
27     \item numarray  0.9 or higher, see \url{http://www.stsci.edu/resources/software_hardware/numarray}     \item numarray  0.9 or higher (see \url{http://www.stsci.edu/resources/software_hardware/numarray})
28     \item python boost boost  1.31.0 or higher (build system defaults to boost 1.33.0), see \url{http://www.boost.org/}     \item python boost boost  1.31.0 or higher (see \url{http://www.boost.org/})
29     \item g++, see \url{http://gcc.gnu.org/}, or intel c++  compiler, see \\     \item g++ (see \url{http://gcc.gnu.org/}) or Intel c++  compiler (see \\
30  \url{http://www.intel.com/cd/software/products/asmo-na/eng/compilers/}.  \url{http://www.intel.com/cd/software/products/asmo-na/eng/compilers/}).
31  \end{itemize}  \end{itemize}
32    
33  \subsection{optional Libraries}  \subsection{Optional Libraries}
34  These libraries are optional at compile time. By default, thay are switched off.  These libraries are optional at compile time. By default, thay are switched off.
35  \begin{itemize}  \begin{itemize}
36     \item parallel direct solver from the SGI SCSL library, see \url{http://www.sgi.com/products/software/scsl.html}     \item parallel direct solver from the SGI SCSL library (see \url{http://www.sgi.com/products/software/scsl.html})
37     \item parallel direct solver from intel MKL library  (delivered with intel compilers), see \url{http://www.intel.com/cd/software/products/asmo-na/eng/perflib/mkl/}.     \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/}).
38  \end{itemize}  \end{itemize}
39    
40  \subsection{optional Software}  \subsection{Optional Software}
41    
42  \begin{itemize}  \begin{itemize}
43     \item off-line visualization:     \item visualization with our pyvisi interface to VTK:
44          \item vtk  4.2.1 or newer with with python interface (see \url{http://public.kitware.com/VTK/}).
45       \item Alternatives for off-line visualization:
46        \begin{itemize}        \begin{itemize}
47        \item mayavi, see \url{http://mayavi.sourceforge.net/}.        \item mayavi (see \url{http://mayavi.sourceforge.net/}).
48        \item opendx, see \url{http://www.opendx.org/}        \item opendx (see \url{http://www.opendx.org/}).
49        \end{itemize}        \end{itemize}
50     \item on-line visualization with pyvisi:     \item Alternatives for on-line visualization:
51  \begin{itemize}  \begin{itemize}
52        \item vtk  4.2.1 or newer with with python interface, see \url{http://public.kitware.com/VTK/}        \item gnuplot  with with python interface (see \url{http://www.gnuplot.info/}).
53        \item gnuplot  with with python interface, see \url{http://www.gnuplot.info/}        \item  povray (see \url{http://www.povray.org/}).
       \item  povray, see \url{http://www.povray.org/}.  
54  \end{itemize}  \end{itemize}
55  \end{itemize}  \end{itemize}
56    
57  \section{Get the source code}  \section{Get the Source Code}
58    
59  You can download the source code, examples and, if required, release tests from \url{http://shake200.esscc.uq.edu.au/joomla/content/view/78//}.  You can download the complete source code, examples and release tests from \url{https://shake200.esscc.uq.edu.au/twiki/bin/view/ESSCC/EsysUser}.
60  Files can be downloaded as *.zip or *.tar.gz files.  Files can be downloaded as *.zip or *.tar.gz files.
61  Usage is under the Open Software License version 3.0, see \url{http://www.opensource.org/licenses/osl-3.0.php}.  This software is distributed under the Open Software License version 3.0 (see \url{http://www.opensource.org/licenses/osl-3.0.php}).
62    
63  \subsection{Unpack zip file}  \subsection{Unpack zip File}
64  Use the commands  Use the commands
65    
66  \begin{verbatim}  \begin{verbatim}
67     mkdir <my esys dir>    mkdir <my esys dir>
68     mv escript*.zip <my esys dir>    mv escript*.zip <my esys dir>
69    cd <my esys dir>    cd <my esys dir>
70    unzip escript*.zip    unzip escript*.zip
71  \end{verbatim}  \end{verbatim}
72    
73  to unzip the source files into the directory  \verb|<my esys dir>|.  to unzip the source files into the directory  \verb|<my esys dir>|.
74    
75  \subsection{Unpack tar file}  \subsection{Unpack tar File}
76        
77  Use the commands  Use the commands
78    
79  \begin{verbatim}  \begin{verbatim}
80    mkdir <my esys dir>    mkdir <my esys dir>
81    mv escriot*.tar.gz <my esys dir>    mv escript*.tar.gz <my esys dir>
82    cd <my esys dir>    cd <my esys dir>
83    tar xzf escript*.tar.gz    tar xzf escript*.tar.gz
84  \end{verbatim}  \end{verbatim}
# Line 83  The installation is started by Line 92  The installation is started by
92    cd <my esys dir>    cd <my esys dir>
93    scons dodebug=no    scons dodebug=no
94  \end{verbatim}  \end{verbatim}
95  By default the configuration for Linux is used. If there is a file \verb|scons/<hostname>_options.py| where is \verb|hostname| is the name of the machine the installation is running (non-literal or non-numerical charcters are replaed by underscore)  options is this file are overwrite the default setting. Use =scons/ess_options.py= as a staring point to create a file for your machine. If you want to use personalied setting in the file myoptions.py you can run  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
96  \begin{verbatim}  \begin{verbatim}
97    cd <my esys dir>    cd <my esys dir>
98    scons dodebug=no options_file=myoptions.py    scons dodebug=no options_file=myoptions.py
99  \end{verbatim}  \end{verbatim}
100  You can also over-ride individual setting through the command line. e.g.  You can also over-ride individual settings through the command line:
101  \begin{verbatim}  \begin{verbatim}
102     cd <my esys dir>     cd <my esys dir>
103    scons dodebug=no libinstall=/usr/lib    scons dodebug=no libinstall=/usr/lib
104  \end{verbatim}  \end{verbatim}
105  will install the libraries into the directory \verb|/usr/lib|.  This will install the libraries into the directory \verb|/usr/lib|.
106    
107  Get help on options with the following command  Help on options is available with:
108  \begin{verbatim}  \begin{verbatim}
109    cd <my esys dir>    cd <my esys dir>
110    scons -h    scons -h
111  \end{verbatim}  \end{verbatim}
112  To uninstall use  To uninstall the software use
113  \begin{verbatim}  \begin{verbatim}
114    cd <my esys dir>    cd <my esys dir>
115    scons -c    scons -c
# Line 112  If you have more than one processor avai Line 121  If you have more than one processor avai
121     scons dodebug=no -j 8     scons dodebug=no -j 8
122  \end{verbatim}  \end{verbatim}
123  \section{Running Release Tests}  \section{Running Release Tests}
124  To test your installation you have to download and unpack the release tests. You can run the tests by  You can run the test suite of approximately 30,000 unit tests in a few hours with
125  \begin{verbatim}  \begin{verbatim}
126     cd <my esys dir>     cd <my esys dir>
127     scons dodebug=no all_tests     scons dodebug=no all_tests
128  \end{verbatim}  \end{verbatim}
 The tests can take a while (up to several hours). In some cases it can be sufficient to run the test for the C/C++ components only. Use    
 \begin{verbatim}  
    cd <my esys dir>  
    scons dodebug=no run_tests  
 \end{verbatim}  
 to run these tests.  
 It can be usefull to run the tests in the debug mode:  
 \begin{verbatim}  
    cd <my esys dir>  
    scons dodebug=yes run_tests  
 \end{verbatim}  
 Keep in mind that this will rebuild the libraries in the debug mode. You have to rebuild the libraries with option =dodebug=no= to get back to a productive installation.  
   
129    
130  \section{Environment setup}  \section{Environment Setup}
131  To make esys accessible from python you have to set  To make esys accessible from python you have to set
132  \begin{verbatim}  \begin{verbatim}
133  export PYTHONPATH=<my esys dir>:${PYTHONPATH}  export PYTHONPATH=<my esys dir>:${PYTHONPATH}
134  export LD_LIBRARY_PATH=<my esys dir>/lib:${LD_LIBRARY_PATH}  export LD_LIBRARY_PATH=<my esys dir>/lib:${LD_LIBRARY_PATH}
135  \end{verbatim}  \end{verbatim}
 Currently an installation into the python site-packages directory is not supported.  
136    
137  If you want to check your setup and you have download the examples you can run  If you build \esys with
138    \begin{verbatim}
139       cd <my esys dir>
140       scons dodebug=no prefix=/usr
141    \end{verbatim}
142    then your libraries and python modules will be installed in system directories and you will
143    not have to set LD_LIBRARY_PATH and PYTHONPATH (assuming python is installed in
144    /usr/lib/python/site-modules).
145    
146    Now you are ready to test your setup by running one of the supplied examples
147  \begin{verbatim}  \begin{verbatim}
148  cd <my esys dir>/doc/examples  cd <my esys dir>/doc/examples
149  python poisson.py  python poisson.py
150  \end{verbatim}  \end{verbatim}
151    
152  \subsection{OpenMP support}  \subsection{OpenMP Support}
153    
154  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):  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):
155  \begin{verbatim}  \begin{verbatim}
156  export OMP_NUM_THREADS=4  export OMP_NUM_THREADS=4
157  cd <my esys dir>/doc/examples  cd <my esys dir>/doc/examples
158  python poisson.py  python poisson.py
159  \end{verbatim}  \end{verbatim}
160    
161  If you do not set OMP_NUM_THREADS you will get one thread for each processor on the system, even though you probably will not use that many processors. Be sure to always set OMP_NUM_THREADS before running the program on a system where OpenMP is enabled.  \subsection{MPI Support}
162    
163    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):
164    \begin{verbatim}
165    cd <my esys dir>/doc/examples
166    mpirun -np 4 <my esys dir>/lib/pythonMPI poisson.py
167    \end{verbatim}
168    
169    When running an MPI job the standard output of process zero goes to the screen, while the standard output of the other processes
170    is automatically redirected to files with names like stdout_cpu_0001.out.
171    
172  \section{Getting help}  \section{Getting Help}
173  If there is a problem or question please contact \url{mailto:esys@esscc.uq.edu.au}.  Please direct any questions you might have to \url{mailto:esys@esscc.uq.edu.au}.

Legend:
Removed from v.737  
changed lines
  Added in v.1567

  ViewVC Help
Powered by ViewVC 1.1.26