mirror of
https://github.com/OPM/opm-simulators.git
synced 2024-12-23 07:53:29 -06:00
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.
Cherry picked from Dumux SVN trunk (revision 8644)
This commit is contained in:
Christoph Grueninger
Andreas Lauser
parent
2416905f45
commit
dcf43bb9da
@ -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,21 +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 functionality provided by the
|
||||
quasi-standard Boost~\cite{BOOST-HP} libraries.
|
||||
which is part of the \Cplusplus standard and was improved in the \Cplusplus11 standard.
|
||||
|
||||
\section{Polymorphism}
|
||||
|
||||
@ -100,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
|
||||
@ -207,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
|
||||
@ -223,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
|
||||
@ -295,19 +294,19 @@ 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
|
||||
\begin{lstlisting}[basicstyle=\ttfamily\scriptsize, numbersep=5pt]
|
||||
test_pdelab.cc:171:9: error: no matching function for call to ‘Dune::\
|
||||
test_pdelab.cc:171:9: error: no matching function for call to <EFBFBD>Dune::\
|
||||
PDELab::GridOperatorSpace<Dune::PDELab::PowerGridFunctionSpace<Dune::\
|
||||
PDELab::GridFunctionSpace<Dune::GridView<Dune::DefaultLeafGridViewTraits\
|
||||
<const Dune::UGGrid<3>, (Dune::PartitionIteratorType)4u> >, Dune::\
|
||||
@ -323,7 +322,7 @@ PDELab::GridFunctionSpaceBlockwiseMapper>, Dumux::PDELab::BoxLocalOperator\
|
||||
<Dumux::Properties::TTag::LensProblem>, Dune::PDELab::\
|
||||
ConstraintsTransformation<long unsigned int, double>, Dune::PDELab::\
|
||||
ConstraintsTransformation<long unsigned int, double>, Dune::PDELab::\
|
||||
ISTLBCRSMatrixBackend<2, 2>, true>::GridOperatorSpace()’
|
||||
ISTLBCRSMatrixBackend<2, 2>, true>::GridOperatorSpace()<EFBFBD>
|
||||
\end{lstlisting}
|
||||
This seriously complicates diagnostics. Although there is no full
|
||||
solution to this problem yet, an effective way of dealing with such
|
||||
@ -472,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}
|
||||
\newcommand{\Dumux}{\texorpdfstring{Du\-Mu$^x$\xspace}{DuMuX}}
|
||||
% 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.
|
||||
|
||||
@ -1,7 +1,7 @@
|
||||
\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}, 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}
|
||||
\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]
|
||||
|
||||
Loading…
Reference in New Issue
Block a user