intro.md

---
title: Introduction to DuMu^x^
subtitle: Overview and Available Models
---

# Table of Contents

## Table of Contents

1. [History and Structure](#history-and-structure)
2. [Available Models](#available-models)
3. [Spatial Discretization](#spatial-discretization)
4. [Model Components](#model-components)
5. [Simulation Flow](#simulation-flow)

# History and Structure

## The DuMu^x^ Development Team (IWS-LH2)

<img src="img/lh2_2021.jpg" width="600"/>

## DuMu^x^ is a DUNE module

<img src="img/dumux_dune_module.png"/>

## The DUNE Framework

* **Developed** by scientists at around 10 European research institutions.
* **Separation** of data structures and algorithms by abstract interfaces.
* Efficient implementation using **generic** programming techniques.
* **Reuse** of existing FE packages with a large body of functionality.
* Current stable release: **2.9** (November 2022).

## DUNE Core Modules

* **dune-common:** basic classes
* **dune-geometry:** geometric entities
* **dune-grid:** abstract grid/mesh interface
* **dune-istl:** iterative solver template library
* **dune-localfunctions:** finite element shape functions

## Overview

<img src="img/dumux.png" width="400"/>

* **DuMu^x^:** DUNE for Multi-{Phase, Component, Scale, Physics, $\text{...}$} flow and transport in porous media.
* **Goal:** **sustainable** and **consistent framework** for the implementation and application of **model concepts** and **constitutive relations**.
* Meanwhile **developed** by more than 30 PhD students and post docs, mostly at LH2.

## Application

* **Successfully applied** to
    * gas (CO~2~, H~2~, CH~4~, ...) storage scenarios
    * environmental remediation problems
    * transport of therapeutic agents through biological tissue
    * root-soil interaction
    * subsurface-atmosphere coupling (Navier-Stokes / Darcy)
    * pore-network modelling
    * flow and transport in fractured porous media

## Exemplary DuMu^x^ Modules

* **dumux-lecture:** example applications for lectures offered by LH2 in Stuttgart
* **dumux-pub:** accompany a publication with all code and data to reproduce the results
* **dumux-appl:** current unpublished development and ongoing research

## History

* 01/2007: Development **starts**.
* 07/2009: Release **1.0**.
* 09/2010: **Split** into stable and development part.
* 12/2010: Anonymous **read access** to the **SVN** trunk of the stable part.
* 02/2011: Release **2.0,** ..., 10/2017: Release **2.12**.
* 09/2015: Transition from Subversion to **Git**.
* 12/2018: Release **3.0,** ..., 03/2023: Release **3.7**.

## Downloads and Publications

* More than 1000 "real" and unique release **downloads**.
* More than 200 peer-reviewed **publications** and PhD theses.

## Evolution of C++ Files

<img src="img/files_vs_releases.png" width="750"/>

## Evolution of Code Lines

<img src="img/lines_vs_releases.png" width="750"/>

## Mathematical Models

* **Porous medium flow (Darcy)**: Single and multi-phase models for flow and transport in porous materials.
* **Free flow (Navier-Stokes)**: Single-phase models based on the Navier-Stokes equation.
* **Shallow water flow**: Two-dimensional shallow water flow (depth-averaged).
* **Geomechanics**: Models taking into account solid deformation.
* **Pore network**: Single and multi-phase models for flow and transport in pore networks.

## Mailing Lists and GitLab

* **Mailing lists** of DUNE (<dune@dune-project.org>) and DuMu^x^ (<dumux@listserv.uni-stuttgart.de>)
* Get **GitLab** accounts (non-anonymous) for better access
    * DUNE GitLab (<https://gitlab.dune-project.org/core>)
    * DuMu^x^ GitLab (<https://git.iws.uni-stuttgart.de/dumux-repositories/dumux>)
* GitLab **Issue Tracker** (<https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/issues>)

## Documentation

* **Doxygen** code **documentation** of
    * DUNE (<https://dune-project.org/doxygen/>)
    * DuMu^x^ (<https://dumux.org/docs/>)
* DuMu^x^ **Handbook** (<https://dumux.org/docs/>)
* Further information &rarr; <https://dumux.org/>

# Available Models

## Available Models

<img src="img/models.png" width="650"/>

## Darcy's law

* Describes the advective flux in porous media on the macro-scale

* One-phase flow

    $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)$

## 1p -- single-phase

* Uses standard Darcy approach for the conservation of momentum
* Mass continuity equation

    $\phi \frac{\partial \varrho}{\partial t} + \text{div} \left\lbrace - \varrho \frac{\textbf{K}}{\mu} \left(\textbf{grad}\, p - \varrho \textbf{g} \right) \right\rbrace = q$

* Primary variable: $p$

## 1pnc -- single-phase, multi-component

* Uses standard Darcy approach for the conservation of momentum
* Transport of component $\kappa \in \{w, a, ...\}$

    $\phi \frac{\partial \varrho X^\kappa}{\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$

* Primary variables: $p$ and $x^\kappa$

## 1pncmin -- with mineralization

* Transport equation for each component $\kappa \in \{w, a, ...\}$

    $\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$

* Mass balance solid or mineral phases

    $\frac{\partial \left(\varrho_\lambda \phi_\lambda \right)}{\partial t} = q_\lambda$

* Primary variables: $p$, $x^k$ and $\phi_\lambda$

## 2p -- two-phase

* Uses standard multi-phase Darcy approach for the conservation of momentum
* Conservation of the phase mass of phase $\alpha \in \{w, n\}$

    $\phi \frac{\partial \varrho_\alpha S_\alpha}{\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$

* Constitutive relation $p_c = p_n - p_w$
* $S_w + S_n = 1$
* Primary variables: $p_w$ and $S_n$ or $p_n$ and $S_w$

## 2pnc

* Transport equation for each component $\kappa \in \{w, n, ...\}$ in phase $\alpha \in \{w, n\}$

    $\frac{\partial \sum_\alpha \varrho_\alpha X_\alpha^\kappa \phi S_\alpha}{\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$

* Constitutive relation $p_c = p_n - p_w$
* $S_w + S_n = 1$ and $X^\kappa_w + X^\kappa_n = 1$
* Primary variables: depend on the phase state

## 2pncmin

* Transport equation for each component $\kappa \in \{w, n, ...\}$ in phase $\alpha \in \{w, n\}$

    $\frac{\partial \sum_\alpha \varrho_\alpha X_\alpha^\kappa \phi S_\alpha}{\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$

* Mass balance solid or mineral phases

    $\frac{\partial \left(\varrho_\lambda \phi_\lambda \right)}{\partial t} = q_\lambda$

* $p_c = p_n - p_w$, $S_w + S_n = 1$ and $X^\kappa_w + X^\kappa_n = 1$
* Primary variables: depend on the phase state

## 3p -- three-phase

* Uses standard multi-phase Darcy approach for the conservation of momentum
* Conservation of the phase mass of phase $\alpha \in \{w, g, n\}$

    $\phi \frac{\partial \varrho_\alpha S_\alpha}{\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$

* $S_w + S_n + S_g = 1$
* Primary variables: $p_g$, $S_w$ and $S_n$

## 3p3c

* Transport equation for each component $\kappa \in \{w, a, c\}$ in phase $\alpha \in \{w, g, n\}$

    $\phi \frac{\partial \left(\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$

* $S_w + S_n + S_g = 1$ and $x^w_\alpha + x^a_\alpha + x^c_\alpha = 1$
* Primary variables: depend on the locally present fluid phases

## Non-Isothermal

* Local thermal equilibrium is assumed

* One energy conservation equation for the porous solid matrix and the fluids

    $\phi \frac{\partial \sum_\alpha \varrho_\alpha u_\alpha S_\alpha}{\partial t} + \left(1 - \phi \right) \frac{\partial \left(\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$

* $u_\alpha = h_\alpha - p_\alpha / \varrho_\alpha$

## Reynolds-Averaged Navier-Stokes (RANS)

* 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}$

* The effective viscosity is composed of the fluid and the eddy viscosity

    $\mu_\textrm{eff} = \mu + \mu_\textrm{t}$

# Spatial Discretization

## Cell Centered Finite Volume Methods

* Use elements of the grid as control volumes
* Discrete **values** are determined at the element/control volume **center**
* **Two-point flux approximation (TPFA)**
    * Simple but robust
* **Multi-point flux approximation (MPFA)**
    * A consistent discrete gradient is constructed

## Two-Point Flux Approximation (TPFA)

<img src="img/tpfa.png" width="75%"/>

## Multi-Point Flux Approximation (MPFA)

<img src="img/mpfa.png" width="80%"/>

## Box method

* Model domain is discretized using a **FE** mesh
* Secondary **FV** mesh is constructed &rarr; control volume/**box**
* Control volumes are partitioned into sub-control volumes (scvs)
* Faces of control volumes are partitioned into sub-control volume faces (scvfs)
* Unites advantages of finite-volume and finite-element methods
    * **Unstructured grids** (from FE method)
    * **Mass conservative** (from FV method)

## Box method

<img src="img/box.png"/>

## Staggered Grid

* Uses a finite volume method with different control volumes for different equations
* Fluxes are evaluated with a two-point flux approximation
* **Robust** and **mass conservative**
* Should be applied for **structured grids** only

## Staggered Grid

<img src="img/staggered_grid.png"/>

# Model Components

## Model Components

* The following components have to be specified
    * **Solver**: Type of solution stategy
    * **Assembler**: Key properties
        * Geometry, Variables, LocalResidual
    * **LinearSolver**: How to solve algebraic equations
    * **Problem**: Initial and boundary conditions
    * **SolutionVector**: Container to store the solution
    * **TimeLoop**: For time-dependent problems
    * **IOFields** and **VtkOutputModule**: Output of the simulation

# Simulation Flow

## Simulation Flow

<img src="img/simulation_flow.png"/>