\section{Installation of \Dumux} \label{install}
\subsection{Preliminary remarks}

In this section about the installion of \Dumux it is assumed that you work on a UNIX compatible operating system and that you are a familiar with the use of a shell. Moreover, you should know,  if necessary, how to install
new software packages or you should have a person aside which can give you assistance with the shell and
the package installation. At the end of this chapter, we list some basic prerequesites for running \Dune and \Dumux. Please check this paragraph to evaluate whether it is possible for you to run \Dune and \Dumux.

In a technical sense \Dumux is a module of \Dune. The installation procedure of \Dumux is strongly related to 
that of \Dune.  Thus, for details of the installation please check also the {\Dune} website \cite{DUNE-HP}. If you are interested in more details of the build-system we refer to the {\Dune}-Build-System-Howto \cite{DUNE-HP}.

As in a \Dune installation, all \Dune modules including the modules for \Dumux as \texttt{dumux} should be extracted into a common directory named {\Dune}-ROOT. Each \Dune module is associated with a directory name in {\Dune}-ROOT. For convenience, this directory name is  also used as an alias for the module name, a practice we will follow here, too.
After installing source code for all requirered \Dune modules including the \Dumux parts
\Dune is being build by the shell-command \texttt{dunecontrol} which is part of {\Dune}-Build-System. The {\Dune}-Build-System is essentially a frontend of the gnu tool autoconf which was specialized for the \Dune project.

\paragraph{Basic prerequisites} \label{prerequisites}
The gnu toolchain of \texttt{g++}  and related gnu variants of developertools like \texttt{libtool}, \texttt{make} and
and \texttt{automake} must be available in a recent version. \Dumux property system (i.e. parts of code) makes use of libboost. It is thus necessary
to install developer version of \texttt{boost}.
The building of documentation requirers latex and auxiliary tools like dvipdf, bibtex (e.g. as of tex-live distribution) installed. Additionally the program convert of package ImageMagick is needed too build the handbook.  If you use configuration-switch --enable-doxygen for documentation you will also need doxygen.

Depending on usage of external libraries the required software packages may vary. Beside the section on external properties below it is a good idea also to check \Dune-Wiki for informations about working with external packages. \\

\subsection{Obtaining \Dune and \Dumux}
Two possibilities exist to obtain \Dune and \Dumux. They can be obtained as so-called tarballs, i.e. \Dumux and \Dune code files of a certain version are packed into tar-archive files for download from the the respective {\Dune} and {\Dumux} website. The shell command \texttt{tar} can be used to extract them on your filesystem. This is explained in the next paragraph. 

\paragraph{Obtaining the software by installing tarballs}
Download the tarballs from the website. You can install the obtained tarballs as follows: Create a \Dune-Root-directory, which we call here DUMUX. For the installation in the shell, type the following commands: 
\begin{itemize}
\item \texttt{mkdir DUMUX}
\item \texttt{cd DUMUX}
\item \texttt{tar xzvf path\_to\_tarball\_of/pde-lab.tar.gz}
\item \texttt{tar xzvf path\_to\_tarball\_of/dumux.tar.gz}
\item \texttt{tar xzvf path\_to\_tarball\_of ...}
\item \texttt{...}
\end{itemize} 

\paragraph{Obtaining \Dune and \Dumux from the SVN repositories} 
The other possibility is to directly access the project archives of \Dune and \Dumux, the so-called software repositories. These are archives of a software version control system named apache subversion. From here on this is referred to as subversion.
You need a subversion client, with which you can access the repositories. This comes with a usual UNIX distribution or can be installed. Our description is limited to a standard subversion shell client realized by the shell command \texttt{svn}.

\paragraph{Checkout of the core modules}
From version 2.0 of \Dune on, it was decided to stick to stable \Dune releases, comprising the core modules 
\texttt{dune-common}, \texttt{dune-grid}, \texttt{dune-istl}, \texttt{dune-localfunctions} and the external \texttt{dune-pdelab}.  
First, create a directory (here, we call it DUMUX) where all the \Dune and \Dumux modules will be stored in. Then, enter the previously created folder and checkout the modules. Checkout means that you get a working copy of the code from the software repository. 
The checkout has to be performed as described on the \Dune webpage, \cite{DUNE-HP}. For the installation in the shell, type the following commands:
\begin{itemize}
\item \texttt{mkdir DUMUX}
\item \texttt{cd DUMUX}
\item \texttt{svn checkout https://svn.dune-project.org/svn/dune-common/releases/2.0 dune-common}
\item \texttt{svn checkout https://svn.dune-project.org/svn/dune-grid/releases/2.0 dune-grid}
\item \texttt{svn checkout https://svn.dune-project.org/svn/dune-istl/releases/2.0 dune-istl}
\item \texttt{svn checkout https://svn.dune-project.org/svn/dune-localfunctions/releases/2.0 dune-localfunctions}
\item \texttt{svn checkout https://svn.dune-project.org/svn/dune-pdelab/branches/2.0snapshot dune-pdelab}
\end{itemize} 

Additionally, it is highly recommended that you also checkout the \texttt{dune-grid} HOWTO by 
\begin{itemize}
\item \texttt{svn checkout https://svn.dune-project.org/svn/dune-grid-howto/releases/2.0 dune-grid-howto}
\end{itemize}
and work yourself through that tutorial in order to get an understanding of the Dune grid interface. 

\paragraph{Checkout of \Dumux}

In order to access an anonymous read-only copy of the stable part of \Dumux from the reposository, the most simple way is to type
\begin{itemize}
\item \texttt{svn checkout --username=anonymous --password='' \\ 
svn://svn.iws.uni-stuttgart.de/DUMUX/dumux/trunk dumux}
\end{itemize}
% On the subversion repository, the \Dumux project is divided into a stable and a developers part, which should stay in separate folders

If you also want to commit new developments to the repositories, you can ask the \Dumux project leader to get developers access fully or in some certain parts. The developer part is only available to people which belong to the \Dumux developer group and have non-anonymous access. If you have developer rights the checkout looks as follows: 
\begin{itemize}
 \item \texttt{svn checkout --username=yourusername \\ 
      \hspace{4cm} svn://svn.iws.uni-stuttgart.de/DUMUX/dumux/trunk dumux}
 \item \texttt{svn checkout --username=yourusername \\
      \hspace{4cm} svn://svn.iws.uni-stuttgart.de/DUMUX/dune-mux/trunk dumux-devel}
\end{itemize} 
The \texttt{dune-devel} makes use of \texttt{dumux} thats why it is also checked out. You can ommit the username option, if the username for the repository access is identical to the one for your system account. Please choose either not to store the password that way or store it by subversion in a secure way, check documentation of subversion for that. A leaked out password can be used by evil persons to vandalize a software repository.
% If you also want to commit new developments or changes to the repositories, you can ask one of the LH$^2$ administrators to add you to the svn group ( \texttt{svndune}).

When using subversion, it is possible, provided that to you are granted developer, i.e. write permissions to repositories, to feed back
your own code or code changes to software repositories. With direct access to software repositories it is also easier for you to keep up with code changes as for important bug fixes or to keep up with general developments of code.


\paragraph{Dune External libraries}

The following libraries provide additional functionality, but are not required to run \Dumux.
If you going to use an external library check information provided on \Dune website.

\begin{itemize}
\item \textbf{UG}: UG is toolbox for Unstructured Grids: for \Dumux is build by autotools and C++-Compiler. Additionally the tools \texttt{lex}/\texttt{yacc} or gnu-versions \texttt{flex}/\texttt{bison} are needed. 

\item \textbf{Alberta}: Adaptive multiLevel finite element toolbox using Bisectioning refinement and Error control by Residual Techniques for scientific Applications: A fortran compiler like \texttt{gfortran} is needed.

\item \textbf{Alugrid}: Alugrid is build by C++-compiler like \texttt{g++}. If you build a parallel version you will need MPI, it was successful run with \texttt{openmpi}. Parallel version need also a graph partitioner, i.e. METIS or PARTY. It was run successfuly in context with \Dune with \texttt{Metis}.


\item \textbf{pardiso} Is a solver for linear equation systems. It is only available as binary.

\item \textbf{SuperLU} Another solver for linear equation systems.

\item \textbf{\Dune multidomaingrid} If you going to run on the same grid different domains or subdomains, this can be a package of choice. To be precise this is an external \Dune module which as \Dumux gets build by \Dune build system, not only external library.
\end{itemize}

These following are dependencies. You will need them depending of which parts of \Dune and external parts you run.
\begin{itemize}
\item \textbf{MPI}: parallel version of \Dune needs MPI also some of the external dependencies when they are going to be build for parallel computing. \texttt{Openmpi} and \texttt{MPICH} in a recent version had been reported to work. 

\item \textbf{lex/yacc} or \textbf{flex/bison}. These are quite common developing tools, code generators for lexical analyser a nd parser.  Is a dependency to UG.

\item \textbf{boost} The Boost-C++-Libraries. Install a developer version. \Dumux property system makes use of libboost also \Dune Multidomaingrid.

\item \textbf{BLAS}: Alberta makes use of BLAS thus install libGOTO, ATLAS, non-optimized BLAS or BLAS by chipmanufacturer. Take care that installation scripts select intended version of BLAS. 

\item \textbf{METIS} Is a dependency to Alugrid, if you run it in parallel, this part is beeing used to partitionate your grid.

\item \textbf{libGOTO} Is an optimized version of BLAS. It's not always available for all architectures and 
its license is not open. For research and education it is possibble to have a copy without additional costs.
A fortran compiler like gfortran is needed to compile it.

\item \textbf{make,autogen,automake,libtool} 
For make use the gnu version of make, the other are also gnu building tools dependencies to build most code of \Dune and \Dumux. Autogen, automake are referred as autools. 

\item \textbf{latex, convert, doxygen} For building \Dumux documentation one will need them. 
Convert is a ImageMagicks image conversion tool. Latex is macro frontend to TeX font setting system, install for example texlive.  Many parts of code documentation is done inline, with doxygen will extract and make html or latex 
from that.

\item \textbf{Compilers} We recommend to use gnu comiler suite, i.e. gcc/g++/gfortran version 4.5 or 4.4. It is also reported that \Dune was successfully build by Intel C++ compiler. \Dune is build by a C++ compiler. The C and Fortran compiler is only needed for few external libraries.

\item \textbf{libgomp} Dune seems makes use of OpenMP. Thus it can be necessary to install it.
% http://openmp.org/

\item \textbf{libgmp} The Gnu Multiple Precision Arithmetic Library (GMP) is also a dependency to \Dune. it might be necessary to install it.
% http://gmplib.org/

\end{itemize}

\paragraph{Hint for IWS Users} User of Institute of Hydraulic Engineering of Stuttgart University 
can also svn check out a repository for external libraries: 

\texttt{svn checkout svn://svn.iws.uni-stuttgart.de/DUMUX/external/trunk external}. \\

This directory \texttt{external} contains a script to install external libraries, i.e. 
alberta, alu, ug it also contains metis and the blas version libGOTO: 
\begin{center}
\texttt{./installExternal.sh all}
\end{center}
it is also possible to install only parts, e.g.:\\ 
\begin{center}
\texttt{./installExternal.sh alberta}
\end{center}

These libraries are then build within this external-directory and not installed in 
a different place. But a dune build still  has to know about where they are.
You have to refer to them as options to \Dune build, e.g. from your options file \texttt{debug.opts}.


\paragraph{Build \Dune and \Dumux}
\label{buildIt}
If you want to compile in the debugging mode, type in the folder \texttt{DUMUX}: 
\begin{center}
\texttt{./dune-common/bin/dunecontrol --opts=\$DUMUX\_ROOT/debug.opts all}
\end{center}

Otherwise you can type
\begin{center}
\texttt{./dune-common/bin/dunecontrol --opts=\$DUMUX\_ROOT/optim.opts all}
\end{center}
in order to get an optimized compilation (better performance, but no possibility to use a debugger).

This uses the \Dune buildsystem. If it does not work, please have a look at the file \texttt{INSTALL} in the \Dumux root directory (if you use SVN, this \texttt{\$DUMUX\_ROOT} is usually \texttt{dumux}, if you use a released version it is usually \texttt{dumux-VERSION}). You can also find more information in the \Dune Buildsystem HOWTO located at the \Dune webpage, \cite{DUNE-HP}.  Alternatively, the tool CMake can be used to build \Dumux. Please check the file \texttt{INSTALL.cmake} for details.
