CHANGELOG.md

Differences Between DuMuX 3.1 and DuMuX 3.0

Important Notes

Improvements and Enhancements

• Added new porous medium model for the energy balance of a porous solid (general heat equation)
• Multidomain: It is now possible to use the facet coupling module together with the mpfa-o scheme in the bulk domain.
• Added a StaggeredNewtonConvergenceWriter for the staggered grid discretization scheme
• The box scheme works now on grids with prism / wedge elements in 3D
• The GridManager now support reading unstructured grids and data from vtu/vtp files (ASCII, XML format) sequential This means for UGGrid and FoamGrid you can now specify a grid in such a format in the input file Grid.File = mygrid.vtu / Grid.File = mygrid.vtp and the associated data is available in the grid data object

Immediate interface changes not allowing/requiring a deprecation period

• NewtonConvergenceWriter's first template argument has changed from GridView, the FVGridGeometry. This allows to call the resize() method after a grid change without any arguments. Here is an example of how to instatiate the convergence writer:

  using NewtonConvergenceWriter = Dumux::NewtonConvergenceWriter<FVGridGeometry, SolutionVector>;
  auto convergenceWriter = std::make_shared<NewtonConvergenceWriter>(*fvGridGeometry);

• The interface of the abstract TimeLoopBase class has been extended by virtual void advanceTimeStep(), virtual void setTimeStepSize(Scalar dt), virtual Scalar maxTimeStepSize(), and virtual bool finished(), thus forcing the inheriting classes to implement those functions. TimeLoop is no longer a template argument in NewtonSolver's solve() method, thereby increasing type safety and providing better compiler error messages.

Deprecated classes/files, to be removed after 3.1:

Deprecated member functions, to be removed after 3.1:

• The convergence writer is no longer passed to NewtonSolver's solve() method. For outputting convergence data, please use newtonSolver.attachConvergenceWriter(convWriter) in main.cc (directly after instantiating the writer). To stop the output, the writer can also be detached again using newtonSolver.detachConvergenceWriter().

Deleted classes/files, property names, constants/enums

Differences Between DuMuX 2.12 and DuMuX 3.0

Important Notes

• DuMuX 3.0 is a major version update. It is not backward compatible in all aspects to 2.12. The following minor version updates will be, as before for the DuMuX 2-series, always backward compatible to at least the last minor version update.

• The tutorial has been replaced by the new module dumux-course which is accessible at https://git.iws.uni-stuttgart.de/dumux-repositories/dumux-course. We recommend new users and also users experienced with DuMuX 2.X to clone the course and have a look at the exercises in there.

• DuMuX 3.0 is based on Dune 2.6 and is expected to run with the current Dune master. We will try to keep the compatibility with the Dune master as long as it is technically feasible and our resources allow it.

• DuMuX 3.0 requires at least GCC 4.9 or Clang 3.5 in their C++-14 mode. However, we suggest to use newer compiler versions, as we cannot test against all previous compiler versions.

• For employing corner-point grids by means of opm-grid, the OPM release 2018.10 has to be used.

Improvements and Enhancements

General

• New style main files: 3.0 comes which a major overhaul of how the sequence of simulation steps is specified. Until 2.12 there was the start.hh header including the free function start that contained a predefined sequence of steps. Customization of the sequence was possible by many hooks implemented in classes used in this sequence. This made it hard to follow the course of the program and hard to implement customization at points where this was not previously envisioned. In contrast, in the new approach the sequence of simulation steps was linearized, meaning that each step is visible in the program's main file. In the new main files, one can clearly see the io, initialization, assembly, solving, update, time loop, etc., of the program. Many parts of the simulation that were previously mandatory, i.e. simulations in 2.12 always contained a time loop, are now optional (stationary simulations just don't need a time loop). The new style main files make it easier two follow the course of the program, are easier to customize, and offer more flexibility concerning the customization of steps and components of a simulation. All tests and examples in the dumux repository have been adapted to the new style main files.
• Property system: The property system is now usable without preprocessor macros. To this end it was completely reimplemented using C++14 techniques and variadic templates. The hierarchies can now be arbitrarily deep instead of being limited to 5 levels. The new implementation does not use C++ inheritance. Properties and TypeTag now have to be properly qualified with the namespaces Properties::, TTag::. Types that share the name with properties have to properly qualified with the Dumux:: namespace. This update makes it hopefully more readable and removes the "magic" part from the property system.
• Runtime parameters: Runtime parameters are no longer accessed with preprocessor macros. They have been replaced by C++ function templates Dumux::getParam, Dumux::hasParam, Dumux::getParamFromGroup. The ..FromGroup version has been redesigned to allow the specification of parameters for different models in one input file. The concept of a parameter group string was extended to make it possible to use a single input file for complex multidomain simulation setups.
• Restarting simulations: The old restart module was replaced by an implementation based on a VTK backend (other formats might be added later such as HDF5). Restarted simulations can read solutions from vtk files. For parallel runs, there is currently the restriction that the number of processors has to be the same as before the restart. Restarted simulations can read grids from vtk (currently only sequential, non-adaptive grids, support for parallel and adaptive will be added in a future version).
• Assembly: The assembler can now assemble implicit and explicit Euler time discretizations. An interface for implementing analytical Jacobians was added. The CCTpfa assembler has been significantly improved for complex models that spend a lot of time computing constitutive laws. Also the numerical differentiation scheme was improved by altering the order in which derivatives are computed.
• TypeTag templates: Implementers of code in DuMuX 3.0 are advised to avoid TypeTag as a template argument for class templates. Many classes in the DuMuX core have been changed to have a small number of specific template arguments, including GridGeometry, TimeLoop, Newton, LinearSolver, SpatialParams. This makes it possible to share objects of these types between models using different TypeTags. This was not possible before as Class<TypeTag1> and Class<TypeTag2> are different types, even if they contain exactly the same implementation code. Furthermore, having TypeTag as a template argument leads to bad programming, and unnecessary dependencies that should be avoided in every object-oriented code.
• The grid geometry concept: In version 3.0, discretization methods use grid geometries which are wrappers or adapters around a Dune::GridView, providing data structures and interfaces necessary to implement these discretization methods easily. In particular, the abstraction of sub-control-volumes (scv) and sub-control-volume-faces (scvf) are now separate classes and the grid geometry provides means to iterate over all scvs and scvfs of an element, using range-based-for loops.
• The caching concept: Version 3.0 introduces a caching concept for the new grid geometry, the volume variables and the flux variables. There are classes with a Grid prefix, that store data for the current grid view, and classes with the Element prefix that store data locally for an element or element stencil. Depending on the caching concept used, data will be either stored completely in the Grid objects (e.g. GridGeometry) and the Element objects (e.g. ElementGeometry) are mere accessor objects, or, data will be partly only cached locally. Local caching uses less memory but might result in an increased runtime. Grid caching is memory intensive but can provide a significant run-time speedup. Choose whatever concept fits your available resources, the default being local caching.
• Support for grid managers dune-subgrid (a meta grid selecting only certain elements from a host grid) and dune-spgrid (a structured parallel grid manager, supporting periodic boundaries).

Models, Physics and Methods

• MPFA schemes: The new design of the DuMuX core facilitates the incorporation of new finite-volume schemes. In particular, the new core comes with a framework for MPFA schemes, in which currently the only available scheme is the MPFA-O scheme. It can be used in conjunction with any DuMuX model and also works on surface grids. More schemes will be added in the future.
• Box-dfm: The 2pdfm model from version 2.12 has been generalized such that it can be used on any DuMuX model and in both two and three dimensions.
• Tracer transport: A new model for tracer transport with a given flow field has been added. The model can be also used to implement sequentially coupled simulations, or iterative solvers where flow and transport are decoupled / weakly coupled.
• Mineralization: An adapter model for mineralization has been added and can be used with all porousmediumflow models. A balance for the solid volume fraction of precipitating, adsorbed, or absorbed substances is added to the existing equations.
• Solution-dependent spatial params: A redesign of the spatial params interface allows now to define spatial parameters such as permeability and porosity that depend on the solution. This makes it easier to implement mineralization models altering the solid structure of the porous medium.
• Solid systems: DuMuX 3.0 introduces solid systems similar to fluid systems but for solid components. This allows a consistent implementation of mineralization models including reactions, dissolution, precipitation and other processes altering the solid phase of the porous medium.
• Multidomain: DuMuX 3.0 introduces a new multidomain framework which does no longer depend on dune-multidomain and can be used for the coupling of an arbitrary number of subdomains. The sub-domains can be regions in which different sets of equations are solved and/or which have different dimensionalities. The implementation is such that any of the existing DuMuX models can be used in the subdomains, while the data and functionality required for the coupling of the sub-domains is implemented in a CouplingManger class. Three different coupling concepts are available, for which there are a number of available CouplingManager class implementations:
  • Boundary: coupling across sub-domain boundaries
  • Embedded: Coupling between a bulk domain and an embedded lower-dimensional sub-domain which has an independent grid
  • Facet: Coupling betweeen a bulk domain and a codimension-one sub-domain, which is conforming with the element facets of the bulk domain
• Free-flow models: The previous Navier-Stokes model using the box method has been replaced by one that employs a staggered grid discretization. The new method does not require any stabilization techniques while those were necessary for the box method in order to avoid spurious oscillations. The free-flow models in DuMuX 3.0 consider single phase flow with or without component/energy transport. So far, only regular Cartesian grids are supported but local grid refinement will be added in a future release. Several RANS models for turbulent flow have been added: k-omega, k-epsilon, low-Re-k-epsilon, one-eq, zero-eq. The RANS models might be subject to further (interface) changes.
• Thermal and chemical non-equilibrium: The possibility to consider thermal and/or chemical non-equilibrium of several types has been enabled for all porous medium models.
• Interface solver: For the two-phase flow model in conjunction with the box scheme, an interface solver can now be used to reconstruct the saturations in the sub-control volumes adjacent to vertices that lie on material discontinuities. This allows a sharper representation of the saturation front evolving in heterogeneous porous media.
• Components: Components can now derive from different base classes, Base, Liquid, Solid, Gas, depending on which phase states are implemented. This can be used to determine at compile time if a component supports a certain phase state.
• Tabulation of fluid parameter laws: The tabulation of fluid parameter laws has been improved to only tabulate those functions actually used during the simulation. To this end, the tabulation is done on the first call of a corresponding fluid parameter.
• MPNC: The general m-phase n-component model has been adapted in structure to the other porous medium flow models.
• Different wettability: The 2p models can now model materials with different wettability (hydrophobic, hydrophilic) in different parts of the domain.
• Maxwell-Stefan-diffusion: Most models can now use Maxwell-Stefan diffusion for multi-component diffusion instead of Fickian diffusion. There are also a few tests demonstrating how to use it.

Immediate interface changes not allowing/requiring a deprecation period

• Many classes have been completely redesigned. See the numerous example applications included in 3.0 showcasing all new classes.
• The GridCreator has been replaced by the GridManager, which no longer uses a singleton for the grid object. This makes it possible to create two grids of the exact same type. The GridManager also handles user data provided in grid files.