Commit d66f594b authored by Christoph Grueninger's avatar Christoph Grueninger
Browse files

[handbook]

Added command \Cplusplus that hurts the eye much less.
Used \Dune instead of Dune in chapter 1.
Added \texttt to some dunecontrol words where it was missing.
Fixed a type.


git-svn-id: svn://svn.iws.uni-stuttgart.de/DUMUX/dumux/trunk@8644 2fb0f335-1f38-0410-981e-8018bf24f1b0
parent 89c1e177
......@@ -65,7 +65,7 @@ be debugged because the debugger gets confused. But the cool thing is, that you
\begin{itemize}
\item open your application's Makefile with the text editor of your choice
\item find the line including \texttt{CXXFLAGS =}
\item these are the options given to the C++ compiler
\item these are the options given to the \Cplusplus compiler
\item add \texttt{-g} (debugging symbols)
\item remove \texttt{-O3} (third level optimization, i.\,e. do not care for anything but execution speed), \texttt{-march=native} and \texttt{-DNDEBUG}.
\item build your application again.
......@@ -73,7 +73,7 @@ be debugged because the debugger gets confused. But the cool thing is, that you
\item compiling without optimization takes also shorter time
\end{itemize}
(The other possibility is to run dunecontrol with \texttt{debug.opts} and afterwards adding \texttt{-O3} into your application Makefile. The performance penalty does not make a big difference and so do the other options besides \texttt{-O3})
(The other possibility is to run \texttt{dunecontrol} with \texttt{debug.opts} and afterwards adding \texttt{-O3} into your application Makefile. The performance penalty does not make a big difference and so do the other options besides \texttt{-O3})
Debugging with the optimization options active will lead to erratic behavior while debugging.
......
......@@ -5,18 +5,18 @@ 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 C++.
with \Cplusplus.
First, a quick motivation of C++ template programming is given. Then
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{C++ Template Programming}
\section{\Cplusplus Template Programming}
One of the main features of modern versions of the C++ 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}
......@@ -40,7 +40,7 @@ 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 C++ programming language specify the template
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]
......@@ -73,20 +73,20 @@ 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 C++ compiler. Thus, diagnostic messages from the compiler are
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 C++ programs which do not use
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 C++ standard and was improved in the C++11 standard.
which is part of the \Cplusplus standard and was improved in the \Cplusplus11 standard.
\section{Polymorphism}
......@@ -99,14 +99,14 @@ 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 C++, there are two common ways to achieve polymorphism: The
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 C++, the polymorphic
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
......@@ -206,7 +206,7 @@ What happens if \dots
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
C++ compilers 'inline' short methods, i.e. they copy the method's body
\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
......@@ -222,7 +222,7 @@ 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 C++
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
......@@ -294,14 +294,14 @@ int main()
\section{Common Template Programming Related Problems}
Although C++ template programming opens a few intriguing
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 C++ templates is that the
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
......@@ -471,8 +471,3 @@ often useful to specify parameters in such a way.
% independent variables. (e.g. the material laws: BrooksCorey
% (function), BrooksCoreyParams (function parameters), wetting
% saturation/fluid state (independent variables)
%%% Local Variables:
%%% mode: latex
%%% TeX-master: "dumux-handbook"
%%% End:
......@@ -45,6 +45,7 @@
\usepackage{makeidx}
\usepackage{graphicx}
\usepackage{xspace}
\usepackage{relsize}
\usepackage[htt]{hyphenat}
\usepackage{lscape}
\usepackage{enumerate}
......@@ -71,8 +72,12 @@
\DeclareGraphicsExtensions{.eps, .jpg}
% Dune logo
\newcommand{\Dune}{{DUNE}\xspace}
% DuMuX logo
\newcommand{\Dumux}{\texorpdfstring{Du\-Mu$^\text{x}$\xspace}{DuMuX}}
% beautify C++
\DeclareRobustCommand\Cplusplus{\texorpdfstring{C\raisebox{2pt}{{\relsize{-3}++}}\xspace}{C++}}
\newcommand{\porosity}{\phi}
\newcommand{\saturation}{S}
......@@ -173,8 +178,3 @@ Universit\"at Stuttgart, Paffenwaldring 61, D-70569 Stuttgart, Germany}\\
\bibliography{dumux-handbook}
\printindex
\end{document}
%%% Local Variables:
%%% mode: latex
%%% TeX-master: "dumux-handbook"
%%% End:
......@@ -35,7 +35,7 @@ The GNU tool chain of \texttt{g++} and the tools of the GNU build system \cite{
(\texttt{autoconf}, \texttt{automake}, \texttt{autogen}, \texttt{libtool}), as well as the GNU variant of \texttt{make}
called gmake must be available in a recent version. For example Ubuntu Linux provides these tools with the
packages \texttt{autoconf}, \texttt{automake}, \texttt{libtool}
and the C++ compiler \texttt{g++} and \texttt{make} are contained in \texttt{build-essential}.
and the \Cplusplus compiler \texttt{g++} and \texttt{make} are contained in \texttt{build-essential}.
At the time of writing this manual, it is expected that \texttt{g++} of version $\geqslant$ 4.5.0, \texttt{automake} of version $\geqslant$ 1.9,
\texttt{autoconf} of version $\geqslant$ 2.65, \texttt{autogen} of version $\geqslant$ 5.9.7, \texttt{libtool} of version $\geqslant$ 2.2.6
......@@ -266,7 +266,7 @@ In the following list, you can find some external modules and external libraries
\begin{itemize}
\item \textbf{ALBERTA}: External library for use as grid. Adaptive multi Level finite element toolbox using Bisectioning refinement and Error control by Residual Techniques for scientific Applications. Building it requires a Fortran compiler \texttt{gfortran}. Download: \texttt{\url{http://www.alberta-fem.de}}.
\item \textbf{ALUGrid}: External library for use as grid. ALUGrid is built by a C++-compiler like \texttt{g++}. If you want to build a parallel version, you will need \texttt{MPI}. It was successfully run with \texttt{openmpi}. The parallel version needs also a graph partitioner, such as \texttt{METIS}. It was run successfully in combination with \Dune using \texttt{METIS}. \\
\item \textbf{ALUGrid}: External library for use as grid. ALUGrid is built by a \Cplusplus compiler like \texttt{g++}. If you want to build a parallel version, you will need \texttt{MPI}. It was successfully run with \texttt{openmpi}. The parallel version needs also a graph partitioner, such as \texttt{METIS}. It was run successfully in combination with \Dune using \texttt{METIS}. \\
Download: \texttt{\url{http://aam.mathematik.uni-freiburg.de/IAM/Research/alugrid}}
\item \textbf{\Dune-multidomaingrid}: External module. If you going to run on the same grid different domains or subdomains,
......@@ -279,7 +279,7 @@ this can be the package of choice. This is done by providing a meta grid. It can
\item \textbf{SuperLU}: External library for solving linear equations. SuperLU is a general purpose library for the direct solution of large, sparse, non-symmetric systems of linear equations. Be aware that the version 4.3 is not supported by \Dune prior to 2.1.0. \\ (\texttt{\url{http://crd.lbl.gov/~xiaoye/SuperLU}}).
\item \textbf{UG}: External library for use as grid. UG is a toolbox for Unstructured Grids: For \Dumux it has to be build by GNU buildsystem and a C++-compiler. That's why \Dune specific patches need applied before use. Building it makes use of the tools \texttt{lex}/\texttt{yacc} or the GNU variants \texttt{flex}/\texttt{bison}.
\item \textbf{UG}: External library for use as grid. UG is a toolbox for Unstructured Grids: For \Dumux it has to be build by GNU buildsystem and a \Cplusplus compiler. That's why \Dune specific patches need applied before use. Building it makes use of the tools \texttt{lex}/\texttt{yacc} or the GNU variants \texttt{flex}/\texttt{bison}.
\end{itemize}
......@@ -297,7 +297,7 @@ Available by \texttt{\url{http://www.tacc.utexas.edu/tacc-projects/gotoblas2/}}.
\item \textbf{METIS}: This is a dependency of ALUGrid, if you are going to run it parallel.
\item \textbf{Compilers}: Beside \texttt{g++} it has been reported that \Dune was successfully built with CLang++ from the LLVM project and the Intel C++ compiler.
\item \textbf{Compilers}: Beside \texttt{g++} it has been reported that \Dune was successfully built with \texttt{Clang++} from the LLVM project and the Intel \Cplusplus compiler.
C and Fortran compiler is needed for some external libraries. As code of different compilers is linked together they have to be be compatible with each other. A good choice is the GNU compiler suite \texttt{gcc}, \texttt{g++} and \texttt{gfortran}.
\item \textbf{libgomp}: External libraries, such as ALUGrid, can make use of OpenMP when used together with METIS. For that purpose it can be necessary to install the \texttt{libgomp} library.
......
\chapter{Introduction}
\Dumux aims to be a generic framework for the simulation of multiphase
fluid flow and transport processes in porous media using contiuum
fluid flow and transport processes in porous media using continuum
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
......@@ -10,28 +10,27 @@ 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 call for C++ as the implementation
programming. These requirements call for \Cplusplus 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
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
\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}, ALUGrid~\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}
\caption{
\label{fig:dune-design}
A high-level overview of DUNE's design is available on the project's
A high-level overview of \Dune's design is available on the project's
web site~\cite{DUNE-HP}.
}
\end{figure}
......@@ -41,7 +40,7 @@ underlying grid. For this purpose, it uses the concept of
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
which are the cell's vertices. The \Dune grid interface generally
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 the sake of efficiency, all entities are further expressed in terms
......@@ -52,10 +51,10 @@ entity can be thought of as a prototype for the actual grid
entity. For example, if we used a grid which applied 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
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
In addition to the grid interface, \Dune also provides quite a few
additional modules, of which the \texttt{dune-localfunctions} and
\texttt{dune-istl} modules are the most relevant in the context of
this handbook. \texttt{dune-localfunctions} provides a set of generic
......@@ -74,7 +73,3 @@ spatial and temporal discretization schemes as well as nonlinear solvers,
to general concepts for model coupling.
Moreover, \Dumux includes ready to use numerical models and a few example applications.
%%% Local Variables:
%%% mode: latex
%%% TeX-master: "dumux-handbook"
%%% End:
......@@ -160,7 +160,7 @@ UNSET_PROP(DerivedTypeTag, TestProp);
\subsection*{Converting Tag Names to Tag Types}
For the C++ compiler, property and type tags are like ordinary
For the \Cplusplus compiler, property and type tags are like ordinary
types. Both can thus be used as template arguments. To convert a
property tag name or a type tag name into the corrosponding type, the
macros \texttt{TTAG(TypeTagName)} and \texttt{PTAG(PropertyTagName)}
......
......@@ -28,14 +28,14 @@ but also try to include error details.
It is possible to compile \Dumux with nearly no explicit options to the build system.
However, for the successful compilation of \Dune and \Dumux, it is currently necessary to pass the
the option \texttt{-fno-strict-aliasing} to the C++-compiler
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
\end{lstlisting}
Too many options can make life hard. That's why usually option files are being used together with dunecontrol and its sub-tools.
Too many options can make life hard. That's why usually option files are being used together with \texttt{dunecontrol} and its sub-tools.
Larger sets of options are kept in them. If you are going to compile with options suited for debugging the code, the following
can be a starting point:
\begin{lstlisting}[style=Bash]
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment