Merge branch 'improve-intro-slides' into 'master'

improve intro slides

See merge request !186

slides/intro.md

@@ -3,17 +3,18 @@ title: Introduction to DuMu^x^
 subtitle: Overview and Available Models
 ---
 
+
 # Table of Contents
 
 ## Table of Contents
 
-1. [History and Structure](#structure-and-development-history)
-2. [Available Models](#available-models)
+1. [Structure and Development History](#structure-and-development-history)
+2. [Mathematical Models](#available-models)
 3. [Spatial Discretization](#spatial-discretization)
 4. [Model Components](#model-components)
 5. [Simulation Flow](#simulation-flow)
 
-# Structure and development history
+# Structure and Development History
 
 ## DuMu^x^ is a DUNE module
 
@@ -47,6 +48,7 @@ subtitle: Overview and Available Models
 ## Applications
 
 * **Successfully applied** to
+
     * gas (CO~2~, H~2~, CH~4~, ...) storage scenarios
     * environmental remediation problems
     * transport of substances in biological tissue
@@ -58,11 +60,11 @@ subtitle: Overview and Available Models
 
 ## DuMu^x^ Modules
 
-* [**dumux-lecture**](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux-lecture): example applications for lectures offered by LH2, Uni Stuttgart
+* [**dumux-lecture**](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux-lecture): example applications for lectures offered by LH^2^, Uni Stuttgart
 * [**dumux-pub/---**](https://git.iws.uni-stuttgart.de/dumux-pub): code and data accompanying a publication (reproduce and archive results)
 * [**dumux-appl/---**](https://git.iws.uni-stuttgart.de/dumux-appl): Various application modules (many not publicly available, e.g. ongoing research)
 
-## Development history
+## Development History
 
 * 01/2007: Development **starts**.
 * 07/2009: Release **1.0**.
@@ -88,7 +90,7 @@ We acknowledge funding that supported the development of DuMu^x^ in past and pre
 ## Downloads and Publications
 
 * More than 1000 unique release **downloads**.
-* More than 200 peer-reviewed **publications** and PhD theses using DuMu^x^
+* More than 200 peer-reviewed [**publications**](https://puma.ub.uni-stuttgart.de/group/dumux/dumuxarticle?resourcetype=publication&items=1000&sortPage=year) and [PhD theses](https://puma.ub.uni-stuttgart.de/group/dumux/dumuxphd?resourcetype=publication&items=1000&sortPage=year) using DuMu^x^.
 
 ## Evolution of C++ Files
 
@@ -135,117 +137,148 @@ Preimplemented models:
 
 * Describes the advective flux in porous media on the macro-scale
 
-* One-phase flow
+* Single-phase flow
 
-    $v = - \frac{\mathbf{K}}{\mu} \left(\textbf{grad}\, p - \varrho \mathbf{g} \right)$
+    $$\mathbf{v} = - \frac{\mathbf{K}}{\mu} \left(\textbf{grad}\, p - \varrho \mathbf{g} \right)$$
 
 * Multi-phase flow (phase $\alpha$)
 
-    $v_\alpha = - \frac{k_{r\alpha}}{\mu_\alpha} \mathbf{K} \left(\textbf{grad}\, p_\alpha - \varrho_\alpha \mathbf{g} \right)$
-    where $k_{r\alpha}(S_\alpha)$ is the relative permeability, a function of saturation $S_\alpha$
+    $$\mathbf{v}_\alpha = - \frac{k_{r\alpha}}{\mu_\alpha} \mathbf{K} \left(\textbf{grad}\, p_\alpha - \varrho_\alpha \mathbf{g} \right)$$
+    where $k_{r\alpha}(S_\alpha)$ is the relative permeability, a function of saturation $S_\alpha$.
+
+* For non-creeping flow, Forchheimer's law is available as an alternative.
 
-## 1p -- single-phase
+## 1p -- Single-Phase
 
-* Uses standard Darcy approach for the conservation of momentum
+* Uses standard Darcy approach for the conservation of momentum by default
 * Mass continuity equation
 
-    $\frac{\partial\left( \phi \varrho \right)}{\partial t} + \text{div} \left\lbrace - \varrho \frac{\textbf{K}}{\mu} \left(\textbf{grad}\, p - \varrho \textbf{g} \right) \right\rbrace = q$
+    $$\frac{\partial\left( \phi \varrho \right)}{\partial t} + \text{div} \left( \varrho \mathbf{v} \right) = q$$
 
 * Primary variable: $p$
 
-## 1pnc -- single-phase, multi-component
+* Further details can be found in the corresponding [documentation](https://dumux.org/docs/doxygen/master/group___one_p_model.html)
+
+## 1pnc -- Single-Phase, Multi-Component
+
+* Uses standard Darcy approach for the conservation of momentum by default
+* Transport of component $\kappa \in \{\text{H2O}, \text{Air}, ...\}$
 
-* Uses standard Darcy approach for the conservation of momentum
-* Transport of component $\kappa \in \{w, a, ...\}$
+    $$\frac{\partial\left( \phi \varrho X^\kappa \right)}{\partial t} + \text{div} \left( \varrho X^\kappa \mathbf{v} - \varrho D^\kappa_\text{pm} \textbf{grad} X^\kappa \right) = q$$
 
-    $\frac{\partial\left( \phi \varrho X^\kappa \right)}{\partial t} - \text{div} \left\lbrace \varrho X^\kappa \frac{\textbf {K}}{\mu} \left(\textbf{grad}\, p - \varrho \textbf{g} \right) + \varrho D^\kappa_\text{pm} \textbf{grad} X^\kappa \right\rbrace = q$
+* Closure relation: $\sum_\kappa X^\kappa = 1$
+* Primary variables: $p$ and $X^\kappa$
 
-* Primary variables: $p$ and $x^\kappa$
+* Further details can be found in the corresponding [documentation](https://dumux.org/docs/doxygen/master/group___one_p_n_c_model.html)
 
-## 1pncmin -- with mineralization
+## 1pncmin -- with Fluid-Solid Phase Change
 
-* Transport equation for each component $\kappa \in \{w, a, ...\}$
+* Transport equation for each component $\kappa \in \{\text{H2O}, \text{Air}, ...\}$
 
-    $\frac{\partial \left( \varrho_f X^\kappa \phi \right)}{\partial t}$
-    $- \text{div} \left\lbrace \varrho_f X^\kappa \frac{k_{r}}{\mu} \mathbf{K} \left(\textbf{grad}\, p - \varrho_f \mathbf{g} \right) \right\rbrace$
-    $- \text{div} \left\lbrace \mathbf{D_{pm}^\kappa} \varrho_f \textbf{grad}\, X^\kappa \right\rbrace = q_\kappa$
+    $$\frac{\partial \left( \varrho_f X^\kappa \phi \right)}{\partial t}
+    + \text{div} \left( \varrho_f X^\kappa \mathbf{v} - \mathbf{D_\text{pm}^\kappa} \varrho_f \textbf{grad}\, X^\kappa \right) = q_\kappa$$
 
-* Mass balance solid or mineral phases
+* Mass balance solid phases
 
-    $\frac{\partial \left(\varrho_\lambda \phi_\lambda \right)}{\partial t} = q_\lambda$
+    $$\frac{\partial \left(\varrho_\lambda \phi_\lambda \right)}{\partial t} = q_\lambda$$
 
-* Primary variables: $p$, $x^k$ and $\phi_\lambda$
+* Primary variables: $p$, $X^k$ and $\phi_\lambda$
 
-## 2p -- two-phase
+* Further details can be found in the corresponding [documentation](https://dumux.org/docs/doxygen/master/group___one_p_n_c_min_model.html)
 
-* Uses standard multi-phase Darcy approach for the conservation of momentum
-* Conservation of the phase mass of phase $\alpha \in \{w, n\}$
+## 2p -- Two-Phase Immiscible
 
-    $\frac{\partial \left( \phi \varrho_\alpha S_\alpha \right)}{\partial t} - \text{div} \left\{\varrho_\alpha \frac{k_{r\alpha}}{\mu_\alpha} \mathbf{K} \left(\textbf{grad}\, p_\alpha - \varrho_\alpha \mathbf{g} \right) \right\} = q_\alpha$
+* Uses standard multi-phase Darcy approach for the conservation of momentum by default
+* Conservation of the phase mass of phase $\alpha \in \{\text{w}, \text{n}\}$
 
-* Constitutive relation: $p_c := p_n - p_w = p_c(S_w)$, $k_{r\alpha}$ = $k_{r\alpha}(S_w)$
-* Physical constraint (no free space): $S_w + S_n = 1$
-* Primary variables: $p_w$, $S_n$ or $p_n$, $S_w$
+    $$\frac{\partial \left( \phi \varrho_\alpha S_\alpha \right)}{\partial t} + \text{div} \left(\varrho_\alpha \mathbf{v}_\alpha \right) = q_\alpha$$
 
-## 2pnc
+* Constitutive relations: $p_\text{c} := p_\text{n} - p_\text{w} = p_\text{c}(S_\text{w})$, $k_{r\alpha}$ = $k_{r\alpha}(S_\text{w})$
+* Physical constraint (void space filled with fluid phases): $S_\text{w} + S_\text{n} = 1$
+* Primary variables: $p_\text{w}$, $S_\text{n}$ or $p_\text{n}$, $S_\text{w}$
 
-* Transport equation for each component $\kappa \in \{w, n, ...\}$ in phase $\alpha \in \{w, n\}$
+* Further details can be found in the corresponding [documentation](https://dumux.org/docs/doxygen/master/group___two_p_model.html)
 
-    $\begin{aligned}\frac{\partial \left( \sum_\alpha \varrho_\alpha X_\alpha^\kappa \phi S_\alpha \right)}{\partial t} &- \sum_\alpha \text{div} \left\lbrace \varrho_\alpha X_\alpha^\kappa \frac{k_{r\alpha}}{\mu_\alpha} \mathbf{K} \left( \textbf{grad}\, p_\alpha - \varrho_\alpha \mathbf{g} \right) \right\rbrace \\
-    &- \sum_\alpha \text{div} \left\lbrace \mathbf{D_{\alpha, pm}^\kappa} \varrho_\alpha \textbf{grad}\, X^\kappa_\alpha \right\rbrace = \sum_\alpha q_\alpha^\kappa \end{aligned}$
+## 2pnc -- Two-Phase Compositional
 
-* Constitutive relation: $p_c := p_n - p_w = p_c(S_w)$, $k_{r\alpha}$ = $k_{r\alpha}(S_w)$
-* Physical constraints: $S_w + S_n = 1$ and $\sum_\kappa X_\alpha^\kappa = 1$
+* Transport equation for each component $\kappa \in \{\text{H2O}, \text{Air}, ...\}$ in phase $\alpha \in \{\text{w}, \text{n}\}$
+
+    $$\begin{aligned}\frac{\partial \left( \sum_\alpha \varrho_\alpha X_\alpha^\kappa \phi S_\alpha \right)}{\partial t} &+ \sum_\alpha \text{div} \left( \varrho_\alpha X_\alpha^\kappa \mathbf{v}_\alpha - \mathbf{D_{\alpha, pm}^\kappa} \varrho_\alpha \textbf{grad}\, X^\kappa_\alpha \right) = \sum_\alpha q_\alpha^\kappa \end{aligned}$$
+
+* Constitutive relation: $p_\text{c} := p_\text{n} - p_\text{w} = p_\text{c}(S_\text{w})$, $k_{r\alpha}$ = $k_{r\alpha}(S_\text{w})$
+* Physical constraints: $S_\text{w} + S_\text{n} = 1$ and $\sum_\kappa X_\alpha^\kappa = 1$
 * Primary variables: depending on the phase state
 
+* Further details can be found in the corresponding [documentation](https://dumux.org/docs/doxygen/master/group___two_p_n_c_model.html)
+
 ## 2pncmin
 
-* Transport equation for each component $\kappa \in \{w, n, ...\}$ in phase $\alpha \in \{w, n\}$
+* Transport equation for each component $\kappa \in \{\text{H2O}, \text{Air}, ...\}$
+
+    $$\begin{aligned}\frac{\partial \left( \sum_\alpha \varrho_\alpha X_\alpha^\kappa \phi S_\alpha \right)}{\partial t} &+ \sum_\alpha \text{div} \left( \varrho_\alpha X_\alpha^\kappa \mathbf{v}_\alpha - \mathbf{D_{\alpha, pm}^\kappa} \varrho_\alpha \textbf{grad}\, X^\kappa_\alpha \right) = \sum_\alpha q_\alpha^\kappa \end{aligned}$$
+
+* Mass balance solid phases
 
-    $\begin{aligned}\frac{\partial \left( \sum_\alpha \varrho_\alpha X_\alpha^\kappa \phi S_\alpha \right)}{\partial t} &- \sum_\alpha \text{div} \left\lbrace \varrho_\alpha X_\alpha^\kappa \frac{k_{r\alpha}}{\mu_\alpha} \mathbf{K} \left( \textbf{grad}\, p_\alpha - \varrho_\alpha \mathbf{g} \right) \right\rbrace \\
-    &- \sum_\alpha \text{div} \left\lbrace \mathbf{D_{\alpha, pm}^\kappa} \varrho_\alpha \textbf{grad}\, X^\kappa_\alpha \right\rbrace = \sum_\alpha q_\alpha^\kappa \end{aligned}$
+    $$\frac{\partial \left(\varrho_\lambda \phi_\lambda \right)}{\partial t} = q_\lambda \quad \forall \lambda \in \Lambda$$
+for a set of solid phases $\Lambda$ each with volume fraction $\varrho_\lambda$
 
-* Mass balance solid or mineral phases
+* Source term models **dissolution/precipiation/phase transition** fluid ↔ solid
 
-    $\frac{\partial \left(\varrho_\lambda \phi_\lambda \right)}{\partial t} = q_\lambda \quad \forall \lambda \in \Lambda$
+* Further details can be found in the corresponding [documentation](https://dumux.org/docs/doxygen/master/group___two_p_n_c_min_model.html)
 
-* for a set of solid phases $\Lambda$ each with volume fraction $\varrho_\lambda$
-* source term models **dissolution** / **precipiation** / **phase transition** fluid ↔ solid
+## 3p -- Three-Phase Immiscible
 
-## 3p -- three-phase
+* Uses standard multi-phase Darcy approach for the conservation of momentum by default
+* Conservation of the phase mass of phase $\alpha \in \{\text{w}, \text{g}, \text{n}\}$
 
-* Uses standard multi-phase Darcy approach for the conservation of momentum
-* Conservation of the phase mass of phase $\alpha \in \{w, g, n\}$
+    $$\frac{\partial \left( \phi \varrho_\alpha S_\alpha \right)}{\partial t} - \text{div} \left( \varrho_\alpha \mathbf{v}_\alpha \right) = q_\alpha$$
 
-    $\frac{\partial \left( \phi \varrho_\alpha S_\alpha \right)}{\partial t} - \text{div} \left\lbrace \varrho_\alpha \frac{k_{r\alpha}}{\mu_\alpha} \mathbf{K} \left(\textbf{grad}\, p_\alpha - \varrho_\alpha \mathbf{g} \right) \right\rbrace = q_\alpha$
+* Physical constraint: $S_\text{w} + S_\text{n} + S_g = 1$
+* Primary variables: $p_\text{g}$, $S_\text{w}$, $S_\text{n}$
 
-* Physical constraint: $S_w + S_n + S_g = 1$
-* Primary variables: $p_g$, $S_w$, $S_n$
+* Further details can be found in the corresponding [documentation](https://dumux.org/docs/doxygen/master/group___three_p_model.html)
 
-## 3p3c
+## 3p3c -- Three-Phase Compositional
 
-* Transport equation for each component $\kappa \in \{w, a, c\}$ in phase $\alpha \in \{w, g, n\}$
+* Transport equation for each component $\kappa \in \{\text{H2O}, \text{Air}, \text{NAPL}\}$ in phase $\alpha \in \{\text{w}, \text{g}, \text{n}\}$
 
-    $\begin{aligned}\frac{\partial \left( \phi \sum_\alpha \varrho_{\alpha,mol} x_\alpha^\kappa S_\alpha \right)}{\partial t}
-    &- \sum_\alpha \text{div} \left\lbrace \frac{k_{r\alpha}}{\mu_\alpha} \varrho_{\alpha,mol} x_\alpha^\kappa \mathbf{K} \left(\textbf{grad}\, p_\alpha - \varrho_{\alpha,mass} \mathbf{g} \right) \right\rbrace \\
-    &- \sum_\alpha \text{div} \left\lbrace D_\text{pm}^\kappa \frac{1}{M_\kappa} \varrho_\alpha \textbf{grad} X^\kappa_{\alpha} \right\rbrace = q^\kappa \end{aligned}$
+    $$\begin{aligned}\frac{\partial \left( \phi \sum_\alpha \varrho_{\alpha,\text{mol}} x_\alpha^\kappa S_\alpha \right)}{\partial t}
+    &+ \sum_\alpha \text{div} \left( \varrho_{\alpha,\text{mol}} x_\alpha^\kappa \mathbf{v}_\alpha - D_\text{pm}^\kappa \frac{1}{M_\kappa} \varrho_\alpha \textbf{grad} X^\kappa_{\alpha} \right) = q^\kappa \end{aligned}$$
 
 * Physical constraints: $\sum_\alpha S_\alpha = 1$ and $\sum_\kappa x^\kappa_\alpha = 1$
 * Primary variables: depend on the locally present fluid phases
 
-## Non-Isothermal (equilibrium)
+* Further details can be found in the corresponding [documentation](https://dumux.org/docs/doxygen/master/group___three_p_three_c_model.html)
+
+## Other Porous-Medium Flow Models
+
+* For other porous-medium flow models, we refer to the Doxygen documentation:
+
+    - [2p1c](https://dumux.org/docs/doxygen/master/group___two_p_one_c_model.html)
+    - [2p2c](https://dumux.org/docs/doxygen/master/group___two_p_two_c_model.html)
+    - [3pwateroil](https://dumux.org/docs/doxygen/master/group___three_p_water_oil_model.html)
+    - [co2](https://dumux.org/docs/doxygen/master/group___c_o2_model.html)
+    - [mpnc](https://dumux.org/docs/doxygen/master/group___m_p_n_c_model.html)
+    - [nonequilibrium](https://dumux.org/docs/doxygen/master/group___non_equilibrium_model.html)
+    - [richards](https://dumux.org/docs/doxygen/master/group___richards_model.html)
+    - [richardsnc](https://dumux.org/docs/doxygen/master/group___richards_n_c_model.html)
+    - [tracer](https://dumux.org/docs/doxygen/master/group___tracer_model.html)
+
+## Non-Isothermal (Equilibrium)
 
 * Local thermal equilibrium assumption
 * One energy conservation equation for the porous solid matrix and the fluids
 
-    $\begin{aligned}\frac{\partial \left( \phi \sum_\alpha \varrho_\alpha u_\alpha S_\alpha \right)}{\partial t} &+ \frac{\partial \left(\left(1 - \phi \right)\varrho_s c_s T \right)}{\partial t} \\
-    &- \sum_\alpha \text{div} \left\lbrace \varrho_\alpha h_\alpha \frac{k_{r\alpha}}{\mu_\alpha} \mathbf{K} \left(\textbf{grad}\, p_\alpha - \varrho_\alpha \mathbf{g} \right) \right\rbrace \\
-    &- \text{div} \left(\lambda_{pm} \textbf{grad}\, T \right) = q^h \end{aligned}$
+    $$\begin{aligned}\frac{\partial \left( \phi \sum_\alpha \varrho_\alpha u_\alpha S_\alpha \right)}{\partial t} &+ \frac{\partial \left(\left(1 - \phi \right)\varrho_s c_s T \right)}{\partial t}
+    + \sum_\alpha \text{div} \left( \varrho_\alpha h_\alpha \mathbf{v}_\alpha \right)
+    - \text{div} \left(\lambda_\text{pm} \textbf{grad}\, T \right) = q^h \end{aligned}$$
+
+* Specific internal energy $u_\alpha = h_\alpha - p_\alpha / \varrho_\alpha$
+* Can be added to other models, additional primary variable temperature $T$
 
-* specific internal energy $u_\alpha = h_\alpha - p_\alpha / \varrho_\alpha$
-* can be added to other models, additional primary variable temperature $T$
+* Further details can be found in the corresponding [documentation](https://dumux.org/docs/doxygen/master/group___n_i_model.html)
 
-## Free flow (Navier-Stokes)
+## Free Flow (Navier-Stokes)
 
 * Stokes equation
 * Navier-Stokes equations
@@ -255,16 +288,26 @@ Preimplemented models:
 
 * Momentum balance equation for a single-phase, isothermal RANS model
 
-    $\frac{\partial \left(\varrho \textbf{v} \right)}{\partial t} + \nabla \cdot \left(\varrho \textbf{v} \textbf{v}^{\text{T}} \right) = \nabla \cdot \left(\mu_\textrm{eff} \left(\nabla \textbf{v} + \nabla \textbf{v}^{\text{T}} \right) \right)$
-    $- \nabla p + \varrho \textbf{g} - \textbf{f}$
+    $$\frac{\partial \left(\varrho \textbf{v} \right)}{\partial t} + \nabla \cdot \left(\varrho \textbf{v} \textbf{v}^{\text{T}} \right) = \nabla \cdot \left(\mu_\textrm{eff} \left(\nabla \textbf{v} + \nabla \textbf{v}^{\text{T}} \right) \right)
+    - \nabla p + \varrho \textbf{g} - \textbf{f}$$
 
 * The effective viscosity is composed of the fluid and the eddy viscosity
 
-    $\mu_\textrm{eff} = \mu + \mu_\textrm{t}$
+    $$\mu_\textrm{eff} = \mu + \mu_\textrm{t}$$
 
 * Various turbulence models are implemented
 
-## Your model equations?
+* More details can be found in the [Doxygen documentation](https://dumux.org/docs/doxygen/master/group___freeflow_models.html)
+
+## Other Models
+
+* For other models, we refer to the Doxygen documentation:
+
+    - [Shallow water](https://dumux.org/docs/doxygen/master/group___shallow_water_models.html)
+    - [Geomechanics](https://dumux.org/docs/doxygen/master/group___geomechanics_models.html)
+    - [Pore network](https://dumux.org/docs/doxygen/master/group___pore_network_models.html)
+
+## Your Model Equations?
 
 # Spatial Discretization
 
@@ -285,7 +328,7 @@ Preimplemented models:
 
 <img src="img/mpfa.png" width="80%"/>
 
-## Control-volume finite element methods
+## Control-Volume Finite Element Methods
 
 * Model domain is discretized using a **FE** mesh
 * Secondary **FV** mesh is constructed &rarr; control volume/**box**
@@ -295,21 +338,21 @@ Preimplemented models:
     * **Unstructured grids** (from FE method)
     * **Mass conservation** (from FV method)
 
-## Box method
+## Box Method
 
 Vertex-centered finite volumes / control volume finite element
 method with piecewise linear polynomial functions ($\mathrm{P}_1/\mathrm{Q}_1$)
 
 <img src="img/box.png" width="70%"/>
 
-## Finite Volume method on staggered grid
+## Finite Volume Method on Staggered Control Volumes
 
 * Uses a finite volume method with different staggered control volumes for different equations
 * Fluxes are evaluated with a two-point flux approximation
 * **Robust** and **mass conservative**
 * Restricted to **structured grids** (tensor-product structure)
 
-## Staggered grid discretization
+## Staggered Grid Discretization
 
 <img src="img/staggered_grid.png"/>