3_detailedinstall.tex

Installing \Dumux means that you first unpack \Dune and \Dumux in a root directory
(section \ref{sc:ObtainingSourceCode}).
In a second step of the installation, all modules are configured with CMake
(section \ref{buildIt}).
After the successful installation of \Dumux, we guide you to start a test application,
described in section \ref{quick-start-guide}.
In section \ref{sec:build-doc}, we explain how to build the \Dumux documentation.
Lastly, section \ref{sec:external-modules-libraries} provides details on optional libraries and modules.

In a technical sense, \Dumux is a module of \Dune.
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-HP}.


\section{Obtaining Source Code for \Dune and \Dumux}
\label{sc:ObtainingSourceCode}
The \Dumux release and trunk (developer tree) are based on the most recent
\Dune release 2.7, comprising the core modules \texttt{dune-common}, \texttt{dune-geometry},
\texttt{dune-grid}, \texttt{dune-istl} and \texttt{dune-localfunctions}.
For working with \Dumux, these modules are required.
All \Dune modules, including the \Dumux module, get extracted into a common root directory, as it
is done in a typical \Dune installation.
We usually name our root directory \texttt{DUMUX}, but an arbitrary name can be chosen.
Source code files for each \Dune module are contained in their own sub-directory within the root directory.
The sub-directories for the modules are named after the module names (depending on how
the modules were obtained, a version number is added to the module name).
The name of each \Dune module is defined in the file \texttt{dune.module}, which is
in the root directory of the respective module. This should not be changed by the user.

In section \ref{sec:prerequisites}, we list some prerequisites for running \Dune and \Dumux.
Please check in said paragraph whether you can fulfill them before continuing.

\paragraph{Obtaining \Dune and \Dumux from software repositories}
\Dune and \Dumux use Git for their software repositories. To access them,
you need to have a working installation of the version control software Git.

In the jargon of Git, \emph{cloning a certain software version} means nothing more then fetching
a local copy from the software repository and laying it out in the file system.
In addition to the software, some more files for the use of the software revision
control system itself are created. (If you have developer access to \Dumux, it is
also possible to do the opposite, i.\,e. to load up a modified revision of software
into the software repository. This is usually termed as \emph{commit} and \emph{push}.)

The download procedure is done as follows:
Create a common root directory, named e.g. \texttt{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.

\begin{lstlisting}[style=Bash,escapechar=\%]
$ mkdir DUMUX
$ cd DUMUX
$ git clone -b releases/2.7 https://gitlab.dune-project.org/core/dune-common.git
$ git clone -b releases/2.7 https://gitlab.dune-project.org/core/dune-geometry.git
$ git clone -b releases/2.7 https://gitlab.dune-project.org/core/dune-grid.git
$ git clone -b releases/2.7 https://gitlab.dune-project.org/core/dune-istl.git
$ git clone -b releases/2.7 https://gitlab.dune-project.org/core/dune-localfunctions.git
$ git clone -b releases/%\DumuxVersion% https://git.iws.uni-stuttgart.de/dumux-repositories/dumux.git
\end{lstlisting}

The newest and maybe unstable developments of \Dune and \Dumux are also provided in these repositories and can be found in the \emph{master} branch.
Please check the \Dune website \cite{DUNE-HP} for further information on the \Dune development. We always try to keep up with the latest developments of \Dune.
However, the current \Dumux release is based on the stable 2.7 release and it might not compile without further adaptations using the newest versions of \Dune.

\section{Building \Dune and \Dumux}
\label{buildIt}
Configuring \Dune and \Dumux is done by the shell-command \texttt{dunecontrol}, which is part of the \Dune build system.
If you are interested in more details about the build system that is used,
they can be found in the \Dune build system documentation\footnote{\url{https://www.dune-project.org/buildsystem/}} and
CMake's documentation\footnote{\url{https://cmake.org/documentation/}}.
If something fails during the execution of \texttt{dunecontrol}, feel free to report it to the \Dune or \Dumux developer mailing list,
but please include error details.

It is possible to compile \Dumux without explicitly passing options to the build system.
However, this will usually not result in the most performant code. A set of default options
that will usually work well is provided with \Dumux in a file and can be passed
to \texttt{dunecontrol}. The following command will configure \Dune and \Dumux
and build all necessary libraries
\begin{lstlisting}[style=Bash]
$ # make sure you are in the common root directory
$ ./dune-common/bin/dunecontrol --opts=dumux/cmake.opts all
\end{lstlisting}

If you are going to compile with modified options, the following
can be a starting point:
\begin{lstlisting}[style=Bash]
$ # make sure you are in the common root directory
$ cp dumux/cmake.opts my-cmake.opts      # create a personal version
$ gedit my-cmake.opts                    # optional editing the options file
$ ./dune-common/bin/dunecontrol --opts=my-cmake.opts all
\end{lstlisting}

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 change over time.
The option file, that comes with the distribution, is to be understood more as a starting point
for setting up own customization than as something which is fixed.
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 a unique name, as done above,
to avoid confusing it with the option files which came out of the distribution.

\section{The First Run of a Test Application}
\label{quick-start-guide}

We recommend the "Getting Started" guide on the \Dumux website: \url{https://dumux.org/gettingstarted/}.
Nevertheless, here is a brief description of how to run a first application.

The previous section showed how to install and compile \Dumux. This section
shall give a very brief introduction on how to run a first test application and how
to visualize the first output files.\par
All executable files are compiled in the \texttt{build} sub-directories of \Dumux.
If not specified differently in the options file, this is \texttt{build-cmake} as default.

\begin{enumerate}
\item Enter the folder \texttt{test/porousmediumflow/2p/incompressible} within your build directory.\\ Type \texttt{make test{\_}2p{\_}incompressible{\_}tpfa}
      in order to compile the application\\\texttt{test{\_}2p{\_}incompressible{\_}tpfa}. To run the simulation,
      type \texttt{./test{\_}2p{\_}incompressible{\_}tpfa params.input}
      into the console.
      The added \texttt{params.input} specifies that all
      important run-time parameters (such as first time step size, end of simulation and location
      of the grid file) can be found in a text file in the same directory  with the
      name \texttt{params.input}.
\item The simulation starts and produces some VTU output files and also a PVD
      file. The PVD file can be used to examine time series and summarizes the VTU
      files. (It is possible to abort a running application by pressing $<$Ctrl$><$c$>$.)
\item You can display the results using the visualization tool ParaView (or
      alternatively VisIt). Just type \texttt{paraview} in the console and open the
      PVD file. On the upper left-hand side, you can choose the desired parameter to be displayed.
\end{enumerate}

\section{Building Documentation}
\label{sec:build-doc}
Building the included documentation like this handbook requires \LaTeX{} and the auxiliary tool
\texttt{bibtex}. One usually chooses a \LaTeX{} distribution like \texttt{texlive} for this purpose.
It is possible to switch off building the documentation by setting the switch \texttt{--disable-documentation}
in the \texttt{CONFIGURE\_FLAGS} of the building options, see section \ref{buildIt}.

\subsection{Doxygen}
\label{sec:build-doxy-doc}
Doxygen documentation is done by specifically formatted comments included in the source code,
which can get extracted by the program \texttt{doxygen}. Besides extracting these comments,
\texttt{doxygen} builds up a web-browsable code-structure documentation
like class hierarchy of code displayed as graphs, see \url{https://www.doxygen.nl/index.html}.

The Doxygen documentation of a module can be built by running \texttt{dunecontrol} (if \texttt{doxygen} is installed), entering the \texttt{build-*}directory, and executing
\texttt{make doc}. Then point your web browser to the file
\texttt{MODULE\_BUILD\_DIRECTORY/doc/doxygen/html/index.html} to read the generated documentation.
This should also work for other \Dune modules.

\subsection{Handbook}
To build the \Dumux handbook, navigate to the \texttt{build-}directory and
run \texttt{make doc} or \texttt{make doc\_handbook\_0\_\\dumux-handbook\_pdf}. The pdf can then be found
in \texttt{MODULE\_BUILD\_DIRECTORY/doc/handbook/0\_dumux\\-handbook.pdf}.

\section{External Libraries and Modules} \label{sec:external-modules-libraries}
The libraries described below 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%
\footnote{DUNE: External libraries, \url{https://www.dune-project.org/doc/external-libraries/}}. You can consult the \Dune website for higher-level \Dune modules, such as Grid Modules
\footnote{DUNE: Grid modules, \url{https://www.dune-project.org/groups/grid/}},
Discretization Modules
\footnote{DUNE: Discretization modules, \url{https://www.dune-project.org/groups/disc/}},
 and Extension Modules
\footnote{DUNE: Extension modules, \url{https://www.dune-project.org/groups/extension/}}.

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 the system.
Make sure that it uses the same library as \Dune when configuring the external library.

Some of the libraries are then compiled within that directory and are not installed in
a different place, but \Dune 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-cmake.opts}.
Make sure you compile the required external libraries before you run \texttt{dunecontrol}.
An easy way to install some of the libraries and modules, given below, is the \texttt{installexternal.py} script located in \texttt{bin}. The script has to be called from your common root directory.


\subsection{List of External Libraries and Modules}
\label{sec:listofexternallibs}

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.

\begin{itemize}
\item \textbf{dune-ALUGrid}: Grid library, comes as a \Dune module.
  The parallel version needs also a graph partitioner, such as {ParMETIS}.
  Download: \url{https://gitlab.dune-project.org/extensions/dune-alugrid}

\item \textbf{dune-foamgrid}: External grid module. One- and two-dimensional grids
  in a physical space of arbitrary dimension; non-manifold grids, growth, element
  paramterizations, and movable vertices. This makes FoamGrid the grid data structure
  of choice for simulating structures such as foams, discrete fracture networks,
  or network flow problems.
  Download: \url{https://gitlab.dune-project.org/extensions/dune-foamgrid}

\item \textbf{opm-grid}: opm-grid is a DUNE module supporting grids in a corner-point format.
  Download: \url{https://github.com/OPM/opm-grid.git} and \url{https://github.com/OPM/opm-common.git}

\item \textbf{dune-subgrid}: The dune-subgrid module is a meta-grid implementation that allows
to mark elements of another hierarchical dune grid and use this sub-grid just like a regular grid.
The set of marked elements can then be accessed as a hierarchical dune grid in its own right.
Dune-Subgrid provides the full grid interface including adaptive mesh refinement.
  Download: \url{https://git.imp.fu-berlin.de/agnumpde/dune-subgrid.git}

\item \textbf{dune-spgrid}: The DUNE module dune-spgrid provides a structured, parallel grid
and supports periodic boundary conditions.
  Download: \url{https://gitlab.dune-project.org/extensions/dune-spgrid.git}

\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.
  Download: \url{http://crd.lbl.gov/~xiaoye/SuperLU}

\item \textbf{UMFPack}: External library for solving linear equations. It is part of SuiteSparse.
  See: \url{http://faculty.cse.tamu.edu/davis/suitesparse.html}. On Debian/Ubuntu you can install the package \texttt{libsuitesparse-dev}.

\item \textbf{dune-UG}: External library for use as grid. UG is a toolbox for unstructured grids, released under GPL.
  To build UG the tools \texttt{lex}/\texttt{yacc} or the GNU variants of \texttt{flex}/\texttt{bison} must be provided.
  Download: \url{https://gitlab.dune-project.org/staging/dune-uggrid}
\end{itemize}

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.

\begin{itemize}
\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} and \texttt{MPICH} in a recent
  version have been reported to work.

\item \textbf{BLAS}: SuperLU 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.

\item \textbf{METIS} and \textbf{ParMETIS}: This are dependencies of ALUGrid and can be used with UG, if run in parallel.

\item \textbf{Compilers}: Beside \texttt{g++}, \Dune can be built with Clang from the LLVM project and
  Intel \Cplusplus compiler. C and Fortran compilers are needed for some external libraries. As code of
  different compilers is linked together, they have to be be compatible with each other.
\end{itemize}

\section{Backwards Compatibility}
\label{sec:backwardscompatibility}

Dumux Releases are split into major (e.g. 2.0, 3.0) and minor (e.g. 3.1, 3.2, 3.3, 3.4) releases.
Major releases are not required to maintain backwards compatibility 
but would provide a detailed guide on updating dependent modules.
For each minor release, maintaining backwards compatibility is strongly encouraged and recommended.

Maintaining backwards compatibility means for all changes made to the dumux master, each tests and all dumux dependent modules should still compile. In addition, the user should be warned at compile time of any relevant interface changes. This can be done by deprecating the old method with a deprecation message and forwarding it to the new method. Examples of this are shown in the \href{https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/blob/master/CONTRIBUTING.md}{contribution guide}. Each of these deprecation messages should also include the release in which the interface will be removed, and all changes should be documented thoroughly in the \href{https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/-/blob/master/CHANGELOG.md}{changelog.md}.

Despite the goal of maintaining backwards compatibility across minor releases,
for more complicated changes, this is to be decided upon on a case-by-case basis, due to limited developer resources.
In the case that implementing full backwards compatibility for an update is not feasible, or would require unreasonable resources, the degree of backwards compatibility will be decided by a vote in one of the monthly core developer meetings.