diff --git a/doc/handbook/CMakeLists.txt b/doc/handbook/CMakeLists.txt
index bf9b31f0917785a70172d46e5c31edf1f5bafcfd..4cb77b9e62d63ab2f8c836b205744b66de68c91c 100644
--- a/doc/handbook/CMakeLists.txt
+++ b/doc/handbook/CMakeLists.txt
@@ -1,5 +1,4 @@
set(TEX_INPUTS
- designpatterns.tex
DumuxFlow.tex
fluidframework.tex
getting-started.tex
@@ -10,16 +9,16 @@ set(TEX_INPUTS
newFolder.tex
dumux-handbook.tex
NewtonInANutshell.tex
- parameterTree.tex
+ parameterfiles.tex
propertysystem.tex
quick-install.tex
quickstart-guide.tex
spatialdiscretization.tex
+ restartsimulations.tex
structure.tex
TipsNTricks.tex
tutorial-coupled.tex
tutorial-decoupled.tex
- tutorial-newmodel.tex
tutorial.tex
ModelDescriptions/1p2cimplicitmodel.tex
ModelDescriptions/1pdecoupledmodel.tex
diff --git a/doc/handbook/DumuxFlow.tex b/doc/handbook/DumuxFlow.tex
index 541f6622b88663f54d9f9e79d69819d8b66987e4..9222640b95160c4b65961f9f2726a1b1e561bc66 100644
--- a/doc/handbook/DumuxFlow.tex
+++ b/doc/handbook/DumuxFlow.tex
@@ -15,7 +15,7 @@ Section \ref{implementation} is structured by \fbox{boxes} and $\overrightarrow{
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}
+\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. Each item stands for a characteristic step within the modeling framework.
@@ -126,7 +126,7 @@ finalize
\textcircled{\ref{elem}} \textsc{Newton} step\\
\textcircled{\ref{calc}} Element-wise assembly
-\section{Structure -- by implementation}
+\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
diff --git a/doc/handbook/TipsNTricks.tex b/doc/handbook/TipsNTricks.tex
index b472b0003f9f43ede19d9e0e7f107a3dea8e288c..3776fe5f60741ecc3cc2dc71ac1aa1070b38593c 100644
--- a/doc/handbook/TipsNTricks.tex
+++ b/doc/handbook/TipsNTricks.tex
@@ -1,30 +1,97 @@
\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.
+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 other developers and write to
-\paragraph{Using the \Dumux-Eclipse profile}
+\section{\Dumux - General Remarks}
-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} $\rightarrow$ Formatter
- \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{Flyspray}
+Flyspray or bug-tracking system is a software application mainly designed to
+keep track of reported software development requests. This includes reported
+bugs and development requests for new or improved features. The main benefit
+of a bug-tracking system is to provide a clear centralized overview of all
+recorded requests and their state. \Dumux users and developers can submit
+development requests at \url{http://www.dumux.org/flyspray/}.
+
+\paragraph{Dashboard}
+The testing-dashboard is a tool to constantly check the \Dumux problems for compiling
+or running correctly. It is a useful tool to check the impacts of your commits
+and for quality management. The dashboard is available at
+\url{http://www.dumux.org/dashboard.php}.
+
+\paragraph{The \Dumux-Mailing List:}
+If you have questions concerning \Dumux, hints for the \Dumux-developers
+or specific problems, which you really struggle to solve on your own,
+you can contact the mailing list \url{dumux@iws.uni-stuttgart.de}.
+You can also subscribed to the mailing list via
+\url{https://listserv.uni-stuttgart.de/mailman/listinfo/dumux}, then you
+will be informed about upcoming releases or events.
+
+\paragraph{The Commit-Mailing List:}
+If you further want to be informed about commits to the dumux can subscribe
+to the commit mailing list:
+\url{https://listserv.uni-stuttgart.de/mailman/listinfo/dumux-commits}.
+
+\section{Developing \Dumux}
+\paragraph{Checking Your Commits:}
+\Dumux is developed with the help of Subversion (\texttt{svn}).
+This means that at some point you will commit your new and/or advanced features
+to the repository. In the following some additional guidelines are shown which are
+are good practice. Especially if you plan on committing to the stable part of
+\Dumux you must follow these steps.
+\begin{itemize}
+ \item add files and folders to your repository
+ \item run \texttt{make doc} in your build-directory
+ \item run \texttt{make headercheck} in your build-directory
+ \item run \texttt{ctest} in your build-directory
+ \item double-check whether the test are working. \textbf{If not} please
+ investigate whether an update of the reference solution or a review
+ of your changes is necessary
+ \item double-check whether you include all necessary files to your commit
+ \item commit
+ \item check-out dumux in new folder and test if everything is still working
+ (this is necessary to keep bump in the workflow small).
+ \item check the testing-dashboard (see above), whether everything is still working
+\end{itemize}
+
+\paragraph{Naming conventions}
+General guidelines for naming conventions are specified in Section \ref{guidelines}.
+However, in order to avoid ambiguity a list of proposed names for variables, types,
+functions etc is provided where users and mainly \Dumux developers can refer for
+standards (check \texttt{dumux-devel/\allowbreak doc/\allowbreak naminglist/\allowbreak naming-conventions.odt}).
-\paragraph{Checking whether commit worked}
+\paragraph{Errors 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}
-\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.
+\noindent 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.\\
+Further check, if the \texttt{Problem} property was defined and spelled correctly.
-\paragraph{Using \Dune debug streams}
+\paragraph{Patching Files or Modules}
+See \ref{sc:patchingDUNE} if you need to apply patches to \Dumux or \Dune.
+If you want to send changes to an other developer of \Dumux providing patches
+can be quite smart. To create a patch simply type:
+\begin{lstlisting}[style=Bash]
+$ svn diff > PATCHFILE
+\end{lstlisting}
+\noindent which creates a text file containing all your changes to the files
+in the current folder or its subdirectories.
+Other developers can now simply apply this patch by
+\begin{lstlisting}[style=Bash]
+$ path -p0 < PATCHFILE
+\end{lstlisting}
+\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.
@@ -42,10 +109,11 @@ This approach really helps keeping the bumps in the work-flow small.
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.
+in the source your application. If the value is set to e.\,g. 4 only the output generated after
+\lstinline{Dune::dwarn} and \lstinline{Dune::dgrave} will be printed.
-\paragraph{File name and line number by predefined macro}
+\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";}\\
@@ -53,8 +121,7 @@ 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}
-
+\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
@@ -77,24 +144,62 @@ be debugged because the debugger gets confused. But the cool thing is, that you
Debugging with the optimization options active will lead to erratic behavior while debugging.
-\paragraph{Faster build with dunecontrol}
+\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}
+\section{External Tools}
+\subsection{svn}
-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.
+\paragraph{Basic Commands}
+The basic svn commands are:
+\begin{itemize}
+ \item \texttt{svn checkout} checkout an repository
+ \item \texttt{svn update} updates file/folder
+ \item \texttt{svn status} to check which files/folders have been changed.
+ \texttt{M}odified, \texttt{D}eleted, \texttt{A}dded, \texttt{?} not in repository
+ \item \texttt{svn diff} to see the changes of a file/folder
+ \item \texttt{svn commit} upload changes to the repository (only with meaningful
+ commit messages)
+\end{itemize}
+The above shows you the necessary steps if you use the command line. There are also other tools providing a graphical
+user interface for using svn like kdesvn or eclipse.
-\paragraph{Flyspray}
-Flyspray or bug-tracking system is a software application mainly designed to keep track of reported software development requests. This includes reported bugs and development requests for new or improved features. The main benefit of a bug-tracking system is to provide a clear centralized overview of all recorded requests and their state. \Dumux users and developers can submit development requests at \texttt{http://www.dumux.org/flyspray/}.
+\paragraph{Properties/Attributes}
+How to set the SVN attributes:
+\begin{itemize}
+ \item{\em eclipse}: right click on the file/folder $\rightarrow$ ``team''
+ $\rightarrow$ ``add to svn:ignore\dots''
+ \item{\em kdesvn}: right click on the file/folder $\rightarrow$ ``ignore/unignore
+ current item''
+ \item{\em SVN on shell}: \verb+svn propedit svn:ignore .+
+\end{itemize}
-\paragraph{Naming conventions}
-General guidelines for naming conventions are specified in Section \ref{guidelines}. However, in order to avoid ambiguity a list of proposed names for variables, types, functions etc is provided where users and mainly \Dumux developers can refer for standards (check \texttt{dumux-devel/doc/naminglist/\\naming-conventions.odt}).
+\subsection{eclipse}
+\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} $\rightarrow$ Formatter
+ \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}
+
+% \subsection{kate}
+
+\subsection{ParaView}
+\paragraph{Reload Button:}
+Yes, you read it right. There is script to reload \texttt{pvd} files or
+series of \texttt{vtu} files since ParaView 4.2. The scripts are available
+under the links below. Just save the specific code portion in a file and load
+it via \texttt{Macros} $\rightarrow$ \texttt{Add new macro}.\\
+\texttt{vtk}: \url{http://markmail.org/message/exxynsgishbvtngg#query:+page:1+mid:rxlwxs7uqrfgibyv+state:results}\\
+\texttt{pvd}: \url{http://markmail.org/message/exxynsgishbvtngg#query:+page:1+mid:rxlwxs7uqrfgibyv+state:results}.
+
+\paragraph{Guide:}
+Since ParaView 4.3.1 The ParaView-Guide is partly
+available for free download, see \url{http://www.paraview.org/documentation/}.
+It corresponds to the ParaView-book, only without three application chaptes.
+Attention its size is 180 MiB.
diff --git a/doc/handbook/designpatterns.tex b/doc/handbook/designpatterns.tex
deleted file mode 100644
index 7b1e514ec02b1a8db11f5d815eb911551a635141..0000000000000000000000000000000000000000
--- a/doc/handbook/designpatterns.tex
+++ /dev/null
@@ -1,473 +0,0 @@
-\chapter{Design Patterns}
-\label{chap:DesignPatterns}
-
-This chapter tries to give a high-level understanding of some of the
-fundamental techniques which are used by \Dune and \Dumux and the
-motivation behind these design decisions. It is assumed that the
-reader already has basic experience in object oriented programming
-with \Cplusplus.
-
-First, a quick motivation of \Cplusplus template programming is given. Then
-follows an introduction to polymorphism and its opportunities as
-opened by the template mechanism. After that, some drawbacks
-associated with template programming are discussed, in particular the
-blow-up of identifier names, the proliferation of template arguments
-and some approaches on how to deal with these problems.
-
-\section{\Cplusplus Template Programming}
-
-One of the main features of modern versions of the \Cplusplus programming
-language is robust support for templates. Templates are a mechanism
-for code generation built directly into the compiler. For the
-motivation behind templates, consider a linked list of \texttt{double}
-values which could be implemented like this:
-\begin{lstlisting}[basicstyle=\ttfamily\scriptsize,numbers=left,numberstyle=\tiny, numbersep=5pt]
-struct DoubleList {
- DoubleList(const double &val, DoubleList *prevNode = 0)
- { value = val; if (prevNode) prevNode->next = this; };
- double value;
- DoubleList *next;
-};
-int main() {
- DoubleList *head, *tail;
- head = tail = new DoubleList(1.23);
- tail = new DoubleList(2.34, tail);
- tail = new DoubleList(3.56, tail);
-};
-\end{lstlisting}
-But what should be done if a list of strings is also required? The
-only ``clean'' way to achive this without templates would be to copy
-\texttt{DoubleList}, then rename it and change the type of the
-\texttt{value} attribute. It is obvious that this is a very
-cumbersome, error-prone and unproductive process. For this reason,
-recent standards of the \Cplusplus programming language specify the template
-mechanism, which is a way of letting the compiler do the tedious work. Using
-templates, a generic linked list can be implemented like this:
-\begin{lstlisting}[basicstyle=\ttfamily\scriptsize,numbers=left,numberstyle=\tiny, numbersep=5pt]
-template <class ValueType>
-struct List {
- List(const ValueType &val, List *prevNode = 0)
- { value = val; if (prevNode) prevNode->next = this; };
- ValueType value;
- List *next;
-};
-int main() {
- typedef List<double> DoubleList;
- DoubleList *head, *tail;
- head = tail = new DoubleList(1.23);
- tail = new DoubleList(2.34, tail);
- tail = new DoubleList(3.56, tail);
-
- typedef List<const char*> StringList;
- StringList *head2, *tail2;
- head2 = tail2 = new StringList("Hello");
- tail2 = new StringList(", ", tail2);
- tail2 = new StringList("World!", tail2);
-};
-\end{lstlisting}
-
-Compared to approaches which use external tools for code generation --
-which is the approach chosen for example by the
-FEniCS~\cite{FENICS-HP} project -- or heavy (ab)use of the C
-preprocessor -- as done for example by the UG framework~\cite{UG-HP}
--- templates have several advantages:
-\begin{description}
-\item[Well Programmable:] Programming errors are directly detected by
- the \Cplusplus compiler. Thus, diagnostic messages from the compiler are
- directly useful because the source code compiled is the
- same as the one written by the developer. This is not the case
- for code generators and C-preprocessor macros where the actual
- statements processed by the compiler are obfuscated.
-\item[Easily Debugable:] Programs which use the template mechanism can be
- debugged almost as easily as \Cplusplus programs which do not use
- templates. This is due to the fact that the debugger always knows
- the ``real'' source file and line number.
-\end{description}
-For these reasons \Dune and \Dumux extensively use the template
-mechanism. Both projects also try to avoid duplicating functionality
-provided by the Standard Template Library (STL,~\cite{STL-REF-HP})
-which is part of the \Cplusplus standard and was improved in the \Cplusplus11 standard.
-
-\section{Polymorphism}
-
-In object oriented programming, some methods often make sense for all
-classes in a hierarchy, but what actually needs to be \textit{done}
-can differ for each concrete class. This observation motivates
-\textit{polymorphism}. Fundamentally, polymorphism means all
-techniques in which a method call results in the processor executing code
-which is specific to the type of object for which the method is
-called\footnote{This is the \textit{poly} of polymorphism: There are
- multiple ways to achieve the same goal.}.
-
-In \Cplusplus, there are two common ways to achieve polymorphism: The
-traditional dynamic polymorphism which does not require template
-programming, and static polymorphism which is made possible by the
-template mechanism.
-
-\subsection*{Dynamic Polymorphism}
-
-To utilize \textit{dynamic polymorphism} in \Cplusplus, the polymorphic
-methods are marked with the \texttt{virtual} keyword in the base
-class. Internally, the compiler realizes dynamic polymorphism by
-storing a pointer to a so-called \texttt{vtable} within each object of
-polymorphic classes. The \texttt{vtable} itself stores the entry point
-of each method which is declared \texttt{virtual}. If such a method is
-called on an object, the compiler generates code which retrieves the
-method's memory address from the object's \texttt{vtable} and then
-continues execution at this address. This explains why this mechanism
-is called \textbf{dynamic} polymorphism: the code which is actually
-executed is dynamically determined at run time.
-
-\begin{example}
- \label{example:DynPoly}
- A class called \texttt{Car} could feature the methods
- \texttt{gasUsage}, which by default corresponds to the current
- $CO_2$ emission goal of the European Union -- line \ref{designpatterns:virtual-usage} -- but can be changed by
- classes representing actual cars. Also, a method called
- \texttt{fuelTankSize} makes sense for all cars, but since there is
- no useful default, its \texttt{vtable} entry is set to $0$ -- line \ref{designpatterns:totally-virtual} -- in the
- base class. This tells the compiler that it is mandatory for this
- method to be defined in derived classes. Finally, the method
- \texttt{range} may calculate the expected remaining kilometers the
- car can drive given a fill level of the fuel tank. Since the
- \texttt{range} method can retrieve the information it needs, it does not
- need to be polymorphic.
-\begin{lstlisting}[basicstyle=\ttfamily\scriptsize,numbers=left,numberstyle=\tiny, numbersep=5pt]
-// The base class
-class Car
-{public:
- virtual double gasUsage()
- { return 4.5; };/*@\label{designpatterns:virtual-usage}@*/
- virtual double fuelTankSize() = 0;/*@\label{designpatterns:totally-virtual}@*/
-
- double range(double fuelTankFillLevel)
- { return 100*fuelTankFillLevel*fuelTankSize()/gasUsage(); }
-};
-\end{lstlisting}
-
-\noindent
-Actual car models can now be derived from the base class like this:
-\begin{lstlisting}[basicstyle=\ttfamily\scriptsize,numbers=left,numberstyle=\tiny, numbersep=5pt]
-// A Mercedes S-class car
-class S : public Car
-{public:
- virtual double gasUsage() { return 9.0; };
- virtual double fuelTankSize() { return 65.0; };
-};
-
-// A VW Lupo
-class Lupo : public Car
-{public:
- virtual double gasUsage() { return 2.99; };
- virtual double fuelTankSize() { return 30.0; };
-};
-\end{lstlisting}
-
-\noindent
-Calling the \texttt{range} method yields the correct result for any
-kind of car:
-\begin{lstlisting}[basicstyle=\ttfamily\scriptsize,numbers=left,numberstyle=\tiny, numbersep=5pt]
-void printMaxRange(Car &car)
-{ std::cout << "Maximum Range: " << car.range(1.00) << "\n"; }
-
-int main()
-{
- Lupo lupo;
- S s;
- std::cout << "VW Lupo:";
- std::cout << "Median range: " << lupo.range(0.50) << "\n";
- printMaxRange(lupo);
- std::cout << "Mercedes S-Class:";
- std::cout << "Median range: " << s.range(0.50) << "\n";
- printMaxRange(s);
-}
-\end{lstlisting}
-
-For both types of cars, \texttt{Lupo} and \texttt{S} the function
-\texttt{printMaxRange} works as expected, it yields
-$1003.3\;\mathrm{km}$ for the Lupo and $722.2\;\mathrm{km}$ for the
-S-Class.
-\end{example}
-
-\begin{exc}
-What happens if \dots
-\begin{itemize}
-\item \dots the \texttt{gasUsage} method is removed from the \texttt{Lupo} class?
-\item \dots the \texttt{virtual} qualifier is removed in front of the
- \texttt{gasUsage} method in the base class?
-\item \dots the \texttt{fuelTankSize} method is removed from the \texttt{Lupo} class?
-\item \dots the \texttt{range} method in the \texttt{S} class is
- overwritten?
-\end{itemize}
-\end{exc}
-
-\subsection*{Static Polymorphism}
-
-Dynamic polymorphism has a few disadvantages. The most relevant in the
-context of \Dumux is that the compiler can not see ``inside'' the
-called methods and thus cannot optimize properly. For example, modern
-\Cplusplus compilers 'inline' short methods, i.e. they copy the method's body
-to where it is called. First, inlining allows to save a few
-instructions by avoiding to jump into and out of the method. Second,
-and more importantly, inlining also allows further optimizations which
-depend on specific properties of the function arguments (e.g. constant
-value elimination) or the contents of the function body (e.g. loop
-unrolling). Unfortunately, inlining and other cross-method
-optimizations are made next to impossible by dynamic
-polymorphism. This is because these optimizations are accomplished by the
-compiler (i.e. at compile time) whilst the code which actually gets
-executed is only determined at run time for \texttt{virtual}
-methods. To overcome this issue, template programming can be used to
-achive polymorphism at compile time. This works by supplying the type
-of the derived class as an additional template parameter to the base
-class. Whenever the base class needs to call back the derived class, \texttt{this} pointer of the base class is reinterpreted as
-being a pointer to an object of the derived class and the method is
-then called on the reinterpreted pointer. This scheme gives the \Cplusplus
-compiler complete transparency of the code executed and thus opens
-much better optimization oportunities. Since this mechanism completely
-happens at compile time, it is called ``static polymorphism'' because
-the called method cannot be dynamically changed at runtime.
-\begin{example}
- Using static polymorphism, the base class of example \ref{example:DynPoly}
- can be implemented like this:
-\begin{lstlisting}[name=staticcars,basicstyle=\ttfamily\scriptsize,numbers=left,numberstyle=\tiny, numbersep=5pt]
-// The base class. The 'Imp' template parameter is the
-// type of implementation, i.e. the derived class
-template <class Imp>
-class Car
-{public:
- double gasUsage()
- { return 4.5; };
- double fuelTankSize()
- { throw "The derived class needs to implement the fuelTankSize() method"; };
-
- double range(double fuelTankFillLevel)
- { return 100*fuelTankFillLevel*asImp_().fuelTankSize()/asImp_().gasUsage(); }
-
-protected:
- // reinterpret 'this' as a pointer to an object of type 'Imp'
- Imp &asImp_() { return *static_cast<Imp*>(this); }
-};
-\end{lstlisting}
-(Notice the \texttt{asImp\_()} calls in the \texttt{range} method.) The
-derived classes may now be defined like this:
-\begin{lstlisting}[name=staticcars,basicstyle=\ttfamily\scriptsize,numbers=left,numberstyle=\tiny, numbersep=5pt]
-// A Mercedes S-class car
-class S : public Car<S>
-{public:
- double gasUsage() { return 9.0; };
- double fuelTankSize() { return 65.0; };
-};
-
-// A VW Lupo
-class Lupo : public Car<Lupo>
-{public:
- double gasUsage() { return 2.99; };
- double fuelTankSize() { return 30.0; };
-};
-\end{lstlisting}
-\end{example}
-
-\noindent
-Analogous to example \ref{example:DynPoly}, the two kinds of cars can
-be used generically within (template) functions:
-\begin{lstlisting}[name=staticcars,basicstyle=\ttfamily\scriptsize,numbers=left,numberstyle=\tiny, numbersep=5pt]
-template <class CarType>
-void printMaxRange(CarType &car)
-{ std::cout << "Maximum Range: " << car.range(1.00) << "\n"; }
-
-int main()
-{
- Lupo lupo;
- S s;
- std::cout << "VW Lupo:";
- std::cout << "Median range: " << lupo.range(0.50) << "\n";
- printMaxRange(lupo);
- std::cout << "Mercedes S-Class:";
- std::cout << "Median range: " << s.range(0.50) << "\n";
- printMaxRange(s);
- return 0;
-}
-\end{lstlisting}
-
-%\textbf{TODO: Exercise}
-
-\section{Common Template Programming Related Problems}
-
-Although \Cplusplus template programming opens a few intriguing
-possibilities, it also has a few disadvantages. In this section, a few
-of them are outlined and some hints on how they can be dealt with are
-provided.
-
-\subsection*{Identifier-Name Blow-Up}
-
-One particular problem with the advanced use of \Cplusplus templates is that the
-canonical identifier names for types and methods quickly become really
-long and unintelligible. For example, a typical error message
-generated using GCC 4.5 and \Dune-PDELab looks like this
-\begin{lstlisting}[basicstyle=\ttfamily\scriptsize, numbersep=5pt]
-test_pdelab.cc:171:9: error: no matching function for call to ‘Dune::\
-PDELab::GridOperatorSpace<Dune::PDELab::PowerGridFunctionSpace<Dune::\
-PDELab::GridFunctionSpace<Dune::GridView<Dune::DefaultLeafGridViewTraits\
-<const Dune::UGGrid<3>, (Dune::PartitionIteratorType)4u> >, Dune::\
-PDELab::Q1LocalFiniteElementMap<double, double, 3>, Dune::PDELab::\
-NoConstraints, Dumux::PDELab::BoxISTLVectorBackend<Dumux::Properties::\
-TTag::LensProblem> >, 2, Dune::PDELab::GridFunctionSpaceBlockwiseMapper>\
-, Dune::PDELab::PowerGridFunctionSpace<Dune::PDELab::GridFunctionSpace<\
-Dune::GridView<Dune::DefaultLeafGridViewTraits<const Dune::UGGrid<3>, \
-(Dune::PartitionIteratorType)4u> >, Dune::PDELab::Q1LocalFiniteElementMap\
-<double, double, 3>, Dune::PDELab::NoConstraints, Dumux::PDELab::\
-BoxISTLVectorBackend<Dumux::Properties::TTag::LensProblem> >, 2, Dune::\
-PDELab::GridFunctionSpaceBlockwiseMapper>, Dumux::PDELab::BoxLocalOperator\
-<Dumux::Properties::TTag::LensProblem>, Dune::PDELab::\
-ConstraintsTransformation<long unsigned int, double>, Dune::PDELab::\
-ConstraintsTransformation<long unsigned int, double>, Dune::PDELab::\
-ISTLBCRSMatrixBackend<2, 2>, true>::GridOperatorSpace()’
-\end{lstlisting}
-This seriously complicates diagnostics. Although there is no full
-solution to this problem yet, an effective way of dealing with such
-kinds of error messages is to ignore the type information and to just
-look at the location given at the beginning of the line. If nested
-templates are used, the lines printed by the compiler above the actual
-error message specify how exactly the code was instantiated (the lines
-starting with ``\texttt{instantiated from}''). In this case it is
-advisable to look at the innermost source code location of ``recently
-added'' source code.
-
-\subsection*{Proliferation of Template Parameters}
-
-Templates often need a large number of template parameters. For
-example, the error message above was produced by the following
-snipplet:
-\begin{lstlisting}[basicstyle=\ttfamily\scriptsize,numbers=left,numberstyle=\tiny, numbersep=5pt]
-int main()
-{
- enum {numEq = 2};
- enum {dim = 3};
- typedef Dune::UGGrid<dim> Grid;
- typedef Grid::LeafGridView GridView;
- typedef Dune::PDELab::Q1LocalFiniteElementMap<double,double,dim> FEM;
- typedef TTAG(LensProblem) TypeTag;
- typedef Dune::PDELab::NoConstraints Constraints;
- typedef Dune::PDELab::GridFunctionSpace<
- GridView, FEM, Constraints, Dumux::PDELab::BoxISTLVectorBackend<TypeTag>
- >
- doubleGridFunctionSpace;
- typedef Dune::PDELab::PowerGridFunctionSpace<
- doubleGridFunctionSpace,
- numEq,
- Dune::PDELab::GridFunctionSpaceBlockwiseMapper
- >
- GridFunctionSpace;
- typedef typename GridFunctionSpace::ConstraintsContainer<double>::Type
- ConstraintsTrafo;
- typedef Dumux::PDELab::BoxLocalOperator<TypeTag> LocalOperator;
- typedef Dune::PDELab::GridOperatorSpace<
- GridFunctionSpace,
- GridFunctionSpace,
- LocalOperator,
- ConstraintsTrafo,
- ConstraintsTrafo,
- Dune::PDELab::ISTLBCRSMatrixBackend<numEq, numEq>,
- true
- >
- GOS;
- GOS gos; // instantiate grid operator space
-}
-\end{lstlisting}
-
-Although the code above is not really intuitivly readable, this does
-not pose a severe problem as long as the type (in this case the grid
-operator space) needs to be specified exactly once in the whole
-program. If, on the other hand, it needs to be consistend over
-multiple locations in the source code, measures have to be taken in
-order to keep the code maintainable.
-
-\section{Traits Classes}
-
-A classic approach to reducing the number of template parameters is to
-gather all the arguments in a special class, a so-called traits
-class. Instead of writing
-\begin{lstlisting}[basicstyle=\ttfamily\scriptsize,numbers=left,numberstyle=\tiny, numbersep=5pt]
-template <class A, class B, class C, class D>
-class MyClass {};
-\end{lstlisting}
-one can use
-\begin{lstlisting}[basicstyle=\ttfamily\scriptsize,numbers=left,numberstyle=\tiny, numbersep=5pt]
-template <class Traits>
-class MyClass {};
-\end{lstlisting}
-where the \texttt{Traits} class contains public type definitions for
-\texttt{A}, \texttt{B}, \texttt{C} and \texttt{D}, e.g.
-\begin{lstlisting}[basicstyle=\ttfamily\scriptsize,numbers=left,numberstyle=\tiny, numbersep=5pt]
-struct MyTraits
-{
- typedef float A;
- typedef double B;
- typedef short C;
- typedef int D;
-};
-\end{lstlisting}
-
-\noindent
-As there is no free lunch, the traits approach comes with a few
-disadvantages of its own:
-\begin{enumerate}
-\item Hierarchies of traits classes are problematic. This is due to
- the fact that each level of the hierarchy must be self-contained. As
- a result, it is impossible to define parameters in the base class
- which depend on parameters which only later get specified by a
- derived traits class.
-\item Traits quickly lead to circular dependencies. In practice
- this means that traits classes can not extract any information from
- templates which get the traits class as an argument -- even if the
- extracted information does not require the traits class.
-\end{enumerate}
-
-\noindent
-To see the point of the first issue, consider the following:
-\begin{lstlisting}[basicstyle=\ttfamily\scriptsize,numbers=left,numberstyle=\tiny, numbersep=5pt]
-struct MyBaseTraits {
- typedef int Scalar;
- typedef std::vector<Scalar> Vector;
- typedef std::list<Scalar> List;
- typedef std::array<Scalar> Array;
- typedef std::set<Scalar> Set;
-};
-
-struct MyDoubleTraits : public MyBaseTraits {
- typedef double Scalar;
-};
-
-int main() {
- MyDoubleTraits::Vector v{1.41421, 1.73205, 2};
- for (int i = 0; i < v.size(); ++i)
- std::cout << v[i]*v[i] << std::endl;
-}
-\end{lstlisting}
-Contrary to what is intended, \texttt{v} is a vector of integers. This
-problem can not be solved using static polymorphism, either, since it
-would lead to a cyclic dependency between \texttt{MyBaseTraits} and
-\texttt{MyDoubleTraits}.
-
-The second issue is illuminated by the following example, where one
-would expect the \texttt{MyTraits:: VectorType} to be \texttt{std::vector<double>}:
-\begin{lstlisting}[basicstyle=\ttfamily\scriptsize,numbers=left,numberstyle=\tiny, numbersep=5pt]
-template <class Traits>
-class MyClass {
-public: typedef double ScalarType;
-private: typedef typename Traits::VectorType VectorType;
-};
-
-struct MyTraits {
- typedef MyClass<MyTraits>::ScalarType ScalarType;
- typedef std::vector<ScalarType> VectorType
-};
-\end{lstlisting}
-Although this example seems to be quite pathetic, in practice it is
-often useful to specify parameters in such a way.
-
-% TODO: section about separation of functions, parameters and
-% independent variables. (e.g. the material laws: BrooksCorey
-% (function), BrooksCoreyParams (function parameters), wetting
-% saturation/fluid state (independent variables)
diff --git a/doc/handbook/dumux-handbook.bib b/doc/handbook/dumux-handbook.bib
index 99252007b8da4af4faf34d5188862c49a524ffda..024c7546281a47d77549e7eacab9706798f7f2b4 100644
--- a/doc/handbook/dumux-handbook.bib
+++ b/doc/handbook/dumux-handbook.bib
@@ -924,7 +924,7 @@
}
@MISC{DOXYGEN-HP,
- title = {Doxgen Homepage: \url{http://www.stack.nl/~dimitri/doxygen/}},
+ title = {Doxygen Homepage: \url{http://www.stack.nl/~dimitri/doxygen/}},
key = {DOXYGEN}
}
@@ -990,7 +990,7 @@
}
@MISC{GNU-BS,
- title = {wikipedia about GNU build system: \url{http://en.wikipedia.org/wiki/GNU_build_system}},
+ title = {Wikipedia about GNU build system: \url{http://en.wikipedia.org/wiki/GNU_build_system}},
key = {WIKIPED-GNU-BS}
}
@@ -1005,7 +1005,7 @@
}
@MISC{WIKIPED-ALIASING,
- title = {wikipedia about aliasing data location in memory: \url{http://en.wikipedia.org/wiki/Aliasing\_(computing)}},
+ title = {Wikipedia about aliasing data location in memory: \url{http://en.wikipedia.org/wiki/Aliasing\_(computing)}},
key = {WikipediaAliasing}
}
diff --git a/doc/handbook/dumux-handbook.tex b/doc/handbook/dumux-handbook.tex
index 72fbab387656ec0183b4fcc06eb1b522757f4ea0..e04db954cb0102901168f2b8bccb9afcb73ff953 100644
--- a/doc/handbook/dumux-handbook.tex
+++ b/doc/handbook/dumux-handbook.tex
@@ -7,41 +7,8 @@
\usepackage{amssymb}
\usepackage{booktabs}
\usepackage{theorem}
-\usepackage{xcolor}
+\usepackage[usenames,dvipsnames]{xcolor}
\usepackage{listings}
-\lstset{language=C++, basicstyle=\ttfamily,
- keywordstyle=\color{black}\bfseries, tabsize=4, stringstyle=\ttfamily,
- commentstyle=\it, extendedchars=true, escapeinside={/*@}{@*/}}
-
-% for listings of bash code in install.tex
-\lstdefinestyle{Bash}
- {language=Bash,
- backgroundcolor=\color{lightgray},
- basicstyle=\ttfamily\small,
- numbers=none,
- captionpos=b,
- tabsize=4,
- breaklines=true,
- frame=single,
- rulecolor=\color{lightgray},
- framerule=1pt,
- framesep=1pt,
- rulesep=0pt,
- aboveskip=\bigskipamount,
- belowskip=\bigskipamount
-}
-% for listings of DuMuX code
-\lstdefinestyle{DumuxCode}
- {language=C++,
- basicstyle=\ttfamily\scriptsize,
- numbers=left,
- numberstyle=\tiny,
- numbersep=5pt,
- breaklines=true
-}
-\lstset{showstringspaces=false,
- breaklines=true}
-
\usepackage{makeidx}
\usepackage{graphicx}
\usepackage{xspace}
@@ -53,12 +20,10 @@
\usepackage{units}
\usepackage{url}
\usepackage{breakurl}
-
\usepackage{tikz}
\usepackage{pdflscape}
\usepackage{rotating}
\usetikzlibrary{arrows,backgrounds,decorations.pathmorphing,patterns,positioning,fit,shapes}
-
\usepackage[normalem]{ulem}
\usepackage{tabularx}
\newcommand{\snakeline}{%
@@ -68,19 +33,59 @@
\usepackage{layout}
\usepackage{hyperref}
+\hypersetup{bookmarksdepth=2}
\DeclareGraphicsExtensions{.pdf, .jpg}
% Dune logo
\newcommand{\Dune}{{DUNE}\xspace}
-% DuMuX logo
-\newcommand{\Dumux}{\texorpdfstring{Du\-Mu$^\text{x}$\xspace}{DuMuX}}
+% DuMuX macro
+\newcommand{\Dumux}{\texorpdfstring{Du\-Mu$^\text{x}$\xspace}{DuMuX\xspace}}
+\newcommand{\DumuxVersion}{2.7}
% DuMuX logo colors
\definecolor{dumuxYellow}{HTML}{E19417}
\definecolor{dumuxBlue}{HTML}{0C73CF}
% beautify C++
\DeclareRobustCommand\Cplusplus{\texorpdfstring{C\nolinebreak[4]\hspace{-.05em}\raisebox{.4ex}{\tiny\bf ++}\xspace}{C++}}
+% for listings of C++ code
+\lstset{language=C++, basicstyle=\ttfamily,
+ keywordstyle=\color{black}\bfseries, tabsize=4, stringstyle=\ttfamily,
+ commentstyle=\it, extendedchars=true, escapeinside={/*@}{@*/}}
+% for listings of bash code in install.tex
+\lstdefinestyle{Bash}
+ {language=Bash,
+ backgroundcolor=\color{lightgray},
+ basicstyle=\ttfamily\small,
+ numbers=none,
+ captionpos=b,
+ tabsize=4,
+ breaklines=true,
+ frame=single,
+ rulecolor=\color{lightgray},
+ framerule=1pt,
+ framesep=1pt,
+ rulesep=0pt,
+ aboveskip=\bigskipamount,
+ belowskip=\bigskipamount
+}
+% for listings of DuMuX code
+\lstdefinestyle{DumuxCode}
+ {language=C++,
+ basicstyle=\ttfamily\scriptsize,
+ numbers=left,
+ numberstyle=\tiny,
+ numbersep=5pt,
+ breaklines=true,
+ keywordstyle=\color{dumuxBlue},
+ stringstyle=\color{Red},
+ commentstyle=\color{Gray},
+ morecomment=[l][\color{OliveGreen}]{\#}
+}
+\lstset{showstringspaces=false,
+ breaklines=true}
+
+
\newcommand{\porosity}{\phi}
\newcommand{\saturation}{S}
@@ -157,13 +162,14 @@ Universit\"at Stuttgart, Paffenwaldring 61, D-70569 Stuttgart, Germany}\\
\maketitle
+\setcounter{tocdepth}{1}
+\pdfbookmark[0]{Table of Contents}{Table of Contents}
\tableofcontents
\input{intro}
\input{getting-started}
\input{tutorial}
\input{structure}
-\input{designpatterns}
\input{propertysystem}
\input{fluidframework}
\input{models}
diff --git a/doc/handbook/getting-started.tex b/doc/handbook/getting-started.tex
index cbf967565468ccc2bd199805f9b0837561610ded..93ba070734e3178031ec108785e7eb53df6759fd 100644
--- a/doc/handbook/getting-started.tex
+++ b/doc/handbook/getting-started.tex
@@ -5,4 +5,3 @@ Then a quick start guide for the first \Dumux experience is provided.
\input{quick-install}
\input{quickstart-guide}
-\input{parameterTree}
diff --git a/doc/handbook/guidelines.tex b/doc/handbook/guidelines.tex
index ccdbc03e5e2580901c5e53e0ef408cf78f698392..13e9c9b99d72298220b498fede7a8f127d3b8a24 100644
--- a/doc/handbook/guidelines.tex
+++ b/doc/handbook/guidelines.tex
@@ -1,4 +1,4 @@
-\section{Guidelines}
+\section{Coding Guidelines}
\label{guidelines}
An important characteristic of source code is that it is written only
@@ -7,56 +7,81 @@ adding features, etc.). For this reason, good programming frameworks
always aim to be as readable as possible, even if comes with higher
effort to write them in the first place. The remainder of this section
is almost a verbatim copy of the DUNE coding guidelines found at
-\cite{DUNE-HP}. These guidelines are also recommended for coding with
-\Dumux as developer and user.
+\url{http://www.dune-project.org/doc/devel/codingstyle.html}. These guidelines
+are also recommended for coding with \Dumux as developer and user.
In order to keep the code maintainable we have decided upon a set of
coding rules. Some of them may seem like splitting hairs to you, but
they do make it much easier for everybody to work on code that hasn't
been written by oneself.
+
+\paragraph{Documentation:}
+\Dumux, as any software project of similar complexity, will stand and fall
+with the quality of its documentation.
+Therefore it is of paramount importance that you document well everything you
+do! We use the Doxygen system to extract easily-readable documentation from the
+source code. Please use its syntax everywhere.\\
+We proclaim the Doc-Me Dogma. It goes like this: Whatever you do, and in whatever hurry you
+happen to be, please document everything at least with a \texttt{/** $\backslash$todo Please doc me! */}.
+That way at least the absence of documentation is documented, and it is easier
+to get rid of it systematically.
+Please document freely what each part of your code does. All comments/ documentation
+is in \textbf{English}. In particular, please comment \textbf{all}:
\begin{itemize}
-\item Naming:
-\begin{itemize}
-\item Comments: they are helpful! Please document freely what each part of your code does.
-\item all comments / documentation is in English
-\item \textbf{Naming Conventions:} Names for variables/functions\ldots \; should only consist of letters and digits. The first
-letter should be lower case. If your variable names consists of several words, then
-the first letter of each new word should be capital. \\
-If and only if a single letter that represents an abbreviation or index is followed by a single letter (abbreviation or index), CamelCase is {\bf not} used. An inner-word underscore is only permitted if it symbolizes a fraction line. Afterwards, we continue with lower case, i.e. the common rules apply to both enumerator and denominator. Examples: \\
-\texttt{pw} vs. \texttt{pressureW} $\rightarrow$ because ``pressure'' is a word.\\
-\texttt{srnw} vs. \texttt{sReg} $\rightarrow$ because ``reg'' is not an abbreviation of a single letter. ``n'' abbreviates ``non'', ``w'' is ``wetting'', so not CamelCase.\\
-\texttt{pcgw} vs \texttt{dTauDPi} $\rightarrow$ Both ``Tau'' and ``Pi'' are words, plus longer than a letter.\\
-The only exception: chemical formulas are written in their chemically correct way $\rightarrow$ \texttt{CaCO3}
-\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 at calling sites. Example:
-\begin{lstlisting}[style=DumuxCode]
- 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.
-\item Type names: For type names, the same rules as for variables apply. The only difference is that the first letter should be a capital one.
-\item Macros: The use of preprocessor macros is strongly discouraged. If you have to use them for whatever reason, please use capital letters only.
-\item The Exclusive-Access Macro: Every header file traditionally begins with the definition of a preprocessor constant that is used to make sure that each header file is only included once. If your header file is called 'myheaderfile.hh', this constant should be DUNE\_MYHEADERFILE\_HH.
-\item Files: File names should consist of lower case letters exclusively. Header files get the suffix .hh, implementation files the suffix .cc
+ \item Method Parameters (in / out)
+ \item Method parameters which are not self-explanatory should always
+ have a meaningful comment at calling sites. Example:
+ \begin{lstlisting}[style=DumuxCode]
+ localResidual.eval(/*includeBoundaries=*/true);
+ \end{lstlisting}
+ \item Template Parameters
+ \item Return Values
+ \item Exceptions thrown by a method
+ \item svn-Commits
\end{itemize}
-\item Documentation:
- \Dumux, as any software project of similar complexity, will stand and fall with the quality of its documentation.
-Therefore it is of paramount importance that you document well everything you do! We use the Doxygen system to extract easily-readable documentation from the source code. Please use its syntax everywhere. In particular, please comment \textbf{all}
+
+\paragraph{Naming:}
+In order to avoid duplicated types or variables a better understanding and usability
+of the code we have the following naming principles.
\begin{itemize}
-\item Method Parameters (in / out)
-\item Template Parameters
-\item Return Values
-\item Exceptions thrown by a method
- \end{itemize}
- Since we all know that writing documentation is not well-liked and is frequently deferred to some vague
-'next week', we herewith proclaim the Doc-Me Dogma. It goes like this: Whatever you do, and in whatever hurry you
-happen to be, please document everything at least with a {\verb /** $\backslash$todo Please doc me! */}. That way at least the absence
-of documentation is documented, and it is easier to get rid of it systematically.
-\item Exceptions:
- The use of exceptions for error handling is encouraged. Until further notice, all exceptions thrown are Dune exceptions.
-\item Debugging Code:
- Global debugging code is switched off by setting the macro NDEBUG or the compiler flag -DNDEBUG. In particular, all asserts are
-automatically removed. Use those asserts freely!
+\item \textbf{Variables/Functions\ldots}
+ \begin{itemize}
+ \item \emph{use} letters and digits
+ \item \emph{first letter} is lower case.
+ \item \emph{CamelCase}: if your variable names consists of several words, then
+ the first letter of each new word should be capital.
+ \item \emph{Abbreviations}: If and only if a single letter that represents an
+ abbreviation or index is followed by a single letter (abbreviation or index),
+ CamelCase is {\bf not} used. An inner-word underscore is only permitted if
+ it symbolizes a fraction line. Afterwards, we continue with lower case, i.e.
+ the common rules apply to both enumerator and denominator. Examples: \\
+ \texttt{pw} but \texttt{pressureW} $\rightarrow$ because ``pressure'' is a word.\\
+ \texttt{srnw} but \texttt{sReg} $\rightarrow$ because ``reg'' is not an abbreviation of a single letter. ``n'' abbreviates ``non'', ``w'' is ``wetting'', so not CamelCase.\\
+ \texttt{pcgw} but \texttt{dTauDPi} $\rightarrow$ Both ``Tau'' and ``Pi'' are words, plus longer than a letter.\\
+ \textbf{But:} \texttt{CaCO3} The only exception: chemical formulas are written in their chemically correct way $\rightarrow$
+ \item \emph{Self-Explaining}: especially abbreviations should be avoided (saturation in stead of S)
+ \end{itemize}
+\item \textbf{Private Data Variables:} Names of private data variables end with an
+ underscore and are the only variables that contain underscores.
+\item \textbf{Type names:} For type names, the same rules as for variables apply. The
+ only difference is that the \emph{first letter is capital}.
+\item \textbf{Files:} File names should consist of \emph{lower case} letters
+ exclusively. Header files get the suffix \texttt{.hh}, implementation files the
+ suffix \texttt{.cc}
+\item \textbf{The Exclusive-Access Macro:} Every header file traditionally begins
+ with the definition of a preprocessor constant that is used to make sure that
+ each header file is only included once. If your header file is called
+ 'myheaderfile.hh', this constant should be DUMUX\_MYHEADERFILE\_HH.
+\item \textbf{Macros:} The use of preprocessor macros is strongly discouraged. If you
+ have to use them for whatever reason, please use capital letters only.
\end{itemize}
+
+\paragraph{Exceptions:}
+The use of exceptions for error handling is encouraged. Until further notice,
+all exceptions thrown are Dune exceptions.
+
+\paragraph{Debugging Code:}
+Global debugging code is switched off by setting the macro NDEBUG or the compiler
+flag -DNDEBUG. In particular, all asserts are automatically removed. Use those
+asserts freely!
diff --git a/doc/handbook/install.tex b/doc/handbook/install.tex
index 43a56d9467aa7b2a3df3311eb92696f64e51361f..6e3090c5acd824045992356b4aa0fee11a30ba88 100644
--- a/doc/handbook/install.tex
+++ b/doc/handbook/install.tex
@@ -1,6 +1,5 @@
\chapter{Detailed Installation Instructions} \label{install}
-\section{Preliminary remarks}
In this section about the installation of \Dumux it is assumed that you work with a Linux or Apple OS X operating system
and that you are familiar with the use of a command line shell. Installation means that you unpack \Dune together with \Dumux in a certain directory.
Then, you compile it in that directory tree in which you do the further work, too. You also should know how to install new software packages
@@ -47,7 +46,7 @@ additional software packages may be required. Some hints on that are given in Se
Subversion (SVN) and a Git clients must be installed to download modules from Subversion and Git repositories.
-\section{Obtaining source code for \Dune and \Dumux}
+\section{Obtaining Source Code for \Dune and \Dumux}
As stated above, the \Dumux release and trunk (developer tree) are based on the most recent
\Dune release 2.3, comprising the core modules dune-common, dune-geometry, dune-grid,
dune-istl and dune-localfunctions. For working with \Dumux, these modules are required. The
@@ -63,14 +62,14 @@ However, if a user does not want to use the most recent version,
certain version tags or branches (i.\,e. special names) are means
of the software revision control system to provide access to different versions of the software.
-\paragraph{Obtaining the software by installing tar files}
+\subsubsection{Obtaining the software by installing tar files}
The slightly old-fashionedly named tape-archive-file, shortly named tar file or tarball, is a common file format for distributing collections of files contained within these archives.
The extraction from the tar files is done as follows:
Download the tarballs from the respective \Dune (version 2.3) and \Dumux websites to a certain folder in your file system.
Create the {\Dune} root directory, named \texttt{dune} in the example below.
Then extract the content of the tar files, e.\,g. with the command-line program \texttt{tar}.
This can be achieved by the following shell commands. Replace \texttt{path\_to\_tarball} with the directory name where the downloaded files are actually located.
-After extraction, the actual name of the \emph{dumux root directory} is \texttt{dumux-2.5}
+After extraction, the actual name of the \emph{dumux root directory} is \texttt{dumux-\DumuxVersion}
(or whatever version you downloaded).
\begin{lstlisting}[style=Bash]
@@ -83,13 +82,13 @@ $ tar xzvf path_to_tarball_of/dune-istl-2.3.1.tar.gz
$ tar xzvf path_to_tarball_of/dune-localfunctions-2.3.1.tar.gz
$ tar xzvf path_to_tarball_of/dune-pdelab-2.0.0.tar.gz
$ tar xzvf path_to_tarball_of/dune-typetree-2.3.1.tar.gz
-$ tar xzvf path_to_tarball_of/dumux-2.6.tar.gz
+$ tar xzvf path_to_tarball_of/dumux-2.7.tar.gz
\end{lstlisting}
Furthermore, if you wish to install the optional \Dune Grid-Howto which provides a tutorial
on the Dune grid interface, act similar.
-\paragraph{Obtaining \Dune and \Dumux from software repositories}
+\subsubsection{Obtaining \Dune and \Dumux from software repositories}
Direct access to a software revision control system for downloading code can be of advantage for the user later on.
It can be easier for him to keep up with code changes and to receive important bug fixes using
the update or pull command of the revision control system. \Dune uses Git and \Dumux uses Apache
@@ -161,32 +160,8 @@ $ # make sure you are in DUNE-Root
$ svn checkout --username=anonymous --password='' svn://svn.iws.uni-stuttgart.de/DUMUX/dumux/trunk dumux
\end{lstlisting}
-\paragraph{Hints for \Dumux-Developers}
-If you also want to actively participate in the development of \Dumux, you can allways send patches
-to the Mailing list.
-
-To get more involved, you can apply either for full developer
-access or for developer access on certain parts of \Dumux. Granted developer access means that
-you are allowed to commit own code and that you can access the \texttt{dumux-devel} module.
-This enhances \texttt{dumux} by providing maybe unstable code from the developer group.
-A developer usually checks out non-anonymously the modules \texttt{dumux} and \texttt{dumux-devel}.
-\texttt{Dumux-devel} itself makes use of the stable part \texttt{dumux}. Hence, the two parts have to be checked out together.
-This is done using the commands below. But \texttt{joeuser} needs to be replaced by
-the actual user name of the developer for accessing the software repository.
-One can omit the \texttt{--username} option in the commands above if the user name for the repository access is
-identical to the one for the system account.
-
-\begin{lstlisting}[style=Bash]
-$ svn co --username=joeuser svn://svn.iws.uni-stuttgart.de/DUMUX/dumux/trunk dumux
-$ svn co --username=joeuser svn://svn.iws.uni-stuttgart.de/DUMUX/dune-mux/trunk dumux-devel
-\end{lstlisting}
-
-Please choose either not to store the password by subversion in an insecure way or
-choose to store it by subversion in a secure way, e.\,g. together with KDE's KWallet or GNOME Keyring.
-Check the documentation of Subversion for info on how this is done.
-A leaked out password can be used by evil persons to abuse a software repository.
-
-\section{Patching \Dune or external libraries}
+\subsubsection{Patching \Dune or external libraries}
+\label{sc:patchingDUNE}
Patching of \Dune modules in order to work together with \Dumux can be necessary for several reasons.
Software like a compiler or even a standard library
changes at times. But, for example, a certain release of a software component that we depend on,
@@ -200,39 +175,67 @@ directory \texttt{dumux/patches}.
Please check the README file in that directory for recent information.
In general, a patch can be applied as follows
(the exact command or the used parameters may be slightly different).
-We include here an example of a patch against \Dune-PDELab 1.1
-for the \Dumux release 2.3 for purpose of showing how a patch gets applied.
+We include here an example of a patching dune-grid.
\begin{lstlisting}[style=Bash]
$ # make sure you are in DUNE-Root
-$ cd dune-pdelab
-$ patch -p0 < ../dumux/patches/pdelab-1.1.0.patch
+$ cd dune-grid
+$ patch -p0 < ../dumux/patches/grid-2.3.1.patch
\end{lstlisting}
It can be removed by
\begin{lstlisting}[style=Bash]
-$ path -p0 -R < ../dumux/patches/pdelab-1.1.0.patch
+$ path -p0 -R < ../dumux/patches/grid-2.3.1.patch
\end{lstlisting}
The \texttt{checkout-dumux} script also applies patches, if not explicitly requested not to do so.
-\section{Building doxygen documentation} \label{sec:build-doxy-doc}
-Doxygen documentation is done by especially formatted comments integrated in the source code, which can get extracted by the program
-\texttt{doxygen}. Beside extracting these comments, \texttt{doxygen} builds up a web-browsable code structure documentation
+\subsubsection{Hints for \Dumux-Developers}
+If you also want to actively participate in the development of \Dumux, you can allways send patches
+to the Mailing list.
+
+To get more involved, you can apply either for full developer
+access or for developer access on certain parts of \Dumux. Granted developer access means that
+you are allowed to commit own code and that you can access the \texttt{dumux-devel} module.
+This enhances \texttt{dumux} by providing maybe unstable code from the developer group.
+A developer usually checks out non-anonymously the modules \texttt{dumux} and \texttt{dumux-devel}.
+\texttt{Dumux-devel} itself makes use of the stable part \texttt{dumux}. Hence, the two parts have to be checked out together.
+This is done using the commands below. But \texttt{joeuser} needs to be replaced by
+the actual user name of the developer for accessing the software repository.
+One can omit the \texttt{--username} option in the commands above if the user name for the repository access is
+identical to the one for the system account.
+
+\begin{lstlisting}[style=Bash]
+$ svn co --username=joeuser svn://svn.iws.uni-stuttgart.de/DUMUX/dumux/trunk dumux
+$ svn co --username=joeuser svn://svn.iws.uni-stuttgart.de/DUMUX/dune-mux/trunk dumux-devel
+\end{lstlisting}
+
+Please choose either not to store the password by subversion in an insecure way or
+choose to store it by subversion in a secure way, e.\,g. together with KDE's KWallet or GNOME Keyring.
+Check the documentation of Subversion for info on how this is done.
+A leaked out password can be used by evil persons to abuse a software repository.
+
+\section{Building Documentation}
+\subsection{Doxygen}
+\label{sec:build-doxy-doc}
+Doxygen documentation is done by especially formatted comments integrated in the source code,
+which can get extracted by the program \texttt{doxygen}. Beside extracting these comments,
+\texttt{doxygen} builds up a web-browsable code structure documentation
like class hierarchy of code displayed as graphs, see \cite{DOXYGEN-HP}.
-The Doxygen documentation of a module can be built, provided the program \texttt{doxygen} is installed,
-by running \texttt{dunecontrol}, entering the module's root directory, and execute \texttt{make doc}.
-Point your web browser to the file
-\texttt{module-root-directory/doc/doxygen/html/index.html} to read the generated documentation.
+The Doxygen documentation of a module can be built, if \texttt{doxygen} is installed,
+by running \texttt{dunecontrol}, entering the \texttt{build-*}directory, and execute
+\texttt{make doc}. Then point your web browser to the file
+\texttt{MODULE\_BUILD\_DIRECTORY/doc/doxygen/html/index.html} to read the generated documentation.
+This should also work for other \Dune modules.
-\section{Building documentation of other \Dune modules}
-If the \texttt{--enable-documentation} switch has been set in the configure flags of
-\texttt{dunecontrol}, this does not necessarily mean that for every
-\Dune module the documentation is automatically being built. Run the target \texttt{make doc}
-in the module's root directory to generate to build the module's documentation.
+\subsection{Handbook}
+To build the \Dumux handbook go into the \texttt{build-}directory and
+run \texttt{make doc} or \texttt{make dumux-handbook\_pdf}. The pdf can then be found
+in \texttt{MODULE\_BUILD\_DIRECTORY/doc/handbook/dumux-handbook.pdf}.
-\section{External libraries and modules} \label{sec:external-modules-libraries}
+
+\section{External Libraries and Modules} \label{sec:external-modules-libraries}
The libraries described below provide additional functionality but are not generally required to run \Dumux.
If you are going to use an external library check the information provided on the \Dune website \cite{DUNE-EXT-LIB}.
If you are going to use an external \Dune module the website on external modules \cite{DUNE-EXT-MOD} can be helpful.
@@ -241,6 +244,8 @@ Installing an external library can require additional libraries which are also u
For some libraries, such as BLAS or MPI, multiple versions can be installed on the system.
Make sure that it uses the same library as \Dune when configuring the external library.
+
+\subsection{List of External Libraries and Modules}
In the following list, you can find some external modules and external libraries, and some more libraries and tools which are prerequisites for their use.
\begin{itemize}
@@ -297,33 +302,44 @@ The following are dependencies of some of the used libraries. You will need them
is the GNU compiler suite consisting of \texttt{gcc}, \texttt{g++} and \texttt{gfortran}.
\end{itemize}
-\section{Hints for Users from IWS}
+\subsection{Hints for Users from IWS}
We provide some features to make life a little bit easier for
users from the Institute for Modelling Hydraulic and Environmental Systems, University of Stuttgart.
-
There exists internally a Subversion repository made for several external libraries.
-If you are allowed to access it, go to the {\Dune}-Root, then the following.
+If you are allowed to access it, go to the {\Dune}-Root, then type the following.
-Prepared external directory:
+Prepare external directory:
\begin{lstlisting}[style=Bash]
$ # Make sure you are in DUNE-Root
$ svn checkout svn://svn.iws.uni-stuttgart.de/DUMUX/external/trunk external
\end{lstlisting}
-This directory \texttt{external} contains a script to install external libraries, such as
-ALBERTA, ALUGrid, UG, and METIS:
-\begin{lstlisting}[style=Bash]
-$ cd external
-$ ./installExternal.sh all
-\end{lstlisting}
+This directory \texttt{external} contains a script to install external libraries.
+type \texttt{help} to see which modules are currently available:
-It is also possible to install only the actually needed external libraries:
\begin{lstlisting}[style=Bash]
-$ ./installExternal.sh -h # show, what options this script provide
-$ ./installExternal.sh --parallel alu
+$ cd external
+$ ./installExternal.sh help
+
+Usage: ./external/installExternal.sh [OPTIONS] PACKAGES
+
+Where PACKAGES is one or more of the following
+ all Install everything and the kitchen sink.
+ alberta Install the alberta grid library.
+ alu Download dune-alugrid.
+ metis Install the METIS graph partitioner.
+ multidomain Download dune-multidomain.
+ multidomaingrid Download dune-multidomaingrid.
+ ug Install the UG grid library.
+ gstat Install the Gstat library.
+
+The following options are recoginzed:
+ --parallel Enable parallelization if available.
+ --debug Compile with debugging symbols and without optimization.
+ --clean Delete all files for the given packages.
\end{lstlisting}
-The libraries are then compiled within that directory and are not installed in a different place.
-A \Dune build may need to know their location. Thus, one may have to refer to them as options for \texttt{dunecontrol},
-for example via the options file \texttt{my-debug.opts}. Make sure you compile the required external libraries before
-you run \texttt{dunecontrol}.
+Some of the libraries are then compiled within that directory and are not installed in
+a different place, but \Dune may need to know their location. Thus, one may have to refer to
+them as options for \texttt{dunecontrol}, for example via the options file \texttt{my-debug.opts}.
+Make sure you compile the required external libraries before you run \texttt{dunecontrol}.
diff --git a/doc/handbook/models.tex b/doc/handbook/models.tex
index e2a2e2cdb779796c7a81f038a09fec52e820580f..e6f1b34f3415313d8353365e2c818de5f72488d7 100644
--- a/doc/handbook/models.tex
+++ b/doc/handbook/models.tex
@@ -1,6 +1,6 @@
-\chapter[Models]{Physical and numerical models}
+\chapter[The \Dumux Models]{Physical and Numerical Models Available in \Dumux}
-\section{Physical and mathematical description}
+\section{Physical and Mathematical Description}
Characteristic of compositional multiphase models is that the phases
are not only matter of a single chemical substance. Instead, their
@@ -111,7 +111,7 @@ $M$ & molar mass of a phase or component & $c_\text{s}$ & specific heat enthalpy
$k_{\text{r}\alpha}$ & relative permeability & $\lambda_\text{pm}$ & heat conductivity \\
$\mu_\alpha$ & phase viscosity & $q^h$ & heat source term \\
$D_\alpha^\kappa$ & diffusivity of component $\kappa$ in phase $\alpha$ & $\boldsymbol{v}_{a,\alpha}$ & advective velocity \\
-$\boldsymbol{v}_\alpha$ & Darcy velocity & & \\
+$\boldsymbol{v}_\alpha$ & velocity (Darcy or free flow)& & \\
\end{tabular}
@@ -196,70 +196,69 @@ fractions, temperature, pressures, etc.
\input{spatialdiscretization}
-\section{Available models}
+\section{Available Models}
The following description of the available models is automatically extracted
from the Doxygen documentation.
% \textbf{TODO}: Unify notation.
-\subsection{Fully-implicit models}
+\subsection{Fully-Implicit Models}
The fully-implicit models described in this section are using the box or the cell centered finite volume method as described in section \ref{box} and \ref{cc} for spatial and the implicit Euler
method as temporal discretization. The models themselves are located in
subdirectories of \texttt{dumux/implicit} of the \Dumux distribution.
-\subsubsection{The single-phase model: OnePModel}
+\subsubsection{The Single-Phase Model: OnePModel}
\input{ModelDescriptions/1pimplicitmodel}
-\subsubsection{The single-phase, two-component model: OnePTwoCModel}
+\subsubsection{The Single-Phase,Two-Component Model: OnePTwoCModel}
\input{ModelDescriptions/1p2cimplicitmodel}
-\subsubsection{The two-phase model using the Richards assumption: RichardsModel}
+\subsubsection{The Two-Phase Model Using the Richards Assumption: RichardsModel}
\input{ModelDescriptions/richardsimplicitmodel}
-\subsubsection{The two-phase model: TwoPModel}
+\subsubsection{The Two-Phase MOdel: TwoPModel}
\input{ModelDescriptions/2pimplicitmodel}
-\subsubsection{The two-phase, two-component model: TwoPTwoCModel}
+\subsubsection{The Two-Phase, Two-Component Model: TwoPTwoCModel}
\input{ModelDescriptions/2p2cimplicitmodel}
-\subsubsection{The CO2 model: CO2Model}
+\subsubsection{The CO2 Model: CO2Model}
\input{ModelDescriptions/co2implicitmodel}
-
-\subsubsection{The three-phase model: ThreePModel}
+\subsubsection{The Three-Phase Model: ThreePModel}
\input{ModelDescriptions/3pimplicitmodel}
-\subsubsection{The three-phase, three-component model: ThreePThreeCModel}
+\subsubsection{The three-Phase, Three-Component Model: ThreePThreeCModel}
\input{ModelDescriptions/3p3cimplicitmodel}
-\subsubsection{The non-isothermal model: NIModel}
+\subsubsection{The Non-Isothermal Model: NIModel}
\input{ModelDescriptions/nonisothermalimplicitmodel}
-\subsubsection{The $M$-phase, $N$-component model: MpNcModel}
+\subsubsection{The $M$-Phase, $N$-Component Model: MpNcModel}
\input{ModelDescriptions/mpncimplicitmodel}
-\subsubsection{The two-phase, discrete fracture model: TwoPDFMModel}
+\subsubsection{The Two-Phase, Discrete Fracture Model: TwoPDFMModel}
\input{ModelDescriptions/2pdfmimplicitmodel}
-\subsubsection{The Stokes model: StokesModel}
+\subsubsection{The Stokes Model: StokesModel}
\input{ModelDescriptions/stokesimplicitmodel}
-\subsubsection{The isothermal $N$-component Stokes model: StokesNcModel}
+\subsubsection{The Isothermal $N$-Component Stokes Model: StokesNcModel}
\input{ModelDescriptions/stokesncimplicitmodel}
-\subsubsection{The non-isothermal $N$-component Stokes model: StokesNcNIModel}
+\subsubsection{The Non-Isothermal $N$-Component Stokes Model: StokesNcNIModel}
\input{ModelDescriptions/stokesncniimplicitmodel}
-\subsubsection{The linear elastic model: ElasticModel}
+\subsubsection{The Linear Elastic Model: ElasticModel}
\input{ModelDescriptions/elasticmodel}
-\subsubsection{The linear elastic one-phase two-component model: ElOnePTwoCModel}
+\subsubsection{The Linear Elastic One-Phase Two-Component Model: ElOnePTwoCModel}
\input{ModelDescriptions/el1p2cmodel}
-\subsubsection{The linear elastic two-phase model: ElTwoPModel}
+\subsubsection{The Linear Elastic Two-Phase Model: ElTwoPModel}
\input{ModelDescriptions/el2pmodel}
-\subsection{Decoupled models}
+\subsection{Decoupled Models}
%
The basic idea the so-called decoupled models have in common is to reformulate the equations of multi-phase flow (e.g. Eq. \ref{A3:eqmass1}) into one equation for pressure and equations for phase-/component-/etc. transport. The pressure equation is the sum of the mass balance equations and thus considers the total flow of the fluid system. The new set of equations is considered as decoupled (or weakly coupled) and can thus be solved sequentially. The most popular decoupled model is the so-called fractional flow formulation for two-phase flow which is usually implemented applying an IMplicit Pressure Explicit Saturation algorithm (IMPES).
In comparison to a fully implicit model, the decoupled structure allows the use of different discretization methods for the different equations. The standard method used in the decoupled models is a cell centered finite volume method. Further schemes, so far only available for the two-phase pressure equation, are cell centered finite volumes with multi-point flux approximation (MPFA O-method) and mimetic finite differences.
@@ -271,13 +270,13 @@ An $h$-adaptive implementation of both \nameref{ch:2p_decoupled} and \nameref{ch
\subsubsection{The two-phase model}\label{ch:2p_decoupled}
-\paragraph{Pressure model}
+\paragraph{Pressure Model}
\input{ModelDescriptions/2pdecoupledpressuremodel}
-\paragraph{Saturation model}
+\paragraph{Saturation Model}
\input{ModelDescriptions/2pdecoupledsaturationmodel}
-\subsubsection{The two-phase, two-component model}\label{ch:2p2c_decoupled}
+\subsubsection{The Two-Phase, Two-Component Model}\label{ch:2p2c_decoupled}
\input{ModelDescriptions/2p2cdecoupledpressuremodel}
\input{ModelDescriptions/2p2cdecoupledtransportmodel}
diff --git a/doc/handbook/newFolder.tex b/doc/handbook/newFolder.tex
index 29894343b6b8c373593c701aeee5409850ae76cd..022a81a47eea53f566a813e106af8ff0a6427a31 100644
--- a/doc/handbook/newFolder.tex
+++ b/doc/handbook/newFolder.tex
@@ -1,56 +1,53 @@
-\section{Setup of a New Folder}
+\section{Setup of a New Folder and New Tests}
-In this section setting up a new folder is described. In fact it is easy to create a new folder, but getting the build system to know the new folder takes some steps:
+\paragraph{Setting up a New Folder}
+In this section it is described how to set up a new folder and how to tell
+the build system, that there is a new one.
\begin{enumerate}[1)]
\item create new folder with content
- \item adapt \verb+Makefile.am+
- \item insert new folder in \verb+Makefile.am+ of the directory above
- \item adapt \verb+configure.ac+ in the \verb+$DUMUX_ROOT+ (the directory you checked out, probably dumux)
- \item rerun dunecontrol / autogen for \Dumux
+ \item adapt the \verb+CMakeList.txt+ in the folder above and add a line with
+ \verb+add_subdirectory(NEW\_FOLDER)+
+ \item adapt the \verb+CMakeList.txt+ in the newly created folder and add your test
+ (see below for more information)
+ \item go to your \texttt{build}-directory and type \verb+make+ to
+ reconfigure the system
\end{enumerate}
-\noindent In more detail:
-
-\textbf{First} of all, the new folder including all relevant files needs to be created (see Section \ref{tutorial-coupled} and \ref{tutorial-decoupled} for description of a problem).
-
-\textbf{Second}, a new \verb+Makefile.am+ for the new Folder needs to be created. It is good practice to simply copy an existing file. For example the file \verb+$DUMUX_ROOT/test/2p/Makefile.am+ looks as follows:
+\paragraph{Adding a New Test Program}
+\noindent To simply add a new executable use the following macro. The test will \emph{not} be built
+automatically when running \texttt{ctest}. You have to compile it manually by
+\texttt{make test\_program}.
\begin{verbatim}
-bin_PROGRAMS = test_2p
-
-test_2p_SOURCES = test_2p.cc
-test_2p_CXXFLAGS = $(MPI_CPPFLAGS)
-test_2p_LDADD = $(MPI_LDFLAGS)
-
-include $(top_srcdir)/am/global-rules
+add_executable_all(test\_program test\_program.cc)
\end{verbatim}
-All occurrences of \verb+test_2p+ need to be replaced by the name of the new project, e.g. \verb+New_Project+. At least if the name of the source file as well as the name of the new project are \verb+New_Project+.
-
-\textbf{Third}: In the directory above your new Project there is also a \verb+Makefile.am+ . In this file the subdirectories are listed. As you introduced a new subdirectory, it needs to be included here. In this case the name of the new Folder is \verb+New_Project+ . Don't forget the trailing backslash.
-
+\noindent To add a test, which should be compiled when running \texttt{ctest}, use the
+\texttt{add\_dumux\_test} macro. You can decide whether, the program should be run
+after compiling or not.
+Please note that the name of the test (first argument) must be unique, whereas the name
+of the executable (second argument) can occur multiple times.
\begin{verbatim}
- SUBDIRS = . \
- 1p \
- 1p2c \
- 2p \
- 2p2c \
- 2p2cni \
- 2pni \
- New_Project \
-...
+add_dumux_test(test\_program test\_program test\_program.cc
+ test\_program # add this line, if the program should also be run
+ )
\end{verbatim}
-\textbf{Fourth}: In \verb+$DUMUX_ROOT+ there is a file \verb+configure.ac+. In this file, the respective Makefiles are listed. After a line reading
-
- \verb+AC_CONFIG_FILES([Makefile+
-
- \noindent a line, declaring a new Makefile, needs to be included. The Makefile itself will be generated automatically during the autogen run which is triggered by dunecontrol. For keeping track of the included files, inserting in alphabetical order is good practice. The new line could read: \verb+test/New_Project/Makefile+
-
-\textbf{Fifth}: Recreate the build system by running dunecontrol as described in Section \ref{install}.
+\noindent To add a test which should be run and compared to a reference solution when using
+\texttt{ctest}, please use the following structure. The macro \texttt{\${CMAKE\_SOURCE\_DIR}}
+gives the location of your source code. The macro \texttt{\${CMAKE\_CURRENT\_BINARY\_DIR}}
+gives the current folder with the executable.
+\begin{verbatim}
+add_dumux_test(test\_program test\_program test\_program.cc
+ ${CMAKE_SOURCE_DIR}/bin/runTest.sh
+ ${CMAKE_SOURCE_DIR}/bin/fuzzycomparevtu.py
+ LOCATION_TO_THE_REFERNCE_SOLUTION/test\_program-reference.vtu
+ ${CMAKE_CURRENT_BINARY_DIR}/test\_program-00009.vtu
+ ${CMAKE_CURRENT_BINARY_DIR}/test\_program)
+\end{verbatim}
-\paragraph{Committing a new folder to the Subversion repository}
-For those who work with Subversion (svn) and want to commit a newly setup folder to the repository some basics are
+\paragraph{Committing a New older to SVN}
+For those who work with Subversion (\texttt{svn}) and want to commit a newly setup folder to the repository some basics are
given in this paragraph. For further reading please check out the Subversion User Manual found at \cite{APACHE-SUBVERSION-HP}
where you will also find a "High Speed Turorial" in the appendix. \\
The four most important commands are \texttt{svn checkout}, \texttt{svn update}, \texttt{svn add}
@@ -60,39 +57,15 @@ latest changes in the repository (commits from other users). In order to add a n
steps have to be taken:
\begin{enumerate}[1)]
- \item \texttt{svn update}: The first step is to update your \Dumux. You should execute this command in your
-dumux-stable or dumux-devel folder.
- \item \texttt{svn add --depth=empty YOURFOLDER}: This command adds the folder without its content.
- \item In your folder: use \texttt{svn add YOURFILES} to add your files. Generally, you should only add
-your header files (.hh), your source files (.cc), your input file (.input) and if required your grid file (.dgf).
+\item \texttt{svn update}: The first step is to update your \Dumux. You should execute this command in your
+ dumux-stable or dumux-devel folder.
+\item \texttt{svn add --depth=empty YOURFOLDER}: This command adds the folder without its content.
+\item In your folder: use \texttt{svn add YOURFILES} to add your files. Generally, you should only add
+ your header files (.hh), your source files (.cc), your input file (.input), if required your
+ grid file (.dgf) or if necessary other text-based files. Please do not upload (large) binary files.
+\item Type \texttt{svn status} in your \texttt{dumux}-root directory the see all the file changes.
+ \texttt{?} indicates possible forgotten files. Make sure that you include all necessary
+ files in your commit.
\item Use \texttt{svn commit} from the directory level containing your folder. This uploads all your changes to the
-svn server. You will be asked to briefly explain the content of your commit in an editor.
-\end{enumerate}
-
-The above shows you the necessary steps if you use the command line. There are also other tools providing a graphical
-user interface for using svn like kdesvn or eclipse. The necessary steps for adding and committing stay the same.
-In the following some additional guidelines are shown which are not necessary but are good practice.
-Especially if you plan on committing to the stable part of \Dumux you must follow these steps.
-
-\begin{enumerate}[1)]
- \item use svn attributes to ignore files which are automatically created by a dunecontrol run
- \item test \texttt{make headercheck}
- \item test Doxygen
+ svn server. You will be asked to briefly explain the content of your commit in an editor.
\end{enumerate}
-
-\noindent In more detail:
-
-\textbf{First}: The command \verb+svn status+ marks all files which are not under version control with a question mark. Because dunecontrol creates a lot of files automatically this output becomes crowded and one might overlook ``real'' files which have to be added (they also will not be shown by a \verb+svn status -q+).
-For the stable part of \Dumux there is the rule to ignore and only to ignore the folder {\em .deps}, executables \texttt{test\_*}, and the files {\em Makefile} and {\em Makefile.in}.
-
-How to set the SVN attributes:
-\begin{itemize}
- \item{\em eclipse}: right click on the file/folder $\rightarrow$ ``team'' $\rightarrow$ ``add to svn:ignore\dots''
- \item{\em kdesvn}: right click on the file/folder $\rightarrow$ ``ignore/unignore current item''
- \item{\em SVN on shell}: \verb+svn propedit svn:ignore .+
-\end{itemize}
-Commit the changes for example in the command line with \verb+svn commit -m+ to the repository. It is also possible to use wildcards, e.\,g., if you want to ignore all vtu-files in your application folder in dumux-devel add \verb+'*.vtu'+ to the SVN ignore properties. Remember that such an ignore is only allowed in dumux-devel and not in the stable dumux.
-
-\textbf{Second}: It is good practice that every header includes everything it uses by itself and does not rely on the includes from headers that are included by themselves. This can be tested with \texttt{make headercheck} and should be done before committing to stable dumux. To test a specific header, use \texttt{make} \texttt{headercheck} \texttt{HEADER=} and add the header's path.
-
-\textbf{Third}: Run \texttt{make doc} in the \texttt{\$DUMUX\_ROOT} directory to generate the class documentation by Doxygen. Have a look into \texttt{\$DUMUX\_ROOT/doc/doxygen/doxyerror.log} whether one of your files have errors or are causing warnings. Please fix them.
diff --git a/doc/handbook/parameterTree.tex b/doc/handbook/parameterTree.tex
deleted file mode 100644
index 8433897a361f1c6b835bbfcb96e0756a0158eb77..0000000000000000000000000000000000000000
--- a/doc/handbook/parameterTree.tex
+++ /dev/null
@@ -1,103 +0,0 @@
-\section{Parameter Files in \Dumux}
-\label{sec:inputFiles}
-Parameter files can be used to set important parameters for the simulation run.
-A list of all available parameters is provided in the Doxygen documentation
-of the file \texttt{parameterfile}, which is accessible via \texttt{Modules -> Parameters}.
-In order to have a closer look, we return to the example from the
-previous section \ref{quick-start-guide}. There, 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{\_}box2p -parameterFile ./test\_box2p.input -PrintParameters 1 }} at the end of the simulation run:
-\begin{lstlisting}[style=Bash]
-###############################
-# Run-time specified parameters:
-###############################
-[ Grid ]
-File = "./grids/test_2p.dgf"
-[ Problem ]
-Name = "lensbox"
-[ SpatialParams ]
-LensLowerLeftX = "1.0"
-LensLowerLeftY = "2.0"
-LensUpperRightX = "4.0"
-LensUpperRightY = "3.0"
-[ TimeManager ]
-DtInitial = "250"
-TEnd = "3000"
-###############################
-# Compile-time specified parameters:
-###############################
-[ Implicit ]
-EnableHints = "0"
-EnableJacobianRecycling = "1"
-EnablePartialReassemble = "1"
-MassUpwindWeight = "1"
-MaxTimeStepDivisions = "10"
-MobilityUpwindWeight = "1"
-NumericDifferenceMethod = "1"
-UseTwoPointFlux = "0"
-[ LinearSolver ]
-MaxIterations = "250"
-PreconditionerRelaxation = "1"
-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"
-[ Problem ]
-EnableGravity = "1"
-[ TimeManager ]
-MaxTimeStepSize = "1.79769e+308"
-[ Vtk ]
-AddVelocity = "0"
-\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.
-
-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.
-
-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/implicit/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/implicit/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.
-
-
diff --git a/doc/handbook/parameterfiles.tex b/doc/handbook/parameterfiles.tex
new file mode 100644
index 0000000000000000000000000000000000000000..7eaeeeba6407103364712d451d03411deb1edc83
--- /dev/null
+++ b/doc/handbook/parameterfiles.tex
@@ -0,0 +1,118 @@
+\section{Parameter Files in \Dumux}
+\label{sec:inputFiles}
+\Dumux simulations can be run with the use parameter files. Here basic information how to set,
+extend, and improve your problem by using parameter files.
+A list of all available parameters is provided in the \texttt{doxygen} documentation
+of the file \texttt{parameterfile}, which is accessible via \texttt{Modules -> Parameters}.
+
+\subsection{Advantages of Parameter Files}
+Parameter files are worth of taking a closer look at, because using then considerably
+improves the workflow.
+
+\begin{itemize}
+ \item The parameter file is read in by the compiled program. This way you can change
+ values without having to recompile the whole application.
+ \item With a very generic model, you can use different input files for defining different
+ setups and always use the same program.
+ \item You can use the parameter file in order to back up parameters that you used for
+ a certain model run.
+\end{itemize}
+
+\subsection{Changing Parameters}
+After having run the example application from section \ref{quick-start-guide} you will
+get the following output at the end of the simulation run
+\footnote{If you did not get the output, restart the application the following way:
+\texttt{./test{\_}box2p -parameterFile ./test\_box2p.input -PrintParameters 1},
+this will print the parameters once your simulation is finished}
+:
+\begin{lstlisting}[style=Bash]
+# Run-time specified parameters:
+[ Grid ]
+File = "./grids/test_2p.dgf"
+[ Implicit ]
+EnableJacobianRecycling = "1"
+EnablePartialReassemble = "1"
+[ Problem ]
+Name = "lensbox"
+[ SpatialParams ]
+LensLowerLeftX = "1.0"
+LensLowerLeftY = "2.0"
+LensUpperRightX = "4.0"
+LensUpperRightY = "3.0"
+[ TimeManager ]
+DtInitial = "250"
+TEnd = "3000"
+# Compile-time specified parameters:
+[ Implicit ]
+EnableHints = "0"
+MassUpwindWeight = "1"
+MaxTimeStepDivisions = "10"
+MobilityUpwindWeight = "1"
+NumericDifferenceMethod = "1"
+UseTwoPointFlux = "0"
+[ LinearSolver ]
+MaxIterations = "250"
+PreconditionerRelaxation = "1"
+ResidualReduction = "1e-06"
+Verbosity = "0"
+[ Newton ]
+EnableResidualCriterion = "0"
+EnableShiftCriterion = "1"
+MaxRelativeShift = "1e-08"
+MaxSteps = "18"
+ResidualReduction = "1e-05"
+SatisfyResidualAndShiftCriterion = "0"
+TargetSteps = "10"
+UseLineSearch = "0"
+WriteConvergence = "0"
+[ Problem ]
+EnableGravity = "1"
+[ TimeManager ]
+MaxTimeStepSize = "1.79769e+308"
+[ Vtk ]
+AddVelocity = "0"
+\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.
+The output will tell you, which parameters are available to the problem and whether they have
+been specified
+\begin{itemize}
+ \item \emph{run-time} via your input file
+ \item \emph{compile-time} and have not been overwritten by the input file
+ \item in your input file, but are \emph{UNUSED} by the simulation
+\end{itemize}
+For example by adding
+\begin{lstlisting}[style=Bash]
+[ Newton ]
+MaxRelativeShift = "1e-11"
+\end{lstlisting}
+to the input file you can specify that the Newton solver considers itself converged for an
+error a thousand times smaller.
+
+The \emph{UNUSED} warning
+\begin{lstlisting}[style=Bash]
+# UNUSED parameters:
+Problem.ImportantVariable = "42"
+\end{lstlisting}
+is important, because it shows that the application did not read in this value.
+Maybe because it was attributed to the wrong group or there was a typo.
+This feature is \emph{very} useful for debugging or spotting typos, like when you wanted
+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.
+
+\subsection{Technical Issues on Parameters}
+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.
+
+
diff --git a/doc/handbook/quick-install.tex b/doc/handbook/quick-install.tex
index 80459c6c4a6b391bafa156192df30464e0026945..9d349ea5a2918e104349944d3ab3f0d296431b57 100644
--- a/doc/handbook/quick-install.tex
+++ b/doc/handbook/quick-install.tex
@@ -6,7 +6,7 @@ If you need more information,
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{Obtaining the Code with the Script \texttt{checkout-dumux}}
The shell-script \texttt{checkout-dumux} facilitates setting up a {\Dune}/{\Dumux} directory tree.
It is available at \cite{DUMUX-DOWNLOAD}.
@@ -37,7 +37,7 @@ 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}:
\begin{lstlisting}[style=Bash]
$ # make sure you are in the directory DUNE-Root
-$ ./dune-common/bin/dunecontrol --configure-opts="CXXFLAGS=-fno-strict-aliasing" all
+$ ./dune-common/bin/dunecontrol --configure-opts="CXXFLAGS=-fno-strict-aliasing" --use-cmake 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.
@@ -47,13 +47,13 @@ can be a starting point:
$ # 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
+$ ./dune-common/bin/dunecontrol --opts=my-debug.opts --use-cmake 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
+$ ./dune-common/bin/dunecontrol --opts=my-optim.opts --use-cmake all
\end{lstlisting}
Sometimes it is necessary to have additional options which
diff --git a/doc/handbook/quickstart-guide.tex b/doc/handbook/quickstart-guide.tex
index 20a010b42863a151e0372d45eb3c104f1ffc5596..16756e4c99ef56b1885524736d7261e367e41343 100644
--- a/doc/handbook/quickstart-guide.tex
+++ b/doc/handbook/quickstart-guide.tex
@@ -1,12 +1,26 @@
-\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 \Dumux. This chapter
+shall give a very brief introduction how to run a first test application and how
+to visualize the first output files. A more detailed explanations can be found in
+the tutorials in the following chapter.\\
+All executables are compiled in the \texttt{build} subdirectories of \Dumux.
+If not given differently in the input files, this is \texttt{build-cmake} as default.
\begin{enumerate}
- \item Go to the directory \texttt{/test}. There, various test application folders can be found. Let us consider as example \texttt{implicit/test{\_}box2p}:
- \item Enter the folder \texttt{implicit/2p}. If everything was compiled correctly, there should be the executable \texttt{test{\_}box2p}. Otherwise, type \texttt{make test{\_}box2p} in order to compile the application \texttt{test{\_}box2p}. To run the simulation, type\\
- \texttt{./test{\_}box2p -parameterFile ./test\_box2p.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\_box2p.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{build-cmake/test}. There, various test application
+ folders can be found. Let us consider as example \texttt{implicit/test{\_}box2p}:
+\item Enter the folder \texttt{implicit/2p}. Type \texttt{make test{\_}box2p} in order
+ to compile the application \texttt{test{\_}box2p}. To run the simulation, type\\
+ \texttt{./test{\_}box2p -parameterFile ./test\_box2p.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\_box2p.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.
\end{enumerate}
diff --git a/doc/handbook/restartsimulations.tex b/doc/handbook/restartsimulations.tex
new file mode 100644
index 0000000000000000000000000000000000000000..cb240f1e417d8e4aabab225d5524348ced213c5f
--- /dev/null
+++ b/doc/handbook/restartsimulations.tex
@@ -0,0 +1,30 @@
+\section{Restart \Dumux Simulations}
+\label{sec:restartSimulations}
+Using the restart capability of \Dumux can be advantageous for computationally
+expensive or time consuming simulations, because you can restart the simulation
+from a specific point in time and e.g. extend the simulation beyond the originally
+end of simulation. What you need is a \texttt{*.drs} file (which contains the
+all necessary restart information.
+Then you can simply restart a simulation via
+\begin{lstlisting}[style=Bash]
+./test_program -ParameterFile test_program.input -TimeManager.Restart RESTART_TIME
+\end{lstlisting}
+To the test restart behavior e.g. use the \texttt{test\_box1p2cni} problem
+in the \texttt{test/implicit/1p2c} folder.
+You get the \texttt{RESTART\_TIME} from the name of your \texttt{.drs} file.
+Please note, that restarting will only work by giving a exact time from
+an existing restart file.
+Depending on your type of model, you should get a \texttt{.drs} file every
+5th or 10th time step. If this not frequently enough, you can change it
+by using the following function into your problem header:
+\begin{lstlisting}[style=DumuxCode]
+/*!
+ * \brief Returns true if a restart file should be written to
+ * disk.
+ */
+bool shouldWriteRestartFile() const
+{
+ return true;
+}
+\end{lstlisting}
+
diff --git a/doc/handbook/spatialdiscretization.tex b/doc/handbook/spatialdiscretization.tex
index 5fd57dff46957bf06dc14e58fd752756300ec471..59e108eb7dad4f465030ea38cb555d98e8c296e6 100644
--- a/doc/handbook/spatialdiscretization.tex
+++ b/doc/handbook/spatialdiscretization.tex
@@ -3,7 +3,7 @@
For the implicit models there are two spatial discretization schemes (box and Cell Centered Finite Volume Method) available which are shortly introduced
in this section.
-\subsection{Box method - A short introduction}\label{box}
+\subsection{Box Method -- A Short Introduction}\label{box}
The so called box method unites the advantages of the finite-volume (FV) and finite-element (FE) methods.
@@ -124,7 +124,7 @@ The consideration of the time discretization and inserting $W_j = 1$ finally lea
V_i \frac{\hat u_i^{n+1} - \hat u_i^{n}}{\Delta t} + \int_{\partial B_i} F(\tilde u^{n+1}) \cdot \mathbf n \; d{\varGamma}_{B_i} - V_i \: q^{n+1} \: = 0
\end{equation}
-\subsection{Cell centered finite volume method - A short introduction}\label{cc}
+\subsection{Cell Centered Finite Volume Method -- A Short Introduction}\label{cc}
\begin{figure} [ht]
\centering
diff --git a/doc/handbook/structure.tex b/doc/handbook/structure.tex
index 3b60c0cf7b22cd6abc5bbee515ad9f5f5dc627e1..57f8679bdf265d806233e1d0350e937f8d8aaf99 100644
--- a/doc/handbook/structure.tex
+++ b/doc/handbook/structure.tex
@@ -9,7 +9,8 @@ the Doxygen documentation should be considered.
It has a similar structure as other DUNE modules like \texttt{dune-grid}.
The following subdirectories are within the module's root directory,
from now on assumed to be \texttt{/}:
-\begin{itemize}
+\begin{itemize}
+\item \texttt{bin}: contains binaries, e.g. used for the automatic testing
\item \texttt{CMake}: the configuration options
for building \Dumux using CMake. See the file \texttt{INSTALL.cmake} in
the root directory of \texttt{dumux} for details. Of course,
@@ -62,7 +63,7 @@ and the \texttt{start.hh} file that includes the common routine for starting a m
% employed by the box method to extract the dual mesh geometry information out of the
% primal one.
-\item \texttt{io}: additional in-/output possibilities like restart files
+\item \texttt{io}: additional in-/output possibilities like restart files, gnuplot-interface
and a VTKWriter extension.
\item \texttt{material}: everything related to material parameters and
@@ -194,7 +195,7 @@ Doxygen documentation should be considered.
\draw [->](c1)--(6.5,2) node [right,text width=12.5cm,align=left]
{Common functionality of cell centered and box formulation: assembling \\[-5pt]in implicitlocaljacobian.hh, evaluation of partial derivative in \\[-5pt]implicitlocalresidual.hh, base classes for model and problem definition.};
\draw [->](io)--(6.5,1) node [right,text width=12.5cm,align=left]
- {Additional in-/output possibilities like restart files and a VTKWriter \\[-4pt]extension. Grid Creator files.};
+ {Additional in-/output possibilities like restart files, gnuplot-interface and a VTKWriter \\[-4pt]extension. Grid Creator files.};
\draw [->](lin)--(6.5,0) node [right,text width=12.5cm,align=left] {Linear solver backend.};
\draw [->](bin)--(6.5,-1) node [right,text width=12.5cm,align=left]
{Binary coefficients (like binary diffusion coefficients) and those needed for \\[-4pt]the constitutive relationships (e.g. Henry coefficient).};
@@ -232,5 +233,7 @@ Doxygen documentation should be considered.
% \end{figure}
% \end{landscape}
-\input{guidelines}
\input{newFolder}
+\input{parameterfiles}
+\input{restartsimulations}
+\input{guidelines}
diff --git a/doc/handbook/tutorial-decoupled.tex b/doc/handbook/tutorial-decoupled.tex
index a8effe7cbee611d7cf46721d637cea7c4a661bcd..69d3b487a125abb66ed29685d30a12268fc276e6 100644
--- a/doc/handbook/tutorial-decoupled.tex
+++ b/doc/handbook/tutorial-decoupled.tex
@@ -93,7 +93,8 @@ message is customized to the problem at hand. This means that at least
the necessary parameters are listed here. For more information about
the input file please refer to section \ref{sec:inputFiles}.
-\subsection{The problem class} \label{decoupled_problem}
+\subsection{The Problem Class}
+\label{decoupled_problem}
When solving a problem using \Dumux, the most important file is the
so-called \textit{problem file} as shown in listing
@@ -171,7 +172,7 @@ sinkterms, boundary conditions (lines \ref{tutorial-decoupled:bctype} to
quantity in line \ref{tutorial-decoupled:initial}. For more information
on the functions, consult the documentation in the code.
-\subsection{The definition of the parameters that are dependent on space}\label{tutorial-decoupled:description-spatialParameters}
+\subsection{The Definition of the Parameters that are Dependent on Space}\label{tutorial-decoupled:description-spatialParameters}
Listing \ref{tutorial-decoupled:spatialparamsfile} shows the file
\verb+tutorialspatialparams_decoupled.hh+:
diff --git a/doc/handbook/tutorial-newmodel.tex b/doc/handbook/tutorial-newmodel.tex
deleted file mode 100644
index 0a9ab94d72b6d5e4c0e262281c545c901319c618..0000000000000000000000000000000000000000
--- a/doc/handbook/tutorial-newmodel.tex
+++ /dev/null
@@ -1,3 +0,0 @@
-\section[New model]{How to implement a new model}
-
-TODO: describe how to impelment a new model
\ No newline at end of file
diff --git a/doc/handbook/tutorial.tex b/doc/handbook/tutorial.tex
index 4233c1b56b3c89ffb6a535185dd753fcb26ecbab..0569ed9252ba8c183d7868b268638cf01db6e991 100644
--- a/doc/handbook/tutorial.tex
+++ b/doc/handbook/tutorial.tex
@@ -7,9 +7,3 @@ Examples for different kinds of both, coupled and decoupled models, are isotherm
In section \ref{box} a short introduction to the box method is given, in section \ref{cc} the cell centered finite volume method is introduced. The box method is used in the fully-coupled models for the spatial discretization of the system of equations. The decoupled models employ usually a cell centered finite volume scheme. The following two sections of the tutorial demonstrate how to solve problems using, first, a fully-coupled model (section \ref{tutorial-coupled}) and, second, using a decoupled model (section \ref{tutorial-decoupled}). Being the easiest case, an isothermal two-phase system (two fluid phases, one solid phase) will be considered.
\input{tutorial-coupled}
\input{tutorial-decoupled}
-%\input{tutorial-newmodel}
-
-%%% Local Variables:
-%%% mode: latex
-%%% TeX-master: "dumux-handbook"
-%%% End: