[doxygen] Move input/output section from handbook to doxygen

doc/doxygen/DoxygenDumuxLayout.xml

@@ -21,6 +21,7 @@ SPDX-License-Identifier: GPL-3.0-or-later
     <tab type="usergroup" title="Usage documentation">
       <tab type="user" url="@ref runtime-parameters" visible="yes" title="Runtime Parameters" intro=""/>
       <tab type="user" url="@ref running-in-parallel" visible="yes" title="Running in parallel" intro=""/>
+      <tab type="user" url="@ref input-and-output-formats" visible="yes" title="Input and output formats" intro=""/>
     </tab>
     <tab type="modules" visible="yes" title="Module documentation" intro=""/>
     <tab type="user" url="@ref flow-and-transport-in-porous-media" visible="yes" title="Flow and transport in porous media" intro=""/>

doc/doxygen/pages/input-output.md

+# Input and output formats
+
+This section explains summarizes
+the grid formats that can be used by DuMux
+and introduces grid management via Dumux::GridManager.
+We briefly discuss grid generation. Finally, we discuss the options for
+outputting results for checkpointing or visualization.
+
+## Supported grid formats
+
+DuMux can read grids from file using the Dune Grid Format (DGF),
+the Gmsh mesh format (MSH, version 2),
+the Eclipse grid format (GRDECL),
+and various Visualization ToolKit (VTK/VTU/VTP) formats.
+
+### The Dune Grid Format (DGF)
+
+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
+([Modules $\rightarrow$ I/O $\rightarrow$ Dune Grid Format (DGF)](https://www.dune-project.org/doxygen/2.9.0/group__DuneGridFormatParser.html#details)). To generate larger or more
+complex DGF files, we recommend to write your own scripts, e.g, in C++, Matlab or Python.
+
+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 [`dumux/test/porousmediumflow/co2`](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/-/tree/master/test/porousmediumflow/co2).
+
+### The Gmsh MSH format
+
+[Gmsh](http://geuz.org/gmsh/) is a powerful open-source grid generator for unstructured (and structured)
+finite-element meshes (@cite GEUZAINE2009).
+DuMux supports the default Gmsh mesh format (MSH), version 2, through Dune.
+For the format specifics and how to create grids with Gmsh, e.g., using
+the provided GUI, we refer to the [Gmsh documentation](http://geuz.org/gmsh/doc/texinfo/gmsh.html).
+Note that the current default in Gmsh produces files in the format version 4. Use the option
+
+```sh
+gmsh -format msh2
+```
+
+or add `Mesh.MshFileVersion = 2.2;` in a `.geo` file.
+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 parametrization supported by, e.g., the grid
+managers `Dune::UGGrid` and `Dune::FoamGrid`.
+
+### Eclipse Grid Format
+
+The Eclipse Grid Format (GRDECL) is commonly used for corner-point grids.
+Such grids consist of hexahedra, which are described by eight points on so-called pillars.
+A special feature of corner-point geometries is that points on pillars can degenerate,
+meaning that two neighboring points on a pillar can coincide.
+Furthermore, faces are, in general, bi-linear and cells can be non-convex.
+This allows for the accurate description of faults, layers, or wells, occurring in geological environments.
+
+Furthermore, petrophysical properties can be defined (for each cell),
+by using eclipse-specific keywords, e.g. `PORO`, `PERMX`, `PERMY`.
+
+DuMux supports the Eclipse Grid Format by using the [`opm-grid` module](https://github.com/OPM/opm-grid)
+of the [Open Porous Media iniative (OPM)](https://opm-project.org).
+See @ref external-libraries for how to install `opm-grid` together with DuMux.
+An example using a corner-point grid can be found in `dumux/test/porousmediumflow/2p/cornerpoint`.
+
+### VTK File Format
+
+VTK format uses ASCII or XML format. It is mostly used by DuMux for output purposes and can be visualized
+by programs such as Paraview, VisIt or Tecplot. Using VTK files to input grid and parameter data is also possible.
+An example can be found in `dumux/test/io/gridmanager`.
+
+### Other Grid Formats
+
+Grid formats other than DGF, MSH, GRDECL, or VTK will have to be converted to the DGF, MSH, GRDECL, or VTK format before they can be used in DuMux.
+A powerful converter tool supporting many common formats is the Python tool [`meshio`](https://pypi.org/project/meshio/).
+If conversion is not an option, another possibility would be to write your own manager class based on Dumux::GridManager.
+
+## The DuMux Grid manager class
+
+The Dumux::GridManager class helps to construct the grid from information in the input file and also handles data provided in grid files.
+Currently, supported Dune grid interface implementations are `Dune::YaspGrid`, `Dune::OneDGrid`, `Dune::UGGrid`, `Dune::ALUGrid`, `Dune::FoamGrid`, `Dune::SubGrid`, `OPM::Grid` (cornerpoint grids), and `Dune::SPGrid`
+(also see [overview of grid managers in Dune](https://www.dune-project.org/groups/grid/)).
+Grids can be constructed from a DGF, VTK or MSH file by simply providing the filename to the grid in the `[Grid]` group.
+Note that group name `[Grid]` is the default group name and can be customized in your problem changing the string property Dumux::Properties::GridParameterGroup. For setups with more than one grid, a different group name can be set for each grid,
+which allows to set different options per grid.
+
+An exemplary input file configuring the grid manager to read a grid from the file `mydgfgrid.dgf` looks like this
+
+```ini
+[Grid]
+File = mydgfgrid.dgf
+```
+
+If you are using an unstructured grid interface like `UGGrid` or `FOAMGrid`, constructing a grid from a VTK or MSH is just changing a line:
+
+```ini
+[Grid]
+File = mygmshgrid.msh
+```
+
+DuMux will tell you in case your selected grid manager does not support reading such files.
+
+You want to initially refine your grid? It's just adding a line:
+
+```ini
+[Grid]
+File = mydgfgrid.dgf
+Refinement = 4
+```
+
+When reading a MSH or VTK file, further parameters are recognized. `Verbose` enables verbose output on grid construction when set to $1$.
+`BoundarySegments` enables reading parameterized boundaries. `PhysicalEntities` enables reading boundary and element flags.
+
+### Parameters specific to the grid implementation
+
+The Dumux::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 `Dune::UGGrid`.
+`UGGrid` supports red-green refinement per default. One can turn off the green closure by setting the grid's closure type
+
+```ini
+[Grid]
+File = mydgfgrid.dgf
+ClosureType = None # or Green
+```
+
+For all available parameters, see Dumux::GridManager and its specializations for different grid types.
+
+### Structured grids
+If you want to construct a structured grid without using a specific grid file, insert the following into the input file:
+
+```ini
+[Grid]
+LowerLeft = 0 0 0
+UpperRight = 1 1 1
+Cells = 10 10 20
+```
+
+where `LowerLeft` is a vector to the lower left corner of the grid and `UpperRight` a vector to the upper right corner.
+`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.
+`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
+
+```ini
+[Grid]
+LowerLeft = 0 0 0
+UpperRight = 1 1 1
+Cells = 10 10 20
+CellType = Cube # or Simplex
+```
+
+For all available parameters see Dumux::GridManager<Dune::YaspGrid<dim,Coordinates>>
+and Dumux::GridManager<Dune::YaspGrid<dim,Dune::TensorProductCoordinates<ctype,dim>>> class documentations.
+
+### Other grid manager implementations
+
+* Dumux::CakeGridManager: Provides a method to create a piece of cake grid
+* Dumux::CpGridManager: Reads the GRDECL file and generates a corner-point grid
+
+## Other input and output formats
+
+The following formats are supported for checkpointing, visualization, and general
+data input and output.
+
+### VTK file format (output)
+
+Dumux allows to write out simulation results via the `VtkOutputModule`.
+For every print-out step, a single VTU file is created. For parallel simulations one file
+per print-out step is generated for each processor.
+The PVD file groups the single VTU files and contains additionally the time step information.
+The VTK file format is supported by common visualisation programs like ParaView, VisIt, and Tecplot.
+
+If provided by the model implementation, the `initOutputModule` function of the model's `IOFields`,
+adds a default set of variables to the VTK output module instance. It is also possible to add variables,
+using the member function Dumux::VtkOutputModuleBase::addField of the Dumux::VtkOutputModule.
+For example, to add a variable called `temperatureExact` add
+
+```cpp
+vtkWriter.addField(problem->getExactTemperature(), "temperatureExact");
+```
+
+The first input argument of this method is the value of the additional variable,
+provided by a method of the corresponding problem.
+If it does not already exists, the user has to provide this method.
+
+```cpp
+const std::vector<Scalar>& getExactTemperature()
+{ return temperatureExact_; }
+```
+
+It is important that the life-time of the added field exceeds the life-time of the writer. That means you cannot pass temporaries
+to the Dumux::VtkOutputModuleBase::addField function. The vector has to be stored somewhere, e.g. in the program main function.
+
+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 `test/porousmediumflow/1pnc/implicit/1p2c/nonisothermal/convection/main.cc`
+
+### VTK file format (input)
+There is support for reading data and grids from VTK files, see Dumux::VTKReader.
+
+## Gnuplot interface
+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 Dumux::GnuplotInterface.
+
+## Container I/O
+DuMux supports writing to file from and reading
+into some STL containers like `std::vector<double>` or `std::vector<Dune::FieldVector>`.
+If you want to read and write simple vectors, have a look at the header dumux/io/container.hh.
+
+## Matrix and Vector I/O
+
+`dune-istl` (the Dune Iterative Solver Template Library) 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 the header `dune/istl/io.hh`).

doc/handbook/0_dumux-handbook.tex

@@ -136,7 +136,6 @@ This chapter contains detailed information for those who are interested
 in deeper modifications of underlying \Dumux models, classes, functions, etc.
 \input{6_temporaldiscretizations}
 \input{6_stepsofasimulation}
-\input{6_inputoutput}
 
 \bibliographystyle{plainnat}
 \bibliography{dumux-handbook}

doc/handbook/6_inputoutput.tex

-% SPDX-FileCopyrightInfo: Copyright © DuMux Project contributors, see AUTHORS.md in root folder
-% SPDX-License-Identifier: CC-BY-4.0
-
-\section{Input and Output}
-\label{sec:inputandoutput}
-
-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}
-\label{sec:supportedGridFormats}
-\Dumux can read grids from file using the Dune Grid Format (DGF), the Gmsh mesh format (MSH), the Eclipse grid format (GRDECL), or the Visualization ToolKit (VTK/VTU/VTP) format. 
-
-\subsubsection{Dune Grid Format}
-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.
-
-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 \texttt{dumux/test/porousmediumflow/co2/}.
-
-\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
-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 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 parametrization supported by, e.g., the grid
-manager \texttt{UGGrid}.
-An example can be found in \texttt{dumux/test\allowbreak/io/gridmanager}.
-
-\subsubsection{Eclipse Grid Format}
-The Eclipse Grid Format (GRDECL) is commonly used for corner-point grids.
-Such grids consist of hexahedra, which are described by eight points on so-called pillars. A special feature of corner-point geometries is that points on pillars can degenerate, meaning that two neighboring points on a pillar can coincide. Furthermore, faces are, in general, bi-linear and cells can be non-convex. This allows for the accurate description of faults, layers, or wells, occurring in geological environments.
-
-Furthermore, petrophysical properties can be defined (for each cell), by using eclipse-specific keywords, e.g. \texttt{PORO}, \texttt{PERMX}, \texttt{PERMY}.
-
-\Dumux supports the Eclipse Grid Format by using the \texttt{opm-grid} module (see (\url{https://opm-project.org}).
-An example can be found in \texttt{dumux/test\allowbreak/porousmediumflow/2p/cornerpoint}.
-
-\subsubsection{VTK File Format}
-VTK format uses ASCII or XML format. It is mostly used by \Dumux for output purposes and can be visualized by programs such as Paraview, ViIt or Tecplot. Using VTK files to input grid and parameter data is also possible.
-An example can be found in \texttt{dumux/test\allowbreak/io/gridmanager}.
-
-\subsubsection{Other Grid Formats}
-Grid formats other than DGF, MSH, GRDECL, or VTK will have to be converted to the DGF, MSH, GRDECL, or 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}s. Examples of other grid formats,
-which have previously been either converted or custom-created in \Dumux, are ArtMesh grids (fractured network grids), and ICEM grids (CAD developed grids).
-
-\subsection{The \Dumux \texttt{GridManager}}
-The \texttt{Dumux::GridManager} class constructs the grid from information in the input file and handles the data.
-Currently, supported Dune grid interface implementations  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, VTK 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.}
-of the input file:
-\begin{lstlisting}[style=DumuxParameterFile]
-[Grid]
-File = mydgfgrid.dgf
-\end{lstlisting}
-
-If you are using an unstructured grid interface like \texttt{UGGrid} or \texttt{FOAMGrid}, constructing a grid from a VTK or 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 such files.
-
-You want to initially refine your grid? It's just adding a line:
-\begin{lstlisting}[style=DumuxParameterFile]
-[Grid]
-File = mydgfgrid.dgf
-Refinement = 4
-\end{lstlisting}
-
-When reading a MSH or VTK 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 implementation}
-The \texttt{{Dumux::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 \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 without using a specific grid file, insert the following into the input file:
-\begin{lstlisting}[style=DumuxParameterFile]
-[Grid]
-LowerLeft = 0 0 0
-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
-vectors only have two entries.
-
-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
-UpperRight = 1 1 1
-Cells = 10 10 20
-CellType = Cube # or Simplex
-\end{lstlisting}
-
-For all available parameters see the Doxygen documentation.
-
-\subsubsection{Other \Dumux \texttt{GridManager}s}
-\begin{itemize}
-\item \texttt{CakeGridManager}: Provides a method to create a piece of cake grid.
-\item \texttt{CpGridManager}: Reads the GRDECL file and generates a corner-point grid.
-\item \texttt{SubgridGridManager}: Creates a \texttt{dune-subgrid} for some given host grid.
-\end{itemize}
-
-\subsection{Input and Output formats}
-
-\subsubsection{VTK file format}
-Dumux allows to write out simulation results via the \texttt{VtkOutputModule}.
-For every print-out step, a single VTU file is created. For parallel simulations one file
-per print-out step is generated for each processor.
-The PVD file groups the single 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}
-Using the respective \texttt{initOutputModule} function of the model \texttt{IOFields}, a default
-set of variables is defined for the output into the VTK files. It is also possible to add further variables,
-using the member function \texttt{addField} of the \texttt{VtkOutputModule}. For example, to add a variable called \texttt{temperatureExact}:
-\begin{lstlisting}[style=DumuxCode]
-vtkWriter.addField(problem->getExactTemperature(), "temperatureExact");
-\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 does not already exists, the user has to provide this method.
-\begin{lstlisting}[style=DumuxCode]
-//! get the analytical temperature
-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/1p2c/nonisothermal/convection/main.cc}
-
-\subsubsection{VTK as input format}
-There is support for reading data and grids from VTK files, see subsection \ref{sec:supportedGridFormats}.
-
-\subsubsection{Gnuplot interface}
-\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}).