install.tex 14 KB
 Klaus Mosthaf committed Oct 13, 2010 1 2 \section{Installation of \Dumux} \label{install} \subsection{Preliminary remarks}  Klaus Mosthaf committed Oct 12, 2010 3   Klaus Mosthaf committed Oct 28, 2010 4 5 6 7 8 In this section about the installation of \Dumux it is assumed that you work on a UNIX compatible operating system and that you are familiar with the use of a shell. Moreover, you should know, if necessary, how to install new software packages or you should have a person aside which can give you assistance with the shell and the package installation. At the end of this chapter, we list some basic prerequisites for running \Dune and \Dumux. Please check this paragraph to evaluate whether it is possible for you to run \Dune and \Dumux. Moreover, some optional libraries and modules are listed, which can be helpful for the work with \Dumux.  Klaus Mosthaf committed Oct 12, 2010 9   Klaus Mosthaf committed Oct 28, 2010 10 11 12 13 In a technical sense \Dumux is a module of \Dune. The installation procedure of \Dumux is strongly related to that of \Dune. Thus, for details of the installation please check also the {\Dune} website \cite{DUNE-HP}. If you are interested in more details of the build-system we refer to the {\Dune}-Build-System-Howto \cite{DUNE-HP}.  Klaus Mosthaf committed Oct 12, 2010 14   Klaus Mosthaf committed Oct 28, 2010 15 16 As in a \Dune installation, all \Dune modules including \Dumux should be extracted into a common directory named {\Dune}-ROOT. Each \Dune module is associated with a directory name in the folder {\Dune}-ROOT. For convenience, this directory name is also used as an alias for the module name, a practice we will follow here, too. After installing source code for all required \Dune modules including the \Dumux parts, \Dune is being built by the shell-command \texttt{dunecontrol} which is part of the {\Dune}-Build-System. The {\Dune}-Build-System is essentially a front-end of the gnu tool \texttt{autoconf} which was specialized for the \Dune project.  Klaus Mosthaf committed Oct 12, 2010 17   Klaus Mosthaf committed Oct 13, 2010 18 \paragraph{Basic prerequisites} \label{prerequisites}  Philipp Nuske committed Jan 05, 2011 19 The gnu tool-chain of \texttt{g++} and related gnu variants of autotools (ubuntu: autoconf, automake, libtool, build-essential) must be available in a recent version.  Klaus Mosthaf committed Oct 28, 2010 20 The \Dumux property system, which is used in most of the models, makes use of \texttt{libboost}.  Philipp Nuske committed Jan 05, 2011 21 It is thus necessary to install a \texttt{boost} version $\geqslant 1.33.1$ (ubuntu: libboost*, libboost-dev).  Klaus Mosthaf committed Oct 28, 2010 22 23 The building of the documentation requires \LaTeX\ and auxiliary tools like \texttt{dvipdf} and \texttt{bibtex}. If you use the configuration switch \texttt{--enable-doxygen} in order to generate the doxygen files (documentation generator) you will also need \texttt{doxygen}.  David Werner committed Oct 25, 2010 24   Klaus Mosthaf committed Oct 28, 2010 25 26 Depending on the usage of external libraries the required software packages may vary. Beside the section on external modules below it is a good idea to check the {\Dune}-Wiki \cite{DUNE-HP} for information about the external packages.  Klaus Mosthaf committed Oct 12, 2010 27 28  \subsection{Obtaining \Dune and \Dumux}  Klaus Mosthaf committed Oct 28, 2010 29 Two possibilities exist to obtain \Dune and \Dumux.  Philipp Nuske committed Dec 10, 2010 30 They can be obtained as so-called tarballs, i.e. \Dumux and \Dune code files of a certain version are packed into tar-archive files for download from the respective {\Dune} and {\Dumux} website.  Klaus Mosthaf committed Oct 28, 2010 31 The shell command \texttt{tar} can be used to extract them on your file system. This is explained in the next paragraph.  Klaus Mosthaf committed Oct 12, 2010 32 33  \paragraph{Obtaining the software by installing tarballs}  Philipp Nuske committed Jan 03, 2011 34 Download the tarballs from the respective websites. You can install the obtained tarballs as follows: Create a {\Dune}-ROOT-directory, which we call here DUMUX.  Klaus Mosthaf committed Oct 28, 2010 35 For the installation in the shell, type the following commands:  Klaus Mosthaf committed Oct 12, 2010 36 37 38 39 40 41 42 43 44 45 \begin{itemize} \item \texttt{mkdir DUMUX} \item \texttt{cd DUMUX} \item \texttt{tar xzvf path\_to\_tarball\_of/pde-lab.tar.gz} \item \texttt{tar xzvf path\_to\_tarball\_of/dumux.tar.gz} \item \texttt{tar xzvf path\_to\_tarball\_of ...} \item \texttt{...} \end{itemize} \paragraph{Obtaining \Dune and \Dumux from the SVN repositories}  Klaus Mosthaf committed Oct 28, 2010 46 47 48 49 50 The other possibility is to directly access the project archives of \Dune and \Dumux, the so-called software repositories. These are archives of a software version control system named \texttt{apache subversion}. From here on this is referred to as subversion. You need a subversion client, with which you can access the repositories. This comes with a usual UNIX distribution or can be installed. Our description is limited to a standard subversion shell client realized by the shell command \texttt{svn}.  Bernd Flemisch committed Jul 16, 2010 51 52  \paragraph{Checkout of the core modules}  Klaus Mosthaf committed Oct 13, 2010 53 54 From version 2.0 of \Dune on, it was decided to stick to stable \Dune releases, comprising the core modules \texttt{dune-common}, \texttt{dune-grid}, \texttt{dune-istl}, \texttt{dune-localfunctions} and the external \texttt{dune-pdelab}.  Klaus Mosthaf committed Oct 28, 2010 55 56 57 58 First, create a directory (here, we call it DUMUX) where all the \Dune and \Dumux modules will be stored in. Then, enter the previously created folder and checkout the modules. Checkout means that you get a working copy of the code from the software repository. The checkout has to be performed as described on the \Dune web page, \cite{DUNE-HP}. For the installation in the shell, type the following commands:  Bernd Flemisch committed Jul 16, 2010 59 \begin{itemize}  Klaus Mosthaf committed Oct 12, 2010 60 61 \item \texttt{mkdir DUMUX} \item \texttt{cd DUMUX}  Benjamin Faigle committed Jul 28, 2010 62 63 64 65 66 \item \texttt{svn checkout https://svn.dune-project.org/svn/dune-common/releases/2.0 dune-common} \item \texttt{svn checkout https://svn.dune-project.org/svn/dune-grid/releases/2.0 dune-grid} \item \texttt{svn checkout https://svn.dune-project.org/svn/dune-istl/releases/2.0 dune-istl} \item \texttt{svn checkout https://svn.dune-project.org/svn/dune-localfunctions/releases/2.0 dune-localfunctions} \item \texttt{svn checkout https://svn.dune-project.org/svn/dune-pdelab/branches/2.0snapshot dune-pdelab}  Bernd Flemisch committed Jul 16, 2010 67 68 \end{itemize}  Klaus Mosthaf committed Oct 12, 2010 69 70 Additionally, it is highly recommended that you also checkout the \texttt{dune-grid} HOWTO by \begin{itemize}  Klaus Mosthaf committed Oct 28, 2010 71 72 \item \texttt{svn checkout \\ \hspace{4cm} https://svn.dune-project.org/svn/dune-grid-howto/releases/2.0 dune-grid-howto}  Klaus Mosthaf committed Oct 12, 2010 73 \end{itemize}  Klaus Mosthaf committed Oct 28, 2010 74 and work yourself through that tutorial in order to get an understanding of the \Dune grid interface.  Klaus Mosthaf committed Oct 08, 2010 75   Klaus Mosthaf committed Oct 12, 2010 76 \paragraph{Checkout of \Dumux}  Klaus Mosthaf committed Oct 08, 2010 77   Philipp Nuske committed Jan 03, 2011 78 In order to obtain an anonymous read-only copy of the \emph{stable} part of \Dumux from the repository, the most simple way is to type  Bernd Flemisch committed Jul 16, 2010 79 \begin{itemize}  Klaus Mosthaf committed Oct 28, 2010 80 81 \item \texttt{svn checkout --username=anonymous --password=''\\ \hspace{4cm} svn://svn.iws.uni-stuttgart.de/DUMUX/dumux/trunk dumux}  Klaus Mosthaf committed Oct 12, 2010 82 83 \end{itemize}  Klaus Mosthaf committed Oct 28, 2010 84 85 If you also want to commit new developments to the repositories, you can ask the \Dumux project leader to get either full developers access or access for certain parts of \Dumux. The developer part \texttt{dumux-devel} is only available for people who belong to the \Dumux developer group and have non-anonymous access to the subversion repositories.  Philipp Nuske committed Dec 10, 2010 86 If you have developer rights the checkout looks as follows (system administrators will have to add you to the developer group and give you a password for this access):  David Werner committed Oct 11, 2010 87 \begin{itemize}  Klaus Mosthaf committed Oct 12, 2010 88 89 90 91  \item \texttt{svn checkout --username=yourusername \\ \hspace{4cm} svn://svn.iws.uni-stuttgart.de/DUMUX/dumux/trunk dumux} \item \texttt{svn checkout --username=yourusername \\ \hspace{4cm} svn://svn.iws.uni-stuttgart.de/DUMUX/dune-mux/trunk dumux-devel}  Bernd Flemisch committed Jul 16, 2010 92 \end{itemize}  Klaus Mosthaf committed Oct 28, 2010 93 94 95 96 \texttt{dumux-devel} is based on the stable part of \texttt{dumux} and hence it has to be also checked out. You can omit the username option, if your username for the repository access is identical to the one for your system account. Please choose either not to store the password or to store it by subversion in a secure way (check the documentation of subversion for that). A leaked out password can be used by evil persons to vandalize a software repository.  Klaus Mosthaf committed Oct 12, 2010 97   Philipp Nuske committed Jan 03, 2011 98 When using subversion it is possible, provided that to you are granted developer access and have write permissions to repositories, to feed back your own code or code modifications to the software repositories.  Klaus Mosthaf committed Oct 28, 2010 99 Moreover, with direct access to the repositories it is easier to keep up with code changes, to receive important bug fixes and to keep up with general developments of code.  Klaus Mosthaf committed Oct 08, 2010 100   Klaus Mosthaf committed Oct 28, 2010 101 \paragraph{External libraries and modules}  David Werner committed Oct 25, 2010 102   Klaus Mosthaf committed Oct 28, 2010 103 104 The following libraries provide additional functionality but are not required to run \Dumux. If you are going to use an external library check the information provided on the \Dune website.  David Werner committed Oct 25, 2010 105   Philipp Nuske committed Sep 27, 2010 106 \begin{itemize}  Klaus Mosthaf committed Oct 27, 2010 107 \item \textbf{UG}: UG is a toolbox for Unstructured Grids: As \Dumux, it is build by \texttt{autotools} and a C++-compiler. Additionally, the tools \texttt{lex}/\texttt{yacc} or the gnu-versions \texttt{flex}/\texttt{bison} are needed.  Philipp Nuske committed Sep 27, 2010 108   Philipp Nuske committed Jan 05, 2011 109 \item \textbf{Alberta}: Adaptive multi Level finite element toolbox using Bisectioning refinement and Error control by Residual Techniques for scientific Applications: A Fortran compiler like \texttt{gfortran} is required.  Philipp Nuske committed Sep 27, 2010 110   Klaus Mosthaf committed Oct 28, 2010 111 \item \textbf{ALUGrid}: ALUGrid is build by a C++-compiler like \texttt{g++}. If you want to build a parallel version, you will need \texttt{MPI}. It was successfully run with \texttt{openmpi}. The parallel version needs also a graph partitioner, such as \texttt{METIS} or \texttt{PARTY}. It was run successfully in combination with \Dune using \texttt{METIS}.  Philipp Nuske committed Sep 27, 2010 112   Philipp Nuske committed Jan 05, 2011 113 \item \textbf{PARDISO}: The package PARDISO is a thread-safe, high-performance, robust, memory efficient and easy to use software for solving large sparse symmetric and asymmetric linear systems of equations on shared memory multiprocessors. The precompiled binary can be downloaded after personal registration from the PARDISO website (\texttt{\url{http://www.pardiso-project.org}}).  Philipp Nuske committed Sep 27, 2010 114   Klaus Mosthaf committed Oct 28, 2010 115 \item \textbf{SuperLU}: SuperLU is a general purpose library for the direct solution of large, sparse, nonsymmetric systems of linear equations (\texttt{\url{http://crd.lbl.gov/~xiaoye/SuperLU}}).  Philipp Nuske committed Sep 27, 2010 116   Klaus Mosthaf committed Oct 28, 2010 117 118 \item \textbf{\Dune-multidomaingrid}: If you going to run on the same grid different domains or subdomains, this can be the package of choice. To be precise, this is not only an external library but an external \Dune module which, like \Dumux, is built by the \Dune build system. The \Dune-multidomaingrid module provides a meta grid that allows the subdivison of arbitrary \Dune grids into subdomains, e.g. for multi-physics approaches (\texttt{\url{http://gitorious.org/dune-multidomaingrid}}).  David Werner committed Oct 25, 2010 119 120 \end{itemize}  Klaus Mosthaf committed Oct 28, 2010 121 The following are dependencies of some of the used libraries. You will need them depending on which modules of \Dune and which external libraries you use.  David Werner committed Oct 25, 2010 122 \begin{itemize}  Klaus Mosthaf committed Oct 28, 2010 123 \item \textbf{MPI}: The parallel version of \Dune and also some of the external dependencies need MPI when they are going to be built for parallel computing. \texttt{Openmpi} and \texttt{MPICH} in a recent version have been reported to work.  Philipp Nuske committed Sep 27, 2010 124   Klaus Mosthaf committed Oct 28, 2010 125 \item \textbf{lex/yacc} or \textbf{flex/bison}: These are quite common developing tools, code generators for lexical analyzers and parsers. This is a prerequisite for UG.  Philipp Nuske committed Sep 27, 2010 126   Klaus Mosthaf committed Oct 28, 2010 127 \item \textbf{BLAS}: Alberta makes use of BLAS. Thus install libGOTO, ATLAS, non-optimized BLAS or BLAS by chipmanufacturer. Take care that the installation scripts select the intended version of BLAS.  Philipp Nuske committed Oct 18, 2010 128   Klaus Mosthaf committed Oct 28, 2010 129 \item \textbf{METIS}: This is a dependency of ALUGrid. If you run it parallel this part is being used to partition your grid.  David Werner committed Oct 25, 2010 130   Klaus Mosthaf committed Oct 28, 2010 131 \item \textbf{libGOTO}: is an optimized version of BLAS. It is not always available for all architectures and  Klaus Mosthaf committed Oct 28, 2010 132 133 the license is not open. For research and education it is possible to obtain a copy without additional costs. A Fortran compiler like \texttt{gfortran} is needed to compile it.  David Werner committed Oct 25, 2010 134   Philipp Nuske committed Jan 05, 2011 135 \item \textbf{\LaTeX, doxygen}: In order to build the \Dumux documentation these tools are needed.  Klaus Mosthaf committed Oct 28, 2010 136 \LaTeX\ is a front-end to the \TeX\ font setting system. Install texlive for example. A great part of the code documentation is done inline using doxygen, which extracts the documentation and makes HTML or \LaTeX\ out of that.  David Werner committed Oct 25, 2010 137   Klaus Mosthaf committed Oct 28, 2010 138 139 140 \item \textbf{Compilers}: We recommend to use the gnu compiler suite, i.e. \texttt{gcc}/\texttt{g++}/\texttt{gfortran} version 4.4 or 4.5. It is also reported that \Dune was successfully build with the Intel C++ compiler. \Dune is build by a C++ compiler. The C and Fortran compiler is only needed for a few external libraries.  David Werner committed Oct 25, 2010 141   Klaus Mosthaf committed Oct 28, 2010 142 \item \textbf{libgomp}: \Dune can make use of OpenMP. Thus it can be necessary to install the \texttt{libgomp} library.  David Werner committed Oct 25, 2010 143 144 % http://openmp.org/  Klaus Mosthaf committed Oct 28, 2010 145 \item \textbf{libgmp}: The Gnu Multiple Precision Arithmetic Library (GMP) is also a prerequisite for \Dune. It may be necessary to install it.  David Werner committed Oct 25, 2010 146 % http://gmplib.org/  David Werner committed Oct 25, 2010 147 \end{itemize}  Klaus Mosthaf committed Oct 21, 2010 148   Klaus Mosthaf committed Oct 27, 2010 149 \paragraph{Hint for IWS Users} Users from the Institute of Hydraulic Engineering, University of Stuttgart,  Klaus Mosthaf committed Oct 28, 2010 150 can also checkout a svn repository with several external libraries: \\  151   Philipp Nuske committed Jan 03, 2011 152 \texttt{svn checkout svn://svn.iws.uni-stuttgart.de/DUMUX/external/trunk external}\\  153   Klaus Mosthaf committed Oct 27, 2010 154 This directory \texttt{external} contains a script to install external libraries, such as  Klaus Mosthaf committed Oct 28, 2010 155 \texttt{alberta}, \texttt{alu}, \texttt{ug}. It also contains METIS and the BLAS version of libGOTO2:  156 157 158 \begin{center} \texttt{./installExternal.sh all} \end{center}  Klaus Mosthaf committed Oct 28, 2010 159 it is also possible to install only certain parts of the external libraries:  160 161 162 163 \begin{center} \texttt{./installExternal.sh alberta} \end{center}  Klaus Mosthaf committed Oct 28, 2010 164 165 The libraries are then build within the external-directory and are not installed in a different place. But a \Dune build still needs to know where they are. You have to refer to them as options for the \Dune build, for example in your options file \texttt{debug.opts}.  166   Bernd Flemisch committed Jul 16, 2010 167   Klaus Mosthaf committed Oct 08, 2010 168 \paragraph{Build \Dune and \Dumux}  Philipp Nuske committed Sep 23, 2010 169 \label{buildIt}  Philipp Nuske committed Jan 03, 2011 170 To compile \Dumux without additional options file, type in the {\Dune}-ROOT-directory (called \texttt{DUMUX} before):  Klaus Mosthaf committed Oct 28, 2010 171 172 173 174 \begin{center} \texttt{./dune-common/bin/dunecontrol all} \end{center}  Klaus Mosthaf committed Oct 08, 2010 175 If you want to compile in the debugging mode, type in the folder \texttt{DUMUX}:  Bernd Flemisch committed Jul 16, 2010 176 177 178 \begin{center} \texttt{./dune-common/bin/dunecontrol --opts=\$DUMUX\_ROOT/debug.opts all} \end{center}  Klaus Mosthaf committed Oct 08, 2010 179 180 181 182 183 184 185  Otherwise you can type \begin{center} \texttt{./dune-common/bin/dunecontrol --opts=\$DUMUX\_ROOT/optim.opts all} \end{center} in order to get an optimized compilation (better performance, but no possibility to use a debugger).  Klaus Mosthaf committed Oct 28, 2010 186 187 188 189 This uses the \Dune build-system. If it does not work, please have a look at the file \texttt{INSTALL} in the \Dumux root directory (if you use SVN, this \texttt{\\$DUMUX\_ROOT} is usually \texttt{dumux}, if you use a released version it is usually \texttt{dumux-VERSION}). You can also find more information in the \Dune Buildsystem HOWTO located at the \Dune web page, \cite{DUNE-HP}. Alternatively, the tool CMake can be used to build \Dumux. Please check the file \texttt{INSTALL.cmake} for details.