diff --git a/doc/handbook/DumuxFlow.tex b/doc/handbook/DumuxFlow.tex
index 0e5b3b540c5b46675f1234500a1694e1b1861fda..4d7df5e48439ae644d885e49a1b772f18743a8e0 100644
--- a/doc/handbook/DumuxFlow.tex
+++ b/doc/handbook/DumuxFlow.tex
@@ -9,7 +9,7 @@ Section \ref{implementation} is written from the point of view of the \emph{impl
Section \ref{implementation} is structured by \fbox{boxes} and $\overrightarrow{\textnormal{arrows}}$. Boxes stand for more or less important points in the programm. They may may be reckoned ``step stones''. Likewise, the arrows connect the boxes. If important things happen in between, it is written under the arrows.
-\fbox{Plain boxes} stand for generic parts of the program. \fbox{\fbox{double}} $\lbrace\lbrace$boundings$\rbrace\rbrace$ stand for the implementatin specific part of the program, like \verb+2p, 2p2c...+. This will be the most important part for most users.
+\fbox{Plain boxes} stand for generic parts of the program. \fbox{\fbox{double}} $\lbrace\lbrace$boundings$\rbrace\rbrace$ stand for the implementatin specific part of the program, like \verb+2p, 2p2c...+. This will be the most important part for most users. \uwave{snakelike lines} tell you that this part is specific to the components considered.
For keeping things simple, the program flow of a \verb+2p+ model is shown.
There are extensive comments regarding the formating in the tex file: so feel free, to enhance this description.
@@ -17,7 +17,7 @@ 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 algothimic 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 employing a fully coupled model. Each item stands for a characteristic step within the modeling framework.
\clearpage
\begin{tabbing}
@@ -34,16 +34,13 @@ initialize \\
\> \> \textbf{foreach} element \\
+\> \> \> calculate element residual \\
\> \> \> calculate element \textit{Jacobian}\\
-\> \> \> assemble into global \textit{Jacobian} matrix \\
+\> \> \> assemble local resdidual into global residual \\
+\> \> \> assemble local \textit{Jacobian} into global \textit{Jacobian} matrix \\
\> \> \textbf{endfor} \\
-\> \> \textbf{foreach} element \\
-\> \> \> calculate element residual \\
-\> \> \> assemble into global defect\\
-\> \> \textbf{endfor} \\
-
\> \> solve linear system\\
\> \> update solution\\
\> \> check for \textsc{Newton} convergence\\
@@ -87,12 +84,19 @@ finalize\\
\section{Structure -- by implementation}
\label{implementation}
-This section is supposed to help you in getting an idea how things are handled in \Dumux and in which files things are written down. This is not intuitivly clear, therefore it is mentioned for each \fbox{step-stone}. \textbf{called by} tells you from which file a function is accessed. \textbf{implemented in} tells you in which file the function is written down. The name of the function is set in \verb+typewriter+. Comments regarding the events within one step-stone are set \scriptsize{smaller}.
+This section is supposed to help you in getting an idea how things are handled in \Dumux and in which files things are written down.
+This is not intuitivly clear, therefore it is mentioned for each \fbox{step-stone}. \textbf{called by} tells you from which file a function is
+accessed. \textbf{implemented in} tells you in which file the function is written down. The name of the function is set in \verb+typewriter+.
+Being a function is indicated by round brackets \verb+()+ but only the function name is given and not the full signature (arguments...) .
+ Comments regarding the events within one step-stone are set \scriptsize{smaller}.
+
\begin{landscape}
+%switch off headings and footer in order to get more space for the flowchart
+\pagestyle{empty}
{\small
-
+\setlength{\voffset}{4.2cm}
%%README!!! it is important NOT to leave any blank lines, as multiple boxes are supposed to be in one line
%% Unfortulately, blank lines need to be inserted manually if one box is lapping over the page border
%% by means of \newline, a new line plus some extra space can be inserted, which has unfortunately to be done after each line
@@ -117,32 +121,31 @@ This section is supposed to help you in getting an idea how things are handled i
% \end{array}
% }$
\begin{tabular}{|l|} \hline
- \textbf{\textcircled{\ref{init}}}\verb+problem.simulate()+ \\
- \begin{scriptsize}dealing with t$_{init}$\end{scriptsize}\\
+ \textbf{\textcircled{\ref{init}}}\verb+timeManager.init()+ \\
+ \begin{scriptsize}initialization\end{scriptsize}\\
\textbf{called by}: main() \\
- \textbf{implemented in}: boxproblem.hh \\
+ \textbf{implemented in}: timemanager.hh \\
\hline
\end{tabular}
$\overrightarrow{}$
\begin{tabular}{|l|}\hline
- \textbf{\textcircled{\ref{init}}}\verb+timeManager_runSimulation(*asImp())+\\
+ \textbf{\textcircled{\ref{init}}}\verb+timeManager.run()+\\
\begin{scriptsize}\end{scriptsize}\\
- \textbf{called by}: {boxproblem.hh}\\
+ \textbf{called by}: {main()}\\
\textbf{implemented in}: {timemanager.hh}\\
\hline
\end{tabular}
{\scriptsize
$\overrightarrow{ %an arrow under which things may be written
\begin{array}{l} % in order to be able to write multiple lines under the arrow
- \textbf{\textcircled{\ref{init}}}\textnormal{init stuff}\\
\textnormal{\texttt{while(!finished)}loop}\\
\textbf{\textbf{\textcircled{\ref{init}}}} \rightarrow \textbf{\textcircled{\ref{prep}} }
\end{array}
}$}
\begin{tabular}{|l|}
\hline
- \textbf{\textcircled{\ref{prep}}}\verb+problem.timeIntegration()+ \\
- \begin{scriptsize}\end{scriptsize}\\
+ \textbf{\textcircled{\ref{prep}}}\verb+problem->timeIntegration()+ \\
+ \begin{scriptsize}execute time integration scheme \end{scriptsize}\\
\textbf{called by}: timemanager.hh\\
\textbf{implemented in}: boxproblem.hh\\
\hline
@@ -150,97 +153,110 @@ This section is supposed to help you in getting an idea how things are handled i
\nextline
{\scriptsize$\overrightarrow{
\begin{array}{l}
- \textnormal{``nothing happens''} \\
- \textnormal{just handed over}
+ \textnormal{define \# allowed \textsc{Newton} fails'} \\
+ \textnormal{(each halving dt)}
\end{array}
}$}
\begin{tabular}{|l|}
\hline
- \textbf{\textcircled{\ref{prep}}}\verb+model_.update()+ \\
+ \textbf{\textcircled{\ref{prep}}}\verb+model->update()+ \\
\begin{scriptsize}sth like numerical model\end{scriptsize}\\
\textbf{called by}: boxproblem.hh\\
\textbf{implemented in}: boxscheme.hh\\
\hline
\end{tabular}
- $\overrightarrow{}$
- \begin{tabular}{|l|}
- \hline
- \textbf{\textcircled{\ref{prep}}}\verb+asImp_().updatebegin()+ \\
- \begin{scriptsize}applies Dirichlets\end{scriptsize}\\
- \textbf{called by}: boxscheme.hh\\
- \textbf{implemented in}: boxscheme.hh\\
- \hline
- \end{tabular}
- {\scriptsize$\overrightarrow{
- \begin{array}{l}
- \textnormal{\texttt{while(true)}loop} \\
- \rightarrow \textnormal{until converged}
- \end{array} } $}
+ {\scriptsize$\overrightarrow{ }$}
+% % $\overrightarrow{}$
+% % \begin{tabular}{|l|}
+% % \hline
+% % \textbf{\textcircled{\ref{prep}}}\verb+asImp_().updatebegin()+ \\
+% % \begin{scriptsize}\textbf{applies Dirichlets}\end{scriptsize}\\
+% % \begin{scriptsize}\textbf{not applied here any mroe}\end{scriptsize}\\
+% % \textbf{called by}: boxscheme.hh\\
+% % \textbf{implemented in}: boxscheme.hh\\
+% % \hline
+% % \end{tabular}
+% %
+% % {\scriptsize$\overrightarrow{
+% %\begin{array}{l}
+% % \textnormal{\texttt{while(true)}loop} \\
+% % \rightarrow \textnormal{until converged}
+% % \end{array} } $}
+% %
\begin{tabular}{|l|}
\hline
\textbf{\textcircled{\ref{prep}}}\verb+solver.execute()+ \\
\begin{scriptsize}$\begin{array}{l}
- \textnormal{solver calls, but more than} \\
- \textnormal{just solving happens in here} \\
- \rightsquigarrow\textnormal{solver keeps track of things}
+ \textnormal{not only solving in there: applying \textsc{Newton} method} \\
+ \rightsquigarrow\textnormal{solver keeps track of things}\\
+ \textnormal{catching errors}
\end{array}$\end{scriptsize}\\
- \textbf{called by}: boxscheme.hh\\
- \textbf{implemented in}: boxscheme.hh\\
+ \textbf{called by}: boxmodel.hh\\
+ \textbf{implemented in}: newtonmethod.hh\\
\hline
\end{tabular}
\nextline
- {\scriptsize$\overrightarrow{ \begin{array}{l}
- \texttt{execute()}\\
+ {
+\scriptsize
+$\overrightarrow{ \begin{array}{l}
+ \texttt{execute\_()}\\
\textnormal{in newtonmethod.hh}
\end{array}
}$
$\overrightarrow{ \begin{array}{l}
\textbf{\textcircled{\ref{prep}}} \rightarrow \textbf{\textcircled{\ref{elem}}}\\
\texttt{while(ctl.newtonProceed())}\\
- \textnormal{init}\\
- \textnormal{u} \rightarrow \textnormal{uOld}
+ \textnormal{init: u} \rightarrow \textnormal{uOld, error} \rightarrow \textnormal{lasterror}
\end{array}
- }$}
+ }$
+}
\begin{tabular}{|l|}
\hline
\textbf{\textcircled{\ref{elem}}}\verb+jacobianAsm.assemble()+ \\
- \begin{scriptsize}\end{scriptsize}\\
+ \begin{scriptsize}linearize the problem: \end{scriptsize}\\
+ \begin{scriptsize}collect this elements contribution to global jacobian and global residual\end{scriptsize}\\
\textbf{called by}: newtonmethod.hh\\
- \textbf{implemented in}: assemblerpdelab.hh\\
+ \textbf{implemented in}: pdelabboxassembler.hh\\
\hline
\end{tabular}
+ \nextline
$\overrightarrow{
}$
- \begin{tabular}{|l|}
- \hline
- \textbf{\textcircled{\ref{elem}}}\verb+gridOperatorSpace_->jacobian()+ \\
- \begin{scriptsize}\end{scriptsize}\\
- \textbf{called by}: assemblerpdelab.hh\\
- \textbf{implemented in}: gridoperatorspace.hh\\
+ \begin{tabular}{|l|}
+ \hline
+ \textbf{\textcircled{\ref{elem}}}\verb+resetSystem_()+ \\
+ \begin{scriptsize}always set r.h.s. (i.e. residual) to 0\end{scriptsize}\\
+ \begin{scriptsize}partially set jacbian to zero in case of partial reassembly\end{scriptsize}\\
+ \textbf{called by}: pdelabboxassembler.hh\\
+ \textbf{implemented in}: pdelabboxassembler.hh\\
\hline
\end{tabular}
- \nextline
{\scriptsize$\overrightarrow{\begin{array}{l}
\textbf{\textcircled{\ref{elem}}}\rightarrow\textbf{\textcircled{\ref{calc}}}\\
- \texttt{for(ElementIterator)}
+ \texttt{loop all elements}
\end{array}
}$}
\begin{tabular}{|l|}
\hline
- \textbf{\textcircled{\ref{calc}}}\verb+LocalAssemblerCallSwitch<La,La::doAlphaVolume>::jacobian_volume()+ \\
- \begin{scriptsize}\end{scriptsize}\\
- \textbf{called by}: gridoperatorspace.hh\\
- \textbf{implemented in}: gridoperatorspaceutilities.hh\\
+ \textbf{\textcircled{\ref{calc}}}\verb+assembleElement_()+ \\
+ \begin{scriptsize}call local jacobian and residual assembling\end{scriptsize}\\
+ \textbf{called by}: pdelabboxassembler.hh\\
+ \textbf{implemented in}: pdelabboxassembler.hh\\
\hline
\end{tabular}
\nextline
- $\overrightarrow{
- }$
+ {\scriptsize$\overrightarrow{
+ \begin{array}{l}
+ \textnormal{(if color == red or !partialassembling )}
+ \end{array}
+ }$}
\begin{tabular}{|l|}
\hline
- \textbf{\textcircled{\ref{calc}}}\verb+la.jacobian_volume()+ \\
- \begin{scriptsize}\end{scriptsize}\\
- \textbf{called by}: gridoperatorspaceutilities.hh\\
+ \textbf{\textcircled{\ref{calc}}}\verb+model_().localJacobian().assemble()+ \\
+ \begin{scriptsize}set curr. element, update element's fin.vol.geom.\end{scriptsize}\\
+ \begin{scriptsize}reset local jacobian to 0\end{scriptsize}\\
+ \begin{scriptsize}update types of boundaries on this element\end{scriptsize}\\
+ \textbf{called by}: pdelabboxassembler.hh\\
\textbf{implemented in}: boxjacobianpdelab.hh\\
\hline
\end{tabular}
@@ -248,20 +264,149 @@ This section is supposed to help you in getting an idea how things are handled i
}$
\begin{tabular}{|l|}
\hline
- \textbf{\textcircled{\ref{calc}}}\verb+model_.localJacobian.assemble()+ \\
- \begin{scriptsize}\end{scriptsize}\\
- \textbf{called by}: boxjacobianpdelab.hh\\
- \textbf{implemented in}: boxjacobian.hh\\
+ \textbf{\textcircled{\ref{calc}}}\verb+prevVolVars_.update()+ \\
+ \begin{scriptsize}calls model specific update of vars defined in the volume:\end{scriptsize}\\
+ \begin{scriptsize}vars from \emph{previous timestep!!}\end{scriptsize}\\
+ \textbf{called by}: boxlocaljacobian.hh\\
+ \textbf{implemented in}: boxelementvolumevariables.hh\\
\hline
\end{tabular}
+\nextline
+ $\overrightarrow{
+ }$
+ \begin{tabular}{||l||}
+ \hline\hline
+ \textbf{\textcircled{\ref{calc}}}\verb+update()+ \\
+ \begin{scriptsize}updates all the variables defined in the volume\end{scriptsize}\\
+ \textbf{called by}: boxelementvolumevariables.hh\\
+ \textbf{implemented in}: 2pvolumevariables.hh\\
+ \hline\hline
+ \end{tabular}
+ $\overrightarrow{
+ }$
+ \begin{tabular}{||l||}
+\hline\hline
+ \textbf{\textcircled{\ref{calc}}}\verb+fluidstate_.update()+ \\
+ \begin{scriptsize}calculates all secondary variables from the primary variables\end{scriptsize}\\
+ \textbf{called by}: 2pvolumevariables.hh\\
+ \textbf{implemented in}: 2pfluidstate.hh\\
+\hline\hline
+ \end{tabular}
+\nextline
+ $\overrightarrow{
+ }$
+ \begin{tabular}{||l||}
+\uwave{\mbox{\phantom{\textbf{\textcircled{\ref{calc}}}+ e.g: density\_ = Fluidsystem::phaseDensity()+ bissl}}}
+\\
+ \textbf{\textcircled{\ref{calc}}}\verb+ e.g: density_ = Fluidsystem::phaseDensity()+ \\
+ \begin{scriptsize}The fluidsystem deals with all the compositional stuff: \end{scriptsize}\\
+ \begin{scriptsize}calculating densities, diffusivities ... \end{scriptsize}\\
+ \textbf{called by}: 2pfluidstate.hh\\
+ \textbf{implemented in}: 2p\_system.hh\\
+\uwave{\mbox{\phantom{\textbf{\textcircled{\ref{calc}}}+ e.g: density\_ = Fluidsystem::phaseDensity()+ bissl}}}
+\\
+ \end{tabular}
+ $\overrightarrow{
+ }$
+ \begin{tabular}{|l|}
+ \hline
+ \textbf{\textcircled{\ref{calc}}}\verb+curVolVars_.update()+ \\
+ \begin{scriptsize}calls model specific update of vars defined in the volume:\end{scriptsize}\\
+ \begin{scriptsize}vars from \emph{current iteration step!!}\end{scriptsize}\\
+ \textbf{called by}: boxlocaljacobian.hh\\
+ \textbf{implemented in}: boxelementvolumevariables.hh\\
+ \hline
+ \end{tabular}
+\nextline
+ $\overrightarrow{
+ }$
+ \begin{tabular}{||l||}
+ \hline\hline
+ \textbf{\textcircled{\ref{calc}}}\verb+update()+ \\
+ \begin{scriptsize}updates all the variables defined in the volume\end{scriptsize}\\
+ \textbf{called by}: boxelementvolumevariables.hh\\
+ \textbf{implemented in}: 2pvolumevariables.hh\\
+ \hline\hline
+ \end{tabular}
+ $\overrightarrow{
+ }$
+ \begin{tabular}{||l||}
+\hline\hline
+ \textbf{\textcircled{\ref{calc}}}\verb+fluidstate_.update()+ \\
+ \begin{scriptsize}calculates all secondary variables from the primary variables\end{scriptsize}\\
+ \textbf{called by}: 2pvolumevariables.hh\\
+ \textbf{implemented in}: 2pfluidstate.hh\\
+\hline\hline
+ \end{tabular}
+ \nextline
+ $\overrightarrow{
+ }$
+ \begin{tabular}{||l||}
+\uwave{\mbox{\phantom{\textbf{\textcircled{\ref{calc}}}+ e.g: density\_ = Fluidsystem::phaseDensity()+ bissl}}}
+\\
+ \textbf{\textcircled{\ref{calc}}}\verb+ e.g: density_ = Fluidsystem::phaseDensity()+ \\
+ \begin{scriptsize}The fluidsystem deals with all the compositional stuff: \end{scriptsize}\\
+ \begin{scriptsize}calculating densities, diffusivities ... \end{scriptsize}\\
+ \textbf{called by}: 2pfluidstate.hh\\
+ \textbf{implemented in}: 2p\_system.hh\\
+\uwave{\mbox{\phantom{\textbf{\textcircled{\ref{calc}}}+ e.g: density\_ = Fluidsystem::phaseDensity()+ bissl}}}
+\\
+ \end{tabular}
+ $\overrightarrow{
+ }$
+ \begin{tabular}{|l|}
+ \hline
+ \textbf{\textcircled{\ref{calc}}}\verb+localResidual().eval()+ \\
+ \begin{scriptsize}the residual is calculated: see the next two stepstones\end{scriptsize}\\
+ \textbf{called by}: boxlocaljacobian.hh\\
+ \textbf{implemented in}: boxlocalresidual.hh\\
+ \hline
+ \end{tabular}
+\nextline
+ $\overrightarrow{
+ }$
+ \begin{tabular}{|l|}
+ \hline
+ \textbf{\textcircled{\ref{calc}}}\verb+asImp_().evalFluxes_()+ \\
+ \begin{scriptsize}evaluate the fluxes going in the r.h.s / residual of the \textsc{Newton} scheme\end{scriptsize}\\
+ \begin{scriptsize}how this is done is \fbox{\fbox{model specific}} (see below)\end{scriptsize}\\
+ \textbf{called by}: boxlocalresidual.hh\\
+ \textbf{implemented in}: boxlocalresidual.hh\\
+ \hline
+ \end{tabular}
+ $\overrightarrow{
+ }$
+ \begin{tabular}{|l|}
+ \hline
+ \textbf{\textcircled{\ref{calc}}}\verb+asImp_().evalVolumeTerms_()+ \\
+ \begin{scriptsize}evaluate the sources and storage going in the r.h.s / residual of the \textsc{Newton} scheme\end{scriptsize}\\
+ \begin{scriptsize}how this is done is \fbox{\fbox{model specific}} (see below)\end{scriptsize}\\
+ \textbf{called by}: boxlocalresidual.hh\\
+ \textbf{implemented in}: boxlocalresidual.hh\\
+ \hline
+ \end{tabular}
+\nextline
+ $\overrightarrow{
+ }$
+ \begin{tabular}{|l|}
+ \hline
+ \textbf{\textcircled{\ref{calc}}}\verb+asImp_().evalBoundary_()+ \\
+ \begin{scriptsize}deal with the different boundary conditions\end{scriptsize}\\
+ \begin{scriptsize}may be \fbox{\fbox{model specific}}\end{scriptsize}\\
+ \textbf{called by}: boxlocalresidual.hh\\
+ \textbf{implemented in}: boxlocalresidual.hh (or modelspecific)\\
+ \hline
+ \end{tabular}
$\overrightarrow{
}$
\begin{tabular}{|l|}
\hline
- \textbf{\textcircled{\ref{calc}}}\verb+assemble_()+ \\
- \begin{scriptsize}the Jacobian\end{scriptsize}\\
- \textbf{called by}: boxjacobian.hh\\
- \textbf{implemented in}: boxjacobian.hh\\
+ \textbf{\textcircled{\ref{calc}}}\verb+asImp_().evalPartialDerivative()+ \\
+ \begin{scriptsize}actually calculate the (local) Jacobian matrix\end{scriptsize}\\
+ \begin{scriptsize}a property chooses backward/central/foward differences\end{scriptsize}\\
+ \begin{scriptsize}here: central differences\end{scriptsize}\\
+ \textbf{called by}: boxlocaljacobian.hh\\
+ \textbf{implemented in}: boxlocaljacobian.hh\\
\hline
\end{tabular}
\nextline
@@ -269,23 +414,26 @@ This section is supposed to help you in getting an idea how things are handled i
}$
\begin{minipage}{0.47\textwidth}
\begin{scriptsize}\textnormal{calculation of the Jacobian: numerical differentiation}\end{scriptsize}\\
- \begin{scriptsize}\textnormal{evaluating the old solution at +/- eps dividing by 2eps}\end{scriptsize}\\
- \begin{scriptsize}\textnormal{call the result something like the gradient}\end{scriptsize}\\
+ \begin{scriptsize}\textnormal{adding +/- eps to the old solution, dividing by 2eps}\end{scriptsize}\\
+ \begin{scriptsize}\textnormal{the result is the (local) jacobian matrix}\end{scriptsize}\\
+\begin{scriptsize}\textnormal{(implementation-wise the jacobian is calculated recycling the code for the residual)}\end{scriptsize}\\
$\left \lbrace
\begin{tabular}{l}%these question marks are for the \verb, not meant as ``unclear''
- \verb?asImp_().deflectCurrentSol(+eps)?\\
+ \verb?priVars[pvIdx]+=eps?\\
\begin{scriptsize}\textnormal{this is adding eps to the current solution}\end{scriptsize}\\
- \verb?evalLocalResidual(+eps)?\\
- \begin{scriptsize}\textnormal{evaluating it, having eps added}\end{scriptsize}\\
+ \verb?curVolVars_[scvIdx].update(+eps)?\\
+ \verb?localResidual().eval(+eps)?\\
+ \begin{scriptsize}\textnormal{recalculate terms, having eps added}\end{scriptsize}\\
{\scriptsize $\left. \begin{array}{l}
- \textnormal{- \textbf{storage}}\\
- \textnormal{- \textbf{source}}\\
- \textnormal{- \textbf{flux}} \\
- \end{array}\right\rbrace \overrightarrow{\phantom{definitly one thing, latex was not meant for...}} $} \\
- \verb?restoreSolution()?\\
- \verb?deflect(-eps)?
- \verb?eval(-eps)?
- \verb?restore?
+ \textnormal{- \textbf{computeFlux}}\\
+ \textnormal{- \textbf{computeStorage}}\\
+ \textnormal{- \textbf{computeSource}} \\
+ \end{array}\right\rbrace \overrightarrow{\phantom{a thing latex was not meant for...}} $} \\
+ \verb?store the residual()?\\
+ \verb?priVars[pvIdx]-=eps?\\
+ \verb?update(-eps)?
+ \verb?recalc(-eps)?
+ \verb?construct jacobian from the two residuals: (+eps, -eps) /2 eps done?
\end{tabular}
\right .
$\\
@@ -297,9 +445,9 @@ $\left \lbrace
\begin{scriptsize}\textnormal{\bf \hspace*{0.042\textwidth}seriously: this is where \textbf{flow} is acutally simulated}\end{scriptsize}\\
$\left\lbrace \left\lbrace
\begin{array}{l}
- \textnormal{\textbf{called by}: boxjacobian.hh}\\
+ \textnormal{\textbf{called by}: boxlocaljacobian.hh}\\
\textnormal{\textbf{implemented in}: 2pboxjacobian.hh} \\
- \textnormal{\textbf{\textcircled{\ref{calc}}}} \verb+computeStorage(massContrib, i, false)+ \\
+ \textnormal{\textbf{\textcircled{\ref{calc}}}} \verb+computeStorage(dStorage_dt, i, false)+ \\
\textnormal{\textbf{\textcircled{\ref{calc}}}} \verb+computeStorage(tmp, i, true)+ \\
\textnormal{\begin{scriptsize}TIME DISCRETIZATION in implicit models: using bool for old or new time step\end{scriptsize}}\\
\textnormal{\textbf{\textcircled{\ref{calc}}}} \verb+computeSource()+ \\
@@ -314,234 +462,260 @@ $\left \lbrace
}$}
\begin{tabular}{||l||}
\hline\hline
- \textbf{\textcircled{\ref{calc}}}\verb+FluxData vars()+ \\
- \begin{scriptsize}this a call to a constructor \end{scriptsize}\\
- \textbf{called by}: 2pboxjacobian.hh\\
- \textbf{implemented in}: 2pboxjacobian.hh\\
+ \textbf{\textcircled{\ref{calc}}}\verb+FluxVariables vars()+ \\
+ \begin{scriptsize}this a call to a constructor: \end{scriptsize}\\
+ \begin{scriptsize}calculate the gradients and average the K\end{scriptsize}\\
+ \textbf{called by}: 2plocalresidual.hh\\
+ \textbf{implemented in}: 2pfluxvariables.hh\\
\hline\hline
\end{tabular}
$\overrightarrow{
}$
\begin{tabular}{||l||}
\hline\hline
- \textbf{\textcircled{\ref{calc}}}\verb+TwoPFluxdata+ \\
- \scriptsize{-all relevant gradients are calculated}\\
+ \textbf{\textcircled{\ref{calc}}}\verb+computeAdvectiveFlux()+ (other models: also diffusive)\\
\scriptsize{-all velocities are calculated}\\
- \textbf{called by}: \\
- \textbf{implemented in}: 2pfluxdata.hh\\
+ \textbf{called by}: 2plocalresidual.hh\\
+ \textbf{implemented in}: 2plocalresidual.hh\\
\hline\hline
\end{tabular}
\nextline
$\left|
\begin{array}{l}
- \textnormal{last solution is now}\\
+ \textnormal{current solution (of this iteration ) is now}\\
\textnormal{``numerically differentiated''}\\
\quad \rightarrow \textnormal{the Jacobian is calculated}
\end{array}
\right |$\\
\nextline
- $\overrightarrow{
- }$
- \begin{tabular}{|l|}
- \hline
- \textbf{\textcircled{\ref{calc}}}\verb+evalLocalResiudal(residU, true)+\\
- \begin{scriptsize}this is calculating the r.h.s.\end{scriptsize}\\ \textbf{called by}: boxjacobian.hh\\
- \textbf{implemented in}: boxjacobian.hh \fbox{\fbox{$\rightarrow$flux}}\\
+ {\scriptsize$\overrightarrow{}$ }
+ \begin{tabular}{|l|}
\hline
- \end{tabular}
- $\overrightarrow{
- }$
- \begin{tabular}{|l|}
- \hline
-% \textbf{called by}: boxjacobian.hh\\
-% \textbf{implemented in}: \\
- \textbf{\textcircled{\ref{calc}}}\verb+this->b[][]=residU[][]+ \\
- \begin{scriptsize}assigned to r.h.s.\end{scriptsize}\\\hline
+ \textbf{\textcircled{\ref{calc}}}\verb+assembleElement_()+ \\
+ \begin{scriptsize}The contribution of a single element is done.\end{scriptsize}\\
+ \begin{scriptsize}Now, it needs to be added to the global quantities:\end{scriptsize}\\
+ \begin{scriptsize}Add to global residual and global jacobian.\end{scriptsize}\\
+ \textbf{called by}: continuing in the function. \\
+ \textbf{implemented in}: pdelabboxassembler.hh\\
+ \hline
\end{tabular}
- $\overrightarrow{
- }$
- \begin{tabular}{|l|}
- \hline
- \textbf{\textcircled{\ref{calc}}}\verb+mat(i,j)=+ \\
- \begin{scriptsize}a matrix is being filled\end{scriptsize}\\
-% \textbf{called by}: boxjacobianpdelab.hh\\
- \textbf{implemented in}: boxjacobianpdelab.hh\\
- \hline
- \end{tabular}
- \nextline
- $\overrightarrow{
- }$
- \begin{tabular}{|l|}
- \hline
- \textbf{\textcircled{\ref{calc}}}\verb+jacobian_volume_post_skeleton()+ \\
- \begin{scriptsize}nothing happesn in here\end{scriptsize}\\
-% \textbf{called by}: .hh\\
-% \textbf{implemented in}: \\
+ {\scriptsize$\overrightarrow{
+ \begin{array}{l}
+ \textnormal{partial assembling:}\\
+ \textnormal{if !vertexColor==Green}
+ \end{array} }$ }
+ \begin{tabular}{|l|}
\hline
+ \textbf{\textcircled{\ref{calc}}}\verb?resdidual_[globI]+=? \\
+ \verb? model_().globalJacobian().resdidual(i)? \\
+ \begin{scriptsize}Add to global residual.\end{scriptsize}\\
+ \textbf{called by}: continuing in the function. \\
+ \textbf{implemented in}: pdelabboxassembler.hh\\
+ \hline
\end{tabular}
- $\overrightarrow{
- }$
- \begin{tabular}{|l|}
- \hline
- \textbf{\textcircled{\ref{calc}}}\verb+etadd()+ \\
- \begin{scriptsize}add local Jacobian to global Jacobian\end{scriptsize}\\
- \begin{scriptsize}apply constraints e.g. Bound.Cond.\end{scriptsize}\\ \textbf{called by}: gridoperatorspace.hh\\
- \textbf{implemented in}: gridoperatorspace.hh\\
- \hline
+ \nextline
+ {\scriptsize$\overrightarrow{
+ \begin{array}{l}
+ \textnormal{loop vertices}\\
+ \textnormal{of an element}
+ \end{array}}$}
+ \begin{tabular}{|l|}
+ \hline
+ \textbf{\textcircled{\ref{calc}}}\verb?(*matrix_)[globI][globJ] +=? \\
+ \verb? model_().localJacobian().mat(i,j)? \\
+ \begin{scriptsize}Add to global jacobian.\end{scriptsize}\\
+ \textbf{called by}: continuing in the function. \\
+ \textbf{implemented in}: pdelabboxassembler.hh\\
+ \hline
\end{tabular}
{\scriptsize$\overrightarrow{
- \begin{array}{l}
- \textnormal{J is completely calculated}\\
- \textnormal{\textbf{\textcircled{\ref{calc}}}}\rightarrow\textnormal{\textbf{\textcircled{\ref{elem}}}}
- \end{array}
+ \begin{array}{l}
+ \textbf{\textcircled{\ref{calc}}}\rightarrow\textbf{\textcircled{\ref{elem}}}\\
+ \end{array}
}$}
- \nextline
- \begin{tabular}{|l|}
- \hline
- \textbf{\textcircled{\ref{elem}}}\verb+gridOperatorspace_->residual()+ \\
- \begin{scriptsize}\end{scriptsize}\\
- \textbf{called by}: assemblerpdelab.hh\\
- \textbf{implemented in}: gridoperatorspace.hh\\
+ \begin{tabular}{|l|}
\hline
+ \textbf{\textcircled{\ref{elem}}}\verb?assemble()? \\
+ \begin{scriptsize}Assembling of elements to global quantities is done.\end{scriptsize}\\
+ \begin{scriptsize}In case: print partial assembling stuff\end{scriptsize}\\
+ \textbf{called by}: continuing in the function. \\
+ \textbf{implemented in}: pdelabboxassembler.hh\\
+ \hline
\end{tabular}
- {\scriptsize$\overrightarrow{
- \texttt{for(ElementIterator)}
- }$}
\nextline
- \begin{tabular}{|l|}
- \hline
- \textnormal{\textbf{\textcircled{\ref{elem}}}}$\rightarrow$\textnormal{\textbf{\textcircled{\ref{calc}}}}\verb+LocalAssemblerCallSwitch<La,La::doAlphaVolume>::alpha_volume()+ \\
- \begin{scriptsize}\end{scriptsize}\\
- \textbf{called by}:gridoperatorspace.hh\\
- \textbf{implemented in}: gridoperatorspace.hh\\
+ {$\overrightarrow{}
+ $}
+ \begin{tabular}{|l|}
\hline
+ \textbf{\textcircled{\ref{elem}}}\verb?execute_() , while newtonProceed() ?\\
+ \begin{scriptsize}Print information.\end{scriptsize}\\
+ \begin{scriptsize}start/ stop timer.\end{scriptsize}\\
+ \textbf{called by}: continuing in the function. \\
+ \textbf{implemented in}: newtonmethod.hh\\
+ \hline
\end{tabular}
- $\overrightarrow{
- }$
- \begin{tabular}{|l|}
- \hline
- \textbf{\textcircled{\ref{calc}}}\verb+la.alpha_volume()+ \\
- \begin{scriptsize}\end{scriptsize}\\
- \textbf{called by}:grid..util\\
- \textbf{implemented in}: boxjacobianpdelab.hh\\
+ {\scriptsize$\overrightarrow
+ {\begin{array}{l}
+ \textnormal{set delta Vector to zero} \\
+ \textnormal{(this is what is}\\
+ \textnormal{solved for later)}\\
+ \end{array}}
+ $}
+ \begin{tabular}{|l|}
\hline
+ \textbf{\textcircled{\ref{elem}}}\verb?execute_() , newtonSolveLinear() ?\\
+ \begin{scriptsize}Ask the linear solver to solve the system.\end{scriptsize}\\
+ \begin{scriptsize}i.e. : give jacobian(matrix), delta(u), r.h.s.(residual) to solver (well, newtoncontroller)\end{scriptsize}\\
+ \begin{scriptsize}tricky: each \textsc{Newton}step has a linear solver step. \end{scriptsize}\\
+ \textbf{called by}: continuing in the function. \\
+ \textbf{implemented in}: newtonmethod.hh\\
+ \hline
\end{tabular}
- $\overrightarrow{
- }$
\nextline
- \begin{tabular}{|l|}
- \hline
- \textbf{\textcircled{\ref{calc}}}\verb+model_.localJacobian().evalLocalResidual(localResidual,true)+ \\
- \begin{scriptsize}this computes r.h.s.\end{scriptsize}\\
- \begin{scriptsize}same implementation as for the calculation of the Jacobian\end{scriptsize}\\
- \textbf{called by}:boxjabianpdelab.hh\\
- \textbf{implemented in}: boxjacobian.hh\\
+ {\scriptsize$\overrightarrow{}
+ $}
+ \begin{tabular}{|l|}
+ \hline
+ \textbf{\textcircled{\ref{elem}}}\verb+newtonSolveLinear()+\\
+ \begin{scriptsize}Catching errors.\end{scriptsize}\\
+ \textbf{called by}: newtonmethod.hh\\
+ \textbf{implemented in}: newtoncontroller.hh\\
\hline
- \end{tabular}
- $\overrightarrow{
- }$
- \begin{tabular}{|l|}
- \hline
- \textbf{\textcircled{\ref{calc}}}\verb+r[]=localResidual[][]+ \\
- \begin{scriptsize}store r.h.s.\end{scriptsize}\\
-% \textbf{called by}:\\
-% \textbf{implemented in}: \\
- \hline
\end{tabular}
- $\overrightarrow{
- }$
- \begin{tabular}{|l|}
- \hline
- \textbf{\textcircled{\ref{calc}}}\verb+lambda_volume()+ \\
- \begin{scriptsize}essentially empty\end{scriptsize}\\
-% \textbf{called by}:\\
-% \textbf{implemented in}: \\
- \hline
- \end{tabular}
- \nextline
- {\scriptsize$\overrightarrow{
- \begin{array}{l}
- newtonmethod.hh\\
- \textbf{\textcircled{\ref{calc}}} \rightarrow \textbf{\textcircled{\ref{elem}}}\\
- \textnormal{apply constraints (BC)}
- \end{array}
- }$}
- \begin{tabular}{|l|}
- \hline
- \textbf{\textcircled{\ref{calc}}}\texttt{...ctl.newtonSolveLinear(*jacobianAsm,u*,*(*f))} \\
- \begin{scriptsize}tricky: each \textsc{Newton} step has a lienar solver step (e.g. BiCG)\end{scriptsize}\\
- \textbf{called by}:newtonmethod.hh\\
- \textbf{implemented in}: newtoncontroller.hh\\
+ {\scriptsize$\overrightarrow{}
+ $}
+ \begin{tabular}{|l|}
\hline
- \end{tabular}
- $\overrightarrow{
- }$
- \begin{tabular}{|l|}
- \hline
- \textbf{\textcircled{\ref{calc}}}\verb+solveSequential_(A,*u,b)+ \\
- \begin{scriptsize}sequ. meaning not parallel\end{scriptsize}\\ \textbf{called by}:newtoncontroller.hh\\
- \textbf{implemented in}:newtoncontroller.hh \\
+ \textbf{\textcircled{\ref{elem}}}\verb+solveLinear_()+\\
+ \verb+typedef Dune::PDELab::ISTLBackend_SEQ_BCGS_SSOR Solver;+\\
+ \begin{scriptsize}Selecting Solver (BiCGStab) and preconditioner (SSOR)\end{scriptsize}\\
+ \begin{scriptsize}Instantiate solver object (set max \# iterations, verbosity)\end{scriptsize}\\
+ \textbf{called by}: newtoncontroller.hh\\
+ \textbf{implemented in}: newtoncontroller.hh\\
\hline
\end{tabular}
\nextline
- {\scriptsize$\overrightarrow{
- \begin{array}{l}
- \textnormal{precondition the matrix}\\
- \end{array}
- }$}
- \begin{tabular}{|l|}
- \hline
- \textbf{\textcircled{\ref{calc}}}\verb+Dune::BiCGStabSolver<Vector>solver(opA,precond...)+ \\
- \begin{scriptsize}call to constructor with parameters\end{scriptsize}\\
- \textbf{called by}:newtoncontroller.hh\\
- \textbf{implemented in}: solvers.hh\\
+ {\scriptsize$\overrightarrow{}
+ $}
+ \begin{tabular}{|l|}
\hline
+ \textbf{\textcircled{\ref{elem}}}\verb+solver.apply(A, x, bTmp, residReduction)+\\
+ \begin{scriptsize}Finally handing Matrix, unknowns and r.h.s. to the solver backend.\end{scriptsize}\\
+ \begin{scriptsize}Preconditioning and solving the system. \end{scriptsize}\\
+ \textbf{called by}: newtoncontroller.hh\\
+ \textbf{implemented in}: istlsolverbackend.hh\\
+ \hline
\end{tabular}
- $\overrightarrow{
- }$
- \begin{tabular}{|l|}
- \hline
- \textbf{\textcircled{\ref{calc}}}\verb+solver.apply(x,b,result)+ \\
- \begin{scriptsize}solving linear system of equations\end{scriptsize}\\
- \textbf{called by}:newtoncontroller.hh\\
- \textbf{implemented in}:solvers.hh \\
+ {\scriptsize$\overrightarrow{}
+ $}
+ \begin{tabular}{|l|}
\hline
+ \textbf{\textcircled{\ref{elem}}}\verb+solveLinear_()+\\
+ \begin{scriptsize}dealing with errors, infs, nans \end{scriptsize}\\
+ \textbf{called by}: continuing in function\\
+ \textbf{implemented in}: newtoncontroller.hh\\
+ \hline
\end{tabular}
- $\overrightarrow{
- }$
- \nextline
- \begin{tabular}{|l|}
- \hline
- \textbf{\textcircled{\ref{calc}}}\verb+updateMethod.update()+ \\
- \begin{scriptsize}no clue why this is an update???\end{scriptsize}\\
- \textbf{called by}:newtonmethod.hh\\
- \textbf{implemented in}:newtonmethod.hh \\
+\nextline
+ {\scriptsize$\overrightarrow{}
+ $}
+ \begin{tabular}{|l|}
\hline
+ \textbf{\textcircled{\ref{elem}}}\verb+newtonupdateRelError()+\\
+ \begin{scriptsize}Calculate the error, finding out if we converged to a solution:\end{scriptsize}\\
+ \begin{scriptsize}find the prim. var. that changed most between \end{scriptsize}\\
+ \begin{scriptsize}\quad last(\verb+uOld+) and current (\verb+uNew+) iteration.\end{scriptsize}\\
+ \begin{scriptsize}$\rightsquigarrow$Call this error.\end{scriptsize}\\
+ \textbf{called by}: newtoncontroller.hh\\
+ \textbf{implemented in}: newtoncontroller.hh\\
+ \hline
\end{tabular}
- $\overrightarrow{
- }$
- \begin{tabular}{|l|}
- \hline
- \textbf{\textcircled{\ref{calc}}}\verb+ctl.NewtonEndStep()+ \\
- \begin{scriptsize}increase steps and write to console\end{scriptsize}\\
- \textbf{called by}:newtonmethod.hh\\
- \textbf{implemented in}:newtoncontroller.hh\\
+ {\scriptsize$\overrightarrow{}
+ $}
+ \begin{tabular}{|l|}
\hline
+ \textbf{\textcircled{\ref{elem}}}\verb+ctl.newtonUpdate()+\\
+ \begin{scriptsize}We solved for the change in solution, but need the solution:\end{scriptsize}\\
+ \begin{scriptsize}Calculate current (this iteration) solution\end{scriptsize}\\
+ \begin{scriptsize}\quad from last (iteration) solution and current (iteration) change in solution.\end{scriptsize}\\
+ \begin{scriptsize}If partial assembly: Mark vertices with big changes for reassembly. \end{scriptsize}\\
+ \textbf{called by}: newtonmethod.hh\\
+ \textbf{implemented in}: newtoncontroller.hh\\
+ \hline
\end{tabular}
- {\scriptsize$\overrightarrow{
- \begin{array}{l}
- \textnormal{newtonmethod.hh}\\
- \textbf{\textcircled{\ref{elem}}} \rightarrow \textbf{\textcircled{\ref{prep}}}
- \end{array}
+\nextline
+ {\scriptsize$\overrightarrow{}
+ $}
+ \begin{tabular}{|l|}
+ \hline
+ \textbf{\textcircled{\ref{elem}}}\verb+ctl.newtonEndStep()+\\
+ \begin{scriptsize}Increase counter \textsc{Newton} steps. \end{scriptsize}\\
+ \begin{scriptsize}Print info. \end{scriptsize}\\
+ \textbf{called by}: newtonmethod.hh\\
+ \textbf{implemented in}: newtoncontroller.hh\\
+ \hline
+ \end{tabular}
+ {\scriptsize$\overrightarrow
+ {\begin{array}{l}
+ \textnormal{check in (while) whether \textsc{Newton} proceeds:}\\
+ \textnormal{that is: check if the error is below tolerance or we had too many steps.}\\
+ \end{array}}
+ $}
+ {\scriptsize$\overrightarrow{\begin{array}{l}
+ \textbf{\textcircled{\ref{elem}}}\rightarrow\textbf{\textcircled{\ref{prep}}}\\
+ \textnormal{\textsc{Newton} done.}\\
+ \textnormal{if failed $\rightsquigarrow$ halve timestep size, restart iteration}
+ \end{array}
}$}
+\nextline
\begin{tabular}{|l|}
\hline
- \textbf{\textcircled{\ref{calc}}}\verb+ctl.newtonEnd()+ \\
- \begin{scriptsize}\end{scriptsize}\\
-% \textbf{called by}:\\
-% \textbf{implemented in}: \\
+ \textbf{\textcircled{\ref{prep}}}\verb+ctl.newtonEnd()+ \\
+ \begin{scriptsize}Tell the controller we are done\end{scriptsize}\\
+ \textbf{called by}: newtonmethod.hh\\
+ \textbf{implemented in}: newtoncontroller.hh\\
\hline
\end{tabular}
+ {\scriptsize$\overrightarrow{ }$}
+ \begin{tabular}{|l|}
+ \hline
+ \textbf{\textcircled{\ref{prep}}}\verb+ctl.updateSuccessfull()+ \\
+ \begin{scriptsize}Can be filled by the \fbox{\fbox{model}}.\end{scriptsize}\\
+ \textbf{called by}: boxmodel.hh\\
+ \textbf{implemented in}: newtoncontroller.hh\\
+ \hline
+ \end{tabular}
+ {\scriptsize$\overrightarrow
+ {\begin{array}{l}
+ \textnormal{in while(!finished)}\\
+ \end{array}}
+ $}
+ \begin{tabular}{|l|}
+ \hline
+ \textbf{\textcircled{\ref{prep}}}\verb+postTimeStep()+ \\
+ \begin{scriptsize}Can be filled by the \fbox{\fbox{model}} e.g. calc global storage.\end{scriptsize}\\
+ \textbf{called by}: boxmodel.hh\\
+ \textbf{implemented in}: newtoncontroller.hh\\
+ \hline
+ \end{tabular}
+\nextline
+ {\scriptsize$\overrightarrow{}$}
+ \begin{tabular}{|l|}
+ \hline
+ \textbf{\textcircled{\ref{prep}}}\verb+suggestTimestepSize()+ \\
+ \begin{scriptsize}Determine new size of dt from \# \textsc{Newton} steps. \end{scriptsize}\\
+ \textbf{called by}: timemanager.hh, boxproblem.hh\\
+ \textbf{implemented in}: newtoncontroller.hh\\
+ \hline
+ \end{tabular}
+ {\scriptsize$\overrightarrow
+ {\begin{array}{l}
+ \textnormal{write output}\\
+ \textnormal{uCur $\rightarrow$ uPrev}\\
+ \textnormal{time += dt, timestepIdx++}\\
+ \textnormal{deal with restart and episodes }\\
+ \end{array}}
+ $}
{\scriptsize$\overrightarrow{
\begin{array}{l}
\textnormal{timemanager.hh}\\
@@ -559,7 +733,10 @@ $\left \lbrace
% $\overrightarrow{\scriptsize
% }$
}
-\end{landscape}
-
+\end{landscape}
\normalsize
+
+\newpage
+% Original pagestyle (headings and footer) were switched off, in order to get mroe space for the flowchart.
+\pagestyle{scrheadings}
diff --git a/doc/handbook/TipsNTricks.tex b/doc/handbook/TipsNTricks.tex
index c73f0cadf0613a64ba5922163265dd94fc1aac0d..2f9a82a55961647eee81d836416e44d27a245ace 100644
--- a/doc/handbook/TipsNTricks.tex
+++ b/doc/handbook/TipsNTricks.tex
@@ -2,7 +2,7 @@
This chapter tries to be a useful collection of tips and tricks that can be handy when working with
\Dumux. One of the most prominent ideas for developing DUNE/\Dumux is that reinventing the wheel in terms of FEM-code should
be avoided. We try to follow this idea also in the day-to-day work by stating the \emph{tell us dogma}: ``If you found something useful,
-handy or for other reasons helping when working with \Dumux: put it into this chapter.'' (or at least write it to the mailing list \\ \verb+dumux@iws.uni-stuttgart.de so somebody else can+).
+handy or for other reasons helping when working with \Dumux: put it into this chapter.'' (or at least write it to the mailing list \\ \verb+dumux@iws.uni-stuttgart.de+ so somebody else can).
\begin{itemize}
\item Using the \Dumux-Eclipse profile:
diff --git a/doc/handbook/designpatterns.tex b/doc/handbook/designpatterns.tex
index 68da24f338133a27a069016aa17eaf4144e54903..6ae714b5de14b5a32076cbb653ad1eb265054a6f 100644
--- a/doc/handbook/designpatterns.tex
+++ b/doc/handbook/designpatterns.tex
@@ -41,7 +41,7 @@ only ``clean'' way to achive this without templates would be to copy
\texttt{value} attribute. It is obvious that this is a very
cumbersome, error-prone and unproductive process. For this reason,
recent standards of the C++ programming language specify the template
-mechanism, which is a way let the compiler do the tedious work. Using
+mechanism, which is a way to let the compiler do the tedious work. Using
templates, a generic linked list can be implemented like this:
\begin{lstlisting}[basicstyle=\ttfamily\scriptsize,numbers=left,numberstyle=\tiny, numbersep=5pt]
template <class ValueType>
@@ -122,13 +122,13 @@ executed is dynamically determined at run time.
\begin{example}
\label{example:DynPoly}
A class called \texttt{Car} could feature the methods
- \texttt{gasUsage}, which by default corrosponds to the current
- $CO_2$ emission goal of the European Union but can be changed by
+ \texttt{gasUsage}, which by default corresponds to the current
+ $CO_2$ emission goal of the European Union -- line \ref{designpatterns:virtual-usage} -- but can be changed by
classes representing actual cars. Also, a method called
\texttt{fuelTankSize} makes sense for all cars, but since there is
- no useful default, its \texttt{vtable} entry is set to $0$ in the
- base class. This tells the compiler that it is mandatorily that this
- method gets defined in derived classes. Finally, the method
+ no useful default, its \texttt{vtable} entry is set to $0$ -- line \ref{designpatterns:totally-virtual} -- in the
+ base class. This tells the compiler that it is mandatory for this
+ method to be defined in derived classes. Finally, the method
\texttt{range} may calculate the expected remaining kilometers the
car can drive given a fill level of the fuel tank. Since the
\texttt{range} method can retrieve information it needs, it does not
@@ -138,8 +138,8 @@ executed is dynamically determined at run time.
class Car
{public:
virtual double gasUsage()
- { return 4.5; };
- virtual double fuelTankSize() = 0;
+ { return 4.5; };/*@\label{designpatterns:virtual-usage}@*/
+ virtual double fuelTankSize() = 0;/*@\label{designpatterns:totally-virtual}@*/
double range(double fuelTankFillLevel)
{ return 100*fuelTankFillLevel*fuelTankSize()/gasUsage(); }
@@ -388,7 +388,7 @@ order to keep the code maintainable.
\section{Traits Classes}
A classic approach to reduce the number of template parameters is to
-gather the all arguments in a special class, a so-called traits
+gather all the arguments in a special class, a so-called traits
class. Instead of writing
\begin{lstlisting}[basicstyle=\ttfamily\scriptsize,numbers=left,numberstyle=\tiny, numbersep=5pt]
template <class A, class B, class C, class D>
@@ -412,7 +412,7 @@ struct MyTraits
\end{lstlisting}
\noindent
-As there is no a free lunch, the traits approach comes with a few
+As there is no free lunch, the traits approach comes with a few
disadvantages of its own:
\begin{enumerate}
\item Hierarchies of traits classes are problematic. This is due to
@@ -448,7 +448,7 @@ int main() {
}
\end{lstlisting}
Contrary to what is intended, \texttt{v} is a vector of integers. This
-problem cannot also be solved using static polymorphism, since it
+problem can also not be solved using static polymorphism, since it
would lead to a cyclic dependency between \texttt{MyBaseTraits} and
\texttt{MyDoubleTraits}.
diff --git a/doc/handbook/dumux-handbook.tex b/doc/handbook/dumux-handbook.tex
index 18ef5a705a9d26125616dccc402f0590fa783f0d..06d466394eab931db394ca0fdf46242cce5ceed3 100644
--- a/doc/handbook/dumux-handbook.tex
+++ b/doc/handbook/dumux-handbook.tex
@@ -21,6 +21,17 @@
\usepackage{rotating}
\usepackage{subfig}
+\usepackage{ulem}
+\usepackage{tabularx}
+\usepackage{graphics}
+\usepackage{pstricks}
+\newcommand{\snakeline}{%
+% {\uwave{\makebox[\linewidth]{\mbox{}}}}
+\uwave{\mbox{}}
+}
+\usepackage{layout}
+
+
%\usepackage{ngerman}
\usepackage[english]{babel}
diff --git a/doc/handbook/install.tex b/doc/handbook/install.tex
index 3e5faaf5a84030946dda6a81c4fe4849720dc2b8..064ff0e3595ac209f4bbe0b15e961c47e3e8c836 100644
--- a/doc/handbook/install.tex
+++ b/doc/handbook/install.tex
@@ -29,7 +29,7 @@ Beside the section on external modules below it is a good idea to check the {\Du
\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.
+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 respective {\Dune} and {\Dumux} website.
The shell command \texttt{tar} can be used to extract them on your file system. This is explained in the next paragraph.
\paragraph{Obtaining the software by installing tarballs}
@@ -85,7 +85,7 @@ In order to obtain an anonymous read-only copy of the stable part of \Dumux from
If you also want to commit new developments to the repositories, you can ask the \Dumux project leader to get either full developers access or access for certain parts of \Dumux.
The developer part \texttt{dumux-devel} is only available for people who belong to the \Dumux developer group and have non-anonymous access to the subversion repositories.
-If you have developer rights the checkout looks as follows:
+If you have developer rights the checkout looks as follows (system administrators will have to add you to the developer group and give you a password for this access):
\begin{itemize}
\item \texttt{svn checkout --username=yourusername \\
\hspace{4cm} svn://svn.iws.uni-stuttgart.de/DUMUX/dumux/trunk dumux}
@@ -174,7 +174,7 @@ But a \Dune build still needs to know where they are. You have to refer to them
\paragraph{Build \Dune and \Dumux}
\label{buildIt}
-To compile \Dumux with out additional options file, type in the {\Dune}-Root-directory (called \texttt{DUMUX} before):
+To compile \Dumux without additional options file, type in the {\Dune}-Root-directory (called \texttt{DUMUX} before):
\begin{center}
\texttt{./dune-common/bin/dunecontrol all}
\end{center}
diff --git a/doc/handbook/intro.tex b/doc/handbook/intro.tex
index 184250df49a60fc021402a49a6bd5c6502fa5340..02eadcf46c968ced7a5c0256a370b8b0aa0cfb43 100644
--- a/doc/handbook/intro.tex
+++ b/doc/handbook/intro.tex
@@ -50,7 +50,7 @@ spatial incarnation within the grid by a so-called geometry
function\footnote{The same approach is also used by \texttt{dune-disc} for
finite element shape functions.}. Here, a reference element for an
entity can be thought of as a prototype for the actual grid
-entity. For example, if we used at a grid that used hexahedrons as cells,
+entity. For example, if we used a grid that used hexahedrons as cells,
the reference element for each cell would be the unit cube $[0, 1]^3$
and the geometry function would scale and translate the cube so that
it matches the grid's cell. For a more thorough description of DUNE's
diff --git a/doc/handbook/models.tex b/doc/handbook/models.tex
index 86cf936021da6e23887a15b8f44b406d85eca0e6..5ef93abedd4442c5f919d1e14cbcedf77b7fbad8 100644
--- a/doc/handbook/models.tex
+++ b/doc/handbook/models.tex
@@ -42,7 +42,7 @@ since discontinuities in pressure can occur across a fluid-fluid
interface due to capillary effects.
\textbf{Notation:} The index $\alpha \in \{\text{w}, \text{n}, \text{g}\}$ refers
-to the phase, while the index $\kappa \in \{\text{w}, \text{a}, \text{c}\}$ refers
+to the phase, while the superscript $\kappa \in \{\text{w}, \text{a}, \text{c}\}$ refers
to the component. \\
\begin{tabular}{llll}
$p_\alpha$ & phase pressure & $\phi$ & porosity \\
diff --git a/doc/handbook/propertysystem.tex b/doc/handbook/propertysystem.tex
index 2eabeb8dceaef4b776e44c220e9a54903c6a257d..4546c0f9f06f9e435fe36d78118514ea86f977ce 100644
--- a/doc/handbook/propertysystem.tex
+++ b/doc/handbook/propertysystem.tex
@@ -7,7 +7,7 @@ follows a short reference and a short self-contained example.
\section{Concepts and Features of the \Dumux Property System}
-The \Dumux property system was designed as an attept to mitigate the
+The \Dumux property system was designed as an attempt to mitigate the
problems of traits classes. In fact, it can be seen as a traits system
which allows easy inheritance and any acyclic dependency of parameter
definitions. Just like traits, the \Dumux property system is a compile
@@ -95,7 +95,7 @@ SET_PROP(TypeTagName, PropertyTagName)
For each program, a property itself can be declared at most once,
although properties may be overwritten for derived type tags.
-Also, the following convenience macros available to define simple
+Also, the following convenience macros are available to define simple
properties:
\begin{lstlisting}[basicstyle=\ttfamily\scriptsize]
SET_TYPE_PROP(TypeTagName, PropertyTagName, type);
@@ -299,9 +299,9 @@ the following:
\item A tank exhibits a top speed of $60\;km/h$, uses $65\;l/100km$
and features a $120\;mm$ diameter canon
\item A sedan has a gas usage of $7\;l/100km$, as well as an automatic
- transmission, in every other aspect it is like for a compact car.
+ transmission, in every other aspect it is like a compact car.
\item A pick-up truck has a top speed of $120\;km/h$ and a payload of
- $5\;t$. In every other aspect it is like sedan or a truck but if in
+ $5\;t$. In every other aspect it is like a sedan or a truck but if in
doubt it is more like a truck.
\item The Hummer-H1 SUV exhibits the same top speed as a pick-up
truck. In all other aspects it is similar to a pickup and a tank,
diff --git a/doc/handbook/structure.tex b/doc/handbook/structure.tex
index 7409a1243aa5a40b358bc88dd17dfddf18453ff5..a744290209702bdf889e545fcd3f66f657a1613e 100644
--- a/doc/handbook/structure.tex
+++ b/doc/handbook/structure.tex
@@ -38,7 +38,7 @@ a derived specific numerical model. The subdirectory \texttt{common} also contai
\item \texttt{common}:
general stuff like the property system and the time management for the
-fully coupled as well as the decoupled models, the interface for the Pardiso direct solver library,\cite{Pardiso}, and the \texttt{start.hh} file that includes the common routine for starting a model called in the main function.
+fully coupled as well as the decoupled models, the interface for the Pardiso direct solver library \cite{Pardiso}, and the \texttt{start.hh} file that includes the common routine for starting a model called in the main function.
\item \texttt{decoupled}:
numerical models to solve the pressure equation as part of the fractional flow formulation. The specific models are contained
@@ -61,7 +61,12 @@ and a VTKWriter extension.
\item \texttt{material}: everything related to material parameters and
constitutive equations. The properties of a pure chemical substance (e.g. water) or pseudo substance (e.g. air) can be found in the subdirectory \texttt{components} with the base class \texttt{components/component.hh}. The fluidsytem in the folder \texttt{fluidsystems} collects the information from the respective component and binary coefficients files, and contains the fluid characteristics of phases (e.g. viscosity, density, enthalpy, diffusion coefficients) for compositional or non-compositional multi-phase flow.
-The base class for all spatially dependend variables like permeability and porosity can be found in \texttt{spatialparameters}. The base class in \texttt{boxspatialparameters.hh} also provides spatial averaging routines. All other spatial properties are specified in the specific files of the respective models. Furthermoren, the constitutive relations are in \texttt{fluidmatrixinteractions}, while the necessary binary coefficients like the Henry coefficient or binary diffusion coefficients are definded in \texttt{binarycoefficients}.
+The base class for all spatially dependend variables -- like permeability and porosity --
+can be found in \texttt{spatialparameters}. The base class in \texttt{boxspatialparameters.hh}
+also provides spatial averaging routines. All other spatial properties are specified in the specific
+ files of the respective models. Furthermore, the constitutive relations -- e.g. $p_c(S_w) $ -- are in \texttt{fluidmatrixinteractions},
+while the necessary binary coefficients like the Henry coefficient or binary diffusion coefficients are definded in
+ \texttt{binarycoefficients}.
\item \texttt{nonlinear}: Newton's method.
diff --git a/doc/handbook/tutorial-coupled.tex b/doc/handbook/tutorial-coupled.tex
index 29059d6407915e6e63c3dabd23a9aac2a6afc010..8b9a7c8348f57e49630a4d6b66e240d33ab7361d 100644
--- a/doc/handbook/tutorial-coupled.tex
+++ b/doc/handbook/tutorial-coupled.tex
@@ -32,7 +32,7 @@ water:
\begin{align}
\label{massbalancewater}
\frac {\partial (\phi \, S_{w}\, \varrho_{w})}{\partial t}
- +
+ -
\nabla \cdot \left( \varrho_{w} \, \frac{k_{rw}}{\mu_{w}} \, \mathbf{K}\;\nabla p_w \right)
-
q_w
@@ -40,7 +40,7 @@ water:
0 \\
\label{massbalanceoil}
\frac {\partial (\phi \, S_{o}\, \varrho_{o})}{\partial t}
- +
+ -
\nabla \cdot \left( \varrho_{o} \, \frac{k_{ro}}{\mu_{o}} \, \mathbf{K}\;\nabla p_o \right)
-
q_o
@@ -61,7 +61,7 @@ above.
\end{lst}
From line \ref{tutorial-coupled:include-begin} to line
-\ref{tutorial-coupled:include-end} the Dune and \Dumux files which
+\ref{tutorial-coupled:include-end} the \Dune and \Dumux files which
contain the needed functions and classes are included.
At line \ref{tutorial-coupled:set-type-tag} the type tag of the
@@ -73,7 +73,7 @@ single type tag. Retrieving them is done between line
property system, see section \ref{sec:propertysystem}.
The first thing which should be done at run time is to initialize the
-message passing interface using DUNE's \texttt{MPIHelper} class. Line
+message passing interface using \Dune's \texttt{MPIHelper} class. Line
\ref{tutorial-coupled:init-mpi} is essential if the simulation is
intended to be run on more than one processor at the same time. Next,
the command line arguments are parsed starting at line
@@ -85,7 +85,7 @@ parse the time when the simulation ends and the initial time step size.
After this, a grid is created in line
\ref{tutorial-coupled:create-grid} and the problem is instantiated for
its leaf grid view in line \ref{tutorial-coupled:instantiate-problem}.
-Finally, on line \ref{tutorial-coupled:restart} a state written to
+Finally, on line \ref{tutorial-coupled:begin-restart} a state written to
disk by a previous simulation run is restored if requested by the user.
The simulation procedure is started at line
\ref{tutorial-coupled:execute}.
@@ -109,7 +109,7 @@ which means that for this problem the two-phase box model is chosen as
discretization scheme. On line \ref{tutorial-coupled:set-problem}, a
problem class is attached to the new type tag, while the grid which
is going to be used is defined in line \ref{tutorial-coupled:set-grid} --
-in this case it's \texttt{SGrid}. Since there's no uniform
+in this case that is \texttt{SGrid}. Since there's no uniform
mechanism to allocate grids in \Dune, the \texttt{Grid} property also contains
a static \texttt{create()} method which provides just that. Next,
the appropriate fluid system, that specifies both information about
@@ -173,7 +173,7 @@ assigned with the methods \texttt{dirichlet()} and \texttt{neumann()} which only
by the first function parameter:
\begin{description}
\item[values:] A vector which stores the result of the method. What
- the values in this vector means is dependent on the method: For
+ the values in this vector mean is dependent on the method: For
\texttt{dirichlet()} it contains the values of the primary
variables, for \texttt{neumann()} the mass fluxes per area unit
over the boundary segment.
@@ -239,15 +239,15 @@ First, a certain material law that best describes the problem at hand has to
be selected in line \ref{tutorial-coupled:rawlaw}\label{tutorial-coupled:materialLaw}.
\Dumux provides several material laws in the folder
\verb+dumux/material/fluidmatrixinteractions+.
-The selected one, here it is a relation according to Brooks Corey, is included
+The selected one -- here it is a relation according to a regularized version of Brooks \& Corey -- is included
in line \ref{tutorial-coupled:rawLawInclude}. After the selection,
-an adapter in line \ref{tutorial-coupled:eff2abs} translates the raw
-law to effective values (residual saturations are considered). As the
-applied raw law knows best which kind of parameters are necessary,
+an adapter in line \ref{tutorial-coupled:eff2abs} translates between the law
+for effective values (the Brooks \& Corey model) and the saturations generated as simulations results, i.e. residual saturations are considered.
+As the applied raw law knows best which kind of parameters are necessary,
it provides a parameter class \texttt{RegularizedBrooksCoreyParams} that is
accessible via the member \texttt{Params} and defined in line
\ref{tutorial-coupled:matLawObjectType}. The material law object
-could now be instantiated correctly as a private object
+is now instantiated correctly as a private object
in line \ref{tutorial-coupled:matParamsObject}.
In line \ref{tutorial-coupled:permeability} the function returning the
@@ -259,21 +259,26 @@ about its geometry and position, the second argument
by the box-method, and the third defines the index of the current sub-control
volume. The intrinsic permeability is a tensor and is thus returned in form of
a $\texttt{dim} \times \texttt{dim}$-matrix where \texttt{dim} is the dimension
-of the problem.\\
+of the problem.
+
The function \texttt{porosity()} defined in line
\ref{tutorial-coupled:porosity} is called with the same arguments as
the permeability function described before and returns the porosity
-dependent on the position in the domain.\\
+dependent on the position in the domain.
+
Next, the method \texttt{materialLawParams()} defines in line
-\ref{tutorial-coupled:matLawParams} which object of a considered
-material law should be applied at this specific position.
-While the selection of the type of this object was already explained (see
-\ref{tutorial-coupled:materialLaw}), some specific parameter
+\ref{tutorial-coupled:matLawParams} which \verb+materialLawParams+ object
+ should be applied at this specific position. Although in this case only one objects is returned,
+in general the problem may be heterogeneous, demanding for different objects at different positions in space.
+While the selection of the type of this object was already explained (line \ref{tutorial-coupled:rawLawInclude}),
+ some specific parameter
values of the applied material law are still needed. This is
done in the constructor body (line \ref{tutorial-coupled:setLawParams}).
Depending on the type of the \texttt{materialLaw} object, the adequate \texttt{set}-methods
are provided by the object to access all necessary parameters
-for the applied material law.
+for the applied material law. The name of the access / set functions as well as the rest of the implementation
+of the material description can be found in
+\verb+dumux/dumux/material/fluidmatrixinteractions/2p+.
\subsection{Exercises}
\label{tutorial-coupled:exercises}
@@ -319,12 +324,13 @@ To get an impression what the results should look like you can first run the ori
\texttt{/dumux/material/components}.
\item \textbf{Use the \Dumux fluid system} \\
-\Dumux usually organises fluid mixtures via a \texttt{fluidsystem}. In order to include a fluidsystem you first have to uncomment the lines \ref{tutorial-coupled:2p-system-start} to \ref{tutorial-coupled:2p-system-end} in the problem file. If you use eclipse, this can easily be done by pressing \textit{str + shift + 7} -- the same as to cancel the comment later on.\\
+\Dumux usually organises fluid mixtures via a \texttt{fluidsystem}. In order to include a fluidsystem you first have to comment the lines \ref{tutorial-coupled:2p-system-start} to \ref{tutorial-coupled:2p-system-end} in the problem file. If you use eclipse, this can easily be done by pressing \textit{str + shift + 7} -- the same as to cancel the comment later on.\\
Now include the file \texttt{fluidsystems/h2o\_n2\_system.hh} in the material folder, and set a property \texttt{FluidSystem} with the appropriate type, \texttt{Dumux::H2O\_N2\_System<TypeTag>}. However, the complicated fluidsystem uses tabularized fluid data, which need to be initilized in the constructor body of the current problem by adding \texttt{GET\_PROP\_TYPE(TypeTag, PTAG(FluidSystem))::init();}, hence using the initialization function of the applied fluidsystem. As water flow replacing a gas is much faster, test your simulation only until 2e3 seconds and start with a time step of 1 second.\\
Please reverse the changes of this example, as we still use bulk phases and hence do not need such an extensive fluid system.
\item \textbf{Changing Constitutive Relations} \\
- Use an unregularized linear law with an entry pressure of $p_e = 0.0$ and maximal capillary pressure of $p_{c_{max}} = 0.0$ instead of using a regularized Brooks-Corey law for the
+ Use an unregularized linear law with an entry pressure of $p_e = 0.0$ and maximal capillary pressure of e.g. $p_{c_{max}} = 2000.0$ instead of using a
+ regularized Brooks-Corey law for the
relative permeability and for the capillary pressure saturation relationship. To do that you have
to change the file \texttt{tutorialspatialparameters\_coupled.hh}.
You can find the material laws in the folder
@@ -372,7 +378,7 @@ property so that it matches the domain described
by figure \ref{tutorial-coupled:ex2_Domain}. Adapt the problem class
so that the boundary conditions are consistent with figure
\ref{tutorial-coupled:ex2_BC}. Initially the domain is fully saturated
-with water and the pressure is $p_w = 5 \times 10^5 \text{Pa}$ . Oil
+with water and the pressure is $p_w = 5 \times 10^5 \text{Pa}$. Oil
infiltrates from the left side. Create a grid with $20$ cells in
$x$-direction and $10$ cells in $y$-direction. The simulation time
should be set to $1\times 10^6 \text{ s}$ with an initial time step size of
@@ -387,11 +393,11 @@ compile the program.
\psfrag{K1}{K $= 10^{-7}\text{ m}^2$}
\psfrag{phi1}{$\phi = 0.2$}
\psfrag{Lin}{Brooks-Corey Law}
-\psfrag{Lin2}{$\lambda = 1.8$, $p_b = 1000$}
+\psfrag{Lin2}{$\lambda = 1.8$, $p_e = 1000$}
\psfrag{K2}{K $= 10^{-9}\text{ m}^2$}
\psfrag{phi2}{$\phi = 0.15$}
\psfrag{BC1}{Brooks-Corey Law}
-\psfrag{BC2}{$\lambda = 2$, $p_b = 1500$}
+\psfrag{BC2}{$\lambda = 2$, $p_e = 1500$}
\psfrag{H1y}{50 m}
\psfrag{H2y}{15 m}
\psfrag{H3y}{20 m}
@@ -404,7 +410,7 @@ compile the program.
\end{figure}
\begin{figure}[h]
-\psfrag{pw}{$p_w = 5 \times 10^5$ \text{Pa}}
+\psfrag{pw}{$p_w = 5 \times 10^5$ [\text{Pa}]}
\psfrag{S}{$S_n = 1.0$}
\psfrag{qw}{$q_w = 2 \times 10^{-4}$ [kg/$\text{m}^2$s]}
\psfrag{qo}{$q_n = 0.0$ [kg/$\text{m}^2$s]}
diff --git a/doc/handbook/tutorial-decoupled.tex b/doc/handbook/tutorial-decoupled.tex
index 8b370ec4ed3c1d04b20fc48619adc1eceda0756d..0ad3693e90c3d53003150ba6c38e74551be4ffb5 100644
--- a/doc/handbook/tutorial-decoupled.tex
+++ b/doc/handbook/tutorial-decoupled.tex
@@ -290,7 +290,7 @@ compile the program.
\end{figure}
\begin{figure}[h]
-\psfrag{pw}{$p_w = 5 \times 10^5$ \text{Pa}}
+\psfrag{pw}{$p_w = 5 \times 10^5$ [\text{Pa}]}
\psfrag{S}{$S_n = 1.0$}
\psfrag{qw}{$q_w = 2 \times 10^{-4}$ [kg/$\text{m}^2$s]}
\psfrag{qo}{$q_n = 0.0$ [kg/$\text{m}^2$s]}