From cd8a714d4505c16d7fad71d4a8aa5acfd66fbc8d Mon Sep 17 00:00:00 2001
From: Benjamin Faigle <benjamin.faigle@posteo.de>
Date: Thu, 11 Oct 2012 07:02:26 +0000
Subject: [PATCH] improvement of handbook: - removed all (old) occurrences of
Dumux 2.1 and Dune 2.1 - updated "Flow of things" to version in the AWR Dumux
paper: Included decoupled flow with adaptive gridding. reviewed by Bernd
git-svn-id: svn://svn.iws.uni-stuttgart.de/DUMUX/dumux/trunk@9272 2fb0f335-1f38-0410-981e-8018bf24f1b0
---
doc/handbook/DumuxFlow.tex | 148 +++++++++++++++++-----------
doc/handbook/guidelines.tex | 2 +-
doc/handbook/install.tex | 6 +-
doc/handbook/tutorial-decoupled.tex | 2 +-
4 files changed, 97 insertions(+), 61 deletions(-)
diff --git a/doc/handbook/DumuxFlow.tex b/doc/handbook/DumuxFlow.tex
index ee89510550..ae4eeb2956 100644
--- a/doc/handbook/DumuxFlow.tex
+++ b/doc/handbook/DumuxFlow.tex
@@ -18,70 +18,106 @@ There are extensive comments regarding the formating in the tex file: so feel fr
\section{Structure -- by content}
\label{content}
% by means of this enumerated list, the connection between algorithm and content can be achieved by references to the labels of this list.
-This list shows the algorithmic outline of a typical \Dumux run employing a fully coupled model. Each item stands for a characteristic step within the modeling framework.
+This list shows the algorithmic outline of a typical \Dumux run. Each item stands for a characteristic step within the modeling framework.
\clearpage
+In Figure \ref{fig:algorithm}, the algorithmic representations of both approaches down to the element level are illustrated.
+
+\begin{figure}[hbt]
+\begin{tabular}{ l | l }
+
+\begin{minipage}[t]{0.48\textwidth}
+\setcounter{thingCounter}{0}
+
+\scriptsize
+\sffamily
\begin{tabbing}
-\textbf{\numberThis{main}{init}} \hspace{0.01\textwidth} \=
-\textbf{\numberThis{time step}{prep}} \hspace{0.01\textwidth} \=
-\textbf{\numberThis{Newton step}{elem}} \hspace{0.01\textwidth} \=
-\textbf{\numberThis{Element}{calc}} \hspace{0.01\textwidth} \\
+\textbf{{\begin{turn}{45}\numberThis{main}{init}\end{turn}}} \=
+\textbf{{\begin{turn}{45}\numberThis{time step}{prep}\end{turn}}} \=
+\textbf{{\begin{turn}{45}\numberThis{\textsc{Newton}}{elem}\end{turn}}} \=
+\textbf{{\begin{turn}{45}\numberThis{element}{calc}\end{turn}}} \= \\
\\
initialize \\
-\textbf{for each} time step\\
-
-\> pre-process solution\\
-\> \textbf{for each} \textsc{Newton} iteration \\
-
-\> \> \textbf{for each} element \\
-
-\> \> \> calculate element's local residual \\
-\> \> \> calculate element's \textsc{Jacobian} of local residual \\
-\> \> \> add local residual to global residual vector \\
-\> \> \> add local \textsc{Jacobian} to global \textsc{Jacobian} matrix \\
-
-\> \> \textbf{end for} \\
-
-\> \> solve linear system of equations\\
-\> \> update current iterative solution\\
-\> \> \textbf{if} converged \\
-\> \> \qquad stop \textsc{Newton} iteration\\
-\> \> \textbf{end if} \\
-\> \textbf{endfor}\\
-\> \textbf{if} converged \\
-\> \qquad post-process solution\\
-\> \qquad write result\\
-\> \qquad adapt timestep size \\
-\> \textbf{else if} not converged \\
-\> \qquad retry with half time step size\\
-\> \textbf{end if} \\
-\textbf{end for}\\
-finalize\\
+\textbf{foreach} time step\\
+
+ \> prepare update\\
+ \> \textbf{foreach} \textsc{Newton} iteration \\
+
+ \> \> \textbf{foreach} element \\
+
+ \> \> \> - calculate element \\
+ \>\>\> \; residual vector and \\
+ \>\>\> \; Jacobian matrix\\
+ \> \> \> - assemble into global\\
+ \>\>\> \; residual vector and \\
+ \> \> \> \;{Jacobian} matrix \\
+
+ \> \> \textbf{endfor} \\
+
+ \> \> solve linear system\\
+ \> \> update solution\\
+ \> \> check for \textsc{Newton} convergence\\
+ \> \textbf{endfor}\\
+ \> - adapt time step size, \\
+ \> \; possibly redo with smaller step size\\
+ \> - write result\\
+\textbf{endfor}\\
+finalize
+\end{tabbing}
+
+\end{minipage}
+
+&
+
+\begin{minipage}[t]{0.48\textwidth}
+\setcounter{thingCounter}{0}
+
+\scriptsize
+\sffamily
+\begin{tabbing}
+\textbf{{\begin{turn}{45}1. main\end{turn}}} \=
+\textbf{{\begin{turn}{45}2. time step\end{turn}}} \=
+\textbf{{\begin{turn}{45}3. \textsc{IMPES/C}\end{turn}}} \=
+\textbf{{\begin{turn}{45}4. element\end{turn}}} \= \\
+\\
+initialize \\
+\textbf{foreach} time step\\
+
+ \> prepare update\\
+ \> \textbf{foreach} \textsc{IMPES/C} step \\
+ \> \> \textbf{if} grid is adaptive\\
+ \> \> \> - calculate refinement indicator\\
+ \> \> \> - mark elements, adapt the grid\\
+ \> \> \> - map old solution to new grid\\
+ \> \> - calculate {flow field}\\
+ \> \> \textbf{foreach} element \\
+
+ \> \> \> - calculate element stiffness matrix \\
+ \> \> \> - assemble into global matrix \\
+
+ \> \> \textbf{endfor} \\
+ \> \> solve linear system\\
+
+ \> \> - calculate {transport} \\
+ \> \> \; (saturations, concentrations,...) \\
+ \> \> \textbf{foreach} element \\
+ \> \> \> -calculate update (explicitly) \\
+ \> \> \>- adapt time step ({CFL}-like criterion) \\
+ \> \> \textbf{endfor} \\
+ \> \> - update old solution \\
+ \> \> - postprocess (flash calculation, etc.)\\
+ \> \textbf{endfor}\\
+\> - write result\\
+\textbf{endfor}\\
+finalize
\end{tabbing}
+\end{minipage}
+\end{tabular}
-%% this is tructured by a table propably the new structure (\numberThis{}{} defined in the main document)is intuetivly easier to get
-% \begin{enumerate}[1]
-% \item\label{init} initialize \\
-% \textbf{foreach} timestep
-% \item\label{prep}
-% \hspace*{0.05\textwidth} prepare update\\
-% \hspace*{0.05\textwidth} \textbf{foreach} \textsc{Newton} step
-% \item\label{elem}
-% \hspace*{0.1\textwidth} \textbf{foreach} element
-% \item\label{calc}
-% \hspace*{0.15\textwidth} calculate element \textit{Jacobian}\\
-% \hspace*{0.15\textwidth} assemble into global \textit{Jacobian} matrix \\
-%
-% \hspace*{0.10\textwidth} \textbf{foreach} element calculate element residual \\
-% \hspace*{0.10\textwidth} assemble into global defect\\
-%
-% \hspace*{0.05\textwidth} solve linear system\\
-% \hspace*{0.05\textwidth} update solution\\
-% \hspace*{0.05\textwidth} check for \textsc{Newton} convergence\\
-% \hspace*{0.05\textwidth} adapt timestep, possibly redo with smaller stepsize\\
-% \hspace*{0.05\textwidth} write result\\
-% \end{enumerate}
+\caption{Structure of a coupled fully-implicit (\textbf{left}) and a decoupled semi-implicit (\textbf{right}) scheme in \Dumux.}
+\label{fig:algorithm}
+\end{figure}
\subsection{Levels}
diff --git a/doc/handbook/guidelines.tex b/doc/handbook/guidelines.tex
index e4b3e7d837..aff2a454de 100644
--- a/doc/handbook/guidelines.tex
+++ b/doc/handbook/guidelines.tex
@@ -34,7 +34,7 @@ been written by oneself.
\item Files: Filenames should consist of lower case letters exclusively. Header files get the suffix .hh, implementation files the suffix .cc
\end{itemize}
\item Documentation:
- Dune, as any software project of similar complexity, will stand and fall with the quality of its documentation.
+ \Dumux, as any software project of similar complexity, will stand and fall with the quality of its documentation.
Therefore it is of paramount importance that you document well everything you do! We use the doxygen system to extract easily-readable documentation from the source code. Please use its syntax everywhere. In particular, please comment \textbf{all}
\begin{itemize}
\item Method Parameters (in / out)
diff --git a/doc/handbook/install.tex b/doc/handbook/install.tex
index 15ad03b60a..2692a5ffca 100644
--- a/doc/handbook/install.tex
+++ b/doc/handbook/install.tex
@@ -83,8 +83,8 @@ for debugging: & valgrind &\\
\end{table}
\section{Obtaining source code for \Dune and \Dumux}
-As stated above, the \Dumux release 2.1.0 and trunk (developer tree) are based on the \Dune release 2.1.1,
-comprising the core modules \texttt{dune-common}, \texttt{dune-grid}, \texttt{dune-istl} and \texttt{dune-localfunctions}.
+As stated above, the \Dumux release 2.2.0 and trunk (developer tree) are based on the \Dune release 2.2.0,
+comprising the core modules \texttt{dune-common}, \texttt{dune-grid}, \texttt{dune-geometry}, \texttt{dune-istl} and \texttt{dune-localfunctions}.
% and the external dune module \texttt{dune-pdelab}.
For working with \Dumux, these modules are required.
@@ -150,7 +150,7 @@ $ svn checkout https://svn.dune-project.org/svn/dune-geometry/branches/release-2
$ svn checkout https://svn.dune-project.org/svn/dune-localfunctions/branches/release-2.2 dune-localfunctions
\end{lstlisting}
-The newest and maybe unstable developments are also provided in these repositories in a folder called \emph{trunk}. Please check the \Dune website \cite{DUNE-DOWNLOAD-SVN} for further information. However, the current \Dumux release is based on the stable 2.1 release and it might not compile without further adaptations using the the newest versions of \Dune.
+The newest and maybe unstable developments are also provided in these repositories in a folder called \emph{trunk}. Please check the \Dune website \cite{DUNE-DOWNLOAD-SVN} for further information. However, the current \Dumux release is based on the stable 2.2 release and it might not compile without further adaptations using the the newest versions of \Dune.
The additional module \texttt{dune-grid-howto} is a tutorial which provides information about the \Dune grid interface.
It may give you an idea of how some abstractions in \Dune are done.
diff --git a/doc/handbook/tutorial-decoupled.tex b/doc/handbook/tutorial-decoupled.tex
index fda3ca7cee..74a6768460 100644
--- a/doc/handbook/tutorial-decoupled.tex
+++ b/doc/handbook/tutorial-decoupled.tex
@@ -297,7 +297,7 @@ compile the program.
\end{itemize}
\subsubsection{Exercise 3: Parameter file input.}
-As you have experienced, compilation takes quite some time. Therefore, \Dumux 2.1 provides a simple method to read in parameters (such as simulation end time or modelling parameters) via \texttt{Paramter Input Files}. The tests in the Test-folder \texttt{/test/} already use this system.\\
+As you have experienced, compilation takes quite some time. Therefore, \Dumux provides a simple method to read in parameters (such as simulation end time or modelling parameters) via \texttt{Paramter Input Files}. The tests in the Test-folder \texttt{/test/} already use this system.\\
If you look at the Application in \texttt{/test/boxmodels/2p/}, you see that the main file looks rather empty: The parameter file \texttt{test\_2p.input} is read by a standard start procedure, which is called in the main function. This should be adapted for your problem at hand. The program run has to be called with the parameter file as argument. As this is a basic \Dumux feature, the procedure is the equivalent in the decoupled as in the box models.
In the code, parameters can be read via the macro \texttt{GET\_RUNTIME\_PARAM(TypeTag, Scalar, MyWonderfulGroup.MyWonderfulParameter);}. In \texttt{test\_2p}, \texttt{MyWonderfulGroup} is the group \texttt{SpatialParams} - any type of groups is applicable, if the group definition in the parameter file is enclosed in square brackets. The parameters are then listed thereafter. Try and use as much parameters as possible via the input file, such as lens dimension, grid resolution, soil properties etc. In addition, certain parameters that are specific to the model, such as the \texttt{CFL}-factor, can be assigned in the parameter file without any further action.
--
GitLab