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
| 2012-2014 | Alexandru Tatomir |
| 2015-2017 | Larissa de Vries |
| 2013 | Katharina Türk |
| 2018 | Martin Utz |
| 2010-2014 | Lena Walter |
| 2018 | Felix Weinhardt |
| 2015-2017 | Kilian Weishaupt |
......
......@@ -11,6 +11,7 @@
\usepackage{enumerate}
\usepackage{hyperref}
\usepackage{graphicx}
\usepackage{listings}
\usepackage{makeidx}
\usepackage[square,numbers]{natbib}
......@@ -72,6 +73,7 @@
\DeclareMathOperator{\grad}{\mathbf{grad}}
\DeclareMathOperator{\curl}{curl}
\DeclareMathOperator{\Div}{div}
\newcommand{\meas}[1]{\lvert{#1}\rvert}
\pagestyle{scrheadings}
......@@ -109,31 +111,32 @@ Universit\"at Stuttgart, Paffenwaldring 61, D-70569 Stuttgart, Germany}\\
\chapter{Introduction}
\input{1_introduction}
\chapter{Getting started}
\chapter{Quick Start}\label{quick-install}
In this chapter we provide a quick start guide to
your first \Dumux experience.
The first section contains instructions on how to very quickly install \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.
your first \Dumux experience, including an install script with all necessary instructions
on how to very quickly install the latest release version of \Dumux.
\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}
\chapter{Tutorial}\label{chp:tutorial}
\input{3_tutorial}
\chapter{Learning to use \Dumux}\label{chp:tutorial}
\input{3_course}
\input{3_furtherpractice}
\chapter{Overview and Infrastructure}
This chapter provides an overview of the general structure in \Dumux \ref{sc_structure}
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
concepts \ref{sc_linearsystem}.
\input{4_structure}
\input{4_newfoldersetup}
\input{4_parameterfiles}
\input{4_restartsimulations}
\input{4_guidelines}
\input{4_developingdumux}
\input{4_externaltools}
\input{4_assemblinglinearsystem}
......@@ -145,7 +148,8 @@ in deeper modifications of underlying \Dumux models, classes, functions, etc.
\input{5_spatialdiscretizations}
\input{5_stepsofasimulation}
\input{5_propertysystem}
\input{5_grids}
\input{5_inputoutput}
\input{5_parallel}
\bibliographystyle{plainnat}
\bibliography{dumux-handbook}
......
......@@ -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}.}.
\begin{figure}[hbt]
\centering
\includegraphics[width=.5\linewidth, keepaspectratio]{PNG/dunedesign.png}
\includegraphics[width=.5\linewidth, keepaspectratio]{png/dunedesign.png}
\caption{
\label{fig:dune-design}
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
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. 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}.
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,
to general concepts for model coupling.
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}
\label{quick-install}
This section only provides one quick way of installing \Dumux.
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 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:
\begin{itemize}
\item GitLab client
......@@ -17,12 +14,7 @@ For this quick start guide the following software packages are required:
\item paraview (to visualize the results)
\end{itemize}
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}
in the \texttt{CONFIGURE\_FLAGS} of the building options, see Chapter \ref{buildIt}.
\subsection{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
and configures all modules with CMake.
% 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).
Run the script by typing into the terminal: \texttt{./installDumux.sh}
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}.
\subsection{A first test run of \Dumux}
......@@ -51,4 +43,4 @@ make -B test_1pcctpfa
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.
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
\url{https://listserv.uni-stuttgart.de/mailman/listinfo/dumux}, then you
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}
\Dumux users and developers at the LH2 are also referred to the internal Wiki for
more information.
......@@ -34,7 +41,7 @@ more information.
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
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.
You can modify the files and change the compiler, the name of the build director,
add third-party dependencies, add additional compiler flags, ... .
......@@ -64,7 +71,10 @@ To apply a patch in the same directory type:
\begin{lstlisting}[style=Bash]
$ patch -p1 < PATCHFILE
\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}
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
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
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:
\subsection{Gnuplot}
\label{gnuplot}
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}.
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}
......
\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.
\end{enumerate}
\paragraph{Adding new Test Programs}
\noindent To add a test use the \texttt{add\_dumux\_test} macro.
The command has four arguments:
\begin{enumerate}[1)]
\item name of test (has to be unique)
\item name of executable
\item source file (*.cc)
\item command to be executed as test - either the executable or a
some helper script with arguments
\end{enumerate}
\noindent To add a test use the \texttt{add\_dune\_test} macro within the \texttt{CMakeList.txt} file.
The macro can be used with a variable amount of arguments. A simple call could look like this:
\begin{lstlisting}[style=DumuxCode]
dune_add_test(NAME my_test
SOURCES mainfile.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}.
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
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
\footnote{If you did not get the output, restart the application the following way:
\texttt{./test{\_}2p{\_}incompressible{\_}tpfa test{\_}2p.input -PrintParameters true},
this will print the parameters once your simulation is finished}:
\footnote{If you did not get the output, add \texttt{Parameters::print();} to your main file.}:
\begin{lstlisting}[style=Bash]
# Runtime-specified parameters used:
[ Grid ]
......@@ -24,8 +22,9 @@ DtInitial = "250"
TEnd = "3000"
# Default parameters used:
[ Implicit ]
[ Assembly ]
NumericDifferenceMethod = "1"
[ Flux ]
UpwindWeight = "1.0"
[ LinearSolver ]
MaxIterations = "250"
......@@ -64,20 +63,33 @@ A number of things can be learned:
\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]
paramname_ = getParam<TYPE>("GROUPNAME.PARAMNAME");
static const TYPE paramname = getParam<TYPE>("GROUPNAME.PARAMNAME");
\end{lstlisting}
If you also want to set a default value for a parameter, just add it like this:
\begin{lstlisting}[name=propsyscars,style=DumuxCode]
paramname_ = getParam<TYPE>("GROUPNAME.PARAMNAME", default);
static const TYPE paramname = getParam<TYPE>("GROUPNAME.PARAMNAME", default);
\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
\texttt{--help} as a command line argument to the application.
For further details, please have a look at \texttt{Dune::ParameterTree}
in the \Dune documentation.
\begin{lstlisting}[name=propsyscars,style=DumuxCode]
auto modelParamGroup0 = "Model0";
static const TYPE paramname0 = getParamFromGroup<TYPE>(modelParamGroup0, "GROUPNAME.PARAMNAME");
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}
\label{sc_restartsimulations}
Restart is currently not available in the \DumuxVersion~release. We are working on it!
% You can restart the simulation
% from a specific point in time or extend the simulation beyond the originally
% end of simulation. What you need is a \texttt{*.drs} file (which contains the
% all necessary restart information.
% Then you can simply restart a simulation via
% \begin{lstlisting}[style=Bash]
% ./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}
\Dumux has some experimental support for check-pointing (restarting paused/stopped/crashed simulations).
You can restart a \Dumux simulation from any time point where a VTK file was written out.
This is currently only supported for sequential, non-adaptive simulations. For adaptive simulation
the full hierarchical grid has to be stored. This is usually done with the grid's \texttt{BackupRestoreFacility}.
There is currently no special support by \Dumux for that, but it is possible to implement
a restart using \texttt{BackupRestoreFacility} with plain Dune.
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 @@
\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}.
For more detailed descriptions of the tests, please have a look at the Doxygen documentation.
\item \texttt{tutorial}: contains the tutorials.
\end{itemize}
\begin{figure}
......@@ -71,20 +70,16 @@
[.\node[SecondLevel] {properties};
\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[SecondLevel] {\emph{models}};
\node[ThirdLevel] {Common methods for all discretizations: variable caching, advective and diffusive fluxes, upwinding...};
% ]
[.\node[SecondLevel] {box};
\node[ThirdLevel] {Specific files for the box finite volume method:
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[ThirdLevel] {Common methods for all discretizations (box, cell-centered TPFA/MPFA, staggered grid): variable caching, advective and diffusive fluxes, ...};
]
[.\node[FirstLevel] {flux};
[\node[ThirdLevel] {
Collection of classes used to calculate advective and diffusive fluxes.};
]
]
[.\node[FirstLevel] {freeflow};
......@@ -93,6 +88,11 @@
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[ThirdLevel] {Additional in-/output possibilities like restart files, gnuplot-interface,
VTKWriter extensions and files for grid generation.};
......@@ -126,28 +126,35 @@
]
[.\node[SecondLevel] {fluidstates};
\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[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[ThirdLevel] {Base class for all spatially dependent variables, like permeability and
porosity. Includes spatial averaging routines. All other properties are
specified in the specific files of the respective models.};
]
]
[.\node[FirstLevel] {mixeddimension};
[.\node[FirstLevel] {multidomain};
\node[ThirdLevel] {
Coupled model with different dimensions.};
Common infrastructure to couple multiple domains, models or physics.};
[.\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[ThirdLevel] {Facet mixed dimension method.};
\node[ThirdLevel] {Mixed-dimensional coupling at facets.};
]
[.\node[SecondLevel] {glue};
\node[ThirdLevel] {Grid glue backend.};
[.\node[SecondLevel] {boundary};
\node[ThirdLevel] {Coupling at the domain boundaries.};
]
]
[.\node[FirstLevel] {nonlinear};
......
\section{Grid Handling}
\label{sec:gridhandling}
This section summarizes some ideas about grid generation and grid formats that can be used by \Dumux. In general,
\Dumux can read grids from file, or, construct grids inside the code. All grids are constructed inside a so called \texttt{GridCreator} which is a \Dumux property.
Note that some \texttt{GridCreator}s are already available in \Dumux, so e.g.
construction of a structured grid is fairly easy. We will subsequently introduce the supported file formats, the standard grid creator and its capabilities,
and briefly mention how to customize and deal with common other grid formats.
\subsection{Supported file formats}
\Dumux can read grids from file using the Dune Grid Format (DGF) or the Gmsh mesh format.
\subsubsection{Dune Grid Format}
Most of our \Dumux tests and tutorials use the Dune Grid Format (DGF) to read in grids. A detailed description
of the DGF format and some examples can be found in the \Dune doxygen documentation
\textbf{(Modules $\rightarrow$ I/O $\rightarrow$ Dune Grid Format (DGF)}). To generate larger or more
complex DGF files, we recommend to write your own scripts, e.g in \Cplusplus, Matlab or Python.
The DGF format can also used to read in spatial parameters defined on the grid. These parameters can
be defined on nodes as well as on the elements. An example for predefined parameters on a grid
can be found in the \texttt{dumux/test/porousmediumflow/co2/implicit/} folder.
\subsubsection{Gmsh Mesh Format}
Gmsh is an open-source flexible grid generator for unstructured finite-element meshes (\cite{GEUZAINE2009}, \url{http://geuz.org/gmsh/}).
\Dumux supports the default Gmsh mesh format (MSH). For the format specifics and how to create grids with Gmsh, e.g. using
the provided GUI, we refer to the Gmsh documentation (\url{http://geuz.org/gmsh/doc/texinfo/gmsh.html}).
The MSH format can contain element and boundary markers defined in the grid. Thus, boundaries can be easily marked as e.g. inflow boundaries
using Gmsh. Further, the format supports higher order elements. They can be used to create boundary parameterization supported by e.g. the grid
manager \texttt{UGGrid}.
An example can be found in \texttt{dumux/test\allowbreak/io/gridcreator}.
\subsection{The default \texttt{GridCreator}}
The default \texttt{GridCreator} is called \texttt{GridCreator} and is automatically avaible in all problems.
It can construct grids from a DGF file (*.dgf) by simply providing the filename to the grid in the \texttt{Grid} group~\footnote{Note
that group name \texttt{Grid} is the default group name and can be customized in your problem changing the string property \texttt{GridParameterGroup}.
This way it is possible, e.g. for problems with more than one grid, to set different group names for each grid, thus configuring them separately.}
of the input file:
\begin{lstlisting}[style=DumuxParameterFile]
[Grid]
File = mydgfgrid.dgf
\end{lstlisting}
If you are using an unstructured grid manager like \texttt{UGGrid} or \texttt{ALUGrid}, constructing a grid from a Gmsh mesh file (*.msh) is just changing a line:
\begin{lstlisting}[style=DumuxParameterFile]
[Grid]
File = mygmshgrid.msh
\end{lstlisting}
\Dumux will tell you in case your selected grid manager does not support reading Gmsh files. You want to intially refine your grid? It's just adding a line:
\begin{lstlisting}[style=DumuxParameterFile]
[Grid]
File = mydgfgrid.dgf
Refinement = 4
\end{lstlisting}
When reading a Gmsh file, further parameters are recognized. \texttt{Verbose} enables verbose output on grid construction when set to $1$.
\texttt{BoundarySegments} enables reading parametrized boundaries. \texttt{PhysicalEntities} enables reading boundary and element flags.
\subsubsection{Grid manager specific parameters}
The default \texttt{GridCreator} supports also a selection of grid specific parameters.
To give an example we look at the commonly used unstructured grid manager \texttt{UGGrid}.
\texttt{UGGrid}s support red-green refinement per default. One can turn off the green closure by setting the grid's closure type
\begin{lstlisting}[style=DumuxParameterFile]
[Grid]
File = mydgfgrid.dgf
ClosureType = None # or Green
\end{lstlisting}
For all available parameters see the Doxygen documentation.
\subsubsection{Structured grids}
If you want to construct a structured grid with the default grid creator instead of the \texttt{File} key supply
\begin{lstlisting}[style=DumuxParameterFile]
[Grid]
LowerLeft = 0 0 0
UpperRight = 1 1 1
Cells = 10 10 20
\end{lstlisting}
where \texttt{LowerLeft} is a vector to the lower left corner of the grid and \texttt{UpperRight} a vector to the upper right corner.
\texttt{Cells} is a vector with the number of cells in each coordinate direction. Note that for a grid in a two-dimensional world, the
vectors only have two entries.
Depending on the grid manager further parameters are recognized.
\texttt{UGGrid}s, for example, supports simplex elements as well as hexahedral elements
(called simplified ``cube'' in \Dune). When creating a structured grid, we can select the cell type as follows
\begin{lstlisting}[style=DumuxParameterFile]
[Grid]
LowerLeft = 0 0 0
UpperRight = 1 1 1
Cells = 10 10 20
CellType = Cube # or Simplex
\end{lstlisting}
For all available parameters see the Doxygen documentation.
\subsection{Other grid formats and customized grid creators}
Other grid formats than DGF and MSH have to be converted to DGF or MSH to be read into \Dumux. A second possiblity (advanced \Cplusplus) is to write your own
\texttt{GridCreator}.
A (non-comprehensive) list of hints for some other common grid formats follows.
\subsubsection{Petrel}
Grids from Petrel (in ASCII format with the extension *.GRDECL) can be imported into \Dumux in two ways:
\begin{enumerate}
\item Using the GRDECL format directly with the help of the grid-manager \texttt{dune-cornerpoint}.
\item Converting the GRDECL file into the DGF format.
\end{enumerate}
The fist options requires the installation of \texttt{dune-cornerpoint} along with its dependencies. Set the property \texttt{Grid} to \texttt{Dune::CpGrid} in your problem file.
The second option has the advantage that you end up with a DGF which can then be used with any grid-manager (\texttt{dune-alugrid}, \texttt{UG} etc.) You also have to install \texttt{dune-cornerpoint}. Additionally you have to modify the converter \texttt{grdecl2vtu} found in \texttt{dune-cornerpoint/examples} to also write a DGF. To do so you have to:
\begin{itemize}
\item Include the \texttt{dgfwriter.hh} found in \texttt{dune-grid/dune/grid/io/file/dgfparser}
\item Create an object of the \texttt{Dune::DGFWriter} and call the its function \texttt{write()} within the \texttt{main} function for example after the \texttt{vtkwriter()} is called:
\begin{lstlisting}[style=DumuxCode]
Dune::DGFWriterParam<CpGrid::LeafGridView> dgfWriter(grid.leafView()))
dgfWriter.write(fnamebase + ".dgf")
\end{lstlisting}
\end{itemize}
Material parameters for elements with Petrel specific keywords like \texttt{PORO} are parsed by the converter \texttt{grdecl2vtu} (see the \texttt{main} function). They are available as vectors within the \texttt{main} function. The main GRDECL file with the coordinates must include the GRDECL files of the parameters, if for example the parameters are not already included, include the file bearing your parameter in your main GRDECL file:
\begin{lstlisting}
INCLUDE
'PARAMETER_X.GRDECL'
/
\end{lstlisting}
To add the parameters to your DGF you have to make changes to the header \texttt{dgfwriter.hh} such that they are passed as arguments of the \texttt{write()} function and written after each element (modify \texttt{writeElement()} and internal \texttt{write()} functions accordingly). Take caution that you stick to the correct DGF syntax (see \textbf{Modules $\rightarrow$ I/O $\rightarrow$ Dune Grid Format (DGF)} for reference).
\subsubsection{ArtMesh}
\href{http://www.topologica.org/toplog/wp/}{ArtMesh} is a 3D mesh generation software. It has its own mesh file format
which can be read by \Dumux via the \texttt{ArtGridCreator}. Traditionally it was used within \Dumux for fracture simulations with
the discrete fracture matrix model (\texttt{2pdfm}). A detailed description of the fracture network creation and gridding
can be found for example in \cite{Tatomir2012a}, pp. 68.
\subsubsection{ICEM}
For complex geometries a graphical tool to create grids might be appropriate. One possibility to mesh for example CAD
geometry data is the commercial software \href{http://www.ansys.com/Products/Other+Products/ANSYS+ICEM+CFD/}{ANSYS ICEM
CFD}. A very detailed, but outdated description can be found at the LH2 internal wiki. A more recent best practice guide is available
in dumux-devel at dumux-devel/util/gridconverters/Documentation\_ICEM\_CFD\_create\_mesh.odt. At LH2 exists a script which converts the ICEM mesh into the DGF.
% \subsubsection{Cornerpoint grids}
% TODO
\section{Input and Output}
\label{sec:inputandoutput}
This section briefly explains grid generation in \Dumux, summarizes
the grid formats that can be used by \Dumux and introduces the \Dumux \texttt{GridManager}.
Finally, this section informs about handling output in \Dumux.
\subsection{Supported grid file formats}
\Dumux can read grids from file using the Dune Grid Format (DGF) or the Gmsh mesh format (MSH).
Using the class \texttt{Dumux::VTKReader}, \Dumux has experimental support for reading grids and data from VTK files.
\subsubsection{Dune Grid Format}
Most of our \Dumux tests use the Dune Grid Format (DGF) to read in grids. A detailed description
of the DGF format and some examples can be found in the \Dune doxygen documentation
\textbf{(Modules $\rightarrow$ I/O $\rightarrow$ Dune Grid Format (DGF)}). To generate larger or more
complex DGF files, we recommend to write your own scripts, e.g, in \Cplusplus, Matlab or Python.
The DGF format can also be used to read in spatial parameters defined on the grid. These parameters can
be defined on nodes as well as on the elements. An example for predefined parameters on a grid
can be found in \texttt{dumux/test/porousmediumflow/co2/implicit/}.
\subsubsection{Gmsh Mesh Format}
Gmsh is an open-source flexible grid generator for unstructured finite-element meshes (\cite{GEUZAINE2009}, \url{http://geuz.org/gmsh/}).
\Dumux supports the default Gmsh mesh format (MSH). For the format specifics and how to create grids with Gmsh, e.g., using
the provided GUI, we refer to the Gmsh documentation (\url{http://geuz.org/gmsh/doc/texinfo/gmsh.html}).
The MSH format can contain element and boundary markers defined on the grid. Thus, boundaries can be easily marked as, e.g., inflow boundaries
using Gmsh. Further, the format supports higher order elements. They can be used to create boundary parameterization supported by, e.g., the grid
manager \texttt{UGGrid}.
An example can be found in \texttt{dumux/test\allowbreak/io/gridmanager}.
\subsubsection{Other Grid Formats}
Grid formats other than DGF, MSH, VTK will have to be converted to the DGF, MSH, VTK format before they can be used in \Dumux.
If conversion is not an option, another possibility would be to write your own \texttt{GridManager}. Examples of other grid formats,
which have previously been either converted or custom-created in \Dumux, are Petrel grids (cornerpoint grids),
ArtMesh grids (fractured network grids), and ICEM grids (CAD developed grids).
\subsection{The \Dumux \texttt{GridManager}}
The \Dumux \texttt{GridManager} constructs the grid from information in the input file and handles the data.
Currently, supported grid managers are \texttt{YaspGrid}, \texttt{OneDGrid}, \texttt{dune-uggrid}, \texttt{dune-alugrid}, \texttt{dune-foamgrid}, \texttt{dune-subgrid}, \texttt{opm-grid} (cornerpoint grids) and \texttt{dune-spgrid}.
Grids can be constructed from a DGF or MSH file by simply providing the filename to the grid in the \texttt{Grid} group~\footnote{Note,
that group name \texttt{Grid} is the default group name and can be customized in your problem changing the string property \texttt{GridParameterGroup}.
This way, it is possible, e.g., for problems with more than one grid, to set different group names for each grid, thus configuring them separately.}
of the input file:
\begin{lstlisting}[style=DumuxParameterFile]