Merge branch 'doc/ex-model-updates' into 'master'

Doc/ex model updates

See merge request !162

slides/index.md

@@ -4,5 +4,6 @@ title: DuMuX Course Slides
 
 - [Introduction to DuMu^x^](./intro.html)
 - [Property System](./properties.html)
+- [Model](./model.html)
 - [Introduction to Multidomain](./multidomain.html)
 - [Discrete Fracture Modeling](./fractures.html)

slides/model.md

 ---
-title: Models in DuMux
+title: Models in DuMuX
 ---
 
 # Implementing a new DuMu<sup>X</sup> model
 
 ## What is a DuMu<sup>X</sup> model
-A DuMu<sup>X</sup> model is an implementation of a **mathematical model**, generally given by partial differential equations, by using **discretization** schemes.
+A DuMu<sup>X</sup> model is an implementation of a discretized **mathematical model**, generally given by partial differential equations.
 
 ## What is a DuMu<sup>X</sup> model
 Mathematical model (PDE):
@@ -29,8 +29,8 @@ $\begin{equation*}
 |B| \frac{S_h(\mathbf{u}^{n+1}_h) - S_h(\mathbf{u}^{n}_h)}{\Delta t}  + \sum_{\sigma \in \Sigma_B} F_{B,\sigma}(\mathbf{u}^{n+1}_h) = \int_{B}  q \, dx, \quad \forall t_{n+1}\leq T, \; \forall B
 \end{equation*}$
 
-* $S_h$: storage calculation
-* $F_{B,\sigma}$: flux over sub control volume face
+* $S_h$: storage term
+* $F_{B,\sigma}$: flux term over sub control volume face (scvf)
 * $q$ source term
 
 How to implement these terms in DuMu<sup>X</sup>?
@@ -75,31 +75,31 @@ with
 
 $\begin{aligned}
     c_B^n: &\:\text{concentration at time $t_n$ and control volume $B$} \\
-    c_h: &\:\text{global discrete solution, interpolation using \textbf{basis functions}} \\
+    c^n_h: &\:\text{global discrete solution at time $t_n$, interpolated using \textbf{basis functions}} \\
     \mathbf{n}: &\:\text{unit outer normal vector} \\
-    \sigma: &\:\text{sub control volume face} \\
+    \sigma: &\:\text{sub control volume face (scvf)} \\
 \end{aligned}$
 
+## Example: Diffusion equation
+Discrete model using the Box discretization:
 
-## Local residual
-The local residual of the diffusion model:
-```cpp
-namespace Dumux {
-template<class TypeTag>
-class DiffusionModelLocalResidual
-: public GetPropType<TypeTag, Properties::BaseLocalResidual>
-{
-```
+$\begin{equation}
+\vert B \vert \frac{c_B^{n+1}-c_B^{n}}{\Delta t} - \sum_{\sigma \in \Sigma_{B}} \left[ D \nabla c_h^{n+1} \cdot \boldsymbol{n}_{B,\sigma} \vert \sigma \vert \right] = 0,
+\end{equation}$
+
+<img src=img/box_scv_scvf.png width="90%">
 
 ## Local residual
+The local residual of the diffusion model:
 ```cpp
-namespace Dumux {
 template<class TypeTag>
 class DiffusionModelLocalResidual
 : public GetPropType<TypeTag, Properties::BaseLocalResidual>
 {
+    ...
+}
 ```
-Our class inherits from the class `BaseLocalResidual`, which has to be chosen depending on the discretization scheme, here *Box scheme*.
+Inherits from the `BaseLocalResidual`, which is chosen depending on the discretization scheme, here *Box scheme*.
 
 ## Storage term
 ```cpp
@@ -107,10 +107,10 @@ NumEqVector computeStorage(const Problem& problem,
 						   const SubControlVolume& scv,
 						   const VolumeVariables& volVars) const
  {
-	 NumEqVector storage;
-     storage[Indices::massBalanceEqIdx]
+    NumEqVector storage;
+    storage[Indices::massBalanceEqIdx]
         = volVars.priVar(Indices::concentrationIdx);
-     return storage;
+    return storage;
  }
 ```
 
@@ -123,29 +123,29 @@ F_{B,\sigma} = -D \nabla c_h^{n+1} \cdot \boldsymbol{n}_{B,\sigma} \vert \sigma
 with
 
 $\begin{aligned}
-    c_h: &\:\text{discrete solution, interpolated using basis functions} \\
-    \sigma: &\:\text{sub control volume face} \\
+    c^n_h: &\:\text{global discrete solution at time $t_n$, interpolated using \textbf{basis functions}} \\
+    \mathbf{n}: &\:\text{unit outer normal vector} \\
+    \sigma: &\:\text{sub control volume face (scvf)} \\
 \end{aligned}$
 
 ## Flux term
-Implementation takes place in the dedicated function `computeFlux`:
 ```cpp
- NumEqVector computeFlux(const Problem& problem,
-                         const Element& element,
-                         const FVElementGeometry& fvGeometry,
-                         const ElementVolumeVariables& elemVolVars,
-                         const SubControlVolumeFace& scvf,
-                         const ElementFluxVariablesCache& elemFluxVarsCache) const
- {
+NumEqVector computeFlux(const Problem& problem,
+                        const Element& element,
+                        const FVElementGeometry& fvGeometry,
+                        const ElementVolumeVariables& elemVolVars,
+                        const SubControlVolumeFace& scvf,
+                        const ElementFluxVariablesCache& elemFluxVarsCache) const
+{
     ...
+}
 ```
 
 ## Flux term
-Implementation takes place in the dedicated function `computeFlux`:
 ```cpp
- NumEqVector computeFlux(...) const
- {
-	 // Compute ∇c
+NumEqVector computeFlux(...) const
+{
+    // Compute ∇c
     const auto& fluxVarCache = elemFluxVarsCache[scvf];
     Dune::FieldVector<Scalar, dimWorld> gradConcentration(0.0);
     for (const auto& scv : scvs(fvGeometry))
@@ -157,14 +157,13 @@ Implementation takes place in the dedicated function `computeFlux`:
         );
     }
     ...
- }
+}
 ```
 
 ## Flux term
-Implementation takes place in the dedicated function `computeFlux`:
 ```cpp
- NumEqVector computeFlux(...) const
- {
+NumEqVector computeFlux(...) const
+{
     ...
     NumEqVector flux;
 
@@ -174,13 +173,12 @@ Implementation takes place in the dedicated function `computeFlux`:
     )*scvf.area();
 
     return flux;
-
- }
+}
 ```
 
 ## Local Residual
 
-A *local residual* implements the discretized mathematical model.
+A **local residual** implements the discretized mathematical model.
 
 For its implementation different model-specific properties have to be set
 
@@ -197,12 +195,12 @@ struct DiffusionModel {};
 } // end namespace Dumux::Properties::TTag
 ```
 ## Model properties
-By specializing properties for the type tag `DiffusionModel`, every other class that knows about the type tag (this will be for example the assembler or the problem), can extract the type information that we specify here.
+We can set nodel properties for the `DiffusionModel` type tag
 
 All properties are defined within the namespace `Dumux::Properties`
 ```cpp
 namespace Dumux::Properties {
-  //define all properties
+    //define all properties
 } // end namespace Dumux::Properties
 ```