We happily announce today's release of DuMux 3.5.
Differences Between DuMux 3.5 and DuMux 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 DuMux 3.0 release. For DuMux 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 DuMux 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 DuMux 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 definitionDUMUX_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 parameterAssembly.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 useDumux::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 useDumux::initialize
instead of manually initializing theDune::MPIHelper
. -
Problem/Spatialparams interface: The interface functions
extrusionFactor
/extrusionFactorAtPos
andtemperature
/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 parameterSpatialParams.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 interfaceharmonicMean
in the spatial parameters. -
Component:
gasViscosityIsConstant
added to component interface -
Fluidsystems: Implemented
viscosityIsConstant(int phaseIdx)
forH2OAir
-
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 yourproperties.hh
header. Per default, theThermalDispersionModel
is set to the same model as theCompositionalDispersionModel
, 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 thetest/porousmediumflow/1pnc/dispersion/
folder, and in thetest/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 theRANSBoundaryTypes
class. This replaces the oldisOnWall
andisOnWallAtPos
functions. -
Discretization tags: We introduced tags in the namespace
DiscretizationMethods
(with s) for each discretization method. These tags replace theenum class DiscretizationMethod
. Tags have several advantages over the enum. Each tag is a named type (seedumux/common/tag.hh
) so they can for example be used in tag dispatch. Moreover specializing with tags is extensible. For example we specialize the templateDarcysLawImplementation
for each discretization. When using the enum no new discretization methods can be added without changingenum 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 testtest_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()
andbindScvf()
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 indelp
is present inp
anddelp
has generally a reduced precision that also leads to some problems in automated testing. -
Richards: the
Richards
model now works together with the genericFluidSystem::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
inSplineCommon
Immediate interface changes not allowing/requiring a deprecation period:
-
Discretization tags: The following classes have changed from a template argument of type
DiscretizationMethod
(anenum
) 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 areDarcysLawImplementation
,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 ofDiscretizationMethod
with the corresponding tag fromDiscretizationMethods
, or typesDiscretizationMethod
in template arguments by genericclass
. -
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, thestore
andreconstruct
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 thegridView
, are deprecated, useupdate(gridView)
instead. -
enum class DiscretizationMethod
and associated functions, to be replaced by tags -
test_dumux.sh
is deprecated. -
compareparameters.sh
is deprecated, usegenerate_parameterlist.py
instead. -
replace_property_macros.sh
is removed. -
isOnWallAtPos
andisOnWall
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
andextrusionFactor
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 newtemperature
andextrusionFactor
interfaces. - Free flow and pore network models now also expect the user problems to expose spatial parameters, in which
gravity
,temperature
andextrusionFactor
are defined. The respective problem interfaces have been deprecated. -
harmonicMean
has been deprecated in the spatial params use newfaceTensorAverage
- The problem interfaces for fluid properties in the poroelastic model, namely
effectiveFluidDensity
andeffectivePorePressure
, have been deprecated and were moved to the spatial parameters. - The function
shearStress
in the classFrictionLaw
and its child classes has been renamed tobottomShearStress
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.