/[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 565 by gross, Mon Feb 27 00:04:17 2006 UTC revision 1567 by ksteube, Thu May 22 22:52:41 2008 UTC
# Line 1  Line 1 
1  % $Id:$  %
2    % $Id$
3    %
4    %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
5    %
6    %           Copyright 2003-2007 by ACceSS MNRF
7    %       Copyright 2007 by University of Queensland
8    %
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.
21    
22    \section{Software Needed for Installation}
23    
24    \begin{itemize}
25       \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/})
27       \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 (see \url{http://www.boost.org/})
29       \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/}).
31    \end{itemize}
32    
33    \subsection{Optional Libraries}
34    These libraries are optional at compile time. By default, thay are switched off.
35    \begin{itemize}
36       \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 which is included with the Intel compilers (see \url{http://www.intel.com/cd/software/products/asmo-na/eng/perflib/mkl/}).
38    \end{itemize}
39    
40  \section{Getting The Software}  \subsection{Optional Software}
41    
 The \escript package contains some submodules:  
42  \begin{itemize}  \begin{itemize}
43  \item \escript : model development environment     \item visualization with our pyvisi interface to VTK:
44  \item \finley : PDE solver library (finite elements)        \item vtk  4.2.1 or newer with with python interface (see \url{http://public.kitware.com/VTK/}).
45  \item \bruce : grid data domain     \item Alternatives for off-line visualization:
46  \item \modelframe : model description environment        \begin{itemize}
47  \item \pyvisi : visualization environment        \item mayavi (see \url{http://mayavi.sourceforge.net/}).
48          \item opendx (see \url{http://www.opendx.org/}).
49          \end{itemize}
50       \item Alternatives for on-line visualization:
51    \begin{itemize}
52          \item gnuplot  with with python interface (see \url{http://www.gnuplot.info/}).
53          \item  povray (see \url{http://www.povray.org/}).
54    \end{itemize}
55  \end{itemize}  \end{itemize}
56    
57  \section{Requirements}  \section{Get the Source Code}
58    
59    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.
61    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}
64    Use the commands
65    
66    \begin{verbatim}
67      mkdir <my esys dir>
68      mv escript*.zip <my esys dir>
69      cd <my esys dir>
70      unzip escript*.zip
71    \end{verbatim}
72    
73    to unzip the source files into the directory  \verb|<my esys dir>|.
74    
75    \subsection{Unpack tar File}
76      
77    Use the commands
78    
79    \begin{verbatim}
80      mkdir <my esys dir>
81      mv escript*.tar.gz <my esys dir>
82      cd <my esys dir>
83      tar xzf escript*.tar.gz
84    \end{verbatim}
85    
86    to unpack the source files into the directory \verb|<my esys dir>|.
87    
88  \section{Installation}  \section{Installation}
89  \section{Testing}  
90    The installation is started by
91    \begin{verbatim}
92      cd <my esys dir>
93      scons dodebug=no
94    \end{verbatim}
95    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}
97      cd <my esys dir>
98      scons dodebug=no options_file=myoptions.py
99    \end{verbatim}
100    You can also over-ride individual settings through the command line:
101    \begin{verbatim}
102       cd <my esys dir>
103      scons dodebug=no libinstall=/usr/lib
104    \end{verbatim}
105    This will install the libraries into the directory \verb|/usr/lib|.
106    
107    Help on options is available with:
108    \begin{verbatim}
109      cd <my esys dir>
110      scons -h
111    \end{verbatim}
112    To uninstall the software use
113    \begin{verbatim}
114      cd <my esys dir>
115      scons -c
116    \end{verbatim}
117    
118    If you have more than one processor available for compilation you can use the -j option to tell scons to do parallel compiles:
119    \begin{verbatim}
120       cd <my esys dir>
121       scons dodebug=no -j 8
122    \end{verbatim}
123    \section{Running Release Tests}
124    You can run the test suite of approximately 30,000 unit tests in a few hours with
125    \begin{verbatim}
126       cd <my esys dir>
127       scons dodebug=no all_tests
128    \end{verbatim}
129    
130    \section{Environment Setup}
131    To make esys accessible from python you have to set
132    \begin{verbatim}
133    export PYTHONPATH=<my esys dir>:${PYTHONPATH}
134    export LD_LIBRARY_PATH=<my esys dir>/lib:${LD_LIBRARY_PATH}
135    \end{verbatim}
136    
137    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}
148    cd <my esys dir>/doc/examples
149    python poisson.py
150    \end{verbatim}
151    
152    \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):
155    \begin{verbatim}
156    export OMP_NUM_THREADS=4
157    cd <my esys dir>/doc/examples
158    python poisson.py
159    \end{verbatim}
160    
161    \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}
173    Please direct any questions you might have to \url{mailto:esys@esscc.uq.edu.au}.

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

  ViewVC Help
Powered by ViewVC 1.1.26