Introduction

Table of Contents

• What is DuMux?
• Overview
• License
• How to cite
• Automated Testing / Test suite
  • Running individual tests
  • Test coverage
• Contributing
• Bug/issue reports or vulnerabilities
• Releases and backwards compatibility policy

What is DuMux?

DuMu^x is a simulation framework with a focus on finite volume discretization methods, model coupling for multi-physics applications, and flow and transport applications in porous media.

DuMu^x is based on the DUNE framework from which it uses the versatile grid interface, vector and matrix types, geometry and local basis functions, and linear solvers. DuMu^x then provides

• Finite volume discretizations (Tpfa, Mpfa, Staggered) and control-volume finite element discretization schemes
• A flexible system matrix assembler and approximation of the Jacobian matrix by numeric differentation
• A customizable Newton method implementation including line search and various stopping criteria
• Many preimplemented models (Darcy-scale porous media flow, Navier-Stokes, Geomechanics, Pore network models, Shallow water equations) and constitutive models
• A multi-domain framework for model coupling suited to couple subproblems with different discretizations/domains/physics/dimensions/... and create monolithic solvers

DuMu^x has been applied to model complex and non-linear phenomena, such as \(\mathrm{CO}_2\) sequestration, soil remediation, reactive transport and precipitaion phenomena, drug delivery in cancer therapy, flow in micro-fluidics, root-soil interaction, flow in fractured porous media, atmosphere-soil flow interaction, evaporation and more. Please have a look at our journal publications (see below: How to cite) for a more detailed description of the goals the development history and motivations behind DuMu^x.

Overview

The following resources are useful to get started with DuMu^x:

• Installation guide
• Getting started guide
• Documentation,
• DuMu^x course materials,
• Examples, with detailed description of code and results,
• Mailing list,
• Changelog, where all changes between different release versions are listed and explained.

Some helpful code snippets are available in the Wiki.

Automated testing of installation:

License

DuMu^x is licensed under the terms and conditions of the GNU General Public License (GPL) version 3 or - at your option - any later version. The GPL can be read online or in the LICENSE.md file provided in the topmost directory of the DuMu^x source code tree.

Please note that DuMu^x' license, unlike DUNE's, does not feature a template exception to the GNU General Public License. This means that you must publish any source code which uses any of the DuMu^x header files if you want to redistribute your program to third parties. If this is unacceptable to you, please contact us for a commercial license.

See the file LICENSE.md for copying permissions. For a curated list of contributors see AUTHORS.md. If you notice that a contributor is missing on the list, please contact us or open a merge request adding the name.

How to cite

DuMu^x is research software and developed at research institutions. You can cite specific releases via DaRUS (from 3.6) or Zenodo: . You can also cite individual code files or even lines via Software Heritage:

If you are using DuMu^x in scientific publications and in the academic context, please cite (at least one of) our publications:

DuMux 3 – an open-source simulator for solving flow and transport problems in porous media with a focus on model coupling. Computers & Mathematics with Applications, 81, 423-443, (2021). PDF

@article{Koch2021,
    doi = {10.1016/j.camwa.2020.02.012},
    year = {2021}, volume = {81}, pages = {423--443},
    publisher = {Elsevier {BV}},
    author = {Timo Koch and Dennis Gläser and Kilian Weishaupt and others},
    title = {{DuMux} 3 {\textendash} an open-source simulator for solving flow and transport problems in porous media with a focus on model coupling},
    journal = {Computers \& Mathematics with Applications}}

DuMux: DUNE for multi-{phase,component,scale,physics,…} flow and transport in porous media. Advances in Water Resources, 34(9), 1102–1112, (2011) PDF

@article{Flemisch2011,
    doi = {10.1016/j.advwatres.2011.03.007},
    year = {2011}, volume = {34}, number = {9}, pages = {1102--1112},
    publisher = {Elsevier {BV}},
    author = {B. Flemisch and others},
    title = {{DuMux}: {DUNE} for multi-$\lbrace$phase, component, scale, physics, {\ldots}$\rbrace$ flow and transport in porous media},
    journal = {Advances in Water Resources}}

Automated Testing / Test suite

• Latest release (3.9):
• Master branch (development / unstable):

DuMu^x features many tests (some unit tests and test problems) that are continuously and automatically tested in the GitLab-CI framework (see badges). The test suite is based on CTest and can also be built and run manually

make -j8 build_tests && ctest -j8

The tests are labelled (see CMakeLists.txt of each individual test for its labels). You can build and run tests of a specific label (e.g. 2p for two-phase flow porous medium model tests) like this

make -j8 build_2p_tests && ctest -j8 -L ^2p$

Running individual tests

To find out how to build a test inspect the CMakeLists.txt file in the respective test folder.

The dumux_add_test command specifies some important parameters: NAME sets the name of the test. There is either SOURCES or TARGET specified. If SOURCES is specified NAME, corresponds to the build target, otherwise TARGET is the build target.

You can build the test by running make REPLACE_BY_NAME_OF_BUILD_TARGET (when using GNU Makefiles (default) this is possible within the test folder in the build directory, for ninja it has to be executed in the top-most build folder level).

Some tests may depend on additional optional dependencies. You can find this by inspecting the argument CMAKE_GUARD, e.g. HAVE_UMFPACK means UMFPack is required (via installing Suitesparse), or ( "dune-foamgrid_FOUND" AND "dune-alugrid_FOUND" ) means that the test requires the additional Dune modules dune-foamgrid and dune-alugrid. For installing external dependencies, have a look at the documentation and the script dumux/bin/installexternal.py.

Test coverage

A weekly coverage report of the test suite is created by gcovr/gcov. The report currently doesn't include non-instantiated code, so the real coverage is likely lower. However, only a few lines of code are never instantiated in the comprehensive test suite.

Contributing

Contributions are highly welcome. Please ask questions over the mailing list. Please review the contribution guidelines before opening issues and merge requests.

Bug/issue reports or vulnerabilities

For bug reports or to report any detected security vulnerabilities contact us over the mailing list, or file an issue. For bug fixes, feature implementations open a merge request or send us formatted patches.

Releases and backwards compatibility policy

For a detailed description of the backwards compatibility policy, please see contribution guidelines.

DuMu^x releases are split into major (e.g. 2.0, 3.0) and minor (e.g. 3.1, 3.2, 3.3) releases. Major releases are not required to maintain backwards compatibility (see below), but would provide a detailed guide on how to update dependent modules. For each minor release, maintaining backwards compatibility is strongly encouraged and recommended.

Despite the goal of maintaining backwards compatibility across minor releases, for more complicated changes, this is decided upon on a case to case basis, due to limited developer resources. In the case that implementing full backwards compatibility for an update is not feasible, or would require unreasonable resources, the degree of backwards compatibility be decided by a vote in one of the monthly core developer meetings.