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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1811 - (show annotations)
Thu Sep 25 23:11:13 2008 UTC (10 years, 6 months ago) by ksteube
File MIME type: application/x-tex
File size: 6632 byte(s)
Copyright updated in all files

1
2 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3 %
4 % Copyright (c) 2003-2008 by University of Queensland
5 % Earth Systems Science Computational Center (ESSCC)
6 % http://www.uq.edu.au/esscc
7 %
8 % Primary Business: Queensland, Australia
9 % Licensed under the Open Software License version 3.0
10 % http://www.opensource.org/licenses/osl-3.0.php
11 %
12 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
13
14
15 \chapter{Installation}
16 \label{INSTALL}
17
18 Visit \url{http://iservo.edu.au/twiki/bin/view/ESSCC/EsysUser} for more information.
19
20 \section{Software Needed for Installation}
21
22 \begin{itemize}
23 \item scons 0.96.91 or newer (see \url{http://www.scons.org/})
24 \item python 2.3.4 or higher (see \url{http://www.python.org/})
25 \item numarray 0.9 or higher (see \url{http://www.stsci.edu/resources/software_hardware/numarray})
26 \item python boost boost 1.31.0 or higher (see \url{http://www.boost.org/})
27 \item g++ (see \url{http://gcc.gnu.org/}) or Intel c++ compiler (see \\
28 \url{http://www.intel.com/cd/software/products/asmo-na/eng/compilers/}).
29 \end{itemize}
30
31 \subsection{Optional Libraries}
32 These libraries are optional at compile time. By default, they are switched off.
33 \begin{itemize}
34 \item parallel direct solver from the SGI SCSL library (see \url{http://www.sgi.com/products/software/scsl.html})
35 \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/}).
36 \end{itemize}
37
38 \subsection{Optional Software}
39
40 \begin{itemize}
41 \item visualization with our pyvisi interface to VTK:
42 \item vtk 4.2.1 or newer with with python interface (see \url{http://public.kitware.com/VTK/}).
43 \item Alternatives for off-line visualization:
44 \begin{itemize}
45 \item mayavi (see \url{http://mayavi.sourceforge.net/}).
46 \item opendx (see \url{http://www.opendx.org/}).
47 \end{itemize}
48 \item Alternatives for on-line visualization:
49 \begin{itemize}
50 \item gnuplot with with python interface (see \url{http://www.gnuplot.info/}).
51 \item povray (see \url{http://www.povray.org/}).
52 \end{itemize}
53 \end{itemize}
54
55 \section{Get the Source Code}
56
57 You can download the complete source code, examples and release tests from \url{https://shake200.esscc.uq.edu.au/twiki/bin/view/ESSCC/EsysUser}.
58 Files can be downloaded as *.zip or *.tar.gz files.
59 This software is distributed under the Open Software License version 3.0 (see \url{http://www.opensource.org/licenses/osl-3.0.php}).
60
61 \subsection{Unpack zip File}
62 Use the commands
63
64 \begin{verbatim}
65 mkdir <my esys dir>
66 mv escript*.zip <my esys dir>
67 cd <my esys dir>
68 unzip escript*.zip
69 \end{verbatim}
70
71 to unzip the source files into the directory \verb|<my esys dir>|.
72
73 \subsection{Unpack tar File}
74
75 Use the commands
76
77 \begin{verbatim}
78 mkdir <my esys dir>
79 mv escript*.tar.gz <my esys dir>
80 cd <my esys dir>
81 tar xzf escript*.tar.gz
82 \end{verbatim}
83
84 to unpack the source files into the directory \verb|<my esys dir>|.
85
86 \section{Installation}
87
88 The installation is started by
89 \begin{verbatim}
90 cd <my esys dir>
91 scons usedebug=no
92 \end{verbatim}
93 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
94 \begin{verbatim}
95 cd <my esys dir>
96 scons usedebug=no options_file=myoptions.py
97 \end{verbatim}
98 You can also over-ride individual settings through the command line:
99 \begin{verbatim}
100 cd <my esys dir>
101 scons usedebug=no libinstall=/usr/lib
102 \end{verbatim}
103 This will install the libraries into the directory \verb|/usr/lib|.
104
105 Help on options is available with:
106 \begin{verbatim}
107 cd <my esys dir>
108 scons -h
109 \end{verbatim}
110 To uninstall the software use
111 \begin{verbatim}
112 cd <my esys dir>
113 scons -c
114 \end{verbatim}
115
116 If you have more than one processor available for compilation you can use the -j option to tell scons to do parallel compiles:
117 \begin{verbatim}
118 cd <my esys dir>
119 scons usedebug=no -j 8
120 \end{verbatim}
121 \section{Running Release Tests}
122 You can run the test suite of approximately 30,000 unit tests in a few hours with
123 \begin{verbatim}
124 cd <my esys dir>
125 scons usedebug=no all_tests
126 \end{verbatim}
127
128 \section{Environment Setup}
129 To make esys accessible from python you have to set
130 \begin{verbatim}
131 export PYTHONPATH=<my esys dir>:${PYTHONPATH}
132 export LD_LIBRARY_PATH=<my esys dir>/lib:${LD_LIBRARY_PATH}
133 \end{verbatim}
134
135 If you build \esys with
136 \begin{verbatim}
137 cd <my esys dir>
138 scons usedebug=no prefix=/usr
139 \end{verbatim}
140 then your libraries and python modules will be installed in system directories and you will
141 not have to set LD_LIBRARY_PATH and PYTHONPATH (assuming python is installed in
142 /usr/lib/python/site-modules).
143
144 Now you are ready to test your setup by running one of the supplied examples
145 \begin{verbatim}
146 cd <my esys dir>/doc/examples
147 python poisson.py
148 \end{verbatim}
149
150 \subsection{OpenMP Support}
151
152 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):
153 \begin{verbatim}
154 export OMP_NUM_THREADS=4
155 cd <my esys dir>/doc/examples
156 python poisson.py
157 \end{verbatim}
158
159 \subsection{MPI Support}
160
161 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):
162 \begin{verbatim}
163 cd <my esys dir>/doc/examples
164 mpirun -np 4 <my esys dir>/lib/pythonMPI poisson.py
165 \end{verbatim}
166
167 When running an MPI job the standard output of process zero goes to the screen, while the standard output of the other processes
168 is automatically redirected to files with names like stdout_cpu_0001.out.
169
170 A python script can obtain the MPI rank and size in two ways.
171 The global number of MPI processes and rank (relative to MPI_COMM_WORLD) are available through
172 \begin{verbatim}
173 iam = getMPIRankWorld()
174 nPE = getMPISizeWorld()
175 \end{verbatim}
176
177 The rank and size relative to a particular domain object (which may be limited to run on a subset of the
178 total list of MPI processes in future versions of Escript) are available through
179 \begin{verbatim}
180 iam = domain.getMPIRankWorld()
181 nPE = domain.getMPISizeWorld()
182 \end{verbatim}
183
184 \section{Getting Help}
185 Please direct any questions you might have to \url{mailto:esys@esscc.uq.edu.au}.

Properties

Name Value
svn:eol-style native
svn:keywords Author Date Id Revision

  ViewVC Help
Powered by ViewVC 1.1.26