Skip to content
Snippets Groups Projects
Commit 226fa261 authored by Thomas Fetzer's avatar Thomas Fetzer
Browse files

[handbook] 

- outsourced furtherpractice subchapter
- updated steps of a dumux simulation
- removed todos



git-svn-id: svn://svn.iws.uni-stuttgart.de/DUMUX/dumux/trunk@15431 2fb0f335-1f38-0410-981e-8018bf24f1b0
parent f368aa49
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
Showing
with 540 additions and 838 deletions
doc/handbook/0_discussion.tex
+ 7
− 8
View file @ 226fa261
\chapter*{Discussion about the new handbook}
\todo[inline]{Ihr konnt die todo Befehle benutzen um Dinge zu markieren, die euch
auffallen, dann können wir die beim nachsten Mal besprechen}
\section*{Beschlossene ToDos}
DEADLINE: 01.09.15
\begin{itemize}
\item steps of dumux simulations - flow chart/Grafik (Gaby + Thomas)
\item Fluidstate/Fluidsystem -$>$ Abstrakte Klassen einführen für doxygen (Natalie)
\item[x] steps of dumux simulations - flow chart/Grafik (Gaby + Thomas)
\item[x] Fluidstate/Fluidsystem -$>$ Abstrakte Klassen einführen für doxygen (Natalie)
\item Modelle raus, Liste rein (Christoph, Beatrix)
\item Neues Gitterkapitel (Natalie)
\item[x] Neues Gitterkapitel (Natalie)
\begin{itemize}
\item gmesh (Timo)
\item petrel (Alex)
\item[x] gmesh (Timo)
\item[x] petrel (Alex)
\item[x] artgridcreator (Nicolas)
\item[x] dgf (kurz kommentieren)
\item[x] icemcfd (nicolas)
......@@ -21,6 +18,8 @@ DEADLINE: 01.09.15
\item[x] Updated folder structure figure in Chapter \ref{sc_structure}
\item[x] How to change compiler (4.6.2)
\end{itemize}
\todo[inline]{An manchen stellen haben wir noch Problemen mit bad boxen, vor allem
wenn \textbackslash texttt\{\} benutzt wird}
% \section*{Offene Fragen}
% \begin{itemize}
......
doc/handbook/0_dumux-handbook.tex
+ 3
− 6
View file @ 226fa261
\documentclass[11pt,a4paper,headinclude,footinclude,DIV16]{scrreprt}
\usepackage[usenames,dvipsnames]{xcolor} % include at beginning because of compitibility issues
\usepackage[usenames,dvipsnames,table]{xcolor} % include at beginning because of compitibility issues
\usepackage[english]{babel}
\usepackage[htt]{hyphenat}
\usepackage[utf8]{inputenc}
\usepackage[automark]{scrpage2}
\usepackage[normalem]{ulem}
......@@ -13,15 +12,12 @@
\usepackage{enumerate}
\usepackage{hyperref}
\usepackage{graphicx}
\usepackage{layout}
\usepackage{listings}
\usepackage{lscape}
\usepackage{makeidx}
\usepackage{pdflscape}
\usepackage{rotating}
\usepackage{subfig}
\usepackage{tabularx}
\usepackage{textcomp}
\usepackage{theorem}
\usepackage{tikz}
\usepackage{tikz-qtree}
......@@ -131,6 +127,7 @@ Then a quick start guide for the first \Dumux experience is provided.
\input{3_tutorial}
\input{3_tutorialcoupled}
\input{3_tutorialdecoupled}
\input{3_furtherpractice}
\chapter{Overview and Infrastructure}
This chapter provides an overview of the general structure in \Dumux \ref{sc_structure}
......@@ -152,7 +149,7 @@ This chapter contains detailed information for those who are interested
in deeper modifications of underlying \Dumux models, classes, functions, etc.
\input{5_models}
\input{5_spatialdiscretizations}
\input{5_flowofthings}
\input{5_stepsofasimulation}
\input{5_propertysystem}
\input{5_fluidframework}
\input{5_grids}
......
doc/handbook/0_listingstyle.tex
+ 2
− 2
View file @ 226fa261
......@@ -83,7 +83,7 @@
numbersep=5pt,
numberstyle=\tiny,
basicstyle=\ttfamily\scriptsize,
keywordstyle=\color{Blue}\ttfamily\let\textcolor\textcolordummy,
keywordstyle=\color{dumuxBlue}\ttfamily\let\textcolor\textcolordummy,
stringstyle=\color{BrickRed}\ttfamily\let\textcolor\textcolordummy,
commentstyle=\color[gray]{0.35}\ttfamily\it\let\textcolor\textcolordummy,
emph={NEW_TYPE_TAG, NEW_PROP_TAG, UNSET_PROP, TTAG, PTAG,
......@@ -104,5 +104,5 @@
basicstyle=\ttfamily\scriptsize,
stringstyle=\color{BrickRed}\ttfamily\let\textcolor\textcolordummy,
commentstyle=\color[gray]{0.35}\ttfamily\it\let\textcolor\textcolordummy,
morecomment=[l][\color{Blue}\let\textcolor\textcolordummy]{[},
morecomment=[l][\color{dumuxBlue}\let\textcolor\textcolordummy]{[},
}
doc/handbook/3_furtherpractice.tex 0 → 100644
+ 38
− 0
View file @ 226fa261
\section{Further Practice}
\label{tutorial-furtherpractice}
If there is a request for further practice, we refer here to the test problems, that
are already implemented in \Dumux. Several examples for coupled and decoupled models
can be found in the \texttt{test}-directory. An overview over the available tests
cases can be found on the class documentation \url{http://www.dumux.org/documentation.php}.
There you also find a \emph{feature-list} for the individual tests.
Another possibility to gain experience with \Dumux is the \texttt{dumux-lecture} module. It is devided according to
the lecture modules Multi-phase-Modelling (mm), Environmental Fluid Mechanics (efm) and Modelling of Hydrosystems (mhs).
They contain several test cases designed to enhance the understanding of physical modelling.
Different aspects of modelling multi-phase multi-component flow and transport processes are approached such as the
choice of phases and components, the discretization and the reduction of a complex problem to the main physical
processes. You can find for example a comparison of different 2-phase-flow problems considering simply two immiscible
fluids up to the case of components present in both phases. Most of the problems are oriented at current research topics.
All the scenarios and their physical background are explained in additional .tex-files. The following test cases are
contained:
\begin{itemize}
\item \texttt{Buckley-Leverett Problem}
\item \texttt{$\text{CO}_2$-plume}
\item \texttt{Column Xylene}
\item \texttt{Convective Mixing}
\item \texttt{Fuel Cell}
\item \texttt{Heatpipe}
\item \texttt{Heavy Oil}
\item \texttt{Henry Problem}
\item \texttt{McWorther Problem}
\item \texttt{NAPL Infiltration}
\item \texttt{Remediation Scenarios}
\item \texttt{Groundwater}
\item \texttt{different 2-phase n-component problems}
\end{itemize}
Dumux-lecture can be obtained as follows:
\begin{lstlisting}[style=Bash]
$ svn checkout --username=anonymous --password='' svn://svn.iws.uni-stuttgart.de/DUMUX/dumux-lecture/trunk dumux-lecture
\end{lstlisting}
doc/handbook/3_tutorialdecoupled.tex
+ 0
− 44
View file @ 226fa261
......@@ -529,47 +529,3 @@ no matter if we model coupled or decoupled. Try to formulate a spatial parameter
file that works with both problems, the coupled and the decoupled. Therein, only
use functions at the position.
\section{Further Practice}\label{tutorial-furtherpractice}
If there is a request for further practice, we refer here to the test problems, that
are already implemented in \Dumux.Several examples for coupled and decoupled models
can be found in the test-directory. An overview over the available tests cases can be
found on the dumux-homepage.
\todo{Sollte es auch eine Liste der vorhandenen Tests geben (und auf die Homepage gestellt werden?)?}
If the handling of certain features is of special interest, the according test cases can be
found via the FeatureList on the \Dumux-homepage.\\
Another possibility to gain experience with \Dumux is the \textbf{dumux-lecture} module. It is devided according to
the lecture modules Multi-phase-Modelling (mm), Environmental Fluid Mechanics (efm) and Modelling of Hydrosystems (mhs).
They contain several test cases designed to enhance the understanding of physical modelling.
Different aspects of modelling multi-phase multi-component flow and transport processes are approached such as the
choice of phases and components, the discretization and the reduction of a complex problem to the main physical
processes. You can find for example a comparison of different 2-phase-flow problems considering simply two immiscible
fluids up to the case of components present in both phases. Most of the problems are oriented at current research topics.
All the scenarios and their physical background are explained in additional .tex-files. The following test cases are
contained:
\begin{itemize}
\item \texttt{Buckley-Leverett Problem}
\item \texttt{$\text{CO}_2$-plume}
\item \texttt{Column Xylene}
\item \texttt{Convective Mixing}
\item \texttt{Fuel Cell}
\item \texttt{Heatpipe}
\item \texttt{Heavy Oil}
\item \texttt{Henry Problem}
\item \texttt{McWorther Problem}
\item \texttt{NAPL Infiltration}
\item \texttt{Remediation Scenarios}
\item \texttt{Groundwater}
\item \texttt{different 2-phase n-component problems}
\end{itemize}
Dumux-lecture can be obtained as follows:
\begin{lstlisting}[style=Bash]
$ # make sure you are in DUMUX-Root
$ svn checkout --username=anonymous --password='' svn://svn.iws.uni-stuttgart.de/DUMUX/dumux-lecture/trunk dumux-lecture
\end{lstlisting}
doc/handbook/5_flowofthings.tex deleted 100644 → 0
+ 0
− 735
View file @ f368aa49
\section{Steps of a \Dumux Simulation}
\label{flow}
\todo[inline]{Hier könnte man den Text auch etwas abspecken}
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 implementation 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.
\subsection{Structure -- by Content}
\todo[inline]{Mehr Farbe, z.B bei den Levels, statt den Links}
\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. Each item stands
for a characteristic step within the modeling framework.
\clearpage
In Figure \ref{fig:algorithm}, the algorithmic representations of both approaches
down to the element level are illustrated.
\begin{figure}[hbt]
\begin{tabular}{ l | l }
\begin{minipage}[t]{0.48\textwidth}
\setcounter{thingCounter}{0}
\scriptsize
\sffamily
\begin{tabbing}
\textbf{{\begin{turn}{45}\numberThis{main}{init}\end{turn}}} \=
\textbf{{\begin{turn}{45}\numberThis{time step}{prep}\end{turn}}} \=
\textbf{{\begin{turn}{45}\numberThis{\textsc{Newton}}{elem}\end{turn}}} \=
\textbf{{\begin{turn}{45}\numberThis{element}{calc}\end{turn}}} \= \\
\\
initialize \\
\textbf{foreach} time step\\
\> prepare update\\
\> \textbf{foreach} \textsc{Newton} iteration \\
\> \> \textbf{foreach} element \\
\> \> \> - calculate element \\
\>\>\> \; residual vector and \\
\>\>\> \; Jacobian matrix\\
\> \> \> - assemble into global\\
\>\>\> \; residual vector and \\
\> \> \> \;{Jacobian} matrix \\
\> \> \textbf{endfor} \\
\> \> solve linear system\\
\> \> update solution\\
\> \> check for \textsc{Newton} convergence\\
\> \textbf{endfor}\\
\> - adapt time step size, \\
\> \; possibly redo with smaller step size\\
\> - write result\\
\textbf{endfor}\\
finalize
\end{tabbing}
\end{minipage}
&
\begin{minipage}[t]{0.48\textwidth}
\setcounter{thingCounter}{0}
\scriptsize
\sffamily
\begin{tabbing}
\textbf{{\begin{turn}{45}1. main\end{turn}}} \=
\textbf{{\begin{turn}{45}2. time step\end{turn}}} \=
\textbf{{\begin{turn}{45}3. \textsc{IMPES/C}\end{turn}}} \=
\textbf{{\begin{turn}{45}4. element\end{turn}}} \= \\
\\
initialize \\
\textbf{foreach} time step\\
\> prepare update\\
\> \textbf{foreach} \textsc{IMPES/C} step \\
\> \> \textbf{if} grid is adaptive\\
\> \> \> - calculate refinement indicator\\
\> \> \> - mark elements, adapt the grid\\
\> \> \> - map old solution to new grid\\
\> \> - calculate {flow field}\\
\> \> \textbf{foreach} element \\
\> \> \> - calculate element stiffness matrix \\
\> \> \> - assemble into global matrix \\
\> \> \textbf{endfor} \\
\> \> solve linear system\\
\> \> - calculate {transport} \\
\> \> \; (saturations, concentrations,...) \\
\> \> \textbf{foreach} element \\
\> \> \> -calculate update (explicitly) \\
\> \> \>- adapt time step ({CFL}-like criterion) \\
\> \> \textbf{endfor} \\
\> \> - update old solution \\
\> \> - postprocess (flash calculation, etc.)\\
\> \textbf{endfor}\\
\> - write result\\
\textbf{endfor}\\
finalize
\end{tabbing}
\end{minipage}
\end{tabular}
\caption{Structure of a coupled fully-implicit (\textbf{left}) and a decoupled
semi-implicit (\textbf{right}) scheme in \Dumux.}
\label{fig:algorithm}
\end{figure}
\subsubsection{Levels}
\textcircled{\ref{init}} main\\
\textcircled{\ref{prep}} time step\\
\textcircled{\ref{elem}} \textsc{Newton} step\\
\textcircled{\ref{calc}} Element-wise assembly
\subsection{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}.
\todo[inline]{Workflow übersichtlicher gestalten}
\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+start()+ \\
\begin{scriptsize}start the simulation\end{scriptsize}\\
\textbf{called by}: main() \\
\textbf{implemented in}: start.hh \\
\hline
\end{tabular}
$\overrightarrow{}$
\begin{tabular}{|l|} \hline
\textbf{\textcircled{\ref{init}}}\verb+timeManager.init()+ \\
\begin{scriptsize}initialization\end{scriptsize}\\
\textbf{called by}: start() \\
\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}: {start()}\\
\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)}}\\
\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}: implicitproblem.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}: implicitproblem.hh\\
\textbf{implemented in}: implicitmodel.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}: implicitmodel.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}: implicitassembler.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}: implicitassembler.hh\\
\textbf{implemented in}: implicitassembler.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}: implicitassembler.hh\\
\textbf{implemented in}: implicitassembler.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}: implicitassembler.hh\\
\textbf{implemented in}: implicitlocaljacobian.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}: implicitlocaljacobian.hh\\
\textbf{implemented in}: implicitelementvolumevariables.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()+ \\
\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}: implicitlocaljacobian.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
{$\overrightarrow{}$}
\begin{tabular}{||l||}
\hline\hline
\textbf{\textcircled{\ref{calc}}}\verb+computeFluxes()+ \\
\begin{scriptsize}model specific flux computation \end{scriptsize}\\
\textbf{called by}: boxlocalresidual.hh\\
\textbf{implemented in}: 2plocalresidual.hh\\
\hline\hline
\end{tabular}
$\overrightarrow{
}$
\begin{tabular}{||l||}
\hline\hline
\textbf{\textcircled{\ref{calc}}}\verb+FluxVariables fluxVars()+ \\
\begin{scriptsize}this is a call to a constructor: \end{scriptsize}\\
\begin{scriptsize}calculate the velocities \end{scriptsize}\\
\textbf{called by}: 2plocalresidual.hh\\
\textbf{implemented in}: boxdarcyfluxvariables.hh\\
\hline\hline
\end{tabular}
$\overrightarrow{
}$
\begin{tabular}{||l||}
\hline\hline
\textbf{\textcircled{\ref{calc}}}\verb+computeAdvectiveFlux()+ (other models: also diffusive)\\
\scriptsize{upwinding decision via \verb+massUpwindWeight_+}\\
\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}: implicitlocaljacobian.hh\\
\textbf{implemented in}: implicitlocaljacobian.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}: implicitassembler.hh \\
\textbf{implemented in}: implicitassembler.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}: implicitassembler.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}: implicitassembler.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}: implicitassembler.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+linearSolver_.solve()+\\
\begin{scriptsize}Solve the linear system with the chosen backend.\end{scriptsize}\\
\textbf{called by}: newtoncontroller.hh\\
\textbf{implemented in}: boxlinearsolver.hh\\
\hline
\end{tabular}
\nextline
{\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}
{\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}
\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+asImp_().updateSuccessful()+ \\
\begin{scriptsize}Can be filled by the \fbox{\fbox{model}}.\end{scriptsize}\\
\textbf{called by}: implicitmodel.hh\\
\textbf{implemented in}: implicitmodel.hh\\
\hline
\end{tabular}
{\scriptsize$\overrightarrow
{\begin{array}{l}
\textnormal{in while(!finished)}\\
\end{array}}
$}
\begin{tabular}{|l|}
\hline
\textbf{\textcircled{\ref{prep}}}\verb+problem_.postTimeStep(),writeOutput()+ \\
\begin{scriptsize}Give the \fbox{\fbox{problem}} the chance to\end{scriptsize}\\
\begin{scriptsize}post-process the solution.\end{scriptsize}\\
\textbf{called by}: timemanager.hh\\
\textbf{implemented in}: implicitproblem.hh\\
\hline
\end{tabular}
\nextline
{\scriptsize$\overrightarrow
{\begin{array}{l}
\textnormal{write output}\\
\textnormal{uPrev $\leftarrow$ uCur}\\
\textnormal{time += dt, timestepIdx++}\\
\textnormal{deal with restart and episodes }\\
\end{array}}
$}
\begin{tabular}{|l|}
\hline
\textbf{\textcircled{\ref{prep}}}\verb+newtonCtl_.suggestTimestepSize()+ \\
\begin{scriptsize}Determine new time step size from number of \textsc{Newton} steps. \end{scriptsize}\\
\textbf{called by}: timemanager.hh, implicitproblem.hh\\
\textbf{implemented in}: newtoncontroller.hh\\
\hline
\end{tabular}
{\scriptsize$\overrightarrow{}$}
{\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:
doc/handbook/5_fluidframework.tex
+ 0
− 8
View file @ 226fa261
\section{Fluid Framework}
\label{sec:fluidframework}
\todo[inline]{Wie kann dieses Kapitel besser mit doxygen vereinbart werden? Evtl. durch generische
Klassen in dumux, die dann automatische im doxygen auftauchen.}
This chapter discusses the \Dumux fluid framework. \Dumux users who
do not want to write new models and who do not need new fluid
configurations may skip this chapter.
......@@ -159,8 +156,6 @@ Also, all fluid states must provide the following methods:
\end{description}
\subsubsection{Available Fluid States}
\todo{Diese Liste von verfügbaren \emph{FluidStates} sollte eigentlich so und
in gleicher Ausfgührlichkeit im doxygen möglich sein -$>$ deshalb raus.}
Currently, the following fluid states are provided by \Dumux:
\begin{description}
\item[NonEquilibriumFluidState:] This is the most general fluid state
......@@ -352,9 +347,6 @@ such fluid systems cannot be used for models that depend on those
methods.
\subsubsection{Available Fluid Systems}
\todo{Diese Liste von verfügbaren \emph{FluidSystems} sollte eigentlich so und
in gleicher Ausfgührlichkeit im doxygen möglich sein -$>$ deshalb raus.}
Currently, the following fluid systems are available in \Dumux:
\begin{description}
\item[Dumux::FluidSystems::TwoPImmiscible:] A two-phase fluid system
......
doc/handbook/5_models.tex
+ 27
− 21
View file @ 226fa261
\section{Models}
\todo{die abschnitte im einzelnen überarbeiten (Thomas)}
Here the basic definitions, the general models concept, and a list of
models available in \Dumux are given.
\subsection{Basic Definitions and Assumptions}
Characteristic of compositional multiphase models is that the phases
are not only matter of a single chemical substance. Instead, their
composition in general includes several species, and for the mass transfer,
the component behavior is quite different from the phase behavior. In the following, we
give some basic definitions and assumptions that are required for the
formulation of the model concept below. As an example, we take a
three-phase three-component system water-NAPL-gas
The basic definitions and assumptions are made, using the example
of a three-phase three-component system water-NAPL-gas
\cite{A3:class:2002a}. The modification for other multicomponent
systems is straightforward and can be found, e.\ g., in
\cite{A3:bielinski:2006,A3:acosta:2006}.
% \todo{gibt es hier noch mehr (allgemeine) Punkte, die es sich lohnen würde
% aufzunehmen?}
\begin{description}
\item[Components:]
The term {\it component} stands for constituents of the phases which
The term \emph{component} stands for constituents of the phases which
can be associated with a unique chemical species, or, more generally, with
a group of species exploiting similar physical behavior. In this work, we
assume a water-gas-NAPL system composed of the phases water (subscript
$\text{w}$), gas ($\text{g}$), and NAPL ($\text{n}$). These phases are
composed of the components water (superscript $\text{w}$), air
($\text{a}$), and the organic contaminant ($\text{c}$) (see Fig.
composed of the components water (superscript $\text{w}$), the pseudo-component
air ($\text{a}$), and the organic contaminant ($\text{c}$) (see Fig.
\ref{fig:phaseMassEnergyTransfer}).
\item[Phases:]
For compositional multi-phase models, \emph{phases}
are not only matter of a single chemical substance. Instead, their
composition in general includes several species/components. For mass transfer,
the component behavior is quite different from the phase behavior.
\item[Equilibrium:]
For the non-isothermal multiphase processes in porous media under
consideration, we state that the assumption of local thermal
equilibrium is valid since flow velocities are small. We neglect
chemical reactions and biological decomposition and assume chemical
equilibrium. Mechanical equilibrium is not valid in a porous medium,
since discontinuities in pressure can occur across a fluid-fluid
interface due to capillary effects.
For the non-isothermal, multi-phase, multi-component processes in porous media
we state that the assumption of \emph{local thermodynamic equilibrium}.
Chemical equilibrium means that the mass/mole fractions of a component in
different phases are in equilibrium.
Thermal equilibrium assumes the same temperature for all considered phases.
Mechanical equilibrium is not valid in a porous medium, since discontinuities
in pressure can occur across a fluid-fluid interface due to capillary effects.
\item[Notation:]
The index $\alpha \in \{\text{w}, \text{n}, \text{g}\}$ refers
to the phase, while the superscript $\kappa \in \{\text{w}, \text{a}, \text{c}\}$ refers
to the component.
The subscript index $\alpha \in \{\text{w}, \text{n}, \text{g}\}$ refers
to the phase, while the superscript $\kappa \in \{\text{w}, \text{a}, \text{c}\}$
refers to the component.
\end{description}
\begin{table}
......
doc/handbook/5_propertysystem.tex
+ 28
− 14
View file @ 226fa261
\section{Property System}
\label{sec:propertysystem}
\todo[inline]{Irgendwo sollten wir erklären wir Property Werte geholt werden und
was der Unterschied zwisch GET\_PROP\_VALUE, GET\_PARAM\_FROM\_GROUP
und GET\_RUNTIME\_PARAM\_FROM\_GROUP ist.}
A high level overview over the property system's design and principle ideas
are given, then follows a reference and a self-contained example.
......@@ -32,8 +29,8 @@ how it was inherited.
\subsection{How-to}
All source files which use the property system should include
the header file \texttt{dumux/ \hskip-1ex{}common/
\hskip-1ex{}propertysystem.hh}. Declaration of type tags and
the header file \path{dumux/common/propertysystem.hh}.
Declaration of type tags and
property tags as well as defining properties must be done inside the
namespace \texttt{Dumux::Properties}.
......@@ -371,13 +368,30 @@ int main()
}
\end{lstlisting}
will yield the following output:
\begin{lstlisting}[style=DumuxCode]
top speed of sedan: 210
top speed of truck: 100
Properties for Sedan:
bool AutomaticTransmission = 'true' defined at test_propertysystem.cc:68
int GasUsage = '7' defined at test_propertysystem.cc:67
Inherited from CompactCar:
int NumSeats = '5' defined at test_propertysystem.cc:55
int TopSpeed = '::Dumux::Properties::GetProperty<TypeTag, ::Dumux::Properties::PTag::GasUsage>::p::value * 30' defined at test_propertysystem.cc:54
\begin{lstlisting}[style=Bash, basicstyle=\ttfamily\scriptsize\let\textcolor\textcolordummy]
$ top speed of sedan: 210
$ top speed of truck: 100
$ Properties for Sedan:
$ bool AutomaticTransmission = 'true' defined at test_propertysystem.cc:68
$ int GasUsage = '7' defined at test_propertysystem.cc:67
$ Inherited from CompactCar:
$ int NumSeats = '5' defined at test_propertysystem.cc:55
$ int TopSpeed = '::Dumux::Properties::GetProperty<TypeTag, ::Dumux::Properties::PTag::GasUsage>::p::value * 30' defined at test_propertysystem.cc:54
\end{lstlisting}
\subsection{Property and Parameter Values}
In \Dumux three different ways to obtain the value of a property are available:
\begin{description}
\item[\texttt{{\small GET\_PROP\_VALUE:}}]
Always returns the \emph{compile-time} specified value of the property. This is
needed for properties, which are not intended to be changed by parameter files.
\item[\texttt{{\small GET\_PARAM\_FROM\_GROUP:}}]
Returns the compile-time specified value, if this value is not be overwritten
by the parameter input file.
\item[\texttt{{\small GET\_RUNTIME\_PARAM\_FROM\_GROUP:}}]
Always returns a \emph{run-time} specified value. If the value is not specified
at run-time an error is thrown. This is needed for problem specific properties
or properties, which do not have a meaningful default value.
\end{description}
doc/handbook/5_stepsofasimulation.tex 0 → 100644
+ 433
− 0
View file @ 226fa261
\section{Steps of a \Dumux Simulation}
\label{flow}
\todo[inline]{Hier könnte man den Text auch etwas abspecken}
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 implementation 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.
\subsection{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. Each item stands
for a characteristic step within the modeling framework.
\clearpage
In Figure \ref{fig:algorithm}, the algorithmic representations of both approaches
down to the element level are illustrated.
\begin{figure}[hbt]
\begin{tabular}{ l | l }
\begin{minipage}[t]{0.48\textwidth}
\setcounter{thingCounter}{0}
\scriptsize
\sffamily
\begin{tabbing}
\textbf{{\begin{turn}{45}\color{black}\numberThis{main}{init}\end{turn}}} \=
\textbf{{\begin{turn}{45}\color{dumuxBlue}\numberThis{time step}{prep}\end{turn}}} \=
\textbf{{\begin{turn}{45}\color{Mulberry}\numberThis{\textsc{Newton}}{elem}\end{turn}}} \=
\textbf{{\begin{turn}{45}\color{dumuxYellow}\numberThis{element}{calc}\end{turn}}} \= \\
\\
\color{black}initialize \\
\color{black}\textbf{foreach} time step\\
\> \color{dumuxBlue}prepare update\\
\> \color{dumuxBlue}\textbf{foreach} \textsc{Newton} iteration \\
\> \> \color{Mulberry}\textbf{foreach} element \\
\> \> \> \color{dumuxYellow}- calculate element \\
\> \> \> \color{dumuxYellow}\; residual vector and \\
\> \> \> \color{dumuxYellow}\; Jacobian matrix\\
\> \> \> \color{dumuxYellow}- assemble into global\\
\> \> \> \color{dumuxYellow}\; residual vector and \\
\> \> \> \color{dumuxYellow}\;{Jacobian} matrix \\
\> \> \color{Mulberry}\textbf{endfor} \\
\> \> \color{Mulberry}solve linear system\\
\> \> \color{Mulberry}update solution\\
\> \> \color{Mulberry}check for \textsc{Newton} convergence\\
\> \color{dumuxBlue}\textbf{endfor}\\
\> \color{dumuxBlue}- adapt time step size, \\
\> \color{dumuxBlue}\; possibly redo with smaller step size\\
\> \color{dumuxBlue}- write result\\
\color{black}\textbf{endfor}\\
\color{black}finalize
\end{tabbing}
\end{minipage}
&
\begin{minipage}[t]{0.48\textwidth}
\setcounter{thingCounter}{0}
\scriptsize
\sffamily
\begin{tabbing}
\textbf{{\begin{turn}{45}\color{black}1. main\end{turn}}} \=
\textbf{{\begin{turn}{45}\color{dumuxBlue}2. time step\end{turn}}} \=
\textbf{{\begin{turn}{45}\color{Mulberry}3. \textsc{IMPES/C}\end{turn}}} \=
\textbf{{\begin{turn}{45}\color{dumuxYellow}4. element\end{turn}}} \= \\
\\
\color{black}initialize \\
\color{black}\textbf{foreach} time step\\
\> \color{dumuxBlue}prepare update\\
\> \color{dumuxBlue}\textbf{foreach} \textsc{IMPES/C} step \\
\> \> \color{Mulberry}\textbf{if} grid is adaptive\\
\> \> \> \color{dumuxYellow}- calculate refinement indicator\\
\> \> \> \color{dumuxYellow}- mark elements, adapt the grid\\
\> \> \> \color{dumuxYellow}- map old solution to new grid\\
\> \> \color{Mulberry}- calculate {flow field}\\
\> \> \color{Mulberry}\textbf{foreach} element \\
\> \> \> \color{dumuxYellow}- calculate element stiffness matrix \\
\> \> \> \color{dumuxYellow}- assemble into global matrix \\
\> \> \color{Mulberry} \textbf{endfor} \\
\> \> \color{Mulberry} solve linear system\\
\> \> \color{Mulberry}- calculate {transport} \\
\> \> \color{Mulberry}\; (saturations, concentrations,...) \\
\> \> \color{Mulberry}\textbf{foreach} element \\
\> \> \> \color{dumuxYellow}-calculate update (explicitly) \\
\> \> \> \color{dumuxYellow}- adapt time step ({CFL}-like criterion) \\
\> \> \color{Mulberry}\textbf{endfor} \\
\> \> \color{Mulberry}- update old solution \\
\> \> \color{Mulberry}- postprocess (flash calculation, etc.)\\
\> \color{dumuxBlue}\textbf{endfor}\\
\> \color{dumuxBlue}- write result\\
\color{black}\textbf{endfor}\\
finalize
\end{tabbing}
\end{minipage}
\end{tabular}
\caption{Structure of a coupled fully-implicit (\textbf{left}) and a decoupled
semi-implicit (\textbf{right}) scheme in \Dumux.}
\label{fig:algorithm}
\end{figure}
\subsection{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}
\pagestyle{empty} % switch off headings and footer in order to get more space for the flowchart
\setlength{\voffset}{4.2cm}
% command for blocks
\newcommand{\step}[6]{
\begin{minipage}{7.5cm}
{\tiny \color{#1}\texttt{#2} $\Rightarrow$ \texttt{#3}}\\
\fcolorbox{#1}{white}{
\begin{minipage}{7.0cm}
\begin{scriptsize}
\texttt{#4} \hfill \color{gray}in: #5\color{black}\\
\hphantom{m}\begin{minipage}[t]{6.8cm}#6\end{minipage}
\end{scriptsize}
\end{minipage}}
\end{minipage}
}
% command for the arrow with text
\newcommand{\longArrow}[1]{
\begin{minipage}[b]{7.5cm}
\fcolorbox{white}{white}{
\begin{minipage}[b]{7.0cm}
\begin{center}
\begin{scriptsize}
$\overrightarrow{ %an arrow under which things may be written
\begin{array}{c} % in order to be able to write multiple lines under the arrow
#1\\
\hphantom{\hspace{6.5cm}}
\end{array}
}$
\end{scriptsize}
\end{center}
\end{minipage}%
}
\end{minipage}%
\hphantom{ $\overrightarrow{}$}%
}
% command for the arrow between steps
\newcommand{\shortArrow}{$\overrightarrow{}$}
% command for marking things as model specific
\newcommand{\modelSpecific}{\emph{model specific}\xspace}
% the distance between two lines
\newcommand{\dummyDistance}{\\[4\baselineskip]}
% THE FLOW CHART STARTS HERE
\noindent
\step{black}{main()}{Dumux::start<ProblemTypeTag>() $\Rightarrow$ start\_()}{start\_()}{start.hh}%
{start the simulation}
\shortArrow
\step{black}{start\_()}{timeManager.init()}{init()}{timemanager.hh}%
{initialization}
\shortArrow
\step{black}{start\_()}{timeManager.run()}{run()}{timemanager.hh}%
{time step management}
\dummyDistance
%
\longArrow{
\textnormal{\texttt{while(!finished)}}\\
\textnormal{\color{black}main}
\rightarrow \textnormal{\color{dumuxBlue}time step}
}
\step{dumuxBlue}{run()}{problem->timeIntegration()}{timeIntegration()}{implicitproblem.hh}%
{execute time integration scheme}%
\longArrow{
\textnormal{define number of allowed \textsc{Newton} fails}\\
\textnormal{(each halving dt)}
}
\dummyDistance
%
\step{dumuxBlue}{timeIntegration()}{model->update()}{update()}{implicitmodel.hh}%
{sth like numerical model}
\shortArrow
\step{dumuxBlue}{update()}{solver.execute()}{execute()}{newtonmethod.hh}%
{applying \textsc{Newton} method\\
keeps track of things, catching errors}
\longArrow{
\textnormal{\color{dumuxBlue}time step}
\rightarrow \textnormal{\color{Mulberry}Newton step}\\
\texttt{while(ctl.newtonProceed()}\\
\textnormal{uLastIter = uCurrentIter(model.uCur())}
}
\dummyDistance
%
\noindent
\step{Mulberry}{execute() $\Rightarrow$ execute\_()}{jacobianAsm.assemble()}{assemble()}{implicitassembler.hh}%
{linearize the problem:\\
add all element contributions to global \textsc{Jacobian}
and global residual}%
\shortArrow
\step{Mulberry}{assemble() $\Rightarrow$ asImp\_().assemble\_()}{resetSystem\_()}{resetSystem\_()}{implicitassembler.hh}%
{set r.h.s. (i.e. residual)\\
set \textsc{Jacobian} to zero }
\longArrow{
\textnormal{\color{Mulberry}Newton step}
\rightarrow \textnormal{\color{dumuxYellow}element}\\
\texttt{loop all elements}\\
}
\dummyDistance
%
\noindent
\step{dumuxYellow}{assemble() $\Rightarrow$ asImp\_().assemble\_()}{asImp\_().assembleElement\_()}{assembleElement\_()}{e.g. boxassembler.hh}%
{call local \textsc{Jacobian} and residual assembly}%
\shortArrow
\step{dumuxYellow}{assembleElement\_()}{model\_().localJacobian().assemble()}{assemble()}{implicitlocaljacobian.hh}%
{set curr. element, update element's fin.vol.geom.\\
reset local \textsc{Jacobian} to 0\\
update types of boundaries on this element}%
\shortArrow
\step{dumuxYellow}{assemble()}{prevVolVars\_.update(),curVolVars\_.update()}{update()}{e.g. 2pvolumevariables.hh}%
{call model (e.g. \texttt{2p})specific update of quantities defined for the volume:\\
variables for the \emph{current} and \emph{previous} timestep}%
\dummyDistance
%
\noindent
\step{dumuxYellow}{update()}{completeFluidState()}{completeFluidState()}{e.g. 2pvolumevariables.hh}%
{calculate all required fluid properties from the primary variables,
here the fluid system does the real work:\\
calculates, saves, and provides: densities, etc.}
\shortArrow
\step{dumuxYellow}{assemble()}{localResidual().eval()$\Rightarrow$asImp\_().eval()}{eval()}{e.g. implicitlocalresidual.hh}%
{the element's local residual is calculated:\\
see the next two stepstones}%
\shortArrow
\step{dumuxYellow}{eval()}{asImp\_().evalFluxes\_()}{evalFluxes\_()}{e.g. boxlocalresidual.hh}%
{evaluate the fluxes going into each finite volume,
this is \modelSpecific}
\dummyDistance
%
\step{dumuxYellow}{evalFluxes\_()}{this$\rightarrow$asImp\_().computeFlux()}{computeFlux()}{e.g. 2plocalresidual.hh}%
{this calculate the \modelSpecific fluxes (e.g. advective and diffusive)
using the \texttt{FluxVariables}}
\shortArrow
\step{dumuxYellow}{eval()}{asImp\_().evalVolumeTerms\_()}{evalVolumeTerms\_()}{implicitlocalresidual.hh}%
{evaluate the \modelSpecific storage and source terms for each finite volume}%
\shortArrow
\step{dumuxYellow}{eval()}{asImp\_().evalBoundary\_()}{evalBoundary\_()}{implicitlocalresidual.hh}%
{evaluate the \modelSpecific boundary conditions}%
\dummyDistance
%
\step{dumuxYellow}{assemble()}{asImp\_().evalPartialDerivative\_()}{evalPartialDerivative\_()}{e.g. implicitlocaljacobian.hh}%
{actually calculate the element's (local) \textsc{Jacobian}\\
matrix a property chooses backward/central/foward\\
differences. here: central differences}
\shortArrow
\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}
\dummyDistance
%
\step{dumuxYellow}{assemble\_()}{asImp\_().assembleElement\_()}{assembleElement\_()}{implicitassembler.hh}%
{Residual of the current solution is now\\
``numerically differentiated'', for the element i.e.\\
the local \textsc{Jacobian} matrix is calculated. }%
\longArrow{
\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}}.}
\step{dumuxYellow}{assemble\_()}{asImp\_().assembleElement\_()}{assembleElement\_()}{e.g. boxassembler.hh}
{Add to global residual.:\\
\texttt{resdidual\_[globI+=\\model\_().globalJacobian().resdidual(i)]}}
\dummyDistance
%
\longArrow{
\textnormal{loop vertices}\\
\textnormal{of an element}
}
\step{dumuxYellow}{assemble\_()}{asImp\_().assembleElement\_()}{assembleElement\_()}{e.g. boxassembler.hh}
{Add to global residual:\\
\texttt{(*matrix\_)[globI][globJ] +=\\model\_().localJacobian().mat(i,j)}}
\longArrow{
\textbf{\textbf{\color{dumuxYellow}element}}
\rightarrow \textbf{\color{Mulberry}Newton step}\\
\textnormal{Assembling of elements to global quantities is done.}
}
\dummyDistance
%
\step{Mulberry}{execute\_()}{while(ctl.newtonProceed())}{newtonProceed()}{newtoncontroller.hh}%
{Print information.\\
Start/ stop timer.}%
\longArrow{
\textnormal{set delta Vector to zero} \\
\textnormal{(this is what is}\\
\textnormal{solved for later)}\\
}
\step{Mulberry}{execute\_()}{ctl.newtonSolveLinear()}{newtonSolveLinear()}{newtoncontroller.hh}%
{Catching errors.\\
Ask the linear solver to solve the system.\\
i.e.: give \textsc{Jacobian}(matrix), delta(x), r.h.s.(residual) to linear solver\\
$\nabla r(x^k) \cdot \Delta x^k = r(x^k)$\\
tricky: each \textsc{Newton} step solves a linear system of equations.}%
\shortArrow
\step{Mulberry}{newtonSolveLinear()}{int converged = linearSolver\_.solve()}{solve()}{boxlinearsolver.hh}%
{Solve the linear system with the chosen backend.}%
\dummyDistance
%
\step{Mulberry}{execute\_()}{ctl.newtonUpdate()}{newtonUpdate()}{newtoncontroller.hh}%
{We solved for the change in solution, but need the solution:\\
Calculate current (this iteration) solution\\
\quad from last (iteration) solution and current (iteration) change in solution:\\
$x^{k+1} = x^k - \Delta x^k$ where $\Delta x^k = (\nabla r(x^k))^{-1} \cdot r(x^k)$}
\shortArrow
\step{Mulberry}{execute\_()}{ctl.newtonEndStep()}{newtonEndStep()}{newtoncontroller.hh}%
{Increase counter for number of \textsc{Newton} steps.\\
Print info.}%
\longArrow{
\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.}
}
\dummyDistance
%
\longArrow{
\textbf{\textbf{\color{Mulberry}Newton step}}
\rightarrow \textbf{\color{dumuxBlue}Time step}\\
\textnormal{\textsc{Newton} done}\\
\textnormal{if failed $\rightsquigarrow$ halve timestep size, restart loop}\\
}
\step{dumuxBlue}{execute\_()}{ctl.newtonEnd()}{newtonEnd()}{newtoncontroller.hh}%
{Tell the controller we are done}%
\shortArrow
\step{dumuxBlue}{update()}{asImp\_().updateSuccessful()}{updateSuccessful()}{e.g. implicitmodel.hh}%
{can be filled \modelSpecific}%
\dummyDistance
%
\longArrow{
\textnormal{in while(!finished)}
}
\step{dumuxBlue}{run()}{problem\_->postTimeStep()}{postTimeStep(),writeOutput()}{implicitproblem.hh}%
{Give the problem the chance to post-process the solution.}%
\longArrow{
\textnormal{write output}\\
\textnormal{uPrev $\leftarrow$ uCur}\\
\textnormal{time += dt, timestepIdx++}\\
\textnormal{deal with restart and episodes }
}
\dummyDistance
%
\step{dumuxBlue}{run()$\Rightarrow$setTimeStepSize(problem\_->nextTimeStepSize(dt))\\
$\Rightarrow$nextTimeStepSize()}
{newtonCtl\_.suggestTimestepSize()}{suggestTimestepSize()}{newtoncontroller.hh}%
{Determine new time step size from number of \textsc{Newton} steps.}%
\longArrow{
\textbf{\color{dumuxBlue}Time step}
\rightarrow \textbf{\color{black}main}\\
\textnormal{loop until simulation is finished}
}
\end{landscape}
\newpage
% Original pagestyle (headings and footer) were switched off,
% in order to get more space for the flowchart.
\pagestyle{scrheadings}
\normalsize
doc/handbook/CMakeLists.txt
+ 2
− 0
View file @ 226fa261
......@@ -9,6 +9,7 @@ set(TEX_INPUTS
3_tutorial.tex
3_tutorialcoupled.tex
3_tutorialdecoupled.tex
3_furtherpractice.tex
4_guidelines.tex
4_developingdumux.tex
4_externaltools.tex
......@@ -18,6 +19,7 @@ set(TEX_INPUTS
4_restartsimulations.tex
4_structure.tex
5_flowofthings.tex
5_stepsofasimulation.tex
5_fluidframework.tex
5_grids.tex
5_models.tex
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment