/[escript]/trunk/doc/install/srcommon.tex
ViewVC logotype

Diff of /trunk/doc/install/srcommon.tex

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 2535 by jfenwick, Thu Jul 9 06:06:35 2009 UTC revision 2536 by caltinay, Thu Jul 16 23:53:07 2009 UTC
# Line 15  Line 15 
15    
16  % The original version of this content came from the esscc twiki page maintained by ksteube  % 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.  This chapter describes how to build \esfinley from source assuming that the dependencies are already installed (for example using precompiled packages for your OS).
 For example using precompiled packages for your OS.  
19  Section~\ref{sec:deps} describes the dependencies, while Section~\ref{sec:compilesrc} gives the compile instructions.  Section~\ref{sec:deps} describes the dependencies, while Section~\ref{sec:compilesrc} gives the compile instructions.
20    
21  If you would prefer to build all the dependecies from source in the escript-support packages please see Chapter~\ref{chap:srcall}  If you would prefer to build all the dependecies from source in the escript-support packages please see Chapter~\ref{chap:allsrc}
22    
23  \esfinley is known to compile and run on the following systems:  \esfinley is known to compile and run on the following systems:
24  \begin{itemize}  \begin{itemize}
25   \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}   \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.} - \Sec{sec:srclinux}
26  \item \linux under icc on SGI ICE 8200.  \item \linux using icc on SGI ICE 8200.
27  \item \macosx under gcc - \Sec{sec:srcmac}  \item \macosx using gcc - \Sec{sec:srcmac}
28  \item \winxp with visual studio (we do not specifically discuss windows builds in this guide).  \item \winxp using the Visual C compiler (we do not specifically discuss Windows builds in this guide).
29  \end{itemize}  \end{itemize}
30    
31  \section{External dependencies}  \section{External dependencies}
# Line 34  If you would prefer to build all the dep Line 33  If you would prefer to build all the dep
33  The following external packages are required in order to compile and run \esfinley.  The following external packages are required in order to compile and run \esfinley.
34  Where version numbers are specified, more recent versions can probably be subsituted.  Where version numbers are specified, more recent versions can probably be subsituted.
35  You can either try the standard/precompiled packages available for your operating system or you can download and build them from source.  You can either try the standard/precompiled packages available for your operating system or you can download and build them from source.
36  The advantage of using existing packages is that they will probably all work togther properly.  The advantage of using existing packages is that they are more likely to work together properly.
37  You must take greater care if downloading sources separately.  You must take greater care if downloading sources separately.
38    
39  \begin{itemize}  \begin{itemize}
40   \item python-2.5.1 (\url{http://python.org}) \\   \item python-2.5.1 (\url{http://python.org}) \\
41  - Python  interpreter (You must compile with shared libraries.)  - Python interpreter (You must compile with shared libraries.)
42  \item numpy 1.1.0 (\url{http://numpy.scipy.org})  \item numpy 1.1.0 (\url{http://numpy.scipy.org})
43  - Arrays for python.  - Arrays for python.
44  \item boost-1.35 (\url{http://www.boost.org}) \\  \item boost-1.35 (\url{http://www.boost.org}) \\
# Line 48  You must take greater care if downloadin Line 47  You must take greater care if downloadin
47  - a python-based alternative to ``make''.  - a python-based alternative to ``make''.
48  \end{itemize}  \end{itemize}
49    
50  The version numbers given here are not strict requirements, more recent (and in some cases older) versions will  The version numbers given here are not strict requirements, more recent (and in some cases older) versions will still work.
 still work.  
51  The following packages should be sufficient (but not necessarily minimal) for Debian 5.0 (``Lenny''):  The following packages should be sufficient (but not necessarily minimal) for Debian 5.0 (``Lenny''):
52  python-dev, libboost1.35-dev, scons, python-numpy, g++.  python-dev, libboost1.35-dev, scons, python-numpy, g++.
53    
54    
55  These packages may be required for some of the optional capabilities of the system.  These packages may be required for some of the optional capabilities of the system:
56    
57  \begin{itemize}  \begin{itemize}
58   \item netcdf-3.6.2 (\url{http://www.unidata.ucar.edu/software/netcdf}) \\-   \item netcdf-3.6.2 (\url{http://www.unidata.ucar.edu/software/netcdf}) \\-
59          Used to save data sets in binary form for checkpoint/restart (must be compiled with -fPIC).          Used to save data sets in binary form for checkpoint/restart (must be compiled with -fPIC).
60  \item vtk-5.0.4 (\url{http://www.vtk.org}) \\-   \item vtk-5.0.4 (\url{http://www.vtk.org}) \\-
61          This is used to save VTK files for visualization.          This is used to save VTK files for visualization.
62    \begin{itemize}    \begin{itemize}
63    \item cmake-2.4.6 (\url{http://www.cmake.org}) \\-     \item cmake-2.4.6 (\url{http://www.cmake.org}) \\-
64          This is used to build VTK.          Required to build VTK.
65    \item     mesa-7.0.3 (\url{http://www.mesa3d.org})\\-     \item mesa-7.0.3 (\url{http://www.mesa3d.org})\\-
66          Free OpenGL replacement used by VTK.          Free OpenGL replacement used by VTK.
67    \end{itemize}    \end{itemize}
68  \item netpbm (\url{http://netpbm.sourceforge.com}) \\-   \item netpbm (\url{http://netpbm.sourceforge.com}) \\-
69      tools for producing movies from images          Tools for producing movies from images
70  \item     mpich2-1.0.7 (\url{http://www.mcs.anl.gov/research/projects/mpich2}) \\-   \item mpich2-1.0.7 (\url{http://www.mcs.anl.gov/research/projects/mpich2}) \\-
71          Parallelization with MPI.          Parallelization with MPI.
72  \item     parmetis-3.1 (\url{http://glaros.dtc.umn.edu/gkhome/metis/parmetis/overview}) \\-   \item parmetis-3.1 (\url{http://glaros.dtc.umn.edu/gkhome/metis/parmetis/overview}) \\-
73          Optimization of the stiffness matrix.          Optimization of the stiffness matrix.
74  \item MKL \\(\url{http://www.intel.com/cd/software/products/asmo-na/eng/307757.htm}) \\-   \item MKL \\(\url{http://www.intel.com/cd/software/products/asmo-na/eng/307757.htm}) \\-
75          Intel's Math Kernel Library for use with their c compiler.          Intel's Math Kernel Library for use with their C compiler.
76  \end{itemize}  \end{itemize}
77    
78  The following packages might be useful for mesh generation:  The following packages might be useful for mesh generation:
# Line 82  The following packages might be useful f Line 80  The following packages might be useful f
80   \item gmsh-2.2.0 (\url{http://www.geuz.org/gmsh}) \\-   \item gmsh-2.2.0 (\url{http://www.geuz.org/gmsh}) \\-
81      Mesh generation and viewing.      Mesh generation and viewing.
82    \begin{itemize}    \begin{itemize}
83   \item fltk-1.1.9 (\url{http://www.fltk.org}) \\-     \item fltk-1.1.9 (\url{http://www.fltk.org}) \\-
84      This is used to build gmsh      Required to build gmsh
85  \item gsl-1.10 (\url{http://www.gnu.org/software/gsl}) \\-     \item gsl-1.10 (\url{http://www.gnu.org/software/gsl}) \\-
86      This is used to build gmsh      Required to build gmsh
87  \end{itemize}    \end{itemize}
88     \item triangle-1.6 (\url{http://www.cs.cmu.edu/~quake/triangle.html})
 \item triangle-1.6 (\url{http://www.cs.cmu.edu/~quake/triangle.html})  
89  \end{itemize}  \end{itemize}
90    
91  Packages for visualization:  Packages for visualization:
92  \begin{itemize}  \begin{itemize}
93   \item mayavi-1.5 (\url{http://mayavi.sourceforge.net}) \\-   \item mayavi-1.5 (\url{http://mayavi.sourceforge.net}) \\-
94      MayaVi is referenced in our User Guide for viewing VTK files.      MayaVi is referenced in our User Guide for viewing VTK files.
95   \item visit-1.9 (\url{https://wci.llnl.gov/codes/visit/})   \item visit-1.11 (\url{https://wci.llnl.gov/codes/visit/}) \\-
96        A featureful visualization system with movie-making capabilities.
97  \end{itemize}  \end{itemize}
98    
99  \section{Compilation}\label{sec:compilesrc}  \section{Compilation}\label{sec:compilesrc}
# Line 104  You can call the directory anything you Line 102  You can call the directory anything you
102    
103  You need to indicate where to find the external dependencies.  You need to indicate where to find the external dependencies.
104  Unless specified otherwise, all paths will be relative to the top level of the source.  Unless specified otherwise, all paths will be relative to the top level of the source.
105  To do this, create a file in the \filename{scons} directory called \filename{x_options.py} where ``x'' is the name of your computer.  To do this, create a file in the \filename{scons} directory called \filename{x_options.py} where ``x'' is the name of your computer (output of the \texttt{hostname} command).
106  As a starting point use one of the following:  As a starting point use one of the following:
107  \begin{itemize}  \begin{itemize}
108   \item \filename{scons/linux_options_example.py} (\linux desktop)   \item \filename{scons/linux_options_example.py} (\linux desktop)
# Line 127  If you require debug versions of the lib Line 125  If you require debug versions of the lib
125  \begin{shellCode}  \begin{shellCode}
126   scons usedebug=yes   scons usedebug=yes
127  \end{shellCode}  \end{shellCode}
128  A note about scons: if you recompile later with different options (eg leaving off usedebug), scons will revert  A note about scons: if you recompile later with different options (e.g. leaving out usedebug), scons will revert
129  to its default values. If you wish to make a change more permanent, then modify your options file.  to its default values. If you wish to make a change more permanent, then modify your options file.
130    
131    
# Line 140  You can test your build using Line 138  You can test your build using
138  \begin{shellCode}  \begin{shellCode}
139  scons all_tests  scons all_tests
140  \end{shellCode}  \end{shellCode}
141  An alternative method is available for performing tests on \openmp and MPI builds.  Grab a coffee or two while the tests compile and run.
142    An alternative method is available for performing tests on \openmp and \mpi builds.
143    
144  \subsection{Compilation with \openmp}  \subsection{Compilation with \openmp}
145  You will need to consult your compiler documentation for the precise switches to use to enable OpenMP features.  You will need to consult your compiler documentation for the precise switches to use to enable \openmp features.
146  Once you know the options, modify the omp_optim, omp_debug and omp_libs variables in your options.py file.  Once you know the options, modify the omp_optim, omp_debug and omp_libs variables in your options.py file.
147    
148  For example, for gcc compilers which support \openmp use.  For example, for gcc compilers which support \openmp use:
149  \begin{shellCode}  \begin{shellCode}
150  omp_optim       = '-fopenmp'  omp_optim       = '-fopenmp'
151  omp_debug       = '-fopenmp'  omp_debug       = '-fopenmp'
152  omp_libs        = ['gomp']  omp_libs        = ['gomp']
153  \end{shellCode}  \end{shellCode}
154  Depending on your version, last change may not be required.  Depending on your version, the last change may not be required.
155    If you're unsure try without the gomp library first and add it if you get linker errors.
156    
157  Then recompile.  Then recompile.
158  \begin{shellCode}  \begin{shellCode}
159   scons useopenmp=yes   scons useopenmp=yes
160  \end{shellCode}  \end{shellCode}
161    
162  You can test your build on for instance 4 threads using  You can test your build, e.g. using 4 threads by issuing
163  \begin{shellCode}  \begin{shellCode}
164  export ESCRIPT_NUM_THREADS=4  export ESCRIPT_NUM_THREADS=4
165  scons all_tests  scons all_tests
166  \end{shellCode}  \end{shellCode}
167    
168  \subsection{Compilation with MPI}  \subsection{Compilation with \mpi}
169  You will need to have MPI installed on your system.  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.  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.  You will need to modify the following variables in your options file.
172  \begin{itemize}  \begin{itemize}
173  \item \texttt{mpi_flavour} \\   \item \texttt{mpi_flavour} \\
174      which MPI implementation is used. Valid values are  \begin{itemize}      which \mpi implementation is used. Valid values are
175      \item[\texttt{MPT}] SGI MPI implementation    \\     \url{http://techpubs.sgi.com/library/manuals/3000/007-3687-010/pdf/007-3687-010.pdf}      \begin{itemize}
176       \item[\texttt{MPICH2}] Argonne's MPICH vesrion 2 implementation \\ \url{http://www.mcs.anl.gov/research/projects/mpi/mpich2/}          \item[\texttt{MPT}] SGI MPI implementation \\
177       \item[\texttt{MPICH}] Argonne's MPICH implementation \\ \url{http://www.mcs.anl.gov/research/projects/mpi/mpich1/}              \url{http://techpubs.sgi.com/library/manuals/3000/007-3687-010/pdf/007-3687-010.pdf}
178        \item[\texttt{OPENMPI}] Open MPI \url{http://www.open-mpi.org/}          \item[\texttt{MPICH2}] Argonne's MPICH version 2 implementation \\
179        \item[\texttt{INTELMPI}] Intel's MPI \url{http://software.intel.com/en-us/intel-mpi-library/}              \url{http://www.mcs.anl.gov/research/projects/mpi/mpich2/}
180     \end{itemize}          \item[\texttt{MPICH}] Argonne's MPICH implementation \\
181                \url{http://www.mcs.anl.gov/research/projects/mpi/mpich1/}
182            \item[\texttt{OPENMPI}] Open MPI \\
183                \url{http://www.open-mpi.org/}
184            \item[\texttt{INTELMPI}] Intel's MPI \\
185                \url{http://software.intel.com/en-us/intel-mpi-library/}
186        \end{itemize}
187   \item \texttt{mpi_path} \\   \item \texttt{mpi_path} \\
188      where to find \filename{mpi.h}      where to find \filename{mpi.h}
189  \item \texttt{mpi_lib_path} \\   \item \texttt{mpi_lib_path} \\
190      where to find libraries for mpi      where to find libraries for \mpi
191  \item \texttt{mpi_libs} \\   \item \texttt{mpi_libs} \\
192      which libraries to link to.      which libraries to link to.
193  \end{itemize}  \end{itemize}
194    
# Line 193  Then compile with: Line 199  Then compile with:
199    
200  As with debug and openmp, you can make this a more permanent setting by modifying your options file.  As with debug and openmp, you can make this a more permanent setting by modifying your options file.
201    
202  You can test your build on for instance 6 processors using  To test your build using 6 processors enter:
203  \begin{shellCode}  \begin{shellCode}
204  export ESCRIPT_NUM_NODES=6  export ESCRIPT_NUM_NODES=6
205  scons usempi=yes all_tests  scons usempi=yes all_tests
206  \end{shellCode}  \end{shellCode}
207  and on  6 processors with 4 threads each using  and on 6 processors with 4 threads each using
208  \begin{shellCode}  \begin{shellCode}
209  export ESCRIPT_NUM_THREADS=4  export ESCRIPT_NUM_THREADS=4
210  export ESCRIPT_NUM_NODES=6  export ESCRIPT_NUM_NODES=6
# Line 210  export ESCRIPT_NUM_THREADS=4 Line 216  export ESCRIPT_NUM_THREADS=4
216  export ESCRIPT_HOSTFILE=myhostfile  export ESCRIPT_HOSTFILE=myhostfile
217  scons usempi=yes all_tests  scons usempi=yes all_tests
218  \end{shellCode}  \end{shellCode}
219  Notice that depending on your MPI flavour it may be required to start a daemon before running the tests under MPI.  Note that depending on your \mpi flavour it may be required to start a daemon before running the tests under \mpi.
220    
221    
222  \subsection{Difficulties}  \subsection{Difficulties}
223    
224  %This is copied from Ken's notes on teh old Twiki page  %This is copied from Ken's notes on the old Twiki page
225  \subsubsection{``Bad magic number''}  \subsubsection{``Bad magic number''}
226  Some reasons for this error message include:  Some reasons for this error message include:
227  \begin{itemize}  \begin{itemize}
228   \item Using different versions of python when installing and running escript (Use \texttt{which python} and \texttt{python --version} to check)   \item Using different versions of python when installing and running escript (Use \texttt{which python} and \texttt{python --version} to check)
229  \item Using different versions of libraries (Make sure \texttt{LD_LIBRARY_PATH} has \filename{/trunk/lib} listed first)  \item Using different versions of libraries (Make sure \texttt{LD_LIBRARY_PATH} has \filename{x/lib} listed first, where x is the escript install path)
230  \item Using different versions of python modules (Make sure \texttt{PYTHONPATH} has \filename{/trunk/escript} directory listed first)  \item Using different versions of python modules (Make sure \texttt{PYTHONPATH} has \filename{/trunk/escript} directory listed first)
231  \end{itemize}  \end{itemize}
232    
233  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}.  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}.
234    
235  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.  It is also possible that incompatible libraries were used when compiling \esfinley.
236    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.
237    Another case is when Boost or Numarray was compiled against the wrong Python library.
238    To avoid these problems both builder and user must ensure they are using the same python libraries.
239    
240  \subsubsection{OpenMP builds segfault running examples}  \subsubsection{\openmp builds segfault running examples}
241    
242  One known cause for this is linking the \filename{gomp} library with escript built using gcc 4.3.3.  One known cause for this is linking the \filename{gomp} library with escript built using gcc 4.3.3.
 While you need the -fomp switch you should not need to link \filename{gomp}.  
243    While you need the \texttt{-fopenmp} switch you should not need to link \filename{gomp}.
244    

Legend:
Removed from v.2535  
changed lines
  Added in v.2536

  ViewVC Help
Powered by ViewVC 1.1.26