Differences Between DuMu^x 3.5 and DuMu^x 3.4

• Requirements: DuMux requires Dune >=2.8 and CMake >= 3.13. It was successfully tested with OPM 2021.10 (which in turn requires Dune <= 2.8), see also patches.

General changes / structure

• Sequential: The old "sequential", "IMPES-style" models have not received updates in several years, are separate from the rest of the code base and increasingly became a maintenance burden. Deprecation warnings are emitted when using the sequential models since the DuMu^x 3.0 release. For DuMu^x 3.5, these models are now removed from the code base. To continue using them use releases/3.4. IMPES-style algorithms are possible in the DuMu^x 3.0 style of implementing models but their development did not receive much attention. See !2629 for the state of current efforts. Further improvements and contributions (MRs) on this front are highly welcome (get in contact via the DuMu^x mailing list).

• We adopted a code of conduct, see dumux/CODE_OF_CONDUCT.md

Improvements and Enhancements

• ParallelFor and multithreaded assembly: For single domain applications using Box of CCTpfa discretization, the possibility for multithreaded (thread-parallel) assembly has been added. It is using the newly added Dumux::parallelFor interface. This features requires a backend to be available. This can be either external backends (TBB, Kokkos) or a working C++ STL parallel algorithms setup. The backend will be selected automatically, if found. You can also specify the backend by setting the compiler definition DUMUX_MULTITHREADING_BACKEND=TBB,Cpp,Kokkos,Serial, where Serial forces to always run in serial. For the assembly, you can explicitly turn multithreading off setting the runtime parameter Assembly.Multithreading = false. If a backend is available and the discretization allows it, the default is multithreaded assembly. When using TBB or Kokkos is it required (recommended) to use Dumux::initialize in the main file.

• initialize: A new control function Dumux::initialize has been added which initializes shared and distributed memory parallelism helpers. It is recommended (and may be required for multithreaded applications) to use Dumux::initialize instead of manually initializing the Dune::MPIHelper.

• Problem/Spatialparams interface: The interface functions extrusionFactor/extrusionFactorAtPos and temperature/temperatureAtPos have been removed from the problem interface and added to the spatial params interface. There is now a default set for temperature (293.15K) which can be changed via the input file parameter SpatialParams.Temperature. For more flexibility overload the function in your spatial parameter class like usual.

• material/spatialparams: The folder has been dissolved and the headers have been moved to other folders. For example, spatial parameter classes specific to porous medium flow problems have been moved to dumux/porousmediumflow. This is due to the realization that spatial parameters do more than defining the "material" (which refers to the porous medium). For example, free flow problem also have parameters that may spatially vary (such as the extrusion factor in an extruded domain).

• Tensor average: Added a function faceTensorAverage which performs a particular average of a tensor at interfaces. This replaces the interface harmonicMean in the spatial parameters.

• Component: gasViscosityIsConstant added to component interface

• Fluidsystems: Implemented viscosityIsConstant(int phaseIdx) for H2OAir

• Dispersion: Dispersion fluxes have been added as an option for the compositional and thermal one-phase porous medium flow models. These models use either a Scheidegger-type dispersion tensor, which is dependent on the velocity field and two length parameters, or a full and constant (not solution-dependent, but possibly spatially varying) tensor that can be user defined in the spatial parameters. For compositional models coupled with flow models (e.g. 1pnc), using the Scheidegger-type dispersion tensor is only implemented for the box discretization method.

  To enable either thermal or compositional dispersion, please define these properties within your properties.hh header. For example:

  template<class TypeTag>
  struct EnableCompositionalDispersion<TypeTag, TTag::MyTest> { static constexpr bool value = true; };
  template<class TypeTag>
  struct EnableThermalDispersion<TypeTag, TTag::MyTest> { static constexpr bool value = true; };

  To determine the type of dispersion tensor, please define the property CompositionalDispersionModel within your properties.hh header. Per default, the ThermalDispersionModel is set to the same model as the CompositionalDispersionModel, but this can be set specifically as well. For example:

  template<class TypeTag>
  struct CompositionalDispersionModel<TypeTag, TTag::MyTest> { using type = ScheideggersDispersionTensor<TypeTag>; };
  template<class TypeTag>
  struct ThermalDispersionModel<TypeTag, TTag::MyTest> { using type = FullDispersionTensor<TypeTag>; };

  The parameters describing your dispersion tensor can then be included in your spatialparameters.hh file, and passed via input parameters. An example of this can be seen in the test/porousmediumflow/1pnc/dispersion/ folder, and in the test/porousmediumflow/tracer/constvel/ folders.

• Embedded coupling: Add a coupling manager for the 1D-3D projection based scheme with resolved interface introduced in Koch 2022 ( https://doi.org/10.1016/j.camwa.2022.01.021)

• RANS Boundary Types: Wall boundaries for the RANS turbulence models can now be set using the setWall method in the RANSBoundaryTypes class. This replaces the old isOnWall and isOnWallAtPos functions.

• Discretization tags: We introduced tags in the namespace DiscretizationMethods (with s) for each discretization method. These tags replace the enum class DiscretizationMethod. Tags have several advantages over the enum. Each tag is a named type (see dumux/common/tag.hh) so they can for example be used in tag dispatch. Moreover specializing with tags is extensible. For example we specialize the template DarcysLawImplementation for each discretization. When using the enum no new discretization methods can be added without changing enum class DiscretizationMethod. With tags you can make your own tag and specialize a class for that tag. This means new discretization methods can be developed in a modular fashion. The introduction of tags involves a couple of non-backwards-compatible changes, mostly in implementation classes that shouldn't affect most users (see below).

• Box: The box scheme now supports the case that volume variables depend on all dofs in the element. In that case, previously only a Jacobian approximation was assembled. As computing the added derivatives causes a significant overhead in the assembly, the feature is disabled per default. To enable the full Jacobian in this case set the parameter Assembly.BoxVolVarsDependOnAllElementDofs = true. The new feature is tested in the new test test_2p3c_surfactant which features relative permeability that depend on the pressure gradient. The test only passes with the full Jacobian.

• Local views: The bind function associated with the local view of the FVElementGeometry, the ElementVolumeVariables, and the ElementFluxVariablesCache have been simplified. Now it is possible to directly create each of these objects where they are already bound. The following are examples of each new call:

  const auto fvGeometry = localView(gridGeometry).bind(element);
  const auto elemVolVars = localView(gridVolVars).bind(element, fvGeometry, sol);
  const auto elemFluxVarsCache = localView(gridFluxVarsCache).bind(element, fvGeometry, elemVolVars);

  This is also available for the bind() bindElement() and bindScvf() functions. The existing methods for binding will remain.

  Please note however that when working with element loops, separating construction and binding of the local view is more efficient, i.e.

  auto fvGeometry = localView(gridGeometry);
  for (const auto& element : elements(gridGeometry.gridView()))
      fvGeometry.bind(element);

• Construction and update of GridGeometries changed: Grid geometries are fully updated after construction. Additional call of update functions are therefore only needed after grid adaption. Calling the update functions after construction now leads to a performance penalty.

• Geometry:

  • Added implementation of sphere and bounding sphere approximation algorithms
  • Added distance queries for Point->BoundingBoxTree
  • Added DistanceField - a wrapper around a geometry set for fast distance queries
  • Added WallDistance - a utility to compute distances to the domain boundary (e.g. for RANS wall functions)
  • Added 3D-3D intersections
  • Added 2D-2D intersections in 3D
  • Fixed a wrong epsilon for floating comparisons in the 2D-2D intersection algorithm

• Parallel grid partitioning: Added a simple backend for using Scotch as partitioner for a grid read on one process (e.g. when using the Dune Gmsh or DGF readers). Repartitioning is not implemented yet.

• Cake grid creator: The cake grid creator can now be used in parallel simulations

• Privarswitch: Fixed a bug in the privar switch which did not fully reset the switched variable. This lead to a possibly increased number of Newton iterations.

• 1pnc: delp has been removed from the default vtk output fields in an attempt to streamline output between models. All information present in delp is present in p and delp has generally a reduced precision that also leads to some problems in automated testing.

• Richards: the Richards model now works together with the generic FluidSystem::TwoPImmiscible as long as a gas and a liquid phase are present.

• Richards: Fixed a bug that creeped into the 1.5-phase model so it actually computes diffusion in the gas phase now.

• Richards: Fixed a bug that checked that the fluid viscosity is not constant whereas the check should have asserted that it is constant

• Fixed intersect in SplineCommon

Immediate interface changes not allowing/requiring a deprecation period:

• Discretization tags: The following classes have changed from a template argument of type DiscretizationMethod (an enum) to class type template arguments and are now specialized for tags: TwoPScvSaturationReconstruction, ScvfToScvBoundaryTypes, ProblemTraits, FluxStencil, EffectiveStressLaw, HookesLaw, FacetCouplingManager, FacetCouplingMapper. Moreover this affects the following helper classes: IsFicksLaw, CheckOverlapSize, PartialReassemblerEngine, SubDomainAssemblerType. Finally, this change has been made for many implementation classes. These should not have been used directly anyway, so we do not explicitly list them here. Examples are DarcysLawImplementation, LinearSolverTraitsImpl. See !2844 for more details. If you face a compiler error from these changes, contact us. Most like the solution is to simply try replacing occurrences of DiscretizationMethod with the corresponding tag from DiscretizationMethods, or types DiscretizationMethod in template arguments by generic class.

• Coupling managers: The coupling managers now store shared_ptrs of the subdomain solutions to be able to manage memory outside. There is compatibility interface that is deprecated but it won't allow for assignments of the form this->curSol() = sol; since curSol returns a MultiTypeVector of references. If assignment is needed for some reason, use a hybrid loop over all subdomain indices.

• Virtual interface of GridDataTransfer: The GridDataTransfer abstract base class now required the Grid type as a template argument. Furthermore, the store and reconstruct interface functions do now expect the grid as a function argument. This allows to correctly update grid geometries and corresponding mapper (see "Construction and update of GridGeometries changed" above in the changelog)

• PengRobinsonMixture::computeMolarVolumes has been removed without deprecation. It was used nowhere and did not translate.

• ShallowWaterViscousFlux: The template argument PrimaryVariables has been removed without deprecation. It was not needed.

Deprecated properties/classes/functions/files, to be removed after 3.5:

• update() functions of grid geometries, which do not receive the gridView, are deprecated, use update(gridView) instead.
• enum class DiscretizationMethod and associated functions, to be replaced by tags
• test_dumux.sh is deprecated.
• compareparameters.sh is deprecated, use generate_parameterlist.py instead.
• replace_property_macros.sh is removed.
• isOnWallAtPos and isOnWall are no longer used in the RANS models to designate wall boundaries. These boundaries are now directly set in the RANSBoundaryTypes using the setWall() function.
• the temperature and extrusionFactor interfaces in the problem class have been deprecated and have been moved to the spatial parameters.
• Porous medium flow models should now inherit from the new base spatial parameters that can be found in the folder dumux/porousmediumflow/, which allow users to overload the new temperature and extrusionFactor interfaces.
• Free flow and pore network models now also expect the user problems to expose spatial parameters, in which gravity, temperature and extrusionFactor are defined. The respective problem interfaces have been deprecated.
• harmonicMean has been deprecated in the spatial params use new faceTensorAverage
• The problem interfaces for fluid properties in the poroelastic model, namely effectiveFluidDensity and effectivePorePressure, have been deprecated and were moved to the spatial parameters.
• The function shearStress in the class FrictionLaw and its child classes has been renamed to bottomShearStress and the return value has been changed. The function returns now the actual bottom shear stress and not the bottom shear stress term as it used in the shallow water model. The bottom shear stress term of the shallow water model is the bottom shear stress multiplied with minus one and normalised by the water density.

New experimental features (possibly subject to backwards-incompatible changes in the future)

• Staggered grid: The staggered grid implementation has been overhauled. Unfortunately, this overhaul has not been completed yet. Most of the Navier-Stokes tests now use the new implementation. The old implementation is still available and not deprecated yet, but will be phased out after the release. For now both implementation live next to each other in the code base. The new implementation is more closely built on the multidomain framework and now fully realizes the finite volume abstractions described in the Dumux paper. The first aspect means that mass and momentum are now separate sub-models of Navier-Stokes than can be (and are) discretized with different discretization methods and then coupled together via coupling managers. The implemented mass discretization is CCTpfa. The momentum discretization is a face-centered staggered finite volume scheme (FCSFV). The second aspect means that for the FCSFV scheme, subcontrol volumes and faces are now represented by corresponding classes in the code just like for CCTpfa, Box, CCMpfa. There is a problem class added that helps to implement both the mass and the momentum problem in one (templated) class. Boundary conditions are now clearly separated into mass and momentum boundary conditions. When the new implementation is fully adapted the documentation will be updated with it, this might take some time and is not included in this release yet.

• FF-PNM: Added a model and test for coupling a porenetwork with a freeflow domain (see Weishaupt PhD: http://dx.doi.org/10.18419/opus-10932)

• Python bindings: The Python bindings work with Dune master now, which features an improved way of installing them. The new way will be described better in the documentation once Dune 2.9 is release. Until then we refer to the documentation of Dune. The setup with Dune 2.9 is not compatible with the setup with Dune 2.8 but we made sure that Dumux 3.5 support both variants.

• Pore-network models: The development continues and many smaller things have been improved. The PNM models remain experimental. The grid creator has been improved in usability. Added a convenience script to extract PNM with porespy and create a DGF grid usable with Dumux.

Continuous integration

• Python bindings: The Python bindings are now tested in the CI. Furthermore, Python scripts are automatically checked with linters, see dumux/python/README.md for more information.