/[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 2529 - (show 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
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 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 \esfinley is known to compile and run on the following systems:
25 \begin{itemize}
26 \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 \item \linux under icc on SGI ICE 8200.
28 \item \macosx under gcc - \Sec{sec:srcmac}
29 \item \winxp with visual studio (we do not specifically discuss windows builds in this guide).
30 \end{itemize}
31
32 \section{External dependencies}
33 \label{sec:deps}
34 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 \item python-2.5.1 (\url{http://python.org}) \\
42 - Python interpreter (You must compile with shared libraries.)
43 \item numpy 1.1.0 (\url{http://numpy.scipy.org})
44 - Arrays for python.
45 \item boost-1.35 (\url{http://www.boost.org}) \\
46 - Provides an interface between C++ and python.
47 \item scons-0.989.5 (\url{http://www.scons.org/}) \\
48 - a python-based alternative to ``make''.
49 \end{itemize}
50
51 The version numbers given here are not strict requirements, more recent (and in some cases older) versions will
52 still work.
53 The following packages should be sufficient (but not necessarily minimal) for Debian 5.0 (``Lenny''):
54 python-dev, libboost1.35-dev, scons, python-numpy, g++.
55
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 \item netpbm (\url{http://netpbm.sourceforge.com}) \\-
71 tools for producing movies from images
72 \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 \item MKL \\(\url{http://www.intel.com/cd/software/products/asmo-na/eng/307757.htm}) \\-
77 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 \section{Compilation}\label{sec:compilesrc}
102 Throughout this section we will assume that the source code is uncompressed in a directory called \filename{escript.d}.
103 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 cd escript.d
120 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 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 \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 \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 \item[\texttt{MPICH2}] Argonne's MPICH vesrion 2 implementation \\ \url{http://www.mcs.anl.gov/research/projects/mpi/mpich2/}
177 \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 \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 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 You can test your build on for instance 6 processors using
197 \begin{shellCode}
198 export ESCRIPT_NUM_NODES=6
199 scons usempi=yes all_tests
200 \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 scons usempi=yes all_tests
206 \end{shellCode}
207 Alternatively, you can give a hostfile
208 \begin{shellCode}
209 export ESCRIPT_NUM_THREADS=4
210 export ESCRIPT_HOSTFILE=myhostfile
211 scons usempi=yes all_tests
212 \end{shellCode}
213 Notice that depending on your MPI flavour it may be required to start a daemon before running the tests under MPI.
214
215
216 \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
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