| 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 |
|
Parent Directory
| 
Revision Log