Commit a47c325a authored by Timo Koch's avatar Timo Koch

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

[handbook] Update for 3.0

Closes #484

See merge request !1338

(cherry picked from commit b0ce2d5a)

9a28187b [handbook] rename domain G to Omega
30ead698 time discretization
f19d0dc0 [handbook] Add link to DUNE cheatsheet.
a81c7e71 [handbook] Update structure and folder setup
46a6e2e6 [handbook] Update parameter section
f8021fa7 [handbook] Move passage about guidelines and delete .tex file
aeacd3d6 Mention where 'actual equations' can be found.
a65a0bb4 [handbook] Modify section on staggered grid discretization.
602eb230 [Handbook] replace tutorial section with dumux course reference
e818ce99 [handbook] updated 'getting started' chapter, split in 'quick start' and…
ed726526 [handbook] Update external modules list
6ea7a2d7 [handbook] Update dune-subgrid description in 2_detailedinstall.tex
a4ff23e9 [handbook] Update dune-sub and spgrid in 2_detailedinstall.tex corrected error in last commit
ae990d7c [handbook] Updated dune-subgrid description in 2_detailedinstall.tex
43e9ae6d [bugfix] Make handbook compile again
2ad6ee7d [handbook] update section on propertysystem to new syntax
4a4e3eaf [doc][handbook] Improve text on property system
b5e780f3 [handbook] Add passage about TTag inheritance order
5cfd24af Add the first draft of parrallel section
b16bd7ab Add the section input and outout
b411ac0a Add the section parralel
b0137f18 Finish the parallel and the input/output section.
747fa637 Add "Costumize the VTK output"
cb612777 [Handbook][Grids] remove external grid section, replace with paragraph in grid format subsection
88eb807a [handbook] Revise stepsofasimulation.
93ef16b6 [handbook][course] cleanup course text to match correct tag reference
02f42fc7 [handbook][3_course] add release tag for dumux-course and cleanup
7677fb70 [handbook][3_course] cleanup
8d47510a [handbook] Update CMakeLists for new tex-files and images
fc5fb34a [handbook][dalton] better image quality
a8e771ec [handbook][4_newfoldersetup] cleanup
1dabc408 [handbook] remove all mentioning of tutorial
74cc4fa9 [handbook][cleanup] Replace \ by \par.
2887b292 [handbook] Introduce to 3.0 and add link to wiki
8f4d1922 [temporal discretization]
68b884db [temporal discretization]
8a77e5e4 [handbook][gnuplot] cleanup
c0f0eec5 [handbook][io] cleanup gnuplot
9541a0b2 [handbook] Update box description
eb9ea429 [handbook][disc] Correction of indices used for the box method
aaf245dc [handbook][disc] Use mpfa stuff from Dennis
132fbb01 [handbook][disc] Add first draft of TPFA description
8ac05303 [handbook][disc] Add first draft of MPFA description
928687f8 [handbook][disc] Update tpfa description and general statements
bb148e5b [handbook][disc] Cleanup mpfa
0b1efc32 [handbook][box] Replace V_j by |B_j|
a900006d [handbook][disc] Use dx d\Gamma consistenly for integrals
11469e1c [handbook][box] Replace wrong scalar products in integrals
6808e8d1 [handbook][pics] Apply renaming of png folder
ac702b5e Merge branch 'feature/improve-handbook-discretization' into 'feature/improve-handbook'
3ab21f73 [handbook] Correct some mistakes in input/output and parallel
3b2dd5a3 [handbook][io] cleanup
a2db2fbc [handbook][parallel] cleanup
067ca3db [handbook][parallel] exceptions multidomain and freeflow
5cb67f60 [handbook] Update input output
824eb40b [handbook] Update parallel
ffa020ef Merge branch 'feature/improve-handbook_inoutput-parallel' into 'feature/improve-handbook'
719b48e0 [handbook] Add small section on restart
12829a9b Update contributors
parent e0263ddb
...@@ -56,6 +56,7 @@ Copyright holders ...@@ -56,6 +56,7 @@ Copyright holders
| 2012-2014 | Alexandru Tatomir | | 2012-2014 | Alexandru Tatomir |
| 2015-2017 | Larissa de Vries | | 2015-2017 | Larissa de Vries |
| 2013 | Katharina Türk | | 2013 | Katharina Türk |
| 2018 | Martin Utz |
| 2010-2014 | Lena Walter | | 2010-2014 | Lena Walter |
| 2018 | Felix Weinhardt | | 2018 | Felix Weinhardt |
| 2015-2017 | Kilian Weishaupt | | 2015-2017 | Kilian Weishaupt |
......
...@@ -11,6 +11,7 @@ ...@@ -11,6 +11,7 @@
\usepackage{enumerate} \usepackage{enumerate}
\usepackage{hyperref} \usepackage{hyperref}
\usepackage{graphicx} \usepackage{graphicx}
\usepackage{listings} \usepackage{listings}
\usepackage{makeidx} \usepackage{makeidx}
\usepackage[square,numbers]{natbib} \usepackage[square,numbers]{natbib}
...@@ -72,6 +73,7 @@ ...@@ -72,6 +73,7 @@
\DeclareMathOperator{\grad}{\mathbf{grad}} \DeclareMathOperator{\grad}{\mathbf{grad}}
\DeclareMathOperator{\curl}{curl} \DeclareMathOperator{\curl}{curl}
\DeclareMathOperator{\Div}{div} \DeclareMathOperator{\Div}{div}
\newcommand{\meas}[1]{\lvert{#1}\rvert}
\pagestyle{scrheadings} \pagestyle{scrheadings}
...@@ -109,31 +111,32 @@ Universit\"at Stuttgart, Paffenwaldring 61, D-70569 Stuttgart, Germany}\\ ...@@ -109,31 +111,32 @@ Universit\"at Stuttgart, Paffenwaldring 61, D-70569 Stuttgart, Germany}\\
\chapter{Introduction} \chapter{Introduction}
\input{1_introduction} \input{1_introduction}
\chapter{Getting started} \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. your first \Dumux experience, including an install script with all necessary instructions
The first section contains instructions on how to very quickly install \Dumux. on how to very quickly install the latest release version of \Dumux.
More detailed information on how to obtain source code, build and test \Dune and \Dumux
follows in the second section of this chapter. The second section also contains information on
how to build the documentation and about external libraries and modules.
\input{2_quickinstall} \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{2_detailedinstall}
\chapter{Tutorial}\label{chp:tutorial} \chapter{Learning to use \Dumux}\label{chp:tutorial}
\input{3_tutorial} \input{3_course}
\input{3_furtherpractice} \input{3_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}
and gives help for basic work with \Dumux and gives help for basic work with \Dumux
(\ref{sc_newfoldersetup},\ref{sc_parameterfiles},\ref{sc_restartsimulations},\ref{sc_guidelines},\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{4_structure}
\input{4_newfoldersetup} \input{4_newfoldersetup}
\input{4_parameterfiles} \input{4_parameterfiles}
\input{4_restartsimulations} \input{4_restartsimulations}
\input{4_guidelines}
\input{4_developingdumux} \input{4_developingdumux}
\input{4_externaltools} \input{4_externaltools}
\input{4_assemblinglinearsystem} \input{4_assemblinglinearsystem}
...@@ -145,7 +148,8 @@ in deeper modifications of underlying \Dumux models, classes, functions, etc. ...@@ -145,7 +148,8 @@ in deeper modifications of underlying \Dumux models, classes, functions, etc.
\input{5_spatialdiscretizations} \input{5_spatialdiscretizations}
\input{5_stepsofasimulation} \input{5_stepsofasimulation}
\input{5_propertysystem} \input{5_propertysystem}
\input{5_grids} \input{5_inputoutput}
\input{5_parallel}
\bibliographystyle{plainnat} \bibliographystyle{plainnat}
\bibliography{dumux-handbook} \bibliography{dumux-handbook}
......
...@@ -25,7 +25,7 @@ libraries\footnote{In fact, the performance penalty resulting from the ...@@ -25,7 +25,7 @@ libraries\footnote{In fact, the performance penalty resulting from the
use of \Dune's grid interface is usually negligible~\cite{BURRI2006}.}. use of \Dune's grid interface is usually negligible~\cite{BURRI2006}.}.
\begin{figure}[hbt] \begin{figure}[hbt]
\centering \centering
\includegraphics[width=.5\linewidth, keepaspectratio]{PNG/dunedesign.png} \includegraphics[width=.5\linewidth, keepaspectratio]{png/dunedesign.png}
\caption{ \caption{
\label{fig:dune-design} \label{fig:dune-design}
A high-level overview of \Dune's design is available on the project's A high-level overview of \Dune's design is available on the project's
...@@ -49,7 +49,10 @@ entity can be thought of as a prototype for the actual grid ...@@ -49,7 +49,10 @@ entity can be thought of as a prototype for the actual grid
entity. For example, if we used a grid which applied hexahedrons as cells, 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. For a more thorough description of \Dune's it matches the grid's cell. A quick overview of reference elements and the
related numbering can be gotten 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}. grid definition, see~\cite{BASTIAN2008}.
In addition to the grid interface, \Dune also provides quite a few In addition to the grid interface, \Dune also provides quite a few
...@@ -71,3 +74,17 @@ spatial and temporal discretization schemes as well as nonlinear solvers, ...@@ -71,3 +74,17 @@ 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 major version update of \Dumux: version 3.0.
The release contains considerable improvements and many new features compared to the 2.x versions.
Due to the major update, backwards compatibility with the last release 2.12 cannot be assured.
To facilitate the transition for our users, we have created a
git wiki entry describing how to update programs from version 2.12 to version 3.0.
It is available online:
\url{https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/wikis/Updating-programs-from-version-2.12-to-version-3.0}.
The guide leads in detail through the interface changes from 2.12 to 3.0,
concerning the \texttt{Problem} class, the \texttt{SpatialParams} class,
the \texttt{Parameters} and \texttt{Properties}, i.e. the main user interface.
Starting with version 3.0.0, all minor
version updates will certainly be backward compatible again with at least the last minor version.
We highly recommend all our users to transition with us to \Dumux-3.0
and wish everyone a brand-new and exciting simulation experience.
This diff is collapsed.
\section{Quick Installation of \Dumux} This chapter provides one quick way of installing \Dumux.
\label{quick-install}
This section only provides one quick way of installing \Dumux.
You should have a recent working Linux environment and no \Dune core modules should be installed. You should have a recent working Linux environment and no \Dune core modules should be installed.
If you need more information or If you need more information or
have \Dune already installed, please have a look at the detailed installation have \Dune already installed, please have a look at the detailed installation
instructions in Section \ref{install}. instructions in the more detailed intructions in the next chapter \ref{detailed-install}.
\subsection{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}
\item GitLab client \item GitLab client
...@@ -17,12 +14,7 @@ For this quick start guide the following software packages are required: ...@@ -17,12 +14,7 @@ For this quick start guide the following software packages are required:
\item paraview (to visualize the results) \item paraview (to visualize the results)
\end{itemize} \end{itemize}
The building of included documentation like this handbook requires \LaTeX{} and auxiliary tools \section{Obtaining code and configuring all modules with a script}
\texttt{bibtex}. One usually chooses a \LaTeX{} distribution like \texttt{texlive} for this purpose.
It is possible to switch off the building of the documentation by setting the switch \texttt{--disable-documentation}
in the \texttt{CONFIGURE\_FLAGS} of the building options, see Chapter \ref{buildIt}.
\subsection{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 % TODO: uncomment/delete the following lines when next is the only release
...@@ -36,7 +28,7 @@ root folder \texttt{DUMUX} will be produced, so you do not need to provide one). ...@@ -36,7 +28,7 @@ root folder \texttt{DUMUX} will be produced, so you do not need to provide one).
Run the script by typing into the terminal: \texttt{./installDumux.sh} Run the script by typing into the terminal: \texttt{./installDumux.sh}
Configuring \Dune and \Dumux is done by the command-line script \texttt{dunecontrol} Configuring \Dune and \Dumux is done by the command-line script \texttt{dunecontrol}
using optimized configure options, see the line entitled \texttt{\# run build} in the \texttt{installDumux.sh} script. using optimized configure options, see the line entitled \texttt{\# run build} in the \texttt{installDumux.sh} script.
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}
...@@ -51,4 +43,4 @@ make -B test_1pcctpfa ...@@ -51,4 +43,4 @@ make -B test_1pcctpfa
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.
So, you've downloaded your very own copy of \Dumux and its dependencies.
You've run dunecontrol, and your example ``test$\_$dumux" not only compiles,
but it even shows a nice simulation in paraview.
Maybe you've read through parts of the handbook, and even started looking
through the doxygen documentation.
Well done. What now? \par
%
\textit{``How on earth is this going to help me solve my multi-(phase, component,
scale, physics) flow and transport problems in porous media systems?''}, you begin to wonder.
Don't panic! In order to best ease our prospective users and developers into the
wonderful \Dumux simulation environment, we've prepared a \Dumux course.
This course is offered once a year over a period of 3 days at the University of Stuttgart.
If you're looking for information on attending, subscribe to the \Dumux mailing list
and stay tuned for updates:
\url{https://listserv.uni-stuttgart.de/mailman/listinfo/dumux}. \par
%
\textit{``But the course won't take place for another 6 months!"} and,
\textit{``I want to start developing a numerical model of my challenging and
interesting process now!"}, you think.
Not a problem. The course materials are all shared online in their own
git repository. A series of beginner-level exercises are explained
such that you can see how a model is developed in \Dumux. As a teaser, we've
also included a suite of examples from hot topics we're working on. Models
exploring ``Coupling free flow and porous-media flow", ``Flow in fractured
porous media" and ``Fluid-solid phase change" are all introduced. \par
%
\textit{``Sounds great, but where is this material? I can't find it within
what I've downloaded."}, you question.
The \Dumux course material is available online:
\url{https://git.iws.uni-stuttgart.de/dumux-repositories/dumux-course}. \par
In order to download this repository, which acts as an additional module to
the \Dumux base, you can download an installation script with the following command:
\begin{lstlisting}[style=Bash]
$ wget https://git.iws.uni-stuttgart.de/dumux-repositories/dumux-course/raw/releases/3.0/scripts/install.sh
\end{lstlisting}
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
and slides describing the previously described examples. \par
%
The \Dumux course will be updated with each \Dumux release.
The above script will download the correct version (\textbf{releases/3.0}) of both
the \texttt{dumux} and \texttt{dumux-course} module.
The tutorial provides instructions ranging from how to set boundary conditions in \Dumux to how to set up your own \Dumux module.
Go to the directory \texttt{tutorial} in the \texttt{dumux} module and read the \texttt{README.md} (best to be opened in a web browser) for instructions on the tutorial.
...@@ -25,6 +25,13 @@ You can subscribe to the mailing list via ...@@ -25,6 +25,13 @@ You can subscribe to the mailing list via
\url{https://listserv.uni-stuttgart.de/mailman/listinfo/dumux}, then you \url{https://listserv.uni-stuttgart.de/mailman/listinfo/dumux}, then you
will be informed about upcoming releases or events. will be informed about upcoming releases or events.
\subsection{Coding Guidelines}
Writing code in a readable manner is very important, especially
for future code developers (e.g. for adding features, debugging, etc.).
For the style guide and instructions how to contribute to \Dumux visit
\url{https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/blob/master/CONTRIBUTING.md}.
\subsection{Tips and Tricks} \subsection{Tips and Tricks}
\Dumux users and developers at the LH2 are also referred to the internal Wiki for \Dumux users and developers at the LH2 are also referred to the internal Wiki for
more information. more information.
...@@ -34,7 +41,7 @@ more information. ...@@ -34,7 +41,7 @@ more information.
The options needed to be specified for that are provided using option files like The options needed to be specified for that are provided using option files like
\texttt{debug.opts} and \texttt{optim.opts}. These two compile \Dune and \Dumux \texttt{debug.opts} and \texttt{optim.opts}. These two compile \Dune and \Dumux
either for debugging or for fast simulation. Programs compiled with optimization options either for debugging or for fast simulation. Programs compiled with optimization options
can lead to a speedup of factor up to ten!\\ can lead to a speedup of factor up to ten!\par
In contrast programs that are compiled with optimization can hardly be debugged. In contrast programs that are compiled with optimization can hardly be debugged.
You can modify the files and change the compiler, the name of the build director, You can modify the files and change the compiler, the name of the build director,
add third-party dependencies, add additional compiler flags, ... . add third-party dependencies, add additional compiler flags, ... .
...@@ -64,7 +71,10 @@ To apply a patch in the same directory type: ...@@ -64,7 +71,10 @@ To apply a patch in the same directory type:
\begin{lstlisting}[style=Bash] \begin{lstlisting}[style=Bash]
$ patch -p1 < PATCHFILE $ patch -p1 < PATCHFILE
\end{lstlisting} \end{lstlisting}
See \ref{sc:patchingDUNE} if you need to apply patches to \Dumux or \Dune.
%TODO: currently, no DUNE patches necessary! Thus, this section is commented and the missing refrence would be bad.
% Uncomment the following statement again when patches might be necessary.
% See \ref{sc:patchingDUNE} if you need to apply patches to \Dumux or \Dune.
\paragraph{File Name and Line Number by Predefined Macro} \paragraph{File Name and Line Number by Predefined Macro}
If you want to know where some output or debug information came from, use the predefined If you want to know where some output or debug information came from, use the predefined
...@@ -98,9 +108,3 @@ To check one header file for all necessary includes to compile the contained cod ...@@ -98,9 +108,3 @@ To check one header file for all necessary includes to compile the contained cod
Include the option \texttt{-DENABLE\_HEADERCHECK=1} in your opts file and run \texttt{dunecontrol}. Include the option \texttt{-DENABLE\_HEADERCHECK=1} in your opts file and run \texttt{dunecontrol}.
Then go to the top level in your build-directory and type \texttt{make headercheck} to check all headers Then go to the top level in your build-directory and type \texttt{make headercheck} to check all headers
or press 'tab' to use the auto-completion to search for a specific header. or press 'tab' to use the auto-completion to search for a specific header.
\paragraph{Naming conventions}
General guidelines for naming conventions are specified in Section \ref{sc_guidelines}.
However, in order to avoid ambiguity a list of proposed names for variables, types,
functions etc is provided where users and mainly \Dumux developers can refer for
standards (check \texttt{dumux-devel/\allowbreak doc/\allowbreak naminglist/\allowbreak naming-conventions.odt}).
...@@ -30,9 +30,42 @@ The basic Git commands are: ...@@ -30,9 +30,42 @@ The basic Git commands are:
\subsection{Gnuplot} \subsection{Gnuplot}
\label{gnuplot}
A gnuplot interface is available to plot or visualize results during a simulation run. A gnuplot interface is available to plot or visualize results during a simulation run.
This is achieved with the help of the class provided in \texttt{io/gnuplotinterface.hh}. This is achieved with the help of the class provided in \texttt{io/gnuplotinterface.hh}.
Have a look at tests including this header for examples how to use this interface.
To use the gnuplot interface you have to make some modifications in your file, e.g., your main file.
First, you have to include the corresponding header file for the gnuplot interface.
\begin{lstlisting}[style=DumuxCode]
#include <dumux/io/gnuplotinterface.hh
\end{lstlisting}
Second, you have to define an instance of the class GnuplotInterface (e.g. called \texttt{gnuplot}).
\begin{lstlisting}[style=DumuxCode]
Dumux::GnuplotInterface<double> gnuplot;
\end{lstlisting}
As an example, to plot the mole fraction of nitrogen (\texttt{y}) over time (\texttt{x}),
extract the variables after each time step in the time loop.
The actual plotting is done using the method of the gnuplot interface:
\begin{lstlisting}[style=DumuxCode]
gnuplot.resetPlot(); // reset the plot
gnuplot.setXRange(0.0, 72000.0); // specify xmin and xmax
gnuplot.setYRange(0.0, 1.0); // specify ymin and ymax
gnuplot.setXlabel("time [s]"); // set xlabel
gnuplot.setYlabel("mole fraction mol/mol"); // set ylabel
// set x-values, y-values, the name of the data file and the Gnuplot options
gnuplot.addDataSetToPlot(x, y, "N2.dat", options);
gnuplot.plot("mole_fraction_N2"); // set the name of the output file
\end{lstlisting}
It is also possible to add several data sets to one plot by calling \texttt{addDataSetToPlot()} more than once.
For more information have a look into a test including the gnuplot interface header file or
the header file itself (\texttt{dumux/io/gnuplotinterface.hh}).
\subsection{Gstat} \subsection{Gstat}
......
\section{Coding Guidelines}
\label{sc_guidelines}
Writing code in a readable manner is very important, especially
for future code developers (e.g. for adding features, debugging, etc.).
For the style guide and instructions how to contribute to \Dumux visit
\url{https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/blob/master/CONTRIBUTING.md}.
...@@ -13,12 +13,15 @@ the build system there is a new one. ...@@ -13,12 +13,15 @@ the build system there is a new one.
\end{enumerate} \end{enumerate}
\paragraph{Adding new Test Programs} \paragraph{Adding new Test Programs}
\noindent To add a test use the \texttt{add\_dumux\_test} macro. \noindent To add a test use the \texttt{add\_dune\_test} macro within the \texttt{CMakeList.txt} file.
The command has four arguments: The macro can be used with a variable amount of arguments. A simple call could look like this:
\begin{enumerate}[1)]
\item name of test (has to be unique) \begin{lstlisting}[style=DumuxCode]
\item name of executable dune_add_test(NAME my_test
\item source file (*.cc) SOURCES mainfile.cc
\item command to be executed as test - either the executable or a CMD_ARGS my_test params.input)
some helper script with arguments \end{lstlisting}
\end{enumerate}
Here, we create an executable called \texttt{my\_test} from a source file \texttt{mainfile.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 executbable \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/}.
...@@ -5,9 +5,7 @@ A list of all available parameters is provided in the Doxygen documentation: \te ...@@ -5,9 +5,7 @@ A list of all available parameters is provided in the Doxygen documentation: \te
After having run the example application from section \ref{quick-start-guide} you will After having run the example application from section \ref{quick-start-guide} you will
get the following output at the end of the simulation run get the following output at the end of the simulation run
\footnote{If you did not get the output, restart the application the following way: \footnote{If you did not get the output, add \texttt{Parameters::print();} to your main file.}:
\texttt{./test{\_}2p{\_}incompressible{\_}tpfa test{\_}2p.input -PrintParameters true},
this will print the parameters once your simulation is finished}:
\begin{lstlisting}[style=Bash] \begin{lstlisting}[style=Bash]
# Runtime-specified parameters used: # Runtime-specified parameters used:
[ Grid ] [ Grid ]
...@@ -24,8 +22,9 @@ DtInitial = "250" ...@@ -24,8 +22,9 @@ DtInitial = "250"
TEnd = "3000" TEnd = "3000"
# Default parameters used: # Default parameters used:
[ Implicit ] [ Assembly ]
NumericDifferenceMethod = "1" NumericDifferenceMethod = "1"
[ Flux ]
UpwindWeight = "1.0" UpwindWeight = "1.0"
[ LinearSolver ] [ LinearSolver ]
MaxIterations = "250" MaxIterations = "250"
...@@ -64,20 +63,33 @@ A number of things can be learned: ...@@ -64,20 +63,33 @@ A number of things can be learned:
\subsection{Parameter Values} \subsection{Parameter Values}
If you want to get the value of a parameter please use: To get the value of an input parameter please use:
\begin{lstlisting}[name=propsyscars,style=DumuxCode] \begin{lstlisting}[name=propsyscars,style=DumuxCode]
paramname_ = getParam<TYPE>("GROUPNAME.PARAMNAME"); static const TYPE paramname = getParam<TYPE>("GROUPNAME.PARAMNAME");
\end{lstlisting} \end{lstlisting}
If you also want to set a default value for a parameter, just add it like this: If you also want to set a default value for a parameter, just add it like this:
\begin{lstlisting}[name=propsyscars,style=DumuxCode] \begin{lstlisting}[name=propsyscars,style=DumuxCode]
paramname_ = getParam<TYPE>("GROUPNAME.PARAMNAME", default); static const TYPE paramname = getParam<TYPE>("GROUPNAME.PARAMNAME", default);
\end{lstlisting} \end{lstlisting}
For further information you can also look at the \Dumux tutorial, especially exercise 1. As this function call is relatively expensive, the respective variables should always be \texttt{static} (e.g., if used in a loop). When dealing with multiple group names, e.g., in the context of coupled models, the fowolling methods might be more convenient:
All applications have a help message which you can read by giving \begin{lstlisting}[name=propsyscars,style=DumuxCode]
\texttt{--help} as a command line argument to the application. auto modelParamGroup0 = "Model0";
For further details, please have a look at \texttt{Dune::ParameterTree} static const TYPE paramname0 = getParamFromGroup<TYPE>(modelParamGroup0, "GROUPNAME.PARAMNAME");
in the \Dune documentation. auto modelParamGroup1 = "Model1";
static const TYPE paramname1 = getParamFromGroup<TYPE>(modelParamGroup1, "GROUPNAME.PARAMNAME");
\end{lstlisting}
The \texttt{FVProblem} class provides a convenience function \texttt{paramGroup()}.
The parameters can then be specified in the input file:
\begin{lstlisting}[style=Bash]
[ Model0.Grid ]
File = file0.dgf
[ Model1.Grid ]
File = file1.dgf
\end{lstlisting}
\section{Restart \Dumux Simulations} \section{Restart \Dumux Simulations}
\label{sc_restartsimulations} \label{sc_restartsimulations}
Restart is currently not available in the \DumuxVersion~release. We are working on it!
% You can restart the simulation \Dumux has some experimental support for check-pointing (restarting paused/stopped/crashed simulations).
% from a specific point in time or extend the simulation beyond the originally You can restart a \Dumux simulation from any time point where a VTK file was written out.
% end of simulation. What you need is a \texttt{*.drs} file (which contains the This is currently only supported for sequential, non-adaptive simulations. For adaptive simulation
% all necessary restart information. the full hierarchical grid has to be stored. This is usually done with the grid's \texttt{BackupRestoreFacility}.
% Then you can simply restart a simulation via There is currently no special support by \Dumux for that, but it is possible to implement
% \begin{lstlisting}[style=Bash] a restart using \texttt{BackupRestoreFacility} with plain Dune.
% ./test_program -TimeManager.Restart RESTART_TIME
% \end{lstlisting}
% To test restart behavior, use the \texttt{test\_box1p2cni} problem
% in the \texttt{test/implicit/1p2c} folder.
% You get the \texttt{RESTART\_TIME} from the name of your \texttt{.drs} file.
% Restarting will only work when the exact time from an existing restart file is given.
% If you need more restart files, you can change the frequency
% by including the function into your problem:
% \begin{lstlisting}[style=DumuxCode]
% // Writes a restart file every 5th time step
% bool shouldWriteRestartFile() const
% {
% return (this->timeManager().timeStepIndex() % 5 == 0);
% }
% \end{lstlisting}
For VTK files the output can be read with the free function \texttt{loadSolution}. Grids can be read with
the \texttt{Dumux::VTKReader} or you can simply recreate the grid as you did in the first simulation run.
Unfortunately, writing double-precision floating point numbers to VTK files is only available with Dune master (will be in 2.7).
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.
We are happy about any contributions (especially HDF5 / XDMF support, improvement of VTK support).
...@@ -15,7 +15,6 @@ ...@@ -15,7 +15,6 @@
\texttt{*.cc}, the problem definition \texttt{*problem.hh}, and an input file \texttt{*.input}. \texttt{*.cc}, the problem definition \texttt{*problem.hh}, and an input file \texttt{*.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.
\item \texttt{tutorial}: contains the tutorials.
\end{itemize} \end{itemize}
\begin{figure} \begin{figure}
...@@ -71,20 +70,16 @@ ...@@ -71,20 +70,16 @@
[.\node[SecondLevel] {properties}; [.\node[SecondLevel] {properties};
\node[ThirdLevel] {Base properties for all models.}; \node[ThirdLevel] {Base properties for all models.};
] ]
[.\node[SecondLevel] {typetraits};
\node[ThirdLevel] {Helper classes to query type information on compile-time. };
]
] ]
[.\node[FirstLevel] {discretization}; [.\node[FirstLevel] {discretization};
% [.\node[SecondLevel] {\emph{models}}; \node[ThirdLevel] {Common methods for all discretizations (box, cell-centered TPFA/MPFA, staggered grid): variable caching, advective and diffusive fluxes, ...};
\node[ThirdLevel] {Common methods for all discretizations: variable caching, advective and diffusive fluxes, upwinding...}; ]
% ] [.\node[FirstLevel] {flux};
[.\node[SecondLevel] {box}; [\node[ThirdLevel] {
\node[ThirdLevel] {Specific files for the box finite volume method: Collection of classes used to calculate advective and diffusive fluxes.};
specifications for advective and diffusive fluxes...};
]
[.\node[SecondLevel] {cellcentered};
\node[ThirdLevel] {Specific files for cell centered finite volume methods.};
]
[.\node[SecondLevel] {staggered};
\node[ThirdLevel] {Specific files for staggered finite volume method.};
] ]
] ]
[.\node[FirstLevel] {freeflow}; [.\node[FirstLevel] {freeflow};
...@@ -93,6 +88,11 @@ ...@@ -93,6 +88,11 @@
and eddy-viscosity based Reynolds-averaged Navier-Stokes turbulence models.}; and eddy-viscosity based Reynolds-averaged Navier-Stokes turbulence models.};
] ]
] ]
[.\node[FirstLevel] {geomechanics};
[.\node[SecondLevel] {\emph{models}};
\node[ThirdLevel] {Elastic and poro-elastic geomechanics models.};
]
]
[.\node[FirstLevel] {io}; [.\node[FirstLevel] {io};
\node[ThirdLevel] {Additional in-/output possibilities like restart files, gnuplot-interface, \node[ThirdLevel] {Additional in-/output possibilities like restart files, gnuplot-interface,
VTKWriter extensions and files for grid generation.}; VTKWriter extensions and files for grid generation.};
...@@ -126,28 +126,35 @@ ...@@ -126,28 +126,35 @@
] ]
[.\node[SecondLevel] {fluidstates}; [.\node[SecondLevel] {fluidstates};
\node[ThirdLevel] {Fluid states are responsible for caching the thermodynamic \node[ThirdLevel] {Fluid states are responsible for caching the thermodynamic
configuration of a system at a given spatial and temporal position.}; configuration of a fluid system at a given spatial and temporal position.};
] ]
[.\node[SecondLevel] {fluidsystems}; [.\node[SecondLevel] {fluidsystems};
\node[ThirdLevel] {Fluid systems express the thermodynamic relations between quantities.}; \node[ThirdLevel] {Fluid systems express the thermodynamic relations between quantities.};
] ]
[.\node[SecondLevel] {solidstates};
\node[ThirdLevel] {Solid states are responsible for caching the thermodynamic
configuration of a solid system at a given spatial and temporal position.};
]
[.\node[SecondLevel] {solidsystems};
\node[ThirdLevel] {Solid systems express the thermodynamic properties of a solid.};
]
[.\node[SecondLevel] {spatialparams}; [.\node[SecondLevel] {spatialparams};
\node[ThirdLevel] {Base class for all spatially dependent variables, like permeability and \node[ThirdLevel] {Base class for all spatially dependent variables, like permeability and
porosity. Includes spatial averaging routines. All other properties are porosity. Includes spatial averaging routines. All other properties are
specified in the specific files of the respective models.}; specified in the specific files of the respective models.};
] ]
] ]
[.\node[FirstLevel] {mixeddimension}; [.\node[FirstLevel] {multidomain};
\node[ThirdLevel] { \node[ThirdLevel] {
Coupled model with different dimensions.}; Common infrastructure to couple multiple domains, models or physics.};
[.\node[SecondLevel] {embedded}; [.\node[SecondLevel] {embedded};
\node[ThirdLevel] {Embedded mixed dimension method.}; \node[ThirdLevel] {Embedding of a lower-dimensional model into a higher-dimensional one};
] ]
[.\node[SecondLevel] {facet}; [.\node[SecondLevel] {facet};
\node[ThirdLevel] {Facet mixed dimension method.}; \node[ThirdLevel] {Mixed-dimensional coupling at facets.};
] ]
[.\node[SecondLevel] {glue}; [.\node[SecondLevel] {boundary};
\node[ThirdLevel] {Grid glue backend.}; \node[ThirdLevel] {Coupling at the domain boundaries.};
] ]
] ]
[.\node[FirstLevel] {nonlinear}; [.\node[FirstLevel] {nonlinear};
......