Some Documentation updated

doc/Installation.md

@@ -21,7 +21,7 @@ can be obtained from https://gitlab.dune-project.org and need to be found in a
 subdirectory of `DUNE_CONTROL_PATH`. See also https://dune-project.org/doc/installation
 for details about the installation of dune modules.
 
-Additionally we require the following libraries to be found:
+Additionally, we require/suggest the following libraries to be found:
 - [MTL4](https://gitlab.math.tu-dresden.de/spraetor/mtl4) (use this fork to get up-to-date changes)
 - [Boost](http://www.boost.org) >= 1.40
 - [SuiteSparse](http://faculty.cse.tamu.edu/davis/suitesparse.html) (optional)

doc/Mainpage.md

 AMDiS    {#mainpage}
 =====
-The *Adaptive Multi-Dimensional Simulation Toolbox* (AMDiS) is implemented as a
-discretization module on top of the [Dune](https://dune-project.org) framework.
-
-Example
--------
-
-An AMDiS program consists of three main incredients:
-1. A Problem class that holds all information necessary for assembling a linear
-   system, see \ref ProblemStat.
-2. Operators describing the (bi)linear-form of your PDE, see \ref operators.
-3. Adaption-modules for the time- and space adaptive solution of the problem, see \ref Adaption.
-
-**Poisson equation:**
-
-The most simple elliptic PDE is the Poisson equation:
-\f{eqnarray*}{
-  -\Delta u &=& f(x),\quad\mbox{ in }\Omega \\
-          u &=& g(x),\quad\mbox{ on }\partial\Omega
-\f}
-where \f$ f(x) \f$ and \f$ g(x) \f$ are parameters describing the volume and
-boundary forces of the problem.
-
-The corresponding weak form of the equation reads:
-\f[
-  \langle \nabla v, \nabla u\rangle_\Omega = (f(x)\,v)_\Omega,\quad\forall v\in V_0
-\f]
-with \f$ u\in V_g \f$.
-
-Thus, we need to define a grid (discretization of \f$ \Omega \f$) and a finite
-element space (discretization of \f$ V_0 \f$ and \f$ V_g \f$). This cab be
-provided as `Traits` parameter in the ProblemStat class:
-
-~~~~~~~~~~~~~~~{.cpp}
-using Grid = Dune::AlbertaGrid<AMDIS_DIM, AMDIS_DOW>;
-using Traits = LagrangeBasis<Grid::LeafGridView, 1>;
-~~~~~~~~~~~~~~~
-
-where `AlbertaGrid` defines a grid and `Traits` a Lagrange Finite-Element space with
-local polynomial degree 1 on the elements.
-
-All AMDiS programs start with initialization of the library, using `AMDiS::init`
-
-~~~~~~~~~~~~~~~{.cpp}
-using namespace AMDiS;
-int main(int argc, char** argv)
-{
-  AMDiS::init(argc, argv);
-
-  ProblemStat<Traits> prob("name");
-~~~~~~~~~~~~~~~
-
-The Problem class is initialized with a name, that is used as identifier in the
-parameter files. In order to initialize the Finite-Element space, the grid and
-all other parts of the problem class, call `initialize(Flag)` where `Flag`
-specifies what to initialize. For now, we initialize everything: `INIT_ALL`:
+The *Adaptive Multi-Dimensional Simulation Toolbox* (AMDiS) is a Finite-Element
+discretization module allowing for fast prototyping of PDEs on adaptively refined
+grids. It is implemented on top of the [Dune](https://dune-project.org) framework.
+
+Tutorial
+--------
+As an example of usage, we want to solve an elliptic PDE, the Poisson equation,
+\f$ -\Delta u = f \f$ in \f$ \Omega \f$ with \f$ u = g \f$ on a subset of the boundary
+\f$ \Gamma\subset\partial\Omega \f$. For simplicity, we assume \f$ f(x) \equiv -1 \f$
+and \f$ g(x) \equiv 0 \f$, the domain \f$ \Omega \f$ a square domain \f$ [0,1]^2 \f$
+and \f$ \Gamma \f$ the lower and left edge of the boundary.
 
-~~~~~~~~~~~~~~~{.cpp}
-prob.initialize(INIT_ALL);
-~~~~~~~~~~~~~~~
-
-Operators specify the (bi-)linear-form and the coefficient function in the term,
-see \ref operators for a list of possible types. The bilinear-form in the Poisson
-equation consists of a second-order term with coefficient = 1 and the linear-form
-includes the function \f$ f(x)=-1 \f$:
-
-~~~~~~~~~~~~~~~{.cpp}
-auto opL = makeOperator(tag::gradtest_gradtrial{}, 1.0);
-prob.addMatrixOperator(opL, 0, 0);
-
-auto opF = makeOperator(tag::test{}, [](auto const& x) { return -1.0; }, 0);
-prob.addVectorOperator(opF, 0);
-~~~~~~~~~~~~~~~
-
-Boundary conditions, in the example above a Dirichlet condition, is specified by
-defining a predicate for the boundary \f$ \Gamma\subset\partial\Omega \f$ and the
-values on the boundary \f$ g(x) = 0 \f$:
-
-~~~~~~~~~~~~~~~{.cpp}
-auto predicate = [](auto const& x){ return x[0] < 1.e-8 || x[1] < 1.e-8; };
-prob.addDirichletBC(predicate, 0, 0, 0.0);
-~~~~~~~~~~~~~~~
-
-The final step is the assembling and solution of the linear system. (Maybe including
-grid adaption). This is realized using an \ref AdaptStationary class:
-
-~~~~~~~~~~~~~~~{.cpp}
-AdaptInfo adaptInfo("adapt");
-AdaptStationary adapt("adapt", prob);
-adapt.adapt(); // assemble and solve
-~~~~~~~~~~~~~~~
-
-Finally, finish the AMDiS program with `AMDiS::finish()`.
-
-The complete program then reads:
 ~~~~~~~~~~~~~~~{.cpp}
 #include <dune/amdis/AMDiS.hpp>
 #include <dune/amdis/AdaptInfo.hpp>
 #include <dune/amdis/AdaptStationary.hpp>
 #include <dune/amdis/ProblemStat.hpp>
 
+// The namespace all AMDiS classes and functions are defined in
 using namespace AMDiS;
 
+// A dune grid type
 using Grid = Dune::AlbertaGrid<AMDIS_DIM, AMDIS_DOW>;
+
+// A dune-functions globalBasis wrapped in a struct,
+// here representing local polynomial shape functions of degree 1
 using Traits = LagrangeBasis<Grid::LeafGridView, 1>;
 
-int main(int argc, char** argv)
+int main(int argc, char* argv[])
 {
+  // Initialize linear-algebra backend and read parameters from file
   AMDiS::init(argc, argv);
 
+  // Create a problem class containing all data for assembling
   ProblemStat<Traits> prob("poisson");
+  // Initialize grid, globalBasis, solution vector and systenmatrix
   prob.initialize(INIT_ALL);
 
+  // An operator representing the weak laplacian with coefficient = 1.0
   auto opL = makeOperator(tag::gradtest_gradtrial{}, 1.0);
   prob.addMatrixOperator(opL, 0, 0);
 
+  // An rhs-operator representing an analytic function f(x) = -1
   auto opF = makeOperator(tag::test{}, [](auto const& x) { return -1.0; }, 0);
   prob.addVectorOperator(opF, 0);
 
-  // set boundary condition
+  // Define the boundary Gamma
   auto predicate = [](auto const& x){ return x[0] < 1.e-8 || x[1] < 1.e-8; };
+  // Set a value g(x) = 0 at this part of the boundary
   prob.addDirichletBC(predicate, 0, 0, 0.0);
 
-  // assemble and solve
+  // assemble and solve the linear system
   AdaptInfo adaptInfo("adapt");
   AdaptStationary adapt("adapt", prob);
   adapt.adapt();
@@ -130,4 +59,12 @@ int main(int argc, char** argv)
   AMDiS::finalize();
   return 0;
 }
-~~~~~~~~~~~~~~~
\ No newline at end of file
+~~~~~~~~~~~~~~~
+
+Notes
+-----
+An AMDiS program consists of three main incredients:
+1. A Problem class that holds all information necessary for assembling a linear
+   system, see \ref ProblemStat.
+2. Operators describing the (bi)linear-form of your PDE, see \ref operators.
+3. A parameter file controlling several parts of the solution process, see \ref Initfile.