/[escript]/branches/dirac/doc/install/srcommon.tex
ViewVC logotype

Contents of /branches/dirac/doc/install/srcommon.tex

Parent Directory Parent Directory | Revision Log Revision Log


Revision 2780 - (show annotations)
Thu Nov 26 03:54:24 2009 UTC (9 years, 9 months ago) by jfenwick
Original Path: trunk/doc/install/srcommon.tex
File MIME type: application/x-tex
File size: 11008 byte(s)
Put the windows instructions back in.
Put more detail in the MPI hints.
1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2 %
3 % Copyright (c) 2003-2009 by University of Queensland
4 % Earth Systems Science Computational Center (ESSCC)
5 % http://www.uq.edu.au/esscc
6 %
7 % Primary Business: Queensland, Australia
8 % Licensed under the Open Software License version 3.0
9 % http://www.opensource.org/licenses/osl-3.0.php
10 %
11 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
12
13 % This file contains material common to all src distributions.
14
15 % The original version of this content came from the esscc twiki page maintained by ksteube
16
17 This chapter describes how to build \esfinley from source assuming that the dependencies are already installed (for example using precompiled packages for your OS).
18 \Sec{sec:deps} describes the dependencies, while \Sec{sec:compilesrc} gives the compile instructions.
19
20 If you would prefer to build all the dependecies from source in the escript-support packages please see \Chap{chap:allsrc}.
21 \esfinley is known to compile and run on the following systems:
22 \begin{itemize}
23 \item \linux using gcc\footnote{There are some problems with \openmp under gcc prior to version 4.3.2. Also do not link the gomp library with gcc 4.3.3 - it causes problems.}
24 \item \linux using icc on SGI ICE 8200
25 \item \macosx using gcc
26 \item \winxp using the Visual C compiler (we do not specifically discuss Windows builds in this guide).
27 \end{itemize}
28
29 \section{External dependencies}
30 \label{sec:deps}
31 The following external packages are required in order to compile and run \esfinley.
32 Where version numbers are specified, more recent versions can probably be subsituted.
33 You can either try the standard/precompiled packages available for your operating system or you can download and build them from source.
34 The advantage of using existing packages is that they are more likely to work together properly.
35 You must take greater care if downloading sources separately.
36
37 \begin{itemize}
38 \item python-2.5.1 (\url{http://python.org}) \\-
39 Python interpreter (you must compile with shared libraries.)
40 \item numpy 1.1.0 (\url{http://numpy.scipy.org}) \\-
41 Arrays for python
42 \item boost-1.35 (\url{http://www.boost.org}) \\-
43 Interface between C++ and Python
44 \item scons-0.989.5 (\url{http://www.scons.org/}) \\-
45 Python-based alternative to ``make''.
46 \end{itemize}
47
48 The version numbers given here are not strict requirements, more recent (and in some cases older) versions are very likely to work.
49 The following packages should be sufficient (but not necessarily minimal) for Debian 5.0 (``Lenny''):
50 python-dev, libboost-python1.35-dev, scons, python-numpy, g++.
51
52 These packages may be required for some of the optional capabilities of the system:
53
54 \begin{itemize}
55 \item netcdf-3.6.2 (\url{http://www.unidata.ucar.edu/software/netcdf}) \\-
56 Used to save data sets in binary form for checkpoint/restart (must be compiled with -fPIC)
57 \item vtk-5.0.4 (\url{http://www.vtk.org}) \\-
58 Used to save VTK files for visualization
59 \begin{itemize}
60 \item cmake-2.4.6 (\url{http://www.cmake.org}) \\-
61 Required to build VTK
62 \item mesa-7.0.3 (\url{http://www.mesa3d.org})\\-
63 Free OpenGL replacement used by VTK
64 \end{itemize}
65 \item netpbm (\url{http://netpbm.sourceforge.com}) \\-
66 Tools for producing movies from images
67 \item parmetis-3.1 (\url{http://glaros.dtc.umn.edu/gkhome/metis/parmetis/overview}) \\-
68 Optimization of the stiffness matrix
69 \item MKL \\(\url{http://www.intel.com/cd/software/products/asmo-na/eng/307757.htm}) \\-
70 Intel's Math Kernel Library for use with their C compiler.
71 \item Lapack - Available in various versions from various places. \\
72 Currently only used to invert dense square matrices larger than 3x3.
73 \end{itemize}
74
75 The following packages might be useful for mesh generation:
76 \begin{itemize}
77 \item gmsh-2.2.0 (\url{http://www.geuz.org/gmsh}) \\-
78 Mesh generation and viewing
79 \begin{itemize}
80 \item fltk-1.1.9 (\url{http://www.fltk.org}) \\-
81 Required to build gmsh
82 \item gsl-1.10 (\url{http://www.gnu.org/software/gsl}) \\-
83 Required to build gmsh
84 \end{itemize}
85 \item triangle-1.6 (\url{http://www.cs.cmu.edu/~quake/triangle.html}) \\-
86 Two-dimensional mesh generator and Delaunay triangulator.
87 \end{itemize}
88
89 Packages for visualization:
90 \begin{itemize}
91 \item mayavi-1.5 (\url{http://mayavi.sourceforge.net}) \\-
92 MayaVi is referenced in our User's Guide for viewing VTK files
93 \item visit-1.11.2 (\url{https://wci.llnl.gov/codes/visit/}) \\-
94 A featureful visualization system with movie-making capabilities.
95 \end{itemize}
96
97 \section{Compilation}\label{sec:compilesrc}
98 Throughout this section we will assume that the source code is uncompressed in a directory called \filename{escript.d}.
99 You can call the directory anything you like, provided that you make the change before you compile.
100
101 You need to indicate where to find the external dependencies.
102 To do this, create a file in the \filename{escript.d/scons} directory called \filename{x_options.py} where ``x'' is the name of your computer (output of the \texttt{hostname} command).
103 Please note that if your hostname has non-alphanumeric characters in it (eg - ) you need to replace them with underscores.
104 For example the options file for \texttt{bob-desktop} would be named \filename{bob_desktop_options.py}.
105
106 From now on all paths will be relative to the top level of the source.
107 As a starting point copy the contents one of the following files into your options file:
108 \begin{itemize}
109 \item \filename{scons/linux_options_example.py} (\linux desktop)
110 \item \filename{scons/mac_options_example.py} (\macosx desktop)
111 \item \filename{scons/ice_options_example.py} (SGI ICE 8200)
112 \item \filename{scons/winxp_options_example.py} (\winxp)
113 \end{itemize}
114
115 Check through the file and ensure that the relevant paths and names are correct for your system.
116 For optional features, you will need to set their use variable as well.
117 For example, to use netcdf, you will need to find the
118 usevtk line and make sure it reads
119 \begin{shellCode}
120 usevtk = 'yes'
121 \end{shellCode}
122 (and is not commented out - ie it does not begin with \#)
123
124 If a line is commented out and you do not require those features, then it can be ignored.
125
126 To actually compile (if you have $n$ processors, then you can use \texttt{scons -j$n$} instead):
127
128 \begin{shellCode}
129 cd escript.d
130 scons
131 \end{shellCode}
132
133 As part of its output, scons will tell you the name of the options file it used as well as a list of features
134 and whether they are enabled for your build.
135
136 If you require debug versions of the libraries, use:
137 \begin{shellCode}
138 scons usedebug=yes
139 \end{shellCode}
140 A note about scons: if you recompile later with different options (e.g. leaving out usedebug), scons will revert
141 to its default values. If you wish to make a change more permanent, then modify your options file.
142
143
144 You can install the binaries/libraries in a different location with:
145 \begin{shellCode}
146 scons prefix=some_dir
147 \end{shellCode}
148
149 You can test your build using
150 \begin{shellCode}
151 scons all_tests
152 \end{shellCode}
153 Grab a coffee or two while the tests compile and run.
154 An alternative method is available for performing tests on \openmp and \mpi builds.
155
156 \subsection{Compilation with \openmp}
157 You will need to consult your compiler documentation for the precise switches to use to enable \openmp features.
158 Once you know the options, modify the omp_optim, omp_debug and omp_libs variables in your options.py file.
159
160 For example, for gcc compilers which support \openmp use:
161 \begin{shellCode}
162 omp_optim = '-fopenmp'
163 omp_debug = '-fopenmp'
164 omp_libs = ['gomp']
165 \end{shellCode}
166 Depending on your version, the last change may not be required.
167 If you're unsure try without the gomp library first and add it if you get linker errors.
168
169 Then recompile.
170 \begin{shellCode}
171 scons useopenmp=yes
172 \end{shellCode}
173
174 You can test your build, e.g. using 4 threads by issuing
175 \begin{shellCode}
176 export ESCRIPT_NUM_THREADS=4
177 scons all_tests
178 \end{shellCode}
179
180 \subsection{Compilation with \mpi}
181 You will need to have \mpi installed on your system.
182 There are a number of implementations so we do not provide any specific advice here.
183 You will need to modify the following variables in your options file.
184 \begin{itemize}
185 \item \texttt{mpi_flavour} \\
186 which \mpi implementation is used. Valid values are
187 \begin{itemize}
188 \item[\texttt{MPT}] SGI MPI implementation \\
189 \url{http://techpubs.sgi.com/library/manuals/3000/007-3687-010/pdf/007-3687-010.pdf}
190 \item[\texttt{MPICH2}] Argonne's MPICH version 2 implementation \\
191 \url{http://www.mcs.anl.gov/research/projects/mpi/mpich2/}
192 \item[\texttt{MPICH}] Argonne's MPICH implementation \\
193 \url{http://www.mcs.anl.gov/research/projects/mpi/mpich1/}
194 \item[\texttt{OPENMPI}] Open MPI \\
195 \url{http://www.open-mpi.org/}
196 \item[\texttt{INTELMPI}] Intel's MPI \\
197 \url{http://software.intel.com/en-us/intel-mpi-library/}
198 \end{itemize}
199 \item \texttt{mpi_path} \\
200 where to find \filename{mpi.h}
201 \item \texttt{mpi_lib_path} \\
202 where to find libraries for \mpi
203 \item \texttt{mpi_libs} \\
204 which libraries to link to.
205 \end{itemize}
206
207 Then compile with:
208 \begin{shellCode}
209 scons usempi=yes
210 \end{shellCode}
211
212 As with debug and openmp, you can make this a more permanent setting by modifying your options file.
213
214 To test your build using 6 processors enter:
215 \begin{shellCode}
216 export ESCRIPT_NUM_NODES=6
217 scons usempi=yes all_tests
218 \end{shellCode}
219 and on 6 processors with 4 threads each using
220 \begin{shellCode}
221 export ESCRIPT_NUM_THREADS=4
222 export ESCRIPT_NUM_NODES=6
223 scons usempi=yes all_tests
224 \end{shellCode}
225 Alternatively, you can give a hostfile
226 \begin{shellCode}
227 export ESCRIPT_NUM_THREADS=4
228 export ESCRIPT_HOSTFILE=myhostfile
229 scons usempi=yes all_tests
230 \end{shellCode}
231 Note that depending on your \mpi flavour it may be required to start a daemon before running the tests under \mpi.
232
233
234 \subsection{Difficulties}
235
236 %This is copied from Ken's notes on the old Twiki page
237 \subsubsection{``Bad magic number''}
238 This error usually indicates that the version of python used to run escript differs from the version used when installing escript (Use \texttt{which python} and \texttt{python --version} to check).
239
240 It is also possible that incompatible libraries were used when compiling \esfinley.
241 For example, if you run with Python2.4 but the software was compiled against Python2.5 then you will get unsatisfied externals or a large error message with a long traceback.
242 Another case is when Boost or Numarray was compiled against the wrong Python library.
243 To avoid these problems both builder and user must ensure they are using the same python libraries.
244
245 \subsubsection{\openmp builds segfault running examples}
246
247 One known cause for this is linking the \filename{gomp} library with escript built using gcc 4.3.3.
248 While you need the \texttt{-fopenmp} switch you should not need to link \filename{gomp}.
249

  ViewVC Help
Powered by ViewVC 1.1.26