Commit 1fbd2501 authored by oliver.sander_at_tu-dresden.de's avatar oliver.sander_at_tu-dresden.de
Browse files

Merge branch 'import-examples' into 'master'

Merge the dune-tnnmg-examples module into dune-tnnmg

See merge request !18
parents d642d297 f0a83f32
Pipeline #33312 passed with stage
in 15 minutes and 16 seconds
......@@ -17,3 +17,15 @@ dune:git clang C++17:
dune:git gcc-8 C++17:
image: registry.dune-project.org/docker/ci/dune:git-debian-10-gcc-8-17
script: duneci-standard-test
dune:git clang C++17 with examples:
image: registry.dune-project.org/docker/ci/dune:git-debian-10-clang-7-libcpp-17
script:
- duneci-install-module https://gitlab.dune-project.org/pdelab/dune-pdelab.git
- duneci-standard-test
dune:git gcc-8 C++17 with examples:
image: registry.dune-project.org/docker/ci/dune:git-debian-10-gcc-8-17
script:
- duneci-install-module https://gitlab.dune-project.org/pdelab/dune-pdelab.git
- duneci-standard-test
......@@ -13,5 +13,6 @@ dune_project()
add_subdirectory("doc")
add_subdirectory("dune")
add_subdirectory("examples")
finalize_dune_project(GENERATE_CONFIG_H_CMAKE)
add_subdirectory(doxygen)
add_subdirectory(manual)
*.atfi
*.aux
*.bbl
*.blg
*.log
*.out
dune-tnnmg-manual.pdf
dune_add_latex_document(
SOURCE dune-tnnmg-manual.tex
FATHER_TARGET doc
INSTALL ${CMAKE_INSTALL_DOCDIR})
@article{bastian_et_al:dune1:2008,
author = {Bastian, P. and Blatt, M. and Dedner, A. and Engwer, C. and Kl\"ofkorn, R. and Ohlberger, M. and Sander, O.},
title = {A Generic Interface for Adaptive and Parallel Scientific Computing. {P}art {I}: Abstract Framework},
journal = {Computing},
year = {2008},
volume = {82},
number = {2--3},
pages = {103--119}
}
@article{bastian_et_al:dune2:2008,
author = {Bastian, P. and Blatt, M. and Dedner, A. and Engwer, C. and Kl\"ofkorn, R. and Kornhuber, R. and Ohlberger, M. and Sander, O.},
title = {A Generic Interface for Adaptive and Parallel Scientific Computing. {P}art {II}: Implementation and Tests in {DUNE}},
journal = {Computing},
year = {2008},
volume = {82},
number = {2--3},
pages = {121--138}
}
@InProceedings{blatt_bastian:06,
author = {Markus Blatt and Peter Bastian},
title = {The Iterative Solver Template Library},
booktitle = {Applied Parallel Computing. State of the Art in Scientific Computing},
series = {Lecture Notes in Scientific Computing},
volume = {4699},
publisher = {Springer Verlag},
pages = {666--675},
year = {2007}
}
@www{dune-web,
key = {{\sc DUNE}},
title = {{Distributed and Unified Numerics Environment}},
url = {http://dune-project.org/}
}
@www{dune-extensions,
key = {External {\sc DUNE} Modules},
howpublished = {\url{www.dune-project.org/downloadext.html}}
}
@www{dune_solvers,
title = {The dune-solvers module},
howpublished = {\url{https://git.imp.fu-berlin.de/agnumpde/dune-solvers}}
}
@www{dune_pdelab,
title = {The dune-pdelab module},
howpublished = {\url{https://www.dune-project.org/modules/dune-pdelab}}
}
@inproceedings{graeser_sack_sander:tnnmg:2009,
author = {Gr\"aser, C. and Sack, U. and Sander, O.},
title = {Truncated Nonsmooth {N}ewton Multigrid Methods for Convex Minimization Problems},
booktitle = {Domain Decomposition Methods in Science and Engineering XVIII},
editor = {Bercovier, M. and Gander, M. and Kornhuber, R. and Widlund, O.},
series = {LNCSE},
publisher = {Springer},
year = {2009},
pages = {129--136}
}
@article{graeser_kornhuber:multigrid_obstacle:2009,
author = {Gr\"aser, C. and Kornhuber, R.},
title = {Multigrid Methods for Obstacle Problems},
year = {2009},
journal = {J. Comp. Math.},
volume = {27},
number = {1},
pages = {1-44}
}
@Article{graeser_kornhuber_sack:ac_anisotropic:2009,
author = {C. Gr\"aser and R. Kornhuber and U. Sack},
title = {Adaptive Multigrid Methods for Anisotropic {A}llen--{C}ahn Equations with Logarithmic Potential},
journal = {},
pages = {},
volume = {},
number = {},
year = {2009},
note = {in preparation}
}
@book{kornhuber:adapt_mmg_for_nonlin_var_prob:1997,
author = {Kornhuber, R.},
title = {Adaptive Monotone Multigrid Methods for Nonlinear Variational Problems},
year = {1997},
publisher = {Teubner},
address = {Stuttgart},
edition = {1.}
}
@Book{glowinski:1984,
author = "R. Glowinski",
title = "Numerical Methods for Nonlinear Variational Problems",
publisher = {Springer Verlag},
year = {1984},
series = {Series in Computational Physics}
}
@book{ekeland_temam:1976,
author = {Ekeland, I. and Temam, R.},
title = {Convex Analysis},
year = {1976},
publisher = {North-Holland}
}
@Book{kikuchi_oden:1988,
author = {N. Kikuchi and J. Oden},
title = {Contact Problems in Elasticity},
publisher = {SIAM},
year = {1988}
}
@Book{Braess:1997,
author = {Dietrich Braess},
title = {Finite Elemente},
publisher = {Springer},
year = {1997},
edition = {2nd},
}
@article{bastian_et_al:1997,
AUTHOR = "P. Bastian and K. Birken and K. Johannsen and S. Lang and
N. N{eu\ss } and H. Rent{z--Reicher}t and C. Wieners",
TITLE = "{UG} -- a flexible Software toolbox for solving
partial differential equations",
JOURNAL = CVS,
YEAR = "1997",
VOLUME = "1",
PAGES = "27--40"
}
@mastersthesis{Hardering2010_diplom,
author = {Hardering, H.},
title = {Analysis and Numerical Approximation of Capillary Surfaces},
type = {Diplomarbeit},
school = {Freie Universit\"at Berlin},
year = {2010}
}
@phdthesis{Sander2008_phd,
author = {Sander, O.},
title = {Multidimensional Coupling in a Human Knee Model},
year = {2008},
school = {Freie Universit\"at Berlin}
}
@inproceedings{GraeserSackSander2009,
author = {Gr{\"a}ser, C. and Sack, U. and Sander, O.},
title = {Truncated Nonsmooth {N}ewton Multigrid Methods for Convex Minimization Problems},
booktitle = {Domain Decomposition Methods in Science and Engineering XVIII},
editor = {Bercovier, M. and Gander, M. and Kornhuber, R. and Widlund, O.},
series = {LNCSE},
volume = {70},
publisher = {Springer},
year = {2009},
pages = {129--136}
}
@article{GraeserKornhuberSack2011,
author = {Gr{\"a}ser, C. and Kornhuber, R. and Sack, U.},
title = {Time discretizations of anisotropic {A}llen--{C}ahn equations},
year = {2013},
journal = {IMA J. Numer. Anal.},
volume = {33},
number = {4},
pages = {1226--1244},
doi = {10.1093/imanum/drs043}
}
% -*- tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 1 -*-
% vi: set et ts=8 sw=1 sts=1:
\pdfoutput=1
\newif\ifpreprint
% \preprintfalse % ANS style
\preprinttrue % ArXiv style
\ifpreprint
\documentclass[11pt,
numbers=noenddot,
headings=normal,
DIV16, BCOR10mm]{scrartcl}
\usepackage[hyphens]{url}
\usepackage{fancyhdr}
\pagestyle{fancy}
\usepackage[linktocpage,breaklinks]{hyperref}
\usepackage{xcolor}
\definecolor{comment}{rgb}{0.0,0.6,0.0}
% \usepackage{natbib}
\usepackage{authblk}
\usepackage{listings}
\lstdefinestyle{cppstyle}{language=C++, basicstyle=\ttfamily\small,
extendedchars=true, escapeinside={/*@}{@*/},
breaklines=true, breakatwhitespace=true,
numbers=left, numberstyle=\tiny,
xleftmargin=5pt,
keywordstyle=\color{blue}\bfseries,
stringstyle=\color{red}\ttfamily,
commentstyle=\color{comment}\ttfamily,
morecomment=[l][\color{magenta}]{\#}
}
\lstnewenvironment{c++}[1][]{\lstset{style=cppstyle}}{}
\lstset{style=cppstyle, basicstyle=\ttfamily}
\newcommand{\cpp}{\lstinline}
\else
\documentclass{ansarticle}
\fi
\usepackage{amsmath,amssymb,amsthm}
\usepackage{mathtools}
\lstdefinestyle{errorstyle}{language=, basicstyle=\ttfamily\small,
extendedchars=true, escapeinside={/*@}{@*/},
breaklines=true, breakatwhitespace=true,
numbers=left, numberstyle=\tiny,
xleftmargin=5pt,
keywordstyle=\color{blue}\bfseries,
stringstyle=\color{red}\ttfamily,
commentstyle=\color{comment}\ttfamily,
morecomment=[l][\color{magenta}]{\#}
}
\lstnewenvironment{error}[1][]{\lstset{style=errorstyle}}{}
\usepackage[utf8x]{inputenc}
\usepackage{bm}
\usepackage{graphicx}
\usepackage[square,numbers,sort]{natbib}
\usepackage{xspace}
\usepackage{overpic}
\usepackage[linesnumbered,inoutnumbered]{algorithm2e}
% \usepackage{lscape}
% \usepackage{multicol}
\usepackage[color=green]{todonotes}
\usepackage{attachfile2}
\usepackage{colonequals}
\usepackage{hyperref}
\usepackage{enumitem}
% TODO-command for things that need to be fixed in the code
\newcommand{\moduletodo}[2][]
{
% ,caption={DUNE}
\todo[color=orange,#1]{#2}
}
\bibliographystyle{abbrvnat}
\newtheorem{theorem}{Theorem}[section]
\newtheorem{definition}{Definition}[section]
\theoremstyle{remark}
\newtheorem{remark}{Remark}[section]
\newcommand{\dune}{\textsc{Dune}\xspace}
\newcommand{\modulename}[1]{\texttt{#1}\xspace}
\newcommand{\classname}[1]{\texttt{#1}\xspace}
\newcommand{\mylistsetup}{\itemindent-1.5em \leftmargin2em}
% For typesetting file names
\newcommand{\file}[1]{\texttt{#1}}
\newcommand{\MM}{\mathbb{M}}
\newcommand{\NN}{\mathbb{N}}
\newcommand{\ZZ}{\mathbb{Z}}
\newcommand{\QQ}{\mathbb{Q}}
\newcommand{\RR}{\mathbb{R}}
\newcommand{\R}{\mathbb{R}}
\newcommand{\RRinfty}{{\mathbb{R} \cup\{\infty\}}}
\newcommand{\CC}{\mathbb{C}}
\newcommand{\op}[1]{\operatorname{#1}}
\newcommand{\argmin}[1]{\underset{#1}{\op{arg\,min\,}}}
\newcommand{\RNN}{\RR^{N\times N}}
\newcommand{\RNn}{(\RR^N)^n}
\newcommand{\RNNnn}{(\RNN)^{n\times n}}
\newcommand{\RMm}{(\RR^M)^m}
\newcommand{\RMNmn}{(\RR^{M\times N})^{m\times n}}
\newcommand{\bn}{\mathbf{n}}
\newcommand{\bu}{\mathbf{u}}
\newcommand{\bv}{\mathbf{v}}
\newcommand{\bw}{\mathbf{w}}
\newcommand{\bC}{\mathbf{C}}
\newcommand{\bH}{\mathbf{H}}
\newcommand{\bsigma}{{\bm{\sigma}}}
\newcommand{\bvarphi}{{\bm{\varphi}}}
\newcommand{\bvarepsilon}{{\bm{\varepsilon}}}
\newcommand{\Indexprefix}{\prec}
\newcommand{\Indexprefixne}{\precneqq}
\newcommand{\st}{\,|\,}
\providecommand{\inner}[2]{\left\langle #1, #2 \right\rangle}
\providecommand{\abs}[1]{\lvert#1\rvert}
\providecommand{\norm}[1]{\lVert#1\rVert}
\setlist[enumerate,1]{label=\arabic{enumi}.,ref=\arabic{enumi}.}
\setlist[enumerate,2]{label=\arabic{enumi}.\arabic{enumii}.,ref=\arabic{enumi}.\arabic{enumii}.}
\setlist[enumerate,3]{label=\arabic{enumi}.\arabic{enumii}.\arabic{enumiii}.,ref=\arabic{enumi}.\arabic{enumii}.\arabic{enumiii}.}
\graphicspath{{gfx/}}
% Make title and authors appear in the pdf meta data
\makeatletter
\AtBeginDocument{
\hypersetup{
pdftitle = {\@title},
pdfauthor = {\@author}
}
}
\makeatother
\title{The \modulename{dune-tnnmg} Module and Some Applications}
\author{Carsten Gr\"aser and Uli Sack and Oliver Sander}
\begin{document}
\maketitle
\begin{abstract}
The Truncated Nonsmooth Newton Multigrid Method (TNNMG) is well known to be an efficient and
reliable algorithm for solving convex minimization problems with a block-separable nonsmooth
structure. It has been used successfully in different applications ranging from phase-separation
problems to problems of mechanical contact and friction. To make the algorithm more easily
accessible to users, a C++ implementation of the TNNMG method has been provided, based on the
\dune libraries. This paper describes the implementation, and should serve as a manual for the code.
It presents the central interfaces, and gives a sequence of complete code examples for test
problems of varying difficulty, such as obstacle problems, and contact problems with and without
friction.
The \dune software system is organized in modules, and the TNNMG implementation presented here
forms its own module called \modulename{dune-tnnmg}. It uses some infrastructure from a second
module called \modulename{dune-solvers}, which provides a general framework for iterative solvers
for linear and nonlinear systems of algebraic equations. We dedicate one chapter to this module.
\end{abstract}
\section{Introduction}
There is a series of application problems that can be written as minimization problems for a strictly convex
functional on a Euclidean space. Most problems that we have in mind result from discretizations of
partial differential equations, but there are a few others, too. In several cases, there is even
more structure. We call a functional
\begin{equation*}
\varphi : \R^n \to \R \cup \{\infty \}
\end{equation*}
{\em block-separable}, if there is a decomposition of $\R^n$ as
\begin{equation*}
\R^n
=
\bigotimes_{i=1}^m \R^{n_i}
\end{equation*}
such that $\varphi$ can be written as a sum
\begin{equation*}
\varphi(v)
=
\sum_{i=1}^m \varphi_i(R_i v)
\end{equation*}
where $R_i : \R^n \to \R^{n_i}$ is the canonical restriction operator to the $i$-th component.
In the following we consider functionals $J:\R^n \to \RRinfty$ of the form
\begin{align*}
J(v) = J_0(v) + \varphi(v)
\end{align*}
where $J_0:\R^n \to \R$ is coercive, and $C^2$,
$\varphi:\R^n \to\RRinfty$ is block-separable, and each $\varphi_i \R^{n_i} \to \RRinfty$
is convex, proper, and lower semi-continuous.
Examples for such problems include obstacle problems~\cite{graeser_kornhuber:multigrid_obstacle:2009},
contact problems~\cite{Sander2008_phd},
and capillary surface problems~\cite{Hardering2010_diplom},
Tresca friction problems and primal small-strain plasticity.
Binary and vector-valued phase transition problems can also be written in this way~\cite{GraeserSackSander2009}.
As a degenerate case, completely differentiable
problems like the $p$-harmonic energy also fall into this category.
\todo[inline]{Describe alternative algorithmic approaches}
The \emph{Truncated Nonsmooth Newton Multigrid} (TNNMG) method is an iterative
method for the solution of minimization problems with an energy functional of
the structure described above. It is based on a nonlinear smoother that is accelerated
by an inexact Newton-step in an appropriate subspace. The nonlinear smoother is typically
of block-Gau\ss--Seidel type and the subspace is selected such that the functional is
smooth enough for linearization locally near the current iterate. Due this structure
the linear subproblem of the Newton-correction can be solved inexactly using a linear
multigrid step leading to an overall nonlinear multigrid method.
In contrast to other multigrid methods for nonsmooth problems that also
use nonlinear operations
on coarser levels, this leads to a much simpler algorithm with a lot of
flexibility for the design of the coarse solver. Furthermore it often exhibits
better convergence properties because it avoids overly-pessimistic coarse grid
corrections~\cite{graeser_kornhuber:multigrid_obstacle:2009,GraeserSackSander2009}.
\todo[inline,author=OS]{Irgendwo hin: The theory of TNNMG assumes that the functional to be minimized
is strictly convex. However, extensions exist for semi-definite problems \cite{ansgar},
biconvex problems~\cite{miehe} and nonconvex problems~\cite{youett} exist.
}
\subsection{Relation to Other \dune Modules}
The module \modulename{dune-tnnmg} is part of the \dune software framework, and as such
it depends on other \dune modules. Not surprisingly, it uses the infrastructure
from \modulename{dune-common}. The linear algebra classes used are template
parameters in \modulename{dune-tnnmg}. They are expected to implement the
interfaces of the classes in \modulename{dune-istl}.
The \modulename{dune-tnnmg} module is integrated into the framework of the solver
hierarchy of the \modulename{dune-solvers}~\cite{dune_solvers} framework.
As a consequence, a TNNMG solver can be used when a solver from \modulename{dune-solvers}
is required. Conversely, the linear correction problems that are part of a
TNNMG step can be solved with a solver from the \modulename{dune-solvers} module.
Note that since the TNNMG method is purely algebraic there is no direct dependence
on the \modulename{dune-grid} module. There is an indirect dependence through
the \modulename{dune-solvers} module, which allows you to solve the linear correction
problems with a geometric multigrid method.
\bigskip
The example programs in this article use the \modulename{dune-pdelab}~\cite{dune_pdelab}
module to assemble the algebraic problems, but you are by no means obliged to do the same in
your own code. We chose \modulename{dune-pdelab} because it is widely used, well maintained,
and the authors are familiar with it. However, there is no technical dependence of \modulename{dune-tnnmg}
on \modulename{dune-pdelab}.
\subsection{Paper Overview}
This paper is structured as follows: In Chapter~\ref{sec:tnnmg_method} we explain the general
abstract TNNMG method.
Finally, the long Chapter~\ref{sec:examples} gives four complete example programs.
\section{The TNNMG Method}
\label{sec:tnnmg_method}
The TNNMG method is designed to solve nonsmooth convex \todo{CG: Should we drop convexity here?} minimization problems
\begin{align}
u^* \in \R^n: \qquad
J(u^*) \leq J(v) \qquad \forall v \in \R^n.
\end{align}
The TNNMG method requires a problem with a certain block structure.
We therefore identity $\R^n$ with a grouping
into $m$ blocks of sizes $n_1, \dots, n_m$ in the sense that there is
an isomorphism $R$ with
\begin{align}\label{eq:blocking}
R : \R^n \to \bigotimes_{i=1}^m \R^{n_i}, \qquad
R(x) = (R_1(x),\dots, R_m(x)), \qquad
R_i : \R^n \to \R^{n_i}.
\end{align}
We call $R_i$ canonical restriction operator for the $i$-th block.
Furthermore we the inverse isomorphism
$P = R^{-1}$ can be written as
\begin{equation*}
P : \bigotimes_{i=1}^m \R^{n_i} \to \R^n, \qquad
P(x_1,\dots,x_m) = \sum_{i=1}^m P_i(x_i), \qquad
P_i : \R^{n_i} \to \R^{n}
\end{equation*}
with canonical prolongation operators $P_i$ for the $i$-the block.
We note that $R$ being an isomorphism implies that $R_i$
is surjective, $P_i$ is injective, and $P_i = R_i^+$
for any $i$, where $(\cdot)^+$ denotes the Moore--Penrose pseudo inverse.
For the range space $V_i \colonequals \op{range}P_i = P_i\R^{n_i}$
this especially gives
\begin{align*}
R_i \circ P_i = Id : \R^{n_i} \to \R^{n_i}, \qquad
P_i \circ R_i = Id : V_i \to V_i, \qquad
\sum_{i=1}^m P_i \circ R_i = Id : \R^{n} \to \R^{n}.
\end{align*}
\begin{definition}
We say that $J: \R^n \to \RRinfty$ is block-separable non-smooth
with respect to the block-structure \eqref{eq:blocking}
if there are a continuously differentiable function $J_0: \R^n \to \R$
and convex, proper, lower-semicontinuous functions $\varphi_i:\R^{n_i} \to \RRinfty$
such that
\begin{align}
\label{eq:min_problem}
J(v) = J_0(v) + \sum_{i=1}^n \varphi_i (R_i v).
\end{align}
\end{definition}
The actual implementation will even generalize this to
a tree structure, but for the time being a blocking is enough.
While these conditions
will be required by a Gau\ss--Seidel type nonlinear smoother
we will additionally assume that $J_0$ is of class $C^2$ or at least $LC^1$,
i.e., $J_0'$ is Lipschitz. Finally, we additionally require that $J$ be strictly convex and coercive.%
\footnote{It is possible to weaken these requirements a little bit. In the process, you may lose
the ability to prove global convergence, but still retain a method that is very competitive
in practice.}
For later reference we recall some standard definitions:
\begin{definition}
Let $V$ a vector space.
For a function $f:V \to \RRinfty$ we call
\begin{align*}
\op{dom} f = \{x \in V \st f(x)<\infty\}
\end{align*}
the domain of $f$. For a subset $M\subset V$ we call
\begin{align*}
\chi_M: V \to \RRinfty, \qquad
\chi_M(z) \colonequals \begin{cases}
0 & \text{ if } z \in M,\\
\infty & \text{ else }
\end{cases}
\end{align*}
the indicator function of $M$.
\end{definition}
Examples:
\begin{enumerate}
\item
Let $A \in \R^{n \times n}$ be symmetric and positive definite and $b \in \R^n$. Then
\begin{equation*}
J(v)
\colonequals
\underbrace{\frac{1}{2} \langle Av,v\rangle - \langle b,v\rangle}_{=J_0(v)}
\end{equation*}
is a functional that fulfills all requirements, with the nonsmooth functions $\varphi_i$ all
being zero. Such a situation occurs when discretizing an elliptic linear PDE using finite elements.
\item
Let $A$ and $b$ as above and $K_i \subset \R$
for $i=1,\dots,n$ nonempty closed intervals. Then
\begin{equation*}
J(v)
\colonequals
\underbrace{\frac{1}{2} \langle Av,v\rangle - \langle b,v\rangle}_{=J_0(v)}
+ \sum_{i=1}^n \underbrace{\chi_{K_i}(v_i)}_{=\varphi_i(v_i)}
\end{equation*}
is of the class described above. This is the energy functional for the classic obstacle
problem of minimizing $J_0$ in the hypercube $K=\prod_{i=1}^n K_i$.
\item
Let $A$ and $b$ as above and
additionally $B_i \in \R^{d \times n}$ and $\gamma_i : \R^{d} \to \R$ be convex
continuously differentiable functions for $i=1,\dots,k$. The functional
\begin{align*}
J_0(v) = \underbrace{\inner{Av}{v} - \inner{b}{v} + \sum_{i=1}^{k} \gamma_i (B_iv)}_{=J_0(v)}
+ \sum_{i=1}^n \underbrace{\chi_{[0,1]}(v_i)}_{=\varphi_i(v_i)}
\end{align*}
occurs when discretizing certain anisotropic phase-field models~\cite{GraeserKornhuberSack2011}.
\item