intro.md

---
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)
3. [Spatial Discretization](#spatial-discretization)
4. [Model Components](#model-components)
5. [Simulation Flow](#simulation-flow)

# Structure and development history

## 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="300"/>

* **DuMu^x^:** DUNE for Multi-{Phase, Component, Scale, Physics, $\text{...}$} flow and transport in porous media.
* **Goal:** **sustainable, consistent, research-friendly framework** for the implementation and application of
**FV discretization schemes**, **model concepts**, and **constitutive relations**.
* **Developed** by more than 30 PhD students and post docs, mostly at LH^2^ (Uni Stuttgart).

## Applications

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

## 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-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

* 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**.

## Funding

Efforts mainly funded through ressources at the LH^2^: [Department of Hydromechanics and Modelling of Hydrosystems at the University of Stuttgart](https://www.iws.uni-stuttgart.de/en/lh2/)
and third-party funding aquired at the LH^2^

<img src="img/lh2.jpeg" width="300"/>

## Funding

We acknowledge funding that supported the development of DuMu^x^ in past and present:

<img src="img/funding.svg" width="550"/>

## Downloads and Publications

* More than 1000 unique release **downloads**.
* More than 200 peer-reviewed **publications** and PhD theses using DuMu^x^

## Evolution of C++ Files

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

## Evolution of Code Lines

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

## Mailing Lists and GitLab

* **Mailing lists** of DUNE (<dune@dune-project.org>) and DuMu^x^ (<dumux@listserv.uni-stuttgart.de>)
* GitLab **Issue Tracker** (<https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/issues>)
* 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>)

## Documentation

* Code **documentation**
    * DuMu^x^ (<https://dumux.org/docs/doxygen/master/>)
    * DUNE (<https://dune-project.org/doxygen/>)
* DuMu^x^ **Handbook** (<https://dumux.org/docs/#handbook>)
* DuMu^x^ **Examples** (<https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/-/tree/master/examples#examples>)
* DuMu^x^ **Website** (<https://dumux.org/>)

# Mathematical Models

## Mathematical Models

Preimplemented models:

* **Flow in porous media (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 equations.
* **Shallow water flow**: Two-dimensional shallow water flow (depth-averaged).
* **Geomechanics**: Models taking into account solid deformation of porous materials.
* **Pore network**: Single and multi-phase models for flow and transport in pore networks.

## Flow in Porous Media

<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)$
    where $k_{r\alpha}(S_\alpha)$ is the relative permeability, a function of saturation $S_\alpha$

## 1p -- single-phase

* Uses standard Darcy approach for the conservation of momentum
* 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$

* Primary variable: $p$

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

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

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

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

## 2pnc

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

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

* 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$
* Primary variables: depending on the phase state

## 2pncmin

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

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

* Mass balance solid or mineral phases

    $\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$
* source term models **dissolution** / **precipiation** / **phase transition** fluid &harr; solid

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

    $\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_w + S_n + S_g = 1$
* Primary variables: $p_g$, $S_w$, $S_n$

## 3p3c

* Transport equation for each component $\kappa \in \{w, a, c\}$ in phase $\alpha \in \{w, g, 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}$

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

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

* specific internal energy $u_\alpha = h_\alpha - p_\alpha / \varrho_\alpha$
* can be added to other models, additional primary variable temperature $T$

## Free flow (Navier-Stokes)

* Stokes equation
* Navier-Stokes equations
* Energy and component transport

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

* Various turbulence models are implemented

## Your model equations?

# Spatial Discretization

## Cell-centered Finite Volume Methods

* Elements of the grid are used as control volumes
* Discrete **values** represent control volume average
* **Two-point flux approximation (TPFA)**
    * Simple and robust but not always consistent
* **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%"/>

## Control-volume finite element methods

* Model domain is discretized using a **FE** mesh
* Secondary **FV** mesh is constructed &rarr; control volume/**box**
* Control volumes (CV) split into sub control volumes (SCVs)
* Faces of CV split into sub control volume faces (SCVFs)
* Unites advantages of finite-volume (simplicity) and finite-element methods (flexibility)
    * **Unstructured grids** (from FE method)
    * **Mass conservation** (from FV 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

* 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

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

# Model Components

## Model Components

* Typically, the following components have to be specified
    * **Model**: Equations and constitutive models
    * **Assembler**: Key properties (Discretization, Variables, LocalResidual)
    * **Solver**: Type of solution stategy (e.g. Newton)
    * **LinearSolver**: Method for solving linear equation systems (e.g. direct / Krylov subspace methods)
    * **Problem**: Initial and boundary conditions, source terms
    * **TimeLoop**: For time-dependent problems
    * **VtkOutputModule** / **IOFields**: For VTK output of the simulation

# Simulation Flow

## Simulation Flow

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