/[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 3265 - (hide annotations)
Tue Oct 12 04:42:03 2010 UTC (8 years, 11 months ago) by caltinay
Original Path: trunk/doc/install/srcommon.tex
File MIME type: application/x-tex
File size: 11696 byte(s)
Updated relevant sections in install guide to reflect scons option changes.
Standalone section needs to be updated before the release.

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 caltinay 3265 \item \filename{scons/TEMPLATE_linux.py} (\linux and \macosx desktop)
110     \item \filename{scons/TEMPLATE_windows.py} (\winxp)
111 jfenwick 2289 \end{itemize}
112    
113 caltinay 3265 The template files contain all available options with a comment explaining the
114     purpose of each.
115     Check through the file and ensure that the relevant paths and names are correct
116     for your system and that you enable optional components that you wish to use.
117     For example, to use netCDF, find the netcdf-related lines, uncomment them
118     (i.e. remove the \# at the beginning of the lines) and change them according
119     to your installation:
120 jfenwick 2780 \begin{shellCode}
121 caltinay 3265 netcdf = True
122     netcdf_prefix = '/opt/netcdf4'
123     netcdf_libs = ['netcdf_c++', 'netcdf']
124 jfenwick 2780 \end{shellCode}
125    
126 caltinay 3265 In this example, netCDF \emph{header} files must be located in
127     \filename{/opt/netcdf4/include}\footnote{or \ldots/include32 or \ldots/include64 or \ldots/inc}
128     and the \emph{libraries} in \filename{/opt/netcdf4/lib}\footnote{or \ldots/lib32 or \ldots/lib64}.
129     If this scheme does not apply to your installation then you may also specify
130     the include-path and library-path directly like so:
131     \begin{shellCode}
132     netcdf_prefix = ['/usr/local/include/netcdf', '/usr/local/lib']
133     \end{shellCode}
134     The order is important: the first element in the list is the
135     \emph{include}-path, the second element is the \emph{library}-path and both
136     must be specified.
137    
138     If a line in the options file is commented out and you do not require the
139     feature, then it can be ignored.
140 jfenwick 2780
141 jfenwick 2289 To actually compile (if you have $n$ processors, then you can use \texttt{scons -j$n$} instead):
142    
143     \begin{shellCode}
144 jfenwick 2529 cd escript.d
145 jfenwick 2289 scons
146     \end{shellCode}
147    
148 caltinay 3265 As part of its output, scons will tell you the name of the options file it used
149     as well as a list of features and whether they are enabled for your build.
150     If you enabled an optional dependency and the library or include files could
151     not be found you will be notified and the build will stop.
152 jfenwick 2289
153 caltinay 3265 Note, that you can override all settings from the options-file on the scons
154     command line. For example, if you usually build an optimized version but would
155     like to build a debug version into a separate directory without changing your
156     default settings, you can use:
157 jfenwick 2289 \begin{shellCode}
158 caltinay 3265 scons debug=1 prefix=debugbuild
159 jfenwick 2289 \end{shellCode}
160 caltinay 3265 This will install the binaries and libraries built in debug mode into
161     directories underneath \filename{./debugbuild}.
162 jfenwick 2289
163 caltinay 3265 To run the unit test suite that comes with the source code issue
164 jfenwick 2289 \begin{shellCode}
165     scons all_tests
166     \end{shellCode}
167 caltinay 2536 Grab a coffee or two while the tests compile and run.
168 caltinay 3265 An alternative method is available for running tests on \openmp and \mpi builds.
169 jfenwick 2289
170     \subsection{Compilation with \openmp}
171 caltinay 3265 \openmp is generally enabled by setting compiler and linker switches. For the
172     most common compilers these are automatically set by build system and all you
173     have to do is set the \texttt{openmp} option to True in your options file. If
174     this does not work or your compiler is different, then consult your compiler
175     documentation for the precise switches to use and modify the \texttt{omp_flags}
176     and \texttt{omp_ldflags} variables in your options file.
177 caltinay 2536 For example, for gcc compilers which support \openmp use:
178 jfenwick 2289 \begin{shellCode}
179 caltinay 3265 openmp = True
180     omp_flags = '-fopenmp'
181     omp_ldflags = '-fopenmp'
182 jfenwick 2289 \end{shellCode}
183 caltinay 3265 (The two latter settings can also be left out as this is the default for gcc.)
184 jfenwick 2289
185 caltinay 3265 You can test your \openmp-enabled build, e.g. using 4 threads by issuing
186 jfenwick 2289 \begin{shellCode}
187 gross 2363 export ESCRIPT_NUM_THREADS=4
188     scons all_tests
189     \end{shellCode}
190    
191 caltinay 2536 \subsection{Compilation with \mpi}
192 caltinay 3265 You need to have \mpi preinstalled on your system.
193     There are a number of implementations so we do not provide any specific advice
194     here.
195     Set the following variables in your options file to according to your
196     installation:
197 jfenwick 2289 \begin{itemize}
198 caltinay 3265 \item \texttt{mpi} \\
199     which \mpi implementation (flavour) is used. Valid values are
200 caltinay 2536 \begin{itemize}
201 caltinay 3265 \item[\texttt{none}] \mpi is disabled
202 caltinay 2536 \item[\texttt{MPT}] SGI MPI implementation \\
203     \url{http://techpubs.sgi.com/library/manuals/3000/007-3687-010/pdf/007-3687-010.pdf}
204 caltinay 3265 \item[\texttt{MPICH}] Argonne's MPICH implementation \\
205     \url{http://www.mcs.anl.gov/research/projects/mpi/mpich1/}
206 caltinay 2536 \item[\texttt{MPICH2}] Argonne's MPICH version 2 implementation \\
207     \url{http://www.mcs.anl.gov/research/projects/mpi/mpich2/}
208     \item[\texttt{OPENMPI}] Open MPI \\
209     \url{http://www.open-mpi.org/}
210 caltinay 3265 \item[\texttt{INTELMPI}] Intel MPI \\
211 caltinay 2536 \url{http://software.intel.com/en-us/intel-mpi-library/}
212     \end{itemize}
213 caltinay 3265 \item \texttt{mpi_prefix} \\
214     where to find \mpi headers and libraries (see netCDF example above)
215 caltinay 2536 \item \texttt{mpi_libs} \\
216 caltinay 3265 which libraries to link to.
217 jfenwick 2289 \end{itemize}
218    
219 caltinay 3265 To test your build using 6 processes enter:
220 jfenwick 2290 \begin{shellCode}
221 caltinay 3265 export ESCRIPT_NUM_PROCS=6
222     scons all_tests
223 jfenwick 2290 \end{shellCode}
224 caltinay 3265 and on 6 processes with 4 threads each (provided \openmp is enabled):
225 gross 2363 \begin{shellCode}
226     export ESCRIPT_NUM_THREADS=4
227 caltinay 3265 export ESCRIPT_NUM_PROCS=6
228     scons all_tests
229 gross 2363 \end{shellCode}
230     Alternatively, you can give a hostfile
231     \begin{shellCode}
232     export ESCRIPT_NUM_THREADS=4
233     export ESCRIPT_HOSTFILE=myhostfile
234 caltinay 3265 scons all_tests
235 gross 2363 \end{shellCode}
236 caltinay 3265 Note that depending on your \mpi flavour it may be required to start a daemon
237     before running the tests under \mpi.
238 gross 2363
239 jfenwick 2289 \subsection{Difficulties}
240    
241 caltinay 3265 \subsubsection{Mismatch of runtime and build libraries}
242     Most external libraries used by \esfinley are linked dynamically.
243     This can lead to problems if after compiling \esfinley these libraries are
244     updated.
245     The same applies to the installed Python executable and libraries.
246     Whenever these dependencies change on your system you should recompile
247     \esfinley to avoid problems at runtime such as load errors or segmentation
248     faults.
249 jfenwick 2289
250 caltinay 2536 \subsubsection{\openmp builds segfault running examples}
251 jfenwick 2512 One known cause for this is linking the \filename{gomp} library with escript built using gcc 4.3.3.
252 caltinay 2536 While you need the \texttt{-fopenmp} switch you should not need to link \filename{gomp}.
253    

  ViewVC Help
Powered by ViewVC 1.1.26