From ad8b4e10b43d51c7e8c8d8484be5a5f32ba19347 Mon Sep 17 00:00:00 2001
From: melaniel <melanie.lipp@iws.uni-stuttgart.de>
Date: Wed, 2 Oct 2019 17:09:06 +0200
Subject: [PATCH] [doc][handbook] Small revisions of chapter 4-6.
---
doc/handbook/0_dumux-handbook.tex | 8 ++---
doc/handbook/4_furtherpractice.tex | 11 +++---
doc/handbook/5_assemblinglinearsystem.tex | 8 ++---
doc/handbook/5_developingdumux.tex | 12 +++----
doc/handbook/5_externaltools.tex | 3 +-
doc/handbook/5_newfoldersetup.tex | 4 +--
doc/handbook/5_parameterfiles.tex | 5 ++-
doc/handbook/5_structure.tex | 6 ++--
doc/handbook/6_basics.tex | 41 +++++++++--------------
doc/handbook/6_inputoutput.tex | 4 +--
doc/handbook/6_propertysystem.tex | 10 +++---
11 files changed, 50 insertions(+), 62 deletions(-)
diff --git a/doc/handbook/0_dumux-handbook.tex b/doc/handbook/0_dumux-handbook.tex
index ed9e3ee8c7..afd34f2bf8 100644
--- a/doc/handbook/0_dumux-handbook.tex
+++ b/doc/handbook/0_dumux-handbook.tex
@@ -141,11 +141,11 @@ wonderful \Dumux simulation environment, we've prepared a \Dumux course and exte
\input{4_furtherpractice}
\chapter{Overview and Infrastructure}
-This chapter provides an overview of the general structure in \Dumux \ref{sc_structure}
+This chapter provides an overview of the general structure in \Dumux (\ref{sc_structure})
and gives help for basic work with \Dumux
-(\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}.
+(\ref{sc_newfoldersetup}-\ref{sc_developingdumux}).
+Further it presents useful external tools (\ref{sc_externaltools}) and basic
+concepts (\ref{sc_linearsystem}).
\input{5_structure}
\input{5_newfoldersetup}
\input{5_parameterfiles}
diff --git a/doc/handbook/4_furtherpractice.tex b/doc/handbook/4_furtherpractice.tex
index 0d49b97db8..76c6c31209 100644
--- a/doc/handbook/4_furtherpractice.tex
+++ b/doc/handbook/4_furtherpractice.tex
@@ -21,24 +21,25 @@ The module is structured based on the different lectures:
\item mhs: Modelling of Hydrosystems.
\end{itemize}
The majority of applications is covered in the course Multiphase Modelling (mm),
-while there are also some basic examples from the
+while there are also some basic examples in the
courses Environmental Fluid Mechanics (efm) and Modelling of Hydrosystems (mhs).
These applications are primarily designed to enhance the understanding of conceptualizing the
governing physical processes and their implementation in a numerical simulator.
Different aspects of modeling multi-phase multi-component flow and transport processes are shown.
-The lectures focus on questions like, e. g., the assignment of boundary conditions, the choice of the
+The lectures focus on questions like the assignment of boundary conditions, the choice of the
appropriate physics for a given problem (which phases, which components), discretization issues,
time stepping. You can find, e. g., a comparison of different two-phase flow problems: The
-more simple approach considers two immiscible fluids while components in both phases with inter-phase
+simpler approach considers two immiscible fluids while components in both phases with inter-phase
mass transfer are considered in the more complex approach.
All scenarios and their physical background are explained in additional .tex-files,
which are provided in sub-directories named \texttt{description}. The following test cases are
contained in the \texttt{dumux-lecture} module:
\begin{itemize}
\item \texttt{buckleyleverett}: The Buckley-Leverett Problem is a classical porous media flow show case
-\item \texttt{co2plume}: Analysis of the influence of the gravitational number on the $\text{CO}_2$ plume
-\item \texttt{columnxylene}: A VEGAS experiment
+\item \texttt{co2plume}: Analysis of the influence of the gravitational number on a $\text{CO}_2$ plume
+\item \texttt{columnxylene}: An experiment of the Research Facility for Subsurface Remediation, University of Stuttgart
\item \texttt{convectivemixing}: A test case related to CO$_2$ storage
+\item \texttt{fractures}: Two-phase flow in fractured porous media
\item \texttt{fuelcell}: Water management in PEM fuel cells
\item \texttt{heatpipe}: A show case for two-phase two-component flow with heat fluxes
\item \texttt{heavyoil}: Steam assisted gravity drainage (SAGD)
diff --git a/doc/handbook/5_assemblinglinearsystem.tex b/doc/handbook/5_assemblinglinearsystem.tex
index e05dad50ab..ddb50b41cb 100644
--- a/doc/handbook/5_assemblinglinearsystem.tex
+++ b/doc/handbook/5_assemblinglinearsystem.tex
@@ -50,7 +50,7 @@ direction of maximum growth $\textbf{x}^i$ until our approximated solution becom
\subsection{Structure of matrix and vectors}
To understand the meaning of an entry in the matrix or the vector of the linear system, we have
to define their structure. Both have a blocking structure. Each block contains the degrees of
-freedom (also called variable or unknown) for a control volume. The equation index is used
+freedom (also called variables or unknowns) for a control volume. The equation index is used
to order of the degrees of freedom. For each control volume we have one block. The mapper is
used to order the blocks.
@@ -113,8 +113,8 @@ used to order the blocks.
\draw (11,2.2) -- (10.7,1.6);
\end{tikzpicture}
\end{center}
-\caption{Structure of matrix and vector, left blocking structure, right within block}
+\caption{Structure of matrix and vector, left: block structure, right: within block}
\end{figure}
-Accessing entries follows this structure. You can access the pressure value in the third sub-control volume in
-a vector \lstinline{sol} with \lstinline{sol[2][pressureIdx]}.
+Accessing entries follows this structure. You can access the pressure value in the third ($n=3$) sub-control volume in
+a solution vector \lstinline{sol} with \lstinline{sol[n-1][pressureIdx]=sol[2][pressureIdx]}.
diff --git a/doc/handbook/5_developingdumux.tex b/doc/handbook/5_developingdumux.tex
index 2ad63f31b0..29b85c69f3 100644
--- a/doc/handbook/5_developingdumux.tex
+++ b/doc/handbook/5_developingdumux.tex
@@ -5,7 +5,7 @@
\paragraph{Issues and Bug Tracking}
The bug-tracking system \emph{GitLab Issues} offers the possibility to report bugs or discuss new development requests.
-Feel free to register (if you don't have a \emph{Git} account already) and to contribute
+Feel free to register (if you don't have an account at out \emph{Git} yet) and to contribute
at \url{https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/issues}.
\paragraph{Commits, Merges, etc.}
@@ -33,7 +33,7 @@ For the style guide and instructions how to contribute to \Dumux visit
\subsection{Tips and Tricks}
-\Dumux users and developers at the LH2 are also referred to the internal Wiki for
+\Dumux users and developers at the LH2 are also referred to the internal confluence pages for
more information.
\paragraph{Optimized computation vs debugging}
@@ -46,13 +46,13 @@ in your options file. You can also do this in any of the \texttt{CMakeLists.txt}
set(CMAKE_BUILD_TYPE Debug)
\end{lstlisting}
-Afterwards rerun cmake again (run cmake <path-to-build-dir>).
+Afterwards rerun cmake (run cmake \texttt{$<$path-to-build-dir$>$}).
\paragraph{Dunecontrol for selected modules}
A complete build using \texttt{dunecontrol} takes some time. In many cases not all modules need to be re-built.
Pass the flag \texttt{--only=dumux} to \texttt{dunecontrol} for configuring or building only \Dumux. A more
-complex example would be the use of an additional module. Then you have to configure and build only \Dune{}-grid
-and \Dumux by adding \texttt{--only=MODULE,dumux}.
+complex example would be a case in which you have to configure and build only e.g. \Dune{}-grid
+and \Dumux. This is achieved by adding \texttt{--only=MODULE,dumux}.
\paragraph{Patching Files or Modules}
If you want to send changes to an other developer of \Dumux providing patches
@@ -72,7 +72,7 @@ $ patch -p1 < PATCHFILE
% 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
+If you want to create output in order to later know where some output or debug information came from, use the predefined
macros \texttt{\_\_FILE\_\_} and \texttt{\_\_LINE\_\_}:
\begin{lstlisting}[style=DumuxCode]
std::cout << "# This was written from "<< __FILE__ << ", line " << __LINE__ << std::endl;
diff --git a/doc/handbook/5_externaltools.tex b/doc/handbook/5_externaltools.tex
index dee059dc1d..7cc542c464 100644
--- a/doc/handbook/5_externaltools.tex
+++ b/doc/handbook/5_externaltools.tex
@@ -75,5 +75,4 @@ Just save the specific code portion in a file and load it via \texttt{Macros} $\
\paragraph{Guide:}
Since ParaView 4.3.1, The ParaView Guide is partly
available for free download, see \url{http://www.paraview.org/documentation/}.
-It corresponds to the ParaView book, only three application chapters short.
-Attention, its size is 180 MiB.
+It contains similar content as the ParaView book.
diff --git a/doc/handbook/5_newfoldersetup.tex b/doc/handbook/5_newfoldersetup.tex
index ea26767b48..50ffc8ade1 100644
--- a/doc/handbook/5_newfoldersetup.tex
+++ b/doc/handbook/5_newfoldersetup.tex
@@ -5,7 +5,7 @@ the build system there is a new one.
\paragraph{Adding new Folders}
\begin{enumerate}[1)]
\item create new folder with content
- \item adapt the \verb+CMakeList.txt+ in the folder above and add a line with
+ \item adapt the \verb+CMakeList.txt+ in the folder above by adding a line with
\verb+add_subdirectory(NEW_FOLDER)+
\item create a \verb+CMakeList.txt+ in the newly created folder
\item go to your \texttt{build}-directory and type \verb+make+ to
@@ -24,4 +24,4 @@ dune_add_test(NAME my_test
Here, we create an executable called \texttt{my\_test} from a source file \texttt{main.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 executable \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/}.
+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.6/}.
diff --git a/doc/handbook/5_parameterfiles.tex b/doc/handbook/5_parameterfiles.tex
index 7be83d7a7c..126b2bf265 100644
--- a/doc/handbook/5_parameterfiles.tex
+++ b/doc/handbook/5_parameterfiles.tex
@@ -1,7 +1,6 @@
\section{Parameters in \Dumux}
\label{sc_parameterfiles}
-Simulation parameters can be parsed to the program via a parameter file or the command line.
-A list of all available parameters is provided in the Doxygen documentation: \texttt{Parameter List}.
+Simulation parameters can be parsed to the program via a parameter file or via the command line.
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
@@ -77,7 +76,7 @@ If you also want to set a default value for a parameter, just add it like this:
static const TYPE paramname = getParam<TYPE>("GROUPNAME.PARAMNAME", default);
\end{lstlisting}
-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:
+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 following methods might be more convenient:
\begin{lstlisting}[name=propsyscars,style=DumuxCode]
auto modelParamGroup0 = "Model0";
diff --git a/doc/handbook/5_structure.tex b/doc/handbook/5_structure.tex
index 76626670c0..c97c67b375 100644
--- a/doc/handbook/5_structure.tex
+++ b/doc/handbook/5_structure.tex
@@ -6,7 +6,7 @@
\item \texttt{bin}: binaries, e.g. used for the automatic testing, post-processing, installation
\item \texttt{cmake}: the configuration options for building \Dumux
\item \texttt{doc}: files necessary for the Doxygen documentation and this handbook, and various logos
-\item \texttt{dumux}: the main folder, containing the source files. See \ref{fig:dumux-structure}
+\item \texttt{dumux}: the main folder, containing the source files. See Fig. \ref{fig:dumux-structure}
for a visualized structure. For more information on the models have a look at the
Doxygen documentation.
\item \texttt{examples}: well-documented examples of applying \Dumux to typical physical problems. In the \texttt{README.md} files, the setup is explained, the used code is presented and documented and images resulting from the simulation are included. The \texttt{README.md} files are located directly in the subfolders of \texttt{examples} and can be displayed by web browsers.
@@ -87,7 +87,7 @@
[.\node[FirstLevel] {freeflow};
[.\node[SecondLevel] {\emph{models}};
\node[ThirdLevel] {Single-phase free flow models using Navier-Stokes
- and eddy-viscosity based Reynolds-averaged Navier-Stokes turbulence models and shallow water equation model.};
+ and eddy-viscosity based Reynolds-averaged Navier-Stokes turbulence models, and shallow water equation model.};
]
]
[.\node[FirstLevel] {geomechanics};
@@ -150,7 +150,7 @@
\node[ThirdLevel] {
Common infrastructure to couple multiple domains, models or physics.};
[.\node[SecondLevel] {embedded};
- \node[ThirdLevel] {Embedding of a lower-dimensional model into a higher-dimensional one};
+ \node[ThirdLevel] {Embedding a lower-dimensional model into a higher-dimensional one};
]
[.\node[SecondLevel] {facet};
\node[ThirdLevel] {Mixed-dimensional coupling at facets.};
diff --git a/doc/handbook/6_basics.tex b/doc/handbook/6_basics.tex
index 691a07f19f..d33f2a51fc 100644
--- a/doc/handbook/6_basics.tex
+++ b/doc/handbook/6_basics.tex
@@ -5,32 +5,28 @@ can be found in the local residuals (see Doxygen documentation of the
model's \texttt{LocalResidual} class).
\subsection{Basic Definitions and Assumptions}
-The basic definitions and assumptions are made, using the example
-of a three-phase three-component system water-NAPL-gas
-\cite{A3:class:2002a}. The modification for other multi-component
-systems is straightforward and can be found, e.\ g., in
-\cite{A3:bielinski:2006,A3:acosta:2006}.
+Basic definitions and assumptions are given. More information can be found e.g. in \cite{A3:acosta:2006,A3:bielinski:2006}.
\begin{description}
+\item[Phases:]
+A \emph{phase} is defined as a continuum having distinct properties (e.g. density and viscosity). If phases are miscible, they contain dissolved portions of the substance of the other phase.
+Fluid and solid phases are distinguished. The fluid phases have different affinities to the solid phases. The phase, which has a higher affinity to the solid phases is referred to as the (more) wetting phase. In the case of two phases, the less wetting one is called the non-wetting phase.
+
+For compositional multi-phase models, fluid phases may be composed of several components, while the solid phases are assumed to consist exclusively of a single component.
+
\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
-a group of species exploiting similar physical behavior. In this work, we
-assume a water-gas-NAPL system composed of the phases water (subscript
+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
-air ($\text{a}$), and the organic contaminant ($\text{c}$) (see Fig.
-\ref{fig:phaseMassEnergyTransfer}).
+air ($\text{a}$), and an organic contaminant ($\text{c}$).
-\item[Phases:]
-For compositional multi-phase models, \emph{phases}
-are not only matter of a single chemical substance. Instead, their
-composition in general includes several species/components. For mass transfer,
-the component behavior is quite different from the phase behavior.
+The composition of the components in a phase can influence the phase properties. Furthermore, for mass transfer, the phase behavior is quite different from the component behavior.
\item[Equilibrium:]
For the non-isothermal, multi-phase, multi-component processes in porous media
-we state that the assumption of \emph{local thermodynamic equilibrium}.
+we state the assumption of \emph{local thermodynamic equilibrium}.
Chemical equilibrium means that the mass/mole fractions of a component in
different phases are in equilibrium.
Thermal equilibrium assumes the same temperature for all considered phases.
@@ -38,8 +34,8 @@ Mechanical equilibrium is not valid in a porous medium, since discontinuities
in pressure can occur across a fluid-fluid interface due to capillary effects.
\item[Notation:]
-The subscript index $\alpha \in \{\text{w}, \text{n}, \text{g}\}$ refers
-to the phase, while the superscript $\kappa \in \{\text{w}, \text{a}, \text{c}\}$
+The subscript index $\alpha$, e.g. $\text{w}, \text{n} \text{ and } \text{g}$ in the example of Fig. \ref{fig:phaseMassEnergyTransfer}, refers
+to the phase, while the superscript $\kappa$, e.g. $\text{w}, \text{a} \text{ and } \text{c}$ in the example of Fig. \ref{fig:phaseMassEnergyTransfer},
refers to the component.
\end{description}
@@ -120,7 +116,7 @@ $\boldsymbol{v}_\alpha$ & velocity (Darcy or free flow)& & \\
\filldraw[black!40](6,-0.2) rectangle +(0.3,0.3) node at (6.3,-0.1)[right,black]{Organic contaminant (NAPL)};
\filldraw[black!70](6,-0.8) rectangle +(0.3,0.3) node at (6.3,-0.75)[right,black]{Solid phase};
\end{tikzpicture}
- \caption{Mass and energy transfer between the phases}
+ \caption{Mass and energy transfer between the phases in a water-NAPL-gas system \cite{A3:class:2002a}}
\label{fig:phaseMassEnergyTransfer}
\end{figure}
@@ -169,14 +165,7 @@ For isotropic porous media, it can be reduced to a scalar quantity $K$.
% \end{equation}
\newpage
-\subsection[Phases and components]{Phases and components\footref{foot:hommel}}\label{sec:phases_components}
-A phase is defined as a continuum having distinct properties (e.g. density and viscosity). If phases are miscible, they contain dissolved portions of the substance of the other phase.
-Fluid and solid phases are distinguished. The fluid phases have different affinities to the solid phases. The phase, which has a higher affinity to the solid phases is referred to as the (more) wetting phase. In the case of two phases, the less wetting one is called the non-wetting phase.
-
-The fluid phases may be composed of several components, while the solid phases are assumed to consist exclusively of a single component. Components are distinct chemical species or a group of chemical species.
-The composition of the components in a phase can influence the phase properties.
-
-\subsubsection{Mass fraction, mole fraction}\label{sec:mole_frac_molality}
+\subsection[Mass fraction, mole fraction]{Mass fraction, mole fraction\footref{foot:hommel}}\label{sec:mole_frac_molality}
The composition of a phase is described by mass or mole fractions of the components.
The mole fraction $x^\kappa_\alpha$ of component $\kappa$ in phase $\alpha$ is defined as:
diff --git a/doc/handbook/6_inputoutput.tex b/doc/handbook/6_inputoutput.tex
index 3d7c5c693b..2f36ad96cf 100644
--- a/doc/handbook/6_inputoutput.tex
+++ b/doc/handbook/6_inputoutput.tex
@@ -131,7 +131,7 @@ The VTK file format is supported by common visualisation programs like ParaView,
\subsubsection{Customize the VTK output}
Using the respective \texttt{initOutputModule} function of the model \texttt{IOFields}, a default
-set of variables is stored in the VTK files. It is also possible to add further variables,
+set of variables is defined for the output into the VTK files. It is also possible to add further variables,
using the member function \texttt{addField} of the \texttt{VtkOutputModule}. For example, to add a variable called \texttt{temperatureExact}:
\begin{lstlisting}[style=DumuxCode]
vtkWriter.addField(problem->getExactTemperature(), "temperatureExact");
@@ -150,7 +150,7 @@ It is important that the life-time of the added field exceeds the life-time of t
to the \texttt{addField} function. The vector has to be stored somewhere, e.g. in the program main file.
The second input argument is the name of the additional variable (as it should be written in the VTK files).
-The example above is taken from: \\ \texttt{test/porousmediumflow/1pnc/implicit/test\_1p2cni\_convection\_fv.cc}
+The example above is taken from: \\ \texttt{test/porousmediumflow/1pnc/implicit/1p2c/nonisothermal/convection/main.cc}
\subsubsection{VTK as input format}
There is support for reading data and grids from VTK files, see subsection \ref{sec:supportedGridFormats}.
diff --git a/doc/handbook/6_propertysystem.tex b/doc/handbook/6_propertysystem.tex
index bfe58b3fa3..63a8f78c58 100644
--- a/doc/handbook/6_propertysystem.tex
+++ b/doc/handbook/6_propertysystem.tex
@@ -20,7 +20,7 @@ defined for arbitrary levels of the inheritance hierarchy.
\subsection{How-to}
All source files which use the property system should include
-the header file \path{dumux/common/propertysystem.hh}.
+the header file \path{dumux/common/properties/propertysystem.hh}.
Declaration of type tags and
property tags as well as defining properties must be done inside the
namespace \texttt{Dumux::Properties}.
@@ -269,16 +269,16 @@ make sense for at least one of the nodes of Figure
follows:
\begin{lstlisting}[name=propsyscars,style=DumuxCode]
template<class TypeTag, class MyTypeTag>
+struct GasUsage { using type = UndefinedProperty; }; // [l/100km]
+template<class TypeTag, class MyTypeTag>
struct TopSpeed { using type = UndefinedProperty; }; // [km/h]
template<class TypeTag, class MyTypeTag>
struct NumSeats { using type = UndefinedProperty; }; // []
template<class TypeTag, class MyTypeTag>
-struct CanonCaliber { using type = UndefinedProperty; }; // [mm]
-template<class TypeTag, class MyTypeTag>
-struct GasUsage { using type = UndefinedProperty; }; // [l/100km]
-template<class TypeTag, class MyTypeTag>
struct AutomaticTransmission { using type = UndefinedProperty; }; // true/false
template<class TypeTag, class MyTypeTag>
+struct CanonCaliber { using type = UndefinedProperty; }; // [mm]
+template<class TypeTag, class MyTypeTag>
struct Payload { using type = UndefinedProperty; }; // [t]
\end{lstlisting}
--
GitLab