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

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

Parent Directory Parent Directory | Revision Log Revision Log


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

  ViewVC Help
Powered by ViewVC 1.1.26