From 510fa48526846997f3d0c93c2e8d393a3ff3db6d Mon Sep 17 00:00:00 2001 From: Andreas Lauser Date: Thu, 1 Nov 2012 16:34:50 +0100 Subject: [PATCH] handbook: language improvements --- doc/handbook/intro.tex | 91 ++++---- doc/handbook/parameters.tex | 16 +- doc/handbook/quick-install.tex | 43 ++-- doc/handbook/quickstart-guide.tex | 34 +-- doc/handbook/tutorial-coupled.tex | 333 ++++++++++++++-------------- doc/handbook/tutorial.tex | 47 ++-- examples/tutorialproblem_coupled.hh | 6 +- 7 files changed, 293 insertions(+), 277 deletions(-) diff --git a/doc/handbook/intro.tex b/doc/handbook/intro.tex index e3a037bec..1dc24ffa7 100644 --- a/doc/handbook/intro.tex +++ b/doc/handbook/intro.tex @@ -1,40 +1,42 @@ \chapter{Introduction} -\eWoms~\cite{EWOMS-HP} aims to be a generic framework for the simulation of multi-phase -fluid flow and transport processes in porous media using continuum -mechanical approaches. At the same time, \eWoms aims to deliver -top-notch computational performance, high flexibility, a sound +\eWoms~\cite{EWOMS-HP} a generic framework for the simulation of +multi-phase fluid flow and transport processes in porous media using +continuum mechanical approaches. \eWoms is also an integral part of +the open porous media initiative~\cite{OPM-HP} for which it implements +the fully-implicit discretization schemes. \eWoms is based on the +source code of the \Dumux~\cite{DUMUX-HP} simulation framework and +aims to be a proper superset of \Dumux when it comes to features, +while at the same time it delivers better performance and a +higher-quality code base. To ease porting features from \Dumux to +\eWoms, the \eWoms source code uses very similar naming and style +conventions as the one of \Dumux. + +Besides being a generic simulation framework, \eWoms also aims to to +deliver top-notch computational performance, high flexibility, a sound software architecture and the ability to run on anything from single processor systems to highly parallel supercomputers with specialized -hardware architectures. - -\eWoms is an integral part of the open porous media -initiative~\cite{OPM-HP} where it provides the fully-implicit -models. \eWoms is based on the source code of the -\Dumux~\cite{DUMUX-HP} simulation framework and aims to be a proper -superset of \Dumux when it comes to features, while at the same time -it aims to deliver better performance and quality of the source -code. To ease porting features from \Dumux to \eWoms and vice-versa, -all classes provided by \eWoms are currently located in the namespace -\texttt{Dumux}. - -The means to achieve these somewhat contradictory goals are the -thorough use of object oriented design in conjunction with template -programming. These requirements motivated the decision to use -\Cplusplus as the implementation language for \eWoms. +hardware architectures. The means to achieve these somewhat +contradictory goals are the thorough use of object oriented design in +conjunction with template programming. These requirements motivated +the decision to implement \eWoms using the \Cplusplus programming +language. One of the more complex issues when dealing with parallel continuum -models is managing the grids used for the spatial discretization of -the physical model. To date, no generic and efficient approach exists -for all possible cases, so \eWoms is build on top of \Dune, the -\textbf{D}istributed and \textbf{U}nified \textbf{N}umerics -\textbf{E}nvironment~\cite{DUNE-HP}. \Dune provides a generic interface -to many existing grid management libraries such as UG~\cite{UG-HP}, -ALBERTA~\cite{ALBERTA-HP}, ALUGrid~\cite{ALUGRID-HP} and a few -more. DUNE also extensively uses template programming in order to -achieve minimal overhead when accessing the underlying grid -libraries\footnote{In fact, the performance penalty resulting from the -use of \Dune's grid interface is usually negligible~\cite{BURRI2006}.}. +models for partial differential equations, is the management of the +grids used for the spatial discretization. To date, no generic and +efficient approach exists for all possible cases, which lead to \eWoms +being build on top of \Dune, the \textbf{D}istributed and +\textbf{U}nified \textbf{N}umerics +\textbf{E}nvironment~\cite{DUNE-HP}. Instead of trying to implement a +grid for everything, \Dune defines a generic \Cplusplus interface to +grids, and provides adapters to several existing grid management +libraries such as UG~\cite{UG-HP}, ALBERTA~\cite{ALBERTA-HP} or +ALUGrid~\cite{ALUGRID-HP}. DUNE also extensively uses template +programming in order to achieve minimal overhead when accessing the +underlying grid 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]{EPS/dunedesign} @@ -65,24 +67,25 @@ it matches the grid's cell. 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 -additional modules, of which the \texttt{dune-localfunctions} and -\texttt{dune-istl} modules are the most relevant in the context of -this handbook. \texttt{dune-localfunctions} provides a set of generic -finite element shape functions, while \texttt{dune-istl} is the -\textbf{I}terative \textbf{S}olver \textbf{T}emplate \textbf{L}ibrary -and provides generic, highly optimized linear algebra routines for -solving the generated systems. +additional modules; In the context of this handbook the +\texttt{dune-localfunctions} and \texttt{dune-istl} modules are +probably the most relevant. \texttt{dune-localfunctions} provides a +set of generic finite element shape functions, while +\texttt{dune-istl} is the \textbf{I}terative \textbf{S}olver +\textbf{T}emplate \textbf{L}ibrary and provides generic, highly +optimized linear algebra routines for solving linear systems of +equations. -\eWoms comes in form of an additional module \Dune module -'\texttt{ewoms}'. It depends on the \Dune core modules -\texttt{dune-common}, \texttt{dune-grid}, \texttt{dune-istl}, and on +\eWoms comes in form of a module \Dune module '\texttt{ewoms}'. It +depends on the \Dune core modules \texttt{dune-common}, +\texttt{dune-grid}, \texttt{dune-istl}, and on \texttt{dune-localfunctions}. The main intention of \eWoms is to provide a framework for an easy and efficient implementation of new physical models for porous media flow problems, ranging from problem formulation and the selection of spatial and temporal discretization -schemes as well as nonlinear solvers, to general concepts for model -coupling. Moreover, \eWoms includes ready-to-use numerical models and -a few example applications. +schemes as well as nonlinear and linear solvers, to general concepts +for model coupling. Moreover, \eWoms includes ready-to-use numerical +models and a few example applications. %%% Local Variables: %%% mode: latex diff --git a/doc/handbook/parameters.tex b/doc/handbook/parameters.tex index 0764ea3f1..4895c0ad3 100644 --- a/doc/handbook/parameters.tex +++ b/doc/handbook/parameters.tex @@ -3,10 +3,10 @@ As already mentioned in the previous section, \eWoms allows to specify a number of parameters at run time. A description of these parameters -can usually obtained by passing the \texttt{--help} parameter to the +can usually be obtained by passing the \texttt{--help} parameter to the executable. The values used for these parameters are printed to the terminal during the start-up of the simulation, e.g. the if the \texttt{lens\_immiscible} -simulation is run with the parameters \texttt{--end-time=30e3 --foo-param=123}, there will an output similar to +simulation is run with the parameters \texttt{--end-time=30e3 --foo-param=123}, it will print an output similar to \begin{lstlisting}[style=Bash] ########### # Parameters specified at run-time @@ -27,13 +27,13 @@ FooParam="123" \end{lstlisting} This can be directly copy-and-pasted into a file -(e.g. \texttt{myparams.ini}) and loaded by passing the -\texttt{--parameter-file=myparams.ini} parameter to the simulation the -next time it is run. +(e.g. \texttt{myparams.ini}). The simulation can be instructed to use +these parameters by passing the \texttt{--parameter-file=myparams.ini} +parameter the next time it is run. Of course, this file can also be +adapted. -When you do simulations, always look for the paramters which are -unknown to the simulation, as this is \emph{very} useful for spotting -typos. +An additional hint: Always watch out for parameters which are unknown +to the simulation, as this is \emph{very} useful for spotting typos. %%% Local Variables: %%% mode: latex diff --git a/doc/handbook/quick-install.tex b/doc/handbook/quick-install.tex index bb9af20b1..cb80995fa 100644 --- a/doc/handbook/quick-install.tex +++ b/doc/handbook/quick-install.tex @@ -2,27 +2,28 @@ This section describes a way of installing \eWoms that works in most cases, but depending on your operating system of choice, \Cplusplus -compiler and features which you need, some tweaks are possibly. As a -pre-requisite it is assumed, that you are using a recent Linux -distribution that has the appropriate development packages (\Cplusplus -compiler, autoconf, automake, libtool and pkg-config amongst possibly -others) installed, but that you did not install \Dune via distribution -provided packages. If you need more information, or if you have \Dune -already installed, please have a look at the detailed installation -instructions in Section \ref{install}. +compiler and features which you need, some tweaks are possibly +required. As a pre-requisite it is assumed, that you are using a +recent Linux distribution that has the appropriate development +packages (\Cplusplus compiler, autoconf, automake, libtool and +pkg-config amongst possibly others) installed, but that you did not +install \Dune via distribution provided packages. If you need more +information, or if you have \Dune already installed, please have a +look at the detailed installation instructions in Section +\ref{install}. \subsection{Retrieving the code} -You can download all \Dune modules by either downloading and unpacking -the tarballs for the \Dune-2.2 release as well as downloading and -unpacking the tarball for the \eWoms 2.2 release, or by retrieving the -code directly from their respective source-code repositories. If you -decide to use the first method, make sure to unpack all tarballs into -the same directory; if you prefer the second method, make sure that -you have the \texttt{git} version control system with the SVN plug-in -installed on your computer and enter the following code snipplet into -a terminal: +You can retrieve all required \Dune modules by either downloading and +unpacking the tarballs for the \Dune-2.2 release followed by +downloading and unpacking the tarball for the \eWoms 2.2 release, or +by retrieving the code directly from their respective source-code +repositories. If you decide to use the first method, make sure to +unpack all tarballs into the same directory; if you prefer the second +method, make sure that you have the \texttt{git} version control +system with the SVN plug-in installed on your computer and enter the +following code snippet into a terminal: \begin{lstlisting}[style=Bash] cd $YOUR_DUNE_ROOT_DIRECTORY for DUNE_MODULE in common geometry grid istl localfunctions; do \ @@ -35,10 +36,10 @@ git clone --branch "release-2.2" git://github.com/OPM/ewoms.git \subsection{Building \Dune and \eWoms} \label{buildIt} -\eWoms is \Dune module and is recommended to build it using the \Dune +\eWoms is a \Dune module and is recommended to build it using the \Dune build system~\cite{DUNE-BS}. To simplify things, \eWoms ships with a few option files for \Dune's build script, \texttt{dunecontrol}. If -you are using \eWoms the first time, we recommend to use the one +you are using \eWoms the first time, we recommend to use the options optimized for the debugging experience, \texttt{debug.opts}: \begin{lstlisting}[style=Bash] @@ -58,12 +59,12 @@ cd $YOUR_DUNE_ROOT_DIRECTORY \end{lstlisting} %$ -Sometimes it is necessary to have additional options which are +Sometimes it is necessary to have additional options which might be specific to the operating system of your choice, or if you have special requirements. For this reason, the option files mentioned above should be rather understood as a starting point for your own option files than as something fixed; feel free to copy and modify -them. To avoid confusion, it is usually helpful to rename your +them. To avoid confusion, it is helpful to rename your customized option files, though. %%% Local Variables: diff --git a/doc/handbook/quickstart-guide.tex b/doc/handbook/quickstart-guide.tex index 7bcb0b20b..4f9ee6608 100644 --- a/doc/handbook/quickstart-guide.tex +++ b/doc/handbook/quickstart-guide.tex @@ -8,17 +8,17 @@ rough steps will be described here; More detailed explanations can be found in the tutorials in the following chapter. \begin{enumerate} -\item Go to the directory \texttt{/test}. There, various test +\item Go to the directory \texttt{test}. There, various test application folders can be found. Let us consider as example - \texttt{boxmodels/lens{\_}immiscible}: -\item Enter the folder \texttt{boxmodels/}. + the one for the fully-implicit models, \texttt{boxmodels}: +\item Enter the folder \texttt{boxmodels}. \item By default, the \texttt{dunecontrol} command only compiles the parts of \Dune modules that are necessary to build modules depending on the given module. For \eWoms, \texttt{dunecontrol} does not build anything by default, because \eWoms only provides \Cplusplus template classes but no libraries that need compilation. To compile - the test simulation for the "lens" problem which uses the immiscible - box model, enter + the test simulation for the "lens" problem which uses the fully-implicit + model that assumes immisciblility, enter \begin{lstlisting}[style=Bash] make lens_immiscible \end{lstlisting} @@ -37,15 +37,15 @@ make -j $N check %$ \item If everything was compiled correctly, there should be an - executable \texttt{lens{\_}immiscible}. To run the simulation, - simply run it, i.e. enter + executable called '\texttt{lens{\_}immiscible}'. To run the simulation, + simply execute it, i.e. enter \begin{lstlisting}[style=Bash] ./lens_immiscible \end{lstlisting} You may also want to change some parameters from the command line. For -example, if you want to change the time up to which the simulation is -run to $30.000$ seconds, use +example, if you want to change the time up to which the problem is +simulated to $30.000$ seconds, use \begin{lstlisting}[style=Bash] ./lens_immiscible --end-time=30e3 \end{lstlisting} @@ -61,11 +61,11 @@ simulation together with a brief description, by running pressing \texttt{+}. \item The actual output files produced by the simulation are a series - of \texttt{.vtu} files and a \texttt{.pvd} file. The \texttt{.vtu} - contain "visualization ready" data which is produced during the - simulation, while the \texttt{.pvd} file "stitches" these together - into a coherent data set. For example, the \texttt{.pvd} holds the - simulation time at which a given data-set is produced which can + of \texttt{.vtu} files and a \texttt{.pvd} file. Each \texttt{.vtu} + file contains "visualization ready" data for a single time step, + while the \texttt{.pvd} file "stitches" these files together into a + coherent data set. For example, the \texttt{.pvd} holds the + simulation time at which a given time step was produced, that can later be used for visualization. \item You can now display the result of the simulation using the visualization tool ParaView (or, if you prefer, VisIt). Just type @@ -74,9 +74,9 @@ simulation together with a brief description, by running ``Apply'' button. Once you have done this, the visualization of the simulation result appears on the screen and you can click the ``play'' button in the toolbar to view display its evolution over - time. Also note that you can choose the output quantity to be - displayed in the toolbar. For the lens problem, the most insight can - be gained by looking at one of the saturations. + time. Also note that you can choose the visualized quantity + in the toolbar. For the lens problem, the most interesting quantities + are probably the saturations. \item Play a bit around to make your self familiar with the visualization tool of your choice as you will be using it a lot. \end{enumerate} diff --git a/doc/handbook/tutorial-coupled.tex b/doc/handbook/tutorial-coupled.tex index 136a92a07..a1dd8995e 100644 --- a/doc/handbook/tutorial-coupled.tex +++ b/doc/handbook/tutorial-coupled.tex @@ -2,22 +2,21 @@ \label{tutorial-coupled} The process of setting up a problem using \eWoms can be roughly -divided into four parts: +divided into three parts: \begin{enumerate} \item A suitable model has to be chosen. -\item The geometry of the problem and correspondingly a grid have to - be defined. -\item Boundary and initial conditions and material properties have to be - selected. +\item The geometry of the problem has to be defined and the suitable + grid has to be created. +\item Boundary and initial conditions and material properties have to + be specified. \end{enumerate} The physical set-up of the flow problem being solved in this tutorial is illustrated in Figure \ref{tutorial-coupled:problemfigure}: It consists of a rectangular domain with no-flow boundary conditions on the top and on the bottom of the domain, which is initially fully -saturated by oil. Water infiltrates from the left side into the domain -and replaces the oil. The effect of gravity is neglected for this -problem. +saturated by a light oil. Water infiltrates from the left side and +replaces the oil. The effect of gravity is neglected. \begin{figure}[ht] \psfrag{x}{x} @@ -58,10 +57,10 @@ The solved equations are the mass balances of water and oil: \subsection{The main source file} -Listing \ref{tutorial-coupled:mainfile} shows the main application -file \texttt{tutorial/tutorial\_coupled.cc} uses the fully implicit -model that assumes immiscibility. This file has to be compiled and -executed in order to solve the problem described above. +Listing \ref{tutorial-coupled:mainfile} shows the main file +\texttt{tutorial/tutorial\_coupled.cc} for the tutorial problem using +a fully-implicit model that assumes immiscibility. This file has to be +compiled and executed in order to solve the problem described above. \begin{lst}[File tutorial/tutorial\_coupled.cc]\label{tutorial-coupled:mainfile} \mbox{} \lstinputlisting[style=eWomsCode, numbersep=5pt, firstline=25, firstnumber=25]{../../tutorial/tutorial_coupled.cc} @@ -84,13 +83,12 @@ The default \eWoms startup routine deals with parsing the command line arguments, reading the parameter file, properly setting up the \Dune infrastructure, creating the grid, and starting the actual simulation. Required parameters for the start of the simulation, such as the -initial time-step size, the simulation time or details of the grid, -can be either specified by command line arguments of the form -(\texttt{--parameter-name=value}), in the file specified by the +initial time-step size, the final simulation time or details of the +grid, can be either specified by command line arguments of the form +(\texttt{--parameter-name=value}), or in the file specified by the \texttt{--parameter-file="file\_name"} argument. A list of all -recognized parameters that can be specified at run time can be printed -by passing the \texttt{--help} argument to the exectutable of the -simulation. +parameters that can be specified at run-time can be obtained by passing +the \texttt{--help} argument to the exectutable of the simulation. \subsection{The problem file} @@ -109,67 +107,74 @@ using the \eWoms property system (for more information see chapter \begin{itemize} \item First, a new type tag is created for the problem in line \ref{tutorial-coupled:create-type-tag}. In this case, the new type - tag inherits all properties from the \texttt{BoxTwoP} type tag, which - means that for this problem the two-phase box model is chosen as - discretization scheme. -\item On line \ref{tutorial-coupled:set-problem}, a problem class is - specified for 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{Dune::YaspGrid}. -\item Since there's no uniform mechanism to allocate grids in \Dune, - \eWoms features the concept of grid creators. In this case the - generic \texttt{CubeGridCreator} is used. This grid creator constructs a structured - hexahedron grid of a specified size and resolution. For this grid - creator the physical domain of the grid is specified via the - run-time parameters \texttt{Grid.upperRightX}, - \texttt{Grid.upperRightY}, \texttt{Grid.numberOfCellsX} and - \texttt{Grid.numberOfCellsY}. These parameters can be specified via - the command-line or in a parameter file. + tag inherits all properties from the \texttt{BoxImmiscibleTwoPhase} + type tag, which means that for this problem the immiscible box model + for two fluid phases is chosen as discretization scheme. +\item On line \ref{tutorial-coupled:set-problem}, the problem class is + specified for the new type tag, while the kind of grid which is + going to be used is defined in line \ref{tutorial-coupled:set-grid} + -- in this case that is \texttt{Dune::YaspGrid}. +\item Since \Dune does not provide a uniform mechanism to initialize + and load grids, \eWoms features the concept of grid creators. In + this case, the generic \texttt{CubeGridCreator} is used. This grid + creator constructs a structured rectangular grid with a specified + size and resolution. For this grid creator, the physical domain of + the grid is specified via the run-time parameters + \texttt{DomainSizeX} and \texttt{DomainSizeY} and its resolution by + \texttt{CellsX} and \texttt{CellsY}. These parameters can be + specified via the command-line or in a parameter file, but the + problem file must define default values for them. Defining these + defaults is done on lines + \ref{tutorial-coupled:grid-default-params-begin} to + \ref{tutorial-coupled:default-params-end}. \end{itemize} Next, an appropriate fluid system -- which specifies the thermodynamic relations of the fluid phases -- has to be chosen. By default, the -fully-implicit immiscible model uses the -\texttt{TwoPImmiscibleFluidSystem}. This fluid system simplifies -things considerably by assuming immiscibility of the phases, but it -requires to explicitly specify the fluids used for the wetting and -non-wetting phases. In this case, liquid water based on the relations -from IAPWS'97~\cite{IAPWS1997} is chosen as the wetting phase on line -\ref{tutorial-coupled:wettingPhase} and liquid oil is chosen as the -non-wetting phase on line \ref{tutorial-coupled:nonwettingPhase}. The -next property, which is set in line \ref{tutorial-coupled:gravity}, -tells the model not to use gravity. This is then followed by the -specifcation default values for parameters specifying the temporal and -spatial domain from line \ref{tutorial-coupled:default-params-begin} -to line \ref{tutorial-coupled:default-params-end}. The values of thos -can be overwritten at run-time if desired. +fully-implicit immiscible model for two fluid phases uses +\texttt{Dumux::FluidSystems::TwoPImmiscible}. This fluid system +simplifies things considerably by assuming immiscibility of the +phases, but it requires to explicitly specify the fluids used for the +wetting and non-wetting phases. In this case, liquid water based on +the relations from IAPWS'97~\cite{IAPWS1997} is chosen as the wetting +phase on line \ref{tutorial-coupled:wettingPhase} and liquid oil is +chosen as the non-wetting phase on line +\ref{tutorial-coupled:nonwettingPhase}. The next property, which is +set in line \ref{tutorial-coupled:gravity}, tells the model not to use +gravity. This is then followed by the specifcation default values for +parameters specifying the temporal and spatial domain from line +\ref{tutorial-coupled:default-params-begin} to line +\ref{tutorial-coupled:default-params-end}. The values of those can be +overwritten at run-time if desired. -Following the property definition is the definition actual physical -set-up to be simulated. This is done by means of the \textit{problem - class}. The problem class specifies boundary and initial conditions, -source terms or spatial quantities like temperature, porosity, -intrinsic permeability and the parameters of the material law within -the domain. Since there are quite a few methods of the problem called -by the \eWoms models, and often there are sensible defaults for these -methods, it is strongly recomended to derive the problem class from -the class specified by the \texttt{BaseProblem} property as can be -seen on line \ref{tutorial-coupled:def-problem}\footnote{Technically, - deriving the problem from the \texttt{BaseProblem} property is not - required if it implements all necessary methods. Do not complain if - things explode in this case, though.}. +Following the property definitions comes the definition of the actual +physical set-up to be simulated. This is done by means of the +\textit{problem class}. The problem class specifies boundary and +initial conditions, source terms or spatial quantities like +temperature, porosity, intrinsic permeability and the parameters of +the material law within the domain. Since there are quite a few +methods of the problem called by the \eWoms models, and often there +are sensible defaults for these methods, it is strongly recomended to +derive the problem class from the class specified by the +\texttt{BaseProblem} property as done on line +\ref{tutorial-coupled:def-problem}\footnote{Technically, deriving the + problem from the \texttt{BaseProblem} property is not required if it + implements all necessary methods. Do not complain if things explode + in this case, though.}. -For isothermal multi-phase porous media models, problem class must always provide at least -the following methods: +For isothermal multi-phase porous media model, the problem class must +always provide at least the following methods: \begin{itemize} \item \texttt{initial()} for specifying the initial condition within - the domain. -\item \texttt{source()} specifying the source term for each conservation quantity. -\item \texttt{boundary()} specifying the conditions which apply on the domain boundary. -\item \texttt{temperature()} specifying temperature at a given time - and at a given position of the domain. If energy is conserved, this - method is not necessary, but energy fluxes must be provided in the - \texttt{boundary()} and \texttt{source()} methods and an initial - temperature needs to be defined in the \texttt{initial()} method. + the domain, +\item \texttt{source()} which specifies the source term for each conservation quantitym +\item \texttt{boundary()} for specifying the conditions which apply on + the domain boundary, +\item \texttt{temperature()} specifying the temperature within the + domain. Note, that if energy is conserved, this method is not + necessary. Though in this case, energy fluxes must be specified by + the \texttt{boundary()} and \texttt{source()} methods and an initial + temperature needs to be defined by the \texttt{initial()} method. \item \texttt{intrinsicPermeability()} returns the intrinsic permeability matrix $\mathbf{K}$ in $[m^2]$ at a given location. \item \texttt{porosity()} returns the ratio of pore space to @@ -181,12 +186,12 @@ the following methods: All of these methods take a single template argument, \texttt{Context}, and the three function arguments \texttt{context}, -\texttt{spaceIdx} and \texttt{timeIdx}. Together these form the +\texttt{spaceIdx} and \texttt{timeIdx}. Together, these form the \textit{execution context}. The execution context can be thought of as a collection of all available information when a given method is called. Execution contexts are thus a way to abstract the differences of the different discretization schemes. The following methods are -provided by all \text{context} objects: +provided by all \texttt{context} objects: \begin{itemize} \item \texttt{pos(spaceIdx, timeIdx)}: This method returns the relevant position of the execution context within the physical @@ -206,7 +211,7 @@ provided by all \text{context} objects: \end{itemize} The execution contexts for the \texttt{source} and \texttt{boundary} -methods provide the following methods in addition: +methods always provide the following methods in addition: \begin{itemize} \item \texttt{volVars(spaceIdx, timeIdx)}: The secondary variables used by the model relevant for the execution context. These are @@ -217,20 +222,21 @@ methods provide the following methods in addition: Finally, the execution context for the \texttt{boundary} method provides the methods \texttt{boundarySegmentArea(spaceIdx, timeIdx)}, -and \texttt{normal(spaceIdx, timeIdx)}, which return the area and -outer unit normal of the execution context's boundary segment. +and \texttt{normal(spaceIdx, timeIdx)}, which return the area of the +boundary segment and outer unit normal of the boundary segment. When specifying the boundary conditions in the problem class, a small -safeguard value \texttt{eps\_} is usually added when comparing spatial -coordinates. For the problem considered here, the left boundary might -hence not be detected if checking whether the first coordinate of the -global position is equal to zero, but by testing whether it is smaller -than a very small value \texttt{eps\_}. Also, the \texttt{bboxMax()} -(``\textbf{max}imum coordinate of the grid's \textbf{b}ounding -\textbf{b}ox'') method is used here to determine the extend of the -physical domain. It returns a vector with the maximum values of each -global coordinate of the grid. This method and the analogous -\texttt{bboxMin()} method are provided by the problem's base class. +safeguard value \texttt{eps\_} should usually be added when comparing +spatial coordinates. For the problem considered here, the left +boundary might not be detected if checking whether the first +coordinate of the global position is equal to zero, but it is detected +reliably by testing whether it is smaller than an +$\epsilon$-value. Also, the \texttt{bboxMax()} (``\textbf{max}imum +coordinate of the grid's \textbf{b}ounding \textbf{box}'') method is +used here to determine the extend of the physical domain. It returns a +vector with the maximum values on each axis of the grid. This method +and the analogous \texttt{bboxMin()} method are provided by the +problem's base class. In addition to these methods, there might be some additional model-specific methods. @@ -238,35 +244,39 @@ model-specific methods. \subsection{Defining fluid properties} \label{tutorial-coupled:description-fluid-class} -The \eWoms distribution includes some common substances which can be -used out of the box. The properties of pure substances (such as -the components nitrogen, water, or the pseudo-component air) are +The \eWoms distribution includes representations of some common +substances which can be used out of the box. The properties of pure +substances (such as nitrogen, water, or the pseudo-component air) are provided by header files located in the folder \texttt{dumux/material/components}. -When two or more components are considered, interactions between pure -substances become relevant and properties of these mixtures of -substances -- e.g. composition, density or enthalpy -- are of -interest. Such interactions are defined by {\em fluid systems}, which -are located in \texttt{dumux/material/fluidsystems}. A more thorough -overview of the \eWoms fluid framework can be found in +When two or more substances are considered, interactions between these +become relevant and the properties of these mixtures of substances -- +e.g. composition, density or enthalpy -- are required. In \eWoms, such +interactions are defined by {\em fluid systems}, which are located in +\texttt{dumux/material/fluidsystems}. A more thorough overview of the +\eWoms fluid framework can be found in chapter~\ref{sec:fluidframework}. \subsection{Exercises} \label{tutorial-coupled:exercises} + The following exercises will give you the opportunity to learn how you can change soil parameters, boundary conditions, run-time parameters and fluid properties in \eWoms. \subsubsection{Exercise 1} -\renewcommand{\labelenumi}{\alph{enumi})} For Exercise 1 you have -to make only some small changes in the tutorial files. + +\renewcommand{\labelenumi}{\alph{enumi})} + +For Exercise 1 you have to modify the tutorial files only sightly, or +even not at all. \begin{enumerate} \item \textbf{Running the Program} \\ - To get an impression what the results should look like you can first run the original version of -the coupled tutorial model by typing \texttt{./tutorial\_coupled}. + To get an impression what the results should look like, you can first run the original version of +the fully-implicit tutorial problem by typing \texttt{./tutorial\_coupled}. Note, that the time-step size is automatically adapted during the simulation. For visualizing the results using the program \texttt{paraview}, please refer to section \ref{quick-start-guide}. @@ -274,24 +284,23 @@ For visualizing the results using the program \texttt{paraview}, please refer to Change the size of the model domain so that you get a rectangle with edge lengths of $\text{x} = \unit[400]{m}$ and $\text{y} = \unit[500]{m}$ and with discretization lengths of $\Delta \text{x} = - \unit[20]{m}$ and $\Delta \text{y} = \unit[20]{m}$. For this you can + \unit[20]{m}$ and $\Delta \text{y} = \unit[20]{m}$. For this, you can either change the properties defined between lines \ref{tutorial-coupled:default-params-begin} and - \ref{tutorial-coupled:default-params-end} (don't forget to - re-compile the program in this case), or pass you may pass them as - command line parameters to the simulation when you run it. Note, - that you do not have to recompile the program if you add command - line parameters to the executable. + \ref{tutorial-coupled:default-params-end}, or you may pass them as + command line parameters to the simulation when you run it. If you chose to change the problem file, re-compile the simulation - by typing \texttt{make tutorial\_coupled}. In both cases, don't - forget run the simulation as explained above. + by typing \texttt{make tutorial\_coupled}. Note, that you do not + have to recompile the program if you use command line parameters. In + both cases, don't forget run the simulation before re-inspecting the + results using \texttt{paraview}. \item \textbf{Boundary Conditions} \\ - Change the boundary conditions in the file + Change the boundary conditions in the problem file \texttt{tutorialproblem\_coupled.hh} so that water enters from the bottom and oil is extracted from the top boundary. The right and the - left boundary should be closed for water and oil fluxes. + left boundary should be closed for both, water and oil. Note that in \eWoms, flux boundary conditions are specified as fluxes of the conserved quantities into the direction of the outer @@ -300,55 +309,59 @@ For visualizing the results using the program \texttt{paraview}, please refer to simulation by typing \texttt{make tutorial\_coupled} and re-run it as explained above. -\item \textbf{Changing the Shape of the Discrete Elements} \\ - In order to complete this exercise you need a \Dune grid module that - is capable of handling simplex grids. By default, \Dune does not - include such a grid manager in its core modules, but one such grid - manager that is freely available - \texttt{ALUGrid}~\cite{ALUGRID-HP}. If you did not install such a - grid manager, please skip this exercise. +\item \textbf{Changing the Shape of the Discrete Elements} \\ + In order to complete this exercise you need a \Dune grid manager + that is capable of handling simplex grids. By default, \Dune does + not include such a grid manager in its core modules, but the freely + available \texttt{ALUGrid}~\cite{ALUGRID-HP} can be used. If you did + not install such a grid manager, you may also skip this exercise. - To complete this excercise, change the problem's grid creator on - line \ref{tutorial-coupled:set-gridcreator} to + Change the grid creator used by the problem to \texttt{SimplexGridCreator} and the type of the grid to - \texttt{Dune::ALUSimplexGrid<2, 2>} on line + \texttt{Dune::ALUSimplexGrid<2, 2>}. The grid creator is specified + on line \ref{tutorial-coupled:set-gridcreator}, whil the type of the + \Dune grid manager is set on line \ref{tutorial-coupled:set-grid}. You also need to change the include - statement from \texttt{cubegridcreator.hh} to + statement of the grid creator from \texttt{cubegridcreator.hh} to \texttt{simplexgridcreator.hh} on line - \ref{tutorial-coupled:include-grid-creator}. + \ref{tutorial-coupled:include-grid-creator} and the one for the grid + manager from \texttt{dune/grid/yaspgrid.hh} to + \texttt{dune/grid/alugrid.hh} on line \ref{tutorial-coupled:include-grid-manager}. The resulting grid can be examined by re-compiling and starting the simulation, loading the result into \texttt{paraview}, and selecting - \texttt{Surface with Edges} as the visualization mode. + \texttt{Surface with Edges} instead of the default visualization + mode \texttt{Surface}. \item \textbf{Changing Fluids} \\ - In this exercise you will change the fluids used. Use DNAPL instead - of Oil and Brine instead of Water. To do that, you may follow the - steps: + In this exercise you will change the fluids used: Use DNAPL instead + of LNAPL and Brine instead of Water. This can be done by the + following steps: \begin{enumerate} \item Brine: Brine is thermodynamically very similar to pure water but - also considers a fixed amount of salt in the liquid phase. Hence, + also includes a fixed amount of salt in the liquid phase. Hence, the class \texttt{Dumux::Brine} calls back to a class which - represents pure water. This can be, for example \texttt{Dumux::H2O}, - or \texttt{Dumux::SimpleH2O}. The class which represents pure water - is passed to \texttt{Dumux::Brine} as the second template argument - after the data type for scalar values, i.e. the full definition of - the brine component is \texttt{Dumux::Brine >}. The file which defines the brine component - is located in the folder \texttt{dumux/material/components/}. - Include this file and select use the brine component as the wetting phase. -\item DNAPL: Now let us include a component representing an oil that + represents pure water. (This can be, for example + \texttt{Dumux::H2O}, or \texttt{Dumux::SimpleH2O}.) The class which + represents pure water is passed to \texttt{Dumux::Brine} as the + second template argument after the data type for scalar values, + i.e. the full definition of the brine component is + \texttt{Dumux::Brine >}. The file which + defines the brine component is located in the folder + \texttt{dumux/material/components/}. Include this file and select + use the brine component as the wetting phase. +\item DNAPL: Now let us use a component that represents an oil that is heavier than water (in environmental engineering this class of substances is often called \textbf{d}ense \textbf{n}on-\textbf{a}queous \textbf{p}hase \textbf{l}iquid (DNAPL)) which is also located in the folder - \texttt{dumux/material/components/}. Try to include the file and - use the \texttt{DNAPL} component as the non-wetting phase. + \texttt{dumux/material/components/}. Include the correct file and + use the DNAPL component as the non-wetting phase. \end{enumerate} If you want to take a closer look on how the fluid classes are defined and which substances are available in the \eWoms distribution, feel free to browse through the files in the directory -\texttt{dumux/material/components} and to read +\texttt{dumux/material/components} and read chapter~\ref{sec:fluidframework}. \item \textbf{Use a Full-Fledged Fluid System} \\ @@ -362,28 +375,26 @@ chapter~\ref{sec:fluidframework}. Now include the file \texttt{dumux/material/fluidsystems/h2oairfluidsystem.hh}, and instruct the model to use this fluid system by setting - \texttt{FluidSystem} via:\\ + the \texttt{FluidSystem} property via:\\ \begin{lstlisting}[style=eWomsCode] SET_TYPE_PROP(TutorialProblemCoupled, FluidSystem, - Dumux::FluidSystems::H2OAir) + Dumux::FluidSystems::H2OAir) \end{lstlisting} -However, this is a rather complicated fluid system which considers -mixtures of components and also uses tabulated components that need to -be initialized -- i.e. some components use tables for expensive to -calculate quantities that need to be filled with values. The -initialization of the fluid system is normally done in the constructor -of the problem by calling \texttt{FluidSystem::init();}. +However, this is a rather complicated fluid system which considers all +fluid phases as a mixture of the components and also uses tabulated +components that need to be filled with values (i.e. some components +use tables to speed up expensive computations). The initialization of +the fluid system is normally done in the constructor of the problem by +calling \texttt{FluidSystem::init();}. -Remember that in \Cplusplus, the constructor always the same name as -the respective class, i.e. \texttt{TutorialProblemCoupled(..)}. +As water flow replacing a gas is much faster, simulate the problem +only until $2.000$ seconds is reached and start with a time step of +$1$ second. -As water flow replacing a gas is much faster, test your simulation -only until $2000$ seconds and start with a time step of $1$ second. - -Please revert the changes made in this part of the exercise, as we -will continue to use immiscible phases from here on and hence do not -need a complex fluid system. +Now, revert the changes made in this part of the exercise, as we will +continue to use immiscible phases from here on and hence do not need a +complex fluid system. \item \textbf{Changing Constitutive Relations} \\ Instead of using a regularized Brooks-Corey law for the relative @@ -400,7 +411,7 @@ need a complex fluid system. of the property definition by \texttt{LinearMaterial} and rename \texttt{RawMaterialLaw} to \texttt{TwoPMaterialLaw}. Also remove the line which contains the \texttt{EffToAbsLaw} typedef. -\item Then adapt the necessary parameters of the linear law and the +\item Then, adapt the necessary parameters of the linear law and the respective \texttt{set}-functions can be found in the file \texttt{dumux/material/fluidmatrixinteractions/2p/linearmaterialparams.hh}.\\ Call the \texttt{set}-functions from the constructor of the problem. @@ -511,12 +522,12 @@ step size of $100\;\text{s}$. \subsubsection{Exercise 3: Create a New Component} Create a new file for the benzene component called \texttt{benzene.hh} -and implement a new component. (You may copy and modify one of the -existing components located in the directory -\texttt{dumux/material/components}. 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$ and a viscosity of -$0.00112 \, \text{Pa} \; \text{s}$. +and implement a new component. (\textbf{Hint:} The easiest way to do +this is to copy and modify one of the existing components located in +the directory \texttt{dumux/material/components}.) Use benzene as a +new non-wetting fluid and run the problem of Exercise 2 with water and +benzene. Benzene has a density of $889.51 \, \text{kg} / \text{m}^3$ +and a viscosity of $0.00112 \, \text{Pa} \; \text{s}$. \clearpage \newpage diff --git a/doc/handbook/tutorial.tex b/doc/handbook/tutorial.tex index 39686ac61..2bc3e15a8 100644 --- a/doc/handbook/tutorial.tex +++ b/doc/handbook/tutorial.tex @@ -1,23 +1,25 @@ \chapter[Tutorial]{Tutorial}\label{chp:tutorial} \eWoms provides two sorts of models: Models which use a fully-implicit -discretization in space and time and models that are -semi-implicit. +discretization in space and time and models that use a +semi-implicit space and an explicit time discretization. -The semi-implicit solve the combined mass balance equation for all -phases implicitly -- which yields a pressure -- and then transport the -conserved quantities in an explicit step based on the result of the -(implicit) pressure step. For this reason these models are also called -to be based on the IMPES approach (\textbf{i}mplicit \textbf{p}ressure -\textbf{e}xplicit \textbf{s}aturation) or, more generally, on the -IMPET approach (IMPES (\textbf{i}mplicit \textbf{p}ressure +The semi-implicit models work by first implicitly solving a mass +balance equation for all conservation quaintites combined. This +procedire yields a pressure field. Then, the conserved quantities are +transported using an explicit post-processing procedure based on of +the pressure field obtained in the implicit step. These models are +usually refered to be based on the IMPES approach (\textbf{i}mplicit +\textbf{p}ressure \textbf{e}xplicit \textbf{s}aturation) or, more +generally, on the IMPET approach (\textbf{i}mplicit \textbf{p}ressure \textbf{e}xplicit \textbf{t}ransport). -The fully-implicit models, describe the conservation quantities of a -flow system as a system of strongly coupled partial differential -equations. Physically, these conservation quantities are mass, -momentum and energy; Although the momentum is usually not explicitly -conserved in the context of flow models for porous media. +In contrast, the fully-implicit models describe the conservation +quantities of a flow system as a system of strongly coupled partial +differential equations which is directly using a non-linear +solver. Physically, these conservation quantities are mass, momentum +and energy; Although the momentum is usually not explicitly conserved +in the context of flow models for porous media. In section \ref{box} a short introduction to the vertex centered finite volume scheme (VCFV or box method) used by \eWoms as the @@ -27,15 +29,14 @@ which is quite similar to the VCFV discretization, except that this scheme does not require to construct a dual grid centered around the primary grid's vertices. - -The following two sections of the tutorial first introduce how to -solve flow problems using a fully-coupled model (section -\ref{tutorial-coupled}) and then how to solve the same problem using a -semi-implicit model (section \ref{tutorial-decoupled}). Being the -easiest case, an isothermal two-phase system (two fluid phases, one -solid phase) will be considered. The source code of these tutorials is -shipped with the \eWoms source package and can be found in the -\texttt{tutorial} directory. +This chapter, first introduce how to solve flow problems using a +fully-implicit model (section \ref{tutorial-coupled}) and then how to +solve the same problem using a semi-implicit model (section +\ref{tutorial-decoupled}). Being simple but representative case, an +isothermal two-phase problem (i.e. two fluid phases, one solid phase) +will be considered. The source code of these tutorials is shipped with +the \eWoms source package and can be found in the \texttt{tutorial} +directory. \input{tutorial-coupled} \input{tutorial-decoupled} diff --git a/examples/tutorialproblem_coupled.hh b/examples/tutorialproblem_coupled.hh index 5751a99f3..2d2d3c41f 100644 --- a/examples/tutorialproblem_coupled.hh +++ b/examples/tutorialproblem_coupled.hh @@ -38,7 +38,7 @@ #include // For the DUNE grid -#include +#include /*@\label{tutorial-coupled:include-grid-manager}@*/ #include /*@\label{tutorial-coupled:include-grid-creator}@*/ // For Dune::FieldMatrix @@ -103,14 +103,14 @@ SET_SCALAR_PROP(TutorialProblemCoupled, EndTime, 100e3); SET_SCALAR_PROP(TutorialProblemCoupled, InitialTimeStepSize, 125.0); // define the physical size of the problem's domain [m] -SET_SCALAR_PROP(TutorialProblemCoupled, DomainSizeX, 300.0); +SET_SCALAR_PROP(TutorialProblemCoupled, DomainSizeX, 300.0); /*@\label{tutorial-coupled:grid-default-params-begin}@*/ SET_SCALAR_PROP(TutorialProblemCoupled, DomainSizeY, 60.0); SET_SCALAR_PROP(TutorialProblemCoupled, DomainSizeZ, 0.0); // // define the number of cells used for discretizing the physical domain SET_INT_PROP(TutorialProblemCoupled, CellsX, 100); SET_INT_PROP(TutorialProblemCoupled, CellsY, 1); -SET_INT_PROP(TutorialProblemCoupled, CellsZ, 1); /*@\label{tutorial-coupled:default-params-end}@*/ +SET_INT_PROP(TutorialProblemCoupled, CellsZ, 1); /*@\label{tutorial-coupled:default-params-end}@*/ } // namespace Properties //! Tutorial problem using the fully-implicit immiscible model.