Skip to content
GitLab
Commit 97589d56 authored by Dennis Gläser's avatar Dennis Gläser
Browse files

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

Feature/cleanup handbook

Closes #635

See merge request !1456
parents 4c6adfa4 2e56a9a5
Expand all Hide whitespace changes
Inline Side-by-side
doc/handbook/0_dumux-handbook.tex
View file @ 97589d56
......@@ -115,17 +115,20 @@ Universit\"at Stuttgart, Paffenwaldring 61, D-70569 Stuttgart, Germany}\\
In this chapter we provide a quick start guide to
your first \Dumux experience, including an install script with all necessary instructions
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}
\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.
It further contains information on
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}
\input{3_course}
\input{3_furtherpractice}
\input{4_course}
\input{4_furtherpractice}
\chapter{Overview and Infrastructure}
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
(\ref{sc_newfoldersetup},\ref{sc_parameterfiles},\ref{sc_restartsimulations}, \ref{sc_developingdumux}).
Further it presents useful external tools \ref{sc_externaltools} and basic
concepts \ref{sc_linearsystem}.
\input{4_structure}
\input{4_newfoldersetup}
\input{4_parameterfiles}
\input{4_restartsimulations}
\input{4_developingdumux}
\input{4_externaltools}
\input{4_assemblinglinearsystem}
\input{5_structure}
\input{5_newfoldersetup}
\input{5_parameterfiles}
\input{5_restartsimulations}
\input{5_developingdumux}
\input{5_externaltools}
\input{5_assemblinglinearsystem}
\chapter{Advanced \Dumux\ -- Detailed Instructions}
This chapter contains detailed information for those who are interested
in deeper modifications of underlying \Dumux models, classes, functions, etc.
\input{5_models}
\input{5_spatialdiscretizations}
\input{5_stepsofasimulation}
\input{5_propertysystem}
\input{5_inputoutput}
\input{5_parallel}
\input{6_basics}
\input{6_temporaldiscretizations}
\input{6_spatialdiscretizations}
\input{6_stepsofasimulation}
\input{6_propertysystem}
\input{6_inputoutput}
\input{6_parallel}
\bibliographystyle{plainnat}
\bibliography{dumux-handbook}
......
doc/handbook/1_introduction.tex
View file @ 97589d56
......@@ -7,7 +7,7 @@ processor systems to highly parallel supercomputers with specialized
hardware architectures.
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
language.
......@@ -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
co-dimensional entities. Roughly speaking, an entity of co-dimension
$0$ constitutes a cell, co-dimension $1$ entities are faces between
cells, co-dimension $1$ are edges, and so on until co-dimension $n$
cells, co-dimension $2$ are edges, and so on until co-dimension $n$
which are the cell's vertices. The \Dune grid interface generally
assumes that all entities are convex polytopes, which means that it
must be possible to express each entity as the convex hull of a set of
......@@ -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$
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
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}).
For a more thorough description of \Dune's
grid definition, see~\cite{BASTIAN2008}.
......@@ -66,7 +66,7 @@ solving the generated systems.
\Dumux comes in form of an additional module \texttt{dumux}.
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
implementation of new physical models for porous media flow problems,
ranging from problem formulation and the selection of
......
doc/handbook/2_quickinstall.tex
View file @ 97589d56
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}
For this quick start guide the following software packages are required:
\begin{itemize}
......@@ -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 CMake 2.8.12 or newer
\item pkg-config
\item paraview (to visualize the results)
\item ParaView (to visualize the results)
\end{itemize}
\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
and configures all modules with CMake.
% TODO: uncomment/delete the following lines when next is the only release
% 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}:
Copy the following lines into a text file named \texttt{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
......@@ -34,13 +25,15 @@ More details about the build-system can be found in section \ref{buildIt}.
\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
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.
\begin{lstlisting}[style=DumuxCode]
cd DUMUX/dumux/build-cmake/test/porousmediumflow/1p/implicit
make -B test_1pcctpfa
./test_1pcctpfa test_1pcctpfa.input
cd DUMUX/dumux/build-cmake/test/porousmediumflow/1p/implicit/isothermal
make -B test_1p_tpfa
./test_1p_tpfa params.input
paraview *pvd
\end{lstlisting}
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.
doc/handbook/2_detailedinstall.tex → doc/handbook/3_detailedinstall.tex
View file @ 97589d56
% \section{Detailed Installation Instructions}
% \label{install}
Installing \Dumux means that you first unpack \Dune and \Dumux in a root directory,
(section \ref{sc:ObtainingSourceCode}).
In a second step of the installation, all modules are configured with CMake
(section \ref{buildIt}).
After successful installation of \Dumux we guide you to start a test application,
After successful installation of \Dumux, we guide you to start a test application,
described in section \ref{quick-start-guide}.
In section \ref{sec:build-doxy-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.
In a technical sense \Dumux is a module of \Dune.
......@@ -18,31 +15,28 @@ Details regarding the installation of \Dune are provided on the \Dune website \c
\section{Obtaining Source Code for \Dune and \Dumux}
\label{sc:ObtainingSourceCode}
The \Dumux release and trunk (developer tree) are based on the most recent
\Dune release 2.6, comprising the core modules dune-common, dune-geometry, dune-grid,
dune-istl and dune-localfunctions. For working with \Dumux, these modules are required.
\Dune release 2.6, comprising the core modules \texttt{dune-common}, \texttt{dune-geometry},
\texttt{dune-grid}, \texttt{dune-istl} and \texttt{dune-localfunctions}.
For working with \Dumux, these modules are required.
All \Dune modules, including the \Dumux module, get extracted into a common root directory, as it
is done in an ordinary \Dune installation.
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.
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).
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.
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.
% % TODO: alpha version was not released with a tarball. For the next releases the following lines need to be deleted again
% There is no tar file for the current \DumuxVersion~release.
% Secondly, a method to obtain the most recent source code (or, more generally, any of its previous revisions) by direct access
% to the software repositories of the revision control system is described in the subsequent part.
% Be aware that you cannot get \texttt{dumux-devel} or the external libraries from \texttt{dumux-external} unless
% you have an GitLab account with the right privileges.
Secondly, the most recent source code
(or, more generally, any of its previous revisions) can be obtained by direct access
to the software repositories of the revision control system. This is described in the second paragraph.
In section \ref{sec:prerequisites} we list some prerequisites for running \Dune and \Dumux.
Please check in said paragraph whether you can fulfill them before continuing.
% TODO: alpha version was not released with a tarball. For the next releases the following lines need to be uncommented again
\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
......@@ -75,7 +69,7 @@ on the Dune grid interface, act similar.
\paragraph{Obtaining \Dune and \Dumux from software repositories}
Direct access to a software revision control system for downloading code can be of advantage later on.
It is easier to keep up with code changes and to receive important bug fixes.
\Dune and \Dumux use Git for their software repositories. To access them a Git client is needed.
\Dune and \Dumux use Git for their software repositories. To access them, a Git client is needed.
In the technical language of Git, \emph{cloning a certain software version} means nothing more then fetching
a local copy from the software repository and laying it out in the file system.
......@@ -144,7 +138,7 @@ Configuring \Dune and \Dumux is done by the shell-command \texttt{dunecontrol} w
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
CMake's documentation\footnote{\url{https://cmake.org/documentation/}}.
If something fails during the execution of \texttt{dunecontrol} feel free to report it to the \Dune or \Dumux developer mailing list,
If something fails during the execution of \texttt{dunecontrol}, feel free to report it to the \Dune or \Dumux developer mailing list,
but please include error details.
It is possible to compile \Dumux with nearly no explicit options to the build system.
......@@ -170,7 +164,7 @@ Sometimes, it is necessary to have additional options which
are specific to a package set of an operating system or
sometimes you have your own preferences.
Feel free to work with your own set of options, which may evolve over time.
The option files above are 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.
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,
......@@ -185,9 +179,6 @@ All executables 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.
\begin{enumerate}
\item Go to the directory \texttt{build-cmake/test}. There, various test application
folders can be found. Let us consider as example\\
\texttt{porousmediumflow/2p/implicit/incompressible/test{\_}2p{\_}incompressible{\_}tpfa}.
\item Enter the folder \texttt{porousmediumflow/2p/implicit/incompressible}.\\ Type \texttt{make test{\_}2p{\_}incompressible{\_}tpfa}
in order to compile the application\\\texttt{test{\_}2p{\_}incompressible{\_}tpfa}. To run the simulation,
type \texttt{./test{\_}2p{\_}incompressible{\_}tpfa params.input}
......@@ -196,16 +187,16 @@ If not specified differently in the options file, this is \texttt{build-cmake} a
important run-time parameters (like 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
name \texttt{params.input}.
\item The simulation starts and produces some .vtu output files and also a .pvd
file. The .pvd file can be used to examine time series and summarizes the .vtu
\item The simulation starts and produces some VTU output files and also a PVD
file. The PVD file can be used to examine time series and summarizes the VTU
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
alternatively VisIt). Just type \texttt{paraview} in the console and open the
.pvd file. On the left hand side, you can choose the desired parameter to be displayed.
PVD file. On the left hand side, you can choose the desired parameter to be displayed.
\end{enumerate}
\section{Building Documentation}
\label{sec:build-doc}
The building of included documentation like this handbook requires \LaTeX{} and auxiliary tools
\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}
......@@ -213,13 +204,13 @@ in the \texttt{CONFIGURE\_FLAGS} of the building options, see section \ref{build
\subsection{Doxygen}
\label{sec:build-doxy-doc}
Doxygen documentation is done by especially formatted comments integrated in the source code,
Doxygen documentation is done by specifically 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 \url{http://www.stack.nl/~dimitri/doxygen/}.
The Doxygen documentation of a module can be built, if \texttt{doxygen} is installed,
by running \texttt{dunecontrol}, entering the \texttt{build-*}directory, and execute
The Doxygen documentation of a module can be built if \texttt{doxygen} is installed,
by running \texttt{dunecontrol}, entering the \texttt{build-*}directory, and executing
\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.
This should also work for other \Dune modules.
......@@ -231,9 +222,9 @@ in \texttt{MODULE\_BUILD\_DIRECTORY/doc/handbook/0\_dumux-handbook.pdf}.
\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%
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/}}.
If you are going to use an external \Dune module the website on external modules%
If you are going to use an external \Dune module, the website on external modules%
\footnote{DUNE: External modules, \url{https://www.dune-project.org/groups/external/}}
can be helpful.
......@@ -307,5 +298,5 @@ depending on which modules of \Dune and which external libraries you use.
\item \textbf{Compilers}: Beside \texttt{g++}, \Dune can be built with Clang from the LLVM project and
Intel \Cplusplus compiler. C and Fortran compilers are needed for some external libraries. As code of
different compilers is linked together they have to be be compatible with each other.
different compilers is linked together, they have to be be compatible with each other.
\end{itemize}
doc/handbook/3_furtherpractice.tex → doc/handbook/4_furtherpractice.tex
View file @ 97589d56
......@@ -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
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}.
% 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
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:
\begin{lstlisting}[style=Bash]
$ git clone https://git.iws.uni-stuttgart.de/dumux-repositories/dumux-lecture.git
\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:
\begin{itemize}
......
doc/handbook/4_externaltools.tex → doc/handbook/5_externaltools.tex
View file @ 97589d56
\section{External Tools}
\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}
Git is a version control tool which we use.
The basic Git commands are:
\begin{itemize}
\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 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 checkout}: receive a specified branch from the repository
\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 pull}: pull changes from the repository; synchronizes the
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
\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 status}: to check which files/folders have been changed
\item \texttt{git gui}: graphical user interface, helps selecting changes for
a commit
\end{itemize}
......@@ -78,13 +67,13 @@ path where gstat is installed).
\subsection{ParaView}
\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
\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}.
\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/}.
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.
doc/handbook/4_newfoldersetup.tex → doc/handbook/5_newfoldersetup.tex
View file @ 97589d56
......@@ -18,10 +18,10 @@ The macro can be used with a variable amount of arguments. A simple call could l
\begin{lstlisting}[style=DumuxCode]
dune_add_test(NAME my_test
SOURCES mainfile.cc
SOURCES main.cc
CMD_ARGS my_test params.input)
\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 \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/}.
doc/handbook/4_parameterfiles.tex → doc/handbook/5_parameterfiles.tex
View file @ 97589d56
......@@ -11,6 +11,8 @@ get the following output at the end of the simulation run
[ Grid ]
Cells = "48 32"
UpperRight = "6 4"
[ Newton ]
EnablePartialReassembly = "true"
[ Problem ]
EnableGravity = "true"
Name = "2p"
......@@ -21,7 +23,7 @@ LensUpperRight = "4.0 3.0"
DtInitial = "250"
TEnd = "3000"
# Default parameters used:
# Global default parameters used:
[ Assembly ]
NumericDifferenceMethod = "1"
[ Flux ]
......@@ -34,6 +36,7 @@ ResidualReduction = "1e-13"
Verbosity = "0"
[ Newton ]
EnableAbsoluteResidualCriterion = "false"
EnableChop = "false"
EnableResidualCriterion = "false"
EnableShiftCriterion = "true"
MaxAbsoluteResidual = "1e-5"
......@@ -44,7 +47,6 @@ SatisfyResidualAndShiftCriterion = "false"
TargetSteps = "10"
UseLineSearch = "false"
[ TimeLoop ]
MaxTimeStepDivisions = "10"
MaxTimeStepSize = "1e300"
[ Vtk ]
AddProcessRank = "true"
......
doc/handbook/4_restartsimulations.tex → doc/handbook/5_restartsimulations.tex
View file @ 97589d56
......@@ -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
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).
doc/handbook/4_structure.tex → doc/handbook/5_structure.tex
View file @ 97589d56
......@@ -6,13 +6,14 @@
\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{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
Doxygen documentation.
\item \texttt{test}: tests for each numerical model and some functionality.
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
\texttt{*.cc}, the problem definition \texttt{*problem.hh}, and an input file \texttt{*.input}.
contains solutions for the automatic testing. Each test program consist of a main file
\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}.
For more detailed descriptions of the tests, please have a look at the Doxygen documentation.
\end{itemize}
......
doc/handbook/5_models.tex → doc/handbook/6_basics.tex
View file @ 97589d56
\section{Models}
\section{Physical Basics}
Here the basic definitions, the general models concept, and a list of
models available in \Dumux are given. The actual differential equations
can be found in the local residuals (see Doxygen documentation of the
model's \texttt{LocalResidual} class).
%TODO: Add more physics
\subsection{Basic Definitions and Assumptions}
The basic definitions and assumptions are made, using the example
......@@ -202,64 +203,3 @@ A list of all available models can be found
in the Doxygen documentation at
\url{http://www.dumux.org/doxygen-stable/html-\DumuxVersion/modules.php}.
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.
doc/handbook/5_inputoutput.tex → doc/handbook/6_inputoutput.tex
View file @ 97589d56
......@@ -120,9 +120,9 @@ For all available parameters see the Doxygen documentation.
\subsubsection{VTK file format}
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.
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.
\subsubsection{Customize the VTK output}
......
doc/handbook/5_parallel.tex → doc/handbook/6_parallel.tex
View file @ 97589d56
......@@ -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
computational domain into subdomains. Some grid managers also support external
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
parallel solvers. Currently, the only parallel solver backend is \texttt{Dumux::AMGBackend}, a parallel AMG-preconditioned
BiCGSTAB solver.
......@@ -62,9 +62,9 @@ submit a job. Check with your cluster administrator how to run parallel applicat
\subsection{Handling Parallel Results}
For serial computations, \Dumux produces single vtu-files as default output format.
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.
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.
For parallel computations, an additional variable \texttt{"process rank"} is written
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.
doc/handbook/6_temporaldiscretizations.tex 0 → 100644
View file @ 97589d56
\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