/[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 3265 - (show 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 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2 %
3 % Copyright (c) 2003-2010 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. (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 \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/TEMPLATE_linux.py} (\linux and \macosx desktop)
110 \item \filename{scons/TEMPLATE_windows.py} (\winxp)
111 \end{itemize}
112
113 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 \begin{shellCode}
121 netcdf = True
122 netcdf_prefix = '/opt/netcdf4'
123 netcdf_libs = ['netcdf_c++', 'netcdf']
124 \end{shellCode}
125
126 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
141 To actually compile (if you have $n$ processors, then you can use \texttt{scons -j$n$} instead):
142
143 \begin{shellCode}
144 cd escript.d
145 scons
146 \end{shellCode}
147
148 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
153 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 \begin{shellCode}
158 scons debug=1 prefix=debugbuild
159 \end{shellCode}
160 This will install the binaries and libraries built in debug mode into
161 directories underneath \filename{./debugbuild}.
162
163 To run the unit test suite that comes with the source code issue
164 \begin{shellCode}
165 scons all_tests
166 \end{shellCode}
167 Grab a coffee or two while the tests compile and run.
168 An alternative method is available for running tests on \openmp and \mpi builds.
169
170 \subsection{Compilation with \openmp}
171 \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 For example, for gcc compilers which support \openmp use:
178 \begin{shellCode}
179 openmp = True
180 omp_flags = '-fopenmp'
181 omp_ldflags = '-fopenmp'
182 \end{shellCode}
183 (The two latter settings can also be left out as this is the default for gcc.)
184
185 You can test your \openmp-enabled build, e.g. using 4 threads by issuing
186 \begin{shellCode}
187 export ESCRIPT_NUM_THREADS=4
188 scons all_tests
189 \end{shellCode}
190
191 \subsection{Compilation with \mpi}
192 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 \begin{itemize}
198 \item \texttt{mpi} \\
199 which \mpi implementation (flavour) is used. Valid values are
200 \begin{itemize}
201 \item[\texttt{none}] \mpi is disabled
202 \item[\texttt{MPT}] SGI MPI implementation \\
203 \url{http://techpubs.sgi.com/library/manuals/3000/007-3687-010/pdf/007-3687-010.pdf}
204 \item[\texttt{MPICH}] Argonne's MPICH implementation \\
205 \url{http://www.mcs.anl.gov/research/projects/mpi/mpich1/}
206 \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 \item[\texttt{INTELMPI}] Intel MPI \\
211 \url{http://software.intel.com/en-us/intel-mpi-library/}
212 \end{itemize}
213 \item \texttt{mpi_prefix} \\
214 where to find \mpi headers and libraries (see netCDF example above)
215 \item \texttt{mpi_libs} \\
216 which libraries to link to.
217 \end{itemize}
218
219 To test your build using 6 processes enter:
220 \begin{shellCode}
221 export ESCRIPT_NUM_PROCS=6
222 scons all_tests
223 \end{shellCode}
224 and on 6 processes with 4 threads each (provided \openmp is enabled):
225 \begin{shellCode}
226 export ESCRIPT_NUM_THREADS=4
227 export ESCRIPT_NUM_PROCS=6
228 scons all_tests
229 \end{shellCode}
230 Alternatively, you can give a hostfile
231 \begin{shellCode}
232 export ESCRIPT_NUM_THREADS=4
233 export ESCRIPT_HOSTFILE=myhostfile
234 scons all_tests
235 \end{shellCode}
236 Note that depending on your \mpi flavour it may be required to start a daemon
237 before running the tests under \mpi.
238
239 \subsection{Difficulties}
240
241 \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
250 \subsubsection{\openmp builds segfault running examples}
251 One known cause for this is linking the \filename{gomp} library with escript built using gcc 4.3.3.
252 While you need the \texttt{-fopenmp} switch you should not need to link \filename{gomp}.
253

  ViewVC Help
Powered by ViewVC 1.1.26