Commit 2a127c66 authored by Thomas Fetzer's avatar Thomas Fetzer
Browse files

[handbook]

Restructured handbook and handbook files as we discussed
it in the handbook meeting. This change is hardly reviewable
so please compile and check whether you miss something in the
new version of the handbook or the structure appears weird.

The models have been removed, because they are just a copy from the
doxygen description and we decided to refer to the doxygen homepage
for a detailed description (which also upgrades doxygen).



git-svn-id: svn://svn.iws.uni-stuttgart.de/DUMUX/dumux/trunk@15030 2fb0f335-1f38-0410-981e-8018bf24f1b0
parent c55c6898
\chapter{Discussion about the new handbook}
BITTE: Fur svn ist es schrecklich eine lange Code-Zeile zu haben, bitte fugt
manuelle Zeilenumbruche hinzu
\todo[inline]{Ihr konnt die todo Befehle benutzen um Dinge zu markieren, die euch
auffallen, dann können wir die beim nachsten Mal besprechen}
\todo[inline]{Bitte schaut mal ob die grobe Kapitelstrukutur stimmt, durch das
umziehen der Dateien, kann sein, das ich etwas beim andern der chapter, sections, etc
vergessen habe. Kann sein, das es dadurch auch etwas unübersichtlich wurde, da
subsubsection zu paragraphs wurden. Wir sollten vllt die Kapitel aufteilen und
dann jeder eines durchgehen.}
\section{Beschlossene ToDos}
\begin{itemize}
\item Umstrukturierung (Thomas)
\item \Dumux aus den Uberschriften in Kap 5 rausnehmen
\item Modelle raus, Liste rein (Christoph)
\item Neues Gitterkapitel (Natalie)
\item Wiki (behandla, Mailing list (LH2), external Modules, lectures, tests
(Vishal), Infos fur neue Doktoranden (Christoph)
\item Hinweis auf tests, lecture und feature list am Ende von Tutorial
\item Doxygen main page - feature list und parameter list
\item Newton etwas ausfuhrlicher und Dumux spezifischer, schematische
Skizze der Matrix (Christoph)
\end{itemize}
\section{Weitere ToDos}
\begin{itemize}
\item Wenn wir einen guten Weg zum Rechtschreibung prüfen finden, ware das sicher
auch gut.
\item Reihenfolge der Unterkapitel
\item Name fur Kapitel 4 und 5
\item man sieht kaum einen Unterschied zwischen subsubsection und paragraphs s.u.
\item wir haben listtings für bash code (ist OK), für c++ und dumux code (sollten
wir schauen wo was benutzt wird und den dumux code entfernen, außerdem wären
Farben ganz nett), dazu könnten wir dann noch ein dumuxInputFile listing
mit anderer Farbgebung (da andere Kommentare) erstellen
\end{itemize}
\subsubsection{subsubsection}
tafsasf mskmf safijsafaSF SAKFMAÖLSFMLDSF
\paragraph{paragraph}
tafsasf mskmf safijsafaSF SAKFMAÖLSFMLDSF
\section{Open Questions}
\begin{itemize}
\item Was kann ins Wiki ausgelagert werden?
\item Was kann ins doxygen ausgelagert werden?
\item Alles was (nicht?) LH2 spezifische raus?
\item Fur listOfProperties und listOfFeatures auf doxygen verweisen! (kommt
unter doxygen main pages)
\item Modelbeschreibungen rausschmeißen?
\item bennenung der ausgelagerten tex dateien mit kapitelnummer (nur eine nummer)
beginnend
\item Neue Kapitel/Abschnitte
\begin{itemize}
\item Wie kann ich Gitter erstellen (externe tools), /einlesen (dune), wo
kann ich bei dune nachschauen. Welche Dateien werden uberhaupt unterstutzt?
in Kap 5 (jemanden finden, der sich auskennt Alex, Timo, Bernd)
\end{itemize}
\item Tutorials:
\begin{itemize}
\item Noch aktuell, noch funktioniert?
\item Welche Features, Modelle brauchten auch ein Tutorial? Wie konnen wir
den Einstieg leicht machen und fur uns den Aufwand gering halten?
\item Verweis auf lecture fur realistischere Anwendungen
\end{itemize}
\end{itemize}
\section{Other}
\subsection{How to move things to stable}
\begin{itemize}
\item mandatory checks
\begin{itemize}
\item remove all warnings (compile e.g. with the pedantic option)
\item are all units given?
\item are all references .g. for model constant, fluids ... given?
\item no tabulators?
\item no trailing whitespaces?
\item is the gnu license still up to date?
\item valgrind?
\item run make headercheck
\end{itemize}
\item optional checks
\begin{itemize}
\item check whether the todos are necessary
\item which lines of code may lead to confusion -> comment them?
\item are the comments necessary and helpful?
\item check and implement the naming conventions from dumux-devel/doc/naminglist
\item are the svn ignore properties set correctly?
\end{itemize}
\item doxygen (mandatory)
\begin{itemize}
\item fill all please doc me placeholders
\item are all public function commented? (minimum level: brief documentation and
explanation of the function parameters)
\item compile doxygen
\end{itemize}
\item for new models
\begin{itemize}
\item no preprocessor macros on the model level
\item integrate the model description into the handbook
\item add a new section in doxygen via the modules.txt
\item check that all equations appear correctly in doxygen
\item check that all class definition are listed, are they also listed in
other groups, where they may be necessary (e.g. fluxvariables)
\item add suitable test problem(s) that tests the main features
\end{itemize}
\item for new problems
\begin{itemize}
\item add a descriptive problem description (e.g. size, BC, what can you see,
where is the example taken from)
\item add reference solution and include in automatic testing
\item are the input files cleaned up (no unnecessary parameters, are the units given,
no unnecessary comments, ...) maybe compare to already existing input files
\item can you see the main features if you run the reference problem
\end{itemize}
\end{itemize}
\ No newline at end of file
\documentclass[11pt,a4paper,headinclude,footinclude,DIV16]{scrreprt}
\usepackage[automark]{scrpage2}
\usepackage[ansinew]{inputenc}
\usepackage[english]{babel}
\usepackage[htt]{hyphenat}
\usepackage[ansinew]{inputenc}
\usepackage[automark]{scrpage2}
\usepackage[normalem]{ulem}
\usepackage{amsmath}
\usepackage{amsfonts}
\usepackage{amssymb}
\usepackage{booktabs}
\usepackage{theorem}
\usepackage[usenames,dvipsnames]{xcolor}
\usepackage{listings}
\usepackage{makeidx}
\usepackage{breakurl}
\usepackage{enumerate}
\usepackage{hyperref}
\usepackage{graphicx}
\usepackage{xspace}
\usepackage[htt]{hyphenat}
\usepackage{layout}
\usepackage{listings}
\usepackage{lscape}
\usepackage{enumerate}
\usepackage{subfig}
\usepackage{units}
\usepackage[hyphens]{url}
\usepackage{tikz}
\usepackage{makeidx}
\usepackage{pdflscape}
\usepackage{textcomp}
\usepackage{rotating}
\usetikzlibrary{arrows,backgrounds,decorations.pathmorphing,patterns,positioning,fit,shapes}
\usepackage[normalem]{ulem}
\usepackage{subfig}
\usepackage{tabularx}
\usepackage{textcomp}
\usepackage{theorem}
\usepackage{tikz}
\usepackage[colorinlistoftodos]{todonotes}
\usepackage{units}
\usepackage{url}
\usepackage{xcolor}
\usepackage{xspace}
\newcommand{\snakeline}{%
% {\uwave{\makebox[\linewidth]{\mbox{}}}}
\uwave{\mbox{}}
}
\usepackage{layout}
\usepackage{hyperref}
\hypersetup{bookmarksdepth=2}
\DeclareGraphicsExtensions{.pdf, .jpg}
% Dune logo
\newcommand{\Dune}{{DUNE}\xspace}
% DuMuX macro
\newcommand{\Dumux}{\texorpdfstring{Du\-Mu$^\text{x}$\xspace}{DuMuX\xspace}}
\newcommand{\DumuxVersion}{2.7}
% DuMuX logo colors
\definecolor{dumuxYellow}{HTML}{E19417}
\definecolor{dumuxBlue}{HTML}{0C73CF}
% beautify C++
\DeclareRobustCommand\Cplusplus{\texorpdfstring{C\nolinebreak[4]\hspace{-.05em}\raisebox{.4ex}{\tiny\bf ++}\xspace}{C++}}
\hypersetup{bookmarksdepth=3}
\usetikzlibrary{arrows,backgrounds,decorations.pathmorphing,patterns,positioning,fit,shapes}
% for listings of C++ code
% for listing of c++ code
\lstset{language=C++, basicstyle=\ttfamily,
keywordstyle=\color{black}\bfseries, tabsize=4, stringstyle=\ttfamily,
commentstyle=\it, extendedchars=true, escapeinside={/*@}{@*/}}
% keywordstyle=\color{black}\bfseries,
tabsize=4, stringstyle=\ttfamily,
% commentstyle=\it,
extendedchars=true, escapeinside={/*@}{@*/},
% keywordstyle=\color[rgb]{0,0,1},
% commentstyle=\color[rgb]{0.026,0.112,0.095},
% stringstyle=\color[rgb]{0.627,0.126,0.941},
numberstyle=\color{cyan},
basicstyle=\ttfamily,
keywordstyle=\color{blue}\ttfamily,
stringstyle=\color{red}\ttfamily,
commentstyle=\color{green}\ttfamily\it,
morecomment=[l][\color{magenta}]{\#}
}
% for listings of bash code in install.tex
\lstdefinestyle{Bash}
{language=Bash,
......@@ -68,6 +72,7 @@
aboveskip=\bigskipamount,
belowskip=\bigskipamount
}
% for listings of DuMuX code
\lstdefinestyle{DumuxCode}
{language=C++,
......@@ -75,15 +80,26 @@
numbers=left,
numberstyle=\tiny,
numbersep=5pt,
breaklines=true,
keywordstyle=\color{dumuxBlue},
stringstyle=\color{Red},
commentstyle=\color{Gray},
morecomment=[l][\color{OliveGreen}]{\#}
breaklines=true
}
\lstset{showstringspaces=false,
breaklines=true}
\lstset{showstringspaces=false, breaklines=true}
\DeclareGraphicsExtensions{.pdf, .jpg}
% Dune logo
\newcommand{\Dune}{{DUNE}\xspace}
% DuMuX logo
\newcommand{\Dumux}{\texorpdfstring{Du\-Mu$^\text{x}$\xspace}{DuMuX\xspace}}
\newcommand{\DumuxVersion}{2.8}
% DuMuX logo colors
\definecolor{dumuxYellow}{HTML}{E19417}
\definecolor{dumuxBlue}{HTML}{0C73CF}
% beautify C++
\DeclareRobustCommand\Cplusplus{\texorpdfstring{C\nolinebreak[4]\hspace{-.05em}\raisebox{.4ex}{\tiny\bf ++}\xspace}{C++}}
% for dumux flow of things
\newcommand{\nextline}{\par\phantom{a}\vspace*{0.1\textwidth}}
\newcommand{\porosity}{\phi}
\newcommand{\saturation}{S}
......@@ -161,21 +177,21 @@ Universit\"at Stuttgart, Paffenwaldring 61, D-70569 Stuttgart, Germany}\\
\maketitle
\setcounter{tocdepth}{1}
\pdfbookmark[0]{Table of Contents}{Table of Contents}
\setcounter{tocdepth}{2}
% \pdfbookmark[0]{Table of Contents}{Table of Contents}
\tableofcontents
\input{intro}
\input{getting-started}
\input{tutorial}
\input{structure}
\input{propertysystem}
\input{fluidframework}
\input{models}
\input{DumuxFlow}
\input{NewtonInANutshell}
\input{TipsNTricks}
\input{install}
\newpage
\pdfbookmark[1]{List of ToDos}{List of ToDos}
% \makeatletter\let\chapter\@undefined\makeatother
\listoftodos
\input{0_discussion}
\input{1_introduction}
\input{2_gettingstarted}
\input{3_tutorial}
\input{4_dumuxoverview}
\input{5_workingwithdumux}
\bibliographystyle{plain}
......
......@@ -26,7 +26,7 @@ achieve minimal overhead when accessing the underlying grid
libraries\footnote{In fact, the performance penalty resulting from the
use of \Dune's grid interface is usually negligible~\cite{BURRI2006}.}.
\begin{figure}[hbt]
\centering
\centering
\includegraphics[width=.5\linewidth, keepaspectratio]{PNG/dunedesign.png}
\caption{
\label{fig:dune-design}
......@@ -63,13 +63,13 @@ finite element shape functions, while \texttt{dune-istl} is the
and provides generic, highly optimized linear algebra routines for
solving the generated systems.
\Dumux comes in form of an additional module \texttt{dumux}.
It depends on the \Dune core modules
\texttt{dune-common}, \texttt{dune-grid}, \texttt{dune-istl}, and on \texttt{dune-localfunctions}.
The main intention of \Dumux is to provide a framework for an easy and efficient
implementation of new physical models for porous media flow problems,
ranging from problem formulation and the selection of
spatial and temporal discretization schemes as well as nonlinear solvers,
to general concepts for model coupling.
Moreover, \Dumux includes ready to use numerical models and a few example applications.
\Dumux comes in form of an additional module \texttt{dumux}.
It depends on the \Dune core modules
\texttt{dune-common}, \texttt{dune-grid}, \texttt{dune-istl}, and on \texttt{dune-localfunctions}.
The main intention of \Dumux is to provide a framework for an easy and efficient
implementation of new physical models for porous media flow problems,
ranging from problem formulation and the selection of
spatial and temporal discretization schemes as well as nonlinear solvers,
to general concepts for model coupling.
Moreover, \Dumux includes ready to use numerical models and a few example applications.
\chapter{Detailed Installation Instructions} \label{install}
In this section about the installation of \Dumux it is assumed that you work with a Linux or Apple OS X 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.
Then, you compile it in that directory tree in which you do the further work, too. You also should know how to install new software packages
or you should have a person on hand who can give you assistance with that. In section \ref{sec:prerequisites} we list some prerequisites for running \Dune and \Dumux.
Please check in said paragraph whether you can fulfill them. In addition, section \ref{sec:external-modules-libraries} provides some 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-INST}.
\section{Detailed Installation Instructions}
\label{install}
\todo[inline]{Dieses Unterkapitel könnte auch kürzer sein}
In this section about the installation of \Dumux it is assumed that you work with
a Linux or Apple OS X 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.
Then, you compile it in that directory tree in which you do the further work, too.
You also should know how to install new software packages
or you should have a person on hand who can give you assistance with that. In
section \ref{sec:prerequisites} we list some prerequisites for running \Dune and \Dumux.
Please check in said paragraph whether you can fulfill them. In addition, section
\ref{sec:external-modules-libraries} provides some 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-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}.
All \Dune modules, including \Dumux, get extracted into a common directory, as it is done in an ordinary \Dune installation.
We refer to that directory abstractly as {\Dune} root directory or, in short, as {\Dune}-Root.
If it is used as directory's path of a shell command it is typed as \texttt{\Dune-Root}.
All \Dune modules, including \Dumux, get extracted into a common directory, as it
is done in an ordinary \Dune installation.
We refer to that directory abstractly as {\Dune} root directory or, in short, 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.
Source code files for each \Dune module are contained in their own subdirectory within {\Dune}-Root.
We name this directory of a certain module \emph{module root directory} or \texttt{module-root-directory} if it is a directory path,
e.\,g. for the module \texttt{dumux} these names are \emph{dumux root directory} respective \texttt{dumux-root-directory}.
The real directory names for the modules can be chosen arbitrarily. In this manual they are the same as the
Source code files for each \Dune module are contained in their own subdirectory
within {\Dune}-Root.
We name this directory of a certain module \emph{module root directory} or
\texttt{module-root-directory} if it is a directory path,
e.\,g. for the module \texttt{dumux} these names are \emph{dumux root directory}
respective \texttt{dumux-root-directory}.
The real directory names for the modules can be chosen arbitrarily. In this manual
they are the same as the
module name or the module name extended by a version number suffix.
The name of each \Dune module is defined in the file \texttt{dune.module}, which is in the root
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.
After extracting the source code for all relevant \Dune modules, including \Dumux, \Dune has to be built
by the shell-command \texttt{dunecontrol} which is part of the \Dune build system.
\section{Prerequisites} \label{sec:prerequisites}
\subsection{Prerequisites} \label{sec:prerequisites}
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 \texttt{make}
must be available in a recent version. For a list of prerequisite software packages to install,see
......@@ -36,17 +49,17 @@ must be available in a recent version. For a list of prerequisite software packa
The building of included documentation like this handbook requires \LaTeX{} and auxiliary tools
\texttt{bibtex}. One usually chooses a \LaTeX{} distribution like \texttt{texlive} for this purpose.
It is possible to switch off the building of the documentation by setting the switch \texttt{--disable-documentation}
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 using \texttt{doxygen}, cf. Section \ref{sec:build-doxy-doc}.
Depending on whether you are going to use external libraries and modules for additional \Dune features,
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}.
Subversion (SVN) and a Git clients must be installed to download modules from Subversion and Git repositories.
\section{Obtaining Source Code for \Dune and \Dumux}
\subsection{Obtaining Source Code for \Dune and \Dumux}
As stated above, the \Dumux release and trunk (developer tree) are based on the most recent
\Dune release 2.3, comprising the core modules dune-common, dune-geometry, dune-grid,
dune-istl and dune-localfunctions. For working with \Dumux, these modules are required. The
......@@ -55,30 +68,35 @@ external module dune-PDELab is recommended and required for several \Dumux featu
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 previous revisions) by direct access
to the software repositories of the revision control system is described in the subsequent part.
Secondly, a method to obtain the most recent source code (or, more generally, any of its previous revisions) by direct access
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 or branches (i.\,e. special names) are means
certain version tags or branches (i.\,e. special names) are means
of the software revision control system to provide access to different versions of the software.
\subsubsection{Obtaining the software by installing tar files}
The slightly old-fashionedly named tape-archive-file, shortly named tar file or tarball, is a common file format for distributing collections of files contained within these archives.
The extraction from the tar files is done as follows:
Download the tarballs from the respective \Dune (version 2.3) and \Dumux websites to a certain folder in your file system.
\paragraph{Obtaining the software by installing tar files}
The slightly old-fashionedly named tape-archive-file, shortly named tar file or
tarball, is a common file format for distributing collections of files contained
within these archives.
The extraction from the tar files is done as follows:
Download the tarballs from the respective \Dune (version 2.3) and \Dumux websites
to a certain folder in your file system.
Create the {\Dune} root directory, named \texttt{dune} in the example below.
Then extract the content of the tar files, e.\,g. with the command-line program \texttt{tar}.
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.
Then extract the content of the tar files, e.\,g. with the command-line program
\texttt{tar}.
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.
After extraction, the actual name of the \emph{dumux root directory} is \texttt{dumux-\DumuxVersion}
(or whatever version you downloaded).
\begin{lstlisting}[style=Bash]
$ mkdir dune
$ cd dune
$ tar xzvf path_to_tarball_of/dune-common-2.3.1.tar.gz
$ tar xzvf path_to_tarball_of/dune-geometry-2.3.1.tar.gz
$ tar xzvf path_to_tarball_of/dune-grid-2.3.1.tar.gz
$ tar xzvf path_to_tarball_of/dune-istl-2.3.1.tar.gz
$ tar xzvf path_to_tarball_of/dune-common-2.3.1.tar.gz
$ tar xzvf path_to_tarball_of/dune-geometry-2.3.1.tar.gz
$ tar xzvf path_to_tarball_of/dune-grid-2.3.1.tar.gz
$ tar xzvf path_to_tarball_of/dune-istl-2.3.1.tar.gz
$ tar xzvf path_to_tarball_of/dune-localfunctions-2.3.1.tar.gz
$ tar xzvf path_to_tarball_of/dune-pdelab-2.0.0.tar.gz
$ tar xzvf path_to_tarball_of/dune-typetree-2.3.1.tar.gz
......@@ -88,15 +106,15 @@ $ tar xzvf path_to_tarball_of/dumux-2.7.tar.gz
Furthermore, if you wish to install the optional \Dune Grid-Howto which provides a tutorial
on the Dune grid interface, act similar.
\subsubsection{Obtaining \Dune and \Dumux from software repositories}
Direct access to a software revision control system for downloading code can be of advantage for the user later on.
\paragraph{Obtaining \Dune and \Dumux from software repositories}
Direct access to a software revision control system for downloading code can be of advantage for the user later on.
It can be easier for him to keep up with code changes and to receive important bug fixes using
the update or pull command of the revision control system. \Dune uses Git and \Dumux uses Apache
Subversion for their software repositories. To access them a certain programs are needed which
is referred to here shortly as Subversion client or Git client. In our description, we use the
Subversion client \texttt{svn} of the Apache Subversion software itself.
In the technical language of Apache Subversion \emph{checking out a certain software version} means nothing more then fetching
In the technical language of Apache Subversion \emph{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.
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
......@@ -105,7 +123,7 @@ into the software repository. This is usually termed as \emph{commit}.
The installation procedure is done as follows:
Create a {\Dune} root directory, named \texttt{dune} in the lines below.
Then, enter the previously created directory and check out the desired modules.
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}.
The \Dune modules of the stable 2.3 release branch are checked out as described
......@@ -152,7 +170,8 @@ Furthermore, if you wish to install the optional \Dune Grid-Howto which provides
on the Dune grid interface, act similar.
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 have also been checked out to. Subsequently, the next command
Its file tree has to be created in the \Dune-Root directory, where the \Dune modules
have also been checked out to. Subsequently, the next command
is executed there, too. The dumux root directory is called \texttt{dumux} here.
\begin{lstlisting}[style=Bash]
......@@ -160,20 +179,20 @@ $ # make sure you are in DUNE-Root
$ svn checkout --username=anonymous --password='' svn://svn.iws.uni-stuttgart.de/DUMUX/dumux/trunk dumux
\end{lstlisting}
\subsubsection{Patching \Dune or external libraries}
\paragraph{Patching \Dune or external libraries}
\label{sc:patchingDUNE}
Patching of \Dune modules in order to work together with \Dumux can be necessary for several reasons.
Software like a compiler or even a standard library
changes at times. But, for example, a certain release of a software component that we depend on,
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.
In the dynamic developing process of software which depends on other modules it is not always feasible
In the dynamic developing process of software which depends on other modules it is not always feasible
to adapt everything to the most recent version of each module. They may fix problems with a certain module
of a certain release without introducing too much structural change.
\Dumux contains patches and documentation about their usage and application within the
\Dumux contains patches and documentation about their usage and application within the
directory \texttt{dumux/patches}.
Please check the README file in that directory for recent information.
In general, a patch can be applied as follows
Please check the README file in that directory for recent information.
In general, a patch can be applied as follows
(the exact command or the used parameters may be slightly different).
We include here an example of a patching dune-grid.
......@@ -183,14 +202,14 @@ $ cd dune-grid
$ patch -p0 < ../dumux/patches/grid-2.3.1.patch
\end{lstlisting}
It can be removed by
It can be removed by
\begin{lstlisting}[style=Bash]
$ path -p0 -R < ../dumux/patches/grid-2.3.1.patch
\end{lstlisting}
The \texttt{checkout-dumux} script also applies patches, if not explicitly requested not to do so.
\subsubsection{Hints for \Dumux-Developers}
\paragraph{Hints for \Dumux-Developers}
If you also want to actively participate in the development of \Dumux, you can allways send patches
to the Mailing list.
......@@ -198,10 +217,10 @@ To get more involved, 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 commit own code and that you can access the \texttt{dumux-devel} module.
This enhances \texttt{dumux} by providing maybe unstable code from the developer group.
A developer usually checks out non-anonymously the modules \texttt{dumux} and \texttt{dumux-devel}.
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 using the commands below. But \texttt{joeuser} needs to be replaced by
the actual user name of the developer for accessing the software repository.
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.
......@@ -215,8 +234,8 @@ choose to store it by subversion in a secure way, e.\,g. together with KDE's KWa
Check the documentation of Subversion for info on how this is done.
A leaked out password can be used by evil persons to abuse a software repository.
\section{Building Documentation}
\subsection{Doxygen}
\subsection{Building Documentation}
\subsubsection{Doxygen}
\label{sec:build-doxy-doc}
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,
......@@ -225,28 +244,29 @@ like class hierarchy of code displayed as graphs, see \cite{DOXYGEN-HP}.
The Doxygen documentation of a module can be built, if \texttt{doxygen} is installed,
by running \texttt{dunecontrol}, entering the \texttt{build-*}directory, and execute
\texttt{make doc}. Then point your web browser to the file
\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}
\subsubsection{Handbook}
To build the \Dumux handbook go into the \texttt{build-}directory and
run \texttt{make doc} or \texttt{make dumux-handbook\_pdf}. The pdf can then be found
in \texttt{MODULE\_BUILD\_DIRECTORY/doc/handbook/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.
\subsection{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 \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.
Installing an external library can require additional libraries which are also used by \Dune.
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.
\subsection{List of External Libraries and Modules}
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.
\subsubsection{List of External Libraries and Modules}
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{ALBERTA}: External grid library. Adaptive multi-level grid manager using bisectioning
......@@ -283,7 +303,8 @@ In the following list, you can find some external modules and external libraries
Download: \texttt{\url{http://www.iwr.uni-heidelberg.de/frame/iwrwikiequipment/software/ug}}
\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.
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
......@@ -302,7 +323,7 @@ The following are dependencies of some of the used libraries. You will need them
is the GNU compiler suite consisting of \texttt{gcc}, \texttt{g++} and \texttt{gfortran}.
\end{itemize}
\subsection{Hints for Users from IWS}
\subsubsection{Hints for Users from IWS}
We provide some features to make life a little bit easier for
users from the Institute for Modelling Hydraulic and Environmental Systems, University of Stuttgart.
There exists internally a Subversion repository made for several external libraries.
......
\chapter{Getting started}
First, we describe a quick installation procedure.
Then a quick start guide for the first \Dumux experience is provided.