Skip to content
GitLab
Commit 4b88ce2c authored by Timo Koch's avatar Timo Koch
Browse files

Merge branch 'cherry-pick-b0ce2d5a' into 'releases/3.0' 

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

See merge request !1428
parents e0263ddb a47c325a
Expand all Hide whitespace changes
Inline Side-by-side
LICENSE.md
View file @ 4b88ce2c
......@@ -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 |
......
doc/handbook/0_dumux-handbook.tex
View file @ 4b88ce2c
......@@ -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}
......
doc/handbook/1_introduction.tex
View file @ 4b88ce2c
......@@ -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.
doc/handbook/2_detailedinstall.tex
View file @ 4b88ce2c
\section{Detailed Installation Instructions}
\label{install}
% \section{Detailed Installation Instructions}
% \label{install}
Installing \Dumux means that you first unpack \Dune and \Dumux in a root directory,
(section \ref{sc:ObtainingSourceCode}).
......@@ -15,10 +15,10 @@ Thus, the installation procedure of \Dumux is the same as that of \Dune.
Details regarding the installation of \Dune are provided on the \Dune website \cite{DUNE-HP}.
\subsection{Obtaining Source Code for \Dune and \Dumux}
\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.5, comprising the core modules dune-common, dune-geometry, dune-grid,
\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.
All \Dune modules, including the \Dumux module, get extracted into a common root directory, as it
is done in an ordinary \Dune installation.
......@@ -32,45 +32,45 @@ in the root directory of the respective module. This should not be changed by th
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.
% % 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.
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
% within these archives.
% The extraction from the tar files is done as follows:
% Download the tarballs from the respective \Dune (version 2.5) and \Dumux websites
% to a certain folder in your file system.
% Create the common root directory, named \texttt{DUMUX} in the example below.
% Then extract the content of the tar files, e.\,g. with the command-line program
% \texttt{tar}.
% This can be achieved by the following shell commands. Replace \texttt{path\_to\_tarball}
% with the directory name where the downloaded files are actually located.
% After extraction, the actual name of the dumux subdirectory is \texttt{dumux-\DumuxVersion}
% (or whatever version you downloaded).
%
% \begin{lstlisting}[style=Bash]
% $ mkdir DUMUX
% $ cd DUMUX
% $ tar xzvf path_to_tarball_of/dune-common-2.5.0.tar.gz
% $ tar xzvf path_to_tarball_of/dune-geometry-2.5.0.tar.gz
% $ tar xzvf path_to_tarball_of/dune-grid-2.5.0.tar.gz
% $ tar xzvf path_to_tarball_of/dune-istl-2.5.0.tar.gz
% $ tar xzvf path_to_tarball_of/dune-localfunctions-2.5.0.tar.gz
% $ tar xzvf path_to_tarball_of/dumux-3.0-alpha.tar.gz
% \end{lstlisting}
%
% Furthermore, if you wish to install the optional \Dune Grid-Howto which provides a tutorial
% on the Dune grid interface, act similar.
\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
within these archives.
The extraction from the tar files is done as follows:
Download the tarballs from the respective \Dune (version 2.6) and \Dumux websites
to a certain folder in your file system.
Create the common root directory, named \texttt{DUMUX} in the example below.
Then extract the content of the tar files, e.\,g. with the command-line program
\texttt{tar}.
This can be achieved by the following shell commands. Replace \texttt{path\_to\_tarball}
with the directory name where the downloaded files are actually located.
After extraction, the actual name of the dumux subdirectory is \texttt{dumux-\DumuxVersion}
(or whatever version you downloaded).
\begin{lstlisting}[style=Bash]
$ mkdir DUMUX
$ cd DUMUX
$ tar xzvf path_to_tarball_of/dune-common-2.6.0.tar.gz
$ tar xzvf path_to_tarball_of/dune-geometry-2.6.0.tar.gz
$ tar xzvf path_to_tarball_of/dune-grid-2.6.0.tar.gz
$ tar xzvf path_to_tarball_of/dune-istl-2.6.0.tar.gz
$ tar xzvf path_to_tarball_of/dune-localfunctions-2.6.0.tar.gz
$ tar xzvf path_to_tarball_of/dumux-3.0.tar.gz
\end{lstlisting}
Furthermore, if you wish to install the optional \Dune Grid-Howto which provides a tutorial
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.
......@@ -93,48 +93,50 @@ one for \Dune and one for \Dumux.
\begin{lstlisting}[style=Bash]
$ mkdir DUMUX
$ cd DUMUX
$ git clone -b releases/2.5 https://gitlab.dune-project.org/core/dune-common.git
$ git clone -b releases/2.5 https://gitlab.dune-project.org/core/dune-geometry.git
$ git clone -b releases/2.5 https://gitlab.dune-project.org/core/dune-grid.git
$ git clone -b releases/2.5 https://gitlab.dune-project.org/core/dune-istl.git
$ git clone -b releases/2.5 https://gitlab.dune-project.org/core/dune-localfunctions.git
$ git clone -b 3.0.0-alpha https://git.iws.uni-stuttgart.de/dumux-repositories/dumux.git
$ git clone -b releases/2.6 https://gitlab.dune-project.org/core/dune-common.git
$ git clone -b releases/2.6 https://gitlab.dune-project.org/core/dune-geometry.git
$ git clone -b releases/2.6 https://gitlab.dune-project.org/core/dune-grid.git
$ git clone -b releases/2.6 https://gitlab.dune-project.org/core/dune-istl.git
$ git clone -b releases/2.6 https://gitlab.dune-project.org/core/dune-localfunctions.git
$ git clone -b releases/3.0 https://git.iws.uni-stuttgart.de/dumux-repositories/dumux.git
\end{lstlisting}
The newest and maybe unstable developments of \Dune and \Dumux are also provided in these repositories and can be found in the \emph{master} branch.
Please check the \Dune website \cite{DUNE-HP} for further information on the \Dune development. We always try to keep up with the latest developments of \Dune.
However, the current \Dumux release is based on the stable 2.5 release and it might not compile without further adaptations using the newest versions of \Dune.
However, the current \Dumux release is based on the stable 2.6 release and it might not compile without further adaptations using the newest versions of \Dune.
Furthermore, if you wish to install the optional \Dune Grid-Howto which provides a tutorial
on the Dune grid interface, act similar.
\paragraph{Patching \Dune or external libraries}
\label{sc:patchingDUNE}
Patching of \Dune modules in order to work together with \Dumux can be necessary for several reasons.
Software like a compiler or even a standard library
changes at times. But, for example, a certain release of a software component that we depend on,
may not reflect that change and thus it has to be modified.
In the dynamic developing process of software which depends on other modules it is not always feasible
to adapt everything to the most recent version of each module. They may fix problems with a certain module
of a certain release without introducing too much structural change.
\Dumux contains patches and documentation about their usage and application within the
directory \texttt{dumux/patches}.
Please check the README file in that directory for recent information.
In general, a patch can be applied as follows
(the exact command or the used parameters may be slightly different).
We include here an example of a patching dune-grid.
\begin{lstlisting}[style=Bash]
$ # make sure you are in the common root directory
$ cd dune-grid
$ patch -p0 < ../dumux/patches/grid-2.3.1.patch
\end{lstlisting}
It can be removed by
\begin{lstlisting}[style=Bash]
$ path -p0 -R < ../dumux/patches/grid-2.3.1.patch
\end{lstlisting}
%TODO:currently, no DUNE patches necessary! Uncomment this section in case this changes again in the future.
%
% \paragraph{Patching \Dune or external libraries}
% \label{sc:patchingDUNE}
% Patching of \Dune modules in order to work together with \Dumux can be necessary for several reasons.
% Software like a compiler or even a standard library
% changes at times. But, for example, a certain release of a software component that we depend on,
% may not reflect that change and thus it has to be modified.
% In the dynamic developing process of software which depends on other modules it is not always feasible
% to adapt everything to the most recent version of each module. They may fix problems with a certain module
% of a certain release without introducing too much structural change.
%
% \Dumux contains patches and documentation about their usage and application within the
% directory \texttt{dumux/patches}.
% Please check the README file in that directory for recent information.
% In general, a patch can be applied as follows
% (the exact command or the used parameters may be slightly different).
% We include here an example of a patching dune-grid.
%
% \begin{lstlisting}[style=Bash]
% $ # make sure you are in the common root directory
% $ cd dune-grid
% $ patch -p0 < ../dumux/patches/grid-2.3.1.patch
% \end{lstlisting}
%
% It can be removed by
% \begin{lstlisting}[style=Bash]
% $ path -p0 -R < ../dumux/patches/grid-2.3.1.patch
% \end{lstlisting}
\paragraph{Hints for \Dumux-Developers}
If you also want to actively participate in the development of \Dumux, you can allways send patches
......@@ -144,14 +146,14 @@ access or for developer access on certain parts of \Dumux. Granted developer acc
you are allowed to commit own code and that you can access the \texttt{dumux-devel} module.
This enhances \texttt{dumux} by providing maybe unstable code from the developer group.
\subsection{Build of \Dune and \Dumux}
\section{Build of \Dune and \Dumux}
\label{buildIt}
Configuring \Dune and \Dumux is done by the shell-command \texttt{dunecontrol} which is part of the \Dune build system.
If you are interested in more details about the build system that is used,
they can be found in the \Dune buildsystem 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,
but also try to include error details.
but please include error details.
It is possible to compile \Dumux with nearly no explicit options to the build system.
However, for the successful compilation of \Dune and \Dumux, it is currently necessary to pass
......@@ -178,7 +180,7 @@ $ cp dumux/optim.opts my-optim.opts
$ ./dune-common/bin/dunecontrol --opts=my-optim.opts --use-cmake all
\end{lstlisting}
Sometimes it is necessary to have additional options which
Sometimes, it is necessary to have additional options which
are specific to a package set of an operating system or
sometimes you have your own preferences.
Feel free to work with your own set of options, which may evolve over time.
......@@ -188,12 +190,11 @@ The use of external libraries can make it necessary to add quite many options in
It can be helpful to give your customized option file its own name, as done above,
to avoid confusing it with the option files which came out of the distribution.
\subsection{The First Run of a Test Application}
\section{The First Run of a Test Application}
\label{quick-start-guide}
The previous section showed how to install and compile \Dumux. This chapter
The previous section showed how to install and compile \Dumux. This section
shall give a very brief introduction how to run a first test application and how
to visualize the first output files. A more detailed explanations can be found in
the tutorials in the following chapter.\\
to visualize the first output files.\par
All executables are compiled in the \texttt{build} subdirectories of \Dumux.
If not given differently in the input files, this is \texttt{build-cmake} as default.
......@@ -201,15 +202,14 @@ If not given differently in the input files, this is \texttt{build-cmake} as def
\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}
into the console. If you explicitly want to state a parameter file, type\\
\texttt{./test{\_}2p{\_}incompressible{\_}tpfa test\_2p.input}.
Adding \texttt{test\_2p.input} specifies that all
important parameters (like first timestep size, end of simulation and location
\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}
into the console.
The added \texttt{params.input} specifies that all
important run-time parameters (like first timestep 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{test\_2p.input}.
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
files. It is possible to stop a running application by pressing $<$Ctrl$><$c$>$.
......@@ -218,8 +218,14 @@ If not given differently in the input files, this is \texttt{build-cmake} as def
.pvd file. On the left hand side, you can choose the desired parameter to be displayed.
\end{enumerate}
\subsection{Building Documentation}
\subsubsection{Doxygen}
\section{Building Documentation}
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 section \ref{buildIt}.
\subsection{Doxygen}
\label{sec:build-doxy-doc}
Doxygen documentation is done by especially formatted comments integrated in the source code,
which can get extracted by the program \texttt{doxygen}. Beside extracting these comments,
......@@ -232,12 +238,12 @@ by running \texttt{dunecontrol}, entering the \texttt{build-*}directory, and exe
\texttt{MODULE\_BUILD\_DIRECTORY/doc/doxygen/html/index.html} to read the generated documentation.
This should also work for other \Dune modules.
\subsubsection{Handbook}
\subsection{Handbook}
To build the \Dumux handbook go into the \texttt{build-}directory and
run \texttt{make doc} or \texttt{make 0\_dumux-handbook\_pdf}. The pdf can then be found
in \texttt{MODULE\_BUILD\_DIRECTORY/doc/handbook/0\_dumux-handbook.pdf}.
\subsection{External Libraries and Modules} \label{sec:external-modules-libraries}
\section{External Libraries and Modules} \label{sec:external-modules-libraries}
The libraries described below provide additional functionality but are not generally required to run \Dumux.
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/}}.
......@@ -259,7 +265,7 @@ An easy way to install some of the libraries and modules given below is the
has to be called from your common root directory.
\subsubsection{List of External Libraries and Modules}
\subsection{List of External Libraries and Modules}
In the following list, you can find some external modules and external libraries,
and some more libraries and tools which are prerequisites for their use.
......@@ -274,6 +280,19 @@ and some more libraries and tools which are prerequisites for their use.
of choice for simulating structures such as foams, discrete fracture networks,
or network flow problems.
Download: \url{https://gitlab.dune-project.org/extensions/dune-foamgrid}
\item \textbf{opm-grid}: opm-grid is a DUNE module supporting grids in a corner-point format.
Download: \url{https://github.com/OPM/opm-grid.git}
\item \textbf{dune-subgrid}: The dune-subgrid module is a meta-grid implementation that allows
to mark elements of another hierarchical dune grid and use this sub-grid just like a regular grid.
The set of marked elements can then be accessed as a hierarchical dune grid in its own right.
Dune-Subgrid provides the full grid interface including adaptive mesh refinement.
Download: \url{https://git.imp.fu-berlin.de/agnumpde/dune-subgrid.git}
\item \textbf{dune-spgrid}: The DUNE module dune-spgrid provides a structured, parallel grid
and supports periodic boundary conditions.
Download: \url{https://gitlab.dune-project.org/extensions/dune-spgrid.git}
\item \textbf{SuperLU}: External library for solving linear equations. SuperLU is a general purpose
library for the direct solution of large, sparse, non-symmetric systems of linear equations.
......
doc/handbook/2_quickinstall.tex
View file @ 4b88ce2c
\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.
doc/handbook/3_course.tex 0 → 100644
View file @ 4b88ce2c
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.
doc/handbook/3_tutorial.tex deleted 100644 → 0
View file @ e0263ddb
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.
doc/handbook/4_developingdumux.tex
View file @ 4b88ce2c
......@@ -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}).
doc/handbook/4_externaltools.tex
View file @ 4b88ce2c
......@@ -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}
......
doc/handbook/4_guidelines.tex deleted 100644 → 0
View file @ e0263ddb
\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}.
doc/handbook/4_newfoldersetup.tex
View file @ 4b88ce2c
......@@ -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: