Source-linked AI summary
DuMu$^\text{x}$ 3 -- an open-source simulator for solving flow and transport problems in porous media with a focus on model coupling
Timo Koch, Dennis Gläser, Kilian Weishaupt, Sina Ackermann, Martin Beck, Beatrix Becker, Samuel Burbulla, Holger Class, Edward Coltman, Simon Emmert, Thomas Fetzer, Christoph Grüninger, Katharina Heck, Johannes Hommel, Theresa Kurz, Melanie Lipp, Farid Mohammadi, Samuel Scherrer, Martin Schneider, Gabriele Seitz, Leopold Stadler, Martin Utz, Felix Weinhardt, Bernd Flemisch
TL;DR
DuMux 3 addresses the challenge of building complex, reusable porous-media simulations within a maintainable open-source research framework. It redesigns simulation components, finite-volume abstractions, and model coupling, and demonstrates the resulting multi-domain framework across several application areas. Multi-domain simulations currently do not run in parallel when multiple grids are involved, while future work targets coupling, usability, and reproducibility.
Problem
Complex porous-media simulations require a maintainable framework supporting modular components, consistent finite-volume schemes, and coupled models.
Method
DuMux 3 redesigns simulation components and finite-volume abstractions and introduces a consistent framework for multi-domain model coupling.
Results
The multi-domain concept has been successfully used for coupled flow and transport models in vascularized brain tissue, root–soil systems, and fractured rock systems.
Takeaways & Limitations
DuMux 3 provides a flexible framework for implementing coupled flow and transport processes across multiple domains and application settings.
Takeaways & Limitations
Multi-domain simulations involving multiple grids currently do not run in parallel, and efficient load balancing remains challenging.
Abstract
from arXiv · showhide
We present version 3 of the open-source simulator for flow and transport processes in porous media DuMu$^\text{x}$. DuMu$^\text{x}$ is based on the modular C++ framework Dune (Distributed and Unified Numerics Environment) and is developed as a research code with a focus on modularity and reusability. We describe recent efforts in improving the transparency and efficiency of the development process and community-building, as well as efforts towards quality assurance and reproducible research. In addition to a major redesign of many simulation components in order to facilitate setting up complex simulations in DuMu$^\text{x}$, version 3 introduces a more consistent abstraction of finite volume schemes. Finally, the new framework for multi-domain simulations is described, and three numerical examples demonstrate its flexibility.
1. Introduction
DuMux is an open-source, modular porous-media simulator built on Dune. Version 3 follows a major redesign while strengthening development practices, reproducibility, education, and community engagement.
- DuMux and its development: DuMux provides a sustainable, consistent, and modular framework for implementing porous-media model concepts and constitutive relations.It has been applied to greenhouse-gas and CO2 storage, radioactive-waste disposal, remediation, biological-tissue transport, fractured media, and subsurface–atmosphere coupling.
- DuMux and its development: DuMux is based on Dune, a C++ framework for solving partial differential equations with generic interfaces and multiple grid managers.Both projects use modern C++ techniques, including template metaprogramming for efficiency and generic interfaces.
- DuMux and its development: Version 3 was initiated after additions in the 2.X series became inefficient, inconsistent with the original design, or increasingly difficult to maintain.The major release dropped backward compatibility because changes affected all parts of the code base.
- Quality assurance and education: The project supports quality assurance and reproducibility through automated testing, public coverage reporting, educational modules, and documented exercises.About 400 unit and system tests run automatically after commits, while dumux-course and dumux-lecture provide exercises, solutions, examples, and explanations.
- Community building: DuMux has pursued community building through user meetings, courses, workshops, and publicly accessible development infrastructure.A 2015 user meeting had 26 participants, including 10 external users, and GitLab supports contribution through merge requests and review.
2. Structure and design principles
DuMux 3 organizes simulations around replaceable components, explicit program flow, and abstractions for coupled PDE models and finite-volume discretizations. Its C++ design uses properties, templates, and object-oriented interfaces to combine flexibility with computational efficiency.
- Modularity and components: DuMux treats simulations as compositions of replaceable components, allowing users to change constitutive laws, numerical fluxes, and other implementations without modifying the DuMux module.User code is usually developed in a separate Dune module that lists DuMux as a dependency.
- Modularity and components: DuMux models describe coupled PDE systems with constitutive equations for closure, while users can select among laws, fluid systems, solid systems, and components.Many non-isothermal, multicomponent, multiphase porous-media models are already implemented.
- Properties and implementation: Properties attached to a type tag specify compile-time simulation options and can be extracted as traits throughout the code.Code Example 1 configures a one-phase model, a cell-centered two-point-flux scheme, and liquid water.
- Program flow: DuMux 3 places the main simulation steps directly in main, enabling direct removal or replacement of time-loop and solver components.This design separates program flow from individual classes and makes the main program flow more transparent, according to user feedback.
3. Abstractions and concepts for general finite volume schemes
DuMux 3 unifies finite-volume discretization through grid-geometry abstractions that support diverse control-volume layouts, flux formulations, and element-wise assembly. The framework also provides a common implementation interface across schemes, while currently supporting only backward and forward Euler time discretization.
- Grid-geometry abstraction: Grid geometry wraps a Dune grid view and constructs the geometric and topological data needed to evaluate discrete finite-volume equations.This abstraction supports unified implementations of multiple finite-volume schemes.
- Finite-volume discretization: Finite-volume discretization partitions the computational domain into control volumes, sub-control-volumes, faces, and sub-faces for local conservation equations.Control volumes need not coincide with grid elements, although cell-centered schemes usually identify them.
- Finite-volume discretization: The discrete formulation approximates storage and source integrals and replaces exact sub-face fluxes with scheme-dependent numerical fluxes.Flux expressions depend on the underlying scheme, including box, tpfa, and mpfa methods.
- Element-wise assembly: DuMux assembles residuals element-wise because Dune grids provide element-centered connectivity, with local views exposing sub-control-volumes, sub-faces, and geometry.The same local-view pattern supports domain-mass accumulation and assembly across the introduced finite-volume schemes.
- Scope boundary: DuMux currently implements only backward and forward Euler time discretization schemes.
- Software representation: The abstraction supports tpfa, mpfa-o, mpfa-l, mac, nonlinear tpfa and mpfa, and mimetic finite-difference schemes; tpfa, box, mpfa-o, and mac are available in the latest version.The implementation represents sub-control-volumes and sub-control-volume-faces as dedicated objects, cached or constructed on demand.
4. Multi-domain simulations
DuMux 3 introduces a consistent multi-domain framework for coupled PDE models whose subdomains may differ in dimensionality, meshes, or discretization schemes. The framework supports flexible coupling, data transfer, residual assembly, and applications spanning several porous-media systems.
- Framework: DuMux 3 represents coupled models as systems of multiple coupled submodels, including subdomains with different domains, dimensionalities, meshes, or spatial discretization schemes.The framework is designed to minimize software coupling and allow existing DuMux models to be coupled with limited core modifications.
- Coupling types: Figure 2 covers multi-physics, non-overlapping, overlapping, and embedded mixed-dimensional coupling, with coupling modes combinable and no fixed limit on subdomains.Examples include 1D-2D, 1D-3D, and 2D-3D mixed-dimensional domains.
- Coupling implementation: Coupling managers transfer data between subproblems and provide coupling stencils that identify residual dependencies across domains.DuMux supplies grid-intersection algorithms based on axis-aligned bounding-box volume hierarchies to determine connectivity efficiently.
- Assembly and solvers: The multi-domain assembler forms a generic residual-based discrete PDE system whose block Jacobian contains subdomain and coupling Jacobians.Its block structure supports arbitrary numbers of subdomains and can be used for monolithic preconditioners or successive subdomain solves.
- Applications: The framework has been used for coupled flow and transport in vascularized brain tissue, root–soil systems, fractured rock, soil–atmosphere flow, and pore-network–Navier–Stokes models.These examples demonstrate use across biological tissue, vadose-zone, fractured-rock, atmospheric, and pore-scale applications.
5. New features in DuMux 3
DuMux 3 adds broad architectural, modeling, and numerical improvements compared with the 2.X series. These changes increase flexibility and reuse while expanding supported physical processes and discretization options.
- Architecture: DuMux 3 redesigns assemblers, linear and nonlinear solvers, grid readers, grid geometry, and file I/O to make main functions more readable and flexible.The redesign targets high-level class abstractions across simulation setup and execution.
- Architecture: The model implementations improve code reuse and modularity, minimizing duplication and improving readability.These changes are presented as improvements over the 2.X series.
- Physical models: A solid system concept enables models including mineralization or precipitation that can modify the porous matrix structure.Porous-material properties such as intrinsic permeability and porosity can depend linearly or nonlinearly on primary variables.
- Physical models: DuMux 3 generalizes thermal and chemical non-equilibrium models, adds Maxwell–Stefan multicomponent diffusion, and makes cell-centered MPFA-O usable with all models.These changes broaden combinations of porous-medium models and transport formulations.
6. Numerical examples
DuMux 3 demonstrates its multi-domain framework through three coupled flow and transport examples spanning free flow, fractured porous media, and root–soil interaction. The examples combine different domains, dimensions, and discretization schemes while preserving model-specific coupling conditions.
- Overview: Three examples demonstrate multi-domain flexibility: free flow coupled to a pore-network model, fractured rock matrix flow, and root-water uptake with tracer transport.The examples cover Navier–Stokes/pore-network coupling, lower-dimensional fracture networks, and coupled root–soil domains.
- 6.1. Coupling a free flow model with a pore-network model: The free-flow example couples Navier–Stokes flow to a one-dimensional pore network embedded in a two-dimensional domain using fully monolithic coupling.The pore-network model represents pore bodies and throats, with coupling conditions enforcing normal-force, velocity, mass, and mole-fraction relations at the interface.
- 6.2. Two-phase flow through fractured porous media: The fractured-medium example represents a two-dimensional rock matrix and one-dimensional fracture network, including conductive and blocking fractures with distinct permeability and porosity.Darcy flow and phase mass balances are formulated across matrix and fracture subdomains, with normal-flux jumps acting as additional source or sink terms.
- 6.2. Two-phase flow through fractured porous media: The fractured-flow problem can switch among tpfa, mpfa-o, and box schemes by changing at most two lines of code.The simulation uses van Genuchten–Mualem constitutive relationships and an aperture of a = 0.05 m for all fractures.
- 6.3. Root-soil interaction: The root–soil example simulates white-lupin water uptake and tracer transport with different discretization schemes in the root and soil domains.The generic coupling manager computes coupling stencils even when the discretization schemes differ; tracer accumulates near roots where uptake is highest.
7. Current limitations and perspectives
DuMux 3 has several current scope and design limitations, while ongoing development targets solver improvements, broader model coupling, and reproducible research.
- Current limitations: Multi-domain simulations involving multiple grids currently do not run in parallel, because inter-grid data communication and load balancing remain challenging.The Dune grid implementations manage MPI-based distributed-memory parallelism, while multi-grid communication requires additional infrastructure.
- Current limitations: DuMux currently supports only forward and backward Euler time discretizations, and adding other schemes requires non-trivial assembly-process refactoring.This limitation constrains the available temporal discretization choices.
- Current limitations: Tag-based property dependencies can be nontransparent and impede modularity and reusability, motivating a medium-term shift toward explicit dependencies.Classes parameterized by different tags remain different types even when their extracted properties are identical, and the technique complicates useful Python wrappers.
- Current limitations: DuMux prioritizes usable and extensible models over flexible linear algebra, limiting support for algebraic manipulations and complex solver strategies.Examples include Jacobian reorderings, quasi-Newton schemes, and matrix-decomposition-based linear solver strategies.
- Perspectives: Future development includes improved coupled free-flow and shallow-water solvers, pore-network models, stronger coupling with preCICE, and better usability and archivability.The stated reproducibility work is pursued through the SusI project.
Author roles
The manuscript and examples were led by authors who also made major code, data, and software contributions, while the broader author group contributed source code to DuMux 3.
- Author roles: T. Koch, D. Gläser, and K. Weishaupt wrote and proof-read the manuscript, developed the examples, curated data and software, and made the most code contributions since release 2.12.B. Flemisch contributed to the manuscript and code and served as administrative head and coordinator of the project.
- Author roles: All other authors contributed source code since release 2.12, supporting the development, quality, and feature growth of the DuMux 3 research software framework.