diff --git a/doc/handbook/TipsNTricks.tex b/doc/handbook/TipsNTricks.tex index 65992120e..cbb464cb1 100644 --- a/doc/handbook/TipsNTricks.tex +++ b/doc/handbook/TipsNTricks.tex @@ -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. diff --git a/doc/handbook/designpatterns.tex b/doc/handbook/designpatterns.tex index 2eabefdc7..21b82c47c 100644 --- a/doc/handbook/designpatterns.tex +++ b/doc/handbook/designpatterns.tex @@ -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 �Dune::\ PDELab::GridOperatorSpace, (Dune::PartitionIteratorType)4u> >, Dune::\ @@ -323,7 +322,7 @@ PDELab::GridFunctionSpaceBlockwiseMapper>, Dumux::PDELab::BoxLocalOperator\ , Dune::PDELab::\ ConstraintsTransformation, Dune::PDELab::\ ConstraintsTransformation, Dune::PDELab::\ -ISTLBCRSMatrixBackend<2, 2>, true>::GridOperatorSpace()’ +ISTLBCRSMatrixBackend<2, 2>, true>::GridOperatorSpace()� \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: diff --git a/doc/handbook/dumux-handbook.tex b/doc/handbook/dumux-handbook.tex index 341569745..92f72ff78 100644 --- a/doc/handbook/dumux-handbook.tex +++ b/doc/handbook/dumux-handbook.tex @@ -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: diff --git a/doc/handbook/install.tex b/doc/handbook/install.tex index b94640439..c571865ce 100644 --- a/doc/handbook/install.tex +++ b/doc/handbook/install.tex @@ -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. diff --git a/doc/handbook/intro.tex b/doc/handbook/intro.tex index 5fbc42d2d..bf65de675 100644 --- a/doc/handbook/intro.tex +++ b/doc/handbook/intro.tex @@ -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: diff --git a/doc/handbook/propertysystem.tex b/doc/handbook/propertysystem.tex index 59ac6e541..95e138f57 100644 --- a/doc/handbook/propertysystem.tex +++ b/doc/handbook/propertysystem.tex @@ -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)} diff --git a/doc/handbook/quick-install.tex b/doc/handbook/quick-install.tex index 77c1b14fb..a41e091cb 100644 --- a/doc/handbook/quick-install.tex +++ b/doc/handbook/quick-install.tex @@ -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]