From 9aad4c3a7ee564cc56d3465fe7c58e1c1a3cddc1 Mon Sep 17 00:00:00 2001 From: Andreas Lauser Date: Wed, 17 Oct 2012 15:48:43 +0200 Subject: [PATCH] handbook: finish update for the 2.2 release at least content-wise. there are still quite a few language issues left to be dealt with... --- doc/handbook/ewoms-handbook.bib | 19 +- doc/handbook/ewoms-handbook.tex | 6 +- doc/handbook/guidelines.tex | 102 +++-- doc/handbook/install.tex | 547 +++++++++++++------------- doc/handbook/intro.tex | 12 +- doc/handbook/new-folder.tex | 89 +++-- doc/handbook/newton-in-a-nutshell.tex | 70 ++-- doc/handbook/structure.tex | 156 ++++---- doc/handbook/tutorial-decoupled.tex | 187 +++++---- examples/tutorialproblem_coupled.hh | 8 +- examples/tutorialproblem_decoupled.hh | 4 +- 11 files changed, 658 insertions(+), 542 deletions(-) diff --git a/doc/handbook/ewoms-handbook.bib b/doc/handbook/ewoms-handbook.bib index bcdda66fb..214b5dbc4 100644 --- a/doc/handbook/ewoms-handbook.bib +++ b/doc/handbook/ewoms-handbook.bib @@ -918,21 +918,36 @@ key = {ALU} } +@MISC{GIT-HP, + title = {The Website of the Git SCM: \url{http://git-scm.com/}}, + key = {GIT} +} + @MISC{APACHE-SUBVERSION-HP, title = {The Apache Subversion Website: \url{http://subversion.apache.org/}}, key = {APACHE-SUBVERSION} } @MISC{DOXYGEN-HP, - title = {Doxgen's Homepage: \url{http://www.stack.nl/~dimitri/doxygen/}}, + title = {The Doxgen website: \url{http://www.stack.nl/~dimitri/doxygen/}}, key = {DOXYGEN} } @MISC{DUMUX-HP, - title = {The {D}umux homepage: \url{http://www.dumux.org/}}, + title = {The {D}umux website: \url{http://www.dumux.org/}}, key = {DUMUX} } +@MISC{EWOMS-HP, + title = {The eWoms website: \url{http://opm-project.org/ewoms}}, + key = {EWOMS} +} + +@MISC{OPM-HP, + title = {The website of the Open Porous Media initiative: \url{http://opm-project.org/}}, + key = {OPM} +} + @MISC{DUNE-BS, title = {{DUNE} Build System Howto: \url{http://www.dune-project.org/doc/buildsystem/buildsystem.pdf}}, key = {DUNE-BS} diff --git a/doc/handbook/ewoms-handbook.tex b/doc/handbook/ewoms-handbook.tex index 69fa969f1..bdd15feec 100644 --- a/doc/handbook/ewoms-handbook.tex +++ b/doc/handbook/ewoms-handbook.tex @@ -179,12 +179,12 @@ \part{Guides} -\input{structure} \input{install} -\input{guidelines} +\input{structure} \input{new-folder} -\input{newton-in-a-nutshell} +\input{guidelines} \input{models} +\input{newton-in-a-nutshell} \bibliographystyle{plain} \bibliography{ewoms-handbook} diff --git a/doc/handbook/guidelines.tex b/doc/handbook/guidelines.tex index 6ecdd0fa5..d13bc0e31 100644 --- a/doc/handbook/guidelines.tex +++ b/doc/handbook/guidelines.tex @@ -1,4 +1,4 @@ -\section{Guidelines} +\chapter{Coding Style Guidelines} \label{guidelines} An important characteristic of source code is that it is written only @@ -6,49 +6,85 @@ once but usually it is read many times (e.g. when debugging things, adding features, etc.). For this reason, good programming frameworks always aim to be as readable as possible, even if comes with higher effort to write them in the first place. The remainder of this section -is almost a verbatim copy of the DUNE coding guidelines found at -\cite{DUNE-HP}. These guidelines are also recommended for coding with -\Dumux as developer and user. - -In order to keep the code maintainable we have decided upon a set of -coding rules. Some of them may seem like splitting hairs to you, but -they do make it much easier for everybody to work on code that hasn't -been written by oneself. +is very similar to the \Dune coding guidelines found at the \Dune +website~\cite{DUNE-HP}. These guidelines are also strongly recommended +for working with \eWoms. Some of these coding style rules may seem +like splitting hairs to you, but they do make it much easier for +everybody to work on code that has not been written by oneself. \begin{itemize} \item Naming: \begin{itemize} -\item Comments: they are helpful! Please document freely what each part of your code does. -\item all comments / documentation is in English -\item Variables: Names for variables should only consist of letters and digits. The first letter should be a lower case one. If your variable names consists of several words, then the first letter of each new word should be capital. As we decided on the only exception are the begin and end methods. -\item Variables should be named as self-explaining as possible: especially abbreviations should be avoided (saturation in stead of S) +\item Comments: They are helpful! Use comments extensively to explain + what your code does, but please refrain from adding trivial + comments. Trivial comments are, for example comments that only + parrot the source code (``this method sets a'' as the comment for a + method called \texttt{setA()}), or comments that explain language + features (``if b is true then a is c else d'' for the statement + \texttt{a = b?c:d}). +\item All comments, documentation and variable or type names are + exclusivly using the English language. +\item Variables: Names for variables should only feature letters and + digits. The first letter should be lower case. If your variable + names consists of several words, then the first letter of each new + word should be capitalized. +\item Variables and methods should be named as self-explanatory as + possible. Especially, this means abbreviations should be avoided + (for example, use 'saturation' in stead of 'S') \item Method parameters which are not self-explanatory should always have a meaningful comment a at calling sites. Example: \begin{lstlisting}[style=eWomsCode] localResidual.eval(/*includeBoundaries=*/true); \end{lstlisting} -\item Private Data Variables: Names of private data variables end with an underscore and are the only variables that contain underscores. -\item Typenames: For typenames, the same rules as for variables apply. The only difference is that the first letter should be a capital one. -\item Macros: The use of preprocessor macros is strongly discouraged. If you have to use them for whatever reason, please use capital letters only. -\item The Exlusive-Access Macro: Every header file traditionally begins with the definition of a preprocessor constant that is used to make sure that each header file is only included once. If your header file is called 'myheaderfile.hh', this constant should be DUNE\_MYHEADERFILE\_HH. -\item Files: Filenames should consist of lower case letters exclusively. Header files get the suffix .hh, implementation files the suffix .cc +\item Private attributes: Names of private attributes should end with + an underscore and are supposed to be the only variables that contain + underscores. +\item Typenames: For typenames (classes, structures, typedefs, etc), + the same rules as for variables apply. The only difference is that + the first letter should be a capital one. +\item Macros: The use of preprocessor macros is strongly + discouraged. If you have to use them for whatever reason, please use + capital letters only. +\item Guardian macros: Every header file traditionally begins with the + definition of a preprocessor macro that is used to make sure that + the header file is only included once. If your header file is + called 'myheaderfile.hh', this constant should be named + \texttt{DUMUX\_MYHEADERFILE\_HH}. +\item Files: File names should exclusively consist of lower case + letters. Header files get the suffix .hh, implementation files the + suffix .cc \end{itemize} -\item Documentation: - Dune, as any software project of similar complexity, will stand and fall with the quality of its documentation. -Therefore it is of paramount importance that you document well everything you do! We use the doxygen system to extract easily-readable documentation from the source code. Please use its syntax everywhere. In particular, please comment \textbf{all} + +\item Documentation: \eWoms, as any software project of similar + complexity, will stand and fall with the quality of its + documentation. Therefore, it is of paramount importance that you + document everything you do well! We use the doxygen system to + extract easily-readable documentation from the source code. Please + use its syntax everywhere. In particular, please comment + \textbf{all} \begin{itemize} -\item Method Parameters (in / out) -\item Template Parameters -\item Return Values +\item Method parameters +\item Template parameters +\item Return values \item Exceptions thrown by a method \end{itemize} - Since we all know that writing documentation is not well-liked and is frequently defered to some vague -'next week', we herewith proclaim the Doc-Me Dogma . It goes like this: Whatever you do, and in whatever hurry you -happen to be, please document everything at least with a {\verb /** $\backslash$todo Please doc me! */}. That way at least the absence -of documentation is documented, and it is easier to get rid of it systematically. -\item Exceptions: - The use of exceptions for error handling is encouraged. Until further notice, all exceptions thrown are DuneEx. -\item Debugging Code: - Global debugging code is switched off by setting the symbol NDEBUG. In particular, all asserts are -automatically removed. Use those asserts freely! + Since we all know that writing documentation is not well-liked and is + frequently defered to some vague 'next week', we herewith proclaim + the Doc-Me Dogma . It goes like this: Whatever you do, and in + whatever hurry you happen to be, please document everything at least + with a {\verb /** $\backslash$todo Please doc me! */}. That way at + least the absence of documentation is documented, and it is easier to + get rid of it systematically. +\item Exceptions: The use of exceptions for error handling is + encouraged. Until further notice, all exceptions thrown are derived + from \texttt{Dune::Exception}. +\item Debugging code: Code which is only there to ease the debugging + process should always be switched off if the preprocessor macro + NDEBUG is defined. In particular, all assertations are automatically + removed. Use those assertations freely! \end{itemize} + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "ewoms-handbook" +%%% End: diff --git a/doc/handbook/install.tex b/doc/handbook/install.tex index 900ae150e..c498ac037 100644 --- a/doc/handbook/install.tex +++ b/doc/handbook/install.tex @@ -1,60 +1,86 @@ -\chapter{Detailed Installation Instructions} \label{install} +\chapter{Detailed Installation Instructions} +\label{install} + \section{Preliminary remarks} -In this section about the installation of \Dumux it is assumed that you work on a Unix or Linux compatible operating system -and that you are familiar with the use of a command line shell. Installation means that you unpack \Dune together with \Dumux in a certain directory. -Then, you compile it in that directory tree in which you do the further work, too. You also should know how to install new software packages -or you should have a person on hand who can give you assistance with that. In section \ref{sec:prerequisites} we list some prerequisites for running \Dune and \Dumux. -Please check in said paragraph whether you can fulfill them. In addition, section \ref{sec:external-modules-libraries} provides some details on optional libraries and modules. +In this section about the installation of \eWoms it is assumed that +you work on a Unix or Linux compatible operating system and that you +are familiar with the use of a command line shell. Installation means +that you unpack \Dune together with \eWoms in a certain directory. +Then, you compile it in that directory tree in which you do the +further work, too. You also should know how to install new software +packages or you should have a person on hand who assist you with +that. In section \ref{sec:prerequisites} we list some prerequisites +for running \Dune and \eWoms. Please make sure to fulfill them before +you proceed. In addition, section \ref{sec:external-modules-libraries} +provides some details on optional libraries and modules. -In a technical sense \Dumux is a module of \Dune. -Thus, the installation procedure of \Dumux is the same as that of \Dune. -Details regarding the installation of \Dune are provided on the \Dune website \cite{DUNE-INST}. -If you are interested in more details about the build system that is used, -they can be found in the {\Dune} Buildsystem Howto \cite{DUNE-BS}. +In a technical sense \eWoms is a module of \Dune. Thus, the +installation procedure of \eWoms is the same as that of \Dune (besides +using different locations to retieve the source code). Details +regarding the installation of \Dune are provided on the \Dune +website~\cite{DUNE-INST}. If you are interested in more details about +the build system that is used, they can be found in the {\Dune} +build system howto \cite{DUNE-BS}. +All \Dune modules, including \eWoms, get extracted into a common +directory. In the following, we refer to that directory as {\Dune} +base directory or, in short, as {\Dune}-base. If it is used as +directory path of a shell command it is typed as +\texttt{dune-base}. For the actual location of the {\Dune} base +directory on your file system, you may chose any valid directory name for +which you have write permissions. -All \Dune modules, including \Dumux, get extracted into a common directory, as it is done in an ordinary \Dune installation. -We refer to that directory abstractly as {\Dune} root directory or, in short, as {\Dune}-Root. -If it is used as directory's path of a shell command it is typed as \texttt{\Dune-Root}. -For the real {\Dune} root directory on your file system any valid directory name can be chosen. +Source code files for each \Dune module are contained in their own +subdirectory within {\Dune}-base. We name this directory of a certain +module \emph{module base directory} or \texttt{module-base} +if it is a directory path, e.\,g. for the module \texttt{ewoms} these +names are \emph{ewoms base directory} respective +\texttt{ewoms-base}. The real directory names for the +modules can be chosen arbitrarily. In this manual they are the same as +the module name or the module name extended by a version number +suffix. The name of each \Dune module is defined in the file +\texttt{dune.module}, which is in the base directory of the respective +module. This should not be changed by the user. It is allowed to have +own files and directories in \Dune-base, which are not related to +\Dune's needs. -Source code files for each \Dune module are contained in their own subdirectory within {\Dune}-Root. -We name this directory of a certain module \emph{module root directory} or \texttt{module-root-directory} if it is a directory path, -e.\,g. for the module \texttt{dumux} these names are \emph{dumux root directory} respective \texttt{dumux-root-directory}. -The real directory names for the modules can be chosen arbitrarily. In this manual they are the same as the -module name or the module name extended by a version number suffix. -The name of each \Dune module is defined in the file \texttt{dune.module}, which is in the root -directory of the respective module. This should not be changed by the user. -It is allowed to have own files and directories in \Dune-Root, which are not related to \Dune's needs. - -After installing source code for all relevant \Dune modules including \Dumux, \Dune is being built by the shell-command \texttt{dunecontrol} which is part of the \Dune build system. The \Dune build system is a front-end of to the GNU build system adapted to the needs of \Dune. +After installing source code for all relevant \Dune modules including +\eWoms, \Dune is being built by the shell-command \texttt{dunecontrol} +which is part of the \Dune build system. The \Dune build system is a +front-end of to the GNU build system adapted to the needs of \Dune. \section{Prerequisites} \label{sec:prerequisites} -The GNU tool chain of \texttt{g++} and the tools of the GNU build system \cite{GNU-BS}, also known as GNU autotools -(\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 \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 -and GNU \texttt{make} version $\geqslant$ 3.81 should do their job for building \Dumux. +The GNU compiler collection with \Cplusplus support (\texttt{g++}) and +the tools of the GNU build system \cite{GNU-BS}, also known as GNU +autotools (\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 enough version. For example Ubuntu +Linux provides these tools by means of the packages \texttt{autoconf}, +\texttt{automake}, \texttt{libtool} and the package +\texttt{build-essential} includes the \Cplusplus compiler +\texttt{g++} and \texttt{make}. -The building of included documentation like this handbook requires \LaTeX\ and auxiliary tools -like \texttt{dvipdf} and \texttt{bibtex}. One usually chooses a \LaTeX\ distribution like \texttt{texlive} for this purpose. -It is possible to switch off the building of the documentation by setting the switch \texttt{--disable-documentation} -in the \texttt{CONFIGURE\_FLAGS} of the building options (see Chapter \ref{buildIt}). -Additional parts of documentation are contained within the source code files as special formatted comments. -Extracting them can be done using \texttt{doxygen} (version $\geqslant$ 1.7.2 works). -See for this optional step Section \ref{sec:build-doxy-doc}. +At the time of writing this manual, the minumum version required for +\texttt{g++} is 4.4.0, \texttt{automake} the documentation by setting the switch +\texttt{--disable-documentation} in the \texttt{CONFIGURE\_FLAGS} of +the building options (see Chapter \ref{buildIt}). Additional parts of +documentation are contained within the source code files as specially +formatted comments. Extracting them can be done using the tool +\texttt{doxygen} (version $\geqslant$ 1.8.2 works). See for this +optional step section \ref{sec:build-doxy-doc}. -Depending on whether you are going to use external libraries and modules for additional \Dune features, -additional software packages may be required. Some hints on that are given in Section \ref{sec:external-modules-libraries}. +Depending on whether you are going to use external libraries and +modules for additional \Dune features, additional software packages +may be required. Some hints on that are given in Section +\ref{sec:external-modules-libraries}. -For the extraction of the content of tar files, the GNU version of \texttt{tar} is used. -The subversion (svn) software repositories can be accessed with help of a subversion client. We recommend the Apache Subversion command-line client \texttt{svn} -contained in Apache Subversion of version $\geqslant$ 1.6.0 \cite{APACHE-SUBVERSION-HP}. +For the extraction of the content of tar files, the GNU version of +\texttt{tar} is used. To access the git or subversion software +repositories, a git and subversion clients are required. We recommend +to use the git command-line client \texttt{git} version 1.7.12 or +newer with the subversion integration plugin \texttt{git-svn} enabled~\cite{GIT-HP}. \begin{table} \centering @@ -63,18 +89,18 @@ contained in Apache Subversion of version $\geqslant$ 1.6.0 \cite{APACHE-SUBVERS \toprule \textbf{purpose} & \textbf{package names} \\ \midrule -general: & subversion & git & libtool \\ +general: & git & git-svn & libtool \\ & automake & build-essential & libboost-all-dev \\ & texlive-latex-base & doxygen & csh\\ -& gfortran & ? libpthread-stubs0 ?\\ +& gfortran & \\ \midrule for alberta: & freeglut3-dev & \\ \midrule for parallel use: & openmpi-common & mpi-default-bin & mpi-default-dev \\ \midrule -for ug parallel: & flex & bison & \\ +for parallel UG: & flex & bison & \\ \midrule -for alberta parallel: & libblas-dev &\\ +for parallel alberta: & libblas-dev &\\ \midrule for debugging: & valgrind &\\ \bottomrule @@ -82,293 +108,258 @@ for debugging: & valgrind &\\ \label{tbl:ubuntu-pkg} \end{table} -\section{Obtaining source code for \Dune and \Dumux} -As stated above, the \Dumux release 2.1.0 and trunk (developer tree) are based on the \Dune release 2.1.1, -comprising the core modules \texttt{dune-common}, \texttt{dune-grid}, \texttt{dune-istl} and \texttt{dune-localfunctions}. -% and the external dune module \texttt{dune-pdelab}. -For working with \Dumux, these modules are required. +\section{Obtaining source code for \Dune and \eWoms} -Two possibilities exist to get the source code of \Dune and \Dumux. -Firstly, \Dune and \Dumux can be downloaded as tar files from the respective \Dune and \Dumux website. They have to be extracted as described in the next paragraph. -Secondly, a method to obtain the most recent source code (or, more generally, any of its previous revisions) by direct access -via Internet to the software repositories of the revision control system is described in the subsequent part. +As stated above, the \eWoms is based on the \Dune release 2.2, +comprising the core modules \texttt{dune-common}, +\texttt{dune-geometry}, \texttt{dune-grid}, \texttt{dune-istl} and +\texttt{dune-localfunctions}. For working with \eWoms, these modules +are required. -However, if a user does not want to use the most recent version, -certain version tags (i.\,e. special names), version numbers and even software branches are means -of the software revision control system to provide access to different versions of the software. +Two possibilities exist to get the source code of \Dune and \eWoms. +Firstly, released versions \Dune and \eWoms can be downloaded as tar +files from the \Dune and \eWoms websites. They have to be extracted as +described in the next paragraph. Secondly, the most recent source +code can be obtained by directly downloading it from its respective +source-code repository. This method is described in the subsequent +section. \paragraph{Obtaining the software by installing tar files} -The slightly old-fashionedly named tape-archive-file, shortly named tar file or tarball, is a common file format for distributing collections of files contained within these archives. -The extraction from the tar files is done as follows: -Download the tarballs from the respective \Dune (version 2.2.0) and \Dumux websites to a certain folder in your file system. -Create the {\Dune} root directory, named DUMUX in the example below. Then extract the content of the tar files, e.\,g. with the command-line program \texttt{tar}. -This can be achieved by the following shell commands. Replace \texttt{path\_to\_tarball} with the directory name where the downloaded files are actually located. -After extraction, the actual name of the \emph{dumux root directory} is \texttt{dumux-2.2}. + +The slightly old-fashionedly named tape-archive-file, shortly named +tar file or tarball, is a common file format for distributing +collections of files contained within these archives. The extraction +from the tar files is done as follows: Download the tarballs from the +respective \Dune~\cite{DUNE-HP} (version 2.2.0) and +\eWoms~\cite{EWOMS-HP} websites. Then, create the {\Dune} base +directory, named \texttt{~/src} in the example below. Then, extract the +content of the tar files, e.\,g. with the command-line program +\texttt{tar}. This can be achieved by the following shell +commands. Replace \texttt{path\_to\_tarball} with the directory name +where the downloaded files are actually located. After extraction, +the actual name of the \emph{ewoms base directory} is +\texttt{ewoms-2.2}. \begin{lstlisting}[style=Bash] -$ mkdir DUMUX -$ cd DUMUX +$ mkdir ~/src +$ cd ~/src $ tar xzvf path_to_tarball_of/dune-common-2.2.0.tar.gz $ tar xzvf path_to_tarball_of/dune-grid-2.2.0.tar.gz $ tar xzvf path_to_tarball_of/dune-geometry-2.2.0.tar.gz $ tar xzvf path_to_tarball_of/dune-istl-2.2.0.tar.gz $ tar xzvf path_to_tarball_of/dune-localfunctions-2.2.0.tar.gz -$ tar xzvf path_to_tarball_of/dumux-2.2.tar.gz +$ tar xzvf path_to_tarball_of/ewoms-2.2.0.tar.gz \end{lstlisting} -Furthermore, if you wish to install the optional \Dune Grid-Howto which provides a tutorial on the Dune grid interface: +\paragraph{Obtaining \Dune and \eWoms from software repositories} + +Direct access to a software repositories for downloading code can be +convenient to always follow the changes of done to the software +project. Usually, source code repositories are structured in +branches. One of these branches is commonly used to include the latest +features of the software, and there is normally one branch for each +release which only receives fixes for bug which have been discovered +after the software was released. The following text describes how to +retrieve the source code of \Dune and \eWoms from such release +branches. + +The \Dune project uses Apache Subversion~\cite{APACHE-SUBVERSION-HP} +to manage its software repositories, while \eWoms -- being part of the +open porous media project -- opted to use the git source code +management system~\cite{GIT-HP}. Fortunately, git ships with a +subversion plugin, so all modules can be managed using git. + +In the technical language of Apache Subversion \emph{cloning a certain + software repository} means nothing more then fetching a local copy +of the software repository and placing it on the local file system. +In addition to the software some more files for the use of the +software revision control system itself are created. They are kept in +a directory named \texttt{.git} at the base directory of the cloned +software repository. + +The installation procedure is structured as follows: Create a {\Dune} base +directory (named \texttt{~/src} in the lines below). Then, enter the +previously created directory and check out the desired modules. As +you see below, the check-out uses two different servers for getting +the sources, one for \Dune and one for \eWoms. The \Dune modules of +the stable 2.2 release branch are cloned similarly as described on the +\Dune website~\cite{DUNE-DOWNLOAD-SVN}: \begin{lstlisting}[style=Bash] -$ tar xzvf path_to_tarball_of/dune-grid-howto-2.2.0.tar.gz +mkdir ~/src +cd ~/src +for DUNE_MODULE in common geometry grid istl localfunctions; do + git svn clone \ + https://svn.dune-project.org/svn/dune-$DUNE_MODULE/branches/release-2.2 \ + dune-$DUNE_MODULE +done \end{lstlisting} -\paragraph{Obtaining \Dune and \Dumux from software repositories} +The newest and maybe unstable developments are also provided in these +repositories in a folder called \emph{trunk}. Please check the \Dune +website \cite{DUNE-DOWNLOAD-SVN} for further information. However, the +current \eWoms release is based on the stable 2.2 \Dune release and it +might misbehave using the the newest version of \Dune. -Direct access to a software revision control system for downloading code can be of advantage for the user later on. -It can be easier for him to keep up with code changes and to receive important bug fixes using the update command of the revision control system. -\Dune and \Dumux use Apache Subversion for their software repositories. To access them a certain program is needed which is referred to here shortly as subversion client. -In our description, we use the subversion client of the Apache Subversion software itself, which is a command-line tool named \texttt{svn}. -It is available for most Linux and Unix distributions as software package. - -In the technical language of Apache Subversion \emph{checking out a certain software version} means nothing more then fetching -a local copy from the software repository and laying it out in the file system. In addition to the software some more files for the use of the software revision control system itself are created. They are kept in directories named \texttt{.svn} and can be found in each subfolder which is under version control. -If you have developer access to \Dumux, it is also possible to do the opposite, i.\,e. to load up a modified revision of software into the software repository. This is usually termed as \emph{software commit}. - -The installation procedure is done as follows: -Create a {\Dune} root directory, named \texttt{DUMUX} in the lines below. -Then, enter the previously created directory and check out the desired modules. -As you see below, the check-out uses two different servers for getting the sources, one for \Dune and one for {\Dumux}. -The \Dune modules of the stable 2.2 release branch are checked out as described on the \Dune website \cite{DUNE-DOWNLOAD-SVN}: +The \eWoms module is checked out as described below (see also the +\eWoms website \cite{EWOMS-HP}). Its source tree has to be created in +the \Dune-base directory, where the \Dune modules have also been +cloned into. Subsequently, the next command is executed there, +too. The directory which holds the \eWoms module is called +\texttt{ewoms} here. \begin{lstlisting}[style=Bash] -$ mkdir DUMUX -$ cd DUMUX -$ svn checkout https://svn.dune-project.org/svn/dune-common/branches/release-2.2 dune-common -$ svn checkout https://svn.dune-project.org/svn/dune-istl/branches/release-2.2 dune-istl -$ svn checkout https://svn.dune-project.org/svn/dune-grid/branches/release-2.2 dune-grid -$ svn checkout https://svn.dune-project.org/svn/dune-geometry/branches/release-2.2 dune-geometry -$ svn checkout https://svn.dune-project.org/svn/dune-localfunctions/branches/release-2.2 dune-localfunctions +cd ~/src +git clone git://github.com/OPM/ewoms.git ewoms \end{lstlisting} -The newest and maybe unstable developments are also provided in these repositories in a folder called \emph{trunk}. Please check the \Dune website \cite{DUNE-DOWNLOAD-SVN} for further information. However, the current \Dumux release is based on the stable 2.1 release and it might not compile without further adaptations using the the newest versions of \Dune. +\section{Building the doxygen documentation} +\label{sec:build-doxy-doc} -The additional module \texttt{dune-grid-howto} is a tutorial which provides information about the \Dune grid interface. -It may give you an idea of how some abstractions in \Dune are done. -The installation of \texttt{dune-grid-howto} is optional and is not required by \Dumux. It is done by: +Doxygen documentation is done by especially formatted comments +integrated in the source code, which can get extracted by the program +\texttt{doxygen}. Beside extracting these comments, \texttt{doxygen} +builds up a web-browsable code structure documentation like class +hierarchy of code displayed as graphs, see \cite{DOXYGEN-HP}. + +Building the doxygen documentation of a module is done as follows, +provided the program \texttt{doxygen} is installed: Set in building +options the \texttt{--enable-doxygen} switch. This is either +accomplished by adding it in \texttt{dunecontrol} options-file to +\texttt{CONFIGURE\_FLAGS}, or by adding it to \texttt{dunecontrol}'s +command-line-argument \texttt{--configure-opts}. After running +\texttt{dunecontrol} enter in module's base directory the subdirectory +\texttt{doc/doxygen}. You then run the command \texttt{doxygen} +within that directory. Point your web browser to the file +\texttt{module-base-directory/doc/doxygen/html/index.html} to read the +generated documentation. For all \Dune-modules that described here, +the doxygen documentation can be generated analogously. \begin{lstlisting}[style=Bash] -$ svn checkout https://svn.dune-project.org/svn/dune-grid-howto/branches/release-2.2 dune-grid-howto +cd ~/src/ewoms/doc/doxygen +doxygen +firefox html/index.html \end{lstlisting} -The \texttt{dumux} module is checked out as described below (see also the \Dumux website \cite{DUMUX-HP}). -Its file tree has to be created in the \Dune-Root directory, where the \Dune modules have also been checked out to. Subsequently, the next command -is executed there, too. The dumux root directory is called \texttt{dumux} here. - -\begin{lstlisting}[style=Bash] -$ # make sure you are in DUNE-Root -$ svn checkout --username=anonymous --password='' svn://svn.iws.uni-stuttgart.de/DUMUX/dumux/trunk dumux -\end{lstlisting} - -\paragraph{Hints for \Dumux-Developers} -If you also want to actively participate in the development of \Dumux, you can apply either for full developer -access or for developer access on certain parts of \Dumux. Granted developer access means that -you are allowed to commit own code and that you can access the \texttt{dumux-devel} module. -This enhances \texttt{dumux} by providing maybe unstable code from the developer group. -A developer usually checks out non-anonymously the modules \texttt{dumux} and \texttt{dumux-devel}. -\texttt{Dumux-devel} itself makes use of the stable part \texttt{dumux}. Hence, the two parts have to be checked out together. -This is done using the commands below. But \texttt{joeuser} needs to be replaced by -the actual user name of the developer for accessing the software repository. -One can omit the \texttt{--username} option in the commands above if the user name for the repository access is -identical to the one for the system account. - -\begin{lstlisting}[style=Bash] -$ svn co --username=joeuser svn://svn.iws.uni-stuttgart.de/DUMUX/dumux/trunk dumux -$ svn co --username=joeuser svn://svn.iws.uni-stuttgart.de/DUMUX/dune-mux/trunk dumux-devel -\end{lstlisting} - -Please choose either not to store the password by subversion in an insecure way or -choose to store it by subversion in a secure way, e.\,g. together with KDE's KWallet or GNOME Keyring. -Check the documentation of Subversion for info on how this is done. -A leaked out password can be used by evil persons to abuse a software repository. - -\section{Patching \Dune or external libraries} -Patching of \Dune modules in order to work together with \Dumux can be necessary for several reasons. -Software like a compiler or even a standard library -changes at times. But, for example, a certain release of a software component that we depend on, may not reflect that change and thus it has to be modified. -In the dynamic developing process of software which depends on other modules it is not always feasible -to adapt everything to the most recent version of each module. Consequently, patches exist or they will be brought into existence. They may fix problems with a certain module -of a certain release without introducing too much structural change. It can also happen -that a release gets amendments (updates) and a formerly useful patch becomes obsolete. - -\Dumux contains patches and documentation about their usage and application within the directory \texttt{dumux/patches}. -Please check the README file in that directory for recent information. -In general, a patch can be applied as follows (the exact command or the used parameters may be slightly different). -We include here an example of a patch against 2.0 release of \Dune for \Dumux release 2.0 for purpose of showing how a patch gets applied. Note this patch is no longer necessary for \Dune 2.2 releases. - -\begin{lstlisting}[style=Bash] -$ # make sure you are in DUNE-Root -$ cd dune-istl -$ patch -p1 < ../dumux/patches/dune-istl-2.0.patch -\end{lstlisting} - -It can be removed by -\begin{lstlisting}[style=Bash] -$ path -p1 -R < ../dumux/patches/dune-istl-2.0.patch -\end{lstlisting} - -The \texttt{checkout-dumux} script also applies patches, if not explicitly requested not to do so. - - -\section{Building doxygen documentation} \label{sec:build-doxy-doc} - -Doxygen documentation is done by especially formatted comments integrated in the source code, which can get extracted by the program -\texttt{doxygen}. Beside extracting these comments, \texttt{doxygen} builds up a web-browsable code structure documentation -like class hierarchy of code displayed as graphs, see \cite{DOXYGEN-HP}. - -Building the doxygen documentation of a module is done as follows, provided the program \texttt{doxygen} is installed: -Set in building options the \texttt{--enable-doxygen} switch. -This is either accomplished by adding it in \texttt{dunecontrol} options-file to \texttt{CONFIGURE\_FLAGS}, or by adding -it to \texttt{dunecontrol}'s command-line-argument \texttt{--configure-opts}. -After running \texttt{dunecontrol} enter in module's root directory the subdirectory \texttt{doc/doxygen}. -You then run the command \texttt{doxygen} within that directory. Point your web browser to the file -\texttt{module-root-directory/doc/doxygen/html/index.html} to read the generated documentation. -All \Dune-modules that are used here except \texttt{dune-grid-howto} including also \texttt{dumux} contain some doxygen documentation, which can be extracted as -described in the following lines. The external library UG has also a \texttt{doc/doxygen} directory for building its doxygen documentation. - -\begin{lstlisting}[style=Bash] -$ # change before next command your directory to DUNE-Root -$ cd dumux/doc/doxygen -$ doxygen -$ firefox html/index.html -\end{lstlisting} - -\section{Building documentation of other \Dune modules} +\section{Building the \eWoms handbook} If the \texttt{--enable-documentation} switch has been set in the configure flags of -\texttt{dunecontrol}, this does not necessarily mean that for every -\Dune module the documentation is being built. -However, at least Makefiles for building the documentation are generated. -Provided you run \texttt{dunecontrol} with the option above, -it should be possible to build documentation if available. -Check the targets you can build in \texttt{module-root-directory/doc/Makefile.am}. -For example in the module \texttt{dune-istl} you can build the documentation \texttt{istl.pdf} by typing the following into the console, when you are in the \Dune-Root: - +\texttt{dunecontrol}, watch for a summary line of the build script that reads \begin{lstlisting}[style=Bash] -$ # change before next command your directory to DUNE-Root -$ cd dune-istl/doc -$ make istl.pdf +Build eWoms handbook....: yes \end{lstlisting} -Or for module \texttt{dune-grid-howto} the documentation can be build by: +If this is the case, the handbook should be automatically build by +\texttt{dunecontrol} and can be found at +\texttt{\$EWOMS\_BASE/doc/handbook/ewoms-handbook.pdf}. -\begin{lstlisting}[style=Bash] -$ # change before next command your directory to DUNE-Root -$ cd dune-grid-howto/doc -$ make grid-howto.pdf -\end{lstlisting} +If the summary line says that the handbook is not going to be build, +then you usually have to install additional \LaTeX packages. -This applies for \Dumux, too. Rebuilding the handbook can be done as follows: +\section{External libraries and modules} +\label{sec:external-modules-libraries} -\begin{lstlisting}[style=Bash] -$ cd dumux/doc/handbook -$ make ewoms-handbook.pdf -\end{lstlisting} +The libraries described below provide additional functionality but are +not generally required to use \eWoms. If you are going to use an +external library, also check the information provided on the \Dune +website~\cite{DUNE-EXT-LIB} for additional hints. If you are going to +use an external \Dune module, the website listing external +modules~\cite{DUNE-EXT-MOD} can also be helpful. +Some external libraries have additional dependencies which can also be +used by \Dune. Also, some libraries, such as BLAS or MPI might have +multiple versions installed on the system. To avoid problems, you +should make sure that all external libraries use the same dependencies +as \Dune. -%As of writing this, no general method of building documentation contained in \Dune's modules is known to the author. - -%Alternatively, the tool CMake can be used to build \Dumux. Please check the file \texttt{INSTALL.cmake} for details. - -\section{External libraries and modules} \label{sec:external-modules-libraries} - -The libraries described below provide additional functionality but are not generally required to run \Dumux. -If you are going to use an external library check the information provided on the \Dune website \cite{DUNE-EXT-LIB}. -If you are going to use an external \Dune module the website on external modules \cite{DUNE-EXT-MOD} can be helpful. - -Installing an external library can require additional libraries which are also used by \Dune. -For some libraries, such as BLAS or MPI, multiple versions can be installed on the system. -Make sure that it uses the same library as \Dune when configuring the external library. - -In the following list, you can find some external modules and external libraries, and some more libraries and tools which are prerequisites for their use. +In the following list, you can find some external modules and external +libraries, and some more libraries and tools which are prerequisites +for their use. \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{ALBERTA}: External library which can be used as an + additional grid manager. ALBERTA stands for ``\textbf{A}daptive multi \textbf{L}evel finite element toolbox + using \textbf{B}isectioning refinement and \textbf{E}rror control by \textbf{R}esidual + \textbf{T}echniques for scientific \textbf{A}pplications''. Building it requires a + Fortran compiler, for example \texttt{gfortran}. It can be downloaded at: + \texttt{\url{http://www.alberta-fem.de}}. -\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{ALUGrid}: External library for use as grid. ALUGrid + requires by a \Cplusplus compiler like \texttt{g++} to be build. If + you want to build a parallel version, you will need an MPI library + like, for example \texttt{openmpi}, installed on your system. The + parallel version needs also a graph partitioner, such as + \texttt{METIS}. -\item \textbf{\Dune-multidomaingrid}: External module. If you going to run on the same grid different domains or subdomains, -this can be the package of choice. This is done by providing a meta grid. It can be useful for multi-physics approaches or domain decomposition methods. Download: \texttt{\url{http://gitorious.org/dune-multidomaingrid}}. -%Furthermore, the external module \textbf{\Dune-multidomain} can be useful for solving heterogenous problems on spatial subdomains. These subdomains are managed using another DUNE module called dune-multidomaingrid. + Download: + \texttt{\url{http://aam.mathematik.uni-freiburg.de/IAM/Research/alugrid}} -\item \textbf{\Dune-PDELab}: External module to write more easily discretizations. PDELab provides already a sound number of discretizations like FEM or discontinuous Galerkin methods. Download: \texttt{\url{http://www.dune-project.org/pdelab}}. +\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. -\item \textbf{PARDISO}: External library for solving linear equations. The package PARDISO is a thread-safe, high-performance, robust, memory efficient and easy to use software for solving large sparse symmetric and asymmetric linear systems of equations on shared memory multiprocessors. The precompiled binary can be downloaded after personal registration from the PARDISO website (\texttt{\url{http://www.pardiso-project.org}}). + Download: + \texttt{\url{http://crd.lbl.gov/~xiaoye/SuperLU}}. -\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 which can be used as an additional + grid manager. UG is a toolbox for \textbf{U}nstructured + \textbf{G}rids: For \eWoms 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}. -\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}. + Website: + \texttt{\url{http://atlas.gcsc.uni-frankfurt.de/~ug/}}\\ + Further information: + \texttt{\url{http://www.dune-project.org/external_libraries/install_ug.html}}\\ \end{itemize} -The following are dependencies of some of the used libraries. You will need them depending on which modules of \Dune and which external libraries you use. +The following are dependencies of some of the external libraries. You +will need them depending on which modules of \Dune and which external +libraries you use. \begin{itemize} -\item \textbf{MPI}: The parallel version of \Dune and also some of the external dependencies need MPI when they are going to be built for parallel computing. \texttt{Openmpi} version $\geqslant$ 1.4.2 and \texttt{MPICH} in a recent version have been reported to work. +\item \textbf{MPI}: The parallel version of \Dune and also some of the + external dependencies need MPI when they are going to be built for + parallel computing. \texttt{Openmpi} version $\geqslant$ 1.4.2 and + \texttt{MPICH} in a recent version have been reported to work. -\item \textbf{lex/yacc} or \textbf{flex/bison}: These are quite common developing tools, code generators for lexical analyzers and parsers. This is a prerequisite for UG. +\item \textbf{lex/yacc} or \textbf{flex/bison}: These are quite common + developing tools, code generators for lexical analyzers and + parsers. This is a prerequisite for compiling UG. -\item \textbf{BLAS}: Alberta makes use of BLAS. Thus install GotoBLAS2, ATLAS, non-optimized BLAS or BLAS provided by a chip manufacturer. Take care that the installation scripts select the intended version of BLAS. See \texttt{\url{http://en.wikipedia.org/wiki/Basic_Linear_Algebra_Subprograms}}. +\item \textbf{BLAS}: Alberta makes use of BLAS (acronym for + ``\textbf{B}asic \textbf{L}inear \textbf{A}lgebra + \textbf{S}ubprograms). Thus install GotoBLAS2, ATLAS, + non-optimized BLAS or a BLAS library provided by a computer + vendor. Take care that the installation scripts select the intended + version of BLAS. For further information, see + \texttt{\url{http://en.wikipedia.org/wiki/Basic_Linear_Algebra_Subprograms}}. -\item \textbf{GotoBLAS2}: This is an optimized version of BLAS. It covers not all processors of the day, but quite a broad range. Its license is now very open. A Fortran compiler like \texttt{gfortran} is needed to compile it.\\ -Available by \texttt{\url{http://www.tacc.utexas.edu/tacc-projects/gotoblas2/}}. +\item \textbf{GotoBLAS2}: This is an optimized BLAS library. It does + not provide optimized routines for all modern processors, but quite + a broad range. Also, its license is now open. A Fortran compiler + like \texttt{gfortran} is needed to compile it. -\item \textbf{METIS}: This is a dependency of ALUGrid, if you are going to run it parallel. + Available at + \texttt{\url{http://www.tacc.utexas.edu/tacc-projects/gotoblas2/}}. -\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{METIS}: This is a dependency of ALUGrid, if you are + going to run it parallel. + + Available for non-commercial use at + \texttt{\url{http://glaros.dtc.umn.edu/gkhome/metis/metis/overview}} -\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. -% http://openmp.org/ - -%\item \textbf{libgmp}: The Gnu Multiple Precision Arithmetic Library (GMP) is also a prerequisite for \Dune. It may be necessary to install it. -% http://gmplib.org/ +\item \textbf{Compilers}: Besides \texttt{g++} \Dune and \eWoms can + also be built with the \texttt{clang++} compiler originating from + the LLVM project. If you try other compilers, be aware that in addition to a + \Cplusplus compiler, C and Fortran compilers are needed to compile + some external libraries. \end{itemize} -\section{Hints for Users from IWS} -We provide some features to make life a little bit easier for -users from the Institute for Modelling Hydraulic and Environmental Systems, University of Stuttgart. - -There exists internally a SVN repository made for several external libraries. -If you are allowed to access it, go to the {\Dune}-Root, then the following. - -Prepared external directory: -\begin{lstlisting}[style=Bash] -$ # Make sure you are in DUNE-Root -$ svn checkout svn://svn.iws.uni-stuttgart.de/DUMUX/external/trunk external -\end{lstlisting} - -This directory \texttt{external} contains a script to install external libraries, such as -ALBERTA, ALUGrid, UG, METIS and GotoBLAS2: -\begin{lstlisting}[style=Bash] -$ cd external -$ ./installExternal.sh all -\end{lstlisting} - -It is also possible to install only the actually needed external libraries: -\begin{lstlisting}[style=Bash] -$ ./installExternal.sh -h # show, what options this script provide -$ ./installExternal.sh --parallel alu -\end{lstlisting} - -The libraries are then compiled within that directory and are not installed in a different place. -A \Dune build may need to know their location. Thus, one may have to refer to them as options for \texttt{dunecontrol}, -for example via the options file \texttt{my-debug.opts}. Make sure you compile the required external libraries before -you run \texttt{dunecontrol}. - - - - %%% Local Variables: %%% mode: latex %%% TeX-master: "ewoms-handbook" diff --git a/doc/handbook/intro.tex b/doc/handbook/intro.tex index 7fb741d5d..e3a037bec 100644 --- a/doc/handbook/intro.tex +++ b/doc/handbook/intro.tex @@ -1,6 +1,6 @@ \chapter{Introduction} -\eWoms aims to be a generic framework for the simulation of multiphase +\eWoms~\cite{EWOMS-HP} aims to be a generic framework for the simulation of multi-phase fluid flow and transport processes in porous media using continuum mechanical approaches. At the same time, \eWoms aims to deliver top-notch computational performance, high flexibility, a sound @@ -8,6 +8,16 @@ software architecture and the ability to run on anything from single processor systems to highly parallel supercomputers with specialized hardware architectures. +\eWoms is an integral part of the open porous media +initiative~\cite{OPM-HP} where it provides the fully-implicit +models. \eWoms is based on the source code of the +\Dumux~\cite{DUMUX-HP} simulation framework and aims to be a proper +superset of \Dumux when it comes to features, while at the same time +it aims to deliver better performance and quality of the source +code. To ease porting features from \Dumux to \eWoms and vice-versa, +all classes provided by \eWoms are currently located in the namespace +\texttt{Dumux}. + The means to achieve these somewhat contradictory goals are the thorough use of object oriented design in conjunction with template programming. These requirements motivated the decision to use diff --git a/doc/handbook/new-folder.tex b/doc/handbook/new-folder.tex index dbe984179..b1661de41 100644 --- a/doc/handbook/new-folder.tex +++ b/doc/handbook/new-folder.tex @@ -1,54 +1,87 @@ -\section{Setup of a New Folder} +\chapter{Creating a new directory for source code} -In this section setting up a new folder is described. In fact it is very easy to create a new folder, but getting \Dumux to know the new folder takes some steps which will be explained in more detail below: +In this section, we describe how setting up a new directory for source +code. In fact, it is very easy to create a new directory, but getting +\Dune build system to recognize the new folder takes some steps which +will be explained in more detail below: \begin{itemize} - \item create new folder with content - \item adapt \verb+Makefile.am+ - \item insert new folder in \verb+Makefile.am+ of the directory above - \item adapt \verb+configure.ac+ in the \verb+$DUMUX_ROOT+ (the directory you checked out, probably dumux) - \item newly compile \Dumux +\item Create new directory with content. Quite often an existing + directory can be used as a base for the new one. +\item Adapt \texttt{Makefile.am} in the new directory and add this + direcory to the \texttt{SUBDIRS} list of the \texttt{Makefile.am} in + the directory above the one which you just created. +\item Adapt \texttt{configure.ac} in the \eWoms base directory (the + directory to which you checked out or unpacked the \eWoms source + code, probably \texttt{ewoms}) +\item Run the command \texttt{automake} in the \eWoms base directory. +\item Re-compile \eWoms by typing \texttt{make} in the \eWoms base + directory. \end{itemize} \noindent In more detail: -\textbf{First} of all, the new folder including all relevant files needs to be created (see Section \ref{tutorial-coupled} and \ref{tutorial-decoupled} for description of a problem). +\textbf{First} of all, the new directory including all relevant files +needs to be created (see section \ref{tutorial-coupled} and +\ref{tutorial-decoupled} for description of how to define problems). -\textbf{Second}, a new \verb+Makefile.am+ for the new Folder needs to be created. It is good practice to simply copy an existing file. For example the file \verb+$DUMUX_ROOT/test/2p/Makefile.am+ looks as follows: +\textbf{Second}, a new \texttt{Makefile.am} for the new directory +needs to be created. It is good practice to simply copy and modify an +existing file. For example, the file \texttt{tutorial/Makefile.am} +looks as follows: \begin{verbatim} -bin_PROGRAMS = test_2p +# programs just to build when "make check" is used +check_PROGRAMS = tutorial_decoupled tutorial_coupled -test_2p_SOURCES = test_2p.cc -test_2p_CXXFLAGS = $(MPI_CPPFLAGS) -test_2p_LDADD = $(MPI_LDFLAGS) +noinst_HEADERS= *.hh +EXTRA_DIST = CMakeLists.txt + +tutorial_coupleddir = $(datadir)/dumux/tutorial +tutorial_coupled_SOURCES = tutorial_coupled.cc +tutorial_coupled_DATA = $(tutorial_coupled_SOURCES) include $(top_srcdir)/am/global-rules \end{verbatim} -All occurrences of \verb+test_2p+ need to be replaced by the name of the new project, e.g. \verb+New_Project+. At least if the name of the source file as well as the name of the new project are \verb+New_Project+. +All occurrences of \texttt{tutorial\_coupled} need to be replaced by +the name of the new project, e.g. \texttt{new\_project}. At least if +the name of the source file as well as the name of the new project are +\texttt{new\_project}. -\textbf{Third}: In the directory above your new Project there is also a \verb+Makefile.am+ . In this file the subdirectories are listed. As you introduced a new subdirectory, it needs to be included here. In this case the name of the new Folder is \verb+New_Project+ . Don't forget the trailing backslash. +\textbf{Third}: In the parent directory of the directory which you +created, there is also a \texttt{Makefile.am}. In this file the +sub-directories are listed. As you introduced a new sub-directory, it +needs to be included there. In this case, the name of the new +directory is \texttt{new\_project}. \begin{verbatim} - SUBDIRS = . \ - 1p \ - 1p2c \ - 2p \ - 2p2c \ - 2p2cni \ - 2pni \ - New_Project \ +... +SUBDIRS = doc dumux m4 test tutorial new_project ... \end{verbatim} -\textbf{Fourth}: In \verb+$DUMUX_ROOT+ there is a file \verb+configure.ac+. In this file, the respective Makefiles are listed. After a line reading +\textbf{Fourth}: In \eWoms base directory there is a file +\texttt{configure.ac}. In this file, the respective Makefiles are +listed. After a line reading - \verb+AC_CONFIG_FILES([Makefile+ + \texttt{AC\_CONFIG\_FILES([Makefile} - \noindent a line, declaring a new Makefile, needs to be included. The Makefile itself will be generated automatically. For keeping track of the included files, inserting in alphabetical order is good practice. The new line could read: \verb+test/New_Project/Makefile+ - -\textbf{Fifth}: Compile \Dumux as described in Section \ref{install}. + \noindent a line, declaring a new Makefile, needs to be added. The + Makefile itself will be generated automatically from the + \texttt{Makefile.am} file which you just generated. For keeping track + of the included files, it is adviced to insert new Makefiles in + alphabetical order. The new line could read: + \texttt{new\_project/Makefile} + \textbf{Fifth}: Run the command \texttt{automake} in the \eWoms base + directory. + + \textbf{Sixth}: Re-compile \eWoms as described in Section \ref{install}. + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "ewoms-handbook" +%%% End: diff --git a/doc/handbook/newton-in-a-nutshell.tex b/doc/handbook/newton-in-a-nutshell.tex index 37d70beda..e43b315a1 100644 --- a/doc/handbook/newton-in-a-nutshell.tex +++ b/doc/handbook/newton-in-a-nutshell.tex @@ -1,64 +1,72 @@ -\chapter{Newton in a Nutshell} +\chapter{The Newton-Raphson method} -For the isothermal immiscible multi-phase model for flow in porous -media, the following mass conservation equation needs to be solved: +For the isothermal immiscible multi-phase model, the following mass +conservation equation needs to be solved: \begin{align} \underbrace{ - \phi \frac{\partial \varrho_\alpha S_\alpha}{\partial t} + \frac{\partial \phi \varrho_\alpha S_\alpha}{\partial t} - \text{div} \left\{ \varrho_\alpha \frac{k_{r\alpha}}{\mu_\alpha} \mbox{\bf K} \left(\text{grad}\, p_\alpha - \varrho_{\alpha} \mbox{\bf g} \right) \right\} - q_\alpha} _ -{\textbf{f}(\textbf{u}^r)} +{\textbf{f}(\textbf{u})} = 0 \; . \end{align} -Because of the nonlinear dependencies (even in this comparativly simple equation) in there, this is a really difficult task. However, for finding roots of of difficult equations there is a really handy method out there: \textsc{Newton}'s method. +Because of the nonlinear dependencies even solving this comparatively +simple equation is a quite challenging task. However, for +finding roots of non-linear systems equations the +\textsc{Newton}-\textsc{Raphson} method can be used. -When using a fully coupled numerical model, one timestep essentially consists of the application of the \textsc{Newton} algorithm to solve the nonlinear system. +When using a fully-implicit numerical model, each time step essentially +consists of the application of the \textsc{Newton} algorithm to solve +the nonlinear system. -One step of the \textsc{Newton} method can be formalized as follows: +The idea of this algorithm is to linearize the non-linear system of +equation at a given solution, and then solving the resulting linear +system of equations. The hope is, that the solution of this linear +system is closer to the root of the non-linear system of +equations. This process is repeated until either convergence is +reached (a pre-determined accuracy is reached), or divergence of the +algorithm is detected (either by trespassing the maximum number of +iterations or by failure to linearize). This method can be formalized +as follows: -\textsc{Newton} method: \begin{subequations} \begin{align} \label{NewtonGen} -\textbf{u}^{r+1} &= \textbf{u}^r - \left(\textbf{f}^\prime (\textbf{u}^r) \right)^{-1} \textbf{f}(\textbf{u}^r) \\ -\Leftrightarrow {\textbf{f}^{\prime}(\textbf{u}^r)} ( \textbf{u}^{r+1}-\textbf{u}^r) &= -\textbf{f}(\textbf{u}^r) \\ -\Leftrightarrow \underbrace{\textbf{f}^{\prime}(\textbf{u}^r)}_{\textnormal{Jacobian}} ( \textbf{u}^r - \textbf{u}^{r+1}) &= \textbf{f}(\textbf{u}^r) \label{NewtonAsUsed} +\textbf{u}^{r+1} &= \textbf{u}^r + \Delta \textbf{u}^r \\ +\Delta \textbf{u}^r & = - \left\{\text{grad}\,\textbf{f} (\textbf{u}^r) \right\}^{-1} \textbf{f}(\textbf{u}^r) \\ \end{align} \end{subequations} \noindent with \begin{itemize} +\item $\textbf{u}$: Vector of unknowns +\item $\textbf{f}(\textbf{u}^r)$: Residual (Function of the vector of unknowns which ought to be set to $0$) \item $\phantom{a}^r$: last iteration, $\phantom{a}^{r+1}$: current iteration, -\item $\phantom{a}^\prime$: derivative -\item $\textbf{u}$: vector of unknowns, the actual primary variables -\item $\textbf{f}(\textbf{u}^r)$: function of vector of unknowns +\item $\text{grad}\,\phantom{a}$: \textsc{Jacobian} matrix of + $\textbf{f}$, i.e. matrix of the derivatives of \textbf{f} regarding + all components of $\textbf{u}$ \end{itemize} -1-D example with slope $m$: -\begin{equation} - m= \frac{y(u^{r+1})-y(u^{r})}{u^{r+1}-u^{r}} \textnormal{ for a root of a function: } m= - \frac{y(u^{r})}{u^{r+1}-u^{r}} -\end{equation} -The value of u (generally a vector of unknowns) for which f becomes zero is searched for. Therefore the quantity of interest is $\textbf{u}^{r+1}$. - -But the (BiCGSTAB / Pardiso / ...) linear solver solves systems of the form: +The value of $\textbf{u}$ for which $\textbf{f}$ becomes zero is +searched for. Bringing \eqref{NewtonGen} into the form used the linear +solvers \begin{equation} \label{GenSysEq} - A\textbf{x} = \textbf{b} . + \textbf{A}\textbf{x} - \textbf{b} = 0 \end{equation} - -Comparing (\ref{GenSysEq}) with (\ref{NewtonAsUsed}) leads to: +leads to \begin{itemize} -\item $\textbf{b} = \textbf{f}(\textbf{u}^r)$ r.h.s. as it is known from the last iteration. Here, $\textbf{f}(\textbf{u}^r)$ is called residual. It is obtained by evaluating the balance equations with the primary variables, as obtained from the last iteration step. -\item $A=\textbf{f}^{\prime}(\textbf{u}^r)$ coefficient matrix or \textsc{Jacobian}. It is obtained by numerical differentiation. Evaluating the balance equations at the last solution + eps, then evaluating the balance equations at the last solution - eps, division by 2eps: numerical differentiation complete. -\item $\textbf{x} = (\textbf{u}^{r+1} - \textbf{u}^{r})$ this is what the linear solver finds as an solution. +\item $\textbf{A} = \text{grad}\,\textbf{f} (\textbf{u}^r)$ +\item $\textbf{x} = \textbf{u}^{r} - \textbf{u}^{r+1}$ +\item $\textbf{b} = \textbf{f}(\textbf{u}^{r})$ \end{itemize} -This is equivalent to stating that the implemented algorithm solves for the change of the solution. Or in other words: until the $\textbf{u}$ does not change with one more \textsc{Newton-}iteration (do not confuse with timestep!). - -In the rest of Dumux (everywhere besides in the solver), not the change of the solution is looked for, but the actual solution is used. Therefore the outcome of the linear solver needs to be reformulated as done in \verb+updateMethod.update(*this, u, *uOld, model);+. In this function the ``change in solution'' is changed to ``solution''. Afterwards the quantity \verb+*u+ stands for the solution. +Once $\textbf{u}^{r} - \textbf{u}^{r+1}$ has been calculated, \eWoms +updates the current solution in \texttt{NewtonController::update()} +and starts the next iteration if the scheme has not yet converged. %%% Local Variables: %%% mode: latex diff --git a/doc/handbook/structure.tex b/doc/handbook/structure.tex index e23f0f897..87d9797de 100644 --- a/doc/handbook/structure.tex +++ b/doc/handbook/structure.tex @@ -1,25 +1,23 @@ -\chapter{Structure, Guidelines, New Folder Setup} +\chapter{Directory structure} -\section{Directory Structure} - -We briefly describe the directory structure of \Dumux in terms +We briefly describe the directory structure of \eWoms in terms of subdirectories, source files, and tests. For more details, the Doxygen documentation should be considered. -\Dumux comes in form of a DUNE module \texttt{dumux}. +\eWoms comes in form of a DUNE module \texttt{dumux}. It has a similar structure as other DUNE modules like \texttt{dune-grid}. The following subdirectories are within the module's root directory, from now on assumed to be \texttt{/}: \begin{itemize} \item \texttt{CMake}: the configuration options -for building \Dumux using CMake. See the file \texttt{INSTALL.cmake} in -the root directory of \texttt{dumux} for details. Of course, +for building \eWoms using CMake. See the file \texttt{INSTALL.cmake} in +the root directory of the \eWoms distribution for details. Of course, it is also possible to use the DUNE buildsystem just like for the other DUNE modules. \item \texttt{doc}: contains the Doxygen documentation in \texttt{doxygen}, -this handbook in \texttt{handbook}, and the \Dumux logo in various formats in +this handbook in \texttt{handbook}, and the \eWoms logo in various formats in \texttt{logo}. The html documentation produced by Doxygen can be accessed as usual, namely, by opening \texttt{doc/doxygen/html/index.html} with a web browser. -\item \texttt{dumux}: the \Dumux source files. See Section \ref{sec:dumux} for details. +\item \texttt{dumux}: the \eWoms source files. See Section \ref{sec:dumux} for details. \item \texttt{test}: tests for each numerical model and the property system. See Section \ref{sec:test} for details. \item \texttt{tutorial}: contains the tutorials described in Chapter \ref{chp:tutorial}. @@ -28,91 +26,91 @@ See Section \ref{sec:test} for details. \subsection{The \texttt{dumux} directory}\label{sec:dumux} -The directory \texttt{dumux} contains the \Dumux source files. It consists of the following subdirectories (see Figure \ref{fig:dumux-structure}): +The directory \texttt{dumux} contains the \eWoms source files. It consists of the following subdirectories (see Figure \ref{fig:dumux-structure}): \begin{itemize} -\item \texttt{boxmodels}: -the general fully implicit box method is contained in the subdirectory -\texttt{common}, while each of the other subdirectories contains -a derived specific numerical model. The subdirectory \texttt{common} also contains the file \texttt{boxfvelementgeometry.hh} employed by the box method to extract the dual mesh geometry information out of the primal one. -% The files \texttt{pdelabboxassembler.hh} and \texttt{pdelabboxlocaloperator.hh} allow the use of the DUNE module \texttt{dune-pdelab}. +\item \texttt{boxmodels}: The fully implicit vertex-centered finite + volume (box) method. This directory features the following + sub-directories + \begin{itemize} + \item \texttt{common}: The infrastructural code shared by all box + models; For example it contains the file + \texttt{boxfvelementgeometry.hh} which is used by the box scheme to + construct the dual grid out of the primal one. + \item \texttt{modules}: This directory features parts which can be + re-used by multiple models, like a generic plug-in for the energy + equation, models for determining the filter velocity, or plugins + describing molecular diffusion. + \item Each of the other subdirectories contains + a physical numerical model which uses the box discretization. + \end{itemize} -\item \texttt{common}: -general stuff like the property system and the time management for the -fully coupled as well as the decoupled models, -% the interface for the Pardiso direct solver library \cite{Pardiso}, -and the \texttt{start.hh} file that includes the common routine for starting a model called in the main function. +\item \texttt{common}: General stuff like the \eWoms property system + and classes for managing time which are shared by the fully-implicit + and the semi-implicit models. For example it features the file + \texttt{start.hh} which provides the default way for starting a + simulation. \item \texttt{decoupled}: - numerical models to solve the pressure equation as part of the fractional flow formulation. The specific models are contained - in corresponding subdirectories. In each model folder are subdirectories for the implicit pressure equation sorted by the employed discretization method, and for the explicit transport equation. The general decoupled formulation for the implicit pressure explicit transport formulation can be found in the subdirectory \texttt{common}. + Numerical models to solve the pressure equation as part of the fractional flow formulation. The specific models are contained + in corresponding subdirectories. In each model folder are subdirectories for the implicit pressure equation sorted by the employed discretization method, and for the explicit transport equation. The general semi-implicit formulation for the implicit pressure, explicit transport formulation can be found in the subdirectory \texttt{common}. -% \item \texttt{fractionalflow}: -% the (non-compositional) fractional flow model, which utilizes the IMPES method -% contained in the subdirectory \texttt{impes}. +\item \texttt{io}: Additional classes that provide in-/output routines + like writing and reading restart files (often called 'checkpoint' + files) and for writing a series of VTK files. -% \item \texttt{functions}: -% the Crouzeix--Raviart function implemented in the style of \texttt{dune-disc}'s P1 function. +\item \texttt{material}: Everything related to material parameters and + constitutive equations. For example, the properties of a pure + chemical substance (e.g. water) or pseudo substance (e.g. air) can + be found in the subdirectory \texttt{components} with the base class + \texttt{components/component.hh}. Fluid systems are located in the + sub-folder \texttt{fluidsystems}, while capillary pressure/relative + permeability laws are located in the sub-folder + \texttt{fluidmatrixinteractions}. Furthermore, the classes computing + binary coefficients like the Henry coefficient or binary diffusion + coefficients are held by the sub-folder \texttt{binarycoefficients}. -% \item \texttt{fvgeometry}: -% employed by the box method to extract the dual mesh geometry information out of the -% primal one. +\item \texttt{nonlinear}: This folder contains an implementation of + the Newton-Raphson method for solving non-linear systems of + equations. -\item \texttt{io}: additional in-/output possibilities like restart files -and a VTKWriter extension. - -\item \texttt{material}: everything related to material parameters and -constitutive equations. The properties of a pure chemical substance (e.g. water) or pseudo substance (e.g. air) can be found in the subdirectory \texttt{components} with the base class \texttt{components/component.hh}. The fluidsytem in the folder \texttt{fluidsystems} collects the information from the respective component and binary coefficients files, and contains the fluid characteristics of phases (e.g. viscosity, density, enthalpy, diffusion coefficients) for compositional or non-compositional multi-phase flow. - -The base class for all spatially dependend variables -- like permeability and porosity -- -can be found in \texttt{spatialparameters}. The base class in \texttt{boxspatialparameters.hh} -also provides spatial averaging routines. All other spatial properties are specified in the specific - files of the respective models. Furthermore, the constitutive relations -- e.g. $p_c(S_w) $ -- are in \texttt{fluidmatrixinteractions}, -while the necessary binary coefficients like the Henry coefficient or binary diffusion coefficients are definded in - \texttt{binarycoefficients}. - - -\item \texttt{nonlinear}: Newton's method. - - -% \item \texttt{operators}: based on \texttt{dune-disc}, assembly operators for Crouzeix--Raviart -% elements and mimetic finite differences. -% -% -% \item \texttt{pardiso}: interface to the Pardiso direct solver library, \cite{Pardiso}. -% -% -% \item \texttt{shapefunctions}: Crouzeix--Raviart element shape functions. -% -% -% \item \texttt{timedisc}: time discretization for the decoupled models. -% -% -% \item \texttt{transport}: numerical models to solve the pressure equation -% as part of the fractional flow formulation analogous to the \texttt{diffusion} -% directory. Moreover, the compositional decoupled models are included here. +\item \texttt{linear}: This folder features code which is required to + parallelize the linear solvers, as well as back-ends for these + solvers. For example it contains classes to calculate an overlap + given the distributed matrix of the linear system, and provides + classes which use this overlap to provide overlapping matrices, + vectors, linear operators and scalar products. +\item \texttt{istl}: This folder contains a copy of slightly modified + linear solvers from the ISTL \Dune module. The reason why they where + copied is to provide linear solvers with better performance and + stability without being held back by the \Dune developers. +\item \texttt{parallel}: Contains some helper classes useful for + programming MPI parallel code. For example this folder contains a + simple MPI buffer class, and various commonly used \Dune + data-handles. \end{itemize} - - \subsection{The directory \texttt{test}}\label{sec:test} - -The directory \texttt{test} contains a test for each numerical model and for -the property system. The tests for the property system can be found in \texttt{common}. -The subfolder \texttt{boxmodels} contains tests for the fully -coupled models (\texttt{1p}, \texttt{1p2c}, \texttt{2p}, \texttt{2p2c}, -\texttt{2p2cni}, \texttt{2pni}, \texttt{3p3c}, \texttt{3p3cni}, \texttt{mpnc} and \texttt{richards}), while the subdirectory \texttt{decoupled} corresponds to the decoupled models. -Each subdirectory contains one or more program files \texttt{test\_*.cc}, where \texttt{*} usually is the -name of the folder. Moreover, the problem definitions can be found -in the \texttt{*problem.hh} files and the definition of the spatially dependent parameters in \texttt{*spatialparameters.hh}. Simply executing the tests should either run the -full test or give a list of required command line arguments. After test execution, -VTK output files should have been generated. -For more detailed descriptions of the tests, the problem definitions and their corresponding -Doxygen documentation should be considered. +The directory \texttt{test} contains at least one test/example for +each numerical model and for each important aspect of the common +\eWoms infrastructure. The directory \texttt{common} contains a test +for the property system. The sub-directory \texttt{boxmodels} +contains test applications for the fully-implicit models (where each +test is named according to the scheme \texttt{PROBLEMNAME\_MODDEL}), +while the subdirectory \texttt{decoupled} features tests for the +semi-implicit models. Each subdirectory contains one or more program +files \texttt{*.cc} which contain the main function for the +test. Moreover, the problem definitions can be found in the +\texttt{*problem.hh} files. Simply executing the tests should either +run the full test or give a list of required command line +arguments. After test execution, VTK output files are generated by +most tests. For more detailed descriptions of the tests, the problem +definitions and their corresponding Doxygen documentation should be +considered. \begin{landscape} \begin{figure}[hbt] @@ -120,7 +118,7 @@ Doxygen documentation should be considered. \includegraphics[width=\linewidth, keepaspectratio]{EPS/ewoms_structure.eps} \caption{ \label{fig:dumux-structure} - Structure of the \eWoms source tree. + Structure \texttt{dumux} sub-directory of the \eWoms source tree. } \end{figure} \end{landscape} diff --git a/doc/handbook/tutorial-decoupled.tex b/doc/handbook/tutorial-decoupled.tex index 61dc2ffe0..243552fbc 100644 --- a/doc/handbook/tutorial-decoupled.tex +++ b/doc/handbook/tutorial-decoupled.tex @@ -1,13 +1,6 @@ -\section[Decoupled model]{Solving a problem using a Decoupled Model}\label{tutorial-decoupled} -The process of solving a problem using \Dumux can be roughly divided into four parts: -\begin{enumerate} - \item The geometry of the problem and correspondingly a grid have to be defined. - \item Material properties and constitutive relationships have to be defined. - \item Boundary conditions as well as initial conditions have to be defined. - \item A suitable model has to be chosen. -\end{enumerate} +\section[Semi-implicit model]{Solving a problem using a Semi-implicit Model}\label{tutorial-decoupled} -In contrast to the last section, we now apply a decoupled solution procedure, a +In contrast to the last section, we now apply a semi-implicit solution procedure, a so-called \textit{IMPET} (\textit{IM}plicit \textit{P}ressure \textit{E}xplicit \textit{T}ransport) algorithm. This means that the pressure equation is first solved using an implicit method. The resulting velocities are then used to solve @@ -16,8 +9,8 @@ In this tutorial, pure fluid phases are solved with a finite volume discretizati of both pressure- and transport step. Primary variables, according to default settings of the model, are the pressure and the saturation of the wetting phase. -The problem which is solved in this tutorial is illustrated in figure -\ref{tutorial-decoupled:problemfigure}. A rectangular domain with no flow +The problem which is solved in this tutorial is the same as for the previous tutorial and is illustrated in figure +\ref{tutorial-decoupled:problemfigure}: A rectangular domain with no flow boundaries on the top and at the bottom, which is initially saturated with oil, is considered. Water infiltrates from the left side into the domain. Gravity effects are neglected. @@ -39,46 +32,46 @@ effects are neglected. \caption{Geometry of the tutorial problem with initial and boundary conditions.}\label{tutorial-decoupled:problemfigure} \end{figure} -Listing \ref{tutorial-decoupled:mainfile} shows how the main file, which has to be executed, has to be set up, if the problem described above is to be solved using a decoupled model. This main file can be found in the directory \texttt{/tutorial} of the stable part of \Dumux. +Listing \ref{tutorial-decoupled:mainfile} shows how the main file, which has to be executed, has to be set up, if the problem described above is to be solved using a semi-implicit model. This main file can be found in the directory \texttt{/tutorial} below the \eWoms base directory. \begin{lst}[File tutorial/tutorial\_decoupled.cc]\label{tutorial-decoupled:mainfile} \mbox{} -\lstinputlisting[style=eWomsCode, numbersep=5pt, firstline=24, firstnumber=24]{../../tutorial/tutorial_decoupled.cc} +\lstinputlisting[style=eWomsCode, numbersep=5pt, firstline=26, firstnumber=26]{../../tutorial/tutorial_decoupled.cc} \end{lst} First, from line \ref{tutorial-decoupled:include-begin} to line -\ref{tutorial-decoupled:include-end} the \Dune and \Dumux files containing +\ref{tutorial-decoupled:include-end} the \Dune and \eWoms files containing essential functions and classes are included. At line \ref{tutorial-decoupled:set-type-tag} the type tag of the problem which is going to be simulated is set. All other data types -can be retrieved by the \Dumux property system and only depend on this +can be retrieved by the \eWoms property system and only depend on this single type tag. For an introduction to the property system, see section \ref{sec:propertysystem}. -After this \Dumux' default startup routine \texttt{Dumux::start()} is +After this, \eWoms' default startup routine \texttt{Dumux::start()} is called in line \ref{tutorial-decoupled:call-start}. This function deals -with parsing the command line arguments, reading the parameter file, +with parsing the command line arguments, setting up the infrastructure necessary for \Dune, loading the grid, and starting the simulation. All parameters can be either specified by command line arguments of the form -(\texttt{--ParameterName=ParameterValue}), in the file specified by the +(\texttt{--ParameterName=ParameterValue}), or in the file specified by the \texttt{--ParameterFile=filename.ini} argument. If a parameter is specified on the command line as well as in the parameter file, the -values provided in the command line have +values provided in the command line takes precedence. \subsection{The problem class} \label{decoupled_problem} -When solving a problem using \Dumux, the most important file is the +When solving a problem using \eWoms, the most important file is the so-called \textit{problem file} as shown in listing \ref{tutorial-decoupled:problemfile} of \texttt{tutorialproblem\_decoupled.hh}. \begin{lst}[File tutorial/tutorialproblem\_decoupled.hh]\label{tutorial-decoupled:problemfile} \mbox{} -\lstinputlisting[style=eWomsCode, numbersep=5pt, firstline=24, firstnumber=24]{../../tutorial/tutorialproblem_decoupled.hh} +\lstinputlisting[style=eWomsCode, numbersep=5pt, firstline=27, firstnumber=27]{../../tutorial/tutorialproblem_decoupled.hh} \end{lst} -First, both \Dune grid handlers and the decoupled model of \Dumux +First, both \Dune grid handlers and the semi-implicit model of \eWoms have to be included. Then, a new type tag is created for the problem in line \ref{tutorial-decoupled:create-type-tag}. In this case, the new type tag inherits all properties defined for the \texttt{DecoupledTwoP} @@ -88,13 +81,13 @@ is chosen as discretization scheme (defined via the include in line a problem class is attached to the new type tag, while the grid which is going to be used is defined in line \ref{tutorial-decoupled:set-grid-type} -- in this case an \texttt{YaspGrid} is created. Since there's no uniform mechanism to -allocate grids in \Dune, \Dumux features the concept of grid creators. +allocate grids in \Dune, \eWoms features the concept of grid creators. In this case the generic \texttt{CubeGridCreator} (line \ref{tutorial-decoupled:set-gridcreator}) which creates a structured hexahedron grid of a specified size and resolution. For this grid creator the physical domain of the grid is specified via the -run-time parameters \texttt{Grid.upperRightX}, -\texttt{Grid.upperRightY}, \texttt{Grid.numberOfCellsX} and -\texttt{Grid.numberOfCellsY}. These parameters can be specified via +run-time parameters \texttt{DomanSizeX}, +\texttt{DomanSizeY}, \texttt{CellsX} and +\texttt{CellsY}. These parameters can be specified via the command-line or in a parameter file. For more information about the \Dune grid interface, the different grid types that are supported and the generation of different grids consult @@ -102,45 +95,45 @@ the \textit{Dune Grid Interface HOWTO} \cite{DUNE-HP}. Next, we select the material of the simulation: In the case of a pure two-phase model, each phase is a bulk fluid, and the complex (compositional) fluidsystems -do not need to be used. However, they can be used (see exercise 1 \ref{dec-ex1-fluidsystem}). -Instead, we use a simplified fluidsystem container that provides classes -for liquid and gas phases, line \ref{tutorial-decoupled:2p-system-start} to -\ref{tutorial-decoupled:2p-system-end}. These are linked to the appropriate -chemical species in line \ref{tutorial-decoupled:wettingPhase} and +do not need to be used. However, they can be used (see exercise 1e). +Instead, we use a simplified fluidsystem that wraps pure component classes +for the liquid and gas phases. This is done from line \ref{tutorial-decoupled:2p-system-start} to +\ref{tutorial-decoupled:2p-system-end}. These components represent fluids made of pure +chemical species, but given the fact, that a even pure chemical species can assume two phases, only their respective liquid phase is selected on lines \ref{tutorial-decoupled:wettingPhase} and \ref{tutorial-decoupled:nonwettingPhase}. For all parameters that depend on space, such as the properties of the soil, the specific spatial parameters for the problem of interest are specified in line \ref{tutorial-decoupled:set-spatialparameters}. -Now we arrive at some model parameters of the applied two-phase decoupled -model. First, in line \ref{tutorial-decoupled:cflflux} a flux function for the evaluation of the cfl-criterion is defined. This is optional as there exists also a default flux function. The choice depends on the problem which has to be solved. For cases which are not advection dominated the one chosen here is more reasonable. +Now we arrive at some model parameters of the applied two-phase semi-implicit +model. First, in line \ref{tutorial-decoupled:cflflux} a flux function for the evaluation of the CFL-criterion is defined. This is optional as there exists also a default flux function. The choice depends on the problem which has to be solved. For cases which are not advection dominated, the one chosen here is more reasonable. Line \ref{tutorial-decoupled:cflfactor} assigns the CFL-factor to be used in the -simulation run, which scales the time step size (kind of security factor). The last property in line \ref{tutorial-decoupled:gravity} -is optional and tells the model not to use gravity. +simulation run, which scales the time step size (kind of security factor). The next property, defined on line \ref{tutorial-decoupled:gravity} +is optional and tells the model to disregard gravity. +Finally, the default dimensions of the size of the physical and temporal +domains are defined on lines +\ref{tutorial-decoupled:domain-defaults-begin} to +\ref{tutorial-decoupled:domain-defaults-end}. -After all necessary information is written into the property system and -its namespace is closed in line \ref{tutorial-decoupled:propertysystem-end}, +After all necessary properties are defined and +its \texttt{Properties} namespace is closed in line \ref{tutorial-decoupled:propertysystem-end}, the problem class is defined in line \ref{tutorial-decoupled:def-problem}. As its property, the problem class itself is also derived from a parent, -\texttt{IMPESProblem2P}. The class constructor (line -\ref{tutorial-decoupled:constructor-problem}) is able to hold two vectors, -which is not needed in this tutorial. +\texttt{IMPESProblem2P}. -Beside the definition of the boundary and initial conditions (discussed in -subsection \label{decoupled-problem:boundary}), the problem class also contains -general information about the current simulation. First, the name used by -the \texttt{VTK-writer} to generate output is defined in the method of line +Beside the definition of the boundary and initial conditions, the problem class also provides +general information about the current simulation. First, the name used by for the +resulting VTK output files is defined by the \texttt{name()} method of line \ref{tutorial-decoupled:name}, and line \ref{tutorial-decoupled:restart} indicates -whether restart files are written. As decoupled schemes usually feature small -timesteps, it can be usefull to set an output interval larger than 1. The respective function is called in line \ref{tutorial-decoupled:outputinterval}, which gets the output interval as argument. +when and whether restart files are written. As semi-implicit schemes usually feature small +timesteps, it can be useful to set an output interval larger than 1. The respective function is called in line \ref{tutorial-decoupled:outputinterval}, which gets the output interval as argument. The following methods all have in common that they may be dependent on space. Hence, they all have either an \texttt{element} or an \texttt{intersection} as their function argument: Both are \Dune entities, depending on whether the parameter of the method is defined in an element, such as - initial values, or on an intersection, such as a boundary condition. As it may be sufficient to return values only based on a position, \Dumux models can also access functions in the problem with the form \mbox{\texttt{...AtPos(GlobalPosition\& globalPos)}}, without an \Dune entity, as one can see in line \ref{tutorial-decoupled:bctype}. + initial values, or on an intersection, such as a boundary condition. As it may be sufficient to return values only based on a position, \eWoms models can also access functions in the problem with the form \mbox{\texttt{...AtPos(GlobalPosition\& globalPos)}}, without an \Dune entity, as one can see in line \ref{tutorial-decoupled:bctype}. -There are the methods for general parameters, source- or -sinkterms, boundary conditions (lines \ref{tutorial-decoupled:bctype} to +There are also methods for terms of the partial differential equations which must be provided such as the source term, boundary conditions (lines \ref{tutorial-decoupled:bctype} to \ref{tutorial-decoupled:neumann}) and initial values for the transported quantity in line \ref{tutorial-decoupled:initial}. For more information on the functions, consult the documentation in the code. @@ -151,16 +144,17 @@ Listing \ref{tutorial-decoupled:spatialparametersfile} shows the file \verb+tutorialspatialparams_decoupled.hh+: \begin{lst}[File tutorial/tutorialspatialparams\_decoupled.hh]\label{tutorial-decoupled:spatialparametersfile} \mbox{} -\lstinputlisting[style=eWomsCode, numbersep=5pt, firstline=24, firstnumber=24]{../../tutorial/tutorialspatialparams_decoupled.hh} +\lstinputlisting[style=eWomsCode, numbersep=5pt, firstline=27, firstnumber=27]{../../tutorial/tutorialspatialparams_decoupled.hh} \end{lst} -The argument list here is the same as for the problem +The argument list for its methods here is the same as for the problem functions: Either an \texttt{element}, or only the global position if the function is called \texttt{...AtPos(...)}. \subsection{Exercises} \label{tutorial-deoucpled:exercises} -The following exercises will give you the opportunity to learn how you can change -soil parameters, boundary conditions and fluid properties in \Dumux and to play along -with the decoupled modelling framework. +The following exercises will give you the opportunity to learn how you +can change soil parameters, boundary conditions and fluid properties +in \eWoms and is intended to give you an opportunity to play with the +semi-implicit modelling framework. \subsubsection{Exercise 1} \renewcommand{\labelenumi}{\alph{enumi})} @@ -168,33 +162,71 @@ For Exercise 1 you only have to make some small changes in the tutorial files. \begin{enumerate} \item \textbf{Altering output} -To get an impression what the results should look like you can first run the original version of the decoupled tutorial model by typing \texttt{./tutorial\_decoupled}. The runtime parameters which are set printed at the start of the simulation. If the input file has the same name than the main file (e.g. \texttt{tutorial\_decoupled.cc} and \texttt{tutorial\_decoupled.input}), it is automatically chosen. If the name differs the program has to be started typing \texttt{./tutorial\_decoupled -parameterFile .input}. For more options you can also type \texttt{./tutorial\_decoupled -h}. For the visualisation with paraview please refer to \ref{quick-start-guide}.\\ -As you can see, the simulation creates many output files. To reduce these in order to perform longer simulations, change the method responsible for output (line \ref{tutorial-decoupled:outputinterval} in the file \texttt{tutorialproblem\_decoupled}) as to write an output only every 20 timesteps. Compile the main file by typing \texttt{make tutorial\_decoupled} and run the model. Now, run the simulation for 5e5 seconds. + To get an impression what the results should look like, you can run + the unmodified version of the semi-implicit tutorial problem by + typing \texttt{./tutorial\_decoupled}. The runtime parameters which + are set printed at the start of the simulation. You may either + specify values for them on the command line by passing the program + \texttt{--ParameterName=Value} arguments, or by putting parameters + into a filie and instructing the program to load it by adding the + command line option \texttt{--ParameterFile=filename}. For a + description of the available parameters options you add the + \texttt{--help} command line argument to the program. For the + visualizing the output using paraview please refer to + \ref{quick-start-guide}. -\item \textbf{Changing the Model Domain and the Boundary Conditions} \\ + As you can see, the simulation creates many output files. To reduce + these in order to perform longer simulations, change the method + responsible for output (line \ref{tutorial-decoupled:outputinterval} + in the file \texttt{tutorialproblem\_decoupled}) so that it only + writes an output file every 20 time steps. Re-compile the program by + typing \texttt{make tutorial\_decoupled} and run it again. Now, run + the simulation for $500\;000$ seconds. + +\item \textbf{Changing the Model Domain} \\ Change the size of the model domain so that you get a rectangle with edge lengths of x = 300 m \\ and y = 300 m and with discretisation lengths of $\Delta \text{x} = 20$ m and $\Delta \text{y} = 10$ m. \\ + + +\item \textbf{Changing the Boundary Conditions} \\ Change the boundary conditions in the file \texttt{tutorialproblem\_decoupled.hh} so that water enters from the bottom and oil flows out at the top boundary. The right and the left boundary should be closed for water and oil fluxes. The Neumannn Boundary conditions are multiplied by the normal (pointing outwards), so an influx is negative, an outflux always positive. Such information can easily be found in the documentation of the functions (also look into base classes). \item \textbf{Changing Fluids} \\ -Now you can change the fluids. Use DNAPL instead of Oil and Brine instead of Water. To do that you have to select different components via the property system in the problem file: +Now change the fluids: Use DNAPL instead of LNAPL and brine instead of water. To do that you have to select different components: \begin{enumerate} - \item Brine: The class \texttt{Dumux::Brine} acts as an adapter to the fluid system that alters a pure water class by adding some salt. Hence, the class \texttt{Dumux::Brine} uses a pure water class, such as \texttt{Dumux::H2O}, as a second template argument after the data type \texttt{} as a template argument (be sure to use the complete water class with its own template parameter). - \item DNAPL: A standard set of chemical substances, such as Water and Brine, is already included (via a list of \texttt{\#include ..} commandos) and hence easily accessible by default. This is not the case for the class \texttt{Dumux::SimpleDNAPL}, however, which is located in the folder \texttt{dumux/material/components/}. Try to include the file as well as select the component via the property system. + \item Brine: First, you need to add an \texttt{\#include} directive for \texttt{brine.hh}. The class \texttt{Dumux::Brine} is an adapter class that slightly adapts the thermodynamic properties of pure water by adding some salt. Hence, the class \texttt{Dumux::Brine} uses a pure water class, such as \texttt{Dumux::H2O}, as a second template argument after the data type \texttt{} as a template argument. + \item DNAPL: First, you need to change \texttt{\#include} directive from \texttt{lnapl.hh} to \texttt{dnapl.hh}. Then change the fluid used for the non-wetting phase from \texttt{LNAPL} to \texttt{DNAPL} \end{enumerate} -If you want to take a closer look at how the fluid classes are defined and which substances are already available please browse through the files in the directory +If you want to take a closer look at how the fluid classes are defined and which substances are already available you may browse the files in the directory \texttt{/dumux/material/components}. -\item \textbf{Use the \Dumux fluid system}\label{dec-ex1-fluidsystem} \\ -\Dumux usually organizes fluid mixtures via a \texttt{fluidsystem}, see also chapter \ref{sec:fluidframework}. In order to include a fluidsystem you first have to comment the lines \ref{tutorial-coupled:2p-system-start} to \ref{tutorial-coupled:2p-system-end} in the problem file. If you use eclipse, this can easily be done by pressing \textit{str + shift + 7} -- the same as to cancel the comment later on.\\ -Now include the file \texttt{fluidsystems/h2oairsystem.hh} in the material folder, and set a property \texttt{FluidSystem} with the appropriate type, \texttt{Dumux::H2OAirFluidSystem}. However, this rather complicated fluidsystem uses tabularized fluid data, which need to be initialized (i.e. the tables need to be filled with values) in the constructor body of the current problem by adding \texttt{GET\_PROP\_TYPE(TypeTag, FluidSystem)::init();}. Remember that the constructor function always has the same name as the respective class, i.e. \texttt{TutorialProblemDecoupled(..)}.\\ -To avoid the initialization, use the simpler version of water \texttt{Dumux::SimpleH2O} or a non-tabulated version \texttt{Dumux::H2O}. This can be done by setting the property \texttt{Components} type \texttt{H2O}, -as is done in all the test problems of the decoupled 2p2c model.\\ -The density of the gas is magnitudes smaller than that of oil, so please decrease the injection rate to $q_n = -3 \times 10^{-4}$ $\left[\frac{\textnormal{kg}}{\textnormal{m}^2 \textnormal{s}}\right]$. Also reduce the simulation duration to 2e4 seconds.\\ -Please reverse the changes of this example, as we still use bulk phases and hence do not need such an extensive fluid system. +\item \textbf{Use an \eWoms fluid system}\label{dec-ex1-fluidsystem} \\ +\eWoms usually organizes fluid mixtures via a \textit{fluid system}, see also chapter \ref{sec:fluidframework}. In order to include a fluid system you first have to comment the lines \ref{tutorial-coupled:2p-system-start} to \ref{tutorial-coupled:2p-system-end} in the problem file.\\ + +Now include the file \texttt{fluidsystems/h2oairsystem.hh} in the +material folder, and set a property \texttt{FluidSystem} with the +appropriate type, +\texttt{Dumux::FluidSystems::H2OAir}. However, this rather +complicated fluidsystem uses tabularized fluid data, which need to be +initialized at startup (i.e. the tables need to be filled with values) +in the constructor body of the current problem by adding +\texttt{GET\_PROP\_TYPE(TypeTag, FluidSystem)::init();}. Remember that +the constructor function always has the same name as the respective +class, i.e. \texttt{TutorialProblemDecoupled(..)}. + +The density of the gas is magnitudes smaller than that of oil, so it +is advisable to decrease the injection rate to $q_n = -3 \cdot 10^{-4} +\frac{\text{kg}}{\text{m}^2 \text{s}}$. Also reduce the simulation +duration to $20\;000$ seconds. + +Before you proceed, please revert the changes made in this exercise, +as we still use bulk phases and hence do not need such an extensive +fluid system. \item \textbf{Heterogeneities} \\ -Set up a model domain with the soil properties given in Figure \ref{tutorial-deoucpled:exercise1_d}. Adjust the boundary conditions so that water is again flowing from left to right. + Set up a model domain with the soil properties given in Figure + \ref{tutorial-deoucpled:exercise1_d}. Adjust the boundary conditions + so that water is again flowing from left to right. \begin{figure}[ht] \psfrag{K1 =}{K $= 10^{-8}\text{ m}^2$} \psfrag{phi1 =}{$\phi = 0.15$} @@ -232,7 +264,7 @@ After this, change the domain size (parameter input file) to match the domain de by figure \ref{tutorial-decoupled:ex2_Domain}. Adapt the problem class so that the boundary conditions are consistent with figure \ref{tutorial-decoupled:ex2_BC}. Initially, the domain is fully saturated -with water and the pressure is $p_w = 2 \times 10^5 \text{Pa}$ . Oil +with water and the pressure is $p_w = 2 \cdot 10^5 \text{Pa}$ . Oil infiltrates from the left side. Create a grid with $20$ cells in $x$-direction and $10$ cells in $y$-direction. The simulation time should be set to $2e4 \text{s}$. @@ -279,24 +311,15 @@ compile the program. \item Further increase the CFL-factor to 2 and investigate the saturation. \end{itemize} -\subsubsection{Exercise 3: Parameter file input.} -As you have experienced, compilation takes quite some time. Therefore, \Dumux 2.1 provides a simple method to read in parameters (such as simulation end time or modelling parameters) via \texttt{Paramter Input Files}. The tests in the Test-folder \texttt{/test/} already use this system.\\ -If you look at the Application in \texttt{/test/boxmodels/2p/}, you see that the main file looks rather empty: The parameter file \texttt{test\_2p.input} is read by a standard start procedure, which is called in the main function. This should be adapted for your problem at hand. The program run has to be called with the parameter file as argument. As this is a basic \Dumux feature, the procedure is the equivalent in the decoupled as in the box models. -In the code, parameters can be read via the macro \texttt{GET\_RUNTIME\_PARAM(TypeTag, Scalar, MyWonderfulGroup.MyWonderfulParameter);}. In \texttt{test\_2p}, \texttt{MyWonderfulGroup} is the group \texttt{SpatialParams} - any type of groups is applicable, if the group definition in the parameter file is enclosed in square brackets. The parameters are then listed thereafter. Try and use as much parameters as possible via the input file, such as lens dimension, grid resolution, soil properties etc. In addition, certain parameters that are specific to the model, such as the \texttt{CFL}-factor, can be assigned in the parameter file without any further action. - -\subsubsection{Exercise 4} +\subsubsection{Exercise 3} Create a new file for benzene called \texttt{benzene.hh} and implement -a new fluid system. (You may get a hint by looking at existing fluid -systems in the directory \verb+/dumux/material/fluidsystems+.) +a new component. (You may get a hint by looking at existing components +in the directory \verb+/dumux/material/components+.) Use benzene as a new fluid and run the model of Exercise 2 with water and benzene. Benzene has a density of $889.51 \, \text{kg} / \text{m}^3$ and a viscosity of $0.00112 \, \text{Pa} \; \text{s}$. - -\subsubsection{Exercise 5} -If both the coupled and the decoupled tutorial are completed, one should have noticed that the function arguments in the problem function differ slighty, as the numerical models differ. However, both are functions that depend on space, so both models can also work with functions based ond \mbox{\texttt{...AtPos(GlobalPosition \& globalPos)}}, no matter if we model coupled or decoupled. Try to formulate a spatial parameters file that works with both problems, the coupled and the decoupled. Therein, only use functions at the position. - %%% Local Variables: %%% mode: latex %%% TeX-master: "ewoms-handbook" diff --git a/examples/tutorialproblem_coupled.hh b/examples/tutorialproblem_coupled.hh index 1fb4048f9..ea9f85a04 100644 --- a/examples/tutorialproblem_coupled.hh +++ b/examples/tutorialproblem_coupled.hh @@ -28,7 +28,7 @@ // The numerical model #include -// The components that are used +// The chemical species that are used #include #include @@ -64,11 +64,13 @@ SET_TYPE_PROP(TutorialProblemCoupled, GridCreator, Dumux::CubeGridCreator >); + Dumux::LiquidPhase >); // Set the non-wetting phase SET_TYPE_PROP(TutorialProblemCoupled, NonwettingPhase, /*@\label{tutorial-coupled:nonwettingPhase}@*/ - Dumux::LiquidPhase >); /*@\label{tutorial-coupled:2p-system-end}@*/ + Dumux::LiquidPhase >); /*@\label{tutorial-coupled:2p-system-end}@*/ // Set the material law SET_PROP(TutorialProblemCoupled, MaterialLaw) diff --git a/examples/tutorialproblem_decoupled.hh b/examples/tutorialproblem_decoupled.hh index 435e47c26..9ee8ef7a0 100644 --- a/examples/tutorialproblem_decoupled.hh +++ b/examples/tutorialproblem_decoupled.hh @@ -96,7 +96,7 @@ SET_SCALAR_PROP(TutorialProblemDecoupled, ImpetCflFactor, 0.95); /*@\label{tutor // Disable gravity SET_BOOL_PROP(TutorialProblemDecoupled, EnableGravity, false); /*@\label{tutorial-decoupled:gravity}@*/ -// define how long the simulation should run [s] +// define how long the simulation should run [s] /*@\label{tutorial-decoupled:domain-defaults-begin}@*/ SET_SCALAR_PROP(TutorialProblemDecoupled, EndTime, 100e3); // define the properties required by the cube grid creator @@ -106,7 +106,7 @@ SET_SCALAR_PROP(TutorialProblemDecoupled, DomainSizeZ, 0.0); SET_INT_PROP(TutorialProblemDecoupled, CellsX, 100); SET_INT_PROP(TutorialProblemDecoupled, CellsY, 1); -SET_INT_PROP(TutorialProblemDecoupled, CellsZ, 0); +SET_INT_PROP(TutorialProblemDecoupled, CellsZ, 0); /*@\label{tutorial-decoupled:domain-defaults-end}@*/ } /*@\label{tutorial-decoupled:propertysystem-end}@*/ /*! \ingroup DecoupledProblems