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. \\
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.\\
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.
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.
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.
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}.\\
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}
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.
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.
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. \\
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.
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".\\
%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}.
\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}}
\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}.
\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}.
\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}.
\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}}).
\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}}).
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.
\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.
\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.
\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}}.
\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/}}.
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}.
\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.
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}.
