handbook finished

doc/handbook/dumux-handbook.bib

@@ -50,6 +50,12 @@
 
 }
 
+@misc{dumux-hp,
+	key = {Dumux},
+	title = {The {D}umux homepage: \url{http://www.dumux.uni-stuttgart.de}},
+
+}
+
 @misc{UG-HP,
 	key = {UG},
 	title = {The {UG} Homepage: \url{http://sit.iwr.uni-heidelberg.de/~ug/}},
@@ -717,6 +723,13 @@ keywords = {Unsymmetric linear systems}
   note = 	 {CS-93-56}
 }
 
+@TechReport{subgrid,
+  author = 	 {C. Gr\"aser and O. Sander},
+  title = 	 {The dune-subgrid Module and Some Applications},
+  year = 	 {2009},
+  note = 	 {Matheon 566}
+}
+
 @PhdThesis{A3:bielinski:2006,
   author = 	 {Bielinski, A.},
   title = 	 {Numerical Simulation of CO$_2$ Sequestration in

doc/handbook/getting-started.tex

@@ -2,8 +2,7 @@
 
 We first describe the steps which are necessary for installing DuMu$^\text{x}$ 
 and then provide a quick start guide for the first DuMu$^\text{x}$ experience. 
-We conclude this chapter with general guidelines for coding your own 
-DuMu$^\text{x}$ application. 
+We conclude this chapter with a copy of the DUNE coding guidelines. 
 
 \input{install}
 \input{quickstart-guide}

doc/handbook/guidelines.tex

@@ -1,6 +1,7 @@
 \section{Guidelines} 
 
-This section mainly quotes the DUNE coding guidelines found at \cite{DUNE-HP}.
+This section quotes the DUNE coding guidelines found at \cite{DUNE-HP}. 
+These guidelines also should be followed by every \Dumux 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.

doc/handbook/install.tex

@@ -5,19 +5,30 @@ For the installation of DuMu$^\text{x}$, the following steps have to be performe
 \paragraph{Checkout of the core modules}
 Since we always want to be up to date with the latest changes in DUNE, 
 we decided to use the developers version of the core modules 
-\texttt{dune-common}, \texttt{dune-grid}, \texttt{dune-istl}, \texttt{dune-disc}, 
-and \texttt{dune-grid-howto}. First, create a directory where all the DUNE modules will be stored in. Then, enter the previously created folder. The checkout has to be performed as described on 
+\texttt{dune-common}, \texttt{dune-grid}, \texttt{dune-istl}, and \texttt{dune-disc}.  
+First, create a directory where all the DUNE modules will be stored in. Then, enter the previously created folder. 
+The checkout has to be performed as described on 
 the DUNE webpage, \cite{DUNE-HP}: 
 \begin{itemize}
 \item \texttt{svn checkout https://svn.dune-project.org/svn/dune-common/trunk dune-common}
 \item \texttt{svn checkout https://svn.dune-project.org/svn/dune-grid/trunk dune-grid}
 \item \texttt{svn checkout https://svn.dune-project.org/svn/dune-istl/trunk dune-istl}
 \item \texttt{svn checkout https://svn.dune-project.org/svn/dune-disc/trunk dune-disc}
-\item \texttt{svn checkout https://svn.dune-project.org/svn/dune-grid-howto/trunk dune-grid-howto}
 \end{itemize} 
+The \Dumux webpage \cite{dumux-hp} contains the revision numbers of the core modules 
+for which compatibility to \Dumux can be guaranteed. 
+
+Additionally, it is highly recommended that you also checkout the \texttt{dune-grid} HOWTO 
+by 
+\begin{center}
+\texttt{svn checkout https://svn.dune-project.org/svn/dune-grid-howto/trunk dune-grid-howto}
+\end{center}
+and work yourself through that tutorial in order to get an understanding of 
+the Dune grid interface. 
 
 \paragraph{Checkout of DuMu$^\text{x}$ and external modules} 
-
+If you obtained a \Dumux tarball, you should just extract the tarball as usual 
+and can skip this part. 
 First of all, you need to ask one of the IWS system administrators to 
 add your account to the group \texttt{svndune}. 
 If you are working on a LH2 computer, you then can checkout DuMu$^\text{x}$ 
@@ -34,7 +45,7 @@ To this end, you need to add once
 \end{center}
 with \texttt{login} replaced 
 by your actual IWS login name, to the section \texttt{[tunnels]} of the 
-file \texttt{\$HOME/.subversion/config}, 
+file \texttt{\$HOME/} \texttt{.subversion/config}, 
 The tunnel then needs to be initialized every time you want 
 to connect to the repository by 
 \begin{center}
@@ -51,12 +62,14 @@ by \texttt{localhost}.
 %\end{itemize} 
 
 \paragraph{Build the external modules} 
-The external modules have to be built first. They consist of Alberta, ALUGrid, UG, GotoBLAS and METIS.
+If you obtained a \Dumux tarball, you should skip this part. 
+The external modules have to be built first. They consist of Alberta, ALUGrid, UG, and METIS.
 To install them all, execute the install script in the folder \texttt{external}:
 \begin{center}
 \texttt{./installExternal.sh all}
 \end{center}
-If you like to only install some of the external software, you can choose one of the corresponding options instead of \texttt{all}: \texttt{alberta, alu, blas, metis, ug}.
+If you like to only install some of the external software, you can choose one of the 
+corresponding options instead of \texttt{all}: \texttt{alberta, alu, metis, ug}.
 Please also refer to the DUNE webpage for additional details, \cite{DUNE-HP}. 
 
 \paragraph{Build DUNE and DuMu$^\text{x}$}
@@ -64,4 +77,9 @@ Type in the folder \texttt{DUMUX}:
 \begin{center}
 \texttt{./dune-common/bin/dunecontrol --opts=dune-mux/debug.opts all}
 \end{center}
-
+This uses the DUNE buildsystem. If it does not work, please 
+consider the file \texttt{INSTALL} in the directory \texttt{dune-mux}. You can also find more information 
+in the DUNE Buildsystem HOWTO located at the DUNE webpage, \cite{DUNE-HP}. 
+Alternatively, the tool Cmake can 
+be used to build \Dumux. Please check the file 
+\texttt{INSTALL.cmake} for details. 

doc/handbook/intro.tex

@@ -26,7 +26,7 @@ co-dimensional entities. Roughly speaking, an entity of co-dimension
 $0$ constitutes a cell, co-dimension $1$ entities are faces between
 cells, co-dimension $1$ are edges, and so on until co-dimension $n$
 which are the cell's vertices.  The DUNE grid interface generally
-assumes, that all entities are convex polytopes, which means that it
+assumes that all entities are convex polytopes, which means that it
 must be possible to express each entity as the convex hull of a set of
 vertices. For efficiency, all entities are further expressed in terms
 of so-called reference elements which are transformed to the actual
@@ -50,12 +50,15 @@ into global linear systems of equations and much more. \texttt{dune-istl} is the
 and provides generic, highly optimized linear algebra routines for solving
 the generated systems. 
 
-DuMu$^\text{x}$ comes in form of an additional module \texttt{dune-mux}. 
-It inherits functionality from all available DUNE modules. 
-Its main intention is to provide a framework for easy and efficient 
+\Dumux comes in form of an additional module \texttt{dune-mux}. 
+It inherits functionality from the DUNE core modules 
+\texttt{dune-common}, \texttt{dune-grid}, and \texttt{dune-istl}, as well as from 
+the discretization module \texttt{dune-disc}. Some numerical models 
+also depend on the \texttt{dune-subgrid} module, \cite{subgrid}. 
+The main intention of \Dumux is to provide a framework for easy and efficient 
 implementation of models from porous media flow problems, 
 ranging from problem formulation, the selection of 
 spatial and temporal discretization schemes, as well as nonlinear solvers,  
 up to general concepts for model coupling.  
-Moreover, DuMu$^\text{x}$ includes ready to use numerical models and example applications. 
+Moreover, \Dumux includes ready to use numerical models and example applications. 
 

doc/handbook/models.tex

@@ -49,7 +49,7 @@ $p_\alpha$ & phase pressure & $\phi$ & porosity \\
 $T$ & temperature & $K$ & absolute permeability tensor \\
 $S_\alpha$ & phase saturation & $\tau$ & tortuosity \\
 $x_\alpha^\kappa$ & mole fraction of component $\kappa$ in phase $\alpha$ & $\boldsymbol{g}$ & gravitational acceleration \\
-$X_\alpha^\kappa$ & mass fraction of component $\kappa$ in phase $\alpha$ & $q^\kappa_\alpha$ & volume source term of component $\kappa$ in phase $\alpha$ \\
+$X_\alpha^\kappa$ & mass fraction of component $\kappa$ in phase $\alpha$ & $q^\kappa_\alpha$ & volume source term of $\kappa$ in $\alpha$ \\
 $\varrho_{\text{mol},\alpha}$ & molar density of phase $\alpha$ & $u_\alpha$ & specific internal energy \\
 $\varrho_{\alpha}$ & mass density of phase $\alpha$ & $h_\alpha$ & specific enthalpy \\
 $k_{\text{r}\alpha}$ & relative permeability & $c_\text{s}$ & specific heat enthalpy \\
@@ -88,7 +88,7 @@ by replacing molar densities by mass densities and mole by mass fractions.
 To obtain a single conserved quantity in the temporal derivative, the total 
 concentration, representing the mass of one component per unit volume, is defined as
 \begin{displaymath}
-C_\alpha^\kappa = \phi S_\alpha \varrho_{\text{mass},\alpha} X_\alpha^\kappa \; .
+C^\kappa = \sum_\alpha \phi S_\alpha \varrho_{\text{mass},\alpha} X_\alpha^\kappa \; .
 \end{displaymath}
 Using this definition, the component mass balance is written as:
 
@@ -136,7 +136,7 @@ formulated as:
 In order to close the system, supplementary constraints for capillary pressure, saturations and mole
 fractions are needed, \cite{A3:helmig:1997}. 
 According to the Gibbsian phase rule, the number of degrees of freedom
-in a non-isothermal multiphase multicomponent system is equal to the
+in a non-isothermal compositional multiphase system is equal to the
 number of components plus one. This means we need as many independent
 unknowns in the system description. The
 available primary variables are, e.\ g., saturations, mole/mass
@@ -146,6 +146,8 @@ fractions, temperature, pressures, etc.
 
 
 \section{Available models} 
+The following description of the available models is automatically extracted 
+from the Doxygen documentation. \textbf{TODO}: Unify notation. 
 
 \subsection{Fully coupled models} 
 

doc/handbook/quickstart-guide.tex

@@ -3,10 +3,10 @@
 The previous chapter 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.
 
 \begin{enumerate}
- \item Go to the directory \texttt{dune-mux/test}. There, various test application folders can be found. Let us consider as example \texttt{test{\_}twophase}:
- \item Enter the folder \texttt{twophase}. If everyting was compiled correctly, there should be an executable \texttt{test{\_}twophase}. In order to run the simulation, type\\ 
-\texttt{./test{\_}twophase 1e4 100}\\
-into the console. The parameters that are used here are the end time of the simulation and the initial timestep. The parameters that are required when calling the application are specified in the application file (here: test{\_}twophase.cc).
+ \item Go to the directory \texttt{dune-mux/test}. There, various test application folders can be found. Let us consider as example \texttt{test{\_}2p}:
+ \item Enter the folder \texttt{2p}. If everyting was compiled correctly, there should be an executable \texttt{test{\_}2p}. In order to run the simulation, type\\ 
+\texttt{./test{\_}2p 1e4 1e2}\\
+into the console. The parameters that are used here are the end time of the simulation and the initial timestep size. The parameters that are required when calling the application are specified in the application file (here: test{\_}2p.cc).
  \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 previously installed 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}

doc/handbook/structure.tex

@@ -99,5 +99,16 @@ directory. Moreover, the compositional decoupled models are included here.
 \section{The directory \texttt{test}}\label{sec:test}
 
 
-
+The directory \texttt{test} contains a test for each numerical model and for 
+the property system. The subfolders \texttt{1p},  \texttt{1p2c},  \texttt{2p},  \texttt{2p2c},  
+\texttt{2p2cni},  \texttt{2pni},  and \texttt{richards} contain tests for the fully 
+coupled models, while \texttt{diffusion}, \texttt{fractionalflow}, and \texttt{transport} 
+correspond to the decoupled models. Each subdirectory 
+contains one or more program files \texttt{test\_*.cc}, where \texttt{*} usually is the 
+name of the folder. Moreover, the problem definitions can be found 
+in the \texttt{*problem.hh} files. Simply executing the tests should either run the 
+full test or give a list of required command line arguments. After test execution, 
+VTK output files should have been generated. 
+For more detailed descriptions of the tests, the problem definitions and their corresponding 
+Doxygen documentation should be considered. 
 

doc/handbook/tutorial-coupled.tex

@@ -1,4 +1,3 @@
-\clearpage
 \section[Fully-coupled model]{Solving a problem using a Fully-Coupled Model}\label{tutorial-coupled}
 
 The process of solving a problem using \Dumux can be roughly divided into four parts:
@@ -9,7 +8,7 @@ The process of solving a problem using \Dumux can be roughly divided into four p
  \item A suitable model has to be chosen.
 \end{enumerate}
 
-The problem that is solved in this tutorial is illustrated in figure \ref{tutorial-coupled:problemfigure}. A rectangular domain with no flow boundaries on the top and on the bottom, which is initially saturated with oil, is considered. Water infiltrates from the left side into the domain. Gravity effects as well as capillarity effects are neglected.
+The problem that is solved in this tutorial is illustrated in Figure \ref{tutorial-coupled:problemfigure}. A rectangular domain with no flow boundaries on the top and on the bottom, which is initially saturated with oil, is considered. Water infiltrates from the left side into the domain. Gravity effects as well as capillarity effects are neglected.
 
 \begin{figure}[h]
 \psfrag{x}{x}
@@ -110,7 +109,7 @@ tag inherits all properties defined for the \texttt{BoxTwoP} type tag,
 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
-going to be used is defined on line \ref{tutorial-coupled:set-grid} --
+is going to be used is defined on line \ref{tutorial-coupled:set-grid} --
 in this case it's \texttt{SGrid}.  Since in Dune, there's no uniform
 mechanism to allocate grids, the \texttt{Grid} property also contains
 a static \texttt{create()} method which provides just that. Next,
@@ -148,9 +147,9 @@ six parameters:
 \item[values:] A vector which stores the result of the method. What
   the values in this vector means is dependent on the method: For
   \texttt{dirichlet()} it contains the values of the primary
-  variables, for \texttt{neumann()} it the mass fluxes per area unit
-  over the boundary segment, and for \texttt{boundaryTypes()} it
-  contains the type of boundary condition which should be used for
+  variables, for \texttt{neumann()} the mass fluxes per area unit
+  over the boundary segment, and for \texttt{boundaryTypes()} 
+  the type of boundary condition which should be used for
   each equation (either \texttt{Dune::BoundaryConditions::dirichlet} or
   \texttt{Dune::BoundaryConditions::neumann}).
 \item[element:] The element of the grid where the boundary segment
@@ -171,8 +170,8 @@ specify properties of sub-control volumes and thus only get
 \texttt{scvIdx} as parameters.
 
 In addition to these five methods, there might be some model-specific
-methods. If the isothermal two-phase model is used, a
-\texttt{temperature()} method which returns the temperature in Kelvin
+methods. If the isothermal two-phase model is used, this includes 
+for example a \texttt{temperature()} method which returns the temperature in Kelvin
 of the fluids and the rock matrix in the domain. This temperature is
 then used by the model to calculate fluid properties which possibly
 depend on it, e.g. density.
@@ -239,12 +238,12 @@ numberstyle=\tiny, numbersep=5pt, firstline=16]{../../tutorial/tutorialsoil_coup
 In line \ref{tutorial-coupled:permeability} the function returning the
 intrinsic permeability can be found. As can be seen, the function has
 to be called with three different arguments. The first one
-(\texttt{x}) is a vector including the global coordinates of the
+(\texttt{globalPos}) is a vector including the global coordinates of the
 current entity (can be an element, vertex, etc.), the second one
-(\texttt{e}) is the entity itself and the third one is a vector
-including the local coordinates of the current entity. The intrinsic
-permeability is a tensor and thus returned in form of a $n \times
-n$-matrix where $n$ is the dimension of the problem.
+(\texttt{element}) is the current element itself and the third one is a vector
+including the local coordinates of the current entity within the element. The intrinsic
+permeability is a tensor and thus returned in form of a $\texttt{dim} \times
+\texttt{dim}$-matrix where \texttt{dim} is the dimension of the problem.
 
 The function \texttt{porosity()} defined in line
 \ref{tutorial-coupled:porosity} is called with the same arguments as
@@ -366,12 +365,12 @@ problem file.
 After this, change the \texttt{create()} method of the \texttt{Grid}
 property and your soil class, so that it matches the domain described
 by figure \ref{tutorial-coupled:ex2_Domain}. Adapt the problem class
-so the boundary conditions are consistent with figure
+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
 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 $4\times 10^7 \text{s}$ with an inital time step of
+should be set to $4\times 10^7 \text{s}$ with an inital time step size of
 $100 \text{s}$.
 
 Now include your new problem file in the main file and replace the
@@ -419,9 +418,6 @@ hint by looking at existing fluid classes in the directory
 \texttt{/dumux/material/fluids}.)
 
 Use benzene as a new fluid and run the model of Exercise 2 with water
-and benzene. Benzene has the following properties:
-\begin{description}
-  \item[density:] $889.51 \, \text{kg} / \text{m}^3$
-  \item[viscosity:] $0.00112 \, \text{Pa} \; \text{s}$
-\end{description}
+and benzene. Benzene has a density of $889.51 \, \text{kg} / \text{m}^3$
+and a viscosity of $0.00112 \, \text{Pa} \; \text{s}$. 
 

doc/handbook/tutorial-decoupled.tex

@@ -1,4 +1,3 @@
-\clearpage
 \section[Decoupled model]{Solving a problem using a Decoupled Model}\label{tutorial-decoupled}
 
 The process of solving a problem using \Dumux can be roughly divided into four parts: 

doc/handbook/tutorial.tex

@@ -1,10 +1,10 @@
 \chapter[Tutorial]{Tutorial}\label{chp:tutorial}
 
-In \Dumux two sorts of models are implemented: Fully coupled models, and decoupled models. In the fully coupled models a flow system is described by a system of strongly coupled equations which can be mass balance equations, balance equations of components, energy balance equations, etc. In contrast a decoupled model consists of a pressure equation which is decoupled or only weakly coupled to a saturation equation, concentration equations, energy balance equations, etc.
+In \Dumux two sorts of models are implemented: Fully coupled models and decoupled models. In the fully coupled models a flow system is described by a system of strongly coupled equations which can be mass balance equations, balance equations of components, energy balance equations, etc. In contrast a decoupled model consists of a pressure equation which is iteratively coupled to a saturation equation, concentration equations, energy balance equations, etc.
 
-Different kinds of both coupled and decoupled models can be isothermal two phase models, isothemal two phase two component models, non-isothermal twophase model, non-isothermal two phase two component models, etc.
+Different kinds of both coupled and decoupled models can be isothermal two phase models, isothermal two phase two component models, non-isothermal twophase model, non-isothermal two phase two component models, etc.
 
 The following two sections of the tutorial demonstrate how to solve problems first using a coupled model (section \ref{tutorial-coupled}) and second using a decoupled model (section \ref{tutorial-decoupled}). Being the easiest case, a isothermal two phase system (two fluid phases, one solid phase) will be considered.
 \input{tutorial-coupled}
 \input{tutorial-decoupled}
-\input{tutorial-newmodel}
+%\input{tutorial-newmodel}