# Contents of /trunk/doc/install/srcommon.tex

Revision 2363 - (show annotations)
Fri Apr 3 03:56:19 2009 UTC (10 years, 5 months ago) by gross
File MIME type: application/x-tex
File size: 9372 byte(s)
scons should now be able to run tests under MPI and OpenMP

 1 2 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 3 % 4 % Copyright (c) 2003-2008 by University of Queensland 5 % Earth Systems Science Computational Center (ESSCC) 6 7 % 8 % Primary Business: Queensland, Australia 9 % Licensed under the Open Software License version 3.0 10 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 \esfinley is known to compile and run on the following systems: 19 \begin{itemize} 20 \item \linux under gcc\footnote{There are some problems with OpenMP under gcc prior to version 4.3.2} - \Sec{sec:srclinux} 21 \item \linux under icc on SGI ICE 8200. 22 \item \macosx under gcc - \Sec{sec:srcmac} 23 \end{itemize} 24 25 \section{External dependencies} 26 The following external packages are required in order to compile and run \esfinley. 27 Where version numbers are specified, more recent versions can probably be subsituted. 28 You can either try the standard/precompiled packages available for your operating system or you can download and build them from source. 29 The advantage of using existing packages is that they will probably all work togther properly. 30 You must take greater care if downloading sources separately. 31 32 \begin{itemize} 33 \item python-2.5.1 (\url{http://python.org}) \\ 34 - Python interpreter (You must compile with shared libraries.) 35 \item numarray 1.5.2 \\ (\url{http://www.stsci.edu/resources/software_hardware/numarray/numarray.html}) \\ 36 - Arrays for python. 37 \item boost-1.35 (\url{http://www.boost.org}) \\ 38 - Provides an interface between C++ and python. 39 \item scons-0.989.5 (\url{http://www.scons.org/}) \\ 40 - a python-based alternative to make''. 41 \end{itemize} 42 43 The version numbers given here are not strict requirements, more recent (and in some cases older) versions will 44 still work. 45 The following packages should be sufficient (but not necessarily minimal) for Debian 5.0 (Lenny''): 46 python-dev, libboost1.35-dev, scons, python-numarray, g++. 47 48 49 These packages may be required for some of the optional capabilities of the system. 50 51 \begin{itemize} 52 \item netcdf-3.6.2 (\url{http://www.unidata.ucar.edu/software/netcdf}) \\- 53 Used to save data sets in binary form for checkpoint/restart (must be compiled with -fPIC). 54 \item vtk-5.0.4 (\url{http://www.vtk.org}) \\- 55 This is used to save VTK files for visualization. 56 \begin{itemize} 57 \item cmake-2.4.6 (\url{http://www.cmake.org}) \\- 58 This is used to build VTK. 59 \item mesa-7.0.3 (\url{http://www.mesa3d.org})\\- 60 Free OpenGL replacement used by VTK. 61 \end{itemize} 62 63 \item mpich2-1.0.7 (\url{http://www.mcs.anl.gov/research/projects/mpich2}) \\- 64 Parallelization with MPI. 65 \item parmetis-3.1 (\url{http://glaros.dtc.umn.edu/gkhome/metis/parmetis/overview}) \\- 66 Optimization of the stiffness matrix. 67 \item MKL \\(\url{http://www.intel.com/cd/software/products/asmo-na/eng/307757.htm}) \\- 68 Intel's Math Kernel Library for use with their c compiler. 69 \end{itemize} 70 71 The following packages might be useful for mesh generation: 72 \begin{itemize} 73 \item gmsh-2.2.0 (\url{http://www.geuz.org/gmsh}) \\- 74 Mesh generation and viewing. 75 \begin{itemize} 76 \item fltk-1.1.9 (\url{http://www.fltk.org}) \\- 77 This is used to build gmsh 78 \item gsl-1.10 (\url{http://www.gnu.org/software/gsl}) \\- 79 This is used to build gmsh 80 \end{itemize} 81 82 \item triangle-1.6 (\url{http://www.cs.cmu.edu/~quake/triangle.html}) 83 \end{itemize} 84 85 Packages for visualization: 86 \begin{itemize} 87 \item mayavi-1.5 (\url{http://mayavi.sourceforge.net}) \\- 88 MayaVi is referenced in our User Guide for viewing VTK files. 89 \item visit-1.9 (\url{https://wci.llnl.gov/codes/visit/}) 90 \end{itemize} 91 92 \section{Compilation}\label{sec:compilesrc} 93 Throughout this section we will assume that the source code is uncompressed in a directory called trunk. 94 You can call the directory anything you like, provided that you make the change before you compile. 95 96 You need to indicate where to find the external dependencies. 97 Unless specified otherwise, all paths will be relative to the top level of the source. 98 To do this, create a file in the \filename{scons} directory called \filename{x_options.py} where x'' is the name of your computer. 99 As a starting point use one of the following: 100 \begin{itemize} 101 \item \filename{scons/linux_options_example.py} (\linux desktop) 102 \item \filename{scons/mac_options_example.py} (\macosx desktop) 103 \item \filename{ice_options_example.py} (SGI ICE 8200) 104 \item \filename{winxp_options_example.py} (\winxp) 105 \end{itemize} 106 107 To actually compile (if you have $n$ processors, then you can use \texttt{scons -j$n$} instead): 108 109 \begin{shellCode} 110 cd trunk 111 scons 112 \end{shellCode} 113 114 As part of its output, scons will tell you the name of the options file it used as well as a list of features 115 and whether they are enabled for your build. 116 117 If you require debug versions of the libraries, use: 118 \begin{shellCode} 119 scons usedebug=yes 120 \end{shellCode} 121 A note about scons: if you recompile later with different options (eg leaving off usedebug), scons will revert 122 to its default values. If you wish to make a change more permanent, then modify your options file. 123 124 125 You can install the binaries/libraries in a different location with: 126 \begin{shellCode} 127 scons prefix=some_dir 128 \end{shellCode} 129 130 You can test your build using 131 \begin{shellCode} 132 scons all_tests 133 \end{shellCode} 134 An alternative method is available for performing tests on \openmp and MPI builds. 135 136 \subsection{Compilation with \openmp} 137 You will need to consult your compiler documentation for the precise switches to use to enable OpenMP features. 138 Once you know the options, modify the omp_optim, omp_debug and omp_libs variables in your options.py file. 139 140 For example, for gcc compilers which support \openmp use. 141 \begin{shellCode} 142 omp_optim = '-fopenmp' 143 omp_debug = '-fopenmp' 144 omp_libs = ['gomp'] 145 \end{shellCode} 146 Depending on your version, last change may not be required. 147 148 Then recompile. 149 \begin{shellCode} 150 scons useopenmp=yes 151 \end{shellCode} 152 153 You can test your build on for instance 4 threads using 154 \begin{shellCode} 155 export ESCRIPT_NUM_THREADS=4 156 scons all_tests 157 \end{shellCode} 158 159 \subsection{Compilation with MPI} 160 You will need to have MPI installed on your system. 161 There are a number of implementations so we do not provide any specific advice here. 162 You will need to modify the following variables in your options file. 163 \begin{itemize} 164 \item \texttt{mpi_flavour} \\ 165 which MPI implementation is used. Valid values are \begin{itemize} 166 \item[\texttt{MPT}] SGI MPI implementation \\ \url{http://techpubs.sgi.com/library/manuals/3000/007-3687-010/pdf/007-3687-010.pdf} 167 \item[\texttt{MPICH}] Argonne's MPICH implementation \\ \url{http://www.mcs.anl.gov/research/projects/mpi/mpich1/} 168 \item[\texttt{OPENMPI}] Open MPI \url{http://www.open-mpi.org/} 169 \item[\texttt{INTELMPI}] Intel's MPI \url{http://software.intel.com/en-us/intel-mpi-library/} 170 \end{itemize} 171 \item \texttt{mpi_path} \\ 172 where to find \filename{mpi.h} 173 \item \texttt{mpi_lib_path} \\ 174 where to find libraries for mpi 175 \item \texttt{mpi_libs} \\ 176 which libraries to link to. 177 \end{itemize} 178 179 Then compile with: 180 \begin{shellCode} 181 scons usempi=yes 182 \end{shellCode} 183 184 As with debug and openmp, you can make this a more permanent setting by modifying your options file. 185 186 You can test your build on for instance 6 processors using 187 \begin{shellCode} 188 export ESCRIPT_NUM_NODES=6 189 scons all_tests 190 \end{shellCode} 191 and on 6 processors with 4 threads each using 192 \begin{shellCode} 193 export ESCRIPT_NUM_THREADS=4 194 export ESCRIPT_NUM_NODES=6 195 scons all_tests 196 \end{shellCode} 197 Alternatively, you can give a hostfile 198 \begin{shellCode} 199 export ESCRIPT_NUM_THREADS=4 200 export ESCRIPT_HOSTFILE=myhostfile 201 scons all_tests 202 \end{shellCode} 203 204 205 \subsection{Difficulties} 206 207 %This is copied from Ken's notes on teh old Twiki page 208 \subsubsection{Bad magic number''} 209 Some reasons for this error message include: 210 \begin{itemize} 211 \item Using different versions of python when installing and running escript (Use \texttt{which python} and \texttt{python --version} to check) 212 \item Using different versions of libraries (Make sure \texttt{LD_LIBRARY_PATH} has \filename{/trunk/lib} listed first) 213 \item Using different versions of python modules (Make sure \texttt{PYTHONPATH} has \filename{/trunk/escript} directory listed first) 214 \end{itemize} 215 216 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}. 217 218 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.