Welcome to the dune-fem tutorial

This module brings python scripting support to Dune. This version describes the bindings for the development version (to become 2.10). The bindings serves three purposes:

1. High level program control for solving partial differential equations using classes from the Dune core and from Dune-Fem [BBD+08, DKNO10] with a recent update provided in [BBD+21]. The unified form language UFL [ALO+13] is used to describe the mathematical model, all realizations of the Dune grid interface can be used to work with the domain tessellation, and the finite element spaces, operator, and solvers provided by Dune-Fem for the discretizations and solving steps. All of this is available to be used in python scripts or through Jupyter notebooks.

2. Rapid prototyping of new methods or other parts of a simulation is easy since the interfaces provided are very similar to the Dune C++ interface. This makes it easy to transfer a working prototype from python (easy to develop) to C++ (high efficiency). Small C++ code snippets can be easy called from python using just in time compilation.

3. Rapid prototyping of new implementations of Dune interfaces. For example new implementations of the Dune grid interface can be easily tested. For Dune-Fem developers, new grid views, discrete function spaces, and scheme classes can be added and tested.

An Overview of this Document

This document tries to describe the main concepts needed to get a new user started on solving complex partial differential equations using the Dune-Fem python bindings. Some parts are still quite raw and we would greatly appreciate any help improving this document. In addition if you would like to promote your own work then please upload a script showcasing some simulation you did bases on this package - it is possibly as easy as providing us with a Python script. More details on how to help us improve and extend this document see the section on How to showcase your own project.

The Python bindings are based on pybind11 [WRM17] and a detailed description on how we export the polymorphic interfaces in Dune is provided in [DN18] which describes the dune module Dune-Python which after the Dune 2.7 release has been directly integrated into the Dune core modules. If you have a version newer then 2.8 then note that the Dune-Python module is obsolete.

Here is a quick summary of the different parts of this document - all of the code is available for download in form of both Notebooks and Scripts. Or can be obtained by cloning the git repository https://gitlab.dune-project.org/dune-fem/dune-fempy where the scripts can be found in the demo folder.

1. First off some remarks on getting the package to work: the simplest approach is to use the Python package index (pip) to install the software into a new virtual environment. Working from the git sources is a good option for more advanced users who want to change the underlying Dune C++ source files.

2. A scalar Laplace problem and a simple scalar, non linear time dependent partial differential equation are used to describe the basic concepts. This leads through the steps required to set up the problem, solve the system of equations, and visualize the results.

3. After the introduction to the underlying concepts and how to get a simple problem up and running, we discuss:

   • how to add more complicated boundary conditions to the problem formulation.

   • how to use different solver backends (including build in solvers, solvers and preconditioners available in Dune-Istl, scipy, PETSc and also petsc4py see also [BAA+18, JOP+--]).

   • how to enable either multithreading or MPI parallelization for your problem

   • how to backup and restore data including discrete functions and the grid hierarchy as is useful for example to checkpoint a simulation.

   • more details on constructing a grid using different formats including for example the Dune Grid Format (DGF) or gmsh but also using simple python structures like dictionaries for describing general unstructured grids is available. Results can be plotted using matplotlib (for 2d) and for example mayavi (for 2d and 3d). For more advanced plotting options data can be exported using vtk format and then analysed for example using paraview. All of this is demonstrated in the provided examples.

   • discuss the grid interface in more details, i.e., how to iterate over the grid, access geometrical information, and attach data to elements of the grid.

4. Building upon the general concepts described in the first part, we provide scripts showing how to solve far more complex PDEs. The Notebooks and Scripts used for each of these and the following examples can be downloaded and are hopefully useful as starting point for new projects.

5. We then discuss some further topics:

   • Local grid refinement and coarsening is a central feature of Dune-Fem. Here we show how to use it for stationary and time dependent problems. Grid adaptivity makes use of special grid views.

   • Other views are also available, one of these can be used to deform the grid given an arbitrary (discrete) vector field. This is used to compute the evolution of a surface under mean curvature flow.

   • We complete our discussion by demonstrating how to straightforwardly extend the functionality of the package and improve performance by important additional C++ algorithms and classes.

6. There are two larger extension modules build on top of dune-fem which provide Python bindings: those are the Dune-Fem-Dg and the Dune-Vem modules which focus on Discontinuous Galerkin methods for advection-diffusion (especially advection dominated problems) and the implementations of the virtual element method, respectively.

7. Finally other projects are presented some of them developed by the authors of this document, some contributed by other users. If you have used this package then we would like to hear about it and would ask you to contribute to this chapter. Doing so is quite easy (see How to showcase your own project for details).

Changes and new features

• Since 2.9 release

Installation

• From PyPi
  • Hints for Windows
• From Source
  • Requirements
  • Building the Required Dune Modules
  • Troubleshooting

Getting Started

• Introduction
  • A Laplace problem
  • Laplace equation with Dirichlet boundary conditions
  • A Non-linear elliptic problem
• General Concepts (with a time dependent problem)
  • Setting up the Mesh
  • Grid Functions
  • Discrete Functions
  • Handling constant parameters
  • A Nonlinear Time Dependent Problem
  • Listing Available Dune Components

Next Steps

• More General Boundary Conditions
  • Dirichlet boundary conditions
  • Accessing the Dirichlet degrees of freedom
  • Neumann and Robin boundary conditions
  • Using boundary ids (and some more complex examples)
• Alternative Linear Solvers (Scipy and Petsc)
  • Using Scipy
  • Handling Dirichlet boundary conditions
  • Using Petsc and Petsc4Py
  • Available solvers and parameters
• Examples of grid construction
  • Example using the Dune Grid Format (DGF)
  • 3D example (using Gmsh)
  • Converting gmsh to DGF
  • 1D example
• Parallelization
  • OpenMP
  • MPI
• Backup and restore (pickling)
  • Pickling
  • A Chekpointer class
• Using the Full Grid Interface
  • Overview
  • Dense Vectors and the Geometry Classes
  • Grid Construction and Basic Interface
  • Using grid functions
  • Importing user defined C++ code
  • Attaching Data to the Grid
  • Output of Grid and Visualization of Data

Further Examples

• Discontinuous Galerkin Methods
  • Advection-Diffusion: Discontinuous Galerkin Method with Upwinding
  • Transport equation:
• Linear Elasticity: a Deformed Beam
• Spiral Wave
• Wave Equation in a Slit Domain
• Saddle Point Solver (using Scipy)
• Eigenvalue problems
  • Eigenvalues of the Neumann Laplacian
  • Dirichlet Eigenvalue problem

Further Topics

• Grid Views: Adaptivity and Moving Domains
  • Overview and some basic grid views (level and filtered)
    • LevelGridView examples
    • FilteredGridView examples
  • Dynamic Local Grid Refinement and Coarsening
    • Re-entrant Corner Problem
    • Crystal Growth (Phase Field model)
  • Evolving Domains
    • Mean Curvature Flow
• Using C++ Code Snippets
  • C++ Based Grid Functions
  • Mean Curvature Flow (revisited)
  • Dual Weighted Reisdual Estimate
  • Sampling the Solution over a Line

Extension Modules

• Discontinuous Galerkin Methods: the DUNE-FEM-DG Module
  • Euler System of Gas Dynamics
  • An Advection-Diffusion-Reaction System: Chemical Reaction Problem
• Virtual Element Methods: the DUNE-VEM module
  • Elliptic Problems
  • Nonlinear Elliptic Problem
  • Linear Elasticity
  • Fourth order problem
  • Cahn-Hilliard

User Projects

• HP adaptive DG scheme for twophase flow problem
• Mixed-dimensional PDEs: the Dune-MMesh module

Information and Resources

• Information for C++ Developers
• How to showcase your own project
• Notebooks and Scripts
• Mesh Files used in the Examples
• Citing this project
• List of things that need doing…
• Keyword index

Bibliography

AGL05

James Ahrens, Berk Geveci, and Charles Law. Paraview: an end-user tool for large data visualization. The visualization handbook, 2005. URL: https://www.paraview.org.

ALO+13

M. Alnaes, A. Logg, K. Olgaard, M. Rognes, and G. Wells. A Unified Form Language: A domain-specific language for weak formulations of partial differential equations. 2013. URL: https://arxiv.org/abs/1211.4047.

BAA+18

Satish Balay, Shrirang Abhyankar, Mark F. Adams, Jed Brown, Peter Brune, Kris Buschelman, Lisandro Dalcin, Alp Dener, Victor Eijkhout, William D. Gropp, Dinesh Kaushik, Matthew G. Knepley, Dave A. May, Lois Curfman McInnes, Richard Tran Mills, Todd Munson, Karl Rupp, Patrick Sanan, Barry F. Smith, Stefano Zampini, Hong Zhang, and Hong Zhang. PETSc Web page. http://www.mcs.anl.gov/petsc, 2018. URL: http://www.mcs.anl.gov/petsc.

BBD+08

P. Bastian, M. Blatt, A. Dedner, C. Engwer, R. Klöfkorn, R. Kornhuber, M. Ohlberger, and O. Sander. A Generic Grid Interface for Parallel and Adaptive Scientific Computing. Part II: Implementation and Tests in DUNE. Computing, 82(2–3):121–138, 2008. doi:10.1007/s00607-008-0004-9.

BBD+21

P. Bastian, M. Blatt, M. Dedner, N.-A. Dreier, R. Engwer, Ch. Fritze, C. Gräset, Ch. Grüninger, D. Kempf, R. Klöfkorn, M. Ohlberger, and O. Sander. The Dune framework: Basic concepts and recent developments. CAMWA, 2021. doi:10.1016/j.camwa.2020.06.007.

BB06

Markus Blatt and Peter Bastian. The iterative solver template library. In International Workshop on Applied Parallel Computing, 666–675. Springer, 2006.

DPKC11

Lisandro D Dalcin, Rodrigo R Paz, Pablo A Kler, and Alejandro Cosimo. Parallel distributed computing using python. Advances in Water Resources, 34(9):1124–1139, 2011. doi:10.1016/j.advwatres.2011.04.013.

DDE05

Klaus Deckelnick, Gerhard Dziuk, and Charles M Elliott. Computation of geometric partial differential equations and mean curvature flow. Acta numerica, 14:139–232, 2005. doi:10.1017/S0962492904000224.

DH21

A. Dedner and A. Hodson. Robust nonconforming virtual element methods for general fourth-order problems with varying coefficients. IMA Journal of Numerical Analysis, :, 2021. doi:10.1093/imanum/drab003.

DKKN18

A. Dedner, B. Kane, R. Klöfkorn, and M. Nolte. Python framework for hp adaptive discontinuous galerkin methods for two-phase flow in porous media. Applied Mathematical Modelling, 67:, 10 2018. doi:10.1016/j.apm.2018.10.013.

DK21

A. Dedner and R. Klöfkorn. Extendible and Efficient Python Framework for Solving Evolution Equations with Stabilized Discontinuous Galerkin Method. Commun. Appl. Math. Comput., 2021. doi:10.1007/s42967-021-00134-5.

DKNO10

A. Dedner, R. Klöfkorn, M. Nolte, and M. Ohlberger. A Generic Interface for Parallel and Adaptive Scientific Computing: Abstraction Principles and the DUNE-FEM Module. Computing, 90(3–4):165–196, 2010. doi:10.1007/s00607-010-0110-3.

DN18

A. Dedner and M. Nolte. The DUNE-PYTHON Module. CoRR, 2018. arXiv:1807.05252.

Hun07

John D Hunter. Matplotlib: a 2d graphics environment. Computing in science and engineering, 9(3):90–95, 2007.

JOP+--

Eric Jones, Travis Oliphant, Pearu Peterson, and others. SciPy: open source scientific tools for Python. 2001–. URL: http://www.scipy.org/.

Kie15

T. Kieu. Galerkin Finite Element Method for Generalized Forchheimer Equation of Slightly Compressible Fluids in Porous Media. 2015. URL: https://arxiv.org/abs/1508.00294.

MS96

Ravi Malladi and James A. Sethian. Image processing: flows under min/max curvature and mean curvature. Graphical models and image processing, 58(2):127–141, 1996.

Oli06

Travis E Oliphant. A guide to NumPy. Volume 1. Trelgol Publishing USA, 2006.

WRM17

J. Wenzel, J. Rhinelander, and D. Moldovan. Pybind11 – seamless operability between c++11 and python. 2017. URL: https://github.com/pybind/pybind11.