Repository files navigation

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

DuMu^x is based on theDUNE framework from which it usesthe 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 differentiation
• A customizable Newton method implementation, including line search and various stopping criteria
• Many pre-implemented models (Darcy-scale porous media flow, Navier-Stokes, Solid and Poromechanics, 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 precipitation 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.

[TOC]

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

• Installation guide
• Getting started guide
• Documentation,
• DuMu^x course materials,
• Examples, with detailed descriptions 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 theWiki.

Automated testing of installation:

DuMu^x is licensed under the terms and conditions of the GNU GeneralPublic License (GPL) version 3 or - at your option - any laterversion. The GPL can beread online or in theLICENSE.md fileprovided in the topmost directory of the DuMu^x source code tree.

Please note that DuMu^x' license, unlike DUNE's, doesnot feature atemplate exception to the GNU General Public License. This means thatyou must publish any source code that uses any of the DuMu^x headerfiles if you want to redistribute your program to third parties. Ifthis is unacceptable, pleasecontact us for a commerciallicense.

See the fileLICENSE.md for copying permissions.For a curated list of contributors, seeAUTHORS.md.If you notice that a contributor is missing on the list,pleasecontact us or open a merge request adding the name.

DuMu^x is research software developed at research institutions.You can citespecific releases viaDaRUS (from 3.6) orZenodo:. You can also cite individual code files or even lines viaSoftwareHeritage.

If you are using DuMu^x in scientific publications and inthe 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}}

• :
• :

DuMu^x features many tests (some unit tests and test problems) thatare 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 (seeCMakeLists.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$

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

Thedumux_add_testcommand specifies some important parameters:NAME sets the name of the test. There is eitherSOURCES orTARGETspecified. IfSOURCES is specifiedNAME, corresponds to the build target, otherwiseTARGET is the build target.

You can build the test by runningmake REPLACE_BY_NAME_OF_BUILD_TARGET (when using GNU Makefiles (default) this is possiblewithin the test folder in the build directory, forninja 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 argumentCMAKE_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 modulesdune-foamgrid anddune-alugrid. For installingexternal dependencies, have a look at thedocumentationand the scriptdumux/bin/installexternal.py.

A weekly coverage report of the test suite is created by gcovr/gcov. The reportcurrently 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.

Contributions are highly welcome. Please ask questions over themailing list.Please review thecontribution guidelinesbefore opening issues and merge requests.

For bug reports or to report any detected security vulnerabilities, contact usover the mailing list, or file anissue. For bug fixes,feature implementations open amerge requestor send us formatted patches.

For a detailed description of the backward compatibility policy,please seecontribution 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 backward compatibility (see below)but would provide a detailed guide on updating dependent modules.For each minor release, maintaining backward compatibility is strongly encouraged and recommended.

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