Changed decoupled tutorial to use the start() routine

- we decided to keep the tutorials similar and to change them to
     start from a parameter file

doc/handbook/tutorial-decoupled.tex

@@ -53,35 +53,34 @@ essential functions and classes are included.
 At line \ref{tutorial-decoupled:set-type-tag} the type tag of the
 problem which is going to be simulated is set. All other data types
 can be retrieved by the \Dumux property system and only depend on this
-single type tag. Retrieving them is done between line
+single type tag. For an introduction to the
-\ref{tutorial-decoupled:retrieve-types-begin} and
-\ref{tutorial-decoupled:retrieve-types-end}. For an introduction to the
 property system, see section \ref{sec:propertysystem}.
 
-The first thing which should be done at run time is to initialize the
+After this \Dumux' default startup routine \texttt{Dumux::start()} is
-message passing interface using \Dune's \texttt{MPIHelper} class. Line
+called on line \ref{tutorial-decoupled:call-start}. This function deals
-\ref{tutorial-decoupled:init-mpi} is essential if the simulation is
+with parsing the command line arguments, reading the parameter file,
-intended to be run on more than one processor at the same time. Next,
+setting up the infrastructure necessary for \Dune, loads the grid, and
-the command line arguments are parsed starting at line
+starts the simulation. When it comes to parameters, all parameters can
-\ref{tutorial-decoupled:parse-args-begin} until line
+be either specified by command line arguments of the form
-\ref{tutorial-decoupled:parse-args-end}. In this case, we check whether and
+(\texttt{-ParameterName ParameterValue}), in the file specified by the
-at which time a previous run of the simulation should be restarted, and we
+\texttt{-parameterFile} argument, or if the latter is not specified,
-parse the time when the simulation ends. As the maximum time-step in the 
+in the file \texttt{tutorial\_decoupled.input}. If a parameter gets
-sequential model is strictly bound by a CFL-criterion, the first time-step
+specified on the command line as well as in the parameter file, the
-size is initialized with the simulation time.
+values provided in the command line have
-
+precedence. Listing~\ref{tutorial-decoupled:parameter-file} shows the
-After this, a grid is created in line \ref{tutorial-decoupled:create-grid}. 
+default parameter file for the tutorial problem.
-The problem is instantiated with the time manager and information about the grid
-(via its leaf grid view) on line \ref{tutorial-decoupled:instantiate-problem}.
-The time manager controlling the simulation run is instantiated 
-with the start parameters in line \ref{tutorial-decoupled:initTimeManager}.
-If demanded, the time manager also restarts a state written to
-disk by a previous simulation run via the last flag, using the appropriate 
-starting time (which has to be the same as the restart file).
-Finally, the simulation proceedure is started by the time manager in line
-\ref{tutorial-decoupled:execute}.
 
+\begin{lst}[File tutorial/tutorial\_decoupled.input]\label{tutorial-decoupled:parameter-file} \mbox{}
+\lstinputlisting[basicstyle=\ttfamily\scriptsize,numbers=left,numberstyle=\tiny]{../../tutorial/tutorial_decoupled.input}
+\end{lst}
 
+To provide an error message, the usage message which is displayed to
+the user if the simulation is called incorrectly, is printed via the
+custom function which is defined on
+line~\ref{tutorial-decoupled:usage-function}. In this function the usage
+message is customized to the problem at hand. This means that at least
+the necessary parameters are listed here.  For more information about
+the input file please refer to section \ref{sec:inputFiles}.
 
 \subsection{The problem class} \label{decoupled_problem}
 
@@ -104,15 +103,15 @@ is chosen as discretization scheme (defined via the include in line
 \ref{tutorial-decoupled:parent-problem}). On line \ref{tutorial-decoupled:set-problem}, 
 a problem class is attached to the new type tag, while the grid which
 is going to be used is defined in line \ref{tutorial-decoupled:set-grid-type} --
-in this case an \texttt{SGrid} is created.  Since in \Dune, there's no uniform
+in this case an \texttt{YaspGrid} is created. Since there's no uniform mechanism to
-mechanism to allocate grids, the \texttt{Grid} property also contains
+allocate grids in \Dune, \Dumux features the concept of grid creators.
-a static \texttt{create()} method which provides just that: From line 
+In this case the generic \texttt{CubeGridCreator} (line \ref{tutorial-decoupled:set-gridcreator}) which creates a
-\ref{tutorial-decoupled:grid-begin} to \ref{tutorial-decoupled:grid-end}, 
+structured hexahedron grid of a specified size and resolution. For
-the geometry is defined and the grid is generated. The three variables of 
+this grid creator the  physical domain of the grid is specified via the
-Type \texttt{Dune::FieldVector} define the lower left corner of the domain 
+run-time parameters \texttt{Grid.upperRightX},
-(\texttt{L}), the upper right corner of the domain (\texttt{H}) and the number 
+\texttt{Grid.upperRightY}, \texttt{Grid.numberOfCellsX} and
-of cells in $x$ and $y$ direction (\texttt{N}). The grid of type 
+\texttt{Grid.numberOfCellsY}. These parameters can be specified via
-\texttt{Dune::SGrid} is then generated in line \ref{tutorial-decoupled:grid-end}. 
+the command-line or in a parameter file.
 For more information about the \Dune grid interface, the different grid types 
 that are supported and the generation of different grids consult 
 the \textit{Dune Grid Interface HOWTO} \cite{DUNE-HP}. 
@@ -130,8 +129,9 @@ for the problem of interest are specified in line
 \ref{tutorial-decoupled:set-spatialparameters}. 
 
 Now we arrive at some model parameters of the applied two-phase decoupled 
-model. Line \ref{tutorial-decoupled:cfl} assigns the CFL-factor to be used in the
+model. First, in line  \ref{tutorial-decoupled:cflflux} a flux function for the evaluation of the cfl-criterion is defined. This is optional as there exists also a default flux function. The choice depends on the problem which has to be solved. For cases which are not advection dominated the one chosen here is more reasonable.
-simulation run, which determines the time step size. The last property in line \ref{tutorial-decoupled:gravity} 
+Line \ref{tutorial-decoupled:cflfactor} assigns the CFL-factor to be used in the
+simulation run, which scales the time step size (kind of security factor). The last property in line \ref{tutorial-decoupled:gravity} 
 is optional and tells the model not to use gravity.
 
 After all necessary information is written into the property system and 
@@ -148,10 +148,7 @@ general information about the current simulation. First, the name used by
 the \texttt{VTK-writer} to generate output is defined in the method of line
 \ref{tutorial-decoupled:name}, and line \ref{tutorial-decoupled:restart} indicates
 wether restart files are written. As decoupled schemes usually feature small 
-timesteps, the method controlling the output in line \ref{tutorial-decoupled:output}
+timesteps, it can be usefull to set an output interval larger than 1. The respective function is called in line \ref{tutorial-decoupled:outputinterval}, which gets the output interval as argument.
-is very useful. The divisor of the modulo operation defines after how many timesteps
-output should be written out -- the default ``1'' resembles output after each 
-step.
 
 The following methods all have in common that they may be dependent on space.
 Hence, they all have either an \texttt{element} or an \texttt{intersection} as their
@@ -190,8 +187,8 @@ with the decoupled modelling framework.
 For Exercise 1 you only have to make some small changes in the tutorial files.
 \begin{enumerate}
 \item \textbf{Altering output}
-To get an impression what the results should look like you can first run the original version of the decoupled tutorial model by typing  \texttt{./tutorial\_decoupled 1e5}. The number behind the simulation name defines the timespan of the simulation run in seconds. For the visualisation with paraview please refer to \ref{quick-start-guide}.\\
+To get an impression what the results should look like you can first run the original version of the decoupled tutorial model by typing  \texttt{./tutorial\_decoupled}. The runtime parameters which are set can be found in the input file (listing~\ref{tutorial-decoupled:parameter-file}). If the input file has the same name than the main file (e.g. \texttt{tutorial\_decoupled.cc} and \texttt{tutorial\_decoupled.input}), it is automatically chosen. If the name differs the programm has to be started typing \texttt{./tutorial\_decoupled -parameterFile <filename>.input}. For more options you can also type \texttt{./tutorial\_decoupled -h}.For the visualisation with paraview please refer to \ref{quick-start-guide}.\\
-As you can see, the simulation creates roughly 150 output files. To reduce these in order to perform longer simulations, change the method responsible for output (line \ref{tutorial-decoupled:output} in the file \texttt{tutorialproblem\_decoupled}) as to write an output only every 20 timesteps by changeing the divisor. Compile the main file by typing \texttt{make tutorial\_decoupled} and run the model. Now, run the simulation for 5e5 seconds.
+As you can see, the simulation creates many output files. To reduce these in order to perform longer simulations, change the method responsible for output (line \ref{tutorial-decoupled:outputinterval} in the file \texttt{tutorialproblem\_decoupled}) as to write an output only every 20 timesteps. Compile the main file by typing \texttt{make tutorial\_decoupled} and run the model. Now, run the simulation for 5e5 seconds.
 
 \item \textbf{Changing the Model Domain and the Boundary Conditions} \\
 Change the size of the model domain so that you get a rectangle

examples/tutorial_decoupled.cc

@@ -29,90 +29,33 @@
 #include "config.h" /*@\label{tutorial-decoupled:include-begin}@*/
 
 #include "tutorialproblem_decoupled.hh" /*@\label{tutorial-decoupled:include-problem-header}@*/
+#include <dumux/common/start.hh> /*@\label{tutorial-decoupled:include-end}@*/
 
-#include <dune/grid/common/gridinfo.hh>
+//! Prints a usage/help message if something goes wrong or the user asks for help
-
+void usage(const char *progName, const std::string &errorMsg)  /*@\label{tutorial-decoupled:usage-function}@*/
-#include <dune/common/exceptions.hh>
-#include <dune/common/mpihelper.hh>
-
-#include <iostream> /*@\label{tutorial-decoupled:include-end}@*/
-
-////////////////////////////////////////////
-// function to check the input parameters
-////////////////////////////////////////////
-void usage(const char *progname)
 {
-    std::cout << "usage: "<<progname<<" [--restart restartTime] tEnd\n";
+    std::cout
-    exit(1);
+        <<  "\nUsage: " << progName << " [options]\n";
+    if (errorMsg.size() > 0)
+        std::cout << errorMsg << "\n";
+    std::cout
+        << "\n"
+        << "The List of Mandatory arguments for this program is:\n"
+        << "\t-tEnd                The end of the simulation [s]\n"
+        << "\t-dtInitial           The initial timestep size [s]\n"
+        << "\t-Grid.upperRightX    The x-coordinate of the grid's upper-right corner [m]\n"
+        << "\t-Grid.upperRightY    The y-coordinate of the grid's upper-right corner [m]\n"
+        << "\t-Grid.numberOfCellsX The grid's x-resolution\n"
+        << "\t-Grid.numberOfCellsY The grid's y-resolution\n"
+        << "\n";
 }
 
+
 ////////////////////////
 // the main function
 ////////////////////////
 int main(int argc, char** argv)
 {
-    try {
+    typedef TTAG(TutorialProblemDecoupled) TypeTag; /*@\label{tutorial-decoupled:set-type-tag}@*/
-        typedef TTAG(TutorialProblemDecoupled) TypeTag; /*@\label{tutorial-decoupled:set-type-tag}@*/
+    return Dumux::start<TypeTag>(argc, argv, usage); /*@\label{tutorial-decoupled:call-start}@*/
-        typedef GET_PROP_TYPE(TypeTag, Scalar) Scalar;    /*@\label{tutorial-decoupled:retrieve-types-begin}@*/
-        typedef GET_PROP_TYPE(TypeTag, Grid) Grid;
-        typedef GET_PROP_TYPE(TypeTag, Problem) Problem;
-        typedef GET_PROP_TYPE(TypeTag, TimeManager) TimeManager;
-        typedef Dune::FieldVector<Scalar, Grid::dimensionworld> GlobalPosition; /*@\label{tutorial-decoupled:retrieve-types-end}@*/
-
-        // initialize MPI, finalize is done automatically on exit
-        Dune::MPIHelper::instance(argc, argv);  /*@\label{tutorial-decoupled:init-mpi}@*/
-
-        ////////////////////////////////////////////////////////////
-        // parse the command line arguments
-        ////////////////////////////////////////////////////////////
-        if (argc < 2)   /*@\label{tutorial-decoupled:parse-args-begin}@*/
-            usage(argv[0]);
-
-        // deal with the restart stuff
-        int argPos = 1;
-        bool restart = false;
-        double startTime = 0.;
-        if (std::string("--restart") == argv[argPos]) {
-            restart = true;
-            ++argPos;
-            // use restart time as start time
-            std::istringstream(argv[argPos++]) >> startTime;
-        }
-        // output in case of wrong numbers of input parameters
-        if (argc - argPos != 1) {
-            usage(argv[0]);
-        }
-
-        // read the initial time step and the end time
-        double tEnd, dt;
-        std::istringstream(argv[argPos++]) >> tEnd;
-        dt = tEnd;  /*@\label{tutorial-decoupled:parse-args-end}@*/
-
-        // create the grid
-        Grid *gridPtr = GET_PROP(TypeTag, Grid)::create(); /*@\label{tutorial-decoupled:create-grid}@*/
-
-        // create time manager responsible for global simulation control
-        TimeManager timeManager;
-
-        ////////////////////////////////////////////////////////////
-        // instantiate and run the concrete problem
-        ////////////////////////////////////////////////////////////
-        Problem problem(timeManager, gridPtr->leafView()); /*@\label{tutorial-decoupled:instantiate-problem}@*/
-
-        // define simulation parameters
-        timeManager.init(problem, startTime, dt, tEnd, restart); /*@\label{tutorial-decoupled:initTimeManager}@*/
-
-        // run the simulation
-        timeManager.run();    /*@\label{tutorial-decoupled:execute}@*/
-        return 0;
-    }
-    catch (Dune::Exception &e) {
-        std::cerr << "Dune reported error: " << e << std::endl;
-    }
-    catch (...) {
-        std::cerr << "Unknown exception thrown!\n";
-        throw;
-    }
-
-    return 3;
 }

examples/tutorial_decoupled.input

@@ -0,0 +1,7 @@
+tEnd=100000 # duration of the simulation [s]
+dtInitial=10 # initial time step size [s]
+[Grid]
+upperRightX=300 # x-coordinate of the upper-right corner of the grid [m]
+upperRightY=60 # y-coordinate of the upper-right corner of the grid [m]
+numberOfCellsX=100 # x-resolution of the grid
+numberOfCellsY=1 # y-resolution of the grid

examples/tutorialproblem_decoupled.hh

@@ -30,7 +30,8 @@
 #define DUMUX_TUTORIALPROBLEM_DECOUPLED_HH // guardian macro /*@\label{tutorial-decoupled:guardian2}@*/
 
 // the grid includes
-#include <dune/grid/sgrid.hh>
+#include <dune/grid/yaspgrid.hh>
+#include <dumux/common/cubegridcreator.hh>
 
 // dumux 2p-decoupled environment
 #include <dumux/decoupled/2p/diffusion/fv/fvpressureproperties2p.hh>
@@ -41,6 +42,9 @@
 // assign parameters dependent on space (e.g. spatial parameters)
 #include "tutorialspatialparameters_decoupled.hh" /*@\label{tutorial-decoupled:spatialparameters}@*/
 
+// include cfl-criterion after coats: more suitable if the problem is not advection dominated
+#include<dumux/decoupled/2p/transport/fv/evalcflfluxcoats.hh>
+
 // the components that are used
 #include <dumux/material/components/h2o.hh>
 #include <dumux/material/components/oil.hh>
@@ -66,24 +70,10 @@ SET_PROP(TutorialProblemDecoupled, Problem) /*@\label{tutorial-decoupled:set-pro
 };
 
 // Set the grid type
-SET_PROP(TutorialProblemDecoupled, Grid) /*@\label{tutorial-decoupled:grid-begin}@*/
+SET_TYPE_PROP(TutorialProblemDecoupled, Grid, Dune::YaspGrid<2>); /*@\label{tutorial-decoupled:set-grid-type}@*/
-{
+
-    typedef Dune::SGrid<2, 2> type; /*@\label{tutorial-decoupled:set-grid-type}@*/
+//Set the grid creator
-    static type *create() /*@\label{tutorial-decoupled:create-grid-method}@*/
+SET_TYPE_PROP(TutorialProblemDecoupled, GridCreator, Dumux::CubeGridCreator<TypeTag>); /*@\label{tutorial-decoupled:set-gridcreator}@*/
-    {
-        typedef typename type::ctype ctype;
-        Dune::FieldVector<int, 2> cellRes;  // vector holding resolution of the grid
-        Dune::FieldVector<ctype, 2> lowerLeft(0.0); // Coordinate of lower left corner of the grid
-        Dune::FieldVector<ctype, 2> upperRight; // Coordinate of upper right corner of the grid
-        cellRes[0] = 100;
-        cellRes[1] = 1;
-        upperRight[0] = 300;
-        upperRight[1] = 60;
-        return new Dune::SGrid<2,2>(cellRes,
-                                    lowerLeft,
-                                    upperRight);
-    } /*@\label{tutorial-decoupled:grid-end}@*/
-};
 
 // Set the wetting phase
 SET_PROP(TutorialProblemDecoupled, WettingPhase) /*@\label{tutorial-decoupled:2p-system-start}@*/
@@ -103,7 +93,8 @@ public:
     typedef Dumux::LiquidPhase<Scalar, Dumux::Oil<Scalar> > type; /*@\label{tutorial-decoupled:nonwettingPhase}@*/
 }; /*@\label{tutorial-decoupled:2p-system-end}@*/
 
-SET_SCALAR_PROP(TutorialProblemDecoupled, CFLFactor, 0.5); /*@\label{tutorial-decoupled:cfl}@*/
+SET_TYPE_PROP(TutorialProblemDecoupled, EvalCflFluxFunction, Dumux::EvalCflFluxCoats<TypeTag>); /*@\label{tutorial-decoupled:cflflux}@*/
+SET_SCALAR_PROP(TutorialProblemDecoupled, CFLFactor, 0.95); /*@\label{tutorial-decoupled:cflfactor}@*/
 
 // Disable gravity
 SET_BOOL_PROP(TutorialProblemDecoupled, EnableGravity, false); /*@\label{tutorial-decoupled:gravity}@*/
@@ -151,7 +142,10 @@ class TutorialProblemDecoupled: public IMPESProblem2P<TypeTag> /*@\label{tutoria
 public:
     TutorialProblemDecoupled(TimeManager &timeManager, const GridView &gridView)
         : ParentType(timeManager, gridView), eps_(1e-6)/*@\label{tutorial-decoupled:constructor-problem}@*/
-    {    }
+    {
+        //write only every 10th time step to output file
+        this->setOutputInterval(1);/*@\label{tutorial-decoupled:outputinterval}@*/
+    }
 
     //! The problem name.
     /*! This is used as a prefix for files generated by the simulation.
@@ -169,16 +163,6 @@ public:
         return false;
     }
 
-    //! Returns true if the current solution should be written to disk (i.e. as a VTK file)
-    /*! The default behaviour is to write out every the solution for
-     *  very time step. Else, change divisor.
-     */
-    bool shouldWriteOutput() const /*@\label{tutorial-decoupled:output}@*/
-    {
-        return this->timeManager().timeStepIndex() > 0 &&
-        (this->timeManager().timeStepIndex() % 1 == 0);
-    }
-
     //! Returns the temperature within the domain at position globalPos.
     /*! This problem assumes a temperature of 10 degrees Celsius.
      *