Merge branch 'feature/additionalDocInTut1' into 'master'

[doc][tutorial] additional in-code comments based on student feedback

See merge request !896

tutorial/ex1/exercise1_2p.cc

@@ -46,6 +46,7 @@
 
 #include <dumux/io/vtkoutputmodule.hh>
 
+// The problem file, where setup-specific boundary and initial conditions are defined.
 #include "injection2pproblem.hh"
 
 ////////////////////////
@@ -101,6 +102,8 @@ int main(int argc, char** argv) try
     gridVariables->init(x, xOld);
 
     // get some time loop parameters
+    // getParam<TYPE>("GROUPNAME.PARAMNAME") reads and sets parameter PARAMNAME
+    // of type TYPE given in the group GROUPNAME from the input file
     using Scalar = typename GET_PROP_TYPE(TypeTag, Scalar);
     const auto tEnd = getParam<Scalar>("TimeLoop.TEnd");
     const auto maxDivisions = getParam<int>("TimeLoop.MaxTimeStepDivisions");

tutorial/ex1/exercise1_2p2c.cc

@@ -46,6 +46,7 @@
 
 #include <dumux/io/vtkoutputmodule.hh>
 
+// The problem file, where setup-specific boundary and initial conditions are defined.
 #include "injection2p2cproblem.hh"
 
 ////////////////////////
@@ -101,6 +102,8 @@ int main(int argc, char** argv) try
     gridVariables->init(x, xOld);
 
     // get some time loop parameters
+    // getParam<TYPE>("GROUPNAME.PARAMNAME") reads and sets parameter PARAMNAME
+    // of type TYPE given in the group GROUPNAME from the input file
     using Scalar = typename GET_PROP_TYPE(TypeTag, Scalar);
     const auto tEnd = getParam<Scalar>("TimeLoop.TEnd");
     const auto maxDivisions = getParam<int>("TimeLoop.MaxTimeStepDivisions");

tutorial/ex1/injection2p2cproblem.hh

@@ -105,6 +105,8 @@ public:
                 /*numP=*/300);
 
         // name of the problem and output file
+        // getParam<TYPE>("GROUPNAME.PARAMNAME") reads and sets parameter PARAMNAME
+        // of type TYPE given in the group GROUPNAME from the input file
         name_ = getParam<std::string>("Problem.Name");
         // depth of the aquifer, units: m
         aquiferDepth_ = getParam<Scalar>("Problem.AquiferDepth");

tutorial/ex1/injection2pniproblem.hh

@@ -107,6 +107,8 @@ public:
                 /*numP=*/300);
 
         // name of the problem and output file
+        // getParam<TYPE>("GROUPNAME.PARAMNAME") reads and sets parameter PARAMNAME
+        // of type TYPE given in the group GROUPNAME from the input file
         name_ = getParam<std::string>("Problem.Name");
         // depth of the aquifer, units: m
         aquiferDepth_ = getParam<Scalar>("Problem.AquiferDepth");
@@ -234,7 +236,7 @@ public:
         * set a temperature gradient of 0.03 K per m beginning at 283 K here.
         * Hint: you can use aquiferDepth_ and the globalPos similar to the pressure gradient
         * use globalPos[0] and globalPos[1] to implement the high temperature lens with 380 K
-        * Hint : use Indices::temperatureIdx
+        * Hint : use Indices::temperatureIdx to address the initial values for temperature
         */
         return values;
     }

tutorial/ex1/injection2pproblem.hh

@@ -40,6 +40,7 @@ class InjectionProblem2P;
 
 namespace Properties
 {
+// define the TypeTag for this problem with a cell-centered two-point flux approximation spatial discretization.
 NEW_TYPE_TAG(Injection2pTypeTag, INHERITS_FROM(TwoP, InjectionSpatialParamsTypeTag));
 NEW_TYPE_TAG(Injection2pCCTypeTag, INHERITS_FROM(CCTpfaModel, Injection2pTypeTag));
 
@@ -103,6 +104,8 @@ public:
                 /*numP=*/300);
 
         // name of the problem and output file
+        // getParam<TYPE>("GROUPNAME.PARAMNAME") reads and sets parameter PARAMNAME
+        // of type TYPE given in the group GROUPNAME from the input file
         name_ = getParam<std::string>("Problem.Name");
         // depth of the aquifer, units: m
         aquiferDepth_ = getParam<Scalar>("Problem.AquiferDepth");
@@ -147,9 +150,11 @@ public:
      */
     BoundaryTypes boundaryTypesAtPos(const GlobalPosition &globalPos) const
     {
-         BoundaryTypes bcTypes;
+        BoundaryTypes bcTypes;
+        // set the left of the domain (with the global position in "0 = x" direction as a Dirichlet boundary
         if (globalPos[0] < eps_)
             bcTypes.setAllDirichlet();
+        // set all other as Neumann boundaries
         else
             bcTypes.setAllNeumann();
 
@@ -184,6 +189,8 @@ public:
         PrimaryVariables values(0.0);
 
         // if we are inside the injection zone set inflow Neumann boundary conditions
+        // using < boundary + eps_ or > boundary - eps_ is safer for floating point comparisons
+        // than using <= or >= as it is robust with regard to imprecision introduced by rounding errors.
         if (time_ < injectionDuration_
             && globalPos[1] < 15 + eps_ && globalPos[1] > 7 - eps_ && globalPos[0] > 0.9*this->fvGridGeometry().bBoxMax()[0])
         {

tutorial/ex1/injection2pspatialparams.hh

@@ -70,6 +70,7 @@ class InjectionSpatialParams : public FVSpatialParams<TypeTag>
     using GridView = typename GET_PROP_TYPE(TypeTag, GridView);
     using Scalar = typename GET_PROP_TYPE(TypeTag, Scalar);
 
+    // get the dimensions of the simulation domain from GridView
     static const int dimWorld = GridView::dimensionworld;
     using GlobalPosition = Dune::FieldVector<Scalar, dimWorld>;
 
@@ -118,8 +119,8 @@ public:
      * \param globalPos The global position
      */
     PermeabilityType permeabilityAtPos(const GlobalPosition& globalPos) const
-
     {
+        // here, either aquitard or aquifer permeability are returned, depending on the global position
         if (isInAquitard_(globalPos))
             return aquitardK_;
         return aquiferK_;
@@ -132,6 +133,7 @@ public:
      */
     Scalar porosityAtPos(const GlobalPosition& globalPos) const
     {
+        // here, either aquitard or aquifer porosity are returned, depending on the global position
         if (isInAquitard_(globalPos))
             return aquitardPorosity_;
         return aquiferPorosity_;
@@ -193,8 +195,12 @@ private:
 
     static constexpr Scalar eps_ = 1e-6;
 
+    // provides a convenient way distinguishing whether a given location is inside the aquitard
     bool isInAquitard_(const GlobalPosition &globalPos) const
-    { return globalPos[dimWorld-1] > aquiferHeightFromBottom_ + eps_; }
+    {
+        // globalPos[dimWorld-1] is the y direction for 2D grids or the z direction for 3D grids
+        return globalPos[dimWorld-1] > aquiferHeightFromBottom_ + eps_;
+    }
 
     Scalar aquitardK_;
     Scalar aquiferK_;