Installing \Dumux means that you first unpack \Dune and \Dumux in a root directory,
Installing \Dumux means that you first unpack \Dune and \Dumux in a root directory
(section \ref{sc:ObtainingSourceCode}).
In a second step of the installation, all modules are configured with CMake
(section \ref{buildIt}).
After successful installation of \Dumux, we guide you to start a test application,
After the successful installation of \Dumux, we guide you to start a test application,
described in section \ref{quick-start-guide}.
In section \ref{sec:build-doc}, we explain how to build the \Dumux documentation.
Lastly, section \ref{sec:external-modules-libraries} provides details on optional libraries and modules.
In a technical sense \Dumux is a module of \Dune.
In a technical sense,\Dumux is a module of \Dune.
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}.
...
...
@@ -19,8 +19,8 @@ The \Dumux release and trunk (developer tree) are based on the most recent
\texttt{dune-grid}, \texttt{dune-istl} and \texttt{dune-localfunctions}.
For working with \Dumux, these modules are required.
All \Dune modules, including the \Dumux module, get extracted into a common root directory, as it
is done in an ordinary\Dune installation.
We usually name our root directory \texttt{DUMUX} but an arbitrary name can be chosen.
is done in a typical\Dune installation.
We usually name our root directory \texttt{DUMUX}, but an arbitrary name can be chosen.
Source code files for each \Dune module are contained in their own sub-directory within the root directory.
The sub-directories for the modules are named after the module names (depending on how
the modules were obtained, a version number is added to the module name).
...
...
@@ -62,9 +62,6 @@ The newest and maybe unstable developments of \Dune and \Dumux are also provided
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.7 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.
%TODO:currently, no DUNE patches necessary! Uncomment this section in case this changes again in the future.
%
% \paragraph{Patching \Dune or external libraries}
...
...
@@ -97,7 +94,7 @@ on the Dune grid interface, act similar.
\section{Building \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.
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 build system documentation\footnote{\url{https://www.dune-project.org/buildsystem/}} and
@@ -126,19 +123,19 @@ $ ./dune-common/bin/dunecontrol --opts=my-cmake.opts all
Sometimes, it is necessary to have additional options which
are specific to a package set of an operating system or
sometimes you have your own preferences.
Feel free to work with your own set of options, which may evolve over time.
The option file that comes with the distribution is to be understood more as a starting point
for setting up an own customization than as something which is fixed.
Feel free to work with your own set of options, which may change over time.
The option file, that comes with the distribution, is to be understood more as a starting point
for setting up own customization than as something which is fixed.
The use of external libraries can make it necessary to add quite many options in an option file.
It can be helpful to give your customized option file its own name, as done above,
It can be helpful to give your customized option file a unique name, as done above,
to avoid confusing it with the option files which came out of the distribution.
\section{The First Run of a Test Application}
\label{quick-start-guide}
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
shall give a very brief introduction on how to run a first test application and how
to visualize the first output files.\par
All executables are compiled in the \texttt{build} sub-directories of \Dumux.
All executable files are compiled in the \texttt{build} sub-directories of \Dumux.
If not specified differently in the options file, this is \texttt{build-cmake} as default.
\begin{enumerate}
...
...
@@ -147,7 +144,7 @@ If not specified differently in the options file, this is \texttt{build-cmake} a
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 time step size, end of simulation and location
important run-time parameters (such as first time step size, end of simulation and location
of the grid file) can be found in a text file in the same directory with the
name \texttt{params.input}.
\item The simulation starts and produces some VTU output files and also a PVD
...
...
@@ -155,7 +152,7 @@ If not specified differently in the options file, this is \texttt{build-cmake} a
files. It is possible to stop a running application by pressing $<$Ctrl$><$c$>$.
\item You can display the results using the visualization tool ParaView (or
alternatively VisIt). Just type \texttt{paraview} in the console and open the
PVD file. On the upper lefthand side, you can choose the desired parameter to be displayed.
PVD file. On the upper left-hand side, you can choose the desired parameter to be displayed.
\end{enumerate}
\section{Building Documentation}
...
...
@@ -167,29 +164,30 @@ in the \texttt{CONFIGURE\_FLAGS} of the building options, see section \ref{build
\subsection{Doxygen}
\label{sec:build-doxy-doc}
Doxygen documentation is done by specifically formatted comments integrated in the source code,
which can get extracted by the program \texttt{doxygen}. Beside extracting these comments,
Doxygen documentation is done by specifically formatted comments included in the source code,
which can get extracted by the program \texttt{doxygen}. Besides extracting these comments,
\texttt{doxygen} builds up a web-browsable code-structure documentation
like class hierarchy of code displayed as graphs, see \url{http://www.stack.nl/~dimitri/doxygen/}.
like class hierarchy of code displayed as graphs, see \url{https://www.doxygen.nl/index.html}.
The Doxygen documentation of a module can be built if \texttt{doxygen} is installed,
by running \texttt{dunecontrol}, entering the \texttt{build-*}directory, and executing
The Doxygen documentation of a module can be built by running \texttt{dunecontrol} (if \texttt{doxygen} is installed), entering the \texttt{build-*}directory, and executing
\texttt{make doc}. Then point your web browser to the file
\texttt{MODULE\_BUILD\_DIRECTORY/doc/doxygen/html/index.html} to read the generated documentation.
This should also work for other \Dune modules.
\subsection{Handbook}
To build the \Dumux handbook go into the \texttt{build-}directory and
To build the \Dumux handbook, navigate to the \texttt{build-}directory and
run \texttt{make doc} or \texttt{make doc\_handbook\_0\_\\dumux-handbook\_pdf}. The pdf can then be found
in \texttt{MODULE\_BUILD\_DIRECTORY/doc/handbook/0\_dumux\\-handbook.pdf}.
\section{External Libraries and Modules}\label{sec:external-modules-libraries}
The libraries described below provide additional functionality but are not generally required to run \Dumux.
If you are going to use an external library, check the information provided on the \Dune website%
\footnote{DUNE: External libraries, \url{https://www.dune-project.org/doc/external-libraries/}}. You can consult the \Dune website for higher-level \Dune modules, such as Grid Modules
Installing an external library can require additional libraries which are also used by \Dune.
For some libraries, such as BLAS or MPI, multiple versions can be installed on the system.
...
...
@@ -199,10 +197,7 @@ Some of the libraries are then compiled within that directory and are not instal
a different place, but \Dune may need to know their location. Thus, one may have to refer to
them as options for \texttt{dunecontrol}, for example via the options file \texttt{my-cmake.opts}.
Make sure you compile the required external libraries before you run \texttt{dunecontrol}.
An easy way to install some of the libraries and modules given below is the
\texttt{installexternal.sh} script located in \texttt{bin}. The script
has to be called from your common root directory.
An easy way to install some of the libraries and modules, given below, is the \texttt{installexternal.py} script located in \texttt{bin}. The script has to be called from your common root directory.
\subsection{List of External Libraries and Modules}
...
...
@@ -270,9 +265,9 @@ depending on which modules of \Dune and which external libraries you use.
\section{Backwards Compatibility}
\label{sec:backwardscompatibility}
Dumux Releases are split into major (e.g. 2.0, 3.0) and minor (e.g. 3.1, 3.2, 3.3) releases.
Major releases are not required to maintain backwards compatibility,
but would provide a detailed guide on how to update dependent modules.
Dumux Releases are split into major (e.g. 2.0, 3.0) and minor (e.g. 3.1, 3.2, 3.3, 3.4) releases.
Major releases are not required to maintain backwards compatibility
but would provide a detailed guide on updating dependent modules.
For each minor release, maintaining backwards compatibility is strongly encouraged and recommended.
Maintaining backwards compatibility means for all changes made to the dumux master, each tests and all dumux dependent modules should still compile. In addition, the user should be warned at compile time of any relevant interface changes. This can be done by deprecating the old method with a deprecation message and forwarding it to the new method. Examples of this are shown in the \href{https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/blob/master/CONTRIBUTING.md}{contribution guide}. Each of these deprecation messages should also include the release in which the interface will be removed, and all changes should be documented thoroughly in the \href{https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/-/blob/master/CHANGELOG.md}{changelog.md}.
@@ -14,4 +14,4 @@ the \texttt{Dumux::VTKReader} or you can simply recreate the grid as you did in
Writing double-precision floating point numbers to VTK files is available with the newest \Dune release 2.7. If you are using that version, it is now possible to specify output precision in the input file using \texttt{Vtk.Precision} followed by either \texttt{Float32}, \texttt{Float64}, \texttt{UInt32}, \texttt{UInt8} or \texttt{Int32}. \texttt{Float32} is set as the default. We especially advice the use of \texttt{Float64} when working with restart files.
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).
We are looking forward to any contributions (especially HDF5 / XDMF support, improvement of VTK support).
@@ -16,7 +16,7 @@ For compositional multi-phase models, fluid phases may be composed of several co
\item[Components:]
The term \emph{component} stands for constituents of the phases which
can be associated with a unique chemical species, or, more generally, with
can be associated with a unique chemical species or, more generally, with
a group of species exploiting similar physical behavior. For example, Fig. \ref{fig:phaseMassEnergyTransfer} shows a water-gas-NAPL system composed of the phases water (subscript
$\text{w}$), gas ($\text{g}$), and NAPL ($\text{n}$). These phases are
composed of the components water (superscript $\text{w}$), the pseudo-component
@@ -222,8 +222,7 @@ model domain and $F(u) = F(\mathbf v, p) = F(\mathbf v(x,t), p(x,t))$.
Like the FE method, the box method follows the principle of weighted residuals.
In the function $f(u)$ the unknown $u$ is approximated by discrete values at the
nodes of the FE mesh $\hat u_i$ and linear basis functions $N_i$ yielding an
approximate function $f(\tilde u)$. For $u\in\lbrace\mathbf v, p, x^\kappa\rbrace$
this means:
approximate function $f(\tilde u)$. For $u\in\lbrace\mathbf v, p, x^\kappa\rbrace$, this means:
\begin{minipage}[b]{0.47\textwidth}
\begin{equation}
...
...
@@ -255,8 +254,7 @@ this means:
\end{equation}
\end{minipage}
Due to the approximation with node values and basis functions the differential
equations are not exactly fulfilled anymore but a residual $\varepsilon$ is produced.
Due to the approximation with node values and basis functions, the differential equations are not exactly fulfilled anymore but a residual $\varepsilon$ is produced.
