1 |
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
2 |
% |
3 |
% Copyright (c) 2003-2009 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 |
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 mpich2-1.0.7 (\url{http://www.mcs.anl.gov/research/projects/mpich2}) \\- |
68 |
Parallelization with \mpi |
69 |
\item parmetis-3.1 (\url{http://glaros.dtc.umn.edu/gkhome/metis/parmetis/overview}) \\- |
70 |
Optimization of the stiffness matrix |
71 |
\item MKL \\(\url{http://www.intel.com/cd/software/products/asmo-na/eng/307757.htm}) \\- |
72 |
Intel's Math Kernel Library for use with their C compiler. |
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 |
From now on all paths will be relative to the top level of the source. |
104 |
As a starting point copy the contents one of the following files : |
105 |
\begin{itemize} |
106 |
\item \filename{scons/linux_options_example.py} (\linux desktop) |
107 |
\item \filename{scons/mac_options_example.py} (\macosx desktop) |
108 |
\item \filename{scons/ice_options_example.py} (SGI ICE 8200) |
109 |
\item \filename{scons/winxp_options_example.py} (\winxp) |
110 |
\end{itemize} |
111 |
|
112 |
To actually compile (if you have $n$ processors, then you can use \texttt{scons -j$n$} instead): |
113 |
|
114 |
\begin{shellCode} |
115 |
cd escript.d |
116 |
scons |
117 |
\end{shellCode} |
118 |
|
119 |
As part of its output, scons will tell you the name of the options file it used as well as a list of features |
120 |
and whether they are enabled for your build. |
121 |
|
122 |
If you require debug versions of the libraries, use: |
123 |
\begin{shellCode} |
124 |
scons usedebug=yes |
125 |
\end{shellCode} |
126 |
A note about scons: if you recompile later with different options (e.g. leaving out usedebug), scons will revert |
127 |
to its default values. If you wish to make a change more permanent, then modify your options file. |
128 |
|
129 |
|
130 |
You can install the binaries/libraries in a different location with: |
131 |
\begin{shellCode} |
132 |
scons prefix=some_dir |
133 |
\end{shellCode} |
134 |
|
135 |
You can test your build using |
136 |
\begin{shellCode} |
137 |
scons all_tests |
138 |
\end{shellCode} |
139 |
Grab a coffee or two while the tests compile and run. |
140 |
An alternative method is available for performing tests on \openmp and \mpi builds. |
141 |
|
142 |
\subsection{Compilation with \openmp} |
143 |
You will need to consult your compiler documentation for the precise switches to use to enable \openmp features. |
144 |
Once you know the options, modify the omp_optim, omp_debug and omp_libs variables in your options.py file. |
145 |
|
146 |
For example, for gcc compilers which support \openmp use: |
147 |
\begin{shellCode} |
148 |
omp_optim = '-fopenmp' |
149 |
omp_debug = '-fopenmp' |
150 |
omp_libs = ['gomp'] |
151 |
\end{shellCode} |
152 |
Depending on your version, the last change may not be required. |
153 |
If you're unsure try without the gomp library first and add it if you get linker errors. |
154 |
|
155 |
Then recompile. |
156 |
\begin{shellCode} |
157 |
scons useopenmp=yes |
158 |
\end{shellCode} |
159 |
|
160 |
You can test your build, e.g. using 4 threads by issuing |
161 |
\begin{shellCode} |
162 |
export ESCRIPT_NUM_THREADS=4 |
163 |
scons all_tests |
164 |
\end{shellCode} |
165 |
|
166 |
\subsection{Compilation with \mpi} |
167 |
You will need to have \mpi installed on your system. |
168 |
There are a number of implementations so we do not provide any specific advice here. |
169 |
You will need to modify the following variables in your options file. |
170 |
\begin{itemize} |
171 |
\item \texttt{mpi_flavour} \\ |
172 |
which \mpi implementation is used. Valid values are |
173 |
\begin{itemize} |
174 |
\item[\texttt{MPT}] SGI MPI implementation \\ |
175 |
\url{http://techpubs.sgi.com/library/manuals/3000/007-3687-010/pdf/007-3687-010.pdf} |
176 |
\item[\texttt{MPICH2}] Argonne's MPICH version 2 implementation \\ |
177 |
\url{http://www.mcs.anl.gov/research/projects/mpi/mpich2/} |
178 |
\item[\texttt{MPICH}] Argonne's MPICH implementation \\ |
179 |
\url{http://www.mcs.anl.gov/research/projects/mpi/mpich1/} |
180 |
\item[\texttt{OPENMPI}] Open MPI \\ |
181 |
\url{http://www.open-mpi.org/} |
182 |
\item[\texttt{INTELMPI}] Intel's MPI \\ |
183 |
\url{http://software.intel.com/en-us/intel-mpi-library/} |
184 |
\end{itemize} |
185 |
\item \texttt{mpi_path} \\ |
186 |
where to find \filename{mpi.h} |
187 |
\item \texttt{mpi_lib_path} \\ |
188 |
where to find libraries for \mpi |
189 |
\item \texttt{mpi_libs} \\ |
190 |
which libraries to link to. |
191 |
\end{itemize} |
192 |
|
193 |
Then compile with: |
194 |
\begin{shellCode} |
195 |
scons usempi=yes |
196 |
\end{shellCode} |
197 |
|
198 |
As with debug and openmp, you can make this a more permanent setting by modifying your options file. |
199 |
|
200 |
To test your build using 6 processors enter: |
201 |
\begin{shellCode} |
202 |
export ESCRIPT_NUM_NODES=6 |
203 |
scons usempi=yes all_tests |
204 |
\end{shellCode} |
205 |
and on 6 processors with 4 threads each using |
206 |
\begin{shellCode} |
207 |
export ESCRIPT_NUM_THREADS=4 |
208 |
export ESCRIPT_NUM_NODES=6 |
209 |
scons usempi=yes all_tests |
210 |
\end{shellCode} |
211 |
Alternatively, you can give a hostfile |
212 |
\begin{shellCode} |
213 |
export ESCRIPT_NUM_THREADS=4 |
214 |
export ESCRIPT_HOSTFILE=myhostfile |
215 |
scons usempi=yes all_tests |
216 |
\end{shellCode} |
217 |
Note that depending on your \mpi flavour it may be required to start a daemon before running the tests under \mpi. |
218 |
|
219 |
|
220 |
\subsection{Difficulties} |
221 |
|
222 |
%This is copied from Ken's notes on the old Twiki page |
223 |
\subsubsection{``Bad magic number''} |
224 |
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). |
225 |
|
226 |
It is also possible that incompatible libraries were used when compiling \esfinley. |
227 |
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. |
228 |
Another case is when Boost or Numarray was compiled against the wrong Python library. |
229 |
To avoid these problems both builder and user must ensure 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 \texttt{-fopenmp} switch you should not need to link \filename{gomp}. |
235 |
|