/[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 2923 - (hide annotations)
Thu Feb 4 04:05:36 2010 UTC (9 years, 7 months ago) by jfenwick
Original Path: trunk/doc/install/srcommon.tex
File MIME type: application/x-tex
File size: 11185 byte(s)
Bringing non-release specific things from stage3.1 r2922 back to trunk

1 jfenwick 2289 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2     %
3 jfenwick 2881 % Copyright (c) 2003-2010 by University of Queensland
4 jfenwick 2289 % 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 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).
18 caltinay 2538 \Sec{sec:deps} describes the dependencies, while \Sec{sec:compilesrc} gives the compile instructions.
19 jfenwick 2529
20 caltinay 2547 If you would prefer to build all the dependecies from source in the escript-support packages please see \Chap{chap:allsrc}.
21 jfenwick 2289 \esfinley is known to compile and run on the following systems:
22     \begin{itemize}
23 caltinay 2547 \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 jfenwick 2923 \item \linux using icc on SGI ICE 8200. (At this stage, we do not recommend building with intel-11)\footnote{There is a bug in icpc-11 related to exception handling and openmp. This results in binaries which crash.}
25 caltinay 2547 \item \macosx using gcc
26 caltinay 2536 \item \winxp using the Visual C compiler (we do not specifically discuss Windows builds in this guide).
27 jfenwick 2289 \end{itemize}
28    
29     \section{External dependencies}
30 jfenwick 2529 \label{sec:deps}
31 jfenwick 2289 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 caltinay 2536 The advantage of using existing packages is that they are more likely to work together properly.
35 jfenwick 2289 You must take greater care if downloading sources separately.
36    
37     \begin{itemize}
38 caltinay 2547 \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 jfenwick 2289 \end{itemize}
47    
48 caltinay 2547 The version numbers given here are not strict requirements, more recent (and in some cases older) versions are very likely to work.
49 jfenwick 2289 The following packages should be sufficient (but not necessarily minimal) for Debian 5.0 (``Lenny''):
50 jfenwick 2583 python-dev, libboost-python1.35-dev, scons, python-numpy, g++.
51 jfenwick 2289
52 caltinay 2536 These packages may be required for some of the optional capabilities of the system:
53 jfenwick 2289
54     \begin{itemize}
55     \item netcdf-3.6.2 (\url{http://www.unidata.ucar.edu/software/netcdf}) \\-
56 caltinay 2547 Used to save data sets in binary form for checkpoint/restart (must be compiled with -fPIC)
57 caltinay 2536 \item vtk-5.0.4 (\url{http://www.vtk.org}) \\-
58 caltinay 2547 Used to save VTK files for visualization
59 jfenwick 2289 \begin{itemize}
60 caltinay 2536 \item cmake-2.4.6 (\url{http://www.cmake.org}) \\-
61 caltinay 2547 Required to build VTK
62 caltinay 2536 \item mesa-7.0.3 (\url{http://www.mesa3d.org})\\-
63 caltinay 2547 Free OpenGL replacement used by VTK
64 jfenwick 2289 \end{itemize}
65 caltinay 2536 \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 caltinay 2547 Optimization of the stiffness matrix
69 caltinay 2536 \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 jfenwick 2780 \item Lapack - Available in various versions from various places. \\
72     Currently only used to invert dense square matrices larger than 3x3.
73 jfenwick 2289 \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 caltinay 2547 Mesh generation and viewing
79 jfenwick 2289 \begin{itemize}
80 caltinay 2536 \item fltk-1.1.9 (\url{http://www.fltk.org}) \\-
81 caltinay 2547 Required to build gmsh
82 caltinay 2536 \item gsl-1.10 (\url{http://www.gnu.org/software/gsl}) \\-
83 caltinay 2547 Required to build gmsh
84 caltinay 2536 \end{itemize}
85 caltinay 2547 \item triangle-1.6 (\url{http://www.cs.cmu.edu/~quake/triangle.html}) \\-
86     Two-dimensional mesh generator and Delaunay triangulator.
87 jfenwick 2289 \end{itemize}
88    
89     Packages for visualization:
90     \begin{itemize}
91     \item mayavi-1.5 (\url{http://mayavi.sourceforge.net}) \\-
92 caltinay 2547 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 jfenwick 2289 \end{itemize}
96    
97 jfenwick 2324 \section{Compilation}\label{sec:compilesrc}
98 jfenwick 2529 Throughout this section we will assume that the source code is uncompressed in a directory called \filename{escript.d}.
99 jfenwick 2289 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 jfenwick 2568 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 jfenwick 2602 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 jfenwick 2568 From now on all paths will be relative to the top level of the source.
107 jfenwick 2780 As a starting point copy the contents one of the following files into your options file:
108 jfenwick 2289 \begin{itemize}
109     \item \filename{scons/linux_options_example.py} (\linux desktop)
110     \item \filename{scons/mac_options_example.py} (\macosx desktop)
111 jfenwick 2568 \item \filename{scons/ice_options_example.py} (SGI ICE 8200)
112     \item \filename{scons/winxp_options_example.py} (\winxp)
113 jfenwick 2289 \end{itemize}
114    
115 jfenwick 2780 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 jfenwick 2289 To actually compile (if you have $n$ processors, then you can use \texttt{scons -j$n$} instead):
127    
128     \begin{shellCode}
129 jfenwick 2529 cd escript.d
130 jfenwick 2289 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 caltinay 2536 A note about scons: if you recompile later with different options (e.g. leaving out usedebug), scons will revert
141 jfenwick 2289 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 caltinay 2536 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 jfenwick 2289
156     \subsection{Compilation with \openmp}
157 caltinay 2536 You will need to consult your compiler documentation for the precise switches to use to enable \openmp features.
158 jfenwick 2289 Once you know the options, modify the omp_optim, omp_debug and omp_libs variables in your options.py file.
159    
160 caltinay 2536 For example, for gcc compilers which support \openmp use:
161 jfenwick 2289 \begin{shellCode}
162     omp_optim = '-fopenmp'
163     omp_debug = '-fopenmp'
164     omp_libs = ['gomp']
165     \end{shellCode}
166 caltinay 2536 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 jfenwick 2289
169     Then recompile.
170     \begin{shellCode}
171     scons useopenmp=yes
172     \end{shellCode}
173    
174 caltinay 2536 You can test your build, e.g. using 4 threads by issuing
175 gross 2363 \begin{shellCode}
176     export ESCRIPT_NUM_THREADS=4
177     scons all_tests
178     \end{shellCode}
179    
180 caltinay 2536 \subsection{Compilation with \mpi}
181     You will need to have \mpi installed on your system.
182 jfenwick 2289 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 caltinay 2536 \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 jfenwick 2289 \item \texttt{mpi_path} \\
200     where to find \filename{mpi.h}
201 caltinay 2536 \item \texttt{mpi_lib_path} \\
202     where to find libraries for \mpi
203     \item \texttt{mpi_libs} \\
204 jfenwick 2289 which libraries to link to.
205     \end{itemize}
206    
207 jfenwick 2290 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 caltinay 2536 To test your build using 6 processors enter:
215 gross 2363 \begin{shellCode}
216     export ESCRIPT_NUM_NODES=6
217 gross 2370 scons usempi=yes all_tests
218 gross 2363 \end{shellCode}
219 caltinay 2536 and on 6 processors with 4 threads each using
220 gross 2363 \begin{shellCode}
221     export ESCRIPT_NUM_THREADS=4
222     export ESCRIPT_NUM_NODES=6
223 gross 2370 scons usempi=yes all_tests
224 gross 2363 \end{shellCode}
225     Alternatively, you can give a hostfile
226     \begin{shellCode}
227     export ESCRIPT_NUM_THREADS=4
228     export ESCRIPT_HOSTFILE=myhostfile
229 gross 2370 scons usempi=yes all_tests
230 gross 2363 \end{shellCode}
231 caltinay 2536 Note that depending on your \mpi flavour it may be required to start a daemon before running the tests under \mpi.
232 gross 2363
233    
234 jfenwick 2289 \subsection{Difficulties}
235    
236 caltinay 2536 %This is copied from Ken's notes on the old Twiki page
237 jfenwick 2289 \subsubsection{``Bad magic number''}
238 caltinay 2547 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 jfenwick 2289
240 caltinay 2536 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 jfenwick 2512
245 caltinay 2536 \subsubsection{\openmp builds segfault running examples}
246 jfenwick 2512
247     One known cause for this is linking the \filename{gomp} library with escript built using gcc 4.3.3.
248 caltinay 2536 While you need the \texttt{-fopenmp} switch you should not need to link \filename{gomp}.
249    

  ViewVC Help
Powered by ViewVC 1.1.26