Merge branch 'feature/improve-handbook_inoutput-parallel' into 'feature/improve-handbook'

[handbook] Improve input/output and parallel sections

See merge request !1401

doc/handbook/5_inputoutput.tex

 \section{Input and Output}
 \label{sec:inputandoutput}
 
-This section summarizes some ideas about grid generation and grid formats that can be used by \Dumux
-for input and output formats.
-In general,
-\Dumux can read grids from file, or construct grids inside the code. All grids are constructed inside a so called \texttt{GridCreator} which is a \Dumux property.
-Note that some \texttt{GridCreator}s are already available in \Dumux, so e.g.
-construction of a structured grid is fairly easy. We will subsequently introduce the supported file formats, the standard \texttt{Gridcreator} and its capabilities
-and briefly mention how to customize and deal with common other grid formats.
+This section briefly explains grid generation in \Dumux, summarizes
+the grid formats that can be used by \Dumux and introduces the \Dumux \texttt{GridManager}.
+Finally, this section informs about handling output in \Dumux.
 
 \subsection{Supported grid file formats}
-\Dumux can read grids from file using the Dune Grid Format (DGF) or the Gmsh mesh format.
+\Dumux can read grids from file using the Dune Grid Format (DGF) or the Gmsh mesh format (MSH).
+Using the class \texttt{Dumux::VTKReader}, \Dumux has experimental support for reading grids and data from VTK files.
 
 \subsubsection{Dune Grid Format}
-Most of our \Dumux tests and tutorials use the Dune Grid Format (DGF) to read in grids. A detailed description
+Most of our \Dumux tests use the Dune Grid Format (DGF) to read in grids. A detailed description
 of the DGF format and some examples can be found in the \Dune doxygen documentation
 \textbf{(Modules $\rightarrow$ I/O $\rightarrow$ Dune Grid Format (DGF)}). To generate larger or more
-complex DGF files, we recommend to write your own scripts, e.g in \Cplusplus, Matlab or Python.
+complex DGF files, we recommend to write your own scripts, e.g, in \Cplusplus, Matlab or Python.
 
-The DGF format can also used to read in spatial parameters defined on the grid. These parameters can
+The DGF format can also be used to read in spatial parameters defined on the grid. These parameters can
 be defined on nodes as well as on the elements. An example for predefined parameters on a grid
-can be found in the  \texttt{dumux/test/porousmediumflow/co2/implicit/} folder.
+can be found in \texttt{dumux/test/porousmediumflow/co2/implicit/}.
 
 \subsubsection{Gmsh Mesh Format}
 Gmsh is an open-source flexible grid generator for unstructured finite-element meshes (\cite{GEUZAINE2009}, \url{http://geuz.org/gmsh/}).
-\Dumux supports the default Gmsh mesh format (MSH). For the format specifics and how to create grids with Gmsh, e.g. using
+\Dumux supports the default Gmsh mesh format (MSH). For the format specifics and how to create grids with Gmsh, e.g., using
 the provided GUI, we refer to the Gmsh documentation (\url{http://geuz.org/gmsh/doc/texinfo/gmsh.html}).
 
-The MSH format can contain element and boundary markers defined in the grid. Thus, boundaries can be easily marked as e.g. inflow boundaries
-using Gmsh. Further, the format supports higher order elements. They can be used to create boundary parameterization supported by e.g. the grid
+The MSH format can contain element and boundary markers defined on the grid. Thus, boundaries can be easily marked as, e.g., inflow boundaries
+using Gmsh. Further, the format supports higher order elements. They can be used to create boundary parameterization supported by, e.g., the grid
 manager \texttt{UGGrid}.
-An example can be found in \texttt{dumux/test\allowbreak/io/gridcreator}.
+An example can be found in \texttt{dumux/test\allowbreak/io/gridmanager}.
 
 \subsubsection{Other Grid Formats}
-Grid formats other than .DGF and .MSH grids will have to be converted to the .DGF or .MSH format before they can be used in \Dumux.
-If conversion is not an option, another possibility would be to write your own \texttt{GridCreator}. Examples of other grid formats,
+Grid formats other than DGF, MSH, VTK will have to be converted to the DGF, MSH, VTK format before they can be used in \Dumux.
+If conversion is not an option, another possibility would be to write your own \texttt{GridManager}. Examples of other grid formats,
 which have previously been either converted or custom-created in \Dumux, are Petrel grids (cornerpoint grids),
 ArtMesh grids (fractured network grids), and ICEM grids (CAD developed grids).
 
-\subsection{The default \texttt{GridCreator}}
-The default \texttt{GridCreator} is called \texttt{GridCreator} and is automatically avaible in all problems.
-It can construct grids from a DGF file (*.dgf) by simply providing the filename to the grid in the \texttt{Grid} group~\footnote{Note
+\subsection{The \Dumux \texttt{GridManager}}
+The \Dumux \texttt{GridManager} constructs the grid from information in the input file and handles the data.
+Currently, supported grid managers are \texttt{YaspGrid}, \texttt{OneDGrid}, \texttt{dune-uggrid}, \texttt{dune-alugrid}, \texttt{dune-foamgrid}, \texttt{dune-subgrid}, \texttt{opm-grid} (cornerpoint grids) and \texttt{dune-spgrid}.
+Grids can be constructed from a DGF or MSH file by simply providing the filename to the grid in the \texttt{Grid} group~\footnote{Note,
 that group name \texttt{Grid} is the default group name and can be customized in your problem changing the string property \texttt{GridParameterGroup}.
-This way it is possible, e.g. for problems with more than one grid, to set different group names for each grid, thus configuring them separately.}
+This way, it is possible, e.g., for problems with more than one grid, to set different group names for each grid, thus configuring them separately.}
 of the input file:
 \begin{lstlisting}[style=DumuxParameterFile]
 [Grid]
 File = mydgfgrid.dgf
 \end{lstlisting}
-If you are using an unstructured grid manager like \texttt{UGGrid} or \texttt{ALUGrid}, constructing a grid from a Gmsh mesh file (*.msh) is just changing a line:
+
+If you are using an unstructured grid manager like \texttt{UGGrid} or \texttt{ALUGrid}, constructing a grid from a MSH is just changing a line:
 \begin{lstlisting}[style=DumuxParameterFile]
 [Grid]
 File = mygmshgrid.msh
 \end{lstlisting}
-\Dumux will tell you in case your selected grid manager does not support reading Gmsh files. You want to intially refine your grid? It's just adding a line:
+\Dumux will tell you in case your selected grid manager does not support reading MSH files.
+
+You want to intially refine your grid? It's just adding a line:
 \begin{lstlisting}[style=DumuxParameterFile]
 [Grid]
 File = mydgfgrid.dgf
 Refinement = 4
 \end{lstlisting}
-When reading a Gmsh file, further parameters are recognized. \texttt{Verbose} enables verbose output on grid construction when set to $1$.
-\texttt{BoundarySegments} enables reading parametrized boundaries. \texttt{PhysicalEntities} enables reading boundary and element flags.
 
-\subsubsection{Grid manager specific parameters}
-The default \texttt{GridCreator} supports also a selection of grid specific parameters.
-To give an example we look at the commonly used unstructured grid manager \texttt{UGGrid}.
-\texttt{UGGrid}s support red-green refinement per default. One can turn off the green closure by setting the grid's closure type
+When reading a MSH file, further parameters are recognized. \texttt{Verbose} enables verbose output on grid construction when set to $1$.
+\texttt{BoundarySegments} enables reading parameterized boundaries. \texttt{PhysicalEntities} enables reading boundary and element flags.
+
+\subsubsection{Parameters specific to the grid manager}
+The \Dumux \texttt{GridManager} supports also a selection of parameters that are specific to the chosen grid manager.
+To give an example, we take a look at the unstructured grid manager \texttt{UGGrid}.
+\texttt{UGGrid} supports red-green refinement per default. One can turn off the green closure by setting the grid's closure type
 \begin{lstlisting}[style=DumuxParameterFile]
 [Grid]
 File = mydgfgrid.dgf
 ClosureType = None # or Green
 \end{lstlisting}
+
 For all available parameters see the Doxygen documentation.
 
 \subsubsection{Structured grids}
-If you want to construct a structured grid with the default grid creator instead of the \texttt{File} key supply
+If you want to construct a structured grid without using a specific grid file, insert the following into the input file:
 \begin{lstlisting}[style=DumuxParameterFile]
 [Grid]
 LowerLeft = 0 0 0
@@ -82,12 +85,12 @@ UpperRight = 1 1 1
 Cells = 10 10 20
 \end{lstlisting}
 where \texttt{LowerLeft} is a vector to the lower left corner of the grid and \texttt{UpperRight} a vector to the upper right corner.
-\texttt{Cells} is a vector with the number of cells in each coordinate direction. Note that for a grid in a two-dimensional world, the
+\texttt{Cells} is a vector with the number of cells in each coordinate direction. Note,  that for a grid in a two-dimensional world, the
 vectors only have two entries.
 
-Depending on the grid manager further parameters are recognized.
-\texttt{UGGrid}s, for example, supports simplex elements as well as hexahedral elements
-(called simplified ``cube'' in \Dune). When creating a structured grid, we can select the cell type as follows
+Depending on the grid manager, further parameters are recognized.
+\texttt{UGGrid}, for example, supports simplex elements as well as hexahedral elements
+(called ``cube'' in \Dune). When creating a structured grid, we can select the cell type as follows
 \begin{lstlisting}[style=DumuxParameterFile]
 [Grid]
 LowerLeft = 0 0 0
@@ -95,33 +98,28 @@ UpperRight = 1 1 1
 Cells = 10 10 20
 CellType = Cube # or Simplex
 \end{lstlisting}
-For all available parameters see the Doxygen documentation.
 
-% \subsubsection{Cornerpoint grids}
-% TODO
+For all available parameters see the Doxygen documentation.
 
-\subsection{Output formats}
-The default output format for \Dumux is the vtk-file format. Additionally it is possible 
-to generate plots with the gnuplot interface.
+\subsection{Input and Output formats}
 
 \subsubsection{VTK file format}
-Dumux allows to write out simulation results via the vtkwirter.
-For every print out step, a single *.vtu file is created. For parallel simulations one file
-per printoutstep is generated for each processor. 
-Time step information and files are stored in a *.pvd file.
-The *.pvd file groups the singel *.vtu files and contains additionaly the timestep information.
-Also it is the main file for the visualisation with paraview.
-The vtk-file format is also supported by other common visualisation programms like Visit and Tecplot. 
+Dumux allows to write out simulation results via the \texttt{VtkOutputModule}.
+For every print-out step, a single \texttt{*.vtu} file is created. For parallel simulations one file
+per print-out step is generated for each processor.
+The \texttt{*.pvd} file groups the single \texttt{*.vtu} files and contains additionally the time step information.
+The VTK file format is supported by common visualisation programs like ParaView, VisIt, and Tecplot.
 
 \subsubsection{Customize the VTK output}
-Dependent on the used \texttt{TYPETAG} a default set of variables is stored in the VTK files, but it's also possible
-to add further variables. For that you can use the method \texttt{addField} of the \texttt{vtkWriter}.
+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,
+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");
 \end{lstlisting}
 
 The first input argument of this method is the value of the additional variable, provided by a method of the corresponding problem.
-If it doesn't already exists, the user has to provide this method (see example below for analytic temperatur).
+If it does not already exists, the user has to provide this method.
 \begin{lstlisting}[style=DumuxCode]
 //! get the analytical temperature
 const std::vector<Scalar>& getExactTemperature()
@@ -129,11 +127,23 @@ const std::vector<Scalar>& getExactTemperature()
     return temperatureExact_;
 }
 \end{lstlisting}
+It is important that the life-time of the added field exceeds the life-time of the writer. That means you can't pass temporaries
+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/test\_1p2cni\_convection\_fv.cc}
+
+\subsubsection{VTK as input format}
+There is experimental support for reading data and grids from VTK files. Have a look at the \texttt{Dumux::VTKReader} class.
 
 \subsubsection{Gnuplot interface}
-\Dumux provides some gnuplot interface, which can be used to plot results and generate directly an 
-image file (e.g. png). To use the gnuplot interface gnuplot has to be installed. For more information see \ref{gnuplot}.
+\Dumux provides a small interface to GNUPlot, which can be used to plot results and generate
+image files (e.g., png). To use the gnuplot, gnuplot has to be installed. For more information see \ref{gnuplot}.
+
+\subsubsection{Container I/O}
+\Dumux supports writing to file from and reading to some standard \Cplusplus containers like \texttt{std::vector<double>} or \texttt{std::vector<Dune::FieldVector>}.
+If you want to read and write simple vectors, have a look at the header \texttt{dumux/io/container.hh}.
 
+\subsubsection{Matrix and Vector I/O}
+\texttt{dune-istl} supports writing and reading vectors and matrices to/from different format. For example you can write a matrix in a sparse matrix format that
+can be read by Matlab (see \texttt{dune/istl/io.hh}).

doc/handbook/5_parallel.tex

 \section{Parallel Computation}
 \label{sec:parallelcomputation}
-Multicore processors are standard nowadays and parallel programming is the key to gain
-performance from modern computers. This section explains how \Dumux can be used 
-on multicore systems, ranging from the users desktop computer to high performance
-computing clusters.  
-
-There are different concepts and methods for parallel programming, they are
-often grouped in \textit{shared-memory} and \textit{distributed-memory}  
-apporaches. The parallelization in \Dumux is based on the 
-\textit{Message Passing Interface} (MPI), which is usually called MPI parallelization (distributed-memory approach). 
-It is the MPI parallelization that allows the user to run
-\Dumux applications in parallel on a desktop computer, the users laptop or 
-large high performance clusters. However, the chosen \Dumux 
-model must support parallel computations, which is the case for the most \Dumux applications.
-
-The main idea behind the MPI parallelization is the concept of \textit{domain 
-decomposition}. For parallel simulations, the computational domain is splitted into 
-subdomains and one process (\textit{rank}) is used to solves the local problem of each 
-subdomain. During the global solution process, some data exchange between the 
-ranks/subdomains is needed. MPI is used to send data to other ranks and to receive 
-data from other ranks. 
-Most grid managers contain own domain decomposition methods to split the 
-computational domain  into subdomains. Some grid managers also support external 
-tools like METIS or ParMETIS for partitioning.
-
-Before \Dumux can be started in parallel, a 
-MPI library (e.g. OpenMPI, MPICH or IntelMPI) 
-must be installed on the system and all \Dune modules and \Dumux must be recompiled.  
-
-
-\subsection{Prepare an Parallel Application}
-Not all parts of \Dumux can be used in parallel. One example are the linear solvers
-of the sequential backend. However, with the AMG backend \Dumux provides 
-a parallel solver backend based on Algebraic Multi Grid (AMG) that can be used in
-parallel. 
-If an application uses not allready the AMG backend, the 
-backend must be switched by the user to run the application also in parallel.
-
-First, the header files for the parallel AMG backend must be included.
+This section explains how \Dumux can be used
+on multicore / multinode systems.
+
+There are different concepts and methods for parallel programming, which are
+often grouped in \textit{shared-memory} and \textit{distributed-memory}
+approaches. The parallelization in \Dumux is based on the model supported by Dune which is currently based on
+\textit{Message Passing Interface} (MPI) (distributed-memory approach).
+
+The main idea behind the MPI parallelization is the concept of \textit{domain
+decomposition}. For parallel simulations, the computational domain is split into
+subdomains and one process (\textit{rank}) is used to solve the local problem of each
+subdomain. During the global solution process, some data exchange between the
+ranks/subdomains is needed. MPI is used to send data to other ranks and to receive
+data from other ranks. The domain decomposition in Dune is handled by the grid managers.
+The grid is partitioned and distributed on several nodes. Most grid managers contain own domain decomposition methods to split the
+computational domain  into subdomains. Some grid managers also support external
+tools like METIS, ParMETIS, PTScotch or ZOLTAN for partitioning.
+On the other hand linear algebra types such as matrices and vectors
+do not know that they are in a parallel environment. Communication is then handled by the components of the
+parallel solvers. Currently, the only parallel solver backend is \texttt{Dumux::AMGBackend}, a parallel AMG-preconditioned
+BiCGSTAB solver.
+
+In order for \Dumux simulation to run in parallel, an
+MPI library (e.g. OpenMPI, MPICH or IntelMPI) implementation
+must be installed on the system.
+
+\subsection{Prepare a Parallel Application}
+Not all parts of \Dumux can be used in parallel. In order to switch to the parallel \texttt{Dumux::AMGBackend}
+solver backend include the respective header
 
 \begin{lstlisting}[style=DumuxCode]
 #include <dumux/linear/amgbackend.hh>
 \end{lstlisting}
 
-so that the backend can be used. The header files of the sequential backend
+Second, the linear solver must be switched to the AMG backend
 
 \begin{lstlisting}[style=DumuxCode]
-#include <dumux/linear/seqsolverbackend.hh>
+using LinearSolver = Dumux::AMGBackend<TypeTag>;
 \end{lstlisting}
-can be removed.
 
-Second, the linear solver must be switched to the AMG backend 
+and the application must be recompiled. The parallel \texttt{Dumux::AMGBackend} instance has to be
+constructed with a \texttt{Dune::GridView} object and a mapper, in order to construct the
+parallel index set needed for communication.
 
 \begin{lstlisting}[style=DumuxCode]
-using LinearSolver = Dumux::AMGBackend<TypeTag>;
+auto linearSolver = std::make_shared<LinearSolver>(leafGridView, fvGridGeometry->dofMapper());
 \end{lstlisting}
 
-and the application must be compiled. 
-
-\subsection{Run an Parallel Application}
-The parallel simulation is started with the \textbf{mpirun} command.
+\subsection{Run a Parallel Application}
+The starting procedure for parallel simulations depends on the chosen MPI library.
+Most MPI implementations use the \textbf{mpirun} command
 
 \begin{lstlisting}[style=Bash]
 mpirun -np <n_cores> <executable_name>
 \end{lstlisting}
 
-\textit{np} sets the number of cores (\texttt{n\_cores}) that should be used for the 
-computation. On a cluster you usually have to use a queuing system (e.g. slurm) to 
-submit a job. 
+where \textit{-np} sets the number of cores (\texttt{n\_cores}) that should be used for the
+computation. On a cluster you usually have to use a queuing system (e.g. slurm) to
+submit a job. Check with your cluster administrator how to run parallel applications on the cluster.
 
 \subsection{Handling Parallel Results}
-For most models, the results should not differ between parallel and serial 
-runs. However, parallel computations are not naturally deterministic. 
-A typical case where one can not assume a deterministic behavior are models where
-small differences in the solution can cause large differences in the results 
-(e.g. for some turbulent flow problems). Nevertheless, it is useful to expect that
-the simulation results do not depend on the number of cores. Therefore one should question
-when a model is not deterministic. Typical reasons for a wrong non deterministic
-behaviour are errors in the parallel computation of boundary conditions or missing/reduced
-data exchange in higher order gradient approximations. 
-
-
-For serial computations \Dumux produces single vtu-files as default output format. 
-During a simulation, one vtu-file is written for every output step. 
-In the parallel case, one vtu-file for each step and processor is created. 
-For parallel computations an additional variable "process rank" is written 
-into the file. The process rank allows the user to inspect the subdomains 
-after the computation.
-
-\subsection{MPI scaling}
-For parallel computations the number of cores must be choosen 
-carefully. Using too many cores will not always lead to more performance, but 
-can produce a bad efficiency. One reason is that for small subdomains, the 
-communication between the subdomains gets the limiting factor for parallel computations. 
-The user should test the MPI scaling (realtion between the number of cores and the computation time) 
-for each specific application to ensure a fast and efficient use of the given resources.   
+For serial computations, \Dumux produces single vtu-files as default output format.
+During a simulation, one vtu-file is written for every output step.
+In the parallel case, one vtu-file for each step and processor is created.
+For parallel computations, an additional variable \texttt{"process rank"} is written
+into the file. The process rank allows the user to inspect the subdomains
+after the computation. The parallel vtu-files are combined in a single pvd file
+like in sequential simulations that can be opened with e.g. ParaView.