handbook: Some work on the intro, start of chapter about the property system

doc/handbook/Makefile.am

@@ -4,7 +4,7 @@ if BUILD_HANDBOOK
 
 #EPS_FILES = EPS/tutorial-problemconfiguration.eps 
 
-DOCSOURCE = dumux-handbook.tex intro.tex navigation.html css.html
+DOCSOURCE = dumux-handbook.tex intro.tex propertysystem.tex navigation.html css.html
 
 MAINDOCS = dumux-handbook.dvi dumux-handbook.pdf dumux-handbook.ps
 

doc/handbook/dumux-handbook.tex

@@ -13,6 +13,7 @@
 \usepackage{psfrag}
 \usepackage{makeidx}
 \usepackage{graphicx}
+\usepackage{xspace}
 \usepackage[htt]{hyphenat}
 \usepackage{color}
 \usepackage{lscape}
@@ -22,7 +23,7 @@
 \DeclareGraphicsExtensions{.eps, .jpg}
 
 \newcommand{\Dune}{{\sf\bfseries DUNE}}
-\newcommand{\Dumux}{DuMu$^\text{x}$ }
+\newcommand{\Dumux}{DuMu$^\text{x}$\xspace}
 \newcommand{\doxyref}[3]{\textnormal{#1}}
 \newenvironment{CompactList}
 {\begin{list}{}{
@@ -57,6 +58,7 @@
 \theorembodyfont{\upshape}
 \theoremheaderfont{\sffamily\bfseries}
 \newtheorem{exc}{Exercise}[chapter]
+\newtheorem{example}[exc]{Example}
 \newtheorem{rem}[exc]{Remark}
 \newtheorem{lst}{Listing}
 \newtheorem{warn}[exc]{Warning}
@@ -103,6 +105,7 @@ Universit\"at Stuttgart, Paffenwaldring 61, D-70569 Stuttgart, Germany}\\
 
 \input{intro}
 \input{getting-started}
+\input{propertysystem}
 \input{tutorial}
 \input{structure}
 \input{models}

doc/handbook/intro.tex

@@ -1,15 +1,31 @@
 \chapter{Introduction}
 
-Since creating, refining and managing grids in general is a very
+\Dumux aims to be a generic framework for simulation of multiphase
-complex topic which has severe effects on computational efficiency and
+fluid flow and transport processes in porous media using contiuum
-for which no generic and efficient approach exists, our simulation
+mechanical approaches.  At the same time, \Dumux aims to deliver
-framework is build on top of DUNE, the \textbf{D}istributed and \textbf{U}nified
+top-notch computational performance, high flexibility, a sound
-\textbf{N}umerics \textbf{E}nvironment~\cite{DUNE-HP}. DUNE provides a generic interface to many
+software architecture and the ability to run on anything from single
-grid management libraries such as UG~\cite{UG-HP}, ALBERTA~\cite{ALBERTA-HP},
+processor systems to highly parallel supercomputers with specialized
-ALU-Grid~\cite{ALUGRID-HP} and a few more. DUNE extensively uses templates in
+hardware architectures.
-order to achieve maximum efficiency to access the actual grid
+
+The means to achieve these somewhat contradictory goals are the
+thorough use of object oriented design in conjunction with template
+programming. These requirements lead to C++ as the implementation
+language.
+
+One of the more complex issues when dealing with parallel continuum
+models is managing the grids used for the spatial discretization of
+the physical model. To date, no generic and efficient approach exists
+for all possible cases, so \Dumux is build on top of DUNE, the
+\textbf{D}istributed and \textbf{U}nified \textbf{N}umerics
+\textbf{E}nvironment~\cite{DUNE-HP}. DUNE provides a generic interface
+to many existing grid management libraries such as UG~\cite{UG-HP},
+ALBERTA~\cite{ALBERTA-HP}, ALU-Grid~\cite{ALUGRID-HP} and a few
+more. DUNE also extensively uses template programming in order to
+achieve minimal overhead when accessing the underlying grid
 libraries\footnote{In fact, the performance penalty resulting from the
-  use of DUNE's grid interface is usually negligible~\cite{BURRI2006}.}.
+  use of DUNE's grid interface is usually
+  negligible~\cite{BURRI2006}.}.
 \begin{figure}[hbt]
   \centering 
   \includegraphics[width=.5\linewidth, keepaspectratio]{EPS/dunedesign}
@@ -40,25 +56,27 @@ 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
 grid definition, see~\cite{BASTIAN2008}.
 
-In addition to the grid interface, DUNE also provides quite a few additional
+In addition to the grid interface, DUNE also provides quite a few
-modules, of which the \texttt{dune-disc} and \texttt{dune-istl} modules are the most
+additional modules, of which the \texttt{dune-pdelab},
-relevant in the context of this handbook.  \texttt{dune-disc} provides a toolbox for
+\texttt{dune-localfunctions} and \texttt{dune-istl} modules are the
-discretization and includes a set of generic finite element shape
+most relevant in the context of this handbook.  \texttt{dune-pdelab}
-functions, matrix assemblers for translating local stiffness matrices
+provides a toolbox for discretization and includes matrix assemblers
-into global linear systems of equations and much more. \texttt{dune-istl} is the
+for translating local stiffness matrices into a global linear system
-\textbf{I}terative \textbf{S}olver \textbf{T}emplate \textbf{L}ibrary
+of equations and much more, while \texttt{dune-localfunctions}
-and provides generic, highly optimized linear algebra routines for solving
+provides a set of generic finite element shape
-the generated systems. 
+functions. \texttt{dune-istl} is the \textbf{I}terative
+\textbf{S}olver \textbf{T}emplate \textbf{L}ibrary and provides
+generic, highly optimized linear algebra routines for solving the
+generated systems.
 
 \Dumux comes in form of an additional module \texttt{dumux}. 
-It inherits functionality from the DUNE core modules 
+It depends on the DUNE core modules 
-\texttt{dune-common}, \texttt{dune-grid}, and \texttt{dune-istl}, as well as from 
+\texttt{dune-common}, \texttt{dune-grid}, \texttt{dune-istl}, \texttt{dune-localfunctions}, as well as from 
-the discretization module \texttt{dune-disc}. Some numerical models 
+the discretization module \texttt{dune-pdelab}. 
-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, 
+implementation of new physical models for 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, \Dumux includes ready to use numerical models and example applications. 
+Moreover, \Dumux includes ready to use numerical models and a few example applications. 
 

doc/handbook/propertysystem.tex

@@ -0,0 +1,252 @@
+\chapter{The \Dumux Property System}
+\label{sec:propertysytem}
+
+This chapter tries to give high-level understanding of the motivation
+for the \Dumux property system and how to use it. First, an
+introduction to polymorphism is given. After this, the fundamental
+motivation and the ideas behind the \Dumux property system are
+highlighted and the implementation is outlined from a high-level
+perspective. The chapter concludes with a simple example of how to use
+the \Dumux property system.
+
+\section{Polymorphism}
+
+In object oriented programming, it often happens that some
+functionality make sense for all classes in a hierarchy, but what
+actually need to be \textit{done} can be quite different. This
+observation gives rise to \textit{polymorphism}. In polymorphism, a
+call to an object's method \textit{means} the same thing, but how this
+method is \textit{implemented} is case specific\footnote{This
+  \textit{poly} of polymorphism: There are multiple ways to achieve
+  the same goal.}.
+
+In C++, there are two common approaches to polymorphism: The
+traditional -- i.e. non-template programming -- dynamic polymorphism,
+and static polymorphism which is made possible by template
+programming.
+
+\subsection*{Dynamic Polymorphism}
+
+To utilize \textit{dynamic polymorphism} in C++, 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 virtual. If such a method is called
+on an object, the compiler generates code which retrieves the method's
+address from the object's \texttt{vtable} and then calls it. This
+explains why this mechanism is called \textbf{dynamic} polymorphism:
+the methods which are actually called are dynamically determined at
+run time.
+
+\begin{example}
+  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 overwritten by the
+  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 which tells the compiler that this method must
+  mandatorily be specified by all 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
+  need to be polymorphic.
+\begin{verbatim}
+// the base class
+class Car
+{public:
+  virtual double gasUsage() 
+  { return 4.5; };
+  virtual double fuelTankSize() = 0;
+  
+  double range(double fuelTankFillLevel) 
+  { return 100*fuelTankFillLevel*fuelTankSize()/gasUsage(); }
+}
+\end{verbatim}
+
+  Actual car models can now derived from the base class:
+\begin{verbatim}
+// 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{verbatim}
+
+The \text{range} method called on the base class yields correct result
+for any car type:
+\begin{verbatim}
+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);
+   return 0;
+}
+\end{verbatim}
+
+For both types of cars, \texttt{Lupo} and \texttt{S} the
+\texttt{printMaxRange} function works as expected, yielding
+$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}
+
+
+
+
+%  can be written by specifying types as
+% template parameters
+%   \item For complex software, the number of template arguments can get
+%     quite large
+%   \item If an additional template argument is required for a base
+%     class template, all derived classes must also be adapted
+%   \end{itemize}
+% \end{frame}
+
+% \begin{frame}
+%   \frametitle{Dynamic Polymorphism}
+
+%   If a class wants to make a callback to a derived class, the
+%   repective method can be declared {\tt virtual}. This has drawbacks:
+%   \begin{itemize}
+%   \item Overhead due to indirect function call
+%   \item No way for the compiler to inline the method
+%   \end{itemize}
+% \end{frame}
+
+% \begin{frame}[fragile]
+%   \frametitle{Static Polymorphism}
+
+%   Static polymorphism can be used if the type of the derived class is
+%   known at compile time:
+%   \begin{itemize}
+%   \item Additional template parameter {\tt Implementation} for the base class:
+% {\scriptsize
+% \begin{verbatim}
+% template <class Implementation>
+% class Base;
+% \end{verbatim}
+% }
+% \item A static cast to {\tt Implementation} is done before each call-back:
+% {\scriptsize
+% \begin{verbatim}
+% static_cast<Implementation*>(this)->callToImplementation();
+% \end{verbatim}
+% }
+%   \item Derived classes are specified like this:
+% {\scriptsize
+% \begin{verbatim}
+% class Derived : public Base<Derived> {};
+% \end{verbatim}
+% }
+% \end{itemize}
+
+% \end{frame}
+
+% \begin{frame}[fragile]
+%   \frametitle{Nested template arguments}
+
+%   One problem of static Polymorphism: 
+%   \begin{itemize}
+%   \item Template arguments often also require template parameters
+%   \item ``Implementation'' arguments are especially nasty:
+%     \begin{itemize}
+%     \item Assume a base class Base<A, B, Imp>
+%     \item Assume a class Derived<B> and that A is C< Derived<B> >
+%     \item To specify Derived:
+%     \end{itemize}
+%   \end{itemize}
+% {\scriptsize
+% \begin{verbatim}
+%     template <class B>
+%     class Derived : public Base< C<Derived<B> >, B, Derived<B> >
+% \end{verbatim}
+% }
+% \end{frame}
+
+% \begin{frame}[fragile]
+%   \frametitle{A real-world example}
+
+% {\scriptsize
+% \begin{verbatim}
+% template<class ProblemT, class BoxTraitsT, class TwoPTwoCTraitsT>
+% class TwoPTwoCBoxJacobian
+%   : public TwoPTwoCBoxJacobianBase<
+%               ProblemT, 
+%               BoxTraitsT,
+%               TwoPTwoCTraitsT,
+%               TwoPTwoCElementData<TwoPTwoCTraitsT,ProblemT>,
+%               TwoPTwoCVertexData<TwoPTwoCTraitsT,ProblemT>,
+%               TwoPTwoCFluxData<TwoPTwoCTraitsT,
+%                                ProblemT,
+%                                TwoPTwoCVertexData<TwoPTwoCTraitsT,
+%                                                   ProblemT> >,
+%               TwoPTwoCBoxJacobian<ProblemT,
+%                                   BoxTraitsT,
+%                                   TwoPTwoCTraitsT> >
+% {
+% // ...
+% }
+% \end{verbatim}
+% }
+% \end{frame}
+
+% \begin{frame}[fragile]
+%   \frametitle{Traits}
+  
+%   A possible solution is to specify a class which specifies the
+%   template parameters as type definitions (often called a Traits
+%   class): {\scriptsize
+% \begin{verbatim}
+% class Traits
+% { public:
+%   typedef int A;
+%   typedef C<A> B;
+% };
+
+% template <class Traits, class Implementation>
+% class Base {};
+
+% template <class Traits>
+% class Derived : public class Base<Traits, Derived<Traits>
+% {};
+% \end{verbatim}
+% }
+
+
+
+%%% Local Variables: 
+%%% mode: latex
+%%% TeX-master: "dumux-handbook"
+%%% End: