Commit ba0007e7 authored by Farid Mohammadi's avatar Farid Mohammadi Committed by Hanchuan Wu
Browse files

[doc][handbook] Update handbook to Dumux version 3.4, check the links and improve the language.

parent cf015263
...@@ -42,7 +42,8 @@ ...@@ -42,7 +42,8 @@
% Dune and Dumux logo % Dune and Dumux logo
\newcommand{\Dune}{{DUNE}\xspace} \newcommand{\Dune}{{DUNE}\xspace}
\newcommand{\Dumux}{\texorpdfstring{Du\-Mu$^\text{x}$\xspace}{DuMuX\xspace}} \newcommand{\Dumux}{\texorpdfstring{Du\-Mu$^\text{x}$\xspace}{DuMuX\xspace}}
\newcommand{\DumuxVersion}{3.3} \newcommand{\DumuxVersion}{3.4}
\newcommand{\DumuxOldVersion}{3.3}
\definecolor{dumuxYellow}{HTML}{E19417} \definecolor{dumuxYellow}{HTML}{E19417}
\definecolor{dumuxBlue}{HTML}{0C73CF} \definecolor{dumuxBlue}{HTML}{0C73CF}
...@@ -111,7 +112,7 @@ Universit\"at Stuttgart, Paffenwaldring 61, D-70569 Stuttgart, Germany}\\ ...@@ -111,7 +112,7 @@ Universit\"at Stuttgart, Paffenwaldring 61, D-70569 Stuttgart, Germany}\\
\input{1_introduction} \input{1_introduction}
\chapter{Quick Start}\label{quick-install} \chapter{Quick Start}\label{quick-install}
In this chapter we provide a quick start guide to In this chapter, we provide a quick start guide to
your first \Dumux experience, including an install script with all necessary instructions your first \Dumux experience, including an install script with all necessary instructions
on how to very quickly install the latest release version of \Dumux. on how to very quickly install the latest release version of \Dumux.
You should have a recent working Linux environment. You should have a recent working Linux environment.
...@@ -145,7 +146,7 @@ wonderful \Dumux simulation environment, we've prepared a \Dumux course and exte ...@@ -145,7 +146,7 @@ wonderful \Dumux simulation environment, we've prepared a \Dumux course and exte
This chapter provides an overview of the general structure in \Dumux (\ref{sc_structure}) This chapter provides an overview of the general structure in \Dumux (\ref{sc_structure})
and gives help for basic work with \Dumux and gives help for basic work with \Dumux
(\ref{sc_newfoldersetup}-\ref{sc_developingdumux}). (\ref{sc_newfoldersetup}-\ref{sc_developingdumux}).
Further it presents useful external tools (\ref{sc_externaltools}) and basic Further, it presents useful external tools (\ref{sc_externaltools}) and basic
concepts (\ref{sc_linearsystem}). concepts (\ref{sc_linearsystem}).
\input{5_structure} \input{5_structure}
\input{5_newfoldersetup} \input{5_newfoldersetup}
......
\Dumux aims to be a generic framework for the simulation of multiphase \Dumux aims to be a generic framework for the simulation of multiphase
fluid flow and transport processes in porous media using continuum fluid flow and transport processes in porous media using continuum
mechanical approaches. At the same time, \Dumux aims to deliver mechanical approaches. At the same time, \Dumux aims to deliver
top-notch computational performance, high flexibility, a sound top-notch computational performance, high flexibility, sound
software architecture and the ability to run on anything from single software architecture and the ability to run on anything from single
processor systems to highly parallel supercomputers with specialized processor systems to highly parallel supercomputers with specialized
hardware architectures. hardware architectures.
...@@ -14,11 +14,11 @@ language. ...@@ -14,11 +14,11 @@ language.
One of the more complex issues when dealing with parallel continuum One of the more complex issues when dealing with parallel continuum
models is managing the grids used for the spatial discretization of models is managing the grids used for the spatial discretization of
the physical model. To date, no generic and efficient approach exists the physical model. To date, no generic and efficient approach exists
for all possible cases, so \Dumux is build on top of \Dune, the for all possible cases, so \Dumux is built on top of \Dune, the
\textbf{D}istributed and \textbf{U}nified \textbf{N}umerics \textbf{D}istributed and \textbf{U}nified \textbf{N}umerics
\textbf{E}nvironment~\cite{DUNE-HP}. \Dune provides a generic interface \textbf{E}nvironment~\cite{DUNE-HP}. \Dune provides a generic interface
to many existing grid management libraries such as UG~\cite{UG-HP}, to many existing grid management libraries such as UG~\cite{UG-HP},
ALUGrid~\cite{ALUGRID-HP,alugrid2016} and a few more. ALUGrid~\cite{ALUGRID-HP,alugrid2016}, and a few more.
DUNE also extensively uses template programming in order to DUNE also extensively uses template programming in order to
achieve minimal overhead when accessing the underlying grid achieve minimal overhead when accessing the underlying grid
libraries\footnote{In fact, the performance penalty resulting from the libraries\footnote{In fact, the performance penalty resulting from the
...@@ -42,12 +42,12 @@ which are the cell's vertices. The \Dune grid interface generally ...@@ -42,12 +42,12 @@ which are the cell's vertices. The \Dune grid interface generally
assumes that all entities are convex polytopes, which means that it assumes that all entities are convex polytopes, which means that it
must be possible to express each entity as the convex hull of a set of must be possible to express each entity as the convex hull of a set of
vertices. For the sake of efficiency, all entities are further expressed in terms vertices. For the sake of efficiency, all entities are further expressed in terms
of so-called reference elements which are transformed to the actual of so-called reference elements, which are transformed to the actual
spatial incarnation within the grid by a so-called geometry spatial incarnation within the grid by a so-called geometry
function. Here, a reference element for an function. Here, a reference element for an
entity can be thought of as a prototype for the actual grid entity can be thought of as a prototype for the actual grid
entity. For example, if we used a grid which applied hexahedrons as cells, entity. For example, if we used a grid that applied hexahedrons as cells,
the reference element for each cell would be the unit cube $[0, 1]^3$ the reference element for each cell would be the unit cube $[0, 1]^3$,
and the geometry function would scale and translate the cube so that and the geometry function would scale and translate the cube so that
it matches the grid's cell. A quick overview of reference elements and the it matches the grid's cell. A quick overview of reference elements and the
related numbering can be obtained from the DUNE cheat sheet related numbering can be obtained from the DUNE cheat sheet
...@@ -64,22 +64,22 @@ finite element shape functions, while \texttt{dune-istl} is the ...@@ -64,22 +64,22 @@ finite element shape functions, while \texttt{dune-istl} is the
and provides generic, highly optimized linear algebra routines for and provides generic, highly optimized linear algebra routines for
solving the generated systems. solving the generated systems.
\Dumux comes in form of an additional module \texttt{dumux}. \Dumux comes in the form of an additional module \texttt{dumux}.
It depends on the \Dune core modules It depends on the \Dune core modules
\texttt{dune-common},\texttt{dune-geometry}, \texttt{dune-grid}, \texttt{dune-istl}, and \texttt{dune-localfunctions}. \texttt{dune-common},\texttt{dune-geometry}, \texttt{dune-grid}, \texttt{dune-istl}, and \texttt{dune-localfunctions}.
The main intention of \Dumux is to provide a framework for an easy and efficient The main intention of \Dumux is to provide a framework for easy and efficient
implementation of new physical models for porous media flow problems, implementation of new physical models for porous media flow problems,
ranging from problem formulation and the selection of ranging from problem formulation and the selection of
spatial and temporal discretization schemes as well as nonlinear solvers, spatial and temporal discretization schemes as well as nonlinear solvers,
to general concepts for model coupling. to general concepts for model coupling.
Moreover, \Dumux includes ready to use numerical models and a few example applications. Moreover, \Dumux includes ready-to-use numerical models and a few example applications.
This is the handbook to a new minor version update of \Dumux: version \DumuxVersion. This document is the handbook to a new minor version update of \Dumux: version \DumuxVersion.
The release contains improvements and new features compared to the 3.2 version. The release contains improvements and new features compared to version \DumuxOldVersion.
The update is backwards compatible with the last release 3.2. The update is backwards compatible with the last release \DumuxOldVersion.
To facilitate the transition for our users, we have created a changelog To facilitate the transition for our users, we have created a changelog
helping to update programs from version 3.2 to version \DumuxVersion, and giving an overview over new capabilities. helping to update programs from version \DumuxOldVersion{} to version \DumuxVersion{} and giving an overview of new capabilities.
It is available online: It is available online at
\url{https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/blob/master/CHANGELOG.md}. \url{https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/blob/master/CHANGELOG.md}.
We highly recommend all our users to transition with us to the most recent version of \Dumux We highly recommend all our users to transition with us to the most recent version of \Dumux
and wish everyone an exciting simulation experience. and wish everyone an exciting simulation experience.
...@@ -26,18 +26,18 @@ $ python installdumux.py ...@@ -26,18 +26,18 @@ $ python installdumux.py
\end{lstlisting} \end{lstlisting}
This script will download each of the \Dune-modules that \Dumux depends on at their 2.7 release, This script will download each of the \Dune-modules that \Dumux depends on at their 2.7 release,
as well as \Dumux's \DumuxVersion release. After these individual modules are downloaded, \Dune and \Dumux as well as \Dumux's \DumuxVersion{} release. After these individual modules are downloaded, \Dune and \Dumux
are automatically configured using the command-line script \texttt{dunecontrol}, located in are automatically configured using the command-line script \texttt{dunecontrol}, located in
\texttt{dune-common/bin/dunecontrol}, optimized using configure options defined in the \texttt{cmake.opts} \texttt{dune-common/bin/dunecontrol}, optimized using configure options defined in the \texttt{cmake.opts}
file located in \texttt{dumux/cmake.opts}. The commands beneath the \texttt{\# run dunecontrol} in file located in \texttt{dumux/cmake.opts}. The commands beneath the \texttt{\# run dunecontrol} in
the \texttt{installdumux.sh} script execute this configuration script, so no further steps are required. the \texttt{installdumux.py} script execute this configuration script, so no further steps are required.
More details about the build-system can be found in section \ref{buildIt}. More details about the build-system can be found in section \ref{buildIt}.
\subsection{A first test run of \Dumux} \subsection{A first test run of \Dumux}
When the \texttt{installdumux.sh} script from the subsection above has run successfully, When the \texttt{installdumux.py} script from the subsection above has run successfully,
you run a simple test to ensure that the installation ran correctly. To do this, you can you run a simple test to ensure that the installation ran correctly. To do this, you can
begin by compiling an example problem and running the simulation. You can then visualize begin by compiling an example problem and running the simulation. You can then visualize
the results using ParaView. We recommend looking at a basic single phase groundwater flow problem. the results using ParaView. We recommend looking at a basic single-phase groundwater flow problem.
\begin{enumerate} \begin{enumerate}
\item Navigate to this test in the build directory using: \item Navigate to this test in the build directory using:
\begin{lstlisting}[style=Bash] \begin{lstlisting}[style=Bash]
...@@ -60,11 +60,11 @@ paraview *pvd ...@@ -60,11 +60,11 @@ paraview *pvd
\end{enumerate} \end{enumerate}
These commands are compiled into \texttt{test\_dumux.sh}, which you can download and run These commands are compiled into \texttt{test\_dumux.sh}, which you can download and run
from the same directory from which you ran \texttt{installDumux.sh}. from the same directory from which you ran \texttt{installdumux.py}.
\begin{lstlisting}[style=Bash,escapechar=\%] \begin{lstlisting}[style=Bash,escapechar=\%]
$ wget https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/-/raw/releases/%\DumuxVersion%/bin/util/test_dumux.sh $ wget https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/-/raw/releases/%\DumuxVersion%/bin/util/test_dumux.sh
$ wget sh test_dumux.sh $ wget sh test_dumux.sh
\end{lstlisting} \end{lstlisting}
For further information on how to get started with dumux, see Section \ref{chp:tutorial}. For further information on how to get started with dumux, see section \ref{chp:tutorial}.
Installing \Dumux means that you first unpack \Dune and \Dumux in a root directory, Installing \Dumux means that you first unpack \Dune and \Dumux in a root directory
(section \ref{sc:ObtainingSourceCode}). (section \ref{sc:ObtainingSourceCode}).
In a second step of the installation, all modules are configured with CMake In a second step of the installation, all modules are configured with CMake
(section \ref{buildIt}). (section \ref{buildIt}).
After successful installation of \Dumux, we guide you to start a test application, After the successful installation of \Dumux, we guide you to start a test application,
described in section \ref{quick-start-guide}. described in section \ref{quick-start-guide}.
In section \ref{sec:build-doc}, we explain how to build the \Dumux documentation. In section \ref{sec:build-doc}, we explain how to build the \Dumux documentation.
Lastly, section \ref{sec:external-modules-libraries} provides details on optional libraries and modules. Lastly, section \ref{sec:external-modules-libraries} provides details on optional libraries and modules.
In a technical sense \Dumux is a module of \Dune. In a technical sense, \Dumux is a module of \Dune.
Thus, the installation procedure of \Dumux is the same as that 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-HP}. Details regarding the installation of \Dune are provided on the \Dune website \cite{DUNE-HP}.
...@@ -19,8 +19,8 @@ The \Dumux release and trunk (developer tree) are based on the most recent ...@@ -19,8 +19,8 @@ The \Dumux release and trunk (developer tree) are based on the most recent
\texttt{dune-grid}, \texttt{dune-istl} and \texttt{dune-localfunctions}. \texttt{dune-grid}, \texttt{dune-istl} and \texttt{dune-localfunctions}.
For working with \Dumux, these modules are required. For working with \Dumux, these modules are required.
All \Dune modules, including the \Dumux module, get extracted into a common root directory, as it All \Dune modules, including the \Dumux module, get extracted into a common root directory, as it
is done in an ordinary \Dune installation. is done in a typical \Dune installation.
We usually name our root directory \texttt{DUMUX} but an arbitrary name can be chosen. We usually name our root directory \texttt{DUMUX}, but an arbitrary name can be chosen.
Source code files for each \Dune module are contained in their own sub-directory within the root directory. Source code files for each \Dune module are contained in their own sub-directory within the root directory.
The sub-directories for the modules are named after the module names (depending on how The sub-directories for the modules are named after the module names (depending on how
the modules were obtained, a version number is added to the module name). the modules were obtained, a version number is added to the module name).
...@@ -62,9 +62,6 @@ The newest and maybe unstable developments of \Dune and \Dumux are also provided ...@@ -62,9 +62,6 @@ The newest and maybe unstable developments of \Dune and \Dumux are also provided
Please check the \Dune website \cite{DUNE-HP} for further information on the \Dune development. We always try to keep up with the latest developments of \Dune. Please check the \Dune website \cite{DUNE-HP} for further information on the \Dune development. We always try to keep up with the latest developments of \Dune.
However, the current \Dumux release is based on the stable 2.7 release and it might not compile without further adaptations using the newest versions of \Dune. However, the current \Dumux release is based on the stable 2.7 release and it might not compile without further adaptations using the newest versions of \Dune.
Furthermore, if you wish to install the optional \Dune Grid-Howto, which provides a tutorial
on the Dune grid interface, act similar.
%TODO:currently, no DUNE patches necessary! Uncomment this section in case this changes again in the future. %TODO:currently, no DUNE patches necessary! Uncomment this section in case this changes again in the future.
% %
% \paragraph{Patching \Dune or external libraries} % \paragraph{Patching \Dune or external libraries}
...@@ -97,7 +94,7 @@ on the Dune grid interface, act similar. ...@@ -97,7 +94,7 @@ on the Dune grid interface, act similar.
\section{Building \Dune and \Dumux} \section{Building \Dune and \Dumux}
\label{buildIt} \label{buildIt}
Configuring \Dune and \Dumux is done by the shell-command \texttt{dunecontrol} which is part of the \Dune build system. Configuring \Dune and \Dumux is done by the shell-command \texttt{dunecontrol}, which is part of the \Dune build system.
If you are interested in more details about the build system that is used, If you are interested in more details about the build system that is used,
they can be found in the \Dune build system documentation\footnote{\url{https://www.dune-project.org/buildsystem/}} and they can be found in the \Dune build system documentation\footnote{\url{https://www.dune-project.org/buildsystem/}} and
CMake's documentation\footnote{\url{https://cmake.org/documentation/}}. CMake's documentation\footnote{\url{https://cmake.org/documentation/}}.
...@@ -126,19 +123,19 @@ $ ./dune-common/bin/dunecontrol --opts=my-cmake.opts all ...@@ -126,19 +123,19 @@ $ ./dune-common/bin/dunecontrol --opts=my-cmake.opts all
Sometimes, it is necessary to have additional options which Sometimes, it is necessary to have additional options which
are specific to a package set of an operating system or are specific to a package set of an operating system or
sometimes you have your own preferences. sometimes you have your own preferences.
Feel free to work with your own set of options, which may evolve over time. Feel free to work with your own set of options, which may change over time.
The option file that comes with the distribution is to be understood more as a starting point The option file, that comes with the distribution, is to be understood more as a starting point
for setting up an own customization than as something which is fixed. for setting up own customization than as something which is fixed.
The use of external libraries can make it necessary to add quite many options in an option file. The use of external libraries can make it necessary to add quite many options in an option file.
It can be helpful to give your customized option file its own name, as done above, It can be helpful to give your customized option file a unique name, as done above,
to avoid confusing it with the option files which came out of the distribution. to avoid confusing it with the option files which came out of the distribution.
\section{The First Run of a Test Application} \section{The First Run of a Test Application}
\label{quick-start-guide} \label{quick-start-guide}
The previous section showed how to install and compile \Dumux. This section The previous section showed how to install and compile \Dumux. This section
shall give a very brief introduction how to run a first test application and how shall give a very brief introduction on how to run a first test application and how
to visualize the first output files.\par to visualize the first output files.\par
All executables are compiled in the \texttt{build} sub-directories of \Dumux. All executable files are compiled in the \texttt{build} sub-directories of \Dumux.
If not specified differently in the options file, this is \texttt{build-cmake} as default. If not specified differently in the options file, this is \texttt{build-cmake} as default.
\begin{enumerate} \begin{enumerate}
...@@ -147,7 +144,7 @@ If not specified differently in the options file, this is \texttt{build-cmake} a ...@@ -147,7 +144,7 @@ If not specified differently in the options file, this is \texttt{build-cmake} a
type \texttt{./test{\_}2p{\_}incompressible{\_}tpfa params.input} type \texttt{./test{\_}2p{\_}incompressible{\_}tpfa params.input}
into the console. into the console.
The added \texttt{params.input} specifies that all The added \texttt{params.input} specifies that all
important run-time parameters (like first time step size, end of simulation and location important run-time parameters (such as first time step size, end of simulation and location
of the grid file) can be found in a text file in the same directory with the of the grid file) can be found in a text file in the same directory with the
name \texttt{params.input}. name \texttt{params.input}.
\item The simulation starts and produces some VTU output files and also a PVD \item The simulation starts and produces some VTU output files and also a PVD
...@@ -155,7 +152,7 @@ If not specified differently in the options file, this is \texttt{build-cmake} a ...@@ -155,7 +152,7 @@ If not specified differently in the options file, this is \texttt{build-cmake} a
files. It is possible to stop a running application by pressing $<$Ctrl$><$c$>$. files. It is possible to stop a running application by pressing $<$Ctrl$><$c$>$.
\item You can display the results using the visualization tool ParaView (or \item You can display the results using the visualization tool ParaView (or
alternatively VisIt). Just type \texttt{paraview} in the console and open the alternatively VisIt). Just type \texttt{paraview} in the console and open the
PVD file. On the upper left hand side, you can choose the desired parameter to be displayed. PVD file. On the upper left-hand side, you can choose the desired parameter to be displayed.
\end{enumerate} \end{enumerate}
\section{Building Documentation} \section{Building Documentation}
...@@ -167,29 +164,30 @@ in the \texttt{CONFIGURE\_FLAGS} of the building options, see section \ref{build ...@@ -167,29 +164,30 @@ in the \texttt{CONFIGURE\_FLAGS} of the building options, see section \ref{build
\subsection{Doxygen} \subsection{Doxygen}
\label{sec:build-doxy-doc} \label{sec:build-doxy-doc}
Doxygen documentation is done by specifically formatted comments integrated in the source code, Doxygen documentation is done by specifically formatted comments included in the source code,
which can get extracted by the program \texttt{doxygen}. Beside extracting these comments, which can get extracted by the program \texttt{doxygen}. Besides extracting these comments,
\texttt{doxygen} builds up a web-browsable code-structure documentation \texttt{doxygen} builds up a web-browsable code-structure documentation
like class hierarchy of code displayed as graphs, see \url{http://www.stack.nl/~dimitri/doxygen/}. like class hierarchy of code displayed as graphs, see \url{https://www.doxygen.nl/index.html}.
The Doxygen documentation of a module can be built if \texttt{doxygen} is installed, The Doxygen documentation of a module can be built by running \texttt{dunecontrol} (if \texttt{doxygen} is installed), entering the \texttt{build-*}directory, and executing
by running \texttt{dunecontrol}, entering the \texttt{build-*}directory, and executing
\texttt{make doc}. Then point your web browser to the file \texttt{make doc}. Then point your web browser to the file
\texttt{MODULE\_BUILD\_DIRECTORY/doc/doxygen/html/index.html} to read the generated documentation. \texttt{MODULE\_BUILD\_DIRECTORY/doc/doxygen/html/index.html} to read the generated documentation.
This should also work for other \Dune modules. This should also work for other \Dune modules.
\subsection{Handbook} \subsection{Handbook}
To build the \Dumux handbook go into the \texttt{build-}directory and To build the \Dumux handbook, navigate to the \texttt{build-}directory and
run \texttt{make doc} or \texttt{make doc\_handbook\_0\_\\dumux-handbook\_pdf}. The pdf can then be found run \texttt{make doc} or \texttt{make doc\_handbook\_0\_\\dumux-handbook\_pdf}. The pdf can then be found
in \texttt{MODULE\_BUILD\_DIRECTORY/doc/handbook/0\_dumux\\-handbook.pdf}. in \texttt{MODULE\_BUILD\_DIRECTORY/doc/handbook/0\_dumux\\-handbook.pdf}.
\section{External Libraries and Modules} \label{sec:external-modules-libraries} \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. 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% If you are going to use an external library, check the information provided on the \Dune website%
\footnote{DUNE: External libraries, \url{https://www.dune-project.org/doc/external-libraries/}}. \footnote{DUNE: External libraries, \url{https://www.dune-project.org/doc/external-libraries/}}. You can consult the \Dune website for higher-level \Dune modules, such as Grid Modules
If you are going to use an external \Dune module, the website on external modules% \footnote{DUNE: Grid modules, \url{https://www.dune-project.org/groups/grid/}},
\footnote{DUNE: External modules, \url{https://www.dune-project.org/groups/external/}} Discretization Modules
can be helpful. \footnote{DUNE: Discretization modules, \url{https://www.dune-project.org/groups/disc/}},
and Extension Modules
\footnote{DUNE: Extension modules, \url{https://www.dune-project.org/groups/extension/}}.
Installing an external library can require additional libraries which are also used by \Dune. 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. For some libraries, such as BLAS or MPI, multiple versions can be installed on the system.
...@@ -199,10 +197,7 @@ Some of the libraries are then compiled within that directory and are not instal ...@@ -199,10 +197,7 @@ Some of the libraries are then compiled within that directory and are not instal
a different place, but \Dune may need to know their location. Thus, one may have to refer to a different place, but \Dune 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-cmake.opts}. them as options for \texttt{dunecontrol}, for example via the options file \texttt{my-cmake.opts}.
Make sure you compile the required external libraries before you run \texttt{dunecontrol}. Make sure you compile the required external libraries before you run \texttt{dunecontrol}.
An easy way to install some of the libraries and modules, given below, is the \texttt{installexternal.py} script located in \texttt{bin}. The script has to be called from your common root directory.
An easy way to install some of the libraries and modules given below is the
\texttt{installexternal.sh} script located in \texttt{bin}. The script
has to be called from your common root directory.
\subsection{List of External Libraries and Modules} \subsection{List of External Libraries and Modules}
...@@ -270,9 +265,9 @@ depending on which modules of \Dune and which external libraries you use. ...@@ -270,9 +265,9 @@ depending on which modules of \Dune and which external libraries you use.
\section{Backwards Compatibility} \section{Backwards Compatibility}
\label{sec:backwardscompatibility} \label{sec:backwardscompatibility}
Dumux Releases are split into major (e.g. 2.0, 3.0) and minor (e.g. 3.1, 3.2, 3.3) releases. Dumux Releases are split into major (e.g. 2.0, 3.0) and minor (e.g. 3.1, 3.2, 3.3, 3.4) releases.
Major releases are not required to maintain backwards compatibility, Major releases are not required to maintain backwards compatibility
but would provide a detailed guide on how to update dependent modules. but would provide a detailed guide on updating dependent modules.
For each minor release, maintaining backwards compatibility is strongly encouraged and recommended. For each minor release, maintaining backwards compatibility is strongly encouraged and recommended.
Maintaining backwards compatibility means for all changes made to the dumux master, each tests and all dumux dependent modules should still compile. In addition, the user should be warned at compile time of any relevant interface changes. This can be done by deprecating the old method with a deprecation message and forwarding it to the new method. Examples of this are shown in the \href{https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/blob/master/CONTRIBUTING.md}{contribution guide}. Each of these deprecation messages should also include the release in which the interface will be removed, and all changes should be documented thoroughly in the \href{https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/-/blob/master/CHANGELOG.md}{changelog.md}. Maintaining backwards compatibility means for all changes made to the dumux master, each tests and all dumux dependent modules should still compile. In addition, the user should be warned at compile time of any relevant interface changes. This can be done by deprecating the old method with a deprecation message and forwarding it to the new method. Examples of this are shown in the \href{https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/blob/master/CONTRIBUTING.md}{contribution guide}. Each of these deprecation messages should also include the release in which the interface will be removed, and all changes should be documented thoroughly in the \href{https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/-/blob/master/CHANGELOG.md}{changelog.md}.
......
...@@ -26,7 +26,7 @@ $ wget https://git.iws.uni-stuttgart.de/dumux-repositories/dumux-course/raw/rele ...@@ -26,7 +26,7 @@ $ wget https://git.iws.uni-stuttgart.de/dumux-repositories/dumux-course/raw/rele
This script will install \texttt{dumux}, it's Dune dependencies, and the \texttt{dumux-course} This script will install \texttt{dumux}, it's Dune dependencies, and the \texttt{dumux-course}
repository. Within the directory \texttt{dumux-course} there are a series of exercises repository. Within the directory \texttt{dumux-course} there are a series of exercises
and slides describing the previously described examples. The course can also be added to your existing and slides describing the previously described examples. The course can also be added to your existing
dumux installation using the \texttt{installExternal.sh} script and the argument \texttt{course}.\par dumux installation using the \texttt{installExternal.py} script and the argument \texttt{course}.\par
% %
The \Dumux course will be updated with each \Dumux release. The \Dumux course will be updated with each \Dumux release.
The above script will download the correct version (\textbf{releases/\DumuxVersion}) of both The above script will download the correct version (\textbf{releases/\DumuxVersion}) of both
......
...@@ -9,7 +9,7 @@ can be found in the \texttt{test}-directory. %An overview over the available tes ...@@ -9,7 +9,7 @@ can be found in the \texttt{test}-directory. %An overview over the available tes
Another possibility to gain more experience with \Dumux is the \texttt{dumux-lecture} module Another possibility to gain more experience with \Dumux is the \texttt{dumux-lecture} module
that contains different application examples that are used in the lectures at the that contains different application examples that are used in the lectures at the
Department of Hydromechanics and Modelling of Hydrosystems in Stuttgart. Department of Hydromechanics and Modelling of Hydrosystems in Stuttgart.
The \texttt{dumux-lecture} module can be obtained with the \texttt{installExternal.sh} The \texttt{dumux-lecture} module can be obtained with the \texttt{installExternal.py}
script and the argument \texttt{lecture}. script and the argument \texttt{lecture}.
The module is structured based on the different lectures: The module is structured based on the different lectures:
...@@ -18,13 +18,13 @@ The module is structured based on the different lectures: ...@@ -18,13 +18,13 @@ The module is structured based on the different lectures:
\item efm: Environmental Fluid Mechanics, \item efm: Environmental Fluid Mechanics,
\item mhs: Modelling of Hydrosystems. \item mhs: Modelling of Hydrosystems.
\end{itemize} \end{itemize}
The majority of applications is covered in the course Multiphase Modelling (mm), The majority of applications are covered in the course Multiphase Modelling (mm),
while there are also some basic examples in the while there are also some basic examples in the
courses Environmental Fluid Mechanics (efm) and Modelling of Hydrosystems (mhs). courses Environmental Fluid Mechanics (efm) and Modelling of Hydrosystems (mhs).
These applications are primarily designed to enhance the understanding of conceptualizing the These applications are primarily designed to enhance the understanding of conceptualizing the
governing physical processes and their implementation in a numerical simulator. governing physical processes and their implementation in a numerical simulator.
Different aspects of modeling multi-phase multi-component flow and transport processes are shown. Different aspects of modeling multi-phase multi-component flow and transport processes are shown.
The lectures focus on questions like the assignment of boundary conditions, the choice of the The lectures focus on questions such as the assignment of boundary conditions, the choice of the
appropriate physics for a given problem (which phases, which components), discretization issues, appropriate physics for a given problem (which phases, which components), discretization issues,
time stepping. You can find, e. g., a comparison of different two-phase flow problems: The time stepping. You can find, e. g., a comparison of different two-phase flow problems: The
simpler approach considers two immiscible fluids while components in both phases with inter-phase simpler approach considers two immiscible fluids while components in both phases with inter-phase
......
...@@ -9,7 +9,7 @@ Feel free to register (if you don't have an account at out \emph{Git} yet) and t ...@@ -9,7 +9,7 @@ Feel free to register (if you don't have an account at out \emph{Git} yet) and t
at \url{https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/issues}. at \url{https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/issues}.
\paragraph{Commits, Merges, etc.} \paragraph{Commits, Merges, etc.}
To be up-to-date with the latest changes made to any git-repository you can use RSS Feeds. To be up-to-date with the latest changes made to any git-repository, you can use RSS Feeds.
Simply click on \emph{Issues} or \emph{Activity} and then select a tab you are interested in Simply click on \emph{Issues} or \emph{Activity} and then select a tab you are interested in
and use your favorite RSS-application for receiving the news. and use your favorite RSS-application for receiving the news.
...@@ -79,7 +79,7 @@ std::cout << "# This was written from "<< __FILE__ << ", line " << __LINE__ << s ...@@ -79,7 +79,7 @@ std::cout << "# This was written from "<< __FILE__ << ", line " << __LINE__ << s
\end{lstlisting} \end{lstlisting}
\paragraph{Using \Dune Debug Streams} \paragraph{Using \Dune Debug Streams}
\Dune provides a helpful feature, for keeping your debug-output organized. \Dune provides a helpful feature for keeping your debug-output organized.
It uses simple streams like \texttt{std::cout}, but they can be switched on and off It uses simple streams like \texttt{std::cout}, but they can be switched on and off
for the whole project. You can choose five different levels of severity: for the whole project. You can choose five different levels of severity:
\begin{verbatim} \begin{verbatim}
......
...@@ -61,7 +61,7 @@ of \texttt{Dumux::GnuplotInterface}, or the header file itself (\texttt{dumux/io ...@@ -61,7 +61,7 @@ of \texttt{Dumux::GnuplotInterface}, or the header file itself (\texttt{dumux/io
Gstat is an open source software tool which generates geostatistical random fields (see \url{www.gstat.org}). Gstat is an open source software tool which generates geostatistical random fields (see \url{www.gstat.org}).
In order to use gstat, execute the \texttt{bin/installexternal.sh} from your \Dumux root In order to use gstat, execute the \texttt{bin/installexternal.sh} from your \Dumux root
directory or donwload, unpack and install the tarball from the gstat-website. directory or donwload, unpack and install the tarball from the gstat-website.
Then rerun cmake (in the second case set \texttt{GSTAT\_ROOT} in your input file to the Then, rerun cmake (in the second case set \texttt{GSTAT\_ROOT} in your input file to the
path where gstat is installed). path where gstat is installed).
......
...@@ -14,4 +14,4 @@ the \texttt{Dumux::VTKReader} or you can simply recreate the grid as you did in ...@@ -14,4 +14,4 @@ the \texttt{Dumux::VTKReader} or you can simply recreate the grid as you did in
Writing double-precision floating point numbers to VTK files is available with the newest \Dune release 2.7. If you are using that version, it is now possible to specify output precision in the input file using \texttt{Vtk.Precision} followed by either \texttt{Float32}, \texttt{Float64}, \texttt{UInt32}, \texttt{UInt8} or \texttt{Int32}. \texttt{Float32} is set as the default. We especially advice the use of \texttt{Float64} when working with restart files. Writing double-precision floating point numbers to VTK files is available with the newest \Dune release 2.7. If you are using that version, it is now possible to specify output precision in the input file using \texttt{Vtk.Precision} followed by either \texttt{Float32}, \texttt{Float64}, \texttt{UInt32}, \texttt{UInt8} or \texttt{Int32}. \texttt{Float32} is set as the default. We especially advice the use of \texttt{Float64} when working with restart files.
The restart capabilities will hopefully be improved in future versions of \Dumux-3. The restart capabilities will hopefully be improved in future versions of \Dumux-3.
We are happy about any contributions (especially HDF5 / XDMF support, improvement of VTK support). We are looking forward to any contributions (especially HDF5 / XDMF support, improvement of VTK support).
...@@ -16,7 +16,7 @@ For compositional multi-phase models, fluid phases may be composed of several co ...@@ -16,7 +16,7 @@ For compositional multi-phase models, fluid phases may be composed of several co
\item[Components:] \item[Components:]
The term \emph{component} stands for constituents of the phases which The term \emph{component} stands for constituents of the phases which
can be associated with a unique chemical species, or, more generally, with can be associated with a unique chemical species or, more generally, with
a group of species exploiting similar physical behavior. For example, Fig. \ref{fig:phaseMassEnergyTransfer} shows a water-gas-NAPL system composed of the phases water (subscript a group of species exploiting similar physical behavior. For example, Fig. \ref{fig:phaseMassEnergyTransfer} shows a water-gas-NAPL system composed of the phases water (subscript
$\text{w}$), gas ($\text{g}$), and NAPL ($\text{n}$). These phases are $\text{w}$), gas ($\text{g}$), and NAPL ($\text{n}$). These phases are
composed of the components water (superscript $\text{w}$), the pseudo-component composed of the components water (superscript $\text{w}$), the pseudo-component
......
\section{Parallel Computation} \section{Parallel Computation}
\label{sec:parallelcomputation} \label{sec:parallelcomputation}
This section explains how \Dumux can be used This section explains how \Dumux can be used
on multicore / multinode systems. on multicore/multinode systems.
There are different concepts and methods for parallel programming, which are There are different concepts and methods for parallel programming, which are
often grouped in \textit{shared-memory} and \textit{distributed-memory} often grouped in \textit{shared-memory} and \textit{distributed-memory}
...@@ -62,7 +62,7 @@ Most MPI implementations use the \textbf{mpirun} command ...@@ -62,7 +62,7 @@ Most MPI implementations use the \textbf{mpirun} command
\begin{lstlisting}[style=Bash] \begin{lstlisting}[style=Bash]
mpirun -np <n_cores> <executable_name> mpirun -np <n_cores> <executable_name>
\end{lstlisting} \end{lstlisting}
%
where \textit{-np} sets the number of cores (\texttt{n\_cores}) that should be used for the where \textit{-np} sets the number of cores (\texttt{n\_cores}) that should be used for the
computation. On a cluster you usually have to use a queuing system (e.g. slurm) to computation. On a cluster you usually have to use a queuing system (e.g. slurm) to
submit a job. Check with your cluster administrator how to run parallel applications on the cluster. submit a job. Check with your cluster administrator how to run parallel applications on the cluster.
......
...@@ -6,10 +6,8 @@ are given, then follows a reference and a self-contained example. ...@@ -6,10 +6,8 @@ are given, then follows a reference and a self-contained example.
\subsection{Motivation and features} \subsection{Motivation and features}
The \Dumux property system is a traits system The \Dumux property system is a traits system
which allows easy inheritance. which allows easy inheritance.
In the context of the \Dumux property system, a property is an arbitrary In the context of the \Dumux property system, a property is an arbitrary
class body which may contain type definitions, values and methods. class body which may contain type definitions, values and methods.
Just like normal classes, properties can be arranged in hierarchies. In Just like normal classes, properties can be arranged in hierarchies. In
the context of the \Dumux property system, nodes of the inheritance the context of the \Dumux property system, nodes of the inheritance
hierarchy are called \emph{type tags}. hierarchy are called \emph{type tags}.
......
...@@ -222,8 +222,7 @@ model domain and $F(u) = F(\mathbf v, p) = F(\mathbf v(x,t), p(x,t))$. ...@@ -222,8 +222,7 @@ model domain and $F(u) = F(\mathbf v, p) = F(\mathbf v(x,t), p(x,t))$.
Like the FE method, the box method follows the principle of weighted residuals. Like the FE method, the box method follows the principle of weighted residuals.
In the function $f(u)$ the unknown $u$ is approximated by discrete values at the In the function $f(u)$ the unknown $u$ is approximated by discrete values at the
nodes of the FE mesh $\hat u_i$ and linear basis functions $N_i$ yielding an nodes of the FE mesh $\hat u_i$ and linear basis functions $N_i$ yielding an
approximate function $f(\tilde u)$. For $u\in \lbrace \mathbf v, p, x^\kappa \rbrace$ approximate function $f(\tilde u)$. For $u\in \lbrace \mathbf v, p, x^\kappa \rbrace$, this means:
this means:
\begin{minipage}[b]{0.47\textwidth} \begin{minipage}[b]{0.47\textwidth}
\begin{equation} \begin{equation}
...@@ -255,8 +254,7 @@ this means: ...@@ -255,8 +254,7 @@ this means:
\end{equation} \end{equation}
\end{minipage} \end{minipage}
Due to the approximation with node values and basis functions the differential Due to the approximation with node values and basis functions, the differential equations are not exactly fulfilled anymore but a residual $\varepsilon$ is produced.
equations are not exactly fulfilled anymore but a residual $\varepsilon$ is produced.
\begin{equation} \begin{equation}
f(u) = 0 \qquad \Rightarrow \qquad f(\tilde u) = \varepsilon f(u) = 0 \qquad \Rightarrow \qquad f(\tilde u) = \varepsilon
......
...@@ -15,7 +15,7 @@ with possibly vector-valued quantities $u$, $m$, $q$ and a tensor-valued flux $\ ...@@ -15,7 +15,7 @@ with possibly vector-valued quantities $u$, $m$, $q$ and a tensor-valued flux $\
For the sake of simplicity, we assume scalar quantities $u$, $m$, $q$ and a vector-valued For the sake of simplicity, we assume scalar quantities $u$, $m$, $q$ and a vector-valued
flux $\mathbf{f}$ in the notation below. flux $\mathbf{f}$ in the notation below.