install.tex 26.2 KB
Newer Older
 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 6 7 8 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. You than compile it in that directory tree and do you further working on there too. You also should know how to install new software packages or you should have a person aside which can give you assistance with the command line and package installation. In section \ref{sec:prerequisites} we list 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 are given. \\  David Werner committed Jan 19, 2011 9   Klaus Mosthaf committed Oct 28, 2010 10 In a technical sense \Dumux is a module of \Dune.  David Werner committed Jan 17, 2011 11 That's why the installation procedure of \Dumux is the same as that of \Dune.  Klaus Mosthaf committed Feb 16, 2011 12 13 14 The details regarding the installation of \Dune are provided on the \Dune website \cite{DUNE-INST}. If you are interested in more details of the build system that is used, you can find them in the {\Dune}'s Build System Howto \cite{DUNE-BS}.\\  Klaus Mosthaf committed Oct 12, 2010 15   David Werner committed Jan 13, 2011 16   Klaus Mosthaf committed Feb 16, 2011 17 As in a \Dune installation, all \Dune modules including \Dumux get extracted into a common directory. We refer to that directory for purpose of documentation 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 filesystem any valid directory name can be chosen.\\  David Werner committed Jan 13, 2011 18   David Werner committed Jan 19, 2011 19 Source code files for each \Dune module are contained in their own subdirectory within {\Dune}-Root.  Klaus Mosthaf committed Feb 16, 2011 20 21 22 We name this directory of a certain module module root directory" or \texttt{module-root-directory} if it is a directory path's, e.g. for module \texttt{dumux} these names are dumux root directory" respective \texttt{dumux-root-directory}. 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 23 module name or the module name extended by a version number suffix.  David Werner committed Jan 17, 2011 24 The name of a \Dune module itself is always defined via the content of file \texttt{dune.module} in its own root  David Werner committed Jan 19, 2011 25 directory, but this should not get changed by an user. The user is allowed to have own files and directories in \Dune-Root, which are not related to \Dune's need.  David Werner committed Jan 13, 2011 26   Klaus Mosthaf committed Feb 16, 2011 27 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 adapted to the needs of \Dune to the GNU build system.  David Werner committed Oct 25, 2010 28   David Werner committed Jan 17, 2011 29 \subsection{Prerequisites} \label{sec:prerequisites}  David Werner committed Jan 17, 2011 30 The GNU tool chain of \texttt{g++} and tools of GNU build system \cite{GNU-BS} also known as GNU autotools  David Werner committed Jan 19, 2011 31 (i.e. \texttt{autoconf}, \texttt{automake}, \texttt{autogen}, \texttt{libtool}) as well as GNU's variant of \texttt{make}  Klaus Mosthaf committed Feb 16, 2011 32 must be available in a recent version. For Ubuntu Linux, e.g., these are contained in the  David Werner committed Jan 17, 2011 33 34 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 35   Klaus Mosthaf committed Feb 16, 2011 36 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 37 \texttt{autoconf} of version $\geqslant$ 2.65, \texttt{autogen} of version $\geqslant$ 5.9.7, \texttt{libtool} of version $\geqslant$ 2.2.6  David Werner committed Jan 17, 2011 38 and GNU \texttt{make} version $\geqslant$ 3.81 should do their job for building \Dumux.\\  David Werner committed Jan 17, 2011 39   Klaus Mosthaf committed Feb 16, 2011 40 \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 41 It is thus necessary to install an appropriate developer package of \texttt{boost}  Klaus Mosthaf committed Feb 16, 2011 42 which is sometimes also named \texttt{libboost}. The matching Ubuntu Linux package is \texttt{libboost-dev}. \\  David Werner committed Jan 17, 2011 43   Klaus Mosthaf committed Feb 16, 2011 44 The building of included documentation like this handbook requires \LaTeX\ and auxiliary tools  David Werner committed Jan 17, 2011 45 like \texttt{dvipdf} and \texttt{bibtex}. One usually chooses a \LaTeX\ distribution like \texttt{texlive} for doing that.  Klaus Mosthaf committed Feb 16, 2011 46 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 as.  David Werner committed Jan 17, 2011 47 Additional parts of documentation are contained in source code files as special formatted comments.  David Werner committed Jan 19, 2011 48 Extracting them can be done by program \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 49 50 51 52  Depending whether you are going to use external libraries and modules for additional \Dune features additional software packages may required. Some hints on that are given in section \ref{sec:external-modules-libraries}.\\  Klaus Mosthaf committed Feb 16, 2011 53 54 For the extraction of the content of tar-files, the GNU version of \texttt{tar} is used. The subversion (SVN) software repositories can be accessed with the help of a subversion client. We recommend the Apache Subversion command-line client \texttt{svn}  David Werner committed Jan 17, 2011 55 contained in Apache Subversion of version $\geqslant$ 1.6.0 \cite{APACHE-SUBVERSION-HP}.  Klaus Mosthaf committed Oct 12, 2010 56   David Werner committed Jan 13, 2011 57 \subsection{Obtaining source code for \Dune and \Dumux}  Klaus Mosthaf committed Feb 16, 2011 58 As written before the \Dumux release 2.0 is based on the \Dune release 2.0, comprising the core modules  David Werner committed Jan 17, 2011 59 \texttt{dune-common}, \texttt{dune-grid}, \texttt{dune-istl}, \texttt{dune-localfunctions} and the external dune  Klaus Mosthaf committed Feb 16, 2011 60 61 module \texttt{dune-pdelab}. Thus, for a proper \Dumux installation these modules are required. Naturally, the external \Dune module \texttt{dumux} is required, too.\\  David Werner committed Jan 13, 2011 62   Klaus Mosthaf committed Feb 16, 2011 63 64 65 66 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. 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. \Dune and \Dumux use Apache Subversion for their software repositories. 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 67   David Werner committed Jan 13, 2011 68 \paragraph{Obtaining the software by installing tar-files}  Klaus Mosthaf committed Feb 16, 2011 69 70 71 72 73 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 in these archives. The extraction from the tar-files is done as follows: Download the tarballs from the respective \Dune (version 2.0) and \Dumux websites to a certain folder in your filesystem. Create the {\Dune} root directory, named below in the examaple DUMUX, then extract the content of the tar-files by the command-line program tar there. 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.  David Werner committed Jan 14, 2011 74 75 76 77 78 79 80 81 82 83 84  \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}  Klaus Mosthaf committed Feb 16, 2011 85 After extraction, the actual dumux root directory's name is \texttt{dumux-2.0}.\\  David Werner committed Jan 19, 2011 86   Klaus Mosthaf committed Feb 16, 2011 87 Furthermore, if you with to install the optional \Dune Grid-Howto:  David Werner committed Jan 14, 2011 88 89 90 91 92  \begin{lstlisting}[style=Bash]$ tar xzvf path_to_tarball_of/dune-grid-howto-2.0.tar.gz \end{lstlisting}  David Werner committed Jan 19, 2011 93 94 However, the required \Dune-module \texttt{dune-pdelab} is not available as tar-file. That's why one has to install it from a software repository by the second method.  Klaus Mosthaf committed Feb 16, 2011 95 If the svn command is available in the command line, it can done as follows:  David Werner committed Jan 19, 2011 96   David Werner committed Jan 14, 2011 97 98 99 \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 100   David Werner committed Jan 13, 2011 101 102 \paragraph{Obtaining \Dune and \Dumux from software repositories}  David Werner committed Jan 19, 2011 103 104 Direct accessing a software revision control system, as Apache Subversion, for downloading code can be of later advantage for an user. It can be easier for him to follow with code changes, through revision control systems update command, as for example to receive important bug fixes. If he takes a revision from a stable branch, with no additional effort, he can be sure to get the latest revision. \\  Bernd Flemisch committed Jul 16, 2010 105   David Werner committed Jan 19, 2011 106 107 To access Apache Subversion software repositories a certain program is needed which is referred here shortly as subversion client. We use in our description the subversion client of the Apache Subversion software itself, which is a command-line tool named \texttt{svn}. Apache Subversion client \texttt{svn} is available for most Linux and UNIX distributions as software package by the distributor.  David Werner committed Jan 13, 2011 108   David Werner committed Jan 17, 2011 109 In technical speech of Apache Subversion checking out a certain software version" means nothing more then fetching  David Werner committed Jan 19, 2011 110 111 it from software repository and laying it out in the filesystem. Additionally with software some more files for use of the software revision control system itself, kept in directories named \texttt{.svn}, are also laid out. For a developer in \Dumux project it is easily possible to do the opposite, i.e. loading up a modified revision of software back into the software repository. This is usually termed as software check in".\\  David Werner committed Jan 13, 2011 112   David Werner committed Jan 19, 2011 113 The installation procedure is done as follows:  David Werner committed Jan 14, 2011 114 Create {\Dune} root directory, named here below DUMUX.  David Werner committed Jan 19, 2011 115 116 117 Then, enter the previously created directory and check out the modules. As you see below the check out uses two different servers for sources one for \Dune and one for {\Dumux}: As described on \Dune's website \cite{DUNE-DOWNLOAD-SVN} we check out the requirered \Dune modules:  David Werner committed Jan 14, 2011 118 119  \begin{lstlisting}[style=Bash]  David Werner committed Jan 17, 2011 120 121 $ mkdir DUMUX $cd DUMUX  David Werner committed Jan 14, 2011 122 123 124 125 126 127 $ 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 128   David Werner committed Jan 19, 2011 129 130 131 The Module \texttt{dune-grid-howto} is a tutorial which aims to give an understanding of the \Dune grid interface. Hopefully it can give you an idea how some abstractions in \Dune are done. The Dune Grid Howto is not required by \Dumux, installing it is purely optional. It is done by:  David Werner committed Jan 14, 2011 132 133 134 135  \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 136   David Werner committed Jan 19, 2011 137 138 139 The needed \texttt{dumux} module is checked out as described on \Dumux website \cite{DUMUX-HP}. Its file tree has to laid out also into \Dune-Root. That's why the next command is excuted in \Dune-Root too.  David Werner committed Jan 13, 2011 140   David Werner committed Jan 14, 2011 141 142 143 \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 144   David Werner committed Jan 19, 2011 145 146 The name of dumux' root directory is this time just \texttt{dumux}.  David Werner committed Jan 13, 2011 147 \paragraph{Hints for \Dumux-Developers}  David Werner committed Jan 19, 2011 148 149 150 151 152 153 154 If you also want activly take part in \Dumux development, you can apply either for full developer access or for developer access on certain parts of \Dumux. Granted developer access means that you are allowed to check in own code and that you can access the \texttt{dumux-devel} module, which enhances \texttt{dumux} by staging code of developer group. A developer ususally checks out non anonymously the modules \texttt{dumux} and \texttt{dumux-devel}. This is done by the commands below. But \texttt{joeuser} needs to replaced by the actual username of developer for accessing the software repository:  David Werner committed Jan 14, 2011 155 156 157 158 159 160  \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 161 162 163 \texttt{Dumux-devel} itself makes use of stable part \texttt{dumux} and hence it needs always together with it being checked out. One can omit in commands above the \texttt{--username} option, if the username for the repository access is identical to the one for the system account.\\  David Werner committed Jan 14, 2011 164   David Werner committed Jan 19, 2011 165 166 167 168 Please choose either not to store the password by subversion in an insecure way or choose to store it by subversion in a secure way like together with \texttt{kwallet} or \texttt{gnomekeyring}. Check the documentation of subversion on how this is being done. A leaked out password can be used by evil persons to abuse a software repository.  Klaus Mosthaf committed Oct 12, 2010 169   David Werner committed Jan 24, 2011 170 171 172 173 174 175 176 177 178 179 \paragraph{checkout-dumux script} The shell-script \texttt{checkout-dumux} facilitates setting up a {\Dune}/{\Dumux} directory tree. It is contained in the download section of \Dumux' webpage \cite{DUMUX-HP}. For example the second line below will check out the required \Dune modules and \texttt{dumux}, \texttt{dumux-devel} and \texttt{external}. \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 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 \subsection{Patching \Dune or external libraries} Patching of \Dune modules in order to work together with \Dumux can be necessary for various reasons. \\ Software like a compiler or even a standard library changes at times. But a certain release of a software-component, we depend on, does not reflect that change. In developing process of software which depends on other modules, it is not always feasible to adapt it to the most recent version of module of the day. That's why for serious errors there exist patches or they are be brought into existence, which fix problems with a certain module of a certain release but do not introduce to much structural change. It can also happen that a release gets amendments (updates) and a formerly useful patch gets obsoleted.\\ \Dumux carries within directory \texttt{dumux/patches} patches and documentation about their usage and application. Please check the README file in that directory for recent informations. At the time of this writing one patch has to applied as follows, but things may vary over time.  David Werner committed Jan 24, 2011 195   David Werner committed Feb 03, 2011 196 197 \begin{lstlisting}[style=Bash] $# make sure you are in DUNE-Root  David Werner committed Feb 03, 2011 198 $ cd dune-istl  David Werner committed Feb 03, 2011 199 200 201 202 $patch -p1 < ../dumux/patches/dune-istl-2.0.patch \end{lstlisting} The \texttt{checkout-dumux} script will also apply patches, if not explicitly requested to do not so.  David Werner committed Jan 24, 2011 203   David Werner committed Jan 14, 2011 204 205 \subsection{Build of \Dune and \Dumux} \label{buildIt}  David Werner committed Jan 19, 2011 206 207 208 209 Building of \Dune is done by \texttt{dunecontrol} as described 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 mailing list, but also try to report also error details. People will likely help you.\\  David Werner committed Jan 14, 2011 210   David Werner committed Jan 19, 2011 211 212 213 214 215 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. As option switches for optimization can switched on 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 216 217 218  \begin{lstlisting}[style=Bash]  David Werner committed Jan 17, 2011 219 $ # make sure you are in the directory DUNE-Root  David Werner committed Jan 14, 2011 220 221 222 $./dune-common/bin/dunecontrol --configure-opts="CXXFLAGS=-fno-strict-aliasing" all \end{lstlisting}  David Werner committed Jan 17, 2011 223 Too many options can make life hard, that's why one usually uses option-files for dunecontrol and its sub-tools.  David Werner committed Jan 19, 2011 224 225 Larger sets of options are kept in them. \\  Benjamin Faigle committed Feb 04, 2011 226 If you are going to compile with options suited for debugging of the code, the following  David Werner committed Jan 14, 2011 227 228 can be a starting point:  David Werner committed Jan 19, 2011 229 %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} 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 230 231  \begin{lstlisting}[style=Bash]  David Werner committed Jan 17, 2011 232 $ # make sure you are in the directory DUNE-Root  David Werner committed Jan 19, 2011 233 234 $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 235 $./dune-common/bin/dunecontrol --opts=my-debug.opts all  David Werner committed Jan 14, 2011 236 237 238 239 240 \end{lstlisting} More optimized code, but which is typically not as useful for standard tasks in debugger can produced by \begin{lstlisting}[style=Bash]  David Werner committed Jan 17, 2011 241 242 $ cp dumux/optim.opts my-optim.opts $./dune-common/bin/dunecontrol --opts=my-optim.opts all  David Werner committed Jan 14, 2011 243 244 \end{lstlisting}  David Werner committed Jan 19, 2011 245 246 247 248 249 250 251 252 253 254 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. Above option files are more to understand as a starting point for setting up an own customization, than as something which is fixed to \Dumux. 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. So one avoids to be confused with option files that came out of distribution and can possible updated by subversion later on.  David Werner committed Jan 17, 2011 255 256 257  \subsection{Building doxygen documentation} \label{sec:build-doxy-doc}  David Werner committed Jan 19, 2011 258 259 Doxygen documentation is done by especially formatted comments in source code, which can get extracted by the program \texttt{doxygen}. Beside extracting these comments, \texttt{doxygen} builds up web-browsable code structure documentation  David Werner committed Jan 17, 2011 260 261 like class hierarchy of code displayed as graphs, see \cite{DOXYGEN-HP}.\\  David Werner committed Jan 19, 2011 262 263 Building a modules doxygen documentation is done as follows provided the program \texttt{doxygen} is installed: Set in building options the \texttt{--enable-doxygen} switch.  David Werner committed Jan 17, 2011 264 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 265 266 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}.  David Werner committed Jan 17, 2011 267 268 269 270 271 You then run within that directory the command \texttt{doxygen}. Point then your web browser to the file \texttt{module-root-directory/doc/doxygen/html/index.html} too read the generated documentation. All here used \Dune-modules except \texttt{dune-grid-howto} so as well \texttt{dumux} contain some doxygen documentation. The external library UG has also a \texttt{doc/doxygen} directory for building its doxygen documentation.  David Werner committed Jan 17, 2011 272 273 274 275 276 277 278 \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 279 280 \subsection{Building documentation of other \Dune modules}  David Werner committed Jan 19, 2011 281 282 283 284 285 286 287 288 289 If the \texttt{--enable-documentation} switch had been set to configure flags of \texttt{dunecontrol}, this means not necessarily that for any \Dune module documentation is being build. But at least Makefiles for building documentation are generated. Provided you run \texttt{dunecontrol} with above option, it should be possible to build documentation if available. Look into \texttt{module-root-directory/doc/Makefile.am} to guess the targets you can build. E.g. for module \texttt{dune-istl} you can build documentation \texttt{istl.pdf} by typing the following in, if you where before in \Dune-Root:  David Werner committed Jan 17, 2011 290 291  \begin{lstlisting}[style=Bash]  David Werner committed Jan 17, 2011 292 $ # change before next command your directory to DUNE-Root  David Werner committed Jan 17, 2011 293 294 295 296 $cd dune-istl/doc$ make istl.pdf \end{lstlisting}  David Werner committed Jan 19, 2011 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 Or for module \texttt{dune-grid-howto} documentation can be build by: \begin{lstlisting}[style=Bash] $# change before next command your directory to DUNE-Root$ cd dune-grid-howto/doc $make grid-howto.pdf \end{lstlisting} But it applies to \Dumux too, rebuilding the handbook can be done as follows: \begin{lstlisting}[style=Bash]$ cd dumux/doc/handbook $make dumux-handbook.pdf \end{lstlisting}  David Werner committed Jan 17, 2011 313 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 314 315  %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 316 317  \subsection{External libraries and modules} \label{sec:external-modules-libraries}  David Werner committed Oct 25, 2010 318   David Werner committed Jan 19, 2011 319 320 321 The following libraries provide additional functionality but are not generally required to run \Dumux. 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 322 %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 323 324 325 326 327 328 329  Installing an external library can require additional libraries which ara also used by \Dune. Of some libraries as for BLAS or MPI there are can be multiple versions installed on system. Make sure that when configuring the external library it uses the same library as \Dune will use.\\ We list here some of external modules and external libraries and some more libraries and tools which get used by them.  David Werner committed Oct 25, 2010 330   Philipp Nuske committed Sep 27, 2010 331 \begin{itemize}  David Werner committed Jan 19, 2011 332 333 \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 userful for multi-physics approaches or domain decomposition methods. Download: \texttt{\url{http://gitorious.org/dune-multidomaingrid}}  David Werner committed Jan 14, 2011 334   David Werner committed Jan 19, 2011 335 \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 336   David Werner committed Jan 19, 2011 337 \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 requirers a FORTRAN compiler \texttt{gfortran}.  Philipp Nuske committed Sep 27, 2010 338   David Werner committed Jan 19, 2011 339 \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}.  Philipp Nuske committed Sep 27, 2010 340   David Werner committed Jan 19, 2011 341 \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 342   David Werner committed Jan 19, 2011 343 \item \textbf{SuperLU}: External library for solving linear equations. 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 344   David Werner committed Oct 25, 2010 345 346 \end{itemize}  Klaus Mosthaf committed Oct 28, 2010 347 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 348   David Werner committed Oct 25, 2010 349 \begin{itemize}  David Werner committed Jan 19, 2011 350 \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 351   Klaus Mosthaf committed Oct 28, 2010 352 \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 353   David Werner committed Jan 17, 2011 354 \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 355   David Werner committed Jan 24, 2011 356 \item \textbf{METIS}: This is a dependency of ALUGrid, if you are going to run it parallel.  David Werner committed Oct 25, 2010 357   David Werner committed Jan 17, 2011 358 359 \item \textbf{GotoBLAS2}: 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.\\ Available by \texttt{\url{http://www.tacc.utexas.edu/tacc-projects/gotoblas2/}}.  David Werner committed Oct 25, 2010 360   David Werner committed Jan 17, 2011 361 \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 362 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 363   David Werner committed Jan 19, 2011 364 \item \textbf{libgomp}: external libraries like ALUGrid when used together with METIS can make use of OpenMP. For that it can be necessary to install the \texttt{libgomp} library.  David Werner committed Oct 25, 2010 365 366 % http://openmp.org/  David Werner committed Jan 17, 2011 367 %\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 368 % http://gmplib.org/  David Werner committed Oct 25, 2010 369 \end{itemize}  Klaus Mosthaf committed Oct 21, 2010 370   David Werner committed Jan 19, 2011 371 372 373 374 375 376 377 \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. If you are allowed to access it: Go to {\Dune}-Root, then do: \paragraph{prepared external directory}  378   David Werner committed Jan 14, 2011 379 \begin{lstlisting}[style=Bash]  David Werner committed Jan 19, 2011 380 $ # Make sure you are in DUNE-Root  David Werner committed Jan 14, 2011 381 382 $svn checkout svn://svn.iws.uni-stuttgart.de/DUMUX/external/trunk external \end{lstlisting}  383   Klaus Mosthaf committed Oct 27, 2010 384 This directory \texttt{external} contains a script to install external libraries, such as  David Werner committed Jan 19, 2011 385 386 ALBERTA, ALUGrid, UG, METIS and GotoBLAS2:  David Werner committed Jan 14, 2011 387 \begin{lstlisting}[style=Bash]  David Werner committed Jan 19, 2011 388 $ cd external  David Werner committed Jan 14, 2011 389 390 $./installExternal.sh all \end{lstlisting}  David Werner committed Jan 19, 2011 391 392 393  it is also possible to install only the actual needed external libraries:  David Werner committed Jan 14, 2011 394 \begin{lstlisting}[style=Bash]  David Werner committed Jan 19, 2011 395 396 $ ./installExternal.sh -h # show, what options this script provide \$ ./installExternal.sh --parallel alu  David Werner committed Jan 14, 2011 397 \end{lstlisting}  398   David Werner committed Jan 19, 2011 399 400 401 The libraries are then compiled within that directory and are not installed in a different place. A \Dune build needs to know, where they are. That's why has to refer to them as options for \texttt{dunecontrol}, for example via options file \texttt{my-debug.opts}.