quenched typos, enhanced readability in few places

AND
updated the "Mother of all Flowcharts" (here to stay)


git-svn-id: svn://svn.iws.uni-stuttgart.de/DUMUX/dumux/trunk@4847 2fb0f335-1f38-0410-981e-8018bf24f1b0

doc/handbook/TipsNTricks.tex

@@ -2,7 +2,7 @@
 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 at least write it to the mailing list \\ \verb+dumux@iws.uni-stuttgart.de so somebody else can+). 
+handy or for other reasons helping when working with \Dumux: put it into this chapter.'' (or at least write it to the mailing list \\ \verb+dumux@iws.uni-stuttgart.de+ so somebody else can). 
 \begin{itemize}
  \item Using the \Dumux-Eclipse profile:
 

doc/handbook/designpatterns.tex

@@ -41,7 +41,7 @@ only ``clean'' way to achive this without templates would be to copy
 \texttt{value} attribute. It is obvious that this is a very
 cumbersome, error-prone and unproductive process. For this reason,
 recent standards of the C++ programming language specify the template
-mechanism, which is a way let the compiler do the tedious work. Using
+mechanism, which is a way to let 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>
@@ -122,13 +122,13 @@ 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 corrosponds to the current
-  $CO_2$ emission goal of the European Union but can be changed by
+  \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$ in the
-  base class. This tells the compiler that it is mandatorily that this
-  method gets defined in derived classes. Finally, the method
+  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 information it needs, it does not
@@ -138,8 +138,8 @@ executed is dynamically determined at run time.
 class Car
 {public:
   virtual double gasUsage() 
-  { return 4.5; };
-  virtual double fuelTankSize() = 0;
+  { return 4.5; };/*@\label{designpatterns:virtual-usage}@*/
+  virtual double fuelTankSize() = 0;/*@\label{designpatterns:totally-virtual}@*/
   
   double range(double fuelTankFillLevel) 
   { return 100*fuelTankFillLevel*fuelTankSize()/gasUsage(); }
@@ -388,7 +388,7 @@ order to keep the code maintainable.
 \section{Traits Classes}
 
 A classic approach to reduce the number of template parameters is to
-gather the all arguments in a special class, a so-called traits
+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>
@@ -412,7 +412,7 @@ struct MyTraits
 \end{lstlisting}
 
 \noindent
-As there is no a free lunch, the traits approach comes with a few
+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
@@ -448,7 +448,7 @@ int main() {
 }
 \end{lstlisting}
 Contrary to what is intended, \texttt{v} is a vector of integers. This
-problem cannot also be solved using static polymorphism, since it
+problem can also not be solved using static polymorphism, since it
 would lead to a cyclic dependency between \texttt{MyBaseTraits} and
 \texttt{MyDoubleTraits}.
 

doc/handbook/dumux-handbook.tex

@@ -21,6 +21,17 @@
 \usepackage{rotating}
 \usepackage{subfig}
 
+\usepackage{ulem}
+\usepackage{tabularx}
+\usepackage{graphics}
+\usepackage{pstricks}
+\newcommand{\snakeline}{%
+% {\uwave{\makebox[\linewidth]{\mbox{}}}}
+\uwave{\mbox{}}
+}
+\usepackage{layout}
+
+
 %\usepackage{ngerman}
 \usepackage[english]{babel}
 

doc/handbook/install.tex

@@ -29,7 +29,7 @@ Beside the section on external modules below it is a good idea to check the {\Du
 
 \subsection{Obtaining \Dune and \Dumux}
 Two possibilities exist to obtain \Dune and \Dumux. 
-They can be obtained as so-called tarballs, i.e. \Dumux and \Dune code files of a certain version are packed into tar-archive files for download from the the respective {\Dune} and {\Dumux} website. 
+They can be obtained as so-called tarballs, i.e. \Dumux and \Dune code files of a certain version are packed into tar-archive files for download from the respective {\Dune} and {\Dumux} website. 
 The shell command \texttt{tar} can be used to extract them on your file system. This is explained in the next paragraph. 
 
 \paragraph{Obtaining the software by installing tarballs}
@@ -85,7 +85,7 @@ In order to obtain an anonymous read-only copy of the stable part of \Dumux from
 
 If you also want to commit new developments to the repositories, you can ask the \Dumux project leader to get either full developers access or access for certain parts of \Dumux. 
 The developer part \texttt{dumux-devel} is only available for people who belong to the \Dumux developer group and have non-anonymous access to the subversion repositories. 
-If you have developer rights the checkout looks as follows: 
+If you have developer rights the checkout looks as follows (system administrators will have to add you to the developer group and  give you a password for this access): 
 \begin{itemize}
  \item \texttt{svn checkout --username=yourusername \\ 
       \hspace{4cm} svn://svn.iws.uni-stuttgart.de/DUMUX/dumux/trunk dumux}
@@ -174,7 +174,7 @@ But a \Dune build still needs to know where they are. You have to refer to them
 
 \paragraph{Build \Dune and \Dumux}
 \label{buildIt}
-To compile \Dumux with out additional options file, type in the {\Dune}-Root-directory (called \texttt{DUMUX} before):
+To compile \Dumux without additional options file, type in the {\Dune}-Root-directory (called \texttt{DUMUX} before):
 \begin{center}
  \texttt{./dune-common/bin/dunecontrol all}
 \end{center}

doc/handbook/intro.tex

@@ -50,7 +50,7 @@ spatial incarnation within the grid by a so-called geometry
 function\footnote{The same approach is also used by \texttt{dune-disc} for
   finite element shape functions.}. Here, a reference element for an
 entity can be thought of as a prototype for the actual grid
-entity. For example, if we used at a grid that used hexahedrons as cells,
+entity. For example, if we used a grid that used hexahedrons as cells,
 the reference element for each cell would be the unit cube $[0, 1]^3$
 and the geometry function would scale and translate the cube so that
 it matches the grid's cell. For a more thorough description of DUNE's

doc/handbook/models.tex

@@ -42,7 +42,7 @@ since discontinuities in pressure can occur across a fluid-fluid
 interface due to capillary effects.
 
 \textbf{Notation:} The index $\alpha \in \{\text{w}, \text{n}, \text{g}\}$ refers 
-to the phase, while the index $\kappa \in \{\text{w}, \text{a}, \text{c}\}$ refers 
+to the phase, while the superscript $\kappa \in \{\text{w}, \text{a}, \text{c}\}$ refers 
 to the component. \\
 \begin{tabular}{llll}
 $p_\alpha$ & phase pressure & $\phi$ & porosity \\

doc/handbook/propertysystem.tex

@@ -7,7 +7,7 @@ follows a short reference and a short self-contained example.
 
 \section{Concepts and Features of the \Dumux Property System}
 
-The \Dumux property system was designed as an attept to mitigate the
+The \Dumux property system was designed as an attempt to mitigate the
 problems of traits classes. In fact, it can be seen as a traits system
 which allows easy inheritance and any acyclic dependency of parameter
 definitions. Just like traits, the \Dumux property system is a compile
@@ -95,7 +95,7 @@ SET_PROP(TypeTagName, PropertyTagName)
 For each program, a property itself can be declared at most once,
 although properties may be overwritten for derived type tags.
 
-Also, the following convenience macros available to define simple
+Also, the following convenience macros are available to define simple
 properties:
 \begin{lstlisting}[basicstyle=\ttfamily\scriptsize]
 SET_TYPE_PROP(TypeTagName, PropertyTagName, type);
@@ -299,9 +299,9 @@ the following:
 \item A tank exhibits a top speed of $60\;km/h$, uses $65\;l/100km$
   and features a $120\;mm$ diameter canon 
 \item A sedan has a gas usage of $7\;l/100km$, as well as an automatic
-  transmission, in every other aspect it is like for a compact car.
+  transmission, in every other aspect it is like a compact car.
 \item A pick-up truck has a top speed of $120\;km/h$ and a payload of
-  $5\;t$. In every other aspect it is like sedan or a truck but if in
+  $5\;t$. In every other aspect it is like a sedan or a truck but if in
   doubt it is more like a truck.
 \item The Hummer-H1 SUV exhibits the same top speed as a pick-up
   truck.  In all other aspects it is similar to a pickup and a tank,

doc/handbook/structure.tex

@@ -38,7 +38,7 @@ a derived specific numerical model. The subdirectory \texttt{common} also contai
 
 \item \texttt{common}:
 general stuff like the property system and the time management for the 
-fully coupled as well as the decoupled models, the interface for the Pardiso direct solver library,\cite{Pardiso}, and the \texttt{start.hh} file that includes the common routine for starting a model called in the main function. 
+fully coupled as well as the decoupled models, the interface for the Pardiso direct solver library \cite{Pardiso}, and the \texttt{start.hh} file that includes the common routine for starting a model called in the main function. 
 
 \item \texttt{decoupled}:
  numerical models to solve the pressure equation as part of the fractional flow formulation. The specific models are contained 
@@ -61,7 +61,12 @@ and a VTKWriter extension.
 \item \texttt{material}: everything related to material parameters and 
 constitutive equations. The properties of a pure chemical substance (e.g. water) or pseudo substance (e.g. air) can be found in the subdirectory \texttt{components} with the base class \texttt{components/component.hh}. The fluidsytem in the folder \texttt{fluidsystems} collects the information from the respective component and binary coefficients files, and contains the fluid characteristics of phases (e.g. viscosity, density, enthalpy, diffusion coefficients) for compositional or non-compositional multi-phase flow. 
 
-The base class for all spatially dependend variables like permeability and porosity can be found in \texttt{spatialparameters}. The base class in \texttt{boxspatialparameters.hh} also provides spatial averaging routines. All other spatial properties are specified in the specific files of the respective models. Furthermoren, the constitutive relations are in \texttt{fluidmatrixinteractions}, while the necessary binary coefficients like the Henry coefficient or binary diffusion coefficients are definded in \texttt{binarycoefficients}.
+The base class for all spatially dependend variables -- like permeability and porosity  -- 
+can be found in \texttt{spatialparameters}. The base class in \texttt{boxspatialparameters.hh} 
+also provides spatial averaging routines. All other spatial properties are specified in the specific
+ files of the respective models. Furthermore, the constitutive relations -- e.g. $p_c(S_w) $ -- are in \texttt{fluidmatrixinteractions}, 
+while the necessary binary coefficients like the Henry coefficient or binary diffusion coefficients are definded in
+ \texttt{binarycoefficients}.
 
 
 \item \texttt{nonlinear}: Newton's method.

doc/handbook/tutorial-coupled.tex

@@ -32,7 +32,7 @@ water:
 \begin{align}
   \label{massbalancewater}
   \frac {\partial (\phi \, S_{w}\, \varrho_{w})}{\partial t}
-  +
+  -
   \nabla \cdot \left( \varrho_{w} \, \frac{k_{rw}}{\mu_{w}} \, \mathbf{K}\;\nabla p_w \right)
   -
   q_w
@@ -40,7 +40,7 @@ water:
   0 \\
   \label{massbalanceoil}
   \frac {\partial (\phi \, S_{o}\, \varrho_{o})}{\partial t}
-  +
+  -
   \nabla \cdot \left( \varrho_{o} \, \frac{k_{ro}}{\mu_{o}} \, \mathbf{K}\;\nabla p_o \right)
   -
   q_o 
@@ -61,7 +61,7 @@ above.
 \end{lst}
 
 From line \ref{tutorial-coupled:include-begin} to line
-\ref{tutorial-coupled:include-end} the Dune and \Dumux files which
+\ref{tutorial-coupled:include-end} the \Dune and \Dumux files which
 contain the needed functions and classes are included.
 
 At line \ref{tutorial-coupled:set-type-tag} the type tag of the
@@ -73,7 +73,7 @@ single type tag. Retrieving them is done between line
 property system, see section \ref{sec:propertysystem}.
 
 The first thing which should be done at run time is to initialize the
-message passing interface using DUNE's \texttt{MPIHelper} class. Line
+message passing interface using \Dune's \texttt{MPIHelper} class. Line
 \ref{tutorial-coupled:init-mpi} is essential if the simulation is
 intended to be run on more than one processor at the same time. Next,
 the command line arguments are parsed starting at line
@@ -85,7 +85,7 @@ parse the time when the simulation ends and the initial time step size.
 After this, a grid is created in line
 \ref{tutorial-coupled:create-grid} and the problem is instantiated for
 its leaf grid view in line \ref{tutorial-coupled:instantiate-problem}.
-Finally, on line \ref{tutorial-coupled:restart} a state written to
+Finally, on line \ref{tutorial-coupled:begin-restart} a state written to
 disk by a previous simulation run is restored if requested by the user.
 The simulation procedure is started at line
 \ref{tutorial-coupled:execute}.
@@ -109,7 +109,7 @@ which means that for this problem the two-phase box model is chosen as
 discretization scheme. On line \ref{tutorial-coupled:set-problem}, a
 problem class is attached to the new type tag, while the grid which
 is going to be used is defined in line \ref{tutorial-coupled:set-grid} --
-in this case it's \texttt{SGrid}.  Since there's no uniform
+in this case that is  \texttt{SGrid}.  Since there's no uniform
 mechanism to allocate grids in \Dune, the \texttt{Grid} property also contains
 a static \texttt{create()} method which provides just that. Next,
 the appropriate fluid system, that specifies both information about
@@ -173,7 +173,7 @@ assigned with the methods \texttt{dirichlet()} and \texttt{neumann()} which only
 by the first function parameter:
 \begin{description}
  \item[values:] A vector which stores the result of the method. What
-  the values in this vector means is dependent on the method: For
+  the values in this vector mean is dependent on the method: For
   \texttt{dirichlet()} it contains the values of the primary
   variables, for \texttt{neumann()} the mass fluxes per area unit
   over the boundary segment.
@@ -239,15 +239,15 @@ First, a certain material law that best describes the problem at hand has to
 be selected in line \ref{tutorial-coupled:rawlaw}\label{tutorial-coupled:materialLaw}. 
 \Dumux provides several material laws in the folder 
 \verb+dumux/material/fluidmatrixinteractions+.
-The selected one, here it is a relation according to Brooks Corey, is included
+The selected one -- here it is a relation according to a regularized version of Brooks \& Corey --  is included
 in line \ref{tutorial-coupled:rawLawInclude}. After the selection,
-an adapter in line \ref{tutorial-coupled:eff2abs} translates the raw 
-law to effective values (residual saturations are considered). As the
-applied raw law knows best which kind of parameters are necessary,
+an adapter in line \ref{tutorial-coupled:eff2abs} translates between the law
+for effective values (the Brooks \& Corey model) and the saturations generated as simulations results, i.e. residual saturations are considered. 
+As the applied raw law knows best which kind of parameters are necessary,
 it provides a parameter class \texttt{RegularizedBrooksCoreyParams} that is
 accessible via the member \texttt{Params} and defined in line 
 \ref{tutorial-coupled:matLawObjectType}. The material law object 
-could now be instantiated correctly as a private object
+is now instantiated correctly as a private object
 in line \ref{tutorial-coupled:matParamsObject}.
 
 In line \ref{tutorial-coupled:permeability} the function returning the
@@ -259,21 +259,26 @@ about its geometry and position, the second argument
 by the box-method, and the third defines the index of the current sub-control 
 volume. The intrinsic permeability is a tensor and is thus returned in form of
 a $\texttt{dim} \times \texttt{dim}$-matrix where \texttt{dim} is the dimension 
-of the problem.\\
+of the problem. 
+
 The function \texttt{porosity()} defined in line
 \ref{tutorial-coupled:porosity} is called with the same arguments as
 the permeability function described before and returns the porosity
-dependent on the position in the domain.\\
+dependent on the position in the domain.
+
 Next, the method \texttt{materialLawParams()} defines in line 
-\ref{tutorial-coupled:matLawParams} which object of a considered 
-material law should be applied at this specific position. 
-While the selection of the type of this object was already explained (see 
-\ref{tutorial-coupled:materialLaw}), some specific parameter 
+\ref{tutorial-coupled:matLawParams} which \verb+materialLawParams+ object 
+ should be applied at this specific position. Although in this case only one objects is returned, 
+in general the problem may be heterogeneous, demanding for different objects at different positions in space. 
+While the selection of the type of this object was already explained (line \ref{tutorial-coupled:rawLawInclude}),
+ some specific parameter 
 values of the applied material law are still needed. This is 
 done in the constructor body (line \ref{tutorial-coupled:setLawParams}).
 Depending on the type of the \texttt{materialLaw} object, the adequate \texttt{set}-methods
 are provided by the object to access all necessary parameters 
-for the applied material law.
+for the applied material law. The name of the access / set functions as well as the rest of the implementation 
+of the material description can be found in 
+\verb+dumux/dumux/material/fluidmatrixinteractions/2p+.
 
 \subsection{Exercises}
 \label{tutorial-coupled:exercises}
@@ -319,12 +324,13 @@ To get an impression what the results should look like you can first run the ori
   \texttt{/dumux/material/components}.
 
 \item \textbf{Use the \Dumux fluid system} \\
-\Dumux usually organises fluid mixtures via a \texttt{fluidsystem}. In order to include a fluidsystem you first have to uncomment the lines \ref{tutorial-coupled:2p-system-start} to \ref{tutorial-coupled:2p-system-end} in the problem file. If you use eclipse, this can easily be done by pressing \textit{str + shift + 7} -- the same as to cancel the comment later on.\\
+\Dumux usually organises fluid mixtures via a \texttt{fluidsystem}. In order to include a fluidsystem you first have to comment the lines \ref{tutorial-coupled:2p-system-start} to \ref{tutorial-coupled:2p-system-end} in the problem file. If you use eclipse, this can easily be done by pressing \textit{str + shift + 7} -- the same as to cancel the comment later on.\\
 Now include the file \texttt{fluidsystems/h2o\_n2\_system.hh} in the material folder, and set a property \texttt{FluidSystem} with the appropriate type, \texttt{Dumux::H2O\_N2\_System<TypeTag>}. However, the complicated fluidsystem uses tabularized fluid data, which need to be initilized in the constructor body of the current problem by adding \texttt{GET\_PROP\_TYPE(TypeTag, PTAG(FluidSystem))::init();}, hence using the initialization function of the applied fluidsystem. As water flow replacing a gas is much faster, test your simulation only until 2e3 seconds and start with a time step of 1 second.\\
 Please reverse the changes of this example, as we still use bulk phases and hence do not need such an extensive fluid system.
 
 \item \textbf{Changing Constitutive Relations} \\
-  Use an unregularized linear law with an entry pressure of $p_e = 0.0$ and maximal capillary pressure of $p_{c_{max}} = 0.0$ instead of using a regularized Brooks-Corey law for the
+  Use an unregularized linear law with an entry pressure of $p_e = 0.0$ and maximal capillary pressure of e.g. $p_{c_{max}} = 2000.0$ instead of using a
+ regularized Brooks-Corey law for the
   relative permeability and for the capillary pressure saturation relationship. To do that you have
   to change the file \texttt{tutorialspatialparameters\_coupled.hh}. 
  You can find the material laws in the folder 
@@ -372,7 +378,7 @@ property so that it matches the domain described
 by figure \ref{tutorial-coupled:ex2_Domain}. Adapt the problem class
 so that the boundary conditions are consistent with figure
 \ref{tutorial-coupled:ex2_BC}. Initially the domain is fully saturated
-with water and the pressure is $p_w = 5 \times 10^5 \text{Pa}$ . Oil
+with water and the pressure is $p_w = 5 \times 10^5 \text{Pa}$. Oil
 infiltrates from the left side. Create a grid with $20$ cells in
 $x$-direction and $10$ cells in $y$-direction. The simulation time
 should be set to $1\times 10^6 \text{ s}$ with an initial time step size of
@@ -387,11 +393,11 @@ compile the program.
 \psfrag{K1}{K $= 10^{-7}\text{ m}^2$}
 \psfrag{phi1}{$\phi = 0.2$}
 \psfrag{Lin}{Brooks-Corey Law}
-\psfrag{Lin2}{$\lambda = 1.8$, $p_b = 1000$}
+\psfrag{Lin2}{$\lambda = 1.8$, $p_e = 1000$}
 \psfrag{K2}{K $= 10^{-9}\text{ m}^2$}
 \psfrag{phi2}{$\phi = 0.15$}
 \psfrag{BC1}{Brooks-Corey Law} 
-\psfrag{BC2}{$\lambda = 2$, $p_b = 1500$}
+\psfrag{BC2}{$\lambda = 2$, $p_e = 1500$}
 \psfrag{H1y}{50 m}
 \psfrag{H2y}{15 m}
 \psfrag{H3y}{20 m}
@@ -404,7 +410,7 @@ compile the program.
 \end{figure}
 
 \begin{figure}[h]
-\psfrag{pw}{$p_w = 5 \times 10^5$ \text{Pa}}
+\psfrag{pw}{$p_w = 5 \times 10^5$ [\text{Pa}]}
 \psfrag{S}{$S_n = 1.0$}
 \psfrag{qw}{$q_w = 2 \times 10^{-4}$ [kg/$\text{m}^2$s]}
 \psfrag{qo}{$q_n = 0.0$ [kg/$\text{m}^2$s]}

doc/handbook/tutorial-decoupled.tex

@@ -290,7 +290,7 @@ compile the program.
 \end{figure}
 
 \begin{figure}[h]
-\psfrag{pw}{$p_w = 5 \times 10^5$ \text{Pa}}
+\psfrag{pw}{$p_w = 5 \times 10^5$ [\text{Pa}]}
 \psfrag{S}{$S_n = 1.0$}
 \psfrag{qw}{$q_w = 2 \times 10^{-4}$ [kg/$\text{m}^2$s]}
 \psfrag{qo}{$q_n = 0.0$ [kg/$\text{m}^2$s]}