install.tex 27.6 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 Feb 16, 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 command line shell. Installation means that you unpack \Dune together with \Dumux in a certain directory.  Klaus Mosthaf committed Feb 24, 2011 6 7 8 Then, you compile it in that directory tree where you do the further work, too. You also should know how to install new software packages or you should have a person aside which can give you assistance with that. In section \ref{sec:prerequisites} we list some prerequisites for running \Dune and \Dumux. Please check this 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   Klaus Mosthaf committed Feb 24, 2011 17 18 19 20 All \Dune modules including \Dumux get extracted into a common directory, as it is done in a usual \Dune installation. We refer to that directory abstractly as {\Dune} root directory or shortly as {\Dune}-Root. 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.  Klaus Mosthaf committed Feb 25, 2011 23 We name this directory of a certain module module root directory" or \texttt{module-root-directory} if it is a directory path,  Klaus Mosthaf committed Feb 24, 2011 24 e.g. for the module \texttt{dumux} these names are dumux root directory" respective \texttt{dumux-root-directory}.  Klaus Mosthaf committed Feb 16, 2011 25 The real directory names for 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.  Klaus Mosthaf committed Feb 24, 2011 27 28 29 The name of each \Dune module is always defined in the file \texttt{dune.module}, which is in root 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   David Werner committed Jan 17, 2011 33 \subsection{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}  Klaus Mosthaf committed Feb 16, 2011 36 must be available in a recent version. For Ubuntu Linux, e.g., these are contained in the  David Werner committed Jan 17, 2011 37 38 packages \texttt{autoconf}, \texttt{automake}, \texttt{libtool} and the C++ compiler \texttt{g++} and \texttt{make} are contained in \texttt{build-essential}.  David Werner committed Jan 19, 2011 39   Klaus Mosthaf committed Feb 16, 2011 40 At the time of writing this manual, it is expected that \texttt{g++} of version $\geqslant$ 4.4.1, \texttt{automake} of version $\geqslant$ 1.11,  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 43 and GNU \texttt{make} version $\geqslant$ 3.81 should do their job for building \Dumux. \Dumux makes use of the \texttt{boost} library in the version $\geqslant$ 1.33.1, but optional external modules may require a more recent version.  David Werner committed Jan 17, 2011 44 It is thus necessary to install an appropriate developer package of \texttt{boost}  Klaus Mosthaf committed Feb 24, 2011 45 which is sometimes also named \texttt{libboost}. The matching Ubuntu Linux package is \texttt{libboost-dev}.  David Werner committed Jan 17, 2011 46   Klaus Mosthaf committed Feb 16, 2011 47 The building of included documentation like this handbook requires \LaTeX\ and auxiliary tools  David Werner committed Jan 17, 2011 48 like \texttt{dvipdf} and \texttt{bibtex}. One usually chooses a \LaTeX\ distribution like \texttt{texlive} for doing that.  Klaus Mosthaf committed Feb 24, 2011 49 50 51 52 53 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. Extracting them can be done with \texttt{doxygen} (version $\geqslant$ 1.7.2 works). See for this optional step Section \ref{sec:build-doxy-doc}.  David Werner committed Jan 17, 2011 54   Klaus Mosthaf committed Feb 24, 2011 55 56 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 57   Klaus Mosthaf committed Feb 16, 2011 58 For the extraction of the content of tar-files, the GNU version of \texttt{tar} is used.  Klaus Mosthaf committed Feb 24, 2011 59 The subversion (svn) software repositories can be accessed with help of a subversion client. We recommend the Apache Subversion command-line client \texttt{svn}  David Werner committed Jan 17, 2011 60 contained in Apache Subversion of version $\geqslant$ 1.6.0 \cite{APACHE-SUBVERSION-HP}.  Klaus Mosthaf committed Oct 12, 2010 61   David Werner committed Jan 13, 2011 62 \subsection{Obtaining source code for \Dune and \Dumux}  Bernd Flemisch committed Jun 15, 2011 63 As stated before, the \Dumux release 2.0.2 is based on the \Dune release 2.1, comprising the core modules  David Werner committed Jan 17, 2011 64 \texttt{dune-common}, \texttt{dune-grid}, \texttt{dune-istl}, \texttt{dune-localfunctions} and the external dune  Klaus Mosthaf committed Feb 16, 2011 65 module \texttt{dune-pdelab}. Thus, for a proper \Dumux installation these modules are required.  David Werner committed Jan 13, 2011 66   Klaus Mosthaf committed Feb 16, 2011 67 68 Two possibilities exist to get the source code of \Dune and \Dumux. 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.  Klaus Mosthaf committed Feb 24, 2011 69 70 71 72 73 74 Secondly, a method to obtain the most recent source code (or more generally any of its the previous revisions) by direct access 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, certain version tags (i.e. special names), version numbers and even software branches are means of the software revision control system to provide access to different versions of the software.  Klaus Mosthaf committed Oct 12, 2010 75   David Werner committed Jan 13, 2011 76 \paragraph{Obtaining the software by installing tar-files}  Klaus Mosthaf committed Feb 24, 2011 77 The slightly old-fashioned named tape-archive-file shortly named tar-file or tarball is a common file format for distributing collections of files contained within these archives.  Klaus Mosthaf committed Feb 16, 2011 78 The extraction from the tar-files is done as follows:  Bernd Flemisch committed Jun 15, 2011 79 Download the tarballs from the respective \Dune (version 2.1) and \Dumux websites to a certain folder in your file system.  Klaus Mosthaf committed Feb 24, 2011 80 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 81 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.  Bernd Flemisch committed Jun 15, 2011 82 After extraction, the actual name of the dumux root directory is \texttt{dumux-2.0.2}.  David Werner committed Jan 14, 2011 83 84 85 86  \begin{lstlisting}[style=Bash] $mkdir DUMUX$ cd DUMUX  Bernd Flemisch committed Jun 15, 2011 87 88 89 90 91 $tar xzvf path_to_tarball_of/dune-common-2.1.0.tar.gz$ tar xzvf path_to_tarball_of/dune-grid-2.1.0.tar.gz $tar xzvf path_to_tarball_of/dune-istl-2.1.0.tar.gz$ tar xzvf path_to_tarball_of/dune-localfunctions-2.1.0.tar.gz $tar xzvf path_to_tarball_of/dumux-2.0.2.tar.gz  David Werner committed Jan 14, 2011 92 93 \end{lstlisting}  Klaus Mosthaf committed Feb 24, 2011 94 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 95 96  \begin{lstlisting}[style=Bash]  Bernd Flemisch committed Jun 15, 2011 97 $ tar xzvf path_to_tarball_of/dune-grid-howto-2.1.tar.gz  David Werner committed Jan 14, 2011 98 99 \end{lstlisting}  David Werner committed Jan 19, 2011 100 However, the required \Dune-module \texttt{dune-pdelab} is not available as tar-file.  Klaus Mosthaf committed Feb 24, 2011 101 102 It can be installed from a software repository via svn. If \texttt{svn} is available in the command line, it can be done as follows:  David Werner committed Jan 19, 2011 103   David Werner committed Jan 14, 2011 104 \begin{lstlisting}[style=Bash]  Bernd Flemisch committed Jun 15, 2011 105 $svn co https://svn.dune-project.org/svn/dune-pdelab/branches/2.1snapshot dune-pdelab  David Werner committed Jan 14, 2011 106 \end{lstlisting}  Klaus Mosthaf committed Oct 12, 2010 107   David Werner committed Jan 13, 2011 108 109 \paragraph{Obtaining \Dune and \Dumux from software repositories}  Klaus Mosthaf committed Feb 23, 2011 110 Direct access to a software revision control system for downloading code can be of later advantage for the user.  Klaus Mosthaf committed Feb 24, 2011 111 112 113 114 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. \Dune and \Dumux use Apache Subversion for their software repositories. To access them a certain program is needed which is referred here shortly as subversion client. In our description, we use the subversion client of the Apache Subversion software itself, which is a command-line tool named \texttt{svn}. It is available for most Linux and UNIX distributions as software package.  David Werner committed Jan 13, 2011 115   Klaus Mosthaf committed Feb 23, 2011 116 117 In the technical speech of Apache Subversion checking out a certain software version" means nothing more then fetching a local copy from the software repository and laying it out in the file system. Additionally 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 that is under version control.  Klaus Mosthaf committed Feb 24, 2011 118 If you have developer access to \Dumux, it is also possible to do the opposite, i.e. loading up a modified revision of software into the software repository. This is usually termed as software commit".  David Werner committed Jan 13, 2011 119   David Werner committed Jan 19, 2011 120 The installation procedure is done as follows:  Klaus Mosthaf committed Feb 23, 2011 121 122 123 Create a {\Dune} root directory, named DUMUX in the lines below. 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}.  Bernd Flemisch committed Jun 15, 2011 124 The \Dune modules of the stable 2.1 release are checked out as described on the \Dune website \cite{DUNE-DOWNLOAD-SVN}:  David Werner committed Jan 14, 2011 125 126  \begin{lstlisting}[style=Bash]  David Werner committed Jan 17, 2011 127 128 $ mkdir DUMUX $cd DUMUX  Bernd Flemisch committed Jun 15, 2011 129 130 131 132 133 $ svn co https://svn.dune-project.org/svn/dune-common/releases/2.1.0 dune-common $svn co https://svn.dune-project.org/svn/dune-grid/releases/2.1.0 dune-grid$ svn co https://svn.dune-project.org/svn/dune-istl/releases/2.1.0 dune-istl $svn co https://svn.dune-project.org/svn/dune-localfunctions/releases/2.1.0 dune-localfunctions$ svn co https://svn.dune-project.org/svn/dune-pdelab/branches/2.1snapshot dune-pdelab  David Werner committed Jan 14, 2011 134 \end{lstlisting}  Bernd Flemisch committed Jul 16, 2010 135   Bernd Flemisch committed Jun 15, 2011 136 The newest (unstable) developments are also provided in these repositories, usually in a folder called trunk''. Please check the \Dune website \cite{DUNE-DOWNLOAD-SVN} for further information. However, the current \Dumux release is based on the stable 2.1 release and it probably will not compile without further adaptations using the the newest versions of \Dune.  Klaus Mosthaf committed Feb 23, 2011 137 138 139 140  The additional module \texttt{dune-grid-howto} is a tutorial which provides information about the \Dune grid interface. It may give you an idea how some abstractions in \Dune are done. The \texttt{dune-grid-howto} is not required by \Dumux, the installation is optional. It is done by:  David Werner committed Jan 14, 2011 141 142  \begin{lstlisting}[style=Bash]  Bernd Flemisch committed Jun 15, 2011 143 $svn co https://svn.dune-project.org/svn/dune-grid-howto/releases/2.1.0 dune-grid-howto  David Werner committed Jan 14, 2011 144 \end{lstlisting}  Klaus Mosthaf committed Oct 08, 2010 145   Klaus Mosthaf committed Feb 24, 2011 146 147 148 The \texttt{dumux} module is checked out as described below (see also the \Dumux website \cite{DUMUX-HP}). Its file tree has to be created in the \Dune-Root directory, where the \Dune modules are also have been checked out to. Subsequently, the next command is executed there, too. The dumux root directory is called \texttt{dumux} here.  David Werner committed Jan 13, 2011 149   David Werner committed Jan 14, 2011 150 \begin{lstlisting}[style=Bash]  Klaus Mosthaf committed Feb 24, 2011 151 $ # make sure you are in DUNE-Root  David Werner committed Jan 14, 2011 152 153 $svn co --username=anonymous --password='' svn://svn.iws.uni-stuttgart.de/DUMUX/dumux/trunk dumux \end{lstlisting}  Klaus Mosthaf committed Oct 12, 2010 154   David Werner committed Jan 13, 2011 155 \paragraph{Hints for \Dumux-Developers}  Klaus Mosthaf committed Feb 23, 2011 156 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 157 access or for developer access on certain parts of \Dumux. Granted developer access means that  Klaus Mosthaf committed Feb 23, 2011 158 you are allowed to commit own code and that you can access the \texttt{dumux-devel} module.  Klaus Mosthaf committed Feb 24, 2011 159 160 161 162 163 164 165 This enhances \texttt{dumux} by providing (unstable) code from the developer group. 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. This is done by the commands below. But \texttt{joeuser} needs to be replaced by the actual user name of the developer for accessing the software repository. One can omit the \texttt{--username} option in the commands above, if the user name for the repository access is identical to the one for the system account.  David Werner committed Jan 14, 2011 166 167 168 169 170 171  \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 172 Please choose either not to store the password by subversion in an insecure way or  Klaus Mosthaf committed Feb 23, 2011 173 174 choose to store it by subversion in a secure way, e.g. together with \texttt{kwallet} or \texttt{gnomekeyring}. Check the documentation of subversion, how this is being done.  David Werner committed Jan 19, 2011 175 A leaked out password can be used by evil persons to abuse a software repository.  Klaus Mosthaf committed Oct 12, 2010 176   David Werner committed Jan 24, 2011 177 178 \paragraph{checkout-dumux script} The shell-script \texttt{checkout-dumux} facilitates setting up a {\Dune}/{\Dumux} directory tree.  Klaus Mosthaf committed Feb 24, 2011 179 It is contained in the download section of the \Dumux web page \cite{DUMUX-HP}.  Klaus Mosthaf committed Feb 23, 2011 180 For example the second line below will check out the required \Dune modules and \texttt{dumux}, \texttt{dumux-devel} and the \texttt{external} folder, which contains some useful external software and libraries.  Klaus Mosthaf committed Feb 24, 2011 181 Again, \texttt{joeuser} needs to be replaced by the actual user name.  David Werner committed Jan 24, 2011 182 183 184 185 186 187  \begin{lstlisting}[style=Bash]$ checkout-dumux -h # show help, $checkout-dumux -gme -u joeuser -p password -d DUMUX \end{lstlisting}  David Werner committed Feb 03, 2011 188 189 \subsection{Patching \Dune or external libraries} Patching of \Dune modules in order to work together with \Dumux  Klaus Mosthaf committed Feb 23, 2011 190 can be necessary for several reasons.  David Werner committed Feb 03, 2011 191 Software like a compiler or even a standard library  Klaus Mosthaf committed Feb 24, 2011 192 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.  Klaus Mosthaf committed Feb 23, 2011 193 In the dynamic developing process of software that depends on other modules it is not always feasible  Klaus Mosthaf committed Feb 24, 2011 194 195 196 to adapt everything to the most recent version of each module. Consequently, patches exist or they are be brought into existence. They may fix problems with a certain module 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 197   Klaus Mosthaf committed Feb 24, 2011 198 \Dumux contains patches and documentation about their usage and application within the directory \texttt{dumux/patches}.  Klaus Mosthaf committed Feb 23, 2011 199 Please check the README file in that directory for recent information.  Klaus Mosthaf committed Feb 24, 2011 200 In general, a patch can be applied as follows (the exact command or the used parameters may be slightly different).  David Werner committed Jan 24, 2011 201   David Werner committed Feb 03, 2011 202 203 \begin{lstlisting}[style=Bash]$ # make sure you are in DUNE-Root  David Werner committed Feb 03, 2011 204 $cd dune-istl  David Werner committed Feb 03, 2011 205 206 207 $ patch -p1 < ../dumux/patches/dune-istl-2.0.patch \end{lstlisting}  Klaus Mosthaf committed Feb 24, 2011 208 209 210 211 212 It can be removed by \begin{lstlisting}[style=Bash] $path -p1 -R < ../dumux/patches/dune-istl-2.0.patch \end{lstlisting}  Klaus Mosthaf committed Feb 23, 2011 213 The \texttt{checkout-dumux} script also applies patches, if not explicitly requested to do not so.  David Werner committed Jan 24, 2011 214   David Werner committed Jan 14, 2011 215 216 \subsection{Build of \Dune and \Dumux} \label{buildIt}  Klaus Mosthaf committed Feb 23, 2011 217 218 219 220 Building of \Dune and \Dumux is done by the command-line script \texttt{dunecontrol} as described in \Dune Installation Notes \cite{DUNE-INST} and in much more comprehensive form in the \Dune Buildsystem Howto \cite{DUNE-BS}. If something fails during the execution of \texttt{dunecontrol} feel free to report it to the \Dune or \Dumux developer mailing list, but also try to include error details.\\  David Werner committed Jan 14, 2011 221   Klaus Mosthaf committed Feb 23, 2011 222 223 224 225 226 227 228 229 It is possible to compile \Dumux with nearly no explicit options to the build system. %, 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. However, for the successful compilation of \Dune and \Dumux, it is currently necessary to pass the %As options, switches for the optimization can be set in parts %build system for code by 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 command-line argument to \texttt{dunecontrol}:  David Werner committed Jan 14, 2011 230 231 232  \begin{lstlisting}[style=Bash]  David Werner committed Jan 17, 2011 233 $ # make sure you are in the directory DUNE-Root  David Werner committed Jan 14, 2011 234 235 236 $./dune-common/bin/dunecontrol --configure-opts="CXXFLAGS=-fno-strict-aliasing" all \end{lstlisting}  Klaus Mosthaf committed Feb 23, 2011 237 Too many options can make life hard, that's why usually option-files are being used together with dunecontrol and its sub-tools.  Klaus Mosthaf committed Feb 24, 2011 238 Larger sets of options are kept in them. If you are going to compile with options suited for debugging of the code, the following  David Werner committed Jan 14, 2011 239 240 can be a starting point:  Bernd Flemisch committed Jun 15, 2011 241 %Below in command-line make sure to insert the right name of dumux' root directory, which is in case of installation from tar-files \texttt{dumux-2.0.2} or in case of installation from subversion just \texttt{dumux}. For a developer it is also possible to take options file from \texttt{dumux-devel}.  David Werner committed Jan 14, 2011 242 243  \begin{lstlisting}[style=Bash]  David Werner committed Jan 17, 2011 244 $ # make sure you are in the directory DUNE-Root  David Werner committed Jan 19, 2011 245 246 $cp dumux/debug.opts my-debug.opts # create a personal version$ gedit my-debug.opts # optional editing the options file  David Werner committed Jan 17, 2011 247 $./dune-common/bin/dunecontrol --opts=my-debug.opts all  David Werner committed Jan 14, 2011 248 249 \end{lstlisting}  Klaus Mosthaf committed Feb 23, 2011 250 More optimized code, which is typically not usable for standard debugging tasks, can produced by  David Werner committed Jan 14, 2011 251 252  \begin{lstlisting}[style=Bash]  David Werner committed Jan 17, 2011 253 254 $ cp dumux/optim.opts my-optim.opts $./dune-common/bin/dunecontrol --opts=my-optim.opts all  David Werner committed Jan 14, 2011 255 256 \end{lstlisting}  David Werner committed Jan 19, 2011 257 258 259 260 Sometimes it is necessary to have additional options which are specific to a package set of an operating system or sometimes you have your own preferences. Feel free to work with your own set of options, which may evolve over time.  Klaus Mosthaf committed Feb 23, 2011 261 262 The option files above are more to be understood as a starting point for setting up an own customization than as something which is fixed.  David Werner committed Jan 19, 2011 263 264 The use of external libraries can make it necessary to add quite many options in an option-file. It can be helpful to give your customized option file its own name, as done above.  Klaus Mosthaf committed Feb 24, 2011 265 266 One avoids to confused it with the option files that came out of the distribution and that can be possibly updated by subversion later on.  David Werner committed Jan 17, 2011 267 268 269  \subsection{Building doxygen documentation} \label{sec:build-doxy-doc}  Klaus Mosthaf committed Feb 24, 2011 270 271 272 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 273   Klaus Mosthaf committed Feb 24, 2011 274 Building the doxygen documentation of a module is done as follows, provided the program \texttt{doxygen} is installed:  David Werner committed Jan 19, 2011 275 Set in building options the \texttt{--enable-doxygen} switch.  David Werner committed Jan 17, 2011 276 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 277 278 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 279 280 281 282 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 283   David Werner committed Jan 17, 2011 284 285 286 287 288 289 290 \begin{lstlisting}[style=Bash]$ # change before next command your directory to DUNE-Root $cd dumux/doc/doxygen$ doxygen $firefox html/index.html \end{lstlisting}  David Werner committed Jan 17, 2011 291 292 \subsection{Building documentation of other \Dune modules}  Klaus Mosthaf committed Feb 24, 2011 293 If the \texttt{--enable-documentation} switch has been set in the configure flags of  Klaus Mosthaf committed Feb 23, 2011 294 295 296 297 \texttt{dunecontrol}, this does not necessarily mean that for every \Dune module the documentation is being build. 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 298 it should be possible to build documentation if available.  Klaus Mosthaf committed Feb 23, 2011 299 300 Check in \texttt{module-root-directory/doc/Makefile.am} which targets you can build. E.g., for 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 301 302  \begin{lstlisting}[style=Bash]  David Werner committed Jan 17, 2011 303 $ # change before next command your directory to DUNE-Root  David Werner committed Jan 17, 2011 304 305 306 307 $cd dune-istl/doc$ make istl.pdf \end{lstlisting}  Klaus Mosthaf committed Feb 23, 2011 308 Or for module \texttt{dune-grid-howto} the documentation can be build by:  David Werner committed Jan 19, 2011 309 310 311 312 313 314 315  \begin{lstlisting}[style=Bash] $# change before next command your directory to DUNE-Root$ cd dune-grid-howto/doc $make grid-howto.pdf \end{lstlisting}  Klaus Mosthaf committed Feb 23, 2011 316 This applies for \Dumux too. Rebuilding the handbook can be done as follows:  David Werner committed Jan 19, 2011 317 318 319 320 321 322 323  \begin{lstlisting}[style=Bash]$ cd dumux/doc/handbook $make dumux-handbook.pdf \end{lstlisting}  Klaus Mosthaf committed Feb 23, 2011 324 %At the time writing this to the author no general method of building documentation contained in \Dune's modules is known.  David Werner committed Jan 14, 2011 325 326  %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 327 328  \subsection{External libraries and modules} \label{sec:external-modules-libraries}  David Werner committed Oct 25, 2010 329   Klaus Mosthaf committed Feb 23, 2011 330 The libraries described in the sequel of this paragraph provide additional functionality but are not generally required to run \Dumux.  David Werner committed Jan 19, 2011 331 332 If you are going to use an external library check the information provided on the \Dune website \cite{DUNE-EXT-LIB}. 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 17, 2011 333 %Further information on external modules and libraries seemed to be contained in {\Dune}s Wiki \cite{DUNE-MAIN-WIKI}.  David Werner committed Jan 19, 2011 334 335   Klaus Mosthaf committed Feb 23, 2011 336 337 Installing an external library can require additional libraries which are also used by \Dune. For some libraries, such as BLAS or MPI, multiple versions can be installed on system.  Klaus Mosthaf committed Feb 24, 2011 338 Make sure that it uses the same library as \Dune when configuring the external library.  David Werner committed Jan 19, 2011 339   Klaus Mosthaf committed Feb 23, 2011 340 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 341   Philipp Nuske committed Sep 27, 2010 342 \begin{itemize}  Klaus Mosthaf committed Feb 23, 2011 343 \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 344   Klaus Mosthaf committed Feb 23, 2011 345 346 \item \textbf{ALUGrid}: External library for use as GRID. 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}. It was run successfully in combination with \Dune using \texttt{METIS}. \\ Download: \texttt{\url{http://aam.mathematik.uni-freiburg.de/IAM/Research/alugrid}}  Philipp Nuske committed Sep 27, 2010 347   Klaus Mosthaf committed Feb 23, 2011 348 349 350 \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 351   David Werner committed Jan 19, 2011 352 \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 353   Klaus Mosthaf committed Feb 23, 2011 354 355 356 \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. \\ (\texttt{\url{http://crd.lbl.gov/~xiaoye/SuperLU}}). \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 C++-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 357   David Werner committed Oct 25, 2010 358 359 \end{itemize}  Klaus Mosthaf committed Oct 28, 2010 360 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 361   David Werner committed Oct 25, 2010 362 \begin{itemize}  David Werner committed Jan 19, 2011 363 \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 364   Klaus Mosthaf committed Oct 28, 2010 365 \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 366   David Werner committed Jan 17, 2011 367 \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 368   Klaus Mosthaf committed Feb 23, 2011 369 \item \textbf{GotoBLAS2}: This is an optimized version of BLAS. It covers not always available 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 370 Available by \texttt{\url{http://www.tacc.utexas.edu/tacc-projects/gotoblas2/}}.  David Werner committed Oct 25, 2010 371   Klaus Mosthaf committed Feb 23, 2011 372 373 \item \textbf{METIS}: This is a dependency of ALUGrid, if you are going to run it parallel.  David Werner committed Jan 17, 2011 374 \item \textbf{Compilers}: Beside \texttt{g++} it has been reported that \Dune was successfully build with the Intel C++ compiler.  David Werner committed Jan 17, 2011 375 C and FORTRAN compiler is needed for a 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 376   Klaus Mosthaf committed Feb 23, 2011 377 \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 378 379 % http://openmp.org/  David Werner committed Jan 17, 2011 380 %\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 381 % http://gmplib.org/  David Werner committed Oct 25, 2010 382 \end{itemize}  Klaus Mosthaf committed Oct 21, 2010 383   David Werner committed Jan 19, 2011 384 385 386 387 388 \subsection{Hints for Users from IWS} We provide some features to make life a little bit easier for users from the Institute of Hydraulic Engineering, University of Stuttgart. There exists internally a svn repository made for several external libraries.  Klaus Mosthaf committed Feb 23, 2011 389 If you are allowed to access it, go to the {\Dune}-Root, then do:  David Werner committed Jan 19, 2011 390 \paragraph{prepared external directory}  391   David Werner committed Jan 14, 2011 392 \begin{lstlisting}[style=Bash]  David Werner committed Jan 19, 2011 393 $ # Make sure you are in DUNE-Root  David Werner committed Jan 14, 2011 394 395 $svn checkout svn://svn.iws.uni-stuttgart.de/DUMUX/external/trunk external \end{lstlisting}  396   Klaus Mosthaf committed Oct 27, 2010 397 This directory \texttt{external} contains a script to install external libraries, such as  David Werner committed Jan 19, 2011 398 399 ALBERTA, ALUGrid, UG, METIS and GotoBLAS2:  David Werner committed Jan 14, 2011 400 \begin{lstlisting}[style=Bash]  David Werner committed Jan 19, 2011 401 $ cd external  David Werner committed Jan 14, 2011 402 403 $./installExternal.sh all \end{lstlisting}  David Werner committed Jan 19, 2011 404   Klaus Mosthaf committed Feb 23, 2011 405 It is also possible to install only the actual needed external libraries:  David Werner committed Jan 19, 2011 406   David Werner committed Jan 14, 2011 407 \begin{lstlisting}[style=Bash]  David Werner committed Jan 19, 2011 408 409 $ ./installExternal.sh -h # show, what options this script provide \$ ./installExternal.sh --parallel alu  David Werner committed Jan 14, 2011 410 \end{lstlisting}  411   David Werner committed Jan 19, 2011 412 The libraries are then compiled within that directory and are not installed in a different place.  Klaus Mosthaf committed Feb 24, 2011 413 414 A \Dune build may need to know their location. Thus, one may have to refer to them as options for \texttt{dunecontrol}, for example via the options file \texttt{my-debug.opts}.  David Werner committed Jan 19, 2011 415