[examples][tracer] edits on spatialparams_1p

examples/1ptracer/spatialparams_1p.hh

@@ -21,25 +21,26 @@
 #ifndef DUMUX_INCOMPRESSIBLE_ONEP_TEST_SPATIAL_PARAMS_HH
 #define DUMUX_INCOMPRESSIBLE_ONEP_TEST_SPATIAL_PARAMS_HH
 
-// In this file, we generate the random permeability field in the constructor of the `OnePTestSpatialParams` class. Thereafter, spatial properties of the porous medium such as the permeability and the porosity are defined in various functions for the 1p problem.
-// We want to generate a random permeability field. For this, we use a random number generation of the C++ standard library.
+// In this file, we generate a random permeability field in the constructor of the `OnePTestSpatialParams` class.
+// For this, we use the random number generation facilities provided by the C++ standard library.
 #include <random>
-// In the file `properties.hh` all properties are declared.
+
+// We use the properties for porous medium flow models, declared in the file `properties.hh`.
 #include <dumux/porousmediumflow/properties.hh>
 
-// We include the spatial parameters for single-phase, finite volumes from which we will inherit.
+// We include the spatial parameters class for single-phase models discretized by finite volume schemes.
+// The spatial parameters defined for this example will inherit from those.
 #include <dumux/material/spatialparams/fv1p.hh>
 
 namespace Dumux {
 
-// In the `OnePTestSpatialParams` class, we define all functions needed to describe the porous matrix, e.g. porosity and permeability for the 1p_problem.
-
+// In the `OnePTestSpatialParams` class, we define all functions needed to describe the porous medium, e.g. porosity and permeability for the 1p_problem.
 template<class GridGeometry, class Scalar>
 class OnePTestSpatialParams
 : public FVSpatialParamsOneP<GridGeometry, Scalar,
                              OnePTestSpatialParams<GridGeometry, Scalar>>
 {
-    // We introduce `using` declarations that are derived from the property system, which we need in this class.
+    // We declare aliases for types that we are going to need in this class.
     using GridView = typename GridGeometry::GridView;
     using FVElementGeometry = typename GridGeometry::LocalView;
     using SubControlVolume = typename FVElementGeometry::SubControlVolume;
@@ -51,6 +52,9 @@ class OnePTestSpatialParams
     using GlobalPosition = typename SubControlVolume::GlobalPosition;
 
 public:
+
+    // The spatial parameters must export the type used to define permeabilities.
+    // Here, we are using scalar permeabilities, but tensors are also supported.
     using PermeabilityType = Scalar;
     OnePTestSpatialParams(std::shared_ptr<const GridGeometry> gridGeometry)
     : ParentType(gridGeometry), K_(gridGeometry->gridView().size(0), 0.0)
@@ -60,11 +64,12 @@ public:
         permeability_ = getParam<Scalar>("SpatialParams.Permeability");
         permeabilityLens_ = getParam<Scalar>("SpatialParams.PermeabilityLens");
 
-        // Further, we get the position of the lens, which is defined by the position of the lower left and the upper right corner.
+        // Furthermore, we get the position of the lens, which is defined by the position of the lower left and the upper right corner.
         lensLowerLeft_ = getParam<GlobalPosition>("SpatialParams.LensLowerLeft");
         lensUpperRight_ =getParam<GlobalPosition>("SpatialParams.LensUpperRight");
 
-        // We generate random fields for the permeability using a lognormal distribution, with the `permeability_` as mean value and 10 % of it as standard deviation. A seperate distribution is used for the lens using `permeabilityLens_`.
+        // We generate random fields for the permeability using lognormal distributions, with `permeability_` as mean value and 10 % of it as standard deviation.
+        // A separate distribution is used for the lens using `permeabilityLens_`. A permeability value is created for each element of the grid and is stored in the vector `K_`.
         std::mt19937 rand(0);
         std::lognormal_distribution<Scalar> K(std::log(permeability_), std::log(permeability_)*0.1);
         std::lognormal_distribution<Scalar> KLens(std::log(permeabilityLens_), std::log(permeabilityLens_)*0.1);
@@ -77,7 +82,9 @@ public:
     }
 
     // ### Properties of the porous matrix
-    // We define the (intrinsic) permeability $`[m^2]`$ using the generated random permeability field. In this test, we use element-wise distributed permeabilities.
+    // This function returns the permeability $`[m^2]`$ to be used within a sub-control volume (`scv`) inside the element `element`.
+    // One can define the permeability as function of the primary variables on the element, which are given in the provided `ElementSolution`.
+    // Here, we use element-wise distributed permeabilities that were randomly generated in the constructor (see above).
     template<class ElementSolution>
     const PermeabilityType& permeability(const Element& element,
                                          const SubControlVolume& scv,
@@ -87,7 +94,7 @@ public:
     }
 
 
-    // We set the porosity $`[-]`$ for the whole domain.
+    // We set the porosity $`[-]`$ for the whole domain to a value of $`20 \%`$.
     Scalar porosityAtPos(const GlobalPosition &globalPos) const
     { return 0.2; }