/[escript]/trunk/doc/install/srcommon.tex
ViewVC logotype

Annotation of /trunk/doc/install/srcommon.tex

Parent Directory Parent Directory | Revision Log Revision Log


Revision 2536 - (hide annotations)
Thu Jul 16 23:53:07 2009 UTC (10 years, 2 months ago) by caltinay
File MIME type: application/x-tex
File size: 10910 byte(s)
installguide: Fixed typos, minor semantics, repetitions and whitespace issues.

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

  ViewVC Help
Powered by ViewVC 1.1.26