opm-simulators/doc/handbook/parameterTree.tex

\section{Parameter Files in \Dumux}
\label{sec:inputFiles}
In section \ref{quick-start-guide} an application was started using an input file. 
This file is worth taking a closer look at because using it considerably improves usability. 

\begin{itemize}
 \item The parameter file is read in by the compiled program. This way you can change 
values in there without having to recompile the whole application. 
\item You can use the parameter file in order to back up parameters that you used for a certain model run. 
\item The parameter file is easily extendable. 
\end{itemize}

After having run the example application from section \ref{quick-start-guide} you will (almost) get the following output\footnote{If you did not get the output, restart the application the following way:
  \texttt{./test{\_}2p -parameterFile ./test\_2p.input -PrintParameters 1 }} at the end of the simulation run:
\begin{lstlisting}[style=Bash]
###############################
# Run-time specified parameters:
###############################
dtInitial = "1"
gridFile = "./grids/test_2p.dgf"
parameterFile = "./test_2p.input"
tEnd = "1"
[ SpatialParameters ]
lensLowerLeftX = "1.0"
lensLowerLeftY = "2.0"
lensUpperRightX = "4.0"
lensUpperRightY = "3.0"
###############################
# Compile-time specified parameters:
###############################
EnableGravity = "1"
EnableHints = "0"
EnableJacobianRecycling = "1"
EnablePartialReassemble = "1"
MassUpwindWeight = "1"
MaxTimeStepSize = "1e+100"
NumericDifferenceMethod = "1"
PreconditionerRelaxation = "1"
[ LinearSolver ]
MaxIterations = "250"
ResidualReduction = "1e-06"
Verbosity = "0"
[ Newton ]
AbsTolerance = "1e-05"
EnableAbsoluteCriterion = "0"
EnableRelativeCriterion = "1"
MaxSteps = "18"
RelTolerance = "1e-08"
SatisfyAbsAndRel = "0"
TargetSteps = "10"
UseLineSearch = "0"
WriteConvergence = "0"
###############################
# UNUSED PARAMETERS:
###############################
SpatialParameters.sthIMadeUp = "42"
\end{lstlisting}

A number of things can be learned from this. Most prominently it tells you the parameters, that can easily be added to the input file without having to change anything in the source code. 
By simply adding the lines\\
\texttt{[ Newton ]\\
RelTolerance = 1e-11}\\
to the input file you can specify that the Newton solver considers itself converged for an error a thousand times smaller. 

Secondly you can see, that there is a variable in the input  file which the program did not use:
\newline
\texttt{SpatialParameters.sthIMadeUp = "42"}.
\newline 
This output was generated by adding the line \\
\lstinline{sthIMadeUp = 42 # [strangeUnit]}\\
at the end of the parameter file. Because the application did not read in this value it is shown here under \texttt{UNUSED PARAMETERS}. You can also see, that the variable was grouped into the SpatialParameters group, because no new group was started. 

This feature is \emph{very} useful for debugging or spotting typos. If you want to overwrite one of the parameters listed under \texttt{Compile-time specified parameters} and misspelled it in the input file, it will be listed in the  \texttt{UNUSED PARAMETERS} section. 

For further use of the input file please refer to the problem file 
\newline 
\texttt{/test/boxmodels/2p2c/injectionproblem.hh}.
\newline
In there, a number of parameters are read in for use in the actual problem. 

If you also want to specify  the grid and spatial extension of your problem via the parameter file, please have a look at 
  \newline 
\texttt{/test/boxmodels/2p/}.
  
\subsection{Technical Issues}
In case you want to learn more about how the input files work, please have a look at the very helpful \Dune documentation, look for \texttt{Dune::ParameterTree}.
  
The parameter tree can also be filled without the help of a text file. Everything that is specified in a \Dumux input file can also be specified directly on the command line. If there is also an input file, the respective parameter on the command line has precedence. 

All applications have a help message which you can read by giving \texttt{--help}   as a command line argument to the application. A message listing syntax and the mandatory input will be displayed on the command line.