opm-simulators/doc/handbook/DumuxFlow.tex

\newcommand{\nextline}{\par\phantom{a}\vspace*{0.1\textwidth}}
\chapter{The flow of things in \Dumux}
\label{flow}

This chapter is supposed to show how things are ``handed around'' in \Dumux. This is not a comprehenisve guide through the modeling framework of \Dumux, but hopefully it will help getting to grips with it. 

In Section \ref{content} the structure of \Dumux is shown from a \emph{content} point of view.
Section \ref{implementation} is written from the point of view of the \emph{implementation}. These two approaches are linked by the circled numbers (like \textbf{\textcircled{\ref{init}}}) in the flowchart of Section \ref{implementation} corresponding to the enumeration of the list of Section \ref{content}. This is supposed to demonstrate at which point of the program-flow you are content- and implementation-wise. 

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. \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.

\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. 

\clearpage
\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} \\
\\
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\\
\end{tabbing}


%% 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}

\subsection{Levels}

\textcircled{\ref{init}} main\\
\textcircled{\ref{prep}} time step\\
\textcircled{\ref{elem}} \textsc{Newton} step\\
\textcircled{\ref{calc}} Element-wise assembly

\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+. 
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
%% Unfortunately, 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 
%% \newline is defined at the beginning of this file
%% sometimes \texttt{} is used (in stead of \verb), as it is not possible to have ANY environment within \verb.
%% If multiple lines are supposed to be under one arrow, I used an align environment and switched back to \textnormal for each line
%% a blank template for one step-stone is at the end of the file

%%SAMPLE:
%    \begin{tabular}{|l|} % each box is a single table, left jusified and bars to the right and left
%       \hline % this makes the top bar of the box
%       \textbf{\textcircled{\ref{calc}}}\verb+ctl.newtonEnd()+ \\ % this is the line for showing code. also in this line the circled numbers are printed, that show the connection to the content wise structure. The numbers are realized as references to the enumerated list. bold!
%       \begin{scriptsize}\end{scriptsize}\\
%       \textbf{called by}:\\ %one line in the box/ table: ``called by'' is set in bold face
%       \textbf{implemented in}: \\ %another line in the box / table  
% 	\hline % this line is smaller textsize for writing comments \hline makesthe bottom bar of the box
%   \end{tabular}
%     $\overrightarrow{\scriptsize % this is the arrow connecting two boxes. In can carry text. 
%     \begin{array}{l} % if the arrow is supposed to carry multiple lines, an array is inserted.
%     \textnormal{timemanager.hh}\\ % formating within an array is tiring. Each line needs its own set of size and textnormal
%     \textbf{\textcircled{\ref{prep}}} \rightarrow \textbf{\textcircled{\ref{init}}}
%     \end{array}
%     }$
  \begin{tabular}{|l|} \hline
    \textbf{\textcircled{\ref{init}}}\verb+timeManager.init()+ \\
    \begin{scriptsize}initialization\end{scriptsize}\\
    \textbf{called by}: main() \\
    \textbf{implemented in}: timemanager.hh \\  
    \hline
  \end{tabular}
    $\overrightarrow{}$
  \begin{tabular}{|l|}\hline
    \textbf{\textcircled{\ref{init}}}\verb+timeManager.run()+\\ 
    \begin{scriptsize}\end{scriptsize}\\
    \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
	\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}execute time integration scheme \end{scriptsize}\\
    \textbf{called by}: timemanager.hh\\
    \textbf{implemented in}: boxproblem.hh\\  
\hline
  \end{tabular}    
\nextline
    {\scriptsize$\overrightarrow{
      \begin{array}{l}
	\textnormal{define number of allowed \textsc{Newton} fails} \\
	\textnormal{(each halving dt)}
      \end{array}
    }$}
      \begin{tabular}{|l|}
    \hline
    \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}
    {\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{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}: boxmodel.hh\\
      \textbf{implemented in}: newtonmethod.hh : $\texttt{execute\_()}$\\  
    \hline
  \end{tabular}
\nextline
 $\overrightarrow{ \begin{array}{l}
				  \textbf{\textcircled{\ref{prep}}} \rightarrow \textbf{\textcircled{\ref{elem}}}\\
                                  \texttt{while(ctl.newtonProceed())}\\
				  \textnormal{uLastIter = uCurrentIter(model.uCur())} 
                                 \end{array}
    }$
    \begin{tabular}{|l|}
      \hline      
	\textbf{\textcircled{\ref{elem}}}\verb+jacobianAsm.assemble()+ \\
    \begin{scriptsize}linearize the problem:  \end{scriptsize}\\
    \begin{scriptsize}add all element contributions to global \textsc{Jacobian} and global residual\end{scriptsize}\\
      \textbf{called by}: newtonmethod.hh\\
      \textbf{implemented in}: boxassembler.hh\\  
	\hline
  \end{tabular}
    \nextline
    $\overrightarrow{
    }$
    \begin{tabular}{|l|}
      \hline      
	\textbf{\textcircled{\ref{elem}}}\verb+resetSystem_()+ \\
    \begin{scriptsize} set r.h.s. (i.e. residual) and\end{scriptsize}\\
    \begin{scriptsize} set \textsc{Jacobian} to zero \end{scriptsize}\\
      \textbf{called by}: boxassembler.hh\\
      \textbf{implemented in}: boxassembler.hh\\  
	\hline
  \end{tabular}
    {\scriptsize$\overrightarrow{\begin{array}{l}
				  \textbf{\textcircled{\ref{elem}}}\rightarrow\textbf{\textcircled{\ref{calc}}}\\
				  \texttt{loop all elements}
                                \end{array}
    }$}
     \begin{tabular}{|l|}
      \hline
      \textbf{\textcircled{\ref{calc}}}\verb+assembleElement_()+ \\
      \begin{scriptsize}call local \textsc{Jacobian} and residual assembly\end{scriptsize}\\
      \textbf{called by}: boxassembler.hh\\
      \textbf{implemented in}: boxassembler.hh\\  
      \hline
     \end{tabular}
\nextline
    {\scriptsize$\overrightarrow{
        }$}
     \begin{tabular}{|l|}
      \hline
     \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 \textsc{Jacobian} to 0\end{scriptsize}\\
     \begin{scriptsize}update types of boundaries on this element\end{scriptsize}\\
      \textbf{called by}: boxassembler.hh\\
      \textbf{implemented in}:  boxlocaljacobian.hh\\  
	\hline
  \end{tabular}
    $\overrightarrow{
    }$
    \begin{tabular}{|l|}
      \hline
      \textbf{\textcircled{\ref{calc}}}\verb+prevVolVars_.update()+, \textbf{\textcircled{\ref{calc}}}\verb+curVolVars_.update()+ \\
    \begin{scriptsize}call model specific update of quantities defined for the volume:\end{scriptsize}\\
    \begin{scriptsize}variables for the \emph{current and 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}calculate all two-phase specific quantites 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+completeFluidState()_.update()+ \\
      \begin{scriptsize}calculate all required fluid properties from the primary variables\end{scriptsize}\\
      \textbf{called by}: 2pvolumevariables.hh\\
      \textbf{implemented in}: 2pvolumevariables.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: rho = Fluidsystem::density()+ \\
      \verb+ fluidState.setDensity(phaseIdx,rho)+ \\
      \begin{scriptsize}The fluid system does the real work: \end{scriptsize}\\
      \begin{scriptsize}calculates densities, diffusivities ... \end{scriptsize}\\
      \begin{scriptsize}The fluidstate save and provides them. \end{scriptsize}\\
      \textbf{called by}: 2pvolumevariables.hh\\
      \textbf{implemented in}: 2pvolumevariables.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 element's local residual is calculated:\end{scriptsize}\\
    \begin{scriptsize}see the next two stepstones\end{scriptsize}\\
      \textbf{called by}: boxlocaljacobian.hh\\
      \textbf{implemented in}: boxlocalresidual.hh\\  
     \hline
  \end{tabular}
    $\overrightarrow{
    }$
    \begin{tabular}{|l|}
      \hline
    \textbf{\textcircled{\ref{calc}}}\verb+asImp_().evalFluxes_()+ \\
    \begin{scriptsize}evaluate the fluxes going into each finite volume\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
{\scriptsize$\overrightarrow{
   \begin{array}{l}
    \textnormal{calculating the fluxes}\\
    \textnormal{takes two more steps}   \\
   \end{array}
}$}
     \begin{tabular}{||l||}
        \hline\hline
        \textbf{\textcircled{\ref{calc}}}\verb+FluxVariables vars()+ \\
        \begin{scriptsize}this is 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+computeAdvectiveFlux()+ (other models: also diffusive)\\
    	\scriptsize{for 2p-model: calculation of phase velocities}\\
	\textbf{called by}: 2plocalresidual.hh\\
      	\textbf{implemented in}: 2plocalresidual.hh\\  
     \hline\hline
  \end{tabular}
\nextline
    $\overrightarrow{
    }$
    \begin{tabular}{|l|}
      \hline
    \textbf{\textcircled{\ref{calc}}}\verb+asImp_().evalVolumeTerms_()+ \\
    \begin{scriptsize}evaluate the storage and source terms for each finite volume\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_().evalBoundary_()+ \\
    \begin{scriptsize}deal with the 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+asImp_().evalPartialDerivative()+ \\
    \begin{scriptsize}actually calculate the element's (local) \textsc{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
    $\overrightarrow{
    }$
    \begin{minipage}{0.50\textwidth}
  \begin{scriptsize}\textnormal{approximation of partial derivatives: numerical differentiation}\end{scriptsize}\\
  \begin{scriptsize}\textnormal{add $\pm \epsilon$ solution, divide difference of residual by $2\epsilon$}\end{scriptsize}\\
  \begin{scriptsize}\textnormal{all partial derivatives for the element from the local \textsc{Jacobian} matrix}\end{scriptsize}\\
$\left \lbrace
     \begin{tabular}{l}%these question marks are for the \verb, not meant as ``unclear''
     	\verb?priVars[pvIdx]+=eps?\\
        \begin{scriptsize}\textnormal{this is adding eps to the current solution}\end{scriptsize}\\
	\verb?curVolVars_[scvIdx].update(+eps)?\\
        \begin{scriptsize}\textnormal{recalculate volume variables, having $\epsilon$ added}\end{scriptsize}\\
     	\verb?localResidual().eval(+eps)?\\
        \begin{scriptsize}\textnormal{calculate local residual for modified solution as before: involves}\end{scriptsize}\\
	{\scriptsize $\begin{array}{l}
		\textnormal{- \textbf{computeFlux}}\\
		\textnormal{- \textbf{computeStorage}}\\
		\textnormal{- \textbf{computeSource}} \\
	\end{array}$} \\
     \verb?store the residual()?\\
     \verb?repeat for priVars[pvIdx]-=eps?\\
     \verb?derivative is (residual(+eps) - residual(-eps))/2eps?\\
  \end{tabular}
  \right .
 $
    \end{minipage}
\hspace{.25\textwidth}
  {\scriptsize$\overrightarrow{}$ }
   \begin{tabular}{|l|} 
      \hline 
      \textbf{\textcircled{\ref{calc}}}\verb+assembleElement_()+ \\ 
      \verb+model_().localJacobian().assemble()+ \\ 
      \begin{scriptsize}Residual of the current solution is now\end{scriptsize}\\
      \begin{scriptsize}``numerically differentiated'', for the element i.e.\end{scriptsize}\\
      \begin{scriptsize}the local \textsc{Jacobian} matrix is calculated. \end{scriptsize}\\
      \textbf{called by}: boxassembler.hh \\ 
      \textbf{implemented in}: boxassembler.hh\\ 
	\hline 
  \end{tabular}
  {\scriptsize$\overrightarrow{}$ }
  $\left|
     \begin{array}{l}
    \textnormal{The contribution of a single element is done.}\\
    \textnormal{Now, it needs to be added to the global quantities:}\\
    \textnormal{Add to global residual and global \textsc{Jacobian}.}
  \end{array}
  \right |$
    {\scriptsize$\overrightarrow{}$ }
   \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}: boxassembler.hh\\ 
	\hline 
  \end{tabular}
 \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 \textsc{Jacobian}.\end{scriptsize}\\
      \textbf{called by}: continuing in the function. \\ 
      \textbf{implemented in}: boxassembler.hh\\ 
	\hline 
  \end{tabular}
    {\scriptsize$\overrightarrow{
	  \begin{array}{l}
	   \textbf{\textcircled{\ref{calc}}}\rightarrow\textbf{\textcircled{\ref{elem}}}\\
           \end{array}
    }$}
   \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}: boxassembler.hh\\ 
	\hline 
  \end{tabular}
\nextline
    {$\overrightarrow{}
    $}
   \begin{tabular}{|l|} 
      \hline 
      \textbf{\textcircled{\ref{elem}}}\verb?while newtonProceed()  ?\\ 
      \begin{scriptsize}Print information.\end{scriptsize}\\
      \begin{scriptsize}start/ stop timer.\end{scriptsize}\\
      \textbf{called by}: continuing in the function, $\texttt{execute\_()}$ \\ 
      \textbf{implemented in}: newtonmethod.hh\\ 
	\hline 
  \end{tabular}
    {\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?newtonSolveLinear()  ?\\ 
      \begin{scriptsize}Ask the linear solver to solve the system.\end{scriptsize}\\
      \begin{scriptsize}i.e. : give \textsc{Jacobian}(matrix), delta(x), r.h.s.(residual) to linear solver\end{scriptsize}\\
      \begin{scriptsize}$\nabla r(x^k) \cdot \Delta x^k = r(x^k)$\end{scriptsize}\\
      \begin{scriptsize}tricky: each \textsc{Newton}step solves a linear system of equations. \end{scriptsize}\\
      \textbf{called by}: continuing in the function, $\texttt{execute\_()}$. \\ 
      \textbf{implemented in}: newtonmethod.hh\\ 
	\hline 
  \end{tabular}
\nextline
    {\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}
    {\scriptsize$\overrightarrow{}
    $}
   \begin{tabular}{|l|} 
      \hline 
      \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 linear solver (set max number of iterations, verbosity)\end{scriptsize}\\
      \textbf{called by}: newtoncontroller.hh\\ 
      \textbf{implemented in}: newtoncontroller.hh\\ 
	\hline 
  \end{tabular}
\nextline
    {\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}
    {\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}
\nextline
    {\scriptsize$\overrightarrow{}
    $}
   \begin{tabular}{|l|} 
      \hline 
      \textbf{\textcircled{\ref{elem}}}\verb+newtonupdateRelError()+\\ 
      \begin{scriptsize}calculate the \emph{relative error} between two iterations\end{scriptsize}\\
      \begin{scriptsize}\quad find the prim. var. that changed most between \end{scriptsize}\\
      \begin{scriptsize}\quad last(\verb+uLastIter+) and current (\verb+uCurrentIter+) \end{scriptsize}\\
      \begin{scriptsize}\quad \textsc{Newton} iteration.\end{scriptsize}\\
      \textbf{called by}: newtoncontroller.hh\\ 
      \textbf{implemented in}: newtoncontroller.hh\\ 
	\hline 
  \end{tabular}
    {\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} $x^{k+1} = x^k - \Delta x^k$ where $\Delta x^k = (\nabla r(x^k))^{-1} \cdot r(x^k)$\end{scriptsize}\\ 
      \textbf{called by}: newtonmethod.hh\\ 
      \textbf{implemented in}: newtoncontroller.hh\\ 
	\hline 
  \end{tabular}
\nextline
    {\scriptsize$\overrightarrow{}
    $}
   \begin{tabular}{|l|} 
      \hline 
      \textbf{\textcircled{\ref{elem}}}\verb+ctl.newtonEndStep()+\\ 
      \begin{scriptsize}Increase counter for number of \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 whether to do another \textsc{Newton} iteration:}\\
				  \textnormal{that is: check if the error is below tolerance or}\\
                                  \textnormal{maximum number of iterations was reached.}\\
                                \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 loop}
                                \end{array}
    }$}
\nextline
    \begin{tabular}{|l|}
      \hline
      \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.updateSuccessful()+ \\
      \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}Give the \fbox{\fbox{problem}} the chance to\end{scriptsize}\\
      \begin{scriptsize}post-process the solution.\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 time step size from number of \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{uPrev $\leftarrow$ uCur}\\
				  \textnormal{time += dt, timestepIdx++}\\
				  \textnormal{deal with restart and episodes }\\
                                \end{array}}
    $}
    {\scriptsize$\overrightarrow{
    \begin{array}{l}
    \textnormal{timemanager.hh}\\
    \textbf{\textcircled{\ref{prep}}} \rightarrow \textbf{\textcircled{\ref{init}}}
    \end{array}
    }$}
%      \begin{tabular}{|l|}
%       \hline
%       \textbf{\textcircled{\ref{calc}}}\verb++ \\
%       \begin{scriptsize}\end{scriptsize}\\
%       \textbf{called by}:\\
%       \textbf{implemented in}: \\  
% 	\hline 
%      \end{tabular}
%     $\overrightarrow{\scriptsize
%     }$
}

\end{landscape}
\normalsize

\newpage 
% Original pagestyle (headings and footer) were switched off, in order to get mroe space for the flowchart.
\pagestyle{scrheadings}

%%% Local Variables: 
%%% mode: latex
%%% TeX-master: "dumux-handbook"
%%% End: