OilfieldToolsNet/opm-simulators
4
0
Fork 0
mirror of https://github.com/OPM/opm-simulators.git synced 2025-02-25 18:55:30 -06:00
Code Issues Packages Projects Releases Wiki Activity

two new chapters in the handbook showing how the problem is moved around in Dumux and one for the Newton

Browse Source
This commit is contained in:
Philipp Nuske
2009-10-27 17:00:08 +00:00
committed by Andreas Lauser
parent fa1175061d
commit d1c43d4f85
4 changed files with 1464 additions and 923 deletions
Download Patch File Download Diff File Expand all files Collapse all files

536
doc/handbook/DumuxFlow.tex Normal file
View File

@@ -0,0 +1,536 @@
\newcommand{\nextline}{\par\phantom{a}\vspace*{0.1\textwidth}}
\chapter{The flow of things in \Dumux}
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.
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 algothimic 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{\textsc{Newton} step}{elem}} \hspace{0.01\textwidth} \=
\textbf{\numberThis{Element}{calc}} \hspace{0.01\textwidth} \\
\\
initialize \\
\textbf{foreach} timestep\\
\> prepare update\\
\> \textbf{foreach} \textsc{Newton} step \\
\> \> \textbf{foreach} element \\
\> \> \> calculate element \textit{Jacobian}\\
\> \> \> assemble 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\\
\> \textbf{endfor}\\
\> adapt timestep, possibly redo with smaller stepsize\\
\> write result\\
\textbf{endfor}\\
finalize\\
\end{tabbing}
%% this is tructured by a table propably the new structure 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\\
\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}.
\begin{landscape}
{\small
%%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
%% \newline is defined at the beginnign 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{called by}:\\ %one line in the box/ table: ``called by'' is set in bold face
% \textbf{implemented in}: \\ %another line in the box / table
% \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}\\\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{called by}: main() \\
\textbf{implemented in}: boxproblem.hh \\
\textbf{\textcircled{\ref{init}}}\verb+problem.simulate()+ \\
\begin{scriptsize}dealing with t$_{init}$\end{scriptsize}\\\hline
\end{tabular}
$\overrightarrow{}$
\begin{tabular}{|l|}\hline
\textbf{called by}: {boxproblem.hh}\\
\textbf{implemented in}: {timemanager.hh}\\
\textbf{\textcircled{\ref{init}}}\verb+timeManager_runSimulation(*asImp())+\\ \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{called by}: timemanager.hh\\
\textbf{implemented in}: boxproblem.hh\\
\textbf{\textcircled{\ref{prep}}}\verb+problem.timeIntegration()+ \\
\begin{scriptsize}\end{scriptsize}\\\hline
\end{tabular}
\nextline
{\scriptsize$\overrightarrow{
\begin{array}{l}
\textnormal{``nothing happens''} \\
\textnormal{just handed over}
\end{array}
}$}
\begin{tabular}{|l|}
\hline
\textbf{called by}: boxproblem.hh\\
\textbf{implemented in}: boxscheme.hh\\
\textbf{\textcircled{\ref{prep}}}\verb+model_.update+ \\
\begin{scriptsize}sth like numerical model\end{scriptsize}\\\hline
\end{tabular}
$\overrightarrow{}$
\begin{tabular}{|l|}
\hline
\textbf{called by}: boxscheme.hh\\
\textbf{implemented in}: boxscheme.hh\\
\textbf{\textcircled{\ref{prep}}}\verb+asImp_().updatebegin()+ \\
\begin{scriptsize}applies Dirichlets\end{scriptsize}\\\hline
\end{tabular}
{\scriptsize$\overrightarrow{
\begin{array}{l}
\textnormal{\texttt{while(true)}loop} \\
\rightarrow \textnormal{until converged}
\end{array} } $}
\begin{tabular}{|l|}
\hline
\textbf{called by}: boxscheme.hh\\
\textbf{implemented in}: boxscheme.hh\\
\textbf{\textcircled{\ref{prep}}}\verb+solver.execute+ \\
\begin{scriptsize}$\begin{array}{l}
\textnormal{solver calls, but more than} \\
\textnormal{just solving happens in here} \\
\textnormal{solver keeps track of things}
\end{array}$\end{scriptsize}\\\hline
\end{tabular}
\nextline
{\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}
\end{array}
}$}
\begin{tabular}{|l|}
\hline
\textbf{called by}: newtonmethod.hh\\
\textbf{implemented in}: assemblerpdelab.hh\\
\textbf{\textcircled{\ref{elem}}}\verb+jacobianAsm.assemble()+ \\
\begin{scriptsize}\end{scriptsize}\\\hline
\end{tabular}
$\overrightarrow{
}$
\begin{tabular}{|l|}
\hline
\textbf{called by}: assemblerpdelab.hh\\
\textbf{implemented in}: gridoperatorspace.hh\\
\textbf{\textcircled{\ref{elem}}}\verb+gridOperatorSpace_->jacobian()+ \\
\begin{scriptsize}\end{scriptsize}\\\hline
\end{tabular}
\nextline
{\scriptsize$\overrightarrow{\begin{array}{l}
\textbf{\textcircled{\ref{elem}}}\rightarrow\textbf{\textcircled{\ref{calc}}}\\
\texttt{for(ElementIterator)}
\end{array}
}$}
\begin{tabular}{|l|}
\hline
\textbf{called by}: gridoperatorspace.hh\\
\textbf{implemented in}: gridoperatorspaceutilities.hh\\
\textbf{\textcircled{\ref{calc}}}\verb+LocalAssemblerCallSwitch<La,La::doAlphaVolume>::jacobian_volume()+ \\
\begin{scriptsize}\end{scriptsize}\\\hline
\end{tabular}
\nextline
$\overrightarrow{
}$
\begin{tabular}{|l|}
\hline
\textbf{called by}: gridoperatorspaceutilities.hh\\
\textbf{implemented in}: boxjacobianpdelab.hh\\
\textbf{\textcircled{\ref{calc}}}\verb+la.jacobian_volume()+ \\
\begin{scriptsize}\end{scriptsize}\\\hline
\end{tabular}
$\overrightarrow{
}$
\begin{tabular}{|l|}
\hline
\textbf{called by}: boxjacobianpdelab.hh\\
\textbf{implemented in}: boxjacobian.hh\\
\textbf{\textcircled{\ref{calc}}}\verb+model_.localJacobian.assemble()+ \\
\begin{scriptsize}\end{scriptsize}\\\hline
\end{tabular}
$\overrightarrow{
}$
\begin{tabular}{|l|}
\hline
\textbf{called by}: boxjacobian.hh\\
\textbf{implemented in}: boxjacobian.hh\\
\textbf{\textcircled{\ref{calc}}}\verb+assemble_()+ \\
\begin{scriptsize}the Jacobian\end{scriptsize}\\\hline
\end{tabular}
\nextline
$\overrightarrow{
}$
\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}\\
$\left \lbrace
\begin{tabular}{l}%these question marks are for the \verb, not meant as ``unclear''
\verb?asImp_().deflectCurrentSol(+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}\\
{\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?
\end{tabular}
\right .
$\\
\end{minipage}
% $\overrightarrow{
% }$
\begin{minipage}{0.47\textwidth}
\begin{scriptsize}\textnormal{\bf \hspace*{0.042\textwidth}\textbf{Fluids} are actually flowing in here!!}\end{scriptsize}\\
\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{implemented in}: 2pboxjacobian.hh} \\
\textnormal{\textbf{\textcircled{\ref{calc}}}} \verb+computeStorage(massContrib, 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()+ \\
\textnormal{\textbf{\textcircled{\ref{calc}}}} \verb+computeFlux()+
\overrightarrow{\textnormal{\scriptsize{ \phantom{really: why oh why latex?}computing the fluxes is more complicated }}}\\
\end{array}
\right. \right.$
\end{minipage}
\nextline
{\scriptsize$\overrightarrow{
\textnormal{calculating the fluxes takes two more steps}
}$}
\begin{tabular}{||l||}
\hline\hline
\textbf{called by}: 2pboxjacobian.hh\\
\textbf{implemented in}: 2pboxjacobian.hh\\
\textbf{\textcircled{\ref{calc}}}\verb+FluxData vars()+ \\
\begin{scriptsize}this a call to a constructor \end{scriptsize}\\\hline\hline
\end{tabular}
$\overrightarrow{
}$
\begin{tabular}{||l||}
\hline\hline
\textbf{called by}: \\
\textbf{implemented in}: 2pfluxdata.hh\\
\textbf{\textcircled{\ref{calc}}}\verb+TwoPFluxdata+ \\
\scriptsize{-all relevant gradients are calculated}\\
\scriptsize{-all velocities are calculated}
\\\hline\hline
\end{tabular}
\nextline
$\left|
\begin{array}{l}
\textnormal{last solution is now}\\
\textnormal{``numerically differentiated''}\\
\quad \rightarrow \textnormal{the Jacobian is calculated}
\end{array}
\right |$\\
\nextline
$\overrightarrow{
}$
\begin{tabular}{|l|}
\hline
\textbf{called by}: boxjacobian.hh\\
\textbf{implemented in}: boxjacobian.hh \fbox{\fbox{$\rightarrow$flux}}\\
\textbf{\textcircled{\ref{calc}}}\verb+evalLocalResiudal(residU, true)+\\
\begin{scriptsize}this is calculating the r.h.s.\end{scriptsize}\\\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
\end{tabular}
$\overrightarrow{
}$
\begin{tabular}{|l|}
\hline
% \textbf{called by}: boxjacobianpdelab.hh\\
\textbf{implemented in}: boxjacobianpdelab.hh\\
\textbf{\textcircled{\ref{calc}}}\verb+mat(i,j)=+ \\
\begin{scriptsize}a matrix is being filled\end{scriptsize}\\\hline
\end{tabular}
\nextline
$\overrightarrow{
}$
\begin{tabular}{|l|}
\hline
% \textbf{called by}: .hh\\
% \textbf{implemented in}: \\
\textbf{\textcircled{\ref{calc}}}\verb+jacobian_volume_post_skeleton()+ \\
\begin{scriptsize}nothing happesn in here\end{scriptsize}\\\hline
\end{tabular}
$\overrightarrow{
}$
\begin{tabular}{|l|}
\hline
\textbf{called by}: gridoperatorspace.hh\\
\textbf{implemented in}: gridoperatorspace.hh\\
\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}\\\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}
}$}
\nextline
\begin{tabular}{|l|}
\hline
\textbf{called by}: assemblerpdelab.hh\\
\textbf{implemented in}: gridoperatorspace.hh\\
\textbf{\textcircled{\ref{elem}}}\verb+gridOperatorspace_->residual()+ \\
\begin{scriptsize}\end{scriptsize}\\\hline
\end{tabular}
{\scriptsize$\overrightarrow{
\texttt{for(ElementIterator)}
}$}
\nextline
\begin{tabular}{|l|}
\hline
\textbf{called by}:gridoperatorspace.hh\\
\textbf{implemented in}: gridoperatorspace.hh\\
\textnormal{\textbf{\textcircled{\ref{elem}}}}$\rightarrow$\textnormal{\textbf{\textcircled{\ref{calc}}}}\verb+LocalAssemblerCallSwitch<La,La::doAlphaVolume>::alpha_volume()+ \\
\begin{scriptsize}\end{scriptsize}\\\hline
\end{tabular}
$\overrightarrow{
}$
\begin{tabular}{|l|}
\hline
\textbf{called by}:grid..util\\
\textbf{implemented in}: boxjacobianpdelab.hh\\
\textbf{\textcircled{\ref{calc}}}\verb+la.alpha_volume()+ \\
\begin{scriptsize}\end{scriptsize}\\\hline
\end{tabular}
$\overrightarrow{
}$
\nextline
\begin{tabular}{|l|}
\hline
\textbf{called by}:boxjabianpdelab.hh\\
\textbf{implemented in}: boxjacobian.hh\\
\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}\\\hline
\end{tabular}
$\overrightarrow{
}$
\begin{tabular}{|l|}
\hline
% \textbf{called by}:\\
% \textbf{implemented in}: \\
\textbf{\textcircled{\ref{calc}}}\verb+r[]=localResidual[][]+ \\
\begin{scriptsize}store r.h.s.\end{scriptsize}\\\hline
\end{tabular}
$\overrightarrow{
}$
\begin{tabular}{|l|}
\hline
% \textbf{called by}:\\
% \textbf{implemented in}: \\
\textbf{\textcircled{\ref{calc}}}\verb+lambda_volume()+ \\
\begin{scriptsize}essentially empty\end{scriptsize}\\\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{called by}:newtonmethod.hh\\
\textbf{implemented in}: newtoncontroller.hh\\
\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}\\\hline
\end{tabular}
$\overrightarrow{
}$
\begin{tabular}{|l|}
\hline
\textbf{called by}:newtoncontroller.hh\\
\textbf{implemented in}:newtoncontroller.hh \\
\textbf{\textcircled{\ref{calc}}}\verb+solveSequential_(A,*u,b)+ \\
\begin{scriptsize}sequ. meaning not parallel\end{scriptsize}\\\hline
\end{tabular}
\nextline
{\scriptsize$\overrightarrow{
\begin{array}{l}
\textnormal{precondition the matrix}\\
\end{array}
}$}
\begin{tabular}{|l|}
\hline
\textbf{called by}:newtoncontroller.hh\\
\textbf{implemented in}: solvers.hh\\
\textbf{\textcircled{\ref{calc}}}\verb+Dune::BiCGStabSolver<Vector>solver(opA,precond...)+ \\
\begin{scriptsize}call to constructor with parameters\end{scriptsize}\\\hline
\end{tabular}
$\overrightarrow{
}$
\begin{tabular}{|l|}
\hline
\textbf{called by}:newtoncontroller.hh\\
\textbf{implemented in}:solvers.hh \\
\textbf{\textcircled{\ref{calc}}}\verb+solver.apply(x,b,result)+ \\
\begin{scriptsize}solving linear system of equations\end{scriptsize}\\\hline
\end{tabular}
$\overrightarrow{
}$
\nextline
\begin{tabular}{|l|}
\hline
\textbf{called by}:newtonmethod.hh\\
\textbf{implemented in}:newtonmethod.hh \\
\textbf{\textcircled{\ref{calc}}}\verb+updateMethod.update()+ \\
\begin{scriptsize}no clue why this is an update???\end{scriptsize}\\\hline
\end{tabular}
$\overrightarrow{
}$
\begin{tabular}{|l|}
\hline
\textbf{called by}:newtonmethod.hh\\
\textbf{implemented in}:newtoncontroller.hh\\
\textbf{\textcircled{\ref{calc}}}\verb+ctl.NewtonEndStep()+ \\
\begin{scriptsize}increase steps and write to console\end{scriptsize}\\\hline
\end{tabular}
{\scriptsize$\overrightarrow{
\begin{array}{l}
\textnormal{newtonmethod.hh}\\
\textbf{\textcircled{\ref{elem}}} \rightarrow \textbf{\textcircled{\ref{prep}}}
\end{array}
}$}
\begin{tabular}{|l|}
\hline
% \textbf{called by}:\\
% \textbf{implemented in}: \\
\textbf{\textcircled{\ref{calc}}}\verb+ctl.newtonEnd()+ \\
\begin{scriptsize}\end{scriptsize}\\\hline
\end{tabular}
{\scriptsize$\overrightarrow{
\begin{array}{l}
\textnormal{timemanager.hh}\\
\textbf{\textcircled{\ref{prep}}} \rightarrow \textbf{\textcircled{\ref{init}}}
\end{array}
}$}
% \begin{tabular}{|l|}
% \hline
% \textbf{called by}:\\
% \textbf{implemented in}: \\
% \textbf{\textcircled{\ref{calc}}}\verb++ \\
% \begin{scriptsize}\end{scriptsize}\\\hline
% \end{tabular}
% $\overrightarrow{\scriptsize
% }$
}
\end{landscape}
\normalsize

50
doc/handbook/NewtonInANutshell.tex Normal file
View File

@@ -0,0 +1,50 @@
\chapter{Newton in an Nutshell}
When using a fully coupled numerical model, one timestep essentially consists of the applicaiotn of the \textsc{Newton} algorith to0 sole the nonlinear system.
One step of the \textsc{Newton} method can be formalized as follows:
\textsc{Newton} method:
\begin{subequations}
\begin{align}
\label{NewtonGen}
\textbf{u}^{r+1} &= \textbf{u}^r - \left(\textbf{f}^\prime (\textbf{u}^r) \right)^{-1} \textbf{f}(\textbf{u}^r) \\
\Leftrightarrow ( \textbf{u}^{r+1}-\textbf{u}^r) {\textbf{f}^{\prime}(\textbf{u}^r)} &= -\textbf{f}(\textbf{u}^r) \\
\Leftrightarrow ( \textbf{u}^r - \textbf{u}^{r+1}) \underbrace{\textbf{f}^{\prime}(\textbf{u}^r)}_{\textnormal{Jacobian}} &= \textbf{f}(\textbf{u}^r) \label{NewtonAsUsed}
\end{align}
\end{subequations}
\noindent with
\begin{itemize}
\item $\phantom{a}^r$: last iteration, $\phantom{a}^{r+1}$: current iteration,
\item $\phantom{a}^\prime$: derivative
\item $\textbf{u}$: vector of unknowns
\item $\textbf{f}(\textbf{u}^r)$: function of vector of unknowns
\end{itemize}
1-D example with slope $m$:
\begin{equation}
m= \frac{y(u^{r+1})-y(u^{r})}{u^{r+1}-u^{r}} \textnormal{ for a root of a function: } m= - \frac{y(u^{r})}{u^{r+1}-u^{r}}
\end{equation}
The value of u (generally a vector of unknowns) for which f becomes zero is searched for. Therefore the quantity of interest is $\textbf{u}^{r+1}$.
But the (BiCGSTAB / Pardiso ...-)linear solver solves systems of the form:
\begin{equation}
\label{GenSysEq}
A\textbf{x} = \textbf{b} .
\end{equation}
Comparing (\ref{GenSysEq}) with (\ref{NewtonAsUsed}) leads to:
\begin{itemize}
\item $\textbf{b} = \textbf{f}(\textbf{u}^r)$ r.h.s. as it is known from the last iteration. Here, $\textbf{f}(\textbf{u}^r)$ is called residual. It is obtained by evaluating the balance equations with the primary variables, as obtained from the last iteration step.
\item $A=\textbf{f}^{\prime}(\textbf{u}^r)$ coefficient matrix or \textsc{Jacobian}. It is obtained by numerical differentiation. Evaluating the balance equations at the last solution + eps, then evaluating the balance equations at the last solution - eps, division by 2eps: numerical differentiation complete.
\item $\textbf{x} = (\textbf{u}^{r+1} - \textbf{u}^{r})$ this is what the linear solver finds as an solution.
\end{itemize}
This is equivalent to stating that the implemented algorithm solves for the change of the solution. Or in other words: until the $\textbf{u}$ does not change with one more iteration.
In the rest of Dumux (everywhere besides in the solver), not the change of the solution is looked for, but the actual solution is used. Therefore the outcome of the linear solver needs to be reformulated as done in \verb+updateMethod.update(*this, u, *uOld, model);+. In this function the ``change in solution'' is changed to ``solution''. Afterwards the quantity \verb+*u+ stands for the solution.

1777
doc/handbook/dumux-handbook.bib
View File

File diff suppressed because it is too large Load Diff

24
doc/handbook/dumux-handbook.tex
View File

@@ -15,6 +15,9 @@
\usepackage{graphicx}
\usepackage[htt]{hyphenat}
\usepackage{color}
\usepackage{lscape}
\usepackage{enumerate}
\DeclareGraphicsExtensions{.eps, .jpg}
@@ -39,6 +42,17 @@
}
{\end{itemize}}
% a new counter
% you can give a label to it and thus reference it
% syntax: \numberThis{printedTextToBeLabeled}{label}
% if you wanted a \newline after a numbered thing, you could just add a empty line after ``\label{#2}''
\newcounter{thingCounter}
\renewcommand{\thethingCounter}{\arabic{thingCounter}}
\newcommand{\numberThis}[2]{%
\refstepcounter{thingCounter}%
\thethingCounter.\ #1 \label{#2}
}
%The theorems
\theorembodyfont{\upshape}
\theoremheaderfont{\sffamily\bfseries}
@@ -46,6 +60,7 @@
\newtheorem{rem}[exc]{Remark}
\newtheorem{lst}{Listing}
\newtheorem{warn}[exc]{Warning}
\newtheorem{justCounting}{}
\DeclareMathOperator{\grad}{grad}
\DeclareMathOperator{\curl}{curl}
@@ -90,11 +105,14 @@ Universit\"at Stuttgart, Paffenwaldring 61, D-70569 Stuttgart, Germany}\\
\input{getting-started}
\input{tutorial}
\input{structure}
\input{models}
\input{models}
\input{DumuxFlow}
\input{NewtonInANutshell}
\bibliographystyle{plain}
\bibliography{dumux-handbook}
\printindex
\end{document}