install.tex 24.8 KB
 Bernd Flemisch committed Feb 01, 2012 1 2 \chapter{Detailed Installation Instructions} \label{install} \section{Preliminary remarks}  Klaus Mosthaf committed Oct 12, 2010 3   Christoph Grueninger committed Feb 23, 2012 4 In this section about the installation of \Dumux it is assumed that you work on a Unix or Linux compatible operating system  Klaus Mosthaf committed Feb 16, 2011 5 and that you are familiar with the use of a command line shell. Installation means that you unpack \Dune together with \Dumux in a certain directory.  Viktor Szukitsch committed Sep 01, 2011 6 7 8 Then, you compile it in that directory tree in which you do the further work, too. You also should know how to install new software packages or you should have a person on hand who can give you assistance with that. In section \ref{sec:prerequisites} we list some prerequisites for running \Dune and \Dumux. Please check in said paragraph whether you can fulfill them. In addition, section \ref{sec:external-modules-libraries} provides some details on optional libraries and modules.  David Werner committed Jan 19, 2011 9   Klaus Mosthaf committed Oct 28, 2010 10 In a technical sense \Dumux is a module of \Dune.  Klaus Mosthaf committed Feb 24, 2011 11 12 13 14 Thus, the installation procedure of \Dumux is the same as that of \Dune. Details regarding the installation of \Dune are provided on the \Dune website \cite{DUNE-INST}. If you are interested in more details about the build system that is used, they can be found in the {\Dune} Buildsystem Howto \cite{DUNE-BS}.  Klaus Mosthaf committed Oct 12, 2010 15   David Werner committed Jan 13, 2011 16   Viktor Szukitsch committed Sep 01, 2011 17 18 All \Dune modules, including \Dumux, get extracted into a common directory, as it is done in an ordinary \Dune installation. We refer to that directory abstractly as {\Dune} root directory or, in short, as {\Dune}-Root.  Klaus Mosthaf committed Feb 24, 2011 19 20 If it is used as directory's path of a shell command it is typed as \texttt{\Dune-Root}. For the real {\Dune} root directory on your file system any valid directory name can be chosen.  David Werner committed Jan 13, 2011 21   David Werner committed Jan 19, 2011 22 Source code files for each \Dune module are contained in their own subdirectory within {\Dune}-Root.  Christoph Grueninger committed Feb 23, 2012 23 24 We name this directory of a certain module \emph{module root directory} or \texttt{module-root-directory} if it is a directory path, e.\,g. for the module \texttt{dumux} these names are \emph{dumux root directory} respective \texttt{dumux-root-directory}.  Viktor Szukitsch committed Sep 01, 2011 25 The real directory names for the modules can be chosen arbitrarily. In this manual they are the same as the  David Werner committed Jan 19, 2011 26 module name or the module name extended by a version number suffix.  Viktor Szukitsch committed Sep 01, 2011 27 The name of each \Dune module is defined in the file \texttt{dune.module}, which is in the root  Klaus Mosthaf committed Feb 24, 2011 28 29 directory of the respective module. This should not be changed by the user. It is allowed to have own files and directories in \Dune-Root, which are not related to \Dune's needs.  David Werner committed Jan 13, 2011 30   Klaus Mosthaf committed Feb 24, 2011 31 After installing source code for all relevant \Dune modules including \Dumux, \Dune is being built by the shell-command \texttt{dunecontrol} which is part of the \Dune build system. The \Dune build system is a front-end of to the GNU build system adapted to the needs of \Dune.  David Werner committed Oct 25, 2010 32   Bernd Flemisch committed Feb 01, 2012 33 \section{Prerequisites} \label{sec:prerequisites}  Klaus Mosthaf committed Feb 24, 2011 34 35 The GNU tool chain of \texttt{g++} and the tools of the GNU build system \cite{GNU-BS}, also known as GNU autotools (\texttt{autoconf}, \texttt{automake}, \texttt{autogen}, \texttt{libtool}), as well as the GNU variant of \texttt{make}  Christoph Grueninger committed Feb 23, 2012 36 called gmake must be available in a recent version. For example Ubuntu Linux provides these tools with the  David Werner committed Jan 17, 2011 37 packages \texttt{autoconf}, \texttt{automake}, \texttt{libtool}  Christoph Grueninger committed Jul 12, 2012 38 and the \Cplusplus compiler \texttt{g++} and \texttt{make} are contained in \texttt{build-essential}.  David Werner committed Jan 19, 2011 39   Christoph Grueninger committed Feb 23, 2012 40 At the time of writing this manual, it is expected that \texttt{g++} of version $\geqslant$ 4.5.0, \texttt{automake} of version $\geqslant$ 1.9,  David Werner committed Jan 19, 2011 41 \texttt{autoconf} of version $\geqslant$ 2.65, \texttt{autogen} of version $\geqslant$ 5.9.7, \texttt{libtool} of version $\geqslant$ 2.2.6  Klaus Mosthaf committed Feb 24, 2011 42 and GNU \texttt{make} version $\geqslant$ 3.81 should do their job for building \Dumux.  Andreas Lauser committed Feb 06, 2012 43   Klaus Mosthaf committed Feb 16, 2011 44 The building of included documentation like this handbook requires \LaTeX\ and auxiliary tools  Viktor Szukitsch committed Sep 01, 2011 45 like \texttt{dvipdf} and \texttt{bibtex}. One usually chooses a \LaTeX\ distribution like \texttt{texlive} for this purpose.  Klaus Mosthaf committed Feb 24, 2011 46 47 48 It is possible to switch off the building of the documentation by setting the switch \texttt{--disable-documentation} in the \texttt{CONFIGURE\_FLAGS} of the building options (see Chapter \ref{buildIt}). Additional parts of documentation are contained within the source code files as special formatted comments.  Viktor Szukitsch committed Sep 01, 2011 49 Extracting them can be done using \texttt{doxygen} (version $\geqslant$ 1.7.2 works).  Klaus Mosthaf committed Feb 24, 2011 50 See for this optional step Section \ref{sec:build-doxy-doc}.  David Werner committed Jan 17, 2011 51   Klaus Mosthaf committed Feb 24, 2011 52 53 Depending on whether you are going to use external libraries and modules for additional \Dune features, additional software packages may be required. Some hints on that are given in Section \ref{sec:external-modules-libraries}.  David Werner committed Jan 17, 2011 54   Christoph Grueninger committed Feb 23, 2012 55 For the extraction of the content of tar files, the GNU version of \texttt{tar} is used.  Klaus Mosthaf committed Feb 24, 2011 56 The subversion (svn) software repositories can be accessed with help of a subversion client. We recommend the Apache Subversion command-line client \texttt{svn}  Philipp Nuske committed Jul 20, 2012 57 contained in Apache Subversion of version $\geqslant$ 1.6.0 \cite{APACHE-SUBVERSION-HP}.  Klaus Mosthaf committed Oct 12, 2010 58   59 60 61 \begin{table} \centering \caption{Ubuntu package names for Ubuntu 12.04}  Philipp Nuske committed Jul 20, 2012 62 63 64 65 66 67 68 \begin{tabular}{llll} \toprule \textbf{purpose} & \textbf{package names} \\ \midrule general: & subversion & git & libtool \\ & automake & build-essential & libboost-all-dev \\ & texlive-latex-base & doxygen & csh\\  Philipp Nuske committed Jul 20, 2012 69 & gfortran & ? libpthread-stubs0 ?\\  Philipp Nuske committed Jul 20, 2012 70 71 72 73 74 75 76 77 \midrule for alberta: & freeglut3-dev & \\ \midrule for parallel use: & openmpi-common & mpi-default-bin & mpi-default-dev \\ \midrule for ug parallel: & flex & bison & \\ \midrule for alberta parallel: & libblas-dev &\\  Nicolas Schwenck committed Jul 20, 2012 78 79 \midrule for debugging: & valgrind &\\  Philipp Nuske committed Jul 20, 2012 80 81 \bottomrule \end{tabular}  82 83 84 \label{tbl:ubuntu-pkg} \end{table}  Bernd Flemisch committed Feb 01, 2012 85 \section{Obtaining source code for \Dune and \Dumux}  Benjamin Faigle committed Oct 11, 2012 86 87 As stated above, the \Dumux release 2.2.0 and trunk (developer tree) are based on the \Dune release 2.2.0, comprising the core modules \texttt{dune-common}, \texttt{dune-grid}, \texttt{dune-geometry}, \texttt{dune-istl} and \texttt{dune-localfunctions}.  Andreas Lauser committed Feb 06, 2012 88 89 % and the external dune module \texttt{dune-pdelab}. For working with \Dumux, these modules are required.  David Werner committed Jan 13, 2011 90   Klaus Mosthaf committed Feb 16, 2011 91 Two possibilities exist to get the source code of \Dune and \Dumux.  Christoph Grueninger committed Feb 23, 2012 92 Firstly, \Dune and \Dumux can be downloaded as tar files from the respective \Dune and \Dumux website. They have to be extracted as described in the next paragraph.  Viktor Szukitsch committed Sep 01, 2011 93 Secondly, a method to obtain the most recent source code (or, more generally, any of its previous revisions) by direct access  Klaus Mosthaf committed Feb 24, 2011 94 95 96 via Internet to the software repositories of the revision control system is described in the subsequent part. However, if a user does not want to use the most recent version,  Christoph Grueninger committed Feb 23, 2012 97 certain version tags (i.\,e. special names), version numbers and even software branches are means  Klaus Mosthaf committed Feb 24, 2011 98 of the software revision control system to provide access to different versions of the software.  Klaus Mosthaf committed Oct 12, 2010 99   Christoph Grueninger committed Feb 23, 2012 100 101 102 \paragraph{Obtaining the software by installing tar files} The slightly old-fashionedly named tape-archive-file, shortly named tar file or tarball, is a common file format for distributing collections of files contained within these archives. The extraction from the tar files is done as follows:  Alexander Kissinger committed Sep 07, 2012 103 Download the tarballs from the respective \Dune (version 2.2.0) and \Dumux websites to a certain folder in your file system.  Christoph Grueninger committed Feb 23, 2012 104 Create the {\Dune} root directory, named DUMUX in the example below. Then extract the content of the tar files, e.\,g. with the command-line program \texttt{tar}.  Klaus Mosthaf committed Feb 16, 2011 105 This can be achieved by the following shell commands. Replace \texttt{path\_to\_tarball} with the directory name where the downloaded files are actually located.  Alexander Kissinger committed Sep 07, 2012 106 After extraction, the actual name of the \emph{dumux root directory} is \texttt{dumux-2.2}.  David Werner committed Jan 14, 2011 107 108 109 110  \begin{lstlisting}[style=Bash] $mkdir DUMUX$ cd DUMUX  Alexander Kissinger committed Sep 07, 2012 111 112 113 114 115 116 $tar xzvf path_to_tarball_of/dune-common-2.2.0.tar.gz$ tar xzvf path_to_tarball_of/dune-grid-2.2.0.tar.gz $tar xzvf path_to_tarball_of/dune-geometry-2.2.0.tar.gz$ tar xzvf path_to_tarball_of/dune-istl-2.2.0.tar.gz $tar xzvf path_to_tarball_of/dune-localfunctions-2.2.0.tar.gz$ tar xzvf path_to_tarball_of/dumux-2.2.tar.gz  David Werner committed Jan 14, 2011 117 118 \end{lstlisting}  Klaus Mosthaf committed Feb 24, 2011 119 Furthermore, if you wish to install the optional \Dune Grid-Howto which provides a tutorial on the Dune grid interface:  David Werner committed Jan 14, 2011 120 121  \begin{lstlisting}[style=Bash]  Alexander Kissinger committed Sep 07, 2012 122 $tar xzvf path_to_tarball_of/dune-grid-howto-2.2.0.tar.gz  David Werner committed Jan 14, 2011 123 124 \end{lstlisting}  David Werner committed Jan 13, 2011 125 126 \paragraph{Obtaining \Dune and \Dumux from software repositories}  Viktor Szukitsch committed Sep 01, 2011 127 Direct access to a software revision control system for downloading code can be of advantage for the user later on.  Klaus Mosthaf committed Feb 24, 2011 128 It can be easier for him to keep up with code changes and to receive important bug fixes using the update command of the revision control system.  Viktor Szukitsch committed Sep 01, 2011 129 \Dune and \Dumux use Apache Subversion for their software repositories. To access them a certain program is needed which is referred to here shortly as subversion client.  Klaus Mosthaf committed Feb 24, 2011 130 In our description, we use the subversion client of the Apache Subversion software itself, which is a command-line tool named \texttt{svn}.  Christoph Grueninger committed Feb 23, 2012 131 It is available for most Linux and Unix distributions as software package.  David Werner committed Jan 13, 2011 132   Christoph Grueninger committed Feb 23, 2012 133 In the technical language of Apache Subversion \emph{checking out a certain software version} means nothing more then fetching  Viktor Szukitsch committed Sep 01, 2011 134 a local copy from the software repository and laying it out in the file system. In addition to the software some more files for the use of the software revision control system itself are created. They are kept in directories named \texttt{.svn} and can be found in each subfolder which is under version control.  Christoph Grueninger committed Feb 23, 2012 135 If you have developer access to \Dumux, it is also possible to do the opposite, i.\,e. to load up a modified revision of software into the software repository. This is usually termed as \emph{software commit}.  David Werner committed Jan 13, 2011 136   David Werner committed Jan 19, 2011 137 The installation procedure is done as follows:  Christoph Grueninger committed Feb 23, 2012 138 Create a {\Dune} root directory, named \texttt{DUMUX} in the lines below.  Klaus Mosthaf committed Feb 23, 2011 139 140 Then, enter the previously created directory and check out the desired modules. As you see below, the check-out uses two different servers for getting the sources, one for \Dune and one for {\Dumux}.  Alexander Kissinger committed Sep 07, 2012 141 The \Dune modules of the stable 2.2 release branch are checked out as described on the \Dune website \cite{DUNE-DOWNLOAD-SVN}:  David Werner committed Jan 14, 2011 142 143  \begin{lstlisting}[style=Bash]  David Werner committed Jan 17, 2011 144 145 $ mkdir DUMUX $cd DUMUX  Alexander Kissinger committed Sep 07, 2012 146 147 148 $ svn checkout https://svn.dune-project.org/svn/dune-common/branches/release-2.2 dune-common $svn checkout https://svn.dune-project.org/svn/dune-istl/branches/release-2.2 dune-istl$ svn checkout https://svn.dune-project.org/svn/dune-grid/branches/release-2.2 dune-grid  Alexander Kissinger committed Sep 07, 2012 149 $svn checkout https://svn.dune-project.org/svn/dune-geometry/branches/release-2.2 dune-geometry  Alexander Kissinger committed Sep 07, 2012 150 $ svn checkout https://svn.dune-project.org/svn/dune-localfunctions/branches/release-2.2 dune-localfunctions  David Werner committed Jan 14, 2011 151 \end{lstlisting}  Bernd Flemisch committed Jul 16, 2010 152   Benjamin Faigle committed Oct 11, 2012 153 The newest and maybe unstable developments are also provided in these repositories in a folder called \emph{trunk}. Please check the \Dune website \cite{DUNE-DOWNLOAD-SVN} for further information. However, the current \Dumux release is based on the stable 2.2 release and it might not compile without further adaptations using the the newest versions of \Dune.  Klaus Mosthaf committed Feb 23, 2011 154 155  The additional module \texttt{dune-grid-howto} is a tutorial which provides information about the \Dune grid interface.  Viktor Szukitsch committed Sep 01, 2011 156 It may give you an idea of how some abstractions in \Dune are done.  Christoph Grueninger committed Feb 23, 2012 157 The installation of \texttt{dune-grid-howto} is optional and is not required by \Dumux. It is done by:  David Werner committed Jan 14, 2011 158 159  \begin{lstlisting}[style=Bash]  Alexander Kissinger committed Sep 07, 2012 160 $svn checkout https://svn.dune-project.org/svn/dune-grid-howto/branches/release-2.2 dune-grid-howto  David Werner committed Jan 14, 2011 161 \end{lstlisting}  Klaus Mosthaf committed Oct 08, 2010 162   Klaus Mosthaf committed Feb 24, 2011 163 The \texttt{dumux} module is checked out as described below (see also the \Dumux website \cite{DUMUX-HP}).  Viktor Szukitsch committed Sep 01, 2011 164 Its file tree has to be created in the \Dune-Root directory, where the \Dune modules have also been checked out to. Subsequently, the next command  Klaus Mosthaf committed Feb 24, 2011 165 is executed there, too. The dumux root directory is called \texttt{dumux} here.  David Werner committed Jan 13, 2011 166   David Werner committed Jan 14, 2011 167 \begin{lstlisting}[style=Bash]  Klaus Mosthaf committed Feb 24, 2011 168 $ # make sure you are in DUNE-Root  Christoph Grueninger committed Feb 23, 2012 169 $svn checkout --username=anonymous --password='' svn://svn.iws.uni-stuttgart.de/DUMUX/dumux/trunk dumux  David Werner committed Jan 14, 2011 170 \end{lstlisting}  Klaus Mosthaf committed Oct 12, 2010 171   David Werner committed Jan 13, 2011 172 \paragraph{Hints for \Dumux-Developers}  Klaus Mosthaf committed Feb 23, 2011 173 If you also want to actively participate in the development of \Dumux, you can apply either for full developer  David Werner committed Jan 19, 2011 174 access or for developer access on certain parts of \Dumux. Granted developer access means that  Klaus Mosthaf committed Feb 23, 2011 175 you are allowed to commit own code and that you can access the \texttt{dumux-devel} module.  Christoph Grueninger committed Feb 23, 2012 176 This enhances \texttt{dumux} by providing maybe unstable code from the developer group.  Klaus Mosthaf committed Feb 24, 2011 177 178 A developer usually checks out non-anonymously the modules \texttt{dumux} and \texttt{dumux-devel}. \texttt{Dumux-devel} itself makes use of the stable part \texttt{dumux}. Hence, the two parts have to be checked out together.  Viktor Szukitsch committed Sep 01, 2011 179 This is done using the commands below. But \texttt{joeuser} needs to be replaced by  Klaus Mosthaf committed Feb 24, 2011 180 the actual user name of the developer for accessing the software repository.  Viktor Szukitsch committed Sep 01, 2011 181 One can omit the \texttt{--username} option in the commands above if the user name for the repository access is  Klaus Mosthaf committed Feb 24, 2011 182 identical to the one for the system account.  David Werner committed Jan 14, 2011 183 184 185 186 187 188  \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 19, 2011 189 Please choose either not to store the password by subversion in an insecure way or  Christoph Grueninger committed Feb 23, 2012 190 191 choose to store it by subversion in a secure way, e.\,g. together with KDE's KWallet or GNOME Keyring. Check the documentation of Subversion for info on how this is done.  Christoph Grueninger committed Oct 02, 2012 192 A leaked out password can be used by evil persons to abuse a software repository.  Klaus Mosthaf committed Oct 12, 2010 193   Bernd Flemisch committed Feb 01, 2012 194 \section{Patching \Dune or external libraries}  Christoph Grueninger committed Feb 23, 2012 195 Patching of \Dune modules in order to work together with \Dumux can be necessary for several reasons.  David Werner committed Feb 03, 2011 196 Software like a compiler or even a standard library  Christoph Grueninger committed Feb 23, 2012 197 changes at times. But, for example, a certain release of a software component that we depend on, may not reflect that change and thus it has to be modified.  Viktor Szukitsch committed Sep 01, 2011 198 199 In the dynamic developing process of software which depends on other modules it is not always feasible to adapt everything to the most recent version of each module. Consequently, patches exist or they will be brought into existence. They may fix problems with a certain module  Klaus Mosthaf committed Feb 24, 2011 200 201 of a certain release without introducing too much structural change. It can also happen that a release gets amendments (updates) and a formerly useful patch becomes obsolete.  David Werner committed Feb 03, 2011 202   Klaus Mosthaf committed Feb 24, 2011 203 \Dumux contains patches and documentation about their usage and application within the directory \texttt{dumux/patches}.  Klaus Mosthaf committed Feb 23, 2011 204 Please check the README file in that directory for recent information.  Klaus Mosthaf committed Feb 24, 2011 205 In general, a patch can be applied as follows (the exact command or the used parameters may be slightly different).  Alexander Kissinger committed Sep 07, 2012 206 We include here an example of a patch against 2.0 release of \Dune for \Dumux release 2.0 for purpose of showing how a patch gets applied. Note this patch is no longer necessary for \Dune 2.2 releases.  David Werner committed Jan 24, 2011 207   David Werner committed Feb 03, 2011 208 209 \begin{lstlisting}[style=Bash]$ # make sure you are in DUNE-Root  David Werner committed Feb 03, 2011 210 $cd dune-istl  David Werner committed Feb 03, 2011 211 212 213 $ patch -p1 < ../dumux/patches/dune-istl-2.0.patch \end{lstlisting}  Klaus Mosthaf committed Feb 24, 2011 214 215 216 217 218 It can be removed by \begin{lstlisting}[style=Bash] $path -p1 -R < ../dumux/patches/dune-istl-2.0.patch \end{lstlisting}  Viktor Szukitsch committed Sep 01, 2011 219 The \texttt{checkout-dumux} script also applies patches, if not explicitly requested not to do so.  David Werner committed Jan 24, 2011 220   David Werner committed Jan 17, 2011 221   Bernd Flemisch committed Feb 01, 2012 222 \section{Building doxygen documentation} \label{sec:build-doxy-doc}  David Werner committed Jan 17, 2011 223   Klaus Mosthaf committed Feb 24, 2011 224 225 226 Doxygen documentation is done by especially formatted comments integrated in the source code, which can get extracted by the program \texttt{doxygen}. Beside extracting these comments, \texttt{doxygen} builds up a web-browsable code structure documentation like class hierarchy of code displayed as graphs, see \cite{DOXYGEN-HP}.  David Werner committed Jan 17, 2011 227   Klaus Mosthaf committed Feb 24, 2011 228 Building the doxygen documentation of a module is done as follows, provided the program \texttt{doxygen} is installed:  David Werner committed Jan 19, 2011 229 Set in building options the \texttt{--enable-doxygen} switch.  David Werner committed Jan 17, 2011 230 This is either accomplished by adding it in \texttt{dunecontrol} options-file to \texttt{CONFIGURE\_FLAGS}, or by adding  David Werner committed Jan 19, 2011 231 232 it to \texttt{dunecontrol}'s command-line-argument \texttt{--configure-opts}. After running \texttt{dunecontrol} enter in module's root directory the subdirectory \texttt{doc/doxygen}.  Klaus Mosthaf committed Feb 23, 2011 233 234 235 236 You then run the command \texttt{doxygen} within that directory. Point your web browser to the file \texttt{module-root-directory/doc/doxygen/html/index.html} to read the generated documentation. All \Dune-modules that are used here except \texttt{dune-grid-howto} including also \texttt{dumux} contain some doxygen documentation, which can be extracted as described in the following lines. The external library UG has also a \texttt{doc/doxygen} directory for building its doxygen documentation.  David Werner committed Jan 17, 2011 237   David Werner committed Jan 17, 2011 238 239 240 241 242 243 244 \begin{lstlisting}[style=Bash]$ # change before next command your directory to DUNE-Root $cd dumux/doc/doxygen$ doxygen $firefox html/index.html \end{lstlisting}  Bernd Flemisch committed Feb 01, 2012 245 \section{Building documentation of other \Dune modules}  David Werner committed Jan 17, 2011 246   Klaus Mosthaf committed Feb 24, 2011 247 If the \texttt{--enable-documentation} switch has been set in the configure flags of  Klaus Mosthaf committed Feb 23, 2011 248 \texttt{dunecontrol}, this does not necessarily mean that for every  Viktor Szukitsch committed Sep 01, 2011 249 \Dune module the documentation is being built.  Klaus Mosthaf committed Feb 23, 2011 250 251 However, at least Makefiles for building the documentation are generated. Provided you run \texttt{dunecontrol} with the option above,  David Werner committed Jan 19, 2011 252 it should be possible to build documentation if available.  Christoph Grueninger committed Feb 23, 2012 253 254 Check the targets you can build in \texttt{module-root-directory/doc/Makefile.am}. For example in the module \texttt{dune-istl} you can build the documentation \texttt{istl.pdf} by typing the following into the console, when you are in the \Dune-Root:  David Werner committed Jan 17, 2011 255 256  \begin{lstlisting}[style=Bash]  David Werner committed Jan 17, 2011 257 $ # change before next command your directory to DUNE-Root  David Werner committed Jan 17, 2011 258 259 260 261 $cd dune-istl/doc$ make istl.pdf \end{lstlisting}  Klaus Mosthaf committed Feb 23, 2011 262 Or for module \texttt{dune-grid-howto} the documentation can be build by:  David Werner committed Jan 19, 2011 263 264 265 266 267 268 269  \begin{lstlisting}[style=Bash] $# change before next command your directory to DUNE-Root$ cd dune-grid-howto/doc $make grid-howto.pdf \end{lstlisting}  Christoph Grueninger committed Feb 23, 2012 270 This applies for \Dumux, too. Rebuilding the handbook can be done as follows:  David Werner committed Jan 19, 2011 271 272 273 274 275 276 277  \begin{lstlisting}[style=Bash]$ cd dumux/doc/handbook $make dumux-handbook.pdf \end{lstlisting}  Viktor Szukitsch committed Sep 01, 2011 278 %As of writing this, no general method of building documentation contained in \Dune's modules is known to the author.  David Werner committed Jan 14, 2011 279 280  %Alternatively, the tool CMake can be used to build \Dumux. Please check the file \texttt{INSTALL.cmake} for details.  David Werner committed Jan 17, 2011 281   Bernd Flemisch committed Feb 01, 2012 282 \section{External libraries and modules} \label{sec:external-modules-libraries}  David Werner committed Oct 25, 2010 283   Viktor Szukitsch committed Sep 01, 2011 284 The libraries described below provide additional functionality but are not generally required to run \Dumux.  David Werner committed Jan 19, 2011 285 If you are going to use an external library check the information provided on the \Dune website \cite{DUNE-EXT-LIB}.  Christoph Grueninger committed Feb 23, 2012 286 If you are going to use an external \Dune module the website on external modules \cite{DUNE-EXT-MOD} can be helpful.  David Werner committed Jan 19, 2011 287   Klaus Mosthaf committed Feb 23, 2011 288 Installing an external library can require additional libraries which are also used by \Dune.  Viktor Szukitsch committed Sep 01, 2011 289 For some libraries, such as BLAS or MPI, multiple versions can be installed on the system.  Klaus Mosthaf committed Feb 24, 2011 290 Make sure that it uses the same library as \Dune when configuring the external library.  David Werner committed Jan 19, 2011 291   Klaus Mosthaf committed Feb 23, 2011 292 In the following list, you can find some external modules and external libraries, and some more libraries and tools which are prerequisites for their use.  David Werner committed Oct 25, 2010 293   Philipp Nuske committed Sep 27, 2010 294 \begin{itemize}  Christoph Grueninger committed Feb 23, 2012 295 \item \textbf{ALBERTA}: External library for use as grid. Adaptive multi Level finite element toolbox using Bisectioning refinement and Error control by Residual Techniques for scientific Applications. Building it requires a Fortran compiler \texttt{gfortran}. Download: \texttt{\url{http://www.alberta-fem.de}}.  David Werner committed Jan 14, 2011 296   Christoph Grueninger committed Jul 12, 2012 297 \item \textbf{ALUGrid}: External library for use as grid. ALUGrid is built by a \Cplusplus 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}. It was run successfully in combination with \Dune using \texttt{METIS}. \\  Klaus Mosthaf committed Feb 23, 2011 298 Download: \texttt{\url{http://aam.mathematik.uni-freiburg.de/IAM/Research/alugrid}}  Philipp Nuske committed Sep 27, 2010 299   Klaus Mosthaf committed Feb 23, 2011 300 301 302 \item \textbf{\Dune-multidomaingrid}: External module. If you going to run on the same grid different domains or subdomains, this can be the package of choice. This is done by providing a meta grid. It can be useful for multi-physics approaches or domain decomposition methods. Download: \texttt{\url{http://gitorious.org/dune-multidomaingrid}}. %Furthermore, the external module \textbf{\Dune-multidomain} can be useful for solving heterogenous problems on spatial subdomains. These subdomains are managed using another DUNE module called dune-multidomaingrid.  Philipp Nuske committed Sep 27, 2010 303   Christoph Grueninger committed Feb 23, 2012 304 305 \item \textbf{\Dune-PDELab}: External module to write more easily discretizations. PDELab provides already a sound number of discretizations like FEM or discontinuous Galerkin methods. Download: \texttt{\url{http://www.dune-project.org/pdelab}}.  David Werner committed Jan 19, 2011 306 \item \textbf{PARDISO}: External library for solving linear equations. 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 307   Christoph Grueninger committed Feb 23, 2012 308 \item \textbf{SuperLU}: External library for solving linear equations. SuperLU is a general purpose library for the direct solution of large, sparse, non-symmetric systems of linear equations. Be aware that the version 4.3 is not supported by \Dune prior to 2.1.0. \\ (\texttt{\url{http://crd.lbl.gov/~xiaoye/SuperLU}}).  Klaus Mosthaf committed Feb 23, 2011 309   Christoph Grueninger committed Jul 12, 2012 310 \item \textbf{UG}: External library for use as grid. UG is a toolbox for Unstructured Grids: For \Dumux it has to be build by GNU buildsystem and a \Cplusplus compiler. That's why \Dune specific patches need applied before use. Building it makes use of the tools \texttt{lex}/\texttt{yacc} or the GNU variants \texttt{flex}/\texttt{bison}.  Philipp Nuske committed Sep 27, 2010 311   David Werner committed Oct 25, 2010 312 313 \end{itemize}  Klaus Mosthaf committed Oct 28, 2010 314 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 Jan 19, 2011 315   David Werner committed Oct 25, 2010 316 \begin{itemize}  David Werner committed Jan 19, 2011 317 \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} version$\geqslant$1.4.2 and \texttt{MPICH} in a recent version have been reported to work.  Philipp Nuske committed Sep 27, 2010 318   Klaus Mosthaf committed Oct 28, 2010 319 \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 320   David Werner committed Jan 17, 2011 321 \item \textbf{BLAS}: Alberta makes use of BLAS. Thus install GotoBLAS2, ATLAS, non-optimized BLAS or BLAS provided by a chip manufacturer. Take care that the installation scripts select the intended version of BLAS. See \texttt{\url{http://en.wikipedia.org/wiki/Basic_Linear_Algebra_Subprograms}}.  Philipp Nuske committed Oct 18, 2010 322   Viktor Szukitsch committed Sep 01, 2011 323 \item \textbf{GotoBLAS2}: This is an optimized version of BLAS. It covers not all processors of the day, but quite a broad range. Its license is now very open. A Fortran compiler like \texttt{gfortran} is needed to compile it.\\  David Werner committed Jan 17, 2011 324 Available by \texttt{\url{http://www.tacc.utexas.edu/tacc-projects/gotoblas2/}}.  David Werner committed Oct 25, 2010 325   Klaus Mosthaf committed Feb 23, 2011 326 327 \item \textbf{METIS}: This is a dependency of ALUGrid, if you are going to run it parallel.  Christoph Grueninger committed Jul 12, 2012 328 \item \textbf{Compilers}: Beside \texttt{g++} it has been reported that \Dune was successfully built with \texttt{Clang++} from the LLVM project and the Intel \Cplusplus compiler.  Viktor Szukitsch committed Sep 01, 2011 329 C and Fortran compiler is needed for some external libraries. As code of different compilers is linked together they have to be be compatible with each other. A good choice is the GNU compiler suite \texttt{gcc}, \texttt{g++} and \texttt{gfortran}.  David Werner committed Oct 25, 2010 330   Klaus Mosthaf committed Feb 23, 2011 331 \item \textbf{libgomp}: External libraries, such as ALUGrid, can make use of OpenMP when used together with METIS. For that purpose it can be necessary to install the \texttt{libgomp} library.  David Werner committed Oct 25, 2010 332 333 % http://openmp.org/  David Werner committed Jan 17, 2011 334 %\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 335 % http://gmplib.org/  David Werner committed Oct 25, 2010 336 \end{itemize}  Klaus Mosthaf committed Oct 21, 2010 337   Bernd Flemisch committed Feb 01, 2012 338 \section{Hints for Users from IWS}  David Werner committed Jan 19, 2011 339 We provide some features to make life a little bit easier for  Andreas Lauser committed Jan 31, 2012 340 users from the Institute for Modelling Hydraulic and Environmental Systems, University of Stuttgart.  David Werner committed Jan 19, 2011 341   Christoph Grueninger committed Feb 23, 2012 342 343 There exists internally a SVN repository made for several external libraries. If you are allowed to access it, go to the {\Dune}-Root, then the following.  344   Christoph Grueninger committed Feb 23, 2012 345 Prepared external directory:  David Werner committed Jan 14, 2011 346 \begin{lstlisting}[style=Bash]  David Werner committed Jan 19, 2011 347 $ # Make sure you are in DUNE-Root  David Werner committed Jan 14, 2011 348 349 $svn checkout svn://svn.iws.uni-stuttgart.de/DUMUX/external/trunk external \end{lstlisting}  350   Klaus Mosthaf committed Oct 27, 2010 351 This directory \texttt{external} contains a script to install external libraries, such as  Christoph Grueninger committed Feb 23, 2012 352 ALBERTA, ALUGrid, UG, METIS and GotoBLAS2:  David Werner committed Jan 14, 2011 353 \begin{lstlisting}[style=Bash]  David Werner committed Jan 19, 2011 354 $ cd external  David Werner committed Jan 14, 2011 355 356 $./installExternal.sh all \end{lstlisting}  David Werner committed Jan 19, 2011 357   Viktor Szukitsch committed Sep 01, 2011 358 It is also possible to install only the actually needed external libraries:  David Werner committed Jan 14, 2011 359 \begin{lstlisting}[style=Bash]  David Werner committed Jan 19, 2011 360 361 $ ./installExternal.sh -h # show, what options this script provide \$ ./installExternal.sh --parallel alu  David Werner committed Jan 14, 2011 362 \end{lstlisting}  363   David Werner committed Jan 19, 2011 364 The libraries are then compiled within that directory and are not installed in a different place.  Klaus Mosthaf committed Feb 24, 2011 365 A \Dune build may need to know their location. Thus, one may have to refer to them as options for \texttt{dunecontrol},  Alexander Kissinger committed Sep 07, 2012 366 367 368 369 370 for example via the options file \texttt{my-debug.opts}. Make sure you compile the required external libraries before you run \texttt{dunecontrol}.  David Werner committed Jan 19, 2011 371   Andreas Lauser committed Feb 06, 2012 372 373 374 375 %%% Local Variables: %%% mode: latex %%% TeX-master: "dumux-handbook" %%% End: