install.tex 19.7 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   David Werner committed Jan 14, 2011 4 5 In this section about the installation of \Dumux it is assumed that you work on a UNIX or Linux compatible operating system and that you are familiar with the use of a shell. You should also know 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.  Philipp Nuske committed Jan 12, 2011 6 Below, we list some basic prerequisites for running \Dune and \Dumux.  Klaus Mosthaf committed Oct 28, 2010 7 Please check this paragraph to evaluate whether it is possible for you to run \Dune and \Dumux.  David Werner committed Jan 14, 2011 8 In addition 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 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}.  David Werner committed Jan 14, 2011 13 If you are interested in more details of the buildsystem we refer to the {\Dune} Build System Howto \cite{DUNE-BS}.\\  Klaus Mosthaf committed Oct 12, 2010 14   David Werner committed Jan 14, 2011 15 As in a \Dune installation, all \Dune modules including \Dumux should be extracted into a common directory. We refer to that directory for purpose of documentation abstactly as {\Dune} root directory or shortly as {\Dune}-Root, but in real life the user is free to choose any valid directory name for his instance of {\Dune} root direcory.\\  David Werner committed Jan 13, 2011 16   David Werner committed Jan 14, 2011 17 18 Source code files for each \Dune module are contained in subdirectory of {\Dune}-Root which exactly is itself associated with module. We name that subdirectory of a certain module, modules root directory", or module-root-directory, e.g. for module dumux the name are dumux' root directory" respective dumux-root-directory". The real directory names can be choosen abitrary, in this manual they are the same as the module name or the module name extended by an version number suffix. The name of a module is always defined via the content of file \texttt{dune.module} in its root directory, and should not get changed by an user. Note that it also possible to have subdirectories in \Dune-Root which contain no module.\\  David Werner committed Jan 13, 2011 19   David Werner committed Jan 14, 2011 20 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.  David Werner committed Jan 13, 2011 21   David Werner committed Jan 14, 2011 22 23 24 \paragraph{Basic prerequisites} \label{prerequisites} The gnu tool-chain of \texttt{g++} and related gnu variants of autotools (\texttt{autoconf}, \texttt{automake}, \texttt{libtool}) must be available in a recent version. E.g. for ubuntu linux these are contained in packages \texttt{autoconf}, \texttt{automake}, \texttt{libtool} and \texttt{build-essential}.  David Werner committed Jan 13, 2011 25   David Werner committed Jan 14, 2011 26 27 28 % The \Dumux property system makes use of library \texttt{boost} of version $\geqslant$ 1.33.1. It is thus necessary to install developer package of \texttt{boost} or sometimes named \texttt{libboost}, the matching ubuntu linux package is \texttt{libboost-dev}. \\  Klaus Mosthaf committed Oct 12, 2010 29   Klaus Mosthaf committed Oct 28, 2010 30 The building of the documentation requires \LaTeX\ and auxiliary tools like \texttt{dvipdf} and \texttt{bibtex}.  David Werner committed Jan 14, 2011 31 If you use the configuration switch \texttt{--enable-doxygen} in your options or option-file (see below) in order to extract inline documentation from source code files you will also need \texttt{doxygen}.\\  David Werner committed Oct 25, 2010 32   Klaus Mosthaf committed Oct 28, 2010 33 Depending on the usage of external libraries the required software packages may vary.  David Werner committed Jan 14, 2011 34 Beside the section on external modules below it is a good idea to check the {\Dune}-Wiki \cite{DUNE-MAIN-WIKI} for information about the external packages.  Klaus Mosthaf committed Oct 12, 2010 35   David Werner committed Jan 13, 2011 36 \subsection{Obtaining source code for \Dune and \Dumux}  David Werner committed Jan 14, 2011 37 38 From version 2.0 of \Dune on, it was decided to develop \Dumux based on \Dune releases, comprising the core modules \texttt{dune-common}, \texttt{dune-grid}, \texttt{dune-istl}, \texttt{dune-localfunctions} and the external dune module \texttt{dune-pdelab}. Thus for a \Dumux installation these modules are required to be installed. Of course the external dune module \texttt{dumux} from \Dumux website ist required too. Using further (external) \Dune modules and/or external \Dune libraries can be necessary, if you are going to use more than basic features of \Dune or \Dumux. To some of these we only refer briefly in end of this chapter.\\  David Werner committed Jan 13, 2011 39 40 41 42 43 44  Two possibilities exist to get source code for \Dune and \Dumux. Firstly \Dune and \Dumux can obtained as tar-archive files by download from respective {\Dune} and {\Dumux} website. They then need to be extracted, as described in the next section. Secondly, described in the section next but one, is a method to obtain most recent source or even also every predecessors by direct access via internet to software repositories of software revision control system of the software developer. \Dune and \Dumux use for their software repositories \texttt{apache subversion} or more shortly \texttt{subversion} or \texttt{svn}. As a user does not always want the most recent version certain version tags (i.e. special names) and version numbers and even software branches are means of software revision control system to provide different versions of a software from a software repository.  Klaus Mosthaf committed Oct 12, 2010 45   David Werner committed Jan 13, 2011 46 \paragraph{Obtaining the software by installing tar-files}  David Werner committed Jan 13, 2011 47 The a bit old fashioned named tape-archive-file shortly named tar-file or tarball is a common file format for distributing collections of files contained in these archives.  David Werner committed Jan 13, 2011 48 49 This part of installation is done as follows: Download the tarballs from the respective \Dune (version 2.0) and \Dumux websites to a certain path in your filesystem.  David Werner committed Jan 14, 2011 50 51 Create the {\Dune} root directory, named here DUMUX, then extract content of tar-files by commandline program tar into it. Above, except download, it can achieved by the following shell commands, replace in them \texttt{path\_to\_tarball} with the direcory pathname where the downloaded files are located.  David Werner committed Jan 14, 2011 52 53 54 55 56 57 58 59 60 61 62  \begin{lstlisting}[style=Bash] $mkdir DUMUX$ cd DUMUX $tar xzvf path_to_tarball_of/dune-common-2.0.tar.gz$ tar xzvf path_to_tarball_of/dune-grid-2.0.tar.gz $tar xzvf path_to_tarball_of/dune-istl-2.0.tar.gz$ tar xzvf path_to_tarball_of/dune-localfunctions-2.0.tar.gz $tar xzvf path_to_tarball_of/dumux-2.0.tar.gz \end{lstlisting}  David Werner committed Jan 14, 2011 63 To rephrase above remark about modules root directory, here dumux-root-directory name which came after extracting the tarfile is \texttt{dumux-2.0}.  David Werner committed Jan 14, 2011 64   David Werner committed Jan 13, 2011 65 Optional:  David Werner committed Jan 14, 2011 66 67 68 69 70 71 72 73 \begin{lstlisting}[style=Bash]$ tar xzvf path_to_tarball_of/dune-grid-howto-2.0.tar.gz \end{lstlisting} However, the required \Dune-module \texttt{dune-pdelab} is not available as tar-file, thus you have to install it from software repository by the second method. Thus if svn command is available, it can done as follows: \begin{lstlisting}[style=Bash] $svn co https://svn.dune-project.org/svn/dune-pdelab/branches/2.0snapshot dune-pdelab \end{lstlisting}  Klaus Mosthaf committed Oct 12, 2010 74   David Werner committed Jan 13, 2011 75 76 77 78 \paragraph{Obtaining \Dune and \Dumux from software repositories} Using a software revision control system as subversion and its software repositories has beside it advantages for developer or developing groups as a tool for assisting them to keep the source code worked on in consistent fashion for an user, i.e. a member who is not in the developing group of a software project, of software also some advantages. In general With direct access to the software repositories it is easier to keep up with code changes, to receive important bug fixes and to keep up with general developments of code.  Bernd Flemisch committed Jul 16, 2010 79   David Werner committed Jan 13, 2011 80 81 82 To access apache subversion software repositories a certain program is needed which is referred here shortly as \texttt{subversion client} or \texttt{svn client}. We use in our description the svn client of the apache subversion software itself, which is a commandline (shell) tool, mostly named \texttt{svn}. Apache subversion client is available for most Linux and UNIX distributions as software package by the distributor or can get installed by building it directly from source.  David Werner committed Jan 14, 2011 83 In technical speach of apache subversion checking out a certain software version" means nothing more then fetching  David Werner committed Jan 13, 2011 84 85 it from software repository and laying it out in the filesystem, additionally with software some files with metainformation regarding the software revision control system itself are also laid out. For a developer in \Dumux project it is easily possible to do the opposite i.e. uploading a modified version he created into software repository. This is usually termed as software check in".  David Werner committed Jan 13, 2011 86 87  The installation procedure is as follows:  David Werner committed Jan 14, 2011 88 Create {\Dune} root directory, named here below DUMUX.  David Werner committed Jan 13, 2011 89 90 91 92 Then, enter the previously created directory and checkout the modules. As you see below the checkout uses two different servers for sources one for \Dune and one for \Dumux, also the anonymous access to these repositories varies a little bit.  David Werner committed Jan 14, 2011 93 94 95 96 97 98 99 100 101 102 103 As described on \Dune's website, \cite{DUNE-DOWNLOAD-SVN}, we first do a checkout of some \Dune modules: \begin{lstlisting}[style=Bash]$ mkdir DUMUX} $cd DUMUX}$ svn co https://svn.dune-project.org/svn/dune-common/releases/2.0 dune-common $svn co https://svn.dune-project.org/svn/dune-grid/releases/2.0 dune-grid$ svn co https://svn.dune-project.org/svn/dune-istl/releases/2.0 dune-istl $svn co https://svn.dune-project.org/svn/dune-localfunctions/releases/2.0 dune-localfunctions$ svn co https://svn.dune-project.org/svn/dune-pdelab/branches/2.0snapshot dune-pdelab \end{lstlisting}  Bernd Flemisch committed Jul 16, 2010 104   David Werner committed Jan 14, 2011 105 106 The \texttt{dune-grid-howto} is a tutorial which aims to give an understanding of the \Dune grid interface, which can give you an idea how abstractions in \Dune are done. \texttt{Dune-grid-howto} is not required by \Dumux, thus installing is purely optional. It is done by:  David Werner committed Jan 14, 2011 107 108 109 110  \begin{lstlisting}[style=Bash] $svn co https://svn.dune-project.org/svn/dune-grid-howto/releases/2.0 dune-grid-howto \end{lstlisting}  Klaus Mosthaf committed Oct 08, 2010 111   David Werner committed Jan 14, 2011 112 113 To obtain the needed \texttt{dumux} module, which is is as mentioned before, just an external module of \Dune. You have to check it out which is as also described on \Dumux website, \cite{DUMUX-HP}. Its filetree should laid out as for any other \Dune module directly into \Dune-Root. This is done if you are in it and execute the following command within \Dune root directory.  David Werner committed Jan 13, 2011 114   David Werner committed Jan 14, 2011 115 116 117 \begin{lstlisting}[style=Bash]$ svn co --username=anonymous --password='' svn://svn.iws.uni-stuttgart.de/DUMUX/dumux/trunk dumux \end{lstlisting}  Klaus Mosthaf committed Oct 12, 2010 118   David Werner committed Jan 13, 2011 119 120 \paragraph{Hints for \Dumux-Developers} If you also want to check in your own \Dumux developments to \Dumux software repositories, you can apply for either full developers access or access for developer access on certain parts of \Dumux. Granted developer access means that you are allowed to check in own code to the software repository and that you can access the \texttt{dumux-devel} module which enhances \texttt{dumux} by staging code of developer group, which is unavailable for user not being member of the developer group.  David Werner committed Jan 14, 2011 121 If you are member of developer group rights the checkout with developer access for \texttt{dumux} and \texttt{dumux-devel} is non-anonymously done with the commands below, insert your username  David Werner committed Jan 14, 2011 122 123 124 125 126 127 128 for accessing \Dumux software repository in place \texttt{joeuser} below. \begin{lstlisting}[style=Bash] $svn co --username=joeuser svn://svn.iws.uni-stuttgart.de/DUMUX/dumux/trunk dumux$ svn co --username=joeuser svn://svn.iws.uni-stuttgart.de/DUMUX/dune-mux/trunk dumux-devel \end{lstlisting}  David Werner committed Jan 14, 2011 129 This time the name for dumux root directory is just as the name of the module \texttt{dumux}.  David Werner committed Jan 14, 2011 130   David Werner committed Jan 13, 2011 131 132 \texttt{Dumux-devel} itself makes use of stable part \texttt{dumux} and hence it needs also being checked out. You can omit in commands above the username option, if your username for the repository access is identical to the one for your system account.  Klaus Mosthaf committed Oct 28, 2010 133 134 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 135   David Werner committed Jan 14, 2011 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 \subsection{Build of \Dune and \Dumux} \label{buildIt} Building of \Dune is done by \texttt{dunecontrol} as descibed in \Dune Installation Notes, \cite{DUNE-INST}, and in much more comprehensive form in \Dune Build System Howto, \cite{DUNE-BS}. If something fails with \texttt{dunecontrol} feel to report it to \Dune or \Dumux developer or mailing list, but also try to report also error details. People will likely help you. It is possible to compile \Dumux with nearly no explicit options to the buildsystem but experience showed that the code quality through all parts of \Dune is not yet high enough to give the compiler full freedom for allowing certain kind optimizations. As option switches for optimization can switched on in parts buildsystem for code be default, it is safer to pass the option \texttt{-fno-strict-aliasing} to the C++-compiler, \cite{WIKIPED-ALIASING}, which is done here via a commandline argument to \texttt{dune-control}. \begin{lstlisting}[style=Bash] $./dune-common/bin/dunecontrol --configure-opts="CXXFLAGS=-fno-strict-aliasing" all \end{lstlisting} Too many options can make life hard, thats why one usually uses option-files for dune-control and its subtools. Larger sets of options are kept in them. If you are going to compile with options suited for code debugging with a debugger, the following can be a starting point: Insert below for \verb+$DUMUX_ROOT+ in shell-commandline just the name of dumux' (or dumux-devels) root directory, which is in case of installation from tarfiles \texttt{dumux-2.0} or in case of installation from svn just \texttt{dumux} (or if one takes a version of option-file from module \texttt{dumux-devel} available only to members of \Dumux developers group, \texttt{dumux-devel}. \begin{lstlisting}[style=Bash] $./dune-common/bin/dunecontrol --opts=$DUMUX_ROOT/debug.opts all \end{lstlisting} More optimized code, but which is typically not as useful for standard tasks in debugger can produced by \begin{lstlisting}[style=Bash] $./dune-common/bin/dunecontrol --opts=$DUMUX_ROOT/optim.opts all \end{lstlisting} Sometimes it is necessary to have additional options which are specific to tools set of an operating system or just mirror your preferences, feel free to work with your own set of options which may evolve over time. Above option files are more to understand as examples as a starting setting for own customization than as something fixed to \Dumux. %Alternatively, the tool CMake can be used to build \Dumux. Please check the file \texttt{INSTALL.cmake} for details. \subsection{External libraries and modules}  David Werner committed Oct 25, 2010 171   Klaus Mosthaf committed Oct 28, 2010 172 The following libraries provide additional functionality but are not required to run \Dumux.  David Werner committed Jan 14, 2011 173 If you are going to use an external library check the information provided on the \Dune website. If you are going to use an external \Dune module beside {\Dune}s website a website regarding the external modules in question can be helpful too. Too make the picture complete we list here complete some of external modules, some of external libraries and some of typical libaries and tools which get used by \Dune.  David Werner committed Oct 25, 2010 174   Philipp Nuske committed Sep 27, 2010 175 \begin{itemize}  David Werner committed Jan 14, 2011 176 177 178 \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 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}}).  Klaus Mosthaf committed Oct 27, 2010 179 \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 180   Philipp Nuske committed Jan 05, 2011 181 \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 182   Klaus Mosthaf committed Oct 28, 2010 183 \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 184   Philipp Nuske committed Jan 05, 2011 185 \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 186   Klaus Mosthaf committed Oct 28, 2010 187 \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 188   David Werner committed Oct 25, 2010 189 190 \end{itemize}  Klaus Mosthaf committed Oct 28, 2010 191 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 192 \begin{itemize}  Klaus Mosthaf committed Oct 28, 2010 193 \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 194   Klaus Mosthaf committed Oct 28, 2010 195 \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 196   David Werner committed Jan 14, 2011 197 \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 198   Klaus Mosthaf committed Oct 28, 2010 199 \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 200   David Werner committed Jan 14, 2011 201 \item \textbf{LibGOTO}: is an optimized version of BLAS. It is not always available for all architectures and  Klaus Mosthaf committed Oct 28, 2010 202 203 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 204   Philipp Nuske committed Jan 05, 2011 205 \item \textbf{\LaTeX, doxygen}: In order to build the \Dumux documentation these tools are needed.  Klaus Mosthaf committed Oct 28, 2010 206 \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 207   Klaus Mosthaf committed Oct 28, 2010 208 209 210 \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 211   Klaus Mosthaf committed Oct 28, 2010 212 \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 213 214 % http://openmp.org/  Klaus Mosthaf committed Oct 28, 2010 215 \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 216 % http://gmplib.org/  David Werner committed Oct 25, 2010 217 \end{itemize}  Klaus Mosthaf committed Oct 21, 2010 218   David Werner committed Jan 14, 2011 219 \paragraph{Hint for Users from IWS} Users from the Institute of Hydraulic Engineering, University of Stuttgart,  David Werner committed Jan 14, 2011 220 can also checkout a svn repository with several external libraries:  221   David Werner committed Jan 14, 2011 222 223 224 \begin{lstlisting}[style=Bash] $svn checkout svn://svn.iws.uni-stuttgart.de/DUMUX/external/trunk external \end{lstlisting}  225   Klaus Mosthaf committed Oct 27, 2010 226 This directory \texttt{external} contains a script to install external libraries, such as  David Werner committed Jan 14, 2011 227 Alberta, ALUGrid, UG, METIS and an optimized version of BLAS named LibGOTO:  David Werner committed Jan 14, 2011 228 229 230 \begin{lstlisting}[style=Bash]$ ./installExternal.sh all \end{lstlisting}  Klaus Mosthaf committed Oct 28, 2010 231 it is also possible to install only certain parts of the external libraries:  David Werner committed Jan 14, 2011 232 233 234 \begin{lstlisting}[style=Bash] \$ ./installExternal.sh alberta \end{lstlisting}  235   Klaus Mosthaf committed Oct 28, 2010 236 237 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}. ` 238