OilfieldToolsNet/opm-simulators
4
0
Fork 0
mirror of https://github.com/OPM/opm-simulators.git synced 2025-02-25 18:55:30 -06:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Andreas Lauser 2010-09-13 17:47:12 +00:00 committed by Andreas Lauser
parent a30ea535c2
commit a0a5b85242
4 changed files with 299 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/handbook/Makefile.am
View File

@ -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

5
doc/handbook/dumux-handbook.tex
View File

@ -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}

66
doc/handbook/intro.tex
View File

@ -1,15 +1,31 @@
\chapter{Introduction}
Since creating, refining and managing grids in general is a very
complex topic which has severe effects on computational efficiency and
for which no generic and efficient approach exists, our simulation
framework 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
grid management libraries such as UG~\cite{UG-HP}, ALBERTA~\cite{ALBERTA-HP},
ALU-Grid~\cite{ALUGRID-HP} and a few more. DUNE extensively uses templates in
order to achieve maximum efficiency to access the actual grid
\Dumux aims to be a generic framework for simulation of multiphase
fluid flow and transport processes in porous media using contiuum
mechanical approaches. At the same time, \Dumux aims to deliver
top-notch computational performance, high flexibility, a sound
software architecture and the ability to run on anything from single
processor systems to highly parallel supercomputers with specialized
hardware architectures.
The means to achieve these somewhat contradictory goals are the
thorough use of object oriented design in conjunction with template
programming. These requirements 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
modules, of which the \texttt{dune-disc} and \texttt{dune-istl} modules are the most
relevant in the context of this handbook. \texttt{dune-disc} provides a toolbox for
discretization and includes a set of generic finite element shape
functions, matrix assemblers for translating local stiffness matrices
into global linear systems of equations and much more. \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.
In addition to the grid interface, DUNE also provides quite a few
additional modules, of which the \texttt{dune-pdelab},
\texttt{dune-localfunctions} and \texttt{dune-istl} modules are the
most relevant in the context of this handbook. \texttt{dune-pdelab}
provides a toolbox for discretization and includes matrix assemblers
for translating local stiffness matrices into a global linear system
of equations and much more, while \texttt{dune-localfunctions}
provides a set of generic finite element shape
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
\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}.
It depends on the DUNE core modules
\texttt{dune-common}, \texttt{dune-grid}, \texttt{dune-istl}, \texttt{dune-localfunctions}, as well as from
the discretization module \texttt{dune-pdelab}.
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.

252
doc/handbook/propertysystem.tex Normal file
View File

@ -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: