Merge branch 'cleanup/cahn-hilliard-example' into 'master'

Cleanup/cahn hilliard example

See merge request !3661

examples/cahn_hilliard/README.md

@@ -45,7 +45,7 @@ with the concentration $c(x,t)$, the mobility coefficient $M$, and surface tensi
 The domain $\Omega \subset \mathbb{R}^2$ is initialized with a concentration field
 $c(x,t=0) = 0.42 + \zeta$, randomly perturbed by
 noise $\zeta$ following a uniform distribution $\zeta \sim U(-0.02, 0.02)$.
-With time the concentration field evolves towards attaining mostly values near to $0$ or $1$ while
+Over time, the concentration field evolves towards attaining mostly values near to $0$ or $1$ while
 conserving the total concentration. The model describes the separation of two immiscible fluids.
 
 The fourth order PDE cannot be solved by a standard finite volume scheme. We therefore

examples/cahn_hilliard/doc/_intro.md

@@ -43,7 +43,7 @@ with the concentration $c(x,t)$, the mobility coefficient $M$, and surface tensi
 The domain $\Omega \subset \mathbb{R}^2$ is initialized with a concentration field
 $c(x,t=0) = 0.42 + \zeta$, randomly perturbed by
 noise $\zeta$ following a uniform distribution $\zeta \sim U(-0.02, 0.02)$.
-With time the concentration field evolves towards attaining mostly values near to $0$ or $1$ while
+Over time, the concentration field evolves towards attaining mostly values near to $0$ or $1$ while
 conserving the total concentration. The model describes the separation of two immiscible fluids.
 
 The fourth order PDE cannot be solved by a standard finite volume scheme. We therefore

examples/cahn_hilliard/doc/main.md

@@ -105,7 +105,7 @@ public:
 
 In the `source` function, we implement the derivative of the free energy.
 This demonstrates how parts of the local residual can be split into model specific
-parts and parts that might change from scenario to scenario.
+parts (see `CahnHilliardModelLocalResidual`) and parts that might change from scenario to scenario.
 
 ```cpp
     template<class ElementVolumeVariables>
@@ -121,8 +121,8 @@ parts and parts that might change from scenario to scenario.
     }
 ```
 
-For the boundary we choose boundary flux (or Neumann) conditions for all equations and on
-every part of the boundary, specifying zero flux everywhere for both equations.
+We choose boundary flux (or Neumann) conditions for all equations on the entire boundary,
+while specifying zero flux for both equations.
 
 ```cpp
     BoundaryTypes boundaryTypesAtPos(const GlobalPosition& globalPos) const
@@ -138,7 +138,7 @@ every part of the boundary, specifying zero flux everywhere for both equations.
 
 The parameters interfaces are used in the local residual (see Part 1).
 We can name this interface however we want as long as we adapt the calling site
-in the `LocalResidual` class in `model.hh`.
+in the `CahnHilliardModelLocalResidual` class in `model.hh`.
 
 ```cpp
     Scalar mobility() const

examples/cahn_hilliard/doc/model.md

@@ -183,14 +183,13 @@ the equation for the chemical potential does not have a storage term.
     }
 ```
 
-**Flux term:** The function `computeFlux` computes the fluxes
-over a sub control volume faces, including the integration over
-the area of the face.
+**Flux term:** The function `computeFlux` computes the integrated
+fluxes over a sub control volume face.
 
 ```math
 \begin{aligned}
-F_{K,\sigma,0} &= -M \sum_{B \in \mathcal{B}_K} \mu_{h,B} \nabla N_B \cdot\boldsymbol{n} \vert \sigma \vert \cr
-F_{K,\sigma,1} &= -\gamma \sum_{B \in \mathcal{B}_K} c_{h,B} \nabla N_B \cdot\boldsymbol{n} \vert \sigma \vert
+F_{K,\sigma,0} &= -M \vert \sigma \vert \sum_{B \in \mathcal{B}_K} \mu_{h,B} \nabla N_B \cdot\boldsymbol{n} \cr
+F_{K,\sigma,1} &= -\gamma \vert \sigma \vert \sum_{B \in \mathcal{B}_K} c_{h,B} \nabla N_B \cdot\boldsymbol{n}
 \end{aligned}
 ````
 
@@ -212,7 +211,7 @@ F_{K,\sigma,1} &= -\gamma \sum_{B \in \mathcal{B}_K} c_{h,B} \nabla N_B \cdot\bo
         for (const auto& scv : scvs(fvGeometry))
         {
             const auto& volVars = elemVolVars[scv];
-            // v.axpy(a, w) means v <- v + a*w
+            // v.axpy(a, w) means v += a*w
             gradConcentration.axpy(
                 volVars.concentration(),
                 fluxVarCache.gradN(scv.indexInElement())
@@ -236,7 +235,7 @@ F_{K,\sigma,1} &= -\gamma \sum_{B \in \mathcal{B}_K} c_{h,B} \nabla N_B \cdot\bo
     }
 ```
 
-**Source term:** The function `computeSource` computes the sources terms for a sub control volume.
+**Source term:** The function `computeSource` computes the source terms for a sub control volume.
 We implement a model-specific source term for the chemical potential equation before
 deferring further implementation to the problem where we add the derivative of the free
 energy.
@@ -285,7 +284,6 @@ struct LocalResidual<TypeTag, TTag::CahnHilliardModel>
 { using type = CahnHilliardModelLocalResidual<TypeTag>; };
 ```
 
-The default scalar type is double.
 We compute with double precision floating point numbers.
 
 ```cpp
@@ -296,7 +294,7 @@ struct Scalar<TypeTag, TTag::CahnHilliardModel>
 
 The model traits specify some information about our equation system.
 Here we have two equations. The indices allow to access primary variables
-and equations with a named indices.
+and equations with named indices.
 
 ```cpp
 template<class TypeTag>
@@ -319,7 +317,8 @@ struct ModelTraits<TypeTag, TTag::CahnHilliardModel>
 ```
 
 The primary variable vector has entries of type `Scalar` and is
-as large as the number of equations (here 2) but we keep it general.
+as large as the number of equations (here 2) but we keep it general
+here by obtaining the number of equations from the `ModelTraits`.
 
 ```cpp
 template<class TypeTag>

examples/cahn_hilliard/main.cc

@@ -85,7 +85,7 @@ public:
 
     // In the `source` function, we implement the derivative of the free energy.
     // This demonstrates how parts of the local residual can be split into model specific
-    // parts and parts that might change from scenario to scenario.
+    // parts (see `CahnHilliardModelLocalResidual`) and parts that might change from scenario to scenario.
     template<class ElementVolumeVariables>
     NumEqVector source(const Element &element,
                        const FVElementGeometry& fvGeometry,
@@ -98,8 +98,8 @@ public:
         return values;
     }
 
-    // For the boundary we choose boundary flux (or Neumann) conditions for all equations and on
-    // every part of the boundary, specifying zero flux everywhere for both equations.
+    // We choose boundary flux (or Neumann) conditions for all equations on the entire boundary,
+    // while specifying zero flux for both equations.
     // [[codeblock]]
     BoundaryTypes boundaryTypesAtPos(const GlobalPosition& globalPos) const
     {
@@ -114,7 +114,7 @@ public:
 
     // The parameters interfaces are used in the local residual (see Part 1).
     // We can name this interface however we want as long as we adapt the calling site
-    // in the `LocalResidual` class in `model.hh`.
+    // in the `CahnHilliardModelLocalResidual` class in `model.hh`.
     // [[codeblock]]
     Scalar mobility() const
     { return mobility_; }

examples/cahn_hilliard/model.hh

@@ -181,14 +181,13 @@ public:
     }
     // [[/codeblock]]
 
-    // **Flux term:** The function `computeFlux` computes the fluxes
-    // over a sub control volume faces, including the integration over
-    // the area of the face.
+    // **Flux term:** The function `computeFlux` computes the integrated
+    // fluxes over a sub control volume face.
     //
     // ```math
     // \begin{aligned}
-    // F_{K,\sigma,0} &= -M \sum_{B \in \mathcal{B}_K} \mu_{h,B} \nabla N_B \cdot\boldsymbol{n} \vert \sigma \vert \cr
-    // F_{K,\sigma,1} &= -\gamma \sum_{B \in \mathcal{B}_K} c_{h,B} \nabla N_B \cdot\boldsymbol{n} \vert \sigma \vert
+    // F_{K,\sigma,0} &= -M \vert \sigma \vert \sum_{B \in \mathcal{B}_K} \mu_{h,B} \nabla N_B \cdot\boldsymbol{n} \cr
+    // F_{K,\sigma,1} &= -\gamma \vert \sigma \vert \sum_{B \in \mathcal{B}_K} c_{h,B} \nabla N_B \cdot\boldsymbol{n}
     // \end{aligned}
     // ````
     //
@@ -209,7 +208,7 @@ public:
         for (const auto& scv : scvs(fvGeometry))
         {
             const auto& volVars = elemVolVars[scv];
-            // v.axpy(a, w) means v <- v + a*w
+            // v.axpy(a, w) means v += a*w
             gradConcentration.axpy(
                 volVars.concentration(),
                 fluxVarCache.gradN(scv.indexInElement())
@@ -233,7 +232,7 @@ public:
     }
     // [[/codeblock]]
 
-    // **Source term:** The function `computeSource` computes the sources terms for a sub control volume.
+    // **Source term:** The function `computeSource` computes the source terms for a sub control volume.
     // We implement a model-specific source term for the chemical potential equation before
     // deferring further implementation to the problem where we add the derivative of the free
     // energy.
@@ -270,7 +269,6 @@ template<class TypeTag>
 struct LocalResidual<TypeTag, TTag::CahnHilliardModel>
 { using type = CahnHilliardModelLocalResidual<TypeTag>; };
 
-// The default scalar type is double.
 // We compute with double precision floating point numbers.
 template<class TypeTag>
 struct Scalar<TypeTag, TTag::CahnHilliardModel>
@@ -278,7 +276,7 @@ struct Scalar<TypeTag, TTag::CahnHilliardModel>
 
 // The model traits specify some information about our equation system.
 // Here we have two equations. The indices allow to access primary variables
-// and equations with a named indices.
+// and equations with named indices.
 template<class TypeTag>
 struct ModelTraits<TypeTag, TTag::CahnHilliardModel>
 {
@@ -298,7 +296,8 @@ struct ModelTraits<TypeTag, TTag::CahnHilliardModel>
 };
 
 // The primary variable vector has entries of type `Scalar` and is
-// as large as the number of equations (here 2) but we keep it general.
+// as large as the number of equations (here 2) but we keep it general
+// here by obtaining the number of equations from the `ModelTraits`.
 template<class TypeTag>
 struct PrimaryVariables<TypeTag, TTag::CahnHilliardModel>
 {