\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/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
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/implicit/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}).
