Welcome to the documentation for dune-fem’s python bindings

This module brings python scripting support to Dune. This version describes the bindings for the development version (to become 2.8). The tutorial compatible with the 2.7 release of the DUNE modules is also available. It 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]. 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 descritizations and solving steps. All of this is available within 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. So new implementations of the Dune grid interface can be easily tested. For Dune-Fem developers, new grid views, discrete function spaces, and scheme classes following the Dune-Fem-Howto concept 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 prior to 2.8 then note that the Dune-Python_ module is not 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 they can be found in the demo folder.

  1. First off some remarks on getting the package to work: an easy way of testing but also developing code within the Dune python framework is to use docker. Working from the git sources is also discussed.

  2. A scalar Laplace problem and a simple scalar, non linear time dependent partial differential equation is 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. After this introduction we discuss 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+--]). The introduction ends with an overview of how more complicated boundary conditions are defined.

  3. We then provide more detail on how to use the Dune grid interface, construct a grid using different formats including for example 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. In this section we also give details of how to attach data to the grid entities and define general grid functions.

  4. Some more examples building up on the general concepts described in the first part are presented. 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.i

    • 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. 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).

Todo

add more citations

Installation

Indices and Tables

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.

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.

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.

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.

https://zenodo.org/badge/DOI/10.5281/zenodo.3706994.svg