Commit e818ce99 authored by Johannes Hommel's avatar Johannes Hommel Committed by Martin Schneider
Browse files

[handbook] updated 'getting started' chapter, split in 'quick start' and...

[handbook] updated 'getting started' chapter, split in 'quick start' and 'detailed installation, documentation and externals'
parent 602eb230
......@@ -110,14 +110,16 @@ 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{Learning to use \Dumux}\label{chp:tutorial}
......
\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,9 +190,9 @@ 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.\\
......@@ -201,15 +203,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 +219,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 +239,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 +266,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.
......
\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.
......@@ -71,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
......
......@@ -11,22 +11,22 @@ echo "*************************************************"
# the core modules
for MOD in common geometry grid localfunctions istl; do
if [ ! -d "dune-$MOD" ]; then
git clone -b releases/2.5 https://gitlab.dune-project.org/core/dune-$MOD.git
git clone -b releases/2.6 https://gitlab.dune-project.org/core/dune-$MOD.git
else
echo "Skip cloning dune-$MOD because the folder already exists."
cd dune-$MOD
git checkout releases/2.5
git checkout releases/2.6
cd ..
fi
done
# dumux
if [ ! -d "dumux" ]; then
git clone -b 3.0.0-alpha https://git.iws.uni-stuttgart.de/dumux-repositories/dumux.git
git clone -b releases/3.0 https://git.iws.uni-stuttgart.de/dumux-repositories/dumux.git
else
echo "Skip cloning dumux because the folder already exists."
cd dumux
git checkout 3.0.0-alpha
git checkout releases/3.0
cd ..
fi
......@@ -42,7 +42,7 @@ echo "(2/2) Configure dune modules and dumux. Build the
dune libaries. This may take several minutes."
echo "*************************************************"
# run build
./dune-common/bin/dunecontrol --opts=dumux/myoptim.opts all
./dune-common/bin/dunecontrol --opts=dumux/optim.opts all
#
if [ $? -ne 0 ]; then
echo "*************************************************"
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment