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

Handbook: some updates

Browse Source 
- adapt the "quick start" chapter to eWoms
- remove the dumux logo from the front page
- remove the "flow of things" and "tipps and tricks" chapters:
  - the former was not useful, IMHO but quite a burden to update and
    the latter rather belongs to the online documentation (wiki?)
- update the flowchart showing the layout of the source tree
This commit is contained in:
Andreas Lauser
2012-10-15 16:57:17 +02:00
parent 91b9730eb0
commit dd8e4520a0
22 changed files with 2073 additions and 2909 deletions
Download Patch File Download Diff File Expand all files Collapse all files

683
doc/handbook/DumuxFlow.tex
View File

@@ -1,683 +0,0 @@
\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:

1584
doc/handbook/EPS/dumux_strucutre_flowchart_horizontal_explained.eps
View File

File diff suppressed because it is too large Load Diff

1389
doc/handbook/EPS/ewoms_structure.eps Normal file
View File

File diff suppressed because it is too large Load Diff

26
doc/handbook/Makefile.am
View File

@@ -4,8 +4,8 @@ if BUILD_HANDBOOK
#EPS_FILES = EPS/tutorial-problemconfiguration.eps
TEXSOURCE = *.tex ./EPS/*.eps
MAINDOCS = dumux-handbook.dvi dumux-handbook.pdf dumux-handbook.ps
EXTRA_DIST = dumux-handbook.pdf $(TEXSOURCE) dumux-handbook.bib ModelDescriptions/*.tex
MAINDOCS = ewoms-handbook.dvi ewoms-handbook.pdf ewoms-handbook.ps
EXTRA_DIST = ewoms-handbook.pdf $(TEXSOURCE) ewoms-handbook.bib ModelDescriptions/*.tex
#Makefile.dist.in Makefile.dist.am
DOCS = $(HTDOCS) $(MAINDOCS)
@@ -15,26 +15,26 @@ BASEDIR=../..
CURDIR=doc/handbook
handbookdir=$(docdir)/handbook
handbook_DATA = dumux-handbook.pdf
handbook_DATA = ewoms-handbook.pdf
CLEANFILES = *.aux *.bbl *.blg *.log *.out *.toc *.dvi *.ps
CLEANFILES += *.4ct *.4tc *.css *.idv *.idx *.lg *.tid *.tmp *.tms *.xref
CLEANFILES += dumux-handbook*.png
CLEANFILES += ewoms-handbook*.png
CLEANFILES += $(DOCS)
CLEANFILES += $(EPS_FILES)
%.eps: $(srcdir)/%.jpg
$CONVERT $< $@
dumux-handbook.tex: $(EPS_FILES)
ewoms-handbook.tex: $(EPS_FILES)
dumux-handbook.pdf: $(TEXSOURCE)
@LATEX@ dumux-handbook.tex <&-
@BIBTEX@ dumux-handbook <&-
@LATEX@ dumux-handbook.tex <&-
@LATEX@ dumux-handbook.tex <&-
@DVIPDF@ dumux-handbook <&-
ewoms-handbook.pdf: $(TEXSOURCE)
@LATEX@ ewoms-handbook.tex <&-
@BIBTEX@ ewoms-handbook <&-
@LATEX@ ewoms-handbook.tex <&-
@LATEX@ ewoms-handbook.tex <&-
@DVIPDF@ ewoms-handbook <&-
doc: dumux-handbook.pdf
doc: ewoms-handbook.pdf
#dist-hook:
# sed $(srcdir)/Makefile.dist.am -e 's/Makefile\.dist/Makefile/g' > $(distdir)/Makefile.am
@@ -46,6 +46,6 @@ else
doc:
echo -n ""
endif
EXTRA_DIST= dumux-handbook.pdf
EXTRA_DIST= ewoms-handbook.pdf
include $(top_srcdir)/am/global-rules
include $(top_srcdir)/am/latex

742
doc/handbook/SVG/dumux_strucutre_flowchart_horizontal_explained.svg → doc/handbook/SVG/ewoms_structure.svg
View File

File diff suppressed because it is too large Load Diff
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 50 KiB

After

Width:  |  Height:  |  Size: 52 KiB

94
doc/handbook/TipsNTricks.tex
View File

@@ -1,94 +0,0 @@
\chapter{Tips \& Tricks}
This chapter tries to be a useful collection of tips and tricks that can be handy when working with
\Dumux. One of the most prominent ideas for developing \Dune / \Dumux is that reinventing the wheel in terms of FEM code should
be avoided. We try to follow this idea also in the day-to-day work by stating the \emph{tell us dogma}: ``If you found something useful,
handy or for other reasons helping when working with \Dumux: put it into this chapter.'' or inform at least the other developers and write
to the mailing list \texttt{dumux@iws.uni-stuttgart.de} so somebody else can.
\paragraph{Using the \Dumux-Eclipse profile}
Everybody using the same profile has the advantage of resulting in less conflicts when different developing environments are used:
\begin{enumerate}
\item in eclipse open: \texttt{Window} $\rightarrow$ \texttt{Preferences} $\rightarrow$ \texttt{C/C++} $\rightarrow$ \texttt{Code Style}
\item press the \texttt{Import} button
\item choose the file \texttt{eclipse\_profile.xml} from your dumux-devel directory
\item make sure that that now \Dumux is chosen in \texttt{Select a profile}
\end{enumerate}
\paragraph{Checking whether commit worked}
\Dumux is developed with the help of Subversion (short SVN, see \texttt{http://subversion.apache.org/pronunciation/index.html}). This means that at some point you will commit your new
and/or advanced features (hereafter called ``stuff'') to the repository. But maybe you forgot to commit this one and tiny change in one file you forgot about.
This may result in \Dumux not compiling any more on another person's computer after updating. You can prevent this by checking out \Dune and \Dumux twice. Now you can work in one version and after committing you can simply update the pristine version and see whether it still works there, too.
This approach really helps keeping the bumps in the work-flow small.
\paragraph{Using \Dune debug streams}
\Dune provides a helpful feature, for keeping your debug-output organized.
In stead of juggling with a bazillion \texttt{std::cout <<} statements or keeping some debug-precompiler statements organized, which are generally and strongly discouraged see \ref{guidelines} in order not to get
flooded away by your output \Dune gives you a nice tool by the so called debug streams.
These are streams like \texttt{cout} but they can be switched on and off for the whole project.
Maybe if you are really in the dark you want to see all your debug information. Another time you may only want to be warned if something is going seriously wrong during a simulation.
This can be achieved by setting the debug streams to desired values. There are five levels:
\begin{verbatim}
5 - grave (dgrave)
4 - warning (dwarn)
3 - info (dinfo)
2 - verbose (dverb)
1 - very verbose (dvverb)
\end{verbatim}
They are used as follows: \lstinline{Dune::dinfo << "message";} or \lstinline{Dune::dgrave << "message";} .
The debug streams are switched on/off via setting \lstinline{#define DUNE_MINIMAL_DEBUG_LEVEL 4}
in the source your application. If the value is set to i.\,g. 4 the output generated after \lstinline{Dune::dinfo} (level 4 and 5) will printed anywhere.
\paragraph{File name and line number by predefined macro}
If you want to know where some output or debug information came from, you can use the predefined macros \lstinline{__FILE__} and \lstinline{__LINE__}
which are used like\\
\lstinline{dataFile << "# This was written from "<< __FILE__ << ", line " << __LINE__ << "\n";}\\
which translates into a line in the output file reading\\
\lstinline{# This was written from [..]/dumux/dumux/io/outputToFile.hh, line 261}\\
This can also be very useful, if you want to have information about where some warning or debug information was issued.
\paragraph{Option files optim.opts and debug.opts}
As explained on page \pageref{buildIt} \Dune and \Dumux are built with the help of the \texttt{dunecontrol}.
A lot of options need to be specified for that, which is done in the \texttt{debug.opts} resp. \texttt{optim.opts}
(plus \texttt{.suse11.2} if applicable) in your \texttt{dumux-devel} directory. These two files differ in the way \Dune and \Dumux are compiled: either for debugging or for fast simulation. Switching between these two states is really
worth it: speedup of factor $\approx 2$.
If you want your \Dumux fast than simply build dunecontrol with the \texttt{optim.opts}. BUT: Programs that are compiled with optimization can hardly
be debugged because the debugger gets confused. But the cool thing is, that you do NOT need to run dunecontrol if you want to start debugging. You can simply remove the optimization options from your application's Makefile:
\begin{itemize}
\item open your application's Makefile with the text editor of your choice
\item find the line including \texttt{CXXFLAGS =}
\item these are the options given to the \Cplusplus compiler
\item add \texttt{-g} (debugging symbols)
\item remove \texttt{-O3} (third level optimization, i.\,e. do not care for anything but execution speed), \texttt{-march=native} and \texttt{-DNDEBUG}.
\item build your application again.
\item as long as you only debug your application (and no \Dune stuff) this works, otherwise recompile with dunecontrol and \texttt{debug.opts}
\item compiling without optimization takes also shorter time
\end{itemize}
(The other possibility is to run \texttt{dunecontrol} with \texttt{debug.opts} and afterwards adding \texttt{-O3} into your application Makefile. The performance penalty does not make a big difference and so do the other options besides \texttt{-O3})
Debugging with the optimization options active will lead to erratic behavior while debugging.
\paragraph{Faster build with dunecontrol}
A complete build using \texttt{dunecontrol} takes some time. If there were just small changes in the folder structure, it is usually sufficient to run dunecontrol with option \texttt{autogen} instead of \texttt{all}, and afterwards creating the makefiles with option \texttt{configure}.
An other possibility to speed up dunecontrol is caching of configure results. Add to the configure flags the line \texttt{--cache-file=/tmp/dune-config.cache} in you options file.
\paragraph{Error messages related to the property system}
The property system is a powerful tool and internally does some template and macro magic.
The price for it are sometimes unintuitive compiler error messages. For example if the
definition of a property could not be found, the error is:
\begin{lstlisting}[style=DumuxCode,numbers=none]
error: no type named 'p' in 'struct Dumux::Properties::GetProperty<Dumux::Properties::TTag::TestProblem, Dumux::Properties::PTag::Scalar, Dumux::Properties::TTag::TestProblem, -1000>'
\end{lstlisting}
So check whether you did not misspelled any name related to the property system in the
line of the error message and whether you really declared the type tag you use there.

0
doc/handbook/dumux-handbook.bib → doc/handbook/ewoms-handbook.bib
View File

27
doc/handbook/dumux-handbook.tex → doc/handbook/ewoms-handbook.tex
View File

@@ -29,8 +29,8 @@
aboveskip=\bigskipamount,
belowskip=\bigskipamount
}
% for listings of DuMuX code
\lstdefinestyle{DumuxCode}
% for listings of eWoms code
\lstdefinestyle{eWomsCode}
{language=C++,
basicstyle=\ttfamily\scriptsize,
numbers=left,
@@ -73,10 +73,12 @@
\DeclareGraphicsExtensions{.eps, .jpg}
% Dune logo
% Dune occuring in text
\newcommand{\Dune}{{DUNE}\xspace}
% DuMuX logo
% dumux occuring in text
\newcommand{\Dumux}{\texorpdfstring{Du\-Mu$^\text{x}$\xspace}{DuMuX}}
% eWoms occuring in text
\newcommand{\eWoms}{eWoms\xspace}
% beautify C++
\DeclareRobustCommand\Cplusplus{\texorpdfstring{C\raisebox{2pt}{{\relsize{-3}++}}\xspace}{C++}}
@@ -131,9 +133,9 @@
\title{
\begin{center}
\includegraphics[width=0.7\textwidth]{../logo/dumux_logo_hires_whitebg.eps}
\\[3cm]
{\Huge Handbook}
%\includegraphics[width=0.7\textwidth]{../logo/dumux_logo_hires_whitebg.eps}
%\\[3cm]
{\Huge The \eWoms Handbook}
\end{center}
}
@@ -142,12 +144,7 @@
\date{\today}
\publishers{%
\vspace{10mm}
{\normalsize Lehrstuhl f\"ur Hydromechanik und Hydrosystemmodellierung, \\
Universit\"at Stuttgart, Paffenwaldring 61, D-70569 Stuttgart, Germany}\\
%
\bigskip
{\normalsize \texttt{\url{http://dumux.org}}}\\
{\normalsize \texttt{\url{http://opm-project.org/ewoms}}}\\
}
\makeindex
@@ -170,12 +167,10 @@ Universit\"at Stuttgart, Paffenwaldring 61, D-70569 Stuttgart, Germany}\\
\input{propertysystem}
\input{fluidframework}
\input{models}
\input{DumuxFlow}
\input{NewtonInANutshell}
\input{TipsNTricks}
\input{install}
\bibliographystyle{plain}
\bibliography{dumux-handbook}
\bibliography{ewoms-handbook}
\printindex
\end{document}

2
doc/handbook/fluidframework.tex
View File

@@ -468,5 +468,5 @@ system of equations is closed.
%%% Local Variables:
%%% mode: latex
%%% TeX-master: "dumux-handbook"
%%% TeX-master: "ewoms-handbook"
%%% End:

5
doc/handbook/getting-started.tex
View File

@@ -6,3 +6,8 @@ Then a quick start guide for the first \Dumux experience is provided.
\input{quick-install}
\input{quickstart-guide}
\input{parameterTree}
%%% Local Variables:
%%% mode: latex
%%% TeX-master: "ewoms-handbook"
%%% End:

2
doc/handbook/guidelines.tex
View File

@@ -24,7 +24,7 @@ been written by oneself.
\item Variables should be named as self-explaining as possible: especially abbreviations should be avoided (saturation in stead of S)
\item Method parameters which are not self-explanatory should always
have a meaningful comment a at calling sites. Example:
\begin{lstlisting}[style=DumuxCode]
\begin{lstlisting}[style=eWomsCode]
localResidual.eval(/*includeBoundaries=*/true);
\end{lstlisting}
\item Private Data Variables: Names of private data variables end with an underscore and are the only variables that contain underscores.

4
doc/handbook/install.tex
View File

@@ -271,7 +271,7 @@ This applies for \Dumux, too. Rebuilding the handbook can be done as follows:
\begin{lstlisting}[style=Bash]
$ cd dumux/doc/handbook
$ make dumux-handbook.pdf
$ make ewoms-handbook.pdf
\end{lstlisting}
@@ -371,5 +371,5 @@ you run \texttt{dunecontrol}.
%%% Local Variables:
%%% mode: latex
%%% TeX-master: "dumux-handbook"
%%% TeX-master: "ewoms-handbook"
%%% End:

33
doc/handbook/intro.tex
View File

@@ -1,8 +1,8 @@
\chapter{Introduction}
\Dumux aims to be a generic framework for the simulation of multiphase
\eWoms aims to be a generic framework for the simulation of multiphase
fluid flow and transport processes in porous media using continuum
mechanical approaches. At the same time, \Dumux aims to deliver
mechanical approaches. At the same time, \eWoms aims to deliver
top-notch computational performance, high flexibility, a sound
software architecture and the ability to run on anything from single
processor systems to highly parallel supercomputers with specialized
@@ -10,13 +10,13 @@ hardware architectures.
The means to achieve these somewhat contradictory goals are the
thorough use of object oriented design in conjunction with template
programming. These requirements call for \Cplusplus as the implementation
language.
programming. These requirements motivated the decision to use
\Cplusplus as the implementation language for \eWoms.
One of the more complex issues when dealing with parallel continuum
models is managing the grids used for the spatial discretization of
the physical model. To date, no generic and efficient approach exists
for all possible cases, so \Dumux is build on top of \Dune, the
for all possible cases, so \eWoms is build on top of \Dune, the
\textbf{D}istributed and \textbf{U}nified \textbf{N}umerics
\textbf{E}nvironment~\cite{DUNE-HP}. \Dune provides a generic interface
to many existing grid management libraries such as UG~\cite{UG-HP},
@@ -63,13 +63,18 @@ finite element shape functions, while \texttt{dune-istl} is the
and provides generic, highly optimized linear algebra routines for
solving the generated systems.
\Dumux comes in form of an additional module \texttt{dumux}.
It depends on the \Dune core modules
\texttt{dune-common}, \texttt{dune-grid}, \texttt{dune-istl}, and on \texttt{dune-localfunctions}.
The main intention of \Dumux is to provide a framework for an easy and efficient
implementation of new physical models for porous media flow problems,
ranging from problem formulation and the selection of
spatial and temporal discretization schemes as well as nonlinear solvers,
to general concepts for model coupling.
Moreover, \Dumux includes ready to use numerical models and a few example applications.
\eWoms comes in form of an additional module \Dune module
'\texttt{ewoms}'. It depends on the \Dune core modules
\texttt{dune-common}, \texttt{dune-grid}, \texttt{dune-istl}, and on
\texttt{dune-localfunctions}. The main intention of \eWoms is to
provide a framework for an easy and efficient implementation of new
physical models for porous media flow problems, ranging from problem
formulation and the selection of spatial and temporal discretization
schemes as well as nonlinear solvers, to general concepts for model
coupling. Moreover, \eWoms includes ready-to-use numerical models and
a few example applications.
%%% Local Variables:
%%% mode: latex
%%% TeX-master: "ewoms-handbook"
%%% End:

6
doc/handbook/models.tex
View File

@@ -209,10 +209,10 @@ An h-adaptive implementation of both \nameref{ch:2p_decoupled} and \nameref{ch:2
\paragraph{Saturation model}
\input{ModelDescriptions/2pdecoupledsaturationmodel}
\subsubsection{The two-phase, two-component model}\label{ch:2p2c_decoupled}
\input{ModelDescriptions/decoupled2p2c}
%\subsubsection{The two-phase, two-component model}\label{ch:2p2c_decoupled}
%\input{ModelDescriptions/decoupled2p2c}
%%% Local Variables:
%%% mode: latex
%%% TeX-master: "dumux-handbook"
%%% TeX-master: "ewoms-handbook"
%%% End:

119
doc/handbook/parameterTree.tex
View File

@@ -1,92 +1,41 @@
\section{Parameter Files in \Dumux}
\section{Specifying Parameters}
\label{sec:inputFiles}
In section \ref{quick-start-guide} an application was started using an input file.
This file is worth taking a closer look at because using it considerably improves usability.
\begin{itemize}
\item The parameter file is read in by the compiled program. This way you can change
values in there without having to recompile the whole application.
\item You can use the parameter file in order to back up parameters that you used for a certain model run.
\item The parameter file is easily extendable.
\end{itemize}
After having run the example application from section \ref{quick-start-guide} you will (almost) get the following output\footnote{If you did not get the output, restart the application the following way:
\texttt{./test{\_}2p -parameterFile ./test\_2p.input -PrintParameters 1 }} at the end of the simulation run:
As already mentioned in the previous section, \eWoms allows to specify
a number of parameters at run time. A description of these parameters
can usually obtained by passing the \texttt{--help} parameter to the
executable. The values used for these parameters are printed to the
terminal during the start-up of the simulation, e.g. the if the \texttt{lens\_immiscible}
simulation is run with the parameters \texttt{--end-time=30e3 --foo-param=123}, there will an output similar to
\begin{lstlisting}[style=Bash]
###############################
# Run-time specified parameters:
###############################
dtInitial = "1"
gridFile = "./grids/test_2p.dgf"
parameterFile = "./test_2p.input"
tEnd = "1"
[ SpatialParameters ]
lensLowerLeftX = "1.0"
lensLowerLeftY = "2.0"
lensUpperRightX = "4.0"
lensUpperRightY = "3.0"
###############################
# Compile-time specified parameters:
###############################
EnableGravity = "1"
EnableHints = "0"
EnableJacobianRecycling = "1"
EnablePartialReassemble = "1"
MassUpwindWeight = "1"
MaxTimeStepSize = "1e+100"
NumericDifferenceMethod = "1"
PreconditionerRelaxation = "1"
[ LinearSolver ]
MaxIterations = "250"
ResidualReduction = "1e-06"
Verbosity = "0"
[ Newton ]
AbsTolerance = "1e-05"
EnableAbsoluteCriterion = "0"
EnableRelativeCriterion = "1"
MaxSteps = "18"
RelTolerance = "1e-08"
SatisfyAbsAndRel = "0"
TargetSteps = "10"
UseLineSearch = "0"
WriteConvergence = "0"
###############################
# UNUSED PARAMETERS:
###############################
SpatialParameters.sthIMadeUp = "42"
###########
# Parameters specified at run-time
###########
EndTime="30e3"
###########
# Parameters with use compile-time fallback values
###########
AmgCoarsenTarget="5000"
...
VtkWriteSaturations="1"
VtkWriteTemperature="1"
VtkWriteViscosities="0"
###########
# Parameters unknown to the simulation
###########
FooParam="123"
\end{lstlisting}
A number of things can be learned from this. Most prominently it tells you the parameters, that can easily be added to the input file without having to change anything in the source code.
By simply adding the lines\\
\texttt{[ Newton ]\\
RelTolerance = 1e-11}\\
to the input file you can specify that the Newton solver considers itself converged for an error a thousand times smaller.
This can be directly copy-and-pasted into a file
(e.g. \texttt{myparams.ini}) and loaded by passing the
\texttt{--parameter-file=myparams.ini} parameter to the simulation the
next time it is run.
Secondly you can see, that there is a variable in the input file which the program did not use:
\newline
\texttt{SpatialParameters.sthIMadeUp = "42"}.
\newline
This output was generated by adding the line \\
\lstinline{sthIMadeUp = 42 # [strangeUnit]}\\
at the end of the parameter file. Because the application did not read in this value it is shown here under \texttt{UNUSED PARAMETERS}. You can also see, that the variable was grouped into the SpatialParameters group, because no new group was started.
When you do simulations, always look for the paramters which are
unknown to the simulation, as this is \emph{very} useful for spotting
typos.
This feature is \emph{very} useful for debugging or spotting typos. If you want to overwrite one of the parameters listed under \texttt{Compile-time specified parameters} and misspelled it in the input file, it will be listed in the \texttt{UNUSED PARAMETERS} section.
For further use of the input file please refer to the problem file
\newline
\texttt{/test/boxmodels/2p2c/injectionproblem.hh}.
\newline
In there, a number of parameters are read in for use in the actual problem.
If you also want to specify the grid and spatial extension of your problem via the parameter file, please have a look at
\newline
\texttt{/test/boxmodels/2p/}.
\subsection{Technical Issues}
In case you want to learn more about how the input files work, please have a look at the very helpful \Dune documentation, look for \texttt{Dune::ParameterTree}.
The parameter tree can also be filled without the help of a text file. Everything that is specified in a \Dumux input file can also be specified directly on the command line. If there is also an input file, the respective parameter on the command line has precedence.
All applications have a help message which you can read by giving \texttt{--help} as a command line argument to the application. A message listing syntax and the mandatory input will be displayed on the command line.
%%% Local Variables:
%%% mode: latex
%%% TeX-master: "ewoms-handbook"
%%% End:

44
doc/handbook/propertysystem.tex
View File

@@ -43,7 +43,7 @@ namespace \texttt{Dumux::Properties}.
\subsection*{Defining Type Tags}
New nodes in the type tag hierarchy can be defined using
\begin{lstlisting}[style=DumuxCode]
\begin{lstlisting}[style=eWomsCode]
NEW_TYPE_TAG(NewTypeTagName, INHERITS_FROM(BaseTagName1, BaseTagName2, ...));
\end{lstlisting}
where the \texttt{INHERITS\_FROM} part is optional. To avoid
@@ -52,7 +52,7 @@ once for a program.
\vskip1ex\noindent
Example:
\begin{lstlisting}[style=DumuxCode]
\begin{lstlisting}[style=eWomsCode]
namespace Dumux {
namespace Properties {
NEW_TYPE_TAG(MyBaseTypeTag1);
@@ -66,7 +66,7 @@ NEW_TYPE_TAG(MyDerivedTypeTag, INHERITS_FROM(MyBaseTypeTag1, MyBaseTypeTag2));
New property tags -- i.e. labels for properties -- are declared
using
\begin{lstlisting}[style=DumuxCode]
\begin{lstlisting}[style=eWomsCode]
NEW_PROP_TAG(NewPropTagName);
\end{lstlisting}
A property tag can be declared arbitrarily often, in fact it is
@@ -75,7 +75,7 @@ are used.
\vskip1ex\noindent
Example:
\begin{lstlisting}[style=DumuxCode]
\begin{lstlisting}[style=eWomsCode]
namespace Dumux {
namespace Properties {
NEW_PROP_TAG(MyPropertyTag);
@@ -86,7 +86,7 @@ NEW_PROP_TAG(MyPropertyTag);
The value of a property on a given node of the type tag hierarchy is
defined using
\begin{lstlisting}[style=DumuxCode]
\begin{lstlisting}[style=eWomsCode]
SET_PROP(TypeTagName, PropertyTagName)
{
// arbitrary body of a struct
@@ -97,7 +97,7 @@ although properties may be overwritten for derived type tags.
Also, the following convenience macros are available to define simple
properties:
\begin{lstlisting}[style=DumuxCode]
\begin{lstlisting}[style=eWomsCode]
SET_TYPE_PROP(TypeTagName, PropertyTagName, type);
SET_BOOL_PROP(TypeTagName, PropertyTagName, booleanValue);
SET_INT_PROP(TypeTagName, PropertyTagName, integerValue);
@@ -106,7 +106,7 @@ SET_SCALAR_PROP(TypeTagName, PropertyTagName, floatingPointValue);
\vskip1ex\noindent
Example:
\begin{lstlisting}[style=DumuxCode]
\begin{lstlisting}[style=eWomsCode]
namespace Dumux {
namespace Properties {
NEW_TYPE_TAG(MyTypeTag);
@@ -135,7 +135,7 @@ SET_SCALAR_PROP(MyTypeTag, MyScalarValue, 12345.67890);
Sometimes some inherited properties do not make sense for a certain
node in the type tag hierarchy. These properties can be explicitly
un-set using
\begin{lstlisting}[style=DumuxCode]
\begin{lstlisting}[style=eWomsCode]
UNSET_PROP(TypeTagName, PropertyTagName);
\end{lstlisting}
The un-set property can not be set for the same type tag, but of
@@ -143,7 +143,7 @@ course derived type tags may set it again.
\vskip1ex\noindent
Example:
\begin{lstlisting}[style=DumuxCode]
\begin{lstlisting}[style=eWomsCode]
namespace Dumux {
namespace Properties {
NEW_TYPE_TAG(BaseTypeTag);
@@ -169,11 +169,11 @@ ought to be used.
\subsection*{Retrieving Property Values}
The value of a property can be retrieved using
\begin{lstlisting}[style=DumuxCode]
\begin{lstlisting}[style=eWomsCode]
GET_PROP(TypeTag, PropertyTag)
\end{lstlisting}
or using the convenience macros
\begin{lstlisting}[style=DumuxCode]
\begin{lstlisting}[style=eWomsCode]
GET_PROP_TYPE(TypeTag, PropertyTag)
GET_PROP_VALUE(TypeTag, PropertyTag)
\end{lstlisting}
@@ -182,19 +182,19 @@ GET_PROP_VALUE(TypeTag, PropertyTag)
\noindent
The first convenience macro retrieves the type defined using
\texttt{SET\_TYPE\_PROP} and is equivalent to
\begin{lstlisting}[style=DumuxCode]
\begin{lstlisting}[style=eWomsCode]
GET_PROP(TypeTag, PropertyTag)::type
\end{lstlisting}
while the second convenience macro retrieves the value of any property
defined using one of the macros \texttt{SET\_}$\{$\texttt{INT,BOOL,SCALAR}$\}$\texttt{\_PROP} and is
equivalent to
\begin{lstlisting}[style=DumuxCode]
\begin{lstlisting}[style=eWomsCode]
GET_PROP(TypeTag, PropertyTag)::value
\end{lstlisting}
\vskip1ex\noindent
Example:\nolinebreak
\begin{lstlisting}[style=DumuxCode]
\begin{lstlisting}[style=eWomsCode]
template <TypeTag>
class MyClass {
// retrieve the ::value attribute of the 'NumEq' property
@@ -219,7 +219,7 @@ retrieve other properties using the \texttt{GET\_PROP} macros.
\vskip1ex\noindent
Example:
\begin{lstlisting}[style=DumuxCode]
\begin{lstlisting}[style=eWomsCode]
SET_PROP(MyModelTypeTag, Vector)
{
private: typedef typename GET_PROP_TYPE(TypeTag, Scalar) Scalar;
@@ -257,7 +257,7 @@ diagram for the car types above might look like outlined in Figure
Using the \Dumux property system, this inheritance hierarchy is
defined by:
\begin{lstlisting}[name=propsyscars,style=DumuxCode]
\begin{lstlisting}[name=propsyscars,style=eWomsCode]
#include <dumux/common/propertysystem.hh>
#include <iostream>
@@ -275,7 +275,7 @@ Figure \ref{fig:car-propertynames} lists a few property names which
make sense for at least one of the nodes of Figure
\ref{fig:car-hierarchy}. These property names can be declared as
follows:
\begin{lstlisting}[name=propsyscars,style=DumuxCode]
\begin{lstlisting}[name=propsyscars,style=eWomsCode]
NEW_PROP_TAG(TopSpeed); // [km/h]
NEW_PROP_TAG(NumSeats); // []
NEW_PROP_TAG(CanonCaliber); // [mm]
@@ -311,7 +311,7 @@ the following:
\noindent
Using the \Dumux property system, these assumptions are formulated
using
\begin{lstlisting}[name=propsyscars,style=DumuxCode]
\begin{lstlisting}[name=propsyscars,style=eWomsCode]
SET_INT_PROP(CompactCar, TopSpeed, GET_PROP_VALUE(TypeTag, GasUsage) * 30);
SET_INT_PROP(CompactCar, NumSeats, 5);
SET_INT_PROP(CompactCar, GasUsage, 4);
@@ -337,7 +337,7 @@ SET_INT_PROP(HummerH1, TopSpeed, GET_PROP_VALUE(TTAG(Pickup), TopSpeed));
\noindent
At this point, the Hummer-H1 has a $\unit[120]{mm}$ canon which it inherited
from its military ancestor. It can be removed by
\begin{lstlisting}[name=propsyscars,style=DumuxCode]
\begin{lstlisting}[name=propsyscars,style=eWomsCode]
UNSET_PROP(HummerH1, CanonCaliber);
}} // close namespaces
@@ -346,7 +346,7 @@ UNSET_PROP(HummerH1, CanonCaliber);
\noindent
Now property values can be retrieved and some diagnostic messages can
be generated. For example
\begin{lstlisting}[name=propsyscars,style=DumuxCode]
\begin{lstlisting}[name=propsyscars,style=eWomsCode]
int main()
{
std::cout << "top speed of sedan: " << GET_PROP_VALUE(TTAG(Sedan), TopSpeed) << "\n";
@@ -359,7 +359,7 @@ int main()
}
\end{lstlisting}
will yield the following output:
\begin{lstlisting}[style=DumuxCode]
\begin{lstlisting}[style=eWomsCode]
top speed of sedan: 210
top speed of truck: 100
Properties for Sedan:
@@ -373,5 +373,5 @@ Properties for Sedan:
%%% Local Variables:
%%% mode: latex
%%% TeX-master: "dumux-handbook"
%%% TeX-master: "ewoms-handbook"
%%% End:

97
doc/handbook/quick-install.tex
View File

@@ -1,64 +1,63 @@
\section{Quick Installation of \Dumux} \label{quick-install}
\section{Quick Installation of \eWoms} \label{quick-install}
This only provides one quick way of installing \Dumux.
You should have a recent working Linux environment, no \Dune core modules should be installed.
If you need more information,
have \Dune already installed, please have a look at the detailed installation
instructions in Section \ref{install}.
This only provides one quick way of installing \eWoms. As a
pre-requisite it is assumed that you are using \eWoms with a recent
Linux distribution that has the appropriate development packages
installed, but without the distribution packages of the \Dune core
modules installed. If you need more information, or if you have \Dune
already installed, please have a look at the detailed installation
instructions in Section \ref{install}.
\subsection{Obtaining the code with the script \texttt{checkout-dumux}}
\subsection{Retrieving the code}
The shell-script \texttt{checkout-dumux} facilitates setting up a {\Dune}/{\Dumux} directory tree (currently for the trunk version).
It is contained in the download section of the \Dumux web page \cite{DUMUX-HP}.
For example the second line below will check out the required \Dune modules and \texttt{dumux},
\texttt{dumux-devel} and the \texttt{external} folder, which contains some useful external software and libraries.
Again, \texttt{joeuser} needs to be replaced by the actual user name.
You can download all \Dune modules by either downloading and unpacking
the tarballs for the \Dune-2.2 release as well as downloading and
unpacking the tarball for the \eWoms 2.2 release, or by retrieving the
code directly from their respective source-code repositories. If you
decide to use the first method, make sure to unpack all tarballs into
the same directory, for the second method you can enter the following
code snipplet into a terminal:
\begin{lstlisting}[style=Bash]
$ checkout-dumux -h # show help,
$ checkout-dumux -gme -u joeuser -p password -d DUMUX
for DUNE_MODULE in common geometry grid istl localfunctions; do \
git svn clone https://svn.dune-project.org/svn/dune-$DUNE_MODULE/branches/release-2.2 $DUNE_MODULE \
done
git clone --branch "release-2.2" git://github.com/OPM/ewoms.git
\end{lstlisting}
\subsection{Build of \Dune and \Dumux}
\subsection{Building \Dune and \eWoms}
\label{buildIt}
Building of \Dune and \Dumux is done by the command-line script \texttt{dunecontrol} as described in \Dune Installation Notes \cite{DUNE-INST}
and in much more comprehensive form in the \Dune Buildsystem Howto \cite{DUNE-BS}.
If something fails during the execution of \texttt{dunecontrol} feel free to report it to the \Dune or \Dumux developer mailing list,
but also try to include error details.
It is possible to compile \Dumux with nearly no explicit options to the build system.
However, for the successful compilation of \Dune and \Dumux, it is currently necessary to pass the
the option \texttt{-fno-strict-aliasing} to the \Cplusplus compiler
\cite{WIKIPED-ALIASING}, which is done here via a command-line argument to \texttt{dunecontrol}:
\eWoms is (almost) a standard \Dune module and is recommended to be
build using the \Dune build system~\cite{DUNE-BS}. \eWoms ships with a
few option files for \Dune's build script, \texttt{dunecontrol}. For
the first time compilation we recommend to use the options optimized
for the debugging experience, \texttt{debug.opts}:
\begin{lstlisting}[style=Bash]
$ # make sure you are in the directory DUNE-Root
$ ./dune-common/bin/dunecontrol --configure-opts="CXXFLAGS=-fno-strict-aliasing" all
# make sure you are in the DUNE's root directory
./dune-common/bin/dunecontrol --opts=ewoms/debug.opts all
\end{lstlisting}
Too many options can make life hard. That's why usually option files are being used together with \texttt{dunecontrol} and its sub-tools.
Larger sets of options are kept in them. If you are going to compile with options suited for debugging the code, the following
can be a starting point:
If you finished with developing and testing your own code on
small-scale problems, re-compile everything with compiler
optimizations enabled before a production run:
\begin{lstlisting}[style=Bash]
$ # make sure you are in the directory DUNE-Root
$ cp dumux/debug.opts my-debug.opts # create a personal version
$ gedit my-debug.opts # optional editing the options file
$ ./dune-common/bin/dunecontrol --opts=my-debug.opts all
# make sure you are in the DUNE's root directory
./dune-common/bin/dunecontrol --opts=ewoms/optim.opts all
\end{lstlisting}
More optimized code, which is typically not usable for standard debugging tasks, can be produced by
\begin{lstlisting}[style=Bash]
$ cp dumux/optim.opts my-optim.opts
$ ./dune-common/bin/dunecontrol --opts=my-optim.opts all
\end{lstlisting}
Sometimes it is necessary to have additional options which
are specific to a package set of an operating system or
sometimes you have your own preferences.
Feel free to work with your own set of options, which may evolve over time.
The option files above are to be understood more as a starting point
for setting up an own customization than as something which is fixed.
The use of external libraries can make it necessary to add quite many options in an option-file.
It can be helpful to give your customized option file its own name, as done above.
One avoids confusing it with the option files which came out of the distribution
and which can be possibly updated by subversion later on.
Sometimes it is necessary to have additional options which are
specific to the concrete operating system you use or you might also
have special needs. For this reason, the option files mentioned above
are to be rather understood as a starting point for specifying the own
options than as something which is fixed; feel free to copy and modify
them. For example, if you need external libraries, you might need to
add or modify quite many options. To avoid confusion, it can also be
helpful to use a different name for your customized option files.
%%% Local Variables:
%%% mode: latex
%%% TeX-master: "ewoms-handbook"
%%% End:

91
doc/handbook/quickstart-guide.tex
View File

@@ -1,12 +1,87 @@
\section[Quick start guide]{Quick start guide: The first run of a test application}\label{quick-start-guide}
\section[Quick start guide]{Quick start guide: The first run of a test application}
\label{quick-start-guide}
The previous section showed how to install and compile \Dumux. This chapter shall give a very brief introduction how to run a first test application and how to visualize the first output files. Only the rough steps will be described here. More detailed explanations can be found in the tutorials in the following chapter.
The previous section showed how to install and compile \eWoms. This
chapter gives you a very brief introduction how to run a first test
application and how to visualize the output files it produces. Only the
rough steps will be described here; More detailed explanations can be
found in the tutorials in the following chapter.
\begin{enumerate}
\item Go to the directory \texttt{/test}. There, various test application folders can be found. Let us consider as example \texttt{boxmodels/test{\_}2p}:
\item Enter the folder \texttt{boxmodels/2p}. If everything was compiled correctly, there should be an executable \texttt{test{\_}2p}. Otherwise, type \texttt{make test{\_}2p} in order to compile the application. To run the simulation, type\\
\texttt{./test{\_}2p -parameterFile ./test\_2p.input}\\
into the console. The parameter \texttt{-parameterFile} specifies that all important parameters (like first timestep size, end of simulation and location of the grid file) can be found in a text file in the same directory with the name \texttt{test\_2p.input}.
\item The simulation starts and produces some .vtu output files and also a .pvd file. The .pvd file can be used to examine time series and summarizes the .vtu files. It is possible to stop a running application by pressing $<$Ctrl$><$c$>$.
\item You can display the results using the visualization tool ParaView (or alternatively VisIt). Just type \texttt{paraview} in the console and open the .pvd file. On the left hand side, you can choose the desired parameter to be displayed.
\item Go to the directory \texttt{/test}. There, various test
application folders can be found. Let us consider as example
\texttt{boxmodels/lens{\_}immiscible}:
\item Enter the folder \texttt{boxmodels/}.
\item By default, the \texttt{dunecontrol} command only compiles the
parts of \Dune modules that are necessary to build modules depending
on the given module. For \eWoms, \texttt{dunecontrol} does not build
anything by default, because \eWoms only provides \Cplusplus
template classes but no libraries that need compilation. To compile
the test simulation for the "lens" problem which uses the immiscible
box model, enter
\begin{lstlisting}[style=Bash]
make lens_immiscible
\end{lstlisting}
You may also compile all available tests which use the box scheme by entering
\begin{lstlisting}[style=Bash]
make check
\end{lstlisting}
This takes quite some time, but if you have a multi-core processor
with \$N cores, you can considerably speed up compilation by using all
of available cores by using
\begin{lstlisting}[style=Bash]
make -j $N check
\end{lstlisting}
%$
\item If everything was compiled correctly, there should be an
executable \texttt{lens{\_}immiscible}. To run the simulation,
simply run it, i.e. enter
\begin{lstlisting}[style=Bash]
./lens_immiscible
\end{lstlisting}
You may also want to change some parameters from the command line. For
example, if you want to change the time up to which the simulation is
run to $30.000$ seconds, use
\begin{lstlisting}[style=Bash]
./lens_immiscible --end-time=30e3
\end{lstlisting}
You can also get a list of parameters recognized by the
simulation together with a brief description, by running
\begin{lstlisting}[style=Bash]
./lens_immiscible --help
\end{lstlisting}
\item After this, the simulation should start and produce some output
on the terminal. It is possible to interrupt it at any time by
pressing \texttt{<Ctrl>+<C>}.
\item The actual output files produced by the simulation are a series
of \texttt{.vtu} files and a \texttt{.pvd} file. The \texttt{.vtu}
contain "visualization ready" data which is produced during the
simulation, while the \texttt{.pvd} file "stitches" these together
into a coherent data set. For example, the \texttt{.pvd} holds the
simulation time at which a given data-set is produced which can
later be used for visualization.
\item You can now display the result of the simulation using the
visualization tool ParaView (or, if you prefer, VisIt). Just type
\texttt{paraview} in the console and open the \texttt{.pvd} file. On
the left hand side, you should now be able to click the green
``Apply'' button. Once you have done this, the visualization of the
simulation result appears on the screen and you can click the
``play'' button in the toolbar to view display its evolution over
time. Also note that you can choose the output quantity to be
displayed in the toolbar. For the lens problem, the most insight can
be gained by looking at one of the saturations.
\item Play a bit around to make your self familiar with the
visualization tool of your choice as you will be using it a lot.
\end{enumerate}
%%% Local Variables:
%%% mode: latex
%%% TeX-master: "ewoms-handbook"
%%% End:

12
doc/handbook/structure.tex
View File

@@ -26,8 +26,7 @@ See Section \ref{sec:test} for details.
\end{itemize}
\subsection{The directory \texttt{dumux}}\label{sec:dumux}
\subsection{The \texttt{dumux} directory}\label{sec:dumux}
The directory \texttt{dumux} contains the \Dumux source files. It consists of the following subdirectories (see Figure \ref{fig:dumux-structure}):
@@ -118,13 +117,18 @@ Doxygen documentation should be considered.
\begin{landscape}
\begin{figure}[hbt]
\centering
\includegraphics[width=\linewidth, keepaspectratio]{EPS/dumux_strucutre_flowchart_horizontal_explained.eps}
\includegraphics[width=\linewidth, keepaspectratio]{EPS/ewoms_structure.eps}
\caption{
\label{fig:dumux-structure}
Structure of the directory \texttt{dumux} containing the \Dumux source files.
Structure of the \eWoms source tree.
}
\end{figure}
\end{landscape}
\input{guidelines}
\input{newFolder}
%%% Local Variables:
%%% mode: latex
%%% TeX-master: "ewoms-handbook"
%%% End:

10
doc/handbook/tutorial-coupled.tex
View File

@@ -57,7 +57,7 @@ model. This file has to be compiled and executed in order to solve the problem d
above.
\begin{lst}[File tutorial/tutorial\_coupled.cc]\label{tutorial-coupled:mainfile} \mbox{}
\lstinputlisting[style=DumuxCode, numbersep=5pt, firstline=24, firstnumber=24]{../../tutorial/tutorial_coupled.cc}
\lstinputlisting[style=eWomsCode, numbersep=5pt, firstline=24, firstnumber=24]{../../tutorial/tutorial_coupled.cc}
\end{lst}
From line \ref{tutorial-coupled:include-begin} to line
@@ -87,7 +87,7 @@ precedence. Listing~\ref{tutorial-coupled:parameter-file} shows the
default parameter file for the tutorial problem.
%\begin{lst}[File tutorial/tutorial\_coupled.input]\label{tutorial-coupled:parameter-file} \mbox{}
%\lstinputlisting[style=DumuxCode]{../../tutorial/tutorial_coupled.input}
%\lstinputlisting[style=eWomsCode]{../../tutorial/tutorial_coupled.input}
%\end{lst}
To provide an error message, the usage message which is displayed to
@@ -106,7 +106,7 @@ so-called \textit{problem file} as shown in
listing~\ref{tutorial-coupled:problemfile}.
\begin{lst}[File tutorial/tutorialproblem\_coupled.hh]\label{tutorial-coupled:problemfile} \mbox{}
\lstinputlisting[style=DumuxCode, numbersep=5pt, firstline=24, firstnumber=24]{../../tutorial/tutorialproblem_coupled.hh}
\lstinputlisting[style=eWomsCode, numbersep=5pt, firstline=24, firstnumber=24]{../../tutorial/tutorialproblem_coupled.hh}
\end{lst}
First, a new type tag is created for the problem in line
@@ -260,7 +260,7 @@ should be derived from the base class
\verb+tutorialspatialparams_coupled.hh+:
%\begin{lst}[File tutorial/tutorialspatialparameters\_coupled.hh]\label{tutorial-coupled:spatialparametersfile} \mbox{}
%\lstinputlisting[style=DumuxCode, numbersep=5pt, firstline=25, firstnumber=25]{../../tutorial/tutorialspatialparams_coupled.hh}
%\lstinputlisting[style=eWomsCode, numbersep=5pt, firstline=25, firstnumber=25]{../../tutorial/tutorialspatialparams_coupled.hh}
%\end{lst}
First, the spatial parameters type tag is created on line
@@ -567,5 +567,5 @@ and benzene. Benzene has a density of $889.51 \, \text{kg} /
\clearpage \newpage
%%% Local Variables:
%%% mode: latex
%%% TeX-master: "dumux-handbook"
%%% TeX-master: "ewoms-handbook"
%%% End:

10
doc/handbook/tutorial-decoupled.tex
View File

@@ -42,7 +42,7 @@ effects are neglected.
Listing \ref{tutorial-decoupled:mainfile} shows how the main file, which has to be executed, has to be set up, if the problem described above is to be solved using a decoupled model. This main file can be found in the directory \texttt{/tutorial} of the stable part of \Dumux.
\begin{lst}[File tutorial/tutorial\_decoupled.cc]\label{tutorial-decoupled:mainfile} \mbox{}
\lstinputlisting[style=DumuxCode, numbersep=5pt, firstline=24, firstnumber=24]{../../tutorial/tutorial_decoupled.cc}
\lstinputlisting[style=eWomsCode, numbersep=5pt, firstline=24, firstnumber=24]{../../tutorial/tutorial_decoupled.cc}
\end{lst}
First, from line \ref{tutorial-decoupled:include-begin} to line
@@ -70,7 +70,7 @@ precedence. Listing~\ref{tutorial-decoupled:parameter-file} shows the
default parameter file for the tutorial problem.
%\begin{lst}[File tutorial/tutorial\_decoupled.input]\label{tutorial-decoupled:parameter-file} \mbox{}
%\lstinputlisting[style=DumuxCode]{../../tutorial/tutorial_decoupled.input}
%\lstinputlisting[style=eWomsCode]{../../tutorial/tutorial_decoupled.input}
%\end{lst}
To provide an error message, the usage message which is displayed to
@@ -89,7 +89,7 @@ so-called \textit{problem file} as shown in listing
\texttt{tutorialproblem\_decoupled.hh}.
\begin{lst}[File tutorial/tutorialproblem\_decoupled.hh]\label{tutorial-decoupled:problemfile} \mbox{}
\lstinputlisting[style=DumuxCode, numbersep=5pt, firstline=24, firstnumber=24]{../../tutorial/tutorialproblem_decoupled.hh}
\lstinputlisting[style=eWomsCode, numbersep=5pt, firstline=24, firstnumber=24]{../../tutorial/tutorialproblem_decoupled.hh}
\end{lst}
First, both \Dune grid handlers and the decoupled model of \Dumux
@@ -165,7 +165,7 @@ Listing \ref{tutorial-decoupled:spatialparametersfile} shows the file
\verb+tutorialspatialparams_decoupled.hh+:
\begin{lst}[File tutorial/tutorialspatialparams\_decoupled.hh]\label{tutorial-decoupled:spatialparametersfile} \mbox{}
\lstinputlisting[style=DumuxCode, numbersep=5pt, firstline=24, firstnumber=24]{../../tutorial/tutorialspatialparams_decoupled.hh}
\lstinputlisting[style=eWomsCode, numbersep=5pt, firstline=24, firstnumber=24]{../../tutorial/tutorialspatialparams_decoupled.hh}
\end{lst}
As this file only slightly differs from the coupled version, consult
chapter \ref{tutorial-coupled:description-spatialParameters} for explanations.
@@ -316,5 +316,5 @@ If both the coupled and the decoupled tutorial are completed, one should have no
%%% Local Variables:
%%% mode: latex
%%% TeX-master: "dumux-handbook"
%%% TeX-master: "ewoms-handbook"
%%% End:

2
doc/handbook/tutorial.tex
View File

@@ -11,5 +11,5 @@ In section \ref{box} a short introduction to the box method is given. The box me
%%% Local Variables:
%%% mode: latex
%%% TeX-master: "dumux-handbook"
%%% TeX-master: "ewoms-handbook"
%%% End: