Commit cc391e21 authored by Dennis Gläser's avatar Dennis Gläser Committed by Timo Koch

Merge branch 'feature/cleanup-handbook' into 'master'

Feature/cleanup handbook

Closes #635

See merge request !1456

(cherry picked from commit 97589d56)

4ff969b2 [handbook] cleanup, restructure discretization
c00a1139 [handbook] rename files
2e56a9a5 [handbook] correct quick installation and cleanup
parent a8de6d1d
...@@ -115,17 +115,20 @@ Universit\"at Stuttgart, Paffenwaldring 61, D-70569 Stuttgart, Germany}\\ ...@@ -115,17 +115,20 @@ Universit\"at Stuttgart, Paffenwaldring 61, D-70569 Stuttgart, Germany}\\
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.
If you need more information, please have a look at the detailed installation
instructions in the next chapter \ref{detailed-install}.
\input{2_quickinstall} \input{2_quickinstall}
\chapter{Detailed Installation, Documentation, and Externals}\label{detailed-install} \chapter{Detailed Installation, Documentation, and Externals}\label{detailed-install}
In this chapter, we provide more detailed information on how to obtain source code, build and test \Dune and \Dumux. In this chapter, we provide more detailed information on how to obtain source code, build and test \Dune and \Dumux.
It further contains information on It further contains information on
how to build the documentation and about external libraries and modules. how to build the documentation and about external libraries and modules.
\input{2_detailedinstall} \input{3_detailedinstall}
\chapter{Learning to use \Dumux}\label{chp:tutorial} \chapter{Learning to use \Dumux}\label{chp:tutorial}
\input{3_course} \input{4_course}
\input{3_furtherpractice} \input{4_furtherpractice}
\chapter{Overview and Infrastructure} \chapter{Overview and Infrastructure}
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}
...@@ -133,23 +136,24 @@ and gives help for basic work with \Dumux ...@@ -133,23 +136,24 @@ and gives help for basic work with \Dumux
(\ref{sc_newfoldersetup},\ref{sc_parameterfiles},\ref{sc_restartsimulations}, \ref{sc_developingdumux}). (\ref{sc_newfoldersetup},\ref{sc_parameterfiles},\ref{sc_restartsimulations}, \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{4_structure} \input{5_structure}
\input{4_newfoldersetup} \input{5_newfoldersetup}
\input{4_parameterfiles} \input{5_parameterfiles}
\input{4_restartsimulations} \input{5_restartsimulations}
\input{4_developingdumux} \input{5_developingdumux}
\input{4_externaltools} \input{5_externaltools}
\input{4_assemblinglinearsystem} \input{5_assemblinglinearsystem}
\chapter{Advanced \Dumux\ -- Detailed Instructions} \chapter{Advanced \Dumux\ -- Detailed Instructions}
This chapter contains detailed information for those who are interested This chapter contains detailed information for those who are interested
in deeper modifications of underlying \Dumux models, classes, functions, etc. in deeper modifications of underlying \Dumux models, classes, functions, etc.
\input{5_models} \input{6_basics}
\input{5_spatialdiscretizations} \input{6_temporaldiscretizations}
\input{5_stepsofasimulation} \input{6_spatialdiscretizations}
\input{5_propertysystem} \input{6_stepsofasimulation}
\input{5_inputoutput} \input{6_propertysystem}
\input{5_parallel} \input{6_inputoutput}
\input{6_parallel}
\bibliographystyle{plainnat} \bibliographystyle{plainnat}
\bibliography{dumux-handbook} \bibliography{dumux-handbook}
......
...@@ -7,7 +7,7 @@ processor systems to highly parallel supercomputers with specialized ...@@ -7,7 +7,7 @@ processor systems to highly parallel supercomputers with specialized
hardware architectures. hardware architectures.
The means to achieve these somewhat contradictory goals are the The means to achieve these somewhat contradictory goals are the
thorough use of object oriented design in conjunction with template thorough use of object-oriented design in conjunction with template
programming. These requirements call for \Cplusplus as the implementation programming. These requirements call for \Cplusplus as the implementation
language. language.
...@@ -37,7 +37,7 @@ DUNE's grid interface is independent of the spatial dimension of the ...@@ -37,7 +37,7 @@ DUNE's grid interface is independent of the spatial dimension of the
underlying grid. For this purpose, it uses the concept of underlying grid. For this purpose, it uses the concept of
co-dimensional entities. Roughly speaking, an entity of co-dimension co-dimensional entities. Roughly speaking, an entity of co-dimension
$0$ constitutes a cell, co-dimension $1$ entities are faces between $0$ constitutes a cell, co-dimension $1$ entities are faces between
cells, co-dimension $1$ are edges, and so on until co-dimension $n$ cells, co-dimension $2$ are edges, and so on until co-dimension $n$
which are the cell's vertices. The \Dune grid interface generally which are the cell's vertices. The \Dune grid interface generally
assumes that all entities are convex polytopes, which means that it 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
...@@ -50,7 +50,7 @@ entity. For example, if we used a grid which applied hexahedrons as cells, ...@@ -50,7 +50,7 @@ entity. For example, if we used a grid which applied hexahedrons as cells,
the reference element for each cell would be the unit cube $[0, 1]^3$ 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 gotten from the DUNE cheat sheet related numbering can be obtained from the DUNE cheat sheet
(\url{https://www.dune-project.org/pdf/dune-cheat-sheet.pdf}). (\url{https://www.dune-project.org/pdf/dune-cheat-sheet.pdf}).
For a more thorough description of \Dune's For a more thorough description of \Dune's
grid definition, see~\cite{BASTIAN2008}. grid definition, see~\cite{BASTIAN2008}.
...@@ -66,7 +66,7 @@ solving the generated systems. ...@@ -66,7 +66,7 @@ solving the generated systems.
\Dumux comes in form of an additional module \texttt{dumux}. \Dumux comes in 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-grid}, \texttt{dune-istl}, and on \texttt{dune-localfunctions}. \texttt{dune-common}, \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 an 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
......
This chapter provides one quick way of installing \Dumux.
You should have a recent working Linux environment and no \Dune core modules should be installed.
If you need more information or
have \Dune already installed, please have a look at the detailed installation
instructions in the more detailed intructions in the next chapter \ref{detailed-install}.
\section{Prerequisites} \label{sec:prerequisites} \section{Prerequisites} \label{sec:prerequisites}
For this quick start guide the following software packages are required: For this quick start guide the following software packages are required:
\begin{itemize} \begin{itemize}
...@@ -11,16 +5,13 @@ For this quick start guide the following software packages are required: ...@@ -11,16 +5,13 @@ For this quick start guide the following software packages are required:
\item A standard compliant C++ compiler supporting C++11 and the C++14 feature set of GCC 4.9. We support GCC 4.9 or newer and Clang 3.8 or newer. \item A standard compliant C++ compiler supporting C++11 and the C++14 feature set of GCC 4.9. We support GCC 4.9 or newer and Clang 3.8 or newer.
\item CMake 2.8.12 or newer \item CMake 2.8.12 or newer
\item pkg-config \item pkg-config
\item paraview (to visualize the results) \item ParaView (to visualize the results)
\end{itemize} \end{itemize}
\section{Obtaining code and configuring all modules with a script} \section{Obtaining code and configuring all modules with a script}
We provide you with a shell-script \texttt{installDumux.sh} that facilitates setting up a {\Dune}/{\Dumux} directory tree We provide you with a shell-script \texttt{installDumux.sh} that facilitates setting up a {\Dune}/{\Dumux} directory tree
and configures all modules with CMake. and configures all modules with CMake.
% TODO: uncomment/delete the following lines when next is the only release Copy the following lines into a text file named \texttt{installDumux.sh}:
% It is available after obtaining a download link via \url{http://www.dumux.org/download/} or
% by copying the following lines into a text-file named \texttt{installDumux.sh}:
Copy the following lines into a text-file named \texttt{installDumux.sh}:
\lstinputlisting[style=DumuxCode, numbersep=5pt, firstline=1, firstnumber=1]{installDumux.sh} \lstinputlisting[style=DumuxCode, numbersep=5pt, firstline=1, firstnumber=1]{installDumux.sh}
Place the \texttt{installDumux.sh} script in the directory where you want to install \Dumux and \Dune (a single Place the \texttt{installDumux.sh} script in the directory where you want to install \Dumux and \Dune (a single
...@@ -34,13 +25,15 @@ More details about the build-system can be found in section \ref{buildIt}. ...@@ -34,13 +25,15 @@ 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, you can execute a second script that When the \texttt{installDumux.sh} script from the subsection above has run successfully, you can execute a second script that
will compile and run a simple one-phase ground water flow example and will visualize the result using ParaView. will compile and run a simple one-phase ground water flow example and will visualize the result using ParaView.
The test script can be obtained by copying the following lines into a text-file named \texttt{test\_dumux.sh} The test script can be obtained by copying the following lines into a text file named \texttt{test\_dumux.sh}
that has to be located in the same directory as the installation script. that has to be located in the same directory as the installation script.
\begin{lstlisting}[style=DumuxCode] \begin{lstlisting}[style=DumuxCode]
cd DUMUX/dumux/build-cmake/test/porousmediumflow/1p/implicit cd DUMUX/dumux/build-cmake/test/porousmediumflow/1p/implicit/isothermal
make -B test_1pcctpfa make -B test_1p_tpfa
./test_1pcctpfa test_1pcctpfa.input ./test_1p_tpfa params.input
paraview *pvd paraview *pvd
\end{lstlisting} \end{lstlisting}
The script \texttt{test\_dumux.sh} can be executed by typing into the terminal: \texttt{./test\_dumux.sh}. The script \texttt{test\_dumux.sh} can be executed by typing into the terminal: \texttt{./test\_dumux.sh}.
If everything works fine, a ParaView window with the result should open automatically. If everything works fine, a ParaView window with the result should open automatically, showing the initial
conditions. Advance ParaView to the next frame (green arrow button) and rescale to data range to admire
the colorful pressure distribution.
...@@ -5,7 +5,6 @@ If there is a need for further practice, we refer here to the test problems that ...@@ -5,7 +5,6 @@ If there is a need for further practice, we refer here to the test problems that
are already implemented in \Dumux. Several examples for all models are already implemented in \Dumux. Several examples for all models
can be found in the \texttt{test}-directory. An overview over the available test can be found in the \texttt{test}-directory. An overview over the available test
cases can be found in the class documentation \url{http://www.dumux.org/documentation.php}. cases can be found in the class documentation \url{http://www.dumux.org/documentation.php}.
% There you also find a \emph{feature-list} for the individual tests.%TODO
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
...@@ -14,8 +13,6 @@ The \texttt{dumux-lecture} module can be obtained as follows: ...@@ -14,8 +13,6 @@ The \texttt{dumux-lecture} module can be obtained as follows:
\begin{lstlisting}[style=Bash] \begin{lstlisting}[style=Bash]
$ git clone https://git.iws.uni-stuttgart.de/dumux-repositories/dumux-lecture.git $ git clone https://git.iws.uni-stuttgart.de/dumux-repositories/dumux-lecture.git
\end{lstlisting} \end{lstlisting}
% TODO: remove again as soon as invalid:
Note that \texttt{dumux-lecture} is currently only compatible with the \Dumux release 2.12.
The module is structured based on the different lectures: The module is structured based on the different lectures:
\begin{itemize} \begin{itemize}
......
\section{External Tools} \section{External Tools}
\label{sc_externaltools} \label{sc_externaltools}
\subsection{Eclipse}
There is an Eclipse style file which can be used for \Dumux.
\begin{enumerate}
\item open in eclipse: \texttt{Window} $\rightarrow$ \texttt{Preferences} $\rightarrow$
\texttt{C/C++} $\rightarrow$ \texttt{Code Style} $\rightarrow$ \texttt{Formatter}
\item press the \texttt{Import} button
\item choose the file \texttt{eclipse\_profile.xml} from your dumux-devel directory
\item make sure that now \Dumux is chosen in \texttt{Select a profile}
\end{enumerate}
\subsection{Git} \subsection{Git}
Git is a version control tool which we use. Git is a version control tool which we use.
The basic Git commands are: The basic Git commands are:
\begin{itemize} \begin{itemize}
\item \texttt{git checkout} receive a specified branch from the repository \item \texttt{git checkout}: receive a specified branch from the repository
\item \texttt{git clone} clone a repository; creates a local copy \item \texttt{git clone}: clone a repository; creates a local copy
\item \texttt{git diff} to see the actual changes compared to your last commit \item \texttt{git diff}: to see the actual changes compared to your last commit
\item \texttt{git pull} pull changes from the repository; synchronizes the \item \texttt{git pull}: pull changes from the repository; synchronizes the
repository with your local copy repository with your local copy
\item \texttt{git push} push comitted changes to the repository; synchronizes \item \texttt{git push}: push comitted changes to the repository; synchronizes
your local copy with the repository your local copy with the repository
\item \texttt{git status} to check which files/folders have been changed \item \texttt{git status}: to check which files/folders have been changed
\item \texttt{git gui} graphical user interface, helps selecting changes for \item \texttt{git gui}: graphical user interface, helps selecting changes for
a commit a commit
\end{itemize} \end{itemize}
...@@ -78,13 +67,13 @@ path where gstat is installed). ...@@ -78,13 +67,13 @@ path where gstat is installed).
\subsection{ParaView} \subsection{ParaView}
\paragraph{Reload Button:} \paragraph{Reload Button:}
There are scripts to reload \texttt{*.pvd} or series of {\texttt{*.vtu} files since ParaView 4.2. There are scripts to reload PVD or series of VTU files since ParaView 4.2.
The scripts can be found The scripts can be found
\href{http://markmail.org/message/exxynsgishbvtngg#query:+page:1+mid:rxlwxs7uqrfgibyv+state:results}{\texttt{under this link}}. \href{http://markmail.org/message/exxynsgishbvtngg#query:+page:1+mid:rxlwxs7uqrfgibyv+state:results}{\texttt{under this link}}.
Just save the specific code portion in a file and load it via \texttt{Macros} $\rightarrow$ \texttt{Add new macro}. Just save the specific code portion in a file and load it via \texttt{Macros} $\rightarrow$ \texttt{Add new macro}.
\paragraph{Guide:} \paragraph{Guide:}
Since ParaView 4.3.1 The ParaView Guide is partly Since ParaView 4.3.1, The ParaView Guide is partly
available for free download, see \url{http://www.paraview.org/documentation/}. available for free download, see \url{http://www.paraview.org/documentation/}.
It corresponds to the ParaView book, only without three application chapters. It corresponds to the ParaView book, only three application chapters short.
Attention, its size is 180 MiB. Attention, its size is 180 MiB.
...@@ -18,10 +18,10 @@ The macro can be used with a variable amount of arguments. A simple call could l ...@@ -18,10 +18,10 @@ The macro can be used with a variable amount of arguments. A simple call could l
\begin{lstlisting}[style=DumuxCode] \begin{lstlisting}[style=DumuxCode]
dune_add_test(NAME my_test dune_add_test(NAME my_test
SOURCES mainfile.cc SOURCES main.cc
CMD_ARGS my_test params.input) CMD_ARGS my_test params.input)
\end{lstlisting} \end{lstlisting}
Here, we create an executable called \texttt{my\_test} from a source file \texttt{mainfile.cc}. Here, we create an executable called \texttt{my\_test} from a source file \texttt{main.cc}.
The name of the test will also be \texttt{my\_test} (has to be unique). The last argument specifies a command - here, we just run the executable \texttt{my\_test} with an input file \texttt{params.input}. For more advanced uses of The name of the test will also be \texttt{my\_test} (has to be unique). The last argument specifies a command - here, we just run the executable \texttt{my\_test} with an input file \texttt{params.input}. For more advanced uses of
the \texttt{add\_dune\_test} macro, have a look at the \texttt{test} directory. A complete documentation is given under \url{https://www.dune-project.org/sphinx/core-2.5/}. the \texttt{add\_dune\_test} macro, have a look at the \texttt{test} directory. A complete documentation is given under \url{https://www.dune-project.org/sphinx/core-2.5/}.
...@@ -11,6 +11,8 @@ get the following output at the end of the simulation run ...@@ -11,6 +11,8 @@ get the following output at the end of the simulation run
[ Grid ] [ Grid ]
Cells = "48 32" Cells = "48 32"
UpperRight = "6 4" UpperRight = "6 4"
[ Newton ]
EnablePartialReassembly = "true"
[ Problem ] [ Problem ]
EnableGravity = "true" EnableGravity = "true"
Name = "2p" Name = "2p"
...@@ -21,7 +23,7 @@ LensUpperRight = "4.0 3.0" ...@@ -21,7 +23,7 @@ LensUpperRight = "4.0 3.0"
DtInitial = "250" DtInitial = "250"
TEnd = "3000" TEnd = "3000"
# Default parameters used: # Global default parameters used:
[ Assembly ] [ Assembly ]
NumericDifferenceMethod = "1" NumericDifferenceMethod = "1"
[ Flux ] [ Flux ]
...@@ -34,6 +36,7 @@ ResidualReduction = "1e-13" ...@@ -34,6 +36,7 @@ ResidualReduction = "1e-13"
Verbosity = "0" Verbosity = "0"
[ Newton ] [ Newton ]
EnableAbsoluteResidualCriterion = "false" EnableAbsoluteResidualCriterion = "false"
EnableChop = "false"
EnableResidualCriterion = "false" EnableResidualCriterion = "false"
EnableShiftCriterion = "true" EnableShiftCriterion = "true"
MaxAbsoluteResidual = "1e-5" MaxAbsoluteResidual = "1e-5"
...@@ -44,7 +47,6 @@ SatisfyResidualAndShiftCriterion = "false" ...@@ -44,7 +47,6 @@ SatisfyResidualAndShiftCriterion = "false"
TargetSteps = "10" TargetSteps = "10"
UseLineSearch = "false" UseLineSearch = "false"
[ TimeLoop ] [ TimeLoop ]
MaxTimeStepDivisions = "10"
MaxTimeStepSize = "1e300" MaxTimeStepSize = "1e300"
[ Vtk ] [ Vtk ]
AddProcessRank = "true" AddProcessRank = "true"
......
...@@ -15,5 +15,5 @@ Unfortunately, writing double-precision floating point numbers to VTK files is o ...@@ -15,5 +15,5 @@ Unfortunately, writing double-precision floating point numbers to VTK files is o
That's why we currently only support single precision restart, meaning some information will be lost if you are computing That's why we currently only support single precision restart, meaning some information will be lost if you are computing
in double precision. in double precision.
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 happy about any contributions (especially HDF5 / XDMF support, improvement of VTK support).
...@@ -6,13 +6,14 @@ ...@@ -6,13 +6,14 @@
\item \texttt{bin}: binaries, e.g. used for the automatic testing, post-processing, installation \item \texttt{bin}: binaries, e.g. used for the automatic testing, post-processing, installation
\item \texttt{cmake}: the configuration options for building \Dumux \item \texttt{cmake}: the configuration options for building \Dumux
\item \texttt{doc}: files necessary for the Doxygen documentation and this handbook, and various logos \item \texttt{doc}: files necessary for the Doxygen documentation and this handbook, and various logos
\item \texttt{dumux}: the main folder, containing the source files. see \ref{fig:dumux-structure} \item \texttt{dumux}: the main folder, containing the source files. See \ref{fig:dumux-structure}
for a visualized structure. For more information on the models have a look at the for a visualized structure. For more information on the models have a look at the
Doxygen documentation. Doxygen documentation.
\item \texttt{test}: tests for each numerical model and some functionality. \item \texttt{test}: tests for each numerical model and some functionality.
The structure is equivalent to the \texttt{dumux} folder, the \texttt{references} folder The structure is equivalent to the \texttt{dumux} folder, the \texttt{references} folder
contains solutions for the automatic testing. Each test program consist of source contains solutions for the automatic testing. Each test program consist of a main file
\texttt{*.cc}, the problem definition \texttt{*problem.hh}, and an input file \texttt{*.input}. \texttt{main.cc}, the problem definition \texttt{*problem.hh} (specifying initial and boundary
conditions), and an input file \texttt{params.input}.
If necessary, spatially dependent parameters are defined in \texttt{*spatialparameters.hh}. If necessary, spatially dependent parameters are defined in \texttt{*spatialparameters.hh}.
For more detailed descriptions of the tests, please have a look at the Doxygen documentation. For more detailed descriptions of the tests, please have a look at the Doxygen documentation.
\end{itemize} \end{itemize}
......
\section{Models} \section{Physical Basics}
Here the basic definitions, the general models concept, and a list of Here the basic definitions, the general models concept, and a list of
models available in \Dumux are given. The actual differential equations models available in \Dumux are given. The actual differential equations
can be found in the local residuals (see Doxygen documentation of the can be found in the local residuals (see Doxygen documentation of the
model's \texttt{LocalResidual} class). model's \texttt{LocalResidual} class).
%TODO: Add more physics
\subsection{Basic Definitions and Assumptions} \subsection{Basic Definitions and Assumptions}
The basic definitions and assumptions are made, using the example The basic definitions and assumptions are made, using the example
...@@ -202,64 +203,3 @@ A list of all available models can be found ...@@ -202,64 +203,3 @@ A list of all available models can be found
in the Doxygen documentation at in the Doxygen documentation at
\url{http://www.dumux.org/doxygen-stable/html-\DumuxVersion/modules.php}. \url{http://www.dumux.org/doxygen-stable/html-\DumuxVersion/modules.php}.
The documentation includes a detailed description for every model. The documentation includes a detailed description for every model.
\subsubsection{Time discretization}
Our systems of partial differential equations are discretized in space and in time.
Let us consider the general case of a balance equation of the following form
\begin{equation}\label{eq:generalbalance}
\frac{\partial m(u)}{\partial t} + \nabla\cdot\mathbf{f}(u, \nabla u) + q(u) = 0,
\end{equation}
seeking an unknown quantity $u$ in terms of storage $m$, flux $\mathbf{f}$ and source $q$.
All available Dumux models can be written mathematically in form of \eqref{eq:generalbalance}
with possibly vector-valued quantities $u$, $m$, $q$ and a tensor-valued flux $\mathbf{f}$.
For the sake of simplicity, we assume scalar quantities $u$, $m$, $q$ and a vector-valued
flux $\mathbf{f}$ in the notation below.
For discretizing \eqref{eq:generalbalance} we need to choose an
approximation for the temporal derivative $\partial m(u)/\partial t$.
While many elaborate methods for this approximation exist,
we focus on the simplest one of a first order difference quotient
\begin{equation}\label{eq:euler}
\frac{\partial m(u_{k/k+1})}{\partial t}
\approx \frac{m(u_{k+1}) - m(u_k)}{\Delta t_{k+1}}
\end{equation}
for approximating the solution $u$ at time $t_k$ (forward) or $t_{k+1}$ (backward).
The question of whether to choose the forward or the backward quotient leads to the
explicit and implicit Euler method, respectively.
In case of the former, inserting \eqref{eq:euler} in \eqref{eq:generalbalance}
at time $t_k$ leads to
\begin{equation}\label{eq:expliciteuler}
\frac{m(u_{k+1}) - m(u_k)}{\Delta t_{k+1}} + \nabla\cdot\mathbf{f}(u_k, \nabla u_k) + q(u_k) = 0,
\end{equation}
whereas the implicit Euler method is described as
\begin{equation}\label{eq:impliciteuler}
\frac{m(u_{k+1}) - m(u_k)}{\Delta t_{k+1}}
+ \nabla\cdot\mathbf{f}(u_{k+1}, \nabla u_{k+1}) + q(u_{k+1}) = 0.
\end{equation}
Once the solution $u_k$ at time $t_k$ is known, it is straightforward
to determine $m(u_{k+1})$ from \eqref{eq:expliciteuler},
while attempting to do the same based on \eqref{eq:impliciteuler}
involves the solution of a system of equations.
On the other hand, the explicit method \eqref{eq:expliciteuler} is stable only
if the time step size $\Delta t_{k+1}$ is below a certain limit that depends
on the specific balance equation, whereas the implicit method \eqref{eq:impliciteuler}
is unconditionally stable.
\subsubsection{Algorithms to solve equations}
The governing equations of each model can be solved monolithically or sequentially.
The basic idea of the sequential algorithm is to reformulate the
equations of multi-phase flow into one equation for
pressure and equations for phase/component/... transport. The pressure equation
is the sum of the mass balance equations and thus considers the total flow of the
fluid system. The new set of equations is considered as decoupled (or weakly coupled)
and can thus be solved sequentially. The most popular sequential model is the
fractional flow formulation for two-phase flow which is usually implemented applying
an IMplicit Pressure Explicit Saturation algorithm (IMPES).
In comparison to solving the equations monolithically, the sequential structure allows the use of
different discretization methods for the different equations. The standard method
used in the sequential algorithm is a cell-centered finite volume method. Further schemes,
so far only available for the two-phase pressure equation, are cell-centered finite
volumes with multi-point flux approximation (Mpfa-O method) and mimetic finite differences.
An $h$-adaptive implementation of both sequential algorithms is provided for two dimensions.
...@@ -120,9 +120,9 @@ For all available parameters see the Doxygen documentation. ...@@ -120,9 +120,9 @@ For all available parameters see the Doxygen documentation.
\subsubsection{VTK file format} \subsubsection{VTK file format}
Dumux allows to write out simulation results via the \texttt{VtkOutputModule}. Dumux allows to write out simulation results via the \texttt{VtkOutputModule}.
For every print-out step, a single \texttt{*.vtu} file is created. For parallel simulations one file For every print-out step, a single VTU file is created. For parallel simulations one file
per print-out step is generated for each processor. per print-out step is generated for each processor.
The \texttt{*.pvd} file groups the single \texttt{*.vtu} files and contains additionally the time step information. The PVD file groups the single VTU files and contains additionally the time step information.
The VTK file format is supported by common visualisation programs like ParaView, VisIt, and Tecplot. The VTK file format is supported by common visualisation programs like ParaView, VisIt, and Tecplot.
\subsubsection{Customize the VTK output} \subsubsection{Customize the VTK output}
......
...@@ -17,7 +17,7 @@ data from other ranks. The domain decomposition in Dune is handled by the grid m ...@@ -17,7 +17,7 @@ data from other ranks. The domain decomposition in Dune is handled by the grid m
The grid is partitioned and distributed on several nodes. Most grid managers contain own domain decomposition methods to split the The grid is partitioned and distributed on several nodes. Most grid managers contain own domain decomposition methods to split the
computational domain into subdomains. Some grid managers also support external computational domain into subdomains. Some grid managers also support external
tools like METIS, ParMETIS, PTScotch or ZOLTAN for partitioning. tools like METIS, ParMETIS, PTScotch or ZOLTAN for partitioning.
On the other hand linear algebra types such as matrices and vectors On the other hand, linear algebra types such as matrices and vectors
do not know that they are in a parallel environment. Communication is then handled by the components of the do not know that they are in a parallel environment. Communication is then handled by the components of the
parallel solvers. Currently, the only parallel solver backend is \texttt{Dumux::AMGBackend}, a parallel AMG-preconditioned parallel solvers. Currently, the only parallel solver backend is \texttt{Dumux::AMGBackend}, a parallel AMG-preconditioned
BiCGSTAB solver. BiCGSTAB solver.
...@@ -62,9 +62,9 @@ submit a job. Check with your cluster administrator how to run parallel applicat ...@@ -62,9 +62,9 @@ submit a job. Check with your cluster administrator how to run parallel applicat
\subsection{Handling Parallel Results} \subsection{Handling Parallel Results}
For serial computations, \Dumux produces single vtu-files as default output format. For serial computations, \Dumux produces single vtu-files as default output format.
During a simulation, one vtu-file is written for every output step. During a simulation, one VTU file is written for every output step.
In the parallel case, one vtu-file for each step and processor is created. In the parallel case, one VTU file for each step and processor is created.
For parallel computations, an additional variable \texttt{"process rank"} is written For parallel computations, an additional variable \texttt{"process rank"} is written
into the file. The process rank allows the user to inspect the subdomains into the file. The process rank allows the user to inspect the subdomains
after the computation. The parallel vtu-files are combined in a single pvd file after the computation. The parallel VTU files are combined in a single pvd file
like in sequential simulations that can be opened with e.g. ParaView. like in sequential simulations that can be opened with e.g. ParaView.
\section{Temporal Discretization and Solution Strategies}
%TODO: Intro sentences
\subsection{Temporal discretization}
Our systems of partial differential equations are discretized in space and in time.
Let us consider the general case of a balance equation of the following form
\begin{equation}\label{eq:generalbalance}
\frac{\partial m(u)}{\partial t} + \nabla\cdot\mathbf{f}(u, \nabla u) + q(u) = 0,
\end{equation}
seeking an unknown quantity $u$ in terms of storage $m$, flux $\mathbf{f}$ and source $q$.
All available Dumux models can be written mathematically in form of \eqref{eq:generalbalance}
with possibly vector-valued quantities $u$, $m$, $q$ and a tensor-valued flux $\mathbf{f}$.
For the sake of simplicity, we assume scalar quantities $u$, $m$, $q$ and a vector-valued
flux $\mathbf{f}$ in the notation below.
For discretizing \eqref{eq:generalbalance} we need to choose an
approximation for the temporal derivative $\partial m(u)/\partial t$.
While many elaborate methods for this approximation exist,
we focus on the simplest one of a first order difference quotient
\begin{equation}\label{eq:euler}
\frac{\partial m(u_{k/k+1})}{\partial t}
\approx \frac{m(u_{k+1}) - m(u_k)}{\Delta t_{k+1}}
\end{equation}
for approximating the solution $u$ at time $t_k$ (forward) or $t_{k+1}$ (backward).
The question of whether to choose the forward or the backward quotient leads to the
explicit and implicit Euler method, respectively.
In case of the former, inserting \eqref{eq:euler} in \eqref{eq:generalbalance}
at time $t_k$ leads to
\begin{equation}\label{eq:expliciteuler}
\frac{m(u_{k+1}) - m(u_k)}{\Delta t_{k+1}} + \nabla\cdot\mathbf{f}(u_k, \nabla u_k) + q(u_k) = 0,
\end{equation}
whereas the implicit Euler method is described as
\begin{equation}\label{eq:impliciteuler}
\frac{m(u_{k+1}) - m(u_k)}{\Delta t_{k+1}}
+ \nabla\cdot\mathbf{f}(u_{k+1}, \nabla u_{k+1}) + q(u_{k+1}) = 0.
\end{equation}
Once the solution $u_k$ at time $t_k$ is known, it is straightforward
to determine $m(u_{k+1})$ from \eqref{eq:expliciteuler},
while attempting to do the same based on \eqref{eq:impliciteuler}
involves the solution of a system of equations.
On the other hand, the explicit method \eqref{eq:expliciteuler} is stable only
if the time step size $\Delta t_{k+1}$ is below a certain limit that depends
on the specific balance equation, whereas the implicit method \eqref{eq:impliciteuler}
is unconditionally stable.
\subsection{Solution strategies to solve equations}
The governing equations of each model can be solved monolithically or sequentially.
The basic idea of the sequential algorithm is to reformulate the
equations of multi-phase flow into one equation for
pressure and equations for phase/component/... transport. The pressure equation
is the sum of the mass balance equations and thus considers the total flow of the
fluid system. The new set of equations is considered as decoupled (or weakly coupled)
and can thus be solved sequentially. The most popular sequential model is the
fractional flow formulation for two-phase flow which is usually implemented applying
an IMplicit Pressure Explicit Saturation algorithm (IMPES).
In comparison to solving the equations monolithically, the sequential structure allows the use of
different discretization methods for the different equations. The standard method
used in the sequential algorithm is a cell-centered finite volume method. Further schemes,
so far only available for the two-phase pressure equation, are cell-centered finite
volumes with multi-point flux approximation (Mpfa-O method) and mimetic finite differences.
An $h$-adaptive implementation of both sequential algorithms is provided for two dimensions.
...@@ -2,23 +2,24 @@ set(TEX_INPUTS ...@@ -2,23 +2,24 @@ set(TEX_INPUTS
0_dumux-handbook.tex 0_dumux-handbook.tex
0_listingstyle.tex 0_listingstyle.tex
1_introduction.tex 1_introduction.tex
2_detailedinstall.tex
2_quickinstall.tex 2_quickinstall.tex
3_course.tex 3_detailedinstall.tex
3_furtherpractice.tex 4_course.tex
4_assemblinglinearsystem.tex 4_furtherpractice.tex
4_developingdumux.tex 5_assemblinglinearsystem.tex
4_externaltools.tex 5_developingdumux.tex
4_newfoldersetup.tex 5_externaltools.tex
4_parameterfiles.tex 5_newfoldersetup.tex
4_restartsimulations.tex 5_parameterfiles.tex
4_structure.tex 5_restartsimulations.tex
5_inputoutput.tex 5_structure.tex
5_models.tex 6_basics.tex
5_parallel.tex 6_inputoutput.tex
5_propertysystem.tex 6_parallel.tex
5_spatialdiscretizations.tex 6_propertysystem.tex
5_stepsofasimulation.tex 6_spatialdiscretizations.tex
6_stepsofasimulation.tex
6_temporaldiscretizations.tex
installDumux.sh) installDumux.sh)
set(TEX_IMAGES set(TEX_IMAGES
......
...@@ -10,25 +10,11 @@ Make sure to be connected to the internet." ...@@ -10,25 +10,11 @@ Make sure to be connected to the internet."
echo "*************************************************" echo "*************************************************"
# the core modules # the core modules
for MOD in common geometry grid localfunctions istl; do for MOD in common geometry grid localfunctions istl; do
if [ ! -d "dune-$MOD" ]; then git clone -b releases/2.6 https://gitlab.dune-project.org/core/dune-$MOD.git
git clone -b releases/2.6 https://gitlab.dune-project.org/core/dune-$MOD.git
else
echo "Skip cloning dune-$MOD because the folder already exists."
cd dune-$MOD
git checkout releases/2.6
cd ..
fi
done done
# dumux # dumux
if [ ! -d "dumux" ]; then git clone -b releases/3.0 https://git.iws.uni-stuttgart.de/dumux-repositories/dumux.git
git clone -b releases/3.0 https://git.iws.uni-stuttgart.de/dumux-repositories/dumux.git
else
echo "Skip cloning dumux because the folder already exists."
cd dumux
git checkout releases/3.0
cd ..
fi
if [ $? -ne 0 ]; then if [ $? -ne 0 ]; then
echo "*************************************************" echo "*************************************************"
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment