From 2bd30dcc74024eab2754fb43c7e4c2d40695b196 Mon Sep 17 00:00:00 2001
From: Benjamin Faigle <benjamin.faigle@posteo.de>
Date: Fri, 4 Feb 2011 15:11:02 +0000
Subject: [PATCH] added more information to tutorial to ease it for newcomers
git-svn-id: svn://svn.iws.uni-stuttgart.de/DUMUX/dumux/trunk@5175 2fb0f335-1f38-0410-981e-8018bf24f1b0
---
doc/handbook/install.tex | 4 +-
doc/handbook/tutorial-coupled.tex | 50 +++++++++++--------
doc/handbook/tutorial-decoupled.tex | 30 ++++++-----
tutorial/tutorialproblem_coupled.hh | 10 ++--
tutorial/tutorialproblem_decoupled.hh | 18 +++----
tutorial/tutorialspatialparameters_coupled.hh | 2 +-
6 files changed, 63 insertions(+), 51 deletions(-)
diff --git a/doc/handbook/install.tex b/doc/handbook/install.tex
index 8dbc3158b5..6cb7af86f4 100644
--- a/doc/handbook/install.tex
+++ b/doc/handbook/install.tex
@@ -18,7 +18,7 @@ If you are interested in more details of the build system, we use below,
they are given in {\Dune}'s Build System Howto \cite{DUNE-BS}.\\
-As for a \Dune installation, all \Dune modules including \Dumux get extracted into a common directory. We refer to that directory for purpose of documentation abstractly as {\Dune} root directory or shortly as {\Dune}-Root or if it is used in directory path's of a shell command it is typed as \texttt{\Dune-Root}. For the real {\Dune} root directory in filesystem any valid directory name can be name chosen.\\
+As for a \Dune installation, all \Dune modules including \Dumux get extracted into a common directory. We refer to that directory for purpose of documentation abstractly as {\Dune} root directory or shortly as {\Dune}-Root. If it is used in directory path's of a shell command it is typed as \texttt{\Dune-Root}. For the real {\Dune} root directory in filesystem any valid directory name can be name chosen.\\
Source code files for each \Dune module are contained in their own subdirectory within {\Dune}-Root.
We name this directory of a certain module, ``module's root directory" or \texttt{module-root-directory} in directory path's,
@@ -228,7 +228,7 @@ $ ./dune-common/bin/dunecontrol --configure-opts="CXXFLAGS=-fno-strict-aliasing"
Too many options can make life hard, that's why one usually uses option-files for dunecontrol and its sub-tools.
Larger sets of options are kept in them. \\
-If you are going to compile with options suited for code debugging with a debugger, the following
+If you are going to compile with options suited for debugging of the code, the following
can be a starting point:
%Below in command-line make sure to insert the right name of dumux' root directory, which is in case of installation from tar-files \texttt{dumux-2.0} or in case of installation from subversion just \texttt{dumux}. For a developer it is also possible to take options file from \texttt{dumux-devel}.
diff --git a/doc/handbook/tutorial-coupled.tex b/doc/handbook/tutorial-coupled.tex
index 4af0f75d5c..d7a1010f48 100644
--- a/doc/handbook/tutorial-coupled.tex
+++ b/doc/handbook/tutorial-coupled.tex
@@ -235,7 +235,10 @@ problem class is attached to the new type tag, while the grid which
is going to be used is defined in line \ref{tutorial-coupled:set-grid} --
in this case that is \texttt{SGrid}. Since there's no uniform
mechanism to allocate grids in \Dune, the \texttt{Grid} property also contains
-a static \texttt{create()} method which provides just that. Next,
+a static \texttt{create()} method which provides just that. Therein, the three variables of
+Type \texttt{Dune::FieldVector} define the lower left corner of the domain
+(\texttt{L}), the upper right corner of the domain (\texttt{H}) and the number
+of cells in $x$ and $y$ direction (\texttt{N}). Next,
the appropriate fluid system, that specifies both information about
the fluid mixture as well as about the pure substances, has to be chosen.
The two-phase model defaults to the \texttt{FluidSystem2P} which assumes
@@ -292,6 +295,11 @@ for all primary variables / equations: Either \texttt{setAllDirichlet()} or \tex
\item[boundaryFaceIdx:] The index of the boundary face in
\texttt{fvElementGeometry} which represents the boundary segment.
\end{description}
+To ensure that no boundaries are undefined, a small safeguard value \texttt{eps\_}
+is usually added when compariing spatial coordinates. The left boundary is
+hence not assigned where the first coordinate is equal to zero, but where it is
+smaller than a very small value \texttt{eps\_}.
+
After the type of the boundary condition is defined, their values have to be
assigned with the methods \texttt{dirichlet()} and \texttt{neumann()} which only differ
by the first function parameter:
@@ -402,7 +410,7 @@ Depending on the type of the \texttt{materialLaw} object, the adequate \texttt{s
are provided by the object to access all necessary parameters
for the applied material law. The name of the access / set functions as well as the rest of the implementation
of the material description can be found in
-\verb+dumux/dumux/material/fluidmatrixinteractions/2p+.
+\verb+dumux/material/fluidmatrixinteractions/2p+.
\subsection{Exercises}
\label{tutorial-coupled:exercises}
@@ -435,16 +443,13 @@ To get an impression what the results should look like you can first run the ori
\item \textbf{Changing Fluids} \\
- Now you can change the fluids. Use \texttt{DNAPL} instead of
- \texttt{Oil} and \texttt{Brine} instead of \texttt{Water}. To do
- that you have to change the problem file:
- \begin{enumerate}
- \item Brine: The class \texttt{Dumux::Brine} acts as an adapter to pure water. Hence, it needs not only \texttt{<Scalar>} as a template argument, but also the complete water class used before (be aware to use the water class with its own template parameters).
- \item DNAPL: A standard set of chemical substances represented by the class \texttt{Dumux::SimpleDNAPL} is located in the folder \texttt{dumux/material/components/} and needs to be included in the problem file.
+Now you can change the fluids. Use DNAPL instead of Oil and Brine instead of Water. To do that you have to select different components via the property system in the problem file:
+\begin{enumerate}
+ \item Brine: The class \texttt{Dumux::Brine} acts as a adapter to the fluid system that alters a pure water class by adding some salt. Hence, the class \texttt{Dumux::Brine} uses a pure water class, such as \texttt{Dumux::H2O}, as a second template argument after the data type \texttt{<Scalar>} as a template argument (be aware to use the complete water class with its own template parameter).
+ \item DNAPL: A standard set of chemical substances, such as Oil and Brinde, is already included (via a list of \texttt{\#include ..} commandos) and hence easy accessible by default. This is not the case for the class \texttt{Dumux::SimpleDNAPL}, however, which is located in the folder \texttt{dumux/material/components/}. Try to include the file as well as select the component via the property system.
\end{enumerate}
- If you want to take a closer look how the fluid classes are defined
- and which substances are already available please browse through the files in the directory
- \texttt{/dumux/material/components}.
+If you want to take a closer look how the fluid classes are defined and which substances are already available please browse through the files in the directory
+\texttt{/dumux/material/components}.
\item \textbf{Use the \Dumux fluid system} \\
\Dumux usually organises fluid mixtures via a \texttt{fluidsystem}. In order to include a fluidsystem you first have to comment the lines \ref{tutorial-coupled:2p-system-start} to \ref{tutorial-coupled:2p-system-end} in the problem file. If you use eclipse, this can easily be done by pressing \textit{str + shift + 7} -- the same as to cancel the comment later on.\\
@@ -477,23 +482,26 @@ of the linear law and the respective \texttt{set}-functions can be found
\includegraphics[width=0.5\linewidth,keepaspectratio]{EPS/exercise1_c.eps}
\caption{Exercise 1f: Set-up of a model domain with a heterogeneity. $\Delta \text{x} = 20$ m $\Delta \text{y} = 20$ m.}\label{tutorial-coupled:exercise1_d}
\end{figure}
-domain. You can use the fluids of exercise 1c).
+domain. You can use the fluids of exercise 1c).\\
+Hint: The current position of the element can be obtained via \texttt{element.geometry().center();}.\\
When does the front cross the material border? In paraview, the option \textit{View} $\rightarrow$ \textit{Animation View} is nice to get a rough feeling of the timestep sizes.
\end{enumerate}
\subsubsection{Exercise 2}
For this exercise you should create a new proplem file analogous to
-the file \texttt{tutorialproblem\_coupled.hh} and new spatial parameters
+the file \texttt{tutorialproblem\_coupled.hh} (e.g. with the name
+\texttt{ex2\_tutorialproblem\_coupled.hh} and new spatial parameters
just like \texttt{tutorialspatialparameters\_coupled.hh}. The new problem file needs to
-be included in the file \texttt{tutorial\_coupled.cc}. \\
-The new file defining spatial parameters should contain the definition
-of a new class, such as \\
-\texttt{SpatialParametersEx2}. Make sure that you also adjust the guardian
-macros in the header files (e.g. change \\
-\texttt{TUTORIALSPATIALPARAMETERS\_COUPLED} to
-\texttt{SPATIALPARAMETERSEX2}). Besides also adjusting the guardian macros,
+be included in the file \texttt{tutorial\_coupled.cc}.\\
+The new files should contain the definition of a new classes with
+names that relate to the file name, such as
+\texttt{Ex2TutorialProblemCoupled}. Make sure that you also adjust the guardian
+macros in lines \ref{tutorial-coupled:guardian1} and \ref{tutorial-coupled:guardian1}
+ in the header files (e.g. change \\
+\texttt{DUMUX\_TUTORIALPROBLEM\_COUPLED\_HH} to
+\texttt{DUMUX\_EX2\_TUTORIALPROBLEM\_COUPLED\_HH}). Besides also adjusting the guardian macros,
the new problem file should define and use a new type tag for the problem as well as a new problem class
-e.g. \texttt{ProblemEx2}. Make sure you assign your newly defined spatial
+e.g. \texttt{Ex2TutorialProblemCoupled}. Make sure you assign your newly defined spatial
parameter class to the \texttt{SpatialParameters} property for the new
type tag. \\
After this, change the \texttt{create()} method of the \texttt{Grid}
diff --git a/doc/handbook/tutorial-decoupled.tex b/doc/handbook/tutorial-decoupled.tex
index b2d2f222cd..5f3f678be4 100644
--- a/doc/handbook/tutorial-decoupled.tex
+++ b/doc/handbook/tutorial-decoupled.tex
@@ -60,11 +60,11 @@ property system, see section \ref{sec:propertysystem}.
The first thing which should be done at run time is to initialize the
message passing interface using \Dune's \texttt{MPIHelper} class. Line
-\ref{tutorial-decoupled:init-mpi} line is essential if the simulation is
+\ref{tutorial-decoupled:init-mpi} is essential if the simulation is
intended to be run on more than one processor at the same time. Next,
the command line arguments are parsed starting at line
\ref{tutorial-decoupled:parse-args-begin} until line
-\ref{tutorial-decoupled:parse-args-end}. In this case, we check if and
+\ref{tutorial-decoupled:parse-args-end}. In this case, we check weather and
at which time a previous run of the simulation should be restarted, and we
parse the time when the simulation ends. As the maximum time-step in the
sequential model is strictly bound by a CFL-criterion, the first time-step
@@ -202,7 +202,7 @@ For Exercise 1 you only have to make some small changes in the tutorial files.
\begin{enumerate}
\item \textbf{Altering output}
To get an impression what the results should look like you can first run the original version of the decoupled tutorial model by typing \texttt{./tutorial\_decoupled 1e5}. The number behind the simulation name defines the timespan of the simulation run in seconds. For the visualisation with paraview please refer to \ref{quick-start-guide}.\\
-As you can see, the simulation creates roughly 150 output files. To reduce these to perform longer simulations, change the method responsible for output in the file \texttt{tutorialproblem\_decoupled} to write an output only every 20 timesteps. Compile the main file by typing \texttt{make tutorial\_decoupled} and run the model. Now, run the simulation for 5e5 seconds.
+As you can see, the simulation creates roughly 150 output files. To reduce these to perform longer simulations, change the method responsible for output (line \ref{tutorial-decoupled:output} in the file \texttt{tutorialproblem\_decoupled}) to write an output only every 20 timesteps by changeing the divisor. Compile the main file by typing \texttt{make tutorial\_decoupled} and run the model. Now, run the simulation for 5e5 seconds.
\item \textbf{Changing the Model Domain and the Boundary Conditions} \\
Change the size of the model domain so that you get a rectangle
@@ -213,14 +213,14 @@ Change the boundary conditions in the file \texttt{tutorialproblem\_decoupled.hh
Now you can change the fluids. Use DNAPL instead of Oil and Brine instead of Water. To do that you have to select different components via the property system in the problem file:
\begin{enumerate}
\item Brine: The class \texttt{Dumux::Brine} acts as a adapter to the fluid system that alters a pure water class by adding some salt. Hence, the class \texttt{Dumux::Brine} uses a pure water class, such as \texttt{Dumux::H2O}, as a second template argument after the data type \texttt{<Scalar>} as a template argument (be aware to use the complete water class with its own template parameter).
- \item DNAPL: A standard set of chemical substances is already included (via a list of \texttt{\#include ..} commandos) and hence easy accessible by default. This is not the case for the class \texttt{Dumux::SimpleDNAPL}, however, which is located in the folder \texttt{dumux/material/components/}. Try to include the file as well as select the component via the property system.
+ \item DNAPL: A standard set of chemical substances, such as Oil and Brinde, is already included (via a list of \texttt{\#include ..} commandos) and hence easy accessible by default. This is not the case for the class \texttt{Dumux::SimpleDNAPL}, however, which is located in the folder \texttt{dumux/material/components/}. Try to include the file as well as select the component via the property system.
\end{enumerate}
If you want to take a closer look how the fluid classes are defined and which substances are already available please browse through the files in the directory
\texttt{/dumux/material/components}.
\item \textbf{Use the \Dumux fluid system}\label{dec-ex1-fluidsystem} \\
As you have experienced in the coupled tutorial (chapter \ref{tutorial-decoupled}), \Dumux usually organises fluid mixtures via a \texttt{fluidsystem}. This is also possible for the decoupled models: Uncomment, as we want to reuse it later on, the lines \ref{tutorial-decoupled:2p-system-start} to \ref{tutorial-decoupled:2p-system-end} in the problem file. If you use eclipse, this can easily be done by pressing \textit{str + shift + 7}, the same shortcut works to cancel the comment later on.\\
-Now include the file \texttt{fluidsystems/h2o\_n2\_system.hh} in the material folder, and set a property \texttt{FluidSystem} with the appropriate type, \texttt{Dumux::H2O\_N2\_System<TypeTag>}. However, the complicated fluidsystem uses tabularized fluid data, which need to be initialized in the constructor body of the current problem by adding \texttt{GET\_PROP\_TYPE(TypeTag, PTAG(FluidSystem))::init();}, hence using the initialization function of the applied fluidsystem. As an alternative, use a simpler version of water, e.g. \texttt{Dumux::SimpleH2O}, and apply it for the property \texttt{Components} with type \texttt{H2O}. The density of the gas is magnitudes smaller than that of oil, so please decrease the injection rate to $q_n = -3 \times 10^-4$ $\left[\frac{\textnormal{kg}}{\textnormal{m}^2 \textnormal{s}}\right]$. Also reduce the simultation duration to 1e5 seconds.\\
+Now include the file \texttt{fluidsystems/h2o\_n2\_system.hh} in the material folder, and set a property \texttt{FluidSystem} with the appropriate type, \texttt{Dumux::H2O\_N2\_System<TypeTag>}. However, the complicated fluidsystem uses tabularized fluid data, which need to be initialized in the constructor body of the current problem by adding \texttt{GET\_PROP\_TYPE(TypeTag, PTAG(FluidSystem))::init();}, hence using the initialization function of the applied fluidsystem. As an alternative, use a simpler version of water, e.g. \texttt{Dumux::SimpleH2O}, and apply it for the property \texttt{Components} with type \texttt{H2O}. The density of the gas is magnitudes smaller than that of oil, so please decrease the injection rate to $q_n = -3 \times 10^-4$ $\left[\frac{\textnormal{kg}}{\textnormal{m}^2 \textnormal{s}}\right]$. Also reduce the simultation duration to 2e4 seconds.\\
Please reverse the changes of this example, as we still use bulk phases and hence do not need such an extensive fluid system.
\item \textbf{Heterogeneities} \\
@@ -241,16 +241,20 @@ When does the front cross the material border? In paraview, the option \textit{V
\subsubsection{Exercise 2}
For this exercise you should create a new proplem file analogous to
-the file \texttt{tutorialproblem\_decoupled.hh} and new spatial parameters
+the file \texttt{tutorialproblem\_decoupled.hh} (e.g. with the name
+\texttt{ex2\_tutorialproblem\_decoupled.hh} and new spatial parameters
just like \texttt{tutorialspatialparameters\_decoupled.hh}. These files need to
be included in the file \texttt{tutorial\_decoupled.cc}.
-The new file defining spatial parameters should contain the definition
-of a new class, such as \texttt{SpatialParametersEx2}. Make sure that you also adjust the guardian
-macros in the header files (e.g. change \texttt{TUTORIALSPATIALPARAMETERS\_COUPLED} to
-\texttt{SPATIALPARAMETERSEX2}). Besides also adjusting the guardian macros,
+The new files should contain the definition of a new classes with
+names that relate to the file name, such as \texttt{Ex2TutorialProblemDecoupled}.
+Make sure that you also adjust the guardian
+macros in lines \ref{tutorial-decoupled:guardian1} and \ref{tutorial-decoupled:guardian1}
+ in the header files (e.g. change \\
+\texttt{DUMUX\_TUTORIALPROBLEM\_DECOUPLED\_HH} to
+\texttt{DUMUX\_EX2\_TUTORIALPROBLEM\_DECOUPLED\_HH}). Besides also adjusting the guardian macros,
the new problem file should define and use a new type tag for the problem as well as a new problem class
-e.g. \texttt{ProblemEx2}. Make sure you assign your newly defined spatial
+e.g. \texttt{Ex2TutorialProblemDecoupled}. Make sure you assign your newly defined spatial
parameter class to the \texttt{SpatialParameters} property for the new
type tag.
@@ -262,7 +266,7 @@ so that the boundary conditions are consistent with figure
with water and the pressure is $p_w = 2 \times 10^5 \text{Pa}$ . Oil
infiltrates from the left side. Create a grid with $20$ cells in
$x$-direction and $10$ cells in $y$-direction. The simulation time
-should be set to $1e5 \text{s}$.
+should be set to $2e4 \text{s}$.
Now include your new problem file in the main file and replace the
\texttt{TutorialProblemCoupled} type tag by the one you've created and
@@ -310,7 +314,7 @@ compile the program.
\subsubsection{Exercise 3}
Create a new file for benzene called \texttt{benzene.hh} and implement
a new fluid system. (You may get a hint by looking at existing fluid
-systems in the directory \verb+/dumux/new_material/fluidsystems+.)
+systems in the directory \verb+/dumux/material/fluidsystems+.)
Use benzene as a new fluid and run the model of Exercise 2 with water
and benzene. Benzene has a density of $889.51 \, \text{kg} / \text{m}^3$
diff --git a/tutorial/tutorialproblem_coupled.hh b/tutorial/tutorialproblem_coupled.hh
index 202759b129..c44e666b98 100644
--- a/tutorial/tutorialproblem_coupled.hh
+++ b/tutorial/tutorialproblem_coupled.hh
@@ -24,8 +24,8 @@
*
* \brief Tutorial problem for a fully coupled twophase box model.
*/
-#ifndef DUMUX_TUTORIALPROBLEM_COUPLED_HH
-#define DUMUX_TUTORIALPROBLEM_COUPLED_HH
+#ifndef DUMUX_TUTORIALPROBLEM_COUPLED_HH // guardian macro /*@\label{tutorial-coupled:guardian1}@*/
+#define DUMUX_TUTORIALPROBLEM_COUPLED_HH // guardian macro /*@\label{tutorial-coupled:guardian2}@*/
// the numerical model
#include <dumux/boxmodels/2p/2pmodel.hh>
@@ -59,9 +59,9 @@ SET_PROP(TutorialProblemCoupled, Grid) /*@\label{tutorial-coupled:set-grid}@*/
static type *create() /*@\label{tutorial-coupled:create-grid-method}@*/
{
typedef typename type::ctype ctype;
- Dune::FieldVector<int, 2> cellRes;
- Dune::FieldVector<ctype, 2> lowerLeft(0.0);
- Dune::FieldVector<ctype, 2> upperRight;
+ Dune::FieldVector<int, 2> cellRes; // vector holding resolution of the grid
+ Dune::FieldVector<ctype, 2> lowerLeft(0.0); // Coordinate of lower left corner of the grid
+ Dune::FieldVector<ctype, 2> upperRight; // Coordinate of upper right corner of the grid
cellRes[0] = 100;
cellRes[1] = 1;
upperRight[0] = 300;
diff --git a/tutorial/tutorialproblem_decoupled.hh b/tutorial/tutorialproblem_decoupled.hh
index 55585b6232..bfbf9f7526 100644
--- a/tutorial/tutorialproblem_decoupled.hh
+++ b/tutorial/tutorialproblem_decoupled.hh
@@ -67,13 +67,13 @@ SET_PROP(TutorialProblemDecoupled, Grid) /*@\label{tutorial-decoupled:grid-begin
static type *create() /*@\label{tutorial-decoupled:create-grid-method}@*/
{
typedef typename type::ctype ctype;
- Dune::FieldVector<int, 2> cellRes;
- Dune::FieldVector<ctype, 2> lowerLeft(0.0);
- Dune::FieldVector<ctype, 2> upperRight;
- upperRight[0] = 300;
- upperRight[1] = 60;
+ Dune::FieldVector<int, 2> cellRes; // vector holding resolution of the grid
+ Dune::FieldVector<ctype, 2> lowerLeft(0.0); // Coordinate of lower left corner of the grid
+ Dune::FieldVector<ctype, 2> upperRight; // Coordinate of upper right corner of the grid
cellRes[0] = 100;
cellRes[1] = 1;
+ upperRight[0] = 300;
+ upperRight[1] = 60;
return new Dune::SGrid<2,2>(cellRes,
lowerLeft,
upperRight);
@@ -227,8 +227,8 @@ public:
{
if (globalPos[0] < this->bboxMin()[0] + eps_)
return BoundaryConditions::dirichlet;
- // all other boundaries
- return BoundaryConditions::neumann;
+ else // all other boundaries
+ return BoundaryConditions::neumann;
}
//! Type of Transport boundary condition.
@@ -238,9 +238,9 @@ public:
BoundaryConditions::Flags bctypeSat(const GlobalPosition& globalPos, const Intersection& intersection) const /*@\label{tutorial-decoupled:bctypeSat}@*/
{
if (globalPos[0] < this->bboxMin()[0] + eps_)
- return Dumux::BoundaryConditions::dirichlet;
+ return BoundaryConditions::dirichlet;
else
- return Dumux::BoundaryConditions::neumann;
+ return BoundaryConditions::neumann;
}
//! Value for dirichlet pressure boundary condition \f$ [Pa] \f$.
/*! In case of a dirichlet BC for the pressure equation, the pressure
diff --git a/tutorial/tutorialspatialparameters_coupled.hh b/tutorial/tutorialspatialparameters_coupled.hh
index 8ad60dcaf3..716537b3b6 100644
--- a/tutorial/tutorialspatialparameters_coupled.hh
+++ b/tutorial/tutorialspatialparameters_coupled.hh
@@ -49,12 +49,12 @@ class TutorialSpatialParametersCoupled: public BoxSpatialParameters<TypeTag> /*@
typedef typename GET_PROP_TYPE(TypeTag, PTAG(Grid)) Grid;
typedef typename GET_PROP_TYPE(TypeTag, PTAG(GridView)) GridView;
typedef typename GET_PROP_TYPE(TypeTag, PTAG(Scalar)) Scalar;
-
enum
{
dim = Grid::dimension,
dimWorld = Grid::dimensionworld,
};
+ typedef Dune::FieldVector<Scalar, dim> GlobalPosition;
// Get object types for function arguments
typedef typename GET_PROP_TYPE(TypeTag, PTAG(FVElementGeometry)) FVElementGeometry;
--
GitLab