CHANGELOG.md 111 KB
Newer Older
1
2
3
Differences Between DuMu<sup>x</sup> 3.5 and DuMu<sup>x</sup> 3.4
=============================================

4
5
6
7
8
9
10
11
12
- __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<sup>x</sup> 3.0 release. For DuMu<sup>x</sup> 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<sup>x</sup> 3.0 style of implementing models but their development did
  not receive much attention. See https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/-/merge_requests/2629
  for the state of current efforts. Further improvements and contributions (MRs) on this front
  are highly welcome (get in contact via the DuMu<sup>x</sup> mailing list).

13
### Improvements and Enhancements
14

15
16
17
18
19
20
- __Geometry__:
    - Add implementation of sphere and bounding sphere approximation algorithms
    - Add distance queries for Point->BoundingBoxTree
    - Add DistanceField - a wrapper around a geometry set for fast distance queries
    - Add WallDistance - a utility to compute distances to the domain boundary (e.g. for RANS wall functions)

21
22
23
- __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.

24
25
- __Cake grid creator__: The cake grid creator can now be used in parallel simulations

26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
- __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:

```cpp
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.

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

43
44
- __Embedded coupling__: Add a coupling manager for the 1D-3D projection based scheme with resolved interface introduced in Koch 2021 (https://arxiv.org/abs/2106.06358)

45
46
### Immediate interface changes not allowing/requiring a deprecation period:
- __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)
47
- `PengRobinsonMixture::computeMolarVolumes` has been removed without deprecation. It was used nowhere and did not translate.
48
49
- __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.
Martin Utz's avatar
Martin Utz committed
50
- __ShallowWaterViscousFlux__: The template argument `PrimaryVariables` has been removed without deprecation. It was not needed.
51
52
53
54
55
56
57
58
59

### 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.

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

### Continuous integration

60
61
62
63
- __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.


64
Differences Between DuMu<sup>x</sup> 3.4 and DuMu<sup>x</sup> 3.3
65
=============================================
66
67

### Improvements and Enhancements
Bernd Flemisch's avatar
Bernd Flemisch committed
68
69
70
- __Requirements__: DuMux still requires Dune >=2.7 and CMake >= 3.13. It was successfully tested with OPM 2021.04.

- __Pore-network models added to DuMux__:
Kilian Weishaupt's avatar
Kilian Weishaupt committed
71
72
73
74
    - Three fully implicit pore-network models (1p, 1pnc, 2p) have been added.
    - A quasi-static 2p PNM for the creation of pc-Sw curves has been added.
    - A new namespace `Dumux::PoreNetwork` has been introduced, containing all relevant classes and functions for pore-network modeling.
    - An example introduces the use of the 1p PNM for the estimation of the upscaled Darcy permeability.
Bernd Flemisch's avatar
Bernd Flemisch committed
75
    - Advection type including inertia effect for simulations in the non-creeping flow regime is available.
Kilian Weishaupt's avatar
Kilian Weishaupt committed
76
    - Note that this is still considered a rather _experimental_ feature. Everything within namespace `Dumux::PoreNetwork` might undergo (backward-compatibility breaking) changes _without prior notice_.
Bernd Flemisch's avatar
Bernd Flemisch committed
77

78
- __Several scripts have been translated to Python__:
79
    - `installexternal.sh` to install external modules and libraries now rewritten as python script `bin/installexternal.py`
Bernd Flemisch's avatar
Bernd Flemisch committed
80
    - `getusedversions.sh` to extract the used DuMux/Dune versions of a module (new script: `bin/util/getusedversions.py`)
81
    - `extractmodulepart.sh` no longer creates an install file, instead, you can now generate install scripts for your module using the new script `bin/util/makeinstallscript.py`.
Bernd Flemisch's avatar
Bernd Flemisch committed
82
83
    - Note: the old shell scripts will be removed after release 3.4.

84
85
- __Python bindings__: There is now a small finite volume example included in the Python tests using the wrapped grid geometry and problem, see [test_explicit_transport_cctpfa.py](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/-/blob/releases/3.4/test/python/test_explicit_transport_cctpfa.py).

86
- __Law for water vapor viscosity in gas mixtures changed__: Polynomial laws for determining the viscosity of vater vapor in gas mixtures are introduced and applied by the new function `h2oGasViscosityInMixture`. The polynomial laws give a better approximation of the gas viscosity especially at higher temperatures ( >273.15 K) and a high water vapor content.
87

88
89
90
91
92
93
- __Newton line search__: The line search algorithm decreases the step size until the residual decreases. The lower bound
of the step size can now be set in the input file via the parameter `Newton.LineSearchMinRelaxationFactor`.

- __Material / Constant component__: The `Component::Constant` can now be used in non-isothermal simulation. Simple relations
for internal energy and enthalpy depending on temperature and constant heat capacity have been added.

94
95
- __Linear PDE solver__: The `LinearPDESolver` can reuse the matrix and thus avoid unnecessary reassembly. See [test/porousmediumflow/tracer/constvel/main.cc](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/-/blob/releases/3.4/test/porousmediumflow/tracer/constvel/main.cc#L119) for an example.

96
- __Ordering strategies for UMFPack__:
97
It is now possible to [choose an ordering strategy](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/-/blob/releases/3.4/dumux/linear/seqsolverbackend.hh#L851) for UMFPack via the runtime parameter `LinearSolver.UMFPackOrdering` or by calling the `setOrdering()` method of `UMFPackBackend`. This can have a positive effect on the solver's performance, depending on the matrix structure.
98
99

- __Add setRetryTimeStepReductionFactor() function  to NewtonSolver__:
Bernd Flemisch's avatar
Bernd Flemisch committed
100
This function allows to set the factor by which the time step is reduced after a failed iteration. Can be used, e.g., for custom Newton solvers inheriting from this class and using a more sophisticated time step management.
101
102

- __Improve upwind interface__:
Bernd Flemisch's avatar
Bernd Flemisch committed
103
104
    - Additional functions have been added to `upwindscheme.hh` which can be used to `apply` the upwind scheme without the need of `FluxVariables` and to get the `multiplier` by which the flux is multiplied.
    - These additional functions are now used in `CCTpfaForchheimersLaw` by providing the upwind scheme as additional template argument.
105
106
107
108
109
110
111

- __Simplified use of SubGridManger__: It is now possible to specify pixel dimensions when reading an image file used as grid. For instance, `Grid.PixelDimension = 1e-3 1e-3` will scale the domain automatically such that the grid cells have a side length of 1e-3 m and you don't need to specify `Grid.UpperRight` anymore.

- __String utility__: There is a new header `common/stringutilities.hh` that implements two functions `tokenize` and `split`
that can split strings at a given delimiter.

- __Add linearRegression() function  to math.hh__:
Bernd Flemisch's avatar
Bernd Flemisch committed
112
This function gets a set of (x, y) data and calculates/returns the intercept and the slope of the regression line using the standard least squares method.
113

Bernd Flemisch's avatar
Bernd Flemisch committed
114
- __Shallow water__: Added a heuristic turbulence model based on a mixing length and resulting in a turbulent viscosity term.
115

116
### Immediate interface changes not allowing/requiring a deprecation period:
117
118
119
- __Newton__: The global parameter defaults have been substituted for local parameter defaults (in nonlinear/newtonsolver.hh). If
              you have been relying on global defaults (reading parameters without supplying a value in the input file nor a default)
              you will get a runtime ParameterException. To solve this simply provide a default or set the value in the input file.
Bernd Flemisch's avatar
Bernd Flemisch committed
120
121
- __MPNC__: The `MPAdapter` can now also be called with a temporary `pcKrSw` object. For this, the compiler needs to deduce the
            class' template argument types. You may need to adapt your `spatialParams` from
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
```
using MPAdapter = Dumux::FluidMatrix::MPAdapter<PcKrSwCurve, 2>;
...
auto fluidMatrixInteractionAtPos(const GlobalPosition &globalPos) const
{
    return makeFluidMatrixInteraction(MPAdapter(pcKrSwCurve_));
}
```
to
```
// alias for MPAdapter is removed
auto fluidMatrixInteractionAtPos(const GlobalPosition &globalPos) const
{
    return makeFluidMatrixInteraction(FluidMatrix::MPAdapter(pcKrSwCurve_));
}
```
Bernd Flemisch's avatar
Bernd Flemisch committed
138
- __Grid geometry__: The local views of grid geometries are now required to implement the interfaces
139
140
141
`element()` (returning the bound element) and `isBound()` returning a `bool` which is `true` if the
functions `bind` or `bindElement` have been called (i.e. the local geometry is in a bound state). These
interfaces are currently not used (except in the unit tests) but will be required
Bernd Flemisch's avatar
Bernd Flemisch committed
142
by the assembler in future DuMux versions.
143

144
### Deprecated properties/classes/functions/files, to be removed after 3.4:
145
- `Dumux::IsIndexable<T, I>` is deprecated, use `Dune::IsIndexable<T, I>`directly.
Bernd Flemisch's avatar
Bernd Flemisch committed
146
147
148

- The property `NumEqVector` has been deprecated. The class `NumEqVector` is now defined in the namespace `Dumux` in the header file `dumux/common/numeqvector.hh`.

149
- The member function `update()` of mappers is deprecated, use `update(gridView)` when updating the mapper after a grid or grid view change.
Bernd Flemisch's avatar
Bernd Flemisch committed
150
151

- All custom mapper implementations should implement `update(gridView)` replacing `update()`. Mappers with `update()` will no longer be supported after support for Dune 2.7 is dropped.
152
153
154
155
156
157

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

- __Time stepping__: a first implementation of a generic `Dumux::MultiStageTimeStepper` was introduced,
that allows for using different time integration schemes besides the currently supported implicit and explicit
Euler schemes. However, this poses new requirements on the linear system assemblers, which are not yet met by
Bernd Flemisch's avatar
Bernd Flemisch committed
158
the standard assemblers provided in DuMux. This will be extended in future versions.
159
160
161

### Continuous integration

Bernd Flemisch's avatar
Bernd Flemisch committed
162
- A first version of the DuMux GitLab CI is now at the disposal of all developers. While every night a complete
163
164
165
test pipeline is triggered automatically, developers have the possibility to manually start test pipelines
within merge requests that automatically identify and run only those tests affected by the changes introduced.

166

167
Differences Between DuMu<sup>x</sup> 3.3 and DuMu<sup>x</sup> 3.2
Timo Koch's avatar
Timo Koch committed
168
169
170
171
=============================================

### Improvements and Enhancements

Kilian Weishaupt's avatar
Kilian Weishaupt committed
172
173
174
175
176
177
178
- __Requirements__: DuMu<sup>x</sup> now requires Dune >=2.7 and CMake >= 3.13.
- __New way to use material laws__: The usage of laws for pc-Sw and kr-Sw has been completely revised. A caller does not have to pass a `parameters` object to the laws anymore. The `spatialParams` now provide a `fluidMatrixInteraction` function which bundles an arbitrary number of
 different interaction laws such as a pc-Sw and kr-Sw curve and interfacial areas.
 New pre-cached spline laws were added which can help to increase efficiency. The usage of the old interface is deprecated and warnings will be raised. The old interface will be removed after the release of 3.3.
- __New example__: We have added another free-flow example dealing with lid-driven cavity flow.
- __Install script written in Python__: The DuMu<sup>x</sup> install script has been translated to Python to improve portability. The old shell script will be removed after release 3.3.
- __Improved velocity reconstruction__: The velocity reconstruction for immiscible porous-media models has been improved, leading to slightly
Kilian Weishaupt's avatar
Kilian Weishaupt committed
179
  different velocity fields in the vicinity of Neumann boundaries.
Kilian Weishaupt's avatar
Kilian Weishaupt committed
180
- __Python bindings (experimental)__: Basic support for Python bindings has been added. Python bindings are an experimental feature
181
182
  and might undergo unannounced API changes until further notice. This concerns the files in the folders `python` and `dumux/python`. To activate
    - add `-DDUNE_ENABLE_PYTHONBINDINGS=TRUE` and `-DCMAKE_POSITION_INDEPENDENT_CODE=TRUE` to your CMAKE_FLAGS and run dunecontrol
Kilian Weishaupt's avatar
Kilian Weishaupt committed
183
    - run `python3 dune-common/bin/setup-dunepy.py`
Kilian Weishaupt's avatar
Kilian Weishaupt committed
184
    - adapt your PYTHONPATH environment variable as described [here](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/-/tree/master/python)
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
- __Obtain DuMux via pip__: The Dumux source code can now be installed using `pip install dumux`. This works for the Python bindings as well as the C++ source code. Matching Dune modules are also installed. Currently not all dune modules have Python packages available. We recommend trying this new feature in a virtual environment by typing
```sh
python3 -m virtualenv venv
source venv/bin/activate
pip install dumux
```
To test the setup you can use the following Python script
```py
from dune.grid import structuredGrid
from dumux.discretization import GridGeometry

gridView = structuredGrid([0,0],[1,1],[5,5])

gridGeometry = GridGeometry(gridView, discMethod="cctpfa")
gridGeometry.update()

print("The total number of scvs is {}".format(gridGeometry.numScv()))
print("The total number of scvfs is {}".format(gridGeometry.numScvf()))
```
Kilian Weishaupt's avatar
Kilian Weishaupt committed
204
- __fmt-library__: We now include a basic version of the [fmt-library](https://github.com/fmtlib/fmt) which implements `std::format` (coming with C++20) without the need for C++20.
Timo Koch's avatar
Timo Koch committed
205
206
  In order to use this, include `<dumux/io/format.hh>`. `format`, `format_to`, `format_to_n`, `formatted_size` are available in the `Dumux::Fmt` namespace.
  The string formatting is documented [here](https://en.cppreference.com/w/cpp/utility/format/formatter#Standard_format_specification) and follows the Python string formatting rules.
Kilian Weishaupt's avatar
Kilian Weishaupt committed
207
208
  The functions are documented on [cppreference](https://en.cppreference.com/w/cpp/utility/format).
 - __RANS__: The RANS models now include variable densities. Compositional or nonisothermal RANS models could produce slightly different, more accurate, results.
Timo Koch's avatar
Timo Koch committed
209
210

### Immediate interface changes not allowing/requiring a deprecation period:
211
- __Flash/Constraintsolver__: The flashes depending on material laws are immediately required to use new-style material laws (fluidMatrixInteraction interface in spatialparams)
Kilian Weishaupt's avatar
Kilian Weishaupt committed
212
- __Box interface solver__: The box interface solver immediately requires the new material law interface without deprecation period. Use the new class `BoxMaterialInterfaces` and update your spatial params to use the new fluidmatrixinteraction interface to be able to use the box interface solver in version 3.3.
213
- For the "sequential" models, the property `BoundaryTypes` has been simply renamed to `SequentialBoundaryTypes`
214
- __Quadmath__: Dumux::Quad has been removed without deprecation. Use Dune::Float128 instead.
215
216
- Within the RANS group, two additional runtime parameters have been included 'IsFlatWallBounded' and 'WriteFlatWallBoundedFields'.
For both the K-Epsilon and Zero-eq RANS models the 'IsFlatWallBounded' runtime parameter should be set as True,
217
as wall topology is not supported for these models with our geometric constraints. If not set as true, the geometry
218
will be checked before the model is run. If either the runtime parameter or the geometry check indicate non-flat walls,
219
the model will terminate. To add FlatWallBounded specific output to the vtk output, WriteFlatWallBoundedFields can be set as True.
220
- __1d3d coupling__: The kernel coupling manager has been replaced with the one from Koch et al (2020) JCP https://doi.org/10.1016/j.jcp.2020.109370
221
222
- __1d3d coupling__: The average and surface coupling managers has been updated with a slightly more accurate version to compute the stencils and the average operator.
The results might differ a bit when using coarse grids. However, both version are expected to converge to the same result with grid refinement.
223

Timo Koch's avatar
Timo Koch committed
224
225
### Deprecated properties/classes/functions/files, to be removed after 3.3:

226
227
- The property `BoundaryTypes` has been deprecated. The boundary condition type can now be deduced from the problem type using `ProblemTraits`.

Timo Koch's avatar
Timo Koch committed
228
229
### Deleted classes/files, property names, constants/enums:

230
- Everything that has been deprecated before release 3.2 has been removed.
231
- All of the geometry headers previously saved in `dumux/common/geometry` have been relocated to `dumux/geometry`.
Bernd Flemisch's avatar
Bernd Flemisch committed
232
  The headers in `dumux/common/geometry` are deprecated and will be removed after 3.3. The geometry tests have been moved from `test/common/geometry`
Ned Coltman's avatar
Ned Coltman committed
233
  and `test/common/boundingboxtree` to `test/geometry`.
234

235
### Other noteworthy changes:
Bernd Flemisch's avatar
Bernd Flemisch committed
236
- Releases earlier than 3.0 are no longer automatically tested or supported.
Timo Koch's avatar
Timo Koch committed
237

238
Differences Between DuMu<sup>x</sup> 3.2 and DuMu<sup>x</sup> 3.1
Timo Koch's avatar
Timo Koch committed
239
240
241
242
=============================================

### Improvements and Enhancements

243
- __C++17__: DuMu<sup>x</sup> now requires a C++ compiler supporting the C++17 features of GCC 7 (e.g. GCC 7, Clang 5).
244
245
- __Radially symmetric problems__: We now have support for radially symmetric problems (disc, ball, toroid). The support comes in form of wrappers for sub control volumes and faces that overload the respective `volume()` and `area()` function turning a 1d or 2d problem into a 2d or 3d radially symmetric problem.

246
247
- __Improvements of Beavers-Joseph(-Saffman) condition for the free flow model__: The naming for handling BJ(-S) boundary conditions has been adapted from `isBJS()` to `isBeaversJoseph()` / `setBJS()` to `setBeaversJoseph()`. In order to consider the velocity within the porous medium, the old `velocityPorousMedium(element, scvf)` method (returning a Scalar) has been renamed to `porousMediumVelocity(element, scvf)` (returning a velocity vector). The latter defaults to `VelocityVector(0.0)`.

248
249
- __Van Genuchten__: The VanGenuchten-Mualem material law now allows to set a parameter `l` (default to 0.5) which is sometimes fitted.

250
251
- __Runtime variable output precision e.g. Float64__: The VtkOutputModule has been adapted to allow easy changes of the vtk output precision. It is now possible to specify output precision in the input file using `Vtk.Precision` followed by either `Float32`, `Float64`, `UInt32`, `UInt8` or `Int32`. `Float32` stays the default. We especially advice the use of `Float64` when working with restart files.
An additional new option is `Vtk.CoordPrecision` which changes the precision of the coordinates only and uses the default of `Vtk.Precision`.
252
253
254

- __Effective Laws and Diffusion Coefficients__: The effective laws interface has been changed within !1684. The interface for these laws has been unified, and all coefficents are to be stored in containers that fit to the model. These quantities should then be added in the volumeVariables, meaning all effective quantities would be accessible from the volumevariables.

255
256
- __Examples__: The documentation of the examples has been improved further, focusing on readability and convenience. Further, three additional examples are included the folder `examples`. To get an overview, point your browser to https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/tree/master/examples.

257
- __Linear solvers__: There is a new ISTL solver factory backend which allows to choose solvers at runtime (requires dune-istl 2.7) and also enables more parallel solvers (requires dune-istl > 2.7.0).
258
259


Timo Koch's avatar
Timo Koch committed
260
261
### Immediate interface changes not allowing/requiring a deprecation period

Christoph Grüninger's avatar
Christoph Grüninger committed
262
- Remove `Grid.HeapSize` as dune-ugrid removed the according feature as well.
263
- __Van Genuchten__: Corrected VanGenuchten-Mualem exponent in the nonwetting saturation formula (`1/3` instead of `1/2` (or `l`, see above))
264
- __Van Genuchten__: Corrected VanGenuchten-Mualem implementation of `dkrn/dSw`
265
- __Brooks-Corey__: Corrected Brooks-Corey implementation of `dkrn/dSw` and added the derivatives for the regularized version
266
- __AMGBackend__: The internal structure of the AMGBackend and the ParallelISTLHelper has been overhauled, as only used by the AMG, we did not make the changes backwards-compatible
267
268
- The global default parameters for linear solvers have been removed and moved to the class `LinearSolver`.
This only affects users that directly obtain this parameter via `getParam` somewhere in the code.
Christoph Grüninger's avatar
Christoph Grüninger committed
269

Kilian Weishaupt's avatar
Kilian Weishaupt committed
270
271
272
- __Sequential linear solver backends__: Remove template argument `precondBlockLevel` from `solve` functions. The preconditioner block level is now determined automatically, assuming a value of
1 for regular BCRS matrices and a value of 2 for MultiTypeBlock matrices. The respective calls from the `NewtonSolver` and `PDESolver`classes have been adapted.

Kilian Weishaupt's avatar
Kilian Weishaupt committed
273
- __Change matrix block arrangement for staggered models__: The matrix block structure has been adapted such that it complies with the literature standard, i.e., having the velocity block (A) on `M[0][0]`
274
275
276
277
rather than on `M[1][1]`. This also requires re-arranging the submodels and properties in dumux-multidomain such that the face-related classes and vector entries now appear before the cell-centered ones.

```math
M = \begin{pmatrix}
Kilian Weishaupt's avatar
Kilian Weishaupt committed
278
279
  D & C\\
  B & A
280
281
282
283
284
\end{pmatrix}

\qquad => \qquad

M = \begin{pmatrix}
Kilian Weishaupt's avatar
Kilian Weishaupt committed
285
286
    A & B\\
    C & D
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
    \end{pmatrix}
```

Backwards-compatibility can only be provided to a certain extent. The following changes need to made in the main file:

1.) change the order of the arguments for the `assembler` such that it reads:
```c++
auto assembler = std::make_shared<Assembler>(std::make_tuple(ffProblem, ffProblem, otherProblem, ...),
                                             std::make_tuple(ffGridGeometry->faceFVGridGeometryPtr(),
                                                             ffFvGridGeometry->cellCenterFVGridGeometryPtr(),
                                                             otherFvGridGeometry, ...),
                                             std::make_tuple(ffGridVariables->faceGridVariablesPtr(),
                                                             ffGridVariables->cellCenterGridVariablesPtr(),
                                                             otherGridVariables, ...),
                                             couplingManager,
                                             timeLoop, solOld);

// Not changing the arguments will yield a deprecation warning stating this hint but the code still compiles and runs.
```

2.) change the order of arguments in the `partial` function:
```c++
ffSol = partial(sol, ffFaceIdx, ffCellCenterIdx);

// Not changing the argument will rise a compiler error which makes the MR not fully backwards-compatible.
```

314
315
316
Regarding changes made to the effective laws and diffusionCoefficient containters, Backwards-compatibility is maintined for a large extent, barring any volumevariable classes defined externally that inherit from the non-isothermal volumevariables.
If you use a self defined volumevariables class that inherits from the non-isothermal volumevariables, please adapt the your volumevariables class to fit to the non-isothermal volumevariables, and include the new methods for accessing the diffusion and effective diffusion coefficients.

317
318
- Tracer model: tracer fluid systems do no longer provide a `getMainComponent` function since this simply doesn't make sense -- the main bulk component is not modeled.

Timo Koch's avatar
Timo Koch committed
319
### Deprecated properties, to be removed after 3.2:
320
- __GridView__: The property `GridView` has been deprecated and can be accessed via `GridGeometry::GridView` instead.
Timo Koch's avatar
Timo Koch committed
321
322

### Deprecated classes/files, to be removed after 3.2:
323
324
- __AMGBackend__: The class AMGBackend is deprecated and has been replaced by AMGBiCGSTABBackend which gets some different template arguments
- __AMGTraits__: AMGTraits are deprecated, are to be replaced by LinearSolverTraits and restructured internally. As they were only used by the AMGBackend, we did not make the internal changes backwards-compatible
Timo Koch's avatar
Timo Koch committed
325
326

### Deprecated member functions, to be removed after 3.2:
327
328
- __DiffusionCoefficient(various arguments)__: These coefficients are now defined in the volvars and stored in a container fit to the model. To access these values, use the unified ```c++ diffusionCoefficient(int phaseIdx, int compIIdx, int compJIdx) ```
- __EffectiveDiffusivity(various arguments)__: These values are now defined in the volvars and stored in a container fit to the model. To access these values, use the unified ```c++ effectiveDiffusionCoefficient(int phaseIdx, int compIIdx, int compJIdx) ```
Timo Koch's avatar
Timo Koch committed
329
330

### Deleted classes/files, property names, constants/enums
Timo Koch's avatar
Timo Koch committed
331
Everything that has been deprecated before release 3.1 has been removed.
Timo Koch's avatar
Timo Koch committed
332

333
Differences Between DuMu<sup>x</sup> 3.1 and DuMu<sup>x</sup> 3.0
Timo Koch's avatar
Timo Koch committed
334
335
336
337
=============================================

### Improvements and Enhancements

338
- __Examples__: Three extensively documented examples have been added which highlight interesting features and show how to apply DuMu<sup>x</sup> to interesting problems. They can be found in the new folder `examples`. To get an overview, point your browser to https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/tree/master/examples.
339

Katharina Heck's avatar
Katharina Heck committed
340
- __Porousmediumflow__: Added a new porous medium model for the energy balance of a porous solid (general heat equation).
341

342
- __Multidomain__: It is now possible to use the facet coupling module together with the mpfa-o scheme in the bulk domain.
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358

- __Box__: The box scheme works now on grids with prism / wedge elements in 3D.

- __Diffusive fluxes__: We revised the formulation of the diffusion laws to allow for changes between mass-averaged velocity reference systems and molar-averaged velocity reference systems. The standard formulation is now set to mass-averaged velocity reference systems.

- __GridManager__:
    * Supports now reading unstructured grids and data from vtu/vtp files (ASCII, XML format) sequential.
      For UGGrid and FoamGrid you can specify a grid in such a format in the input file:
      `Grid.File = mygrid.vtu` / `Grid.File = mygrid.vtp`. The associated data is then available in the grid data object.
    * Instead of always including all grid manager specializations you can now only include the specialization that you need.
      For example, if you only use YaspGrid in your code, you only need to include `dumux/io/grid/gridmanager_yasp.hh`. The
      convenience header `dumux/io/grid/gridmanager.hh` still includes all specializations.
    * Added a `NetPBMReader` which allows to read simple raster images files (`*.pbm` and `*.pgm`). Can be used, e.g., with
      `dune-subgrid` in order to create a grid from an image file.

- __Freeflow__: A second order approximation of the convective term of all Navier-Stokes based models is now available.
Roman Winter's avatar
Roman Winter committed
359
  This can be enabled using the property `UpwindSchemeOrder`. This property defaults to a first order upwinding approximation,
360
  which is the method used for all models in release 3.0. If this property is set to `2`, a second order flux limiter method will be used.
361
362
363
364
  Various flux limiter functions have been implemented to maintain the monotonicity of this discretization. Per default the
  `Minmod` flux limiter is used, but `Vanleer`, `Vanalbada`, `Superbee`, `Umist`, `Mclimiter`, and `Wahyd` based flux limiters
  are also available. These can be specified using the input file entry `Flux.DifferencingScheme`. These methods are also
  implemented for non-uniform structured grids (e.g. YaspGrid - TensorProductCoordinates). Per default, a scheme assuming a
Ned Coltman's avatar
Ned Coltman committed
365
  uniform grid is used, but two other methods, `Li` and `Hou`, are both available for adaptations to non-uniform grids.
366
  These can be specified using the input file entry `Flux.TVDApproach`.
367

Ned Coltman's avatar
Ned Coltman committed
368
- __RANS__: The called RANS model, defined in the properties system, will specify, via the model traits,
369
370
371
  which RANS problem implementation should be used. In each problem file, the initial and boundary conditions can be
  set using templated functions based on the model type. Examples of these functions exist in the RANS based tests.
  No further preprocessor macros are required.
372
373
374
375
376
377

- __ShallowWater__: Thanks to Leopold Stadler we now have a shallow water equations solver / model. Have a look at freeflow/shallowwater and give it a try with the dam break test at test/freeflow/shallowwater. The are also some friction laws computing shear stresses (Manning, Nikuradse) to account for friction in a channel/river bed, thanks to Martin Utz.

- __Staggered__: Added a `StaggeredNewtonConvergenceWriter` for the staggered grid discretization scheme.

- __Solver__: There is a new abstract base class `PDESolver` that is a class that does linearize & assemble, solve and update.
Roman Winter's avatar
Roman Winter committed
378
  The NewtonSolver now derives from this class (interface is unchanged). A new class `LinearPDESolver` simplifies solving linear problems
379
  by reducing the code in the main file and streamlining the terminal output to look like the Newton output.
Katharina Heck's avatar
Katharina Heck committed
380

381

Timo Koch's avatar
Timo Koch committed
382
383
### Immediate interface changes not allowing/requiring a deprecation period

Roman Winter's avatar
Roman Winter committed
384
385
- `NewtonConvergenceWriter`'s first template argument has changed from `GridView` to `FVGridGeometry`. This allows to call the `resize()` method after a grid change without any arguments.
  Here is an example how to instatiate the convergence writer:
386
387
388
389
  ```
  using NewtonConvergenceWriter = Dumux::NewtonConvergenceWriter<FVGridGeometry, SolutionVector>;
  auto convergenceWriter = std::make_shared<NewtonConvergenceWriter>(*fvGridGeometry);
  ```
390

391
392
393
394
- 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.
395

Katharina Heck's avatar
Katharina Heck committed
396
397
- __RANS__: The base problems for all turbulence models e.g. `ZeroEqProblem` have been been renamed to one generic `RANSProblem`

398
399
400
401
402
403
404
405
### Deprecated properties, to be removed after 3.1:

- `FVGridGeometry` and `EnableFVGridGeometryCache` have been replaced by
  `GridGeometry` and `EnableGridGeometryCache`.

Unfortunately, clang doesn't emit deprecation warnings if an old property name is
used. Consider employing gcc for detecting occurrences of the old name.

Timo Koch's avatar
Timo Koch committed
406
407
### Deprecated classes/files, to be removed after 3.1:

408
409
410
411
412
413
- `BaseFVGridGeometry` from `dumux/discretization`. Use `BaseGridGeometry` instead.

- `CakeGridCreator` and `SubgridGridCreator` from `dumux/io/grid`. Use the corresponding `...Manager` instead.

- `IntRange` from `dumux/common`. Use `Dune::IntegralRange` instead.

Timo Koch's avatar
Timo Koch committed
414
415
### Deprecated member functions, to be removed after 3.1:

416
417
418
419
- 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()`.

Timo Koch's avatar
Timo Koch committed
420
421
### Deleted classes/files, property names, constants/enums

422
423
- Deprecated classes and files for the 3.0 release listed below stay deprecated
  for at least one more release cycle.
Timo Koch's avatar
Timo Koch committed
424

425
Differences Between DuMu<sup>x</sup> 2.12 and DuMu<sup>x</sup> 3.0
426
427
=============================================

Bernd Flemisch's avatar
Bernd Flemisch committed
428
429
## Important Notes

430
431
- DuMu<sup>x</sup> 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 DuMu<sup>x</sup> 2-series, always backward compatible
432
433
      to at least the last minor version update.

Bernd Flemisch's avatar
Bernd Flemisch committed
434
435
- 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.
436
  We recommend new users and also users experienced with DuMu<sup>x</sup> 2.X to clone
Bernd Flemisch's avatar
Bernd Flemisch committed
437
438
  the course and have a look at the exercises in there.

439
- DuMu<sup>x</sup> 3.0 is based on Dune 2.6 and is expected to run with the current Dune master.
Bernd Flemisch's avatar
Bernd Flemisch committed
440
441
442
  We will try to keep the compatibility with the Dune master
  as long as it is technically feasible and our resources allow it.

443
- DuMu<sup>x</sup> 3.0 requires at least GCC 4.9 or Clang 3.5 in their C++-14 mode.
Bernd Flemisch's avatar
Bernd Flemisch committed
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
  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.
478
479
- __TypeTag templates:__ Implementers of code in DuMu<sup>x</sup> 3.0 are advised to avoid TypeTag as a template argument for class templates.
  Many classes in the DuMu<sup>x</sup> core have been changed to have a small number of specific template arguments, including `GridGeometry`,
Bernd Flemisch's avatar
Bernd Flemisch committed
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
  `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

501
502
- __MPFA schemes:__ The new design of the DuMu<sup>x</sup> 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 DuMu<sup>x</sup> model and
Bernd Flemisch's avatar
Bernd Flemisch committed
503
  also works on surface grids. More schemes will be added in the future.
504
- __Box-dfm:__ The `2pdfm` model from version 2.12 has been generalized such that it can be used on any DuMu<sup>x</sup> model and in both two and three dimensions.
Bernd Flemisch's avatar
Bernd Flemisch committed
505
506
507
508
509
510
- __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.
511
- __Solid systems:__ DuMu<sup>x</sup> 3.0 introduces solid systems similar to fluid systems but for solid components. This allows a consistent
Bernd Flemisch's avatar
Bernd Flemisch committed
512
513
  implementation of mineralization models including reactions, dissolution, precipitation and other processes altering the solid
  phase of the porous medium.
514
- __Multidomain:__ DuMu<sup>x</sup> 3.0 introduces a new multidomain framework which does no longer depend on `dune-multidomain` and can be used for the coupling
Bernd Flemisch's avatar
Bernd Flemisch committed
515
  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
516
  dimensionalities. The implementation is such that any of the existing DuMu<sup>x</sup> models can be used in the subdomains, while the data and functionality
Bernd Flemisch's avatar
Bernd Flemisch committed
517
518
519
520
521
522
523
  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.
524
  The free-flow models in DuMu<sup>x</sup> 3.0 consider single phase flow with or without component/energy transport. So far, only regular Cartesian grids are supported
Bernd Flemisch's avatar
Bernd Flemisch committed
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
  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.

## Deprecated classes/files, to be removed after 3.0
- All classes of the sequential models are deprecated. The sequential models will be ported to the new structure
  of porous medium models (formerly called implicit models). This way sequential and implicit model implementations
  no longer differ and use the same numerical infrastructure.
- The `TimeManager` class is to be replaced by the class `TimeLoop`.
- The `VtkMultiWriter` class is to be replaced by the class `VtkOutputModule`.
- The file `start.hh` is replaced by new style main files.

556
## Deleted classes/files/functions... which have been deprecated in DuMu<sup>x</sup> 2.12
Bernd Flemisch's avatar
Bernd Flemisch committed
557
- Everything listed as deprecated below has been removed.
558
559


560
Differences Between DuMu<sup>x</sup> 2.11 and DuMu<sup>x</sup> 2.12
561
562
563
=============================================

* IMPORTANT NOTES:
564
    - DuMu<sup>x</sup> 2.12 is expected to run based on Dune 2.4.1, 2.5, 2.6 and the Dune
565
566
      master. We will try to keep the compatibility with the Dune master
      as long as it is technically feasible and our resources allow it. If
567
      you want to use DuMu<sup>x</sup> multidomain models, you have to stick with the
568
      Dune 2.4 core and specific versions of other modules, see
569
570
      [test/multidomain/README](test/multidomain/README) for details.
      Also the geomechanics models require Dune 2.4 and PDELab 2.0.
571

572
    - DuMu<sup>x</sup> 2.12 requires at least GCC 4.9 or Clang 3.5 in their C++-14 mode.
573
574

    - For employing corner-point grids by means of opm-grid (former
575
      dune-cornerpoint), the OPM releases 2017.04 or 2017.10 have to be used.
576
577

* IMPROVEMENTS and ENHANCEMENTS:
578
579
580
581
582
583
584
585
    - Four new tutorial exercises have been added in the folder
      [tutorial](tutorial). They can be built by executing
      `make build_tutorials` in the build folder. Each exercise
      comes with detailed instructions:
        1. [Exercise 1](tutorial/ex1/README.md)
        2. [Exercise 2](tutorial/ex2/README.md)
        3. [Exercise 3](tutorial/ex3/README.md)
        4. [Exercise 4](tutorial/ex4/README.md)
586

587
588
589
590
591
592
    - Fixed bug in heatCapacity() of component air and replace
      the use of a constant value in  gasEnthalpy() by calling
      heatCapacity().

    - The GnuplotInterface now supports in-simulation generation of image
      files (*.png).
593

594
595
    - A paraview python script for exporting 2d pictures from *.vtu files
      has been added.
596

597
598
    - A class for estimating turbulence properties has been added with
      turbulenceproperties.hh.
599

600
601
602
603
* IMMEDIATE INTERFACE CHANGES not allowing/requiring a deprecation period:
    - gnuplotinterface.hh: The add...ToPlot() functions have changed signature,
      the curve name/title is not mandatory anymore and can be specified together
      with the curve options.
604
605

* DELETED classes/files, property names, constants/enums,
606
  member functions, which have been deprecated in DuMu<sup>x</sup> 2.11:
607
608
609
    - Everything listed as deprecated below has been removed.


610
Differences Between DuMu<sup>x</sup> 2.10 and DuMu<sup>x</sup> 2.11
Christoph Grüninger's avatar
Christoph Grüninger committed
611
612
613
=============================================

* IMPORTANT NOTES:
614
    - DuMu<sup>x</sup> 2.11 is expected to run based on Dune 2.4.1, 2.5 and the Dune
Christoph Grüninger's avatar
Christoph Grüninger committed
615
616
      master. We will try to keep the compatibility with the Dune master
      as long as it is technically feasible and our resources allow it. If
617
      you want to use DuMu<sup>x</sup> multidomain models, you have to stick with the
Christoph Grüninger's avatar
Christoph Grüninger committed
618
619
620
      Dune 2.4 core and specific versions of other modules, see
      `test/multidomain/README` for details.

621
    - DuMu<sup>x</sup> 2.11 requires at least GCC 4.9 or Clang 3.5 in their C++-14 mode.
Christoph Grüninger's avatar
Christoph Grüninger committed
622
623
624
625
626
627
628

    - For employing corner-point grids by means of opm-grid (former
      dune-cornerpoint), the OPM release 2016.04 has to be used.

* IMPROVEMENTS and ENHANCEMENTS:

* IMMEDIATE INTERFACE CHANGES not allowing/requiring a deprecation period:
629
630
631
632
    - A gridcreator for piece-of-cake-type grids has been added. It is capable
      of creating meshes with gradually in- and decreasing distances between nodes.
      It also allows the creation of a 360° cake where the last elements are
      connected to the first elements.
633
634
635
636
    - shouldWriteRestartFile() is now, as shouldWriteOutput() already was,
      called before the time level is advanced. So it might be necessary to use
      ...WillBeFinished instead of ...IsFinished for writing restart files at
      the correct time.
637
638
639
    - In the ZeroEq models, the properties BBoxMinIsWall and BBoxMaxIsWall have
      been replaced by the functions bBoxMaxIsWall() and bBoxMaxIsWall() in the
      problem file.
640
641
642
643
644
645
    - In the TwoPNC (and, consequently the TwoPNCMin) models, the old formulations
      pgSl, plSg as well as pnSw and pwSg have been replaced by the pnsw and pwsn,
      to satify the naming convention and be consistent with TwoPTwoC.
    - In the TwoPTwoC model, the indices are no longer dependent on the
      formulation. Further, the values of "nPhaseOnly" and "bothPhases"
      have been harmonized with those in TwoPNC
Christoph Grüninger's avatar
Christoph Grüninger committed
646
647
648
649
650
651
652
653
654
655
656

* Deprecated PROPERTY and PARAMETER NAMES, to be removed after 2.11: BEWARE: The
  compiler will not print any warning if a deprecated property or parameter name
  is used. If possible, a run-time warning will appear in the summary lines
  after the corresponding run.

* Deprecated CLASSES/FILES, to be removed after 2.11:

* Deprecated MEMBER FUNCTIONS, to be removed after 2.11:

* DELETED classes/files, property names, constants/enums,
657
  member functions, which have been deprecated in DuMu<sup>x</sup> 2.10:
Christoph Grüninger's avatar
Christoph Grüninger committed
658
659
660
    - Everything listed as deprecated below has been removed.


661
Differences Between DuMu<sup>x</sup> 2.9 and DuMu<sup>x</sup> 2.10
662
663
664
===================================================

* IMPORTANT NOTES:
665
    - DuMu<sup>x</sup> 2.10 is expected to run based on Dune 2.4.1, 2.5 and the Dune
666
667
      master. We will try to keep the compatibility with the Dune master
      as long as it is technically feasible and our resources allow it. If
668
      you want to use DuMu<sup>x</sup> multidomain models, you have to stick with the
669
670
      Dune 2.4 core and specific versions of other modules, see
      `test/multidomain/README` for details.
671

672
    - DuMu<sup>x</sup> 2.10 requires at least GCC 4.9 or Clang 3.5 in their C++-14 mode.
673

674
675
676
    - For employing corner-point grids by means of opm-grid (former
      dune-cornerpoint), the OPM release 2016.04 has to be used.

677
* IMPROVEMENTS and ENHANCEMENTS:
678
679
680
681
682
683
684
685
686
687
688
    - Two new fully-implicit models have been added: `ThreePWaterOil` and
      `TwoPOneC`. The first one admits two components water and oil that may be
      present in two liquid and one gaseous phase, see `test_box3pwateroil` in
      `test/porousmediumflow/3pwateroil/implicit` for details. The second one is
      dedicated to one generic component that may be present in liquid and
      gaseous state, see `test_boxsteaminjection` in
      `test/porousmediumflow/2p1c/implicit` for an example.

    - Numbering of the VTK files starts with `0` now.

    - Using the geostatistical tool gstat for generating random fields has been
689
690
      facilitated. See `test_cc1pwithgstat` in `test/porousmediumflow/1p/implicit`.
      This tool can be installed using the `bin/installexternal.sh` script.
691
692
      If cmake does not find gstat, one has to specify the GSTAT_ROOT variable,
      see the standard optim.opts or debug.opts.
Christoph Grüninger's avatar
Christoph Grüninger committed
693

694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
    - The multidomain models should now run with all compilers without
      segfaults, both with optimization and debug options.

    - Computation for two-dimensional fracture networks in three-dimensional
      space has been fixed and is tested now in
      `test/porousmediumflow/2p/implicit/test_fracture_box2p`.

    - The `bin` folder containing various helper scripts has been restructured.
      For example, the scripts `fuzzycompare.py` and `runtest.py` are now
      contained in the subfolder `testing`.

    - Two new scripts `extractlinedata.py` and `extractpointdataovertime.py`
      have been added to `bin/postprocessing`. They realize what their names
      suggest.

    - The computation of the tortuosity tau with the Millington-Quirk model has
      been optimized. Tests show a speedup of up to 5% for a 2p2c simulation.

    - The fully-implicit box scheme now fully supports prism-shaped elements.

    - Convenience functions for reading values from a file to a container and
      for writing values to a file from a container have been added, see
      `test_container_io` in `test/io/container`.
717
718

* IMMEDIATE INTERFACE CHANGES not allowing/requiring a deprecation period:
719
720
    - The problem class interface needs to provide the method maxTimeStepSize().
      This is important if you implement problem classes not deriving from the base
721
      problem classes in DuMu<sup>x</sup> (`ImplicitProblem`, `OneModelProblem`,
722
      `ImpetProblem`, and `MultidomainProblem`).
723
724
725
726
    - All name-related methods that previously returned / received `const char*`
      do now use the type-safe alternative `std::string`. An example is
      `FluidSystem::componentName()`. If you need a
      `const char*` for special operation use the string member `c_str()`.
727
728
729

* Deprecated PROPERTY and PARAMETER NAMES, to be removed after 2.10: BEWARE: The
  compiler will not print any warning if a deprecated property or parameter name
730
731
732
733
734
  is used. If possible, a run-time warning will appear in the summary lines
  after the corresponding run.
    - The pure run-time parameter `tau` has been renamed to the property and
      run-time parameter `TauTortuosity`. For the models 1p2c, 2p2c, 3p3c it got
      the default value 0.5.
735
736

* Deprecated CLASSES/FILES, to be removed after 2.10:
737
738
739
    - The class `DiffusivityConstantTau<TypeTag, Scalar>` was renamed to
      `DiffusivityConstant<TypeTag>` and is located in a according new header. The
      old class, its header and the property `tau` are deprecated.
740

741
742
743
744
745
746
    - `PointSourceHelper<TypeTag>` has been deprecated. Use
      `BoundingBoxTreePointSourceHelper<TypeTag>` instead.

    - The classes `Dumux::Liquid/GasPhase<Scalar, Component>` have been moved to
      the namespace `Dumux::FluidSystems`.

747
* Deprecated MEMBER FUNCTIONS, to be removed after 2.10:
748
749
    - `checkEffectiveSaturation` of the classes `PlotMaterialLaw<TypeTag>` in
      `dumux/io`.
750

751
752
    - `concentrationGrad` of the class `TwoPNCFluxVariables<TypeTag>`. Use
      `moleFractionGrad` instead, with the obviously different physical meaning.
753
754

* DELETED classes/files, property names, constants/enums,
755
  member functions, which have been deprecated in DuMu<sup>x</sup> 2.9:
756
757
758
    - Everything listed as deprecated below has been removed.


759
Differences Between DuMu<sup>x</sup> 2.8 and DuMu<sup>x</sup> 2.9
760
761
762
===================================================

* IMPORTANT NOTES:
763
    - DuMu<sup>x</sup> 2.9 is expected to run based on either Dune 2.4 or Dune 3.0. We will
Bernd Flemisch's avatar
Bernd Flemisch committed
764
      try to keep the compatibility with Dune 3.0 as long as it is technically
765
      feasible and our resources allow it. If you want to use DuMu<sup>x</sup> multidomain
Bernd Flemisch's avatar
Bernd Flemisch committed
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
      models, you have to stick with the Dune 2.4 core and specific versions of
      other modules, see `test/multidomain/README` for details.

    - The ALUGrid stand-alone library cannot be used any longer. Use the module
      [dune-alugrid](https://gitlab.dune-project.org/extensions/dune-alugrid)
      instead. Both the `releases/2.4` branch and the `master` should work.

    - The above is not true if you like to run a sequential MPFA model on an
      `ALUGrid`. Then, you currently have to use the `master-old` branch of
      dune-alugrid. We will try to fix this as soon as possible. Alternatively,
      `UGGrid` or `YaspGrid` can be chosen as grid managers.

    - Instead of using AlbertaGrid for the tests where dim < dimWorld, we now
      employ
      [dune-foamgrid](https://gitlab.dune-project.org/extensions/dune-foamgrid).
      Dune-foamgrid provides 1d and 2d simplex grids embedded in an arbitrary
      dimension world space. It features element parametrizations, runtime growth,
      runtime-movable vertices. You might still use AlbertaGrid, but it is not
      supported by our GridCreator.

    - If you like/have to use corner-point grids by means of the module
      dune-cornerpoint, you have to use (and partially patch) the 2015.10 release
      of [OPM](http://opm-project.org/?page_id=36). See `patches/README` for
      details.
790
791

* IMPROVEMENTS and ENHANCEMENTS:
Bernd Flemisch's avatar
Bernd Flemisch committed
792
793
794
795
796
    - The folder structure has been changed according to
      [FS#250](http://www.dumux.org/flyspray/index.php?do=details&task_id=250).
      This has been a rather massive change affecting more than 1000 files. Close
      to 400 files have been moved and/or renamed.
      We made everything backwards-compatible, the worst thing that should happen
797
      after switching to DuMu<sup>x</sup> 2.9, will be some warnings when including headers
Bernd Flemisch's avatar
Bernd Flemisch committed
798
799
800
801
802
803
804
805
806
807
      from old destinations/names. You can fix the include statements and get rid
      of the warnings by applying the bash script `bin/fix_includes.sh` to your
      source files, for example by executing
      ```
      bash ../dumux/bin/fix_includes.sh file1 [file2 ...]
      ```
      or
      ```
      find . -name '*.[ch][ch]' -exec bash ../dumux/bin/fix_includes.sh {} \;
      ```
808
      inside the folder that contains your files.
809
810
811
812
      A patch is available to remove deprecated header files:
      ```
      patch -p1 < patches/dumux-2.9-no-deprecated-headers.patch
      ```
Bernd Flemisch's avatar
Bernd Flemisch committed
813
      The benefits are hopefully:
814
        + A clearer structure in terms of the problems that you want to apply DuMu<sup>x</sup>
Bernd Flemisch's avatar
Bernd Flemisch committed
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
          for. Three main application areas on the top level: `porousmediumflow`,
          `freeflow` and `geomechanics`. The different numerical treatments "fully
          implicit" or "sequential" appear as discretization detail after the
          choice of the physical model. That's of course currently rather wishful
          thinking, but nevertheless where we are headed. The folder `implicit` on
          the top level now only contains physics-agnostic classes that can be used
          by any class of an application area.  Please note the change from
          "decoupled" to "sequential" according to the related task
          [FS#252](http://www.dumux.org/flyspray/index.php?do=details&task_id=252).

        + Nicer include statements due to relaxation of the naming conventions for
          the header files. Compare the old
          ```
          #include <dumux/multidomain/2cnistokes2p2cni/2cnistokes2p2cnilocaloperator.hh>
          ```
          with the new
          ```
832
          #include <dumux/multidomain/2cnistokes2p2cni/localoperator.hh>
Bernd Flemisch's avatar
Bernd Flemisch committed
833
834
835
836
837
838
839
840
841
842
843
          ```
      The structure change is reflected in the `test` folder:
        + The tests from`test/implicit/particular_model` have been moved to
          `test/porousmediumflow/particular_model/implicit`. For example,
          `test/implicit/2p` has been moved to `test/porousmediumflow/2p/implicit`.

        + Analogously, the tests from `test/decoupled/particular_model` have been
          moved to `test/porousmediumflow/particular_model/sequential`.

        + The subfolders `decoupled` and `implicit` of `test` have been removed.

844
        + If you have cloned the DuMu<sup>x</sup> Git repository and have local changes in the
Bernd Flemisch's avatar
Bernd Flemisch committed
845
846
847
848
849
850
851
          folders `test/implicit` or `test/decoupled`, you can expect merge
          conflicts for your next `git pull`. You can either deal with these
          conflicts directly or create a patch, remove the local changes, pull, and
          apply the patch afterwards with some care to respect the changed
          structure.

    - A two-phase multiple-interacting-continua (MINC) model has been added to
852
      the DuMu<sup>x</sup> model portfolio. See `test/porousmediumflow/2pminc/implicit` for
Bernd Flemisch's avatar
Bernd Flemisch committed
853
854
855
856
857
858
859
      details.

    - The multidomain models have been restructured. Duplicated code has been
      reduced; isothermal and non-isothermal models are treated in a more
      consistent manner.

    - It is now possible to specify point sources for implicit models. A point
860
      source is a source term specified at any point location in e.g. kg/s. DuMu<sup>x</sup>
Bernd Flemisch's avatar
Bernd Flemisch committed
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
      will compute the correct control volume the source belongs to for you. Point
      sources can be e.g. solution and/or time-dependent. See tests
      (1p/implicit/pointsources, 2p/implicit/pointsources) for examples.

    - All tests use our standard `GridCreator` now. If it is possible to specify
      the grid entirely in the input-file, the corresponding DGF files have been
      deleted. In particular, a YaspGrid tensor grid can now also be specified via
      the input file only.

    - Several sections on our fluid/material framework have been moved from the
      handbook to the Doxygen documentation.

    - The three-phase constitutive relations from
      `material/fluidmatrixinteractions` have been reworked to be consistent with
      their two-phase analogues. In particular, an `EffToAbsLaw` and
      regularization classes have been implemented.

    - In case of a simulation stop due to too many timestep subdivisions, restart
      files of both the current and the old solution are automatically generated.
880

881
* IMMEDIATE INTERFACE CHANGES not allowing/requiring a deprecation period:
Bernd Flemisch's avatar
Bernd Flemisch committed
882
883
884
885
    - All flux variables are now default-constructible. While the non-trivial
      constructors are deprecated, model implementers might be required to make
      their flux variables default-constructible too. In particular, this affects
      you if you develop your own flux variables that
886
        + inherit from flux variables from dumux-stable, such as the
Bernd Flemisch's avatar
Bernd Flemisch committed
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
          `ImplicitDaryFluxVariables`,
        + and/or are used in a local residual from dumux-stable.
      See the
      [mailing list](https://listserv.uni-stuttgart.de/pipermail/dumux/2016q1/001551.html)
      for details.

    - For the multidomain models, the notation of the boundary condition types
      has changed. This is especially important for all momentum boundary
      conditions. In general:
        + `couplingInflow`  -> `couplingNeumann`
        + `couplingOutflow` -> `couplingDirichlet`
    - But for the momentum balances:
        + `couplingInflow`  -> `couplingDirichlet`
        + `couplingOutflow` -> `couplingNeumann`

    - Due to the change in the three-phase fluid-matrix-interactions, you might
      have to adjust your spatial parameters. You should get a compiler warning
      message that gives you more details.

    - The TypeTags `ImplicitModel` and `ExplicitModel` have been deleted. They
      haven't been used apart from one internal inheritance. See FS#304 for
      details.
909

Timo Koch's avatar
Timo Koch committed
910
* Deprecated PROPERTY and PARAMETER NAMES, to be removed after 2.9: BEWARE: The
911
912
913
  compiler will not print any warning if a deprecated property or parameter name
  is used. However, a run-time warning should appear in the summary lines after
  the corresponding run.
Bernd Flemisch's avatar
Bernd Flemisch committed
914
915
916
917
918
919
    - The word `Decoupled` in the TypeTags has been replaced by `Sequential`:
        + `DecoupledModel` -> `SequentialModel`
        + `DecoupledOneP` -> `SequentialOneP`
        + `DecoupledTwoP` -> `SequentialTwoP`
        + `DecoupledTwoPTwoC` -> `SequentialTwoPTwoC`
        + `DecoupledTwoPTwoCAdaptive` -> `SequentialTwoPTwoCAdaptive`
920

921

Timo Koch's avatar
Timo Koch committed
922
* Deprecated CLASSES/FILES, to be removed after 2.9:
Bernd Flemisch's avatar
Bernd Flemisch committed
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
    - Self-written parallel linear solvers and corresponding infrastructure,
      according to
      [FS#293](http://www.dumux.org/flyspray/index.php?do=details&task_id=293).
      For parallel runs, use the `AMGBackend` instead. For sequential runs,
      direct replacements are:
        + `BoxBiCGStabILU0Solver` -> `ILU0BiCGSTABBackend`
        + `BoxBiCGStabSORSolver` -> `SORBiCGSTABBackend`
        + `BoxBiCGStabSSORSolver` -> `SSORBiCGSTABBackend`
        + `BoxBiCGStabJacSolver` -> `JacBiCGSTABBackend`
        + `BoxBiCGStabGSSolver` -> `GSBiCGSTABBackend`
        + `BoxCGILU0Solver` -> `ILUnCGBackend`
        + `BoxCGSORSolver` -> `SORCGBackend`
        + `BoxCGSSORSolver` -> `SSORCGBackend`
        + `BoxCGJacSolver` -> `JacCGBackend`
        + `BoxCGGSSolver` -> `GSCGBackend`
        + `IMPETBiCGStabILU0Solver` -> `ILU0BiCGSTABBackend`

    - `CubeGridCreator`, functionality available in default `GridCreator`

    - `SimplexGridCreator`, functionality available in default `GridCreator`

    - `DgfGridCreator`, functionality available in default `GridCreator` (since 2.8)

    - `Decoupled...Indices` -> `Sequential...Indices` (BEWARE: maybe no compiler
    warnings)
948

Timo Koch's avatar
Timo Koch committed
949
* Deprecated MEMBER FUNCTIONS, to be removed after 2.9:
950

Timo Koch's avatar
Timo Koch committed
951
* Deprecated protected MEMBER VARIABLES, to be removed after 2.9: BEWARE: Older
952
953
954
955
  compilers will not print any warning if a deprecated protected member variable
  is used.

* DELETED classes/files, property names, constants/enums,
956
  member functions, which have been deprecated in DuMu<sup>x</sup> 2.8:
Bernd Flemisch's avatar
Bernd Flemisch committed
957
958
    - Everything listed as deprecated below has been removed.

959

960
Differences Between DuMu<sup>x</sup> 2.7 and DuMu<sup>x</sup> 2.8
Thomas Fetzer's avatar
Thomas Fetzer committed
961
962
963
===================================================

* IMPORTANT NOTES:
964
  - DuMu<sup>x</sup> 2.8 is expected to run based on either Dune 2.3 or Dune 2.4. However,
Bernd Flemisch's avatar
Bernd Flemisch committed
965
966
967
968
969
    no attempt has been made to fix the warnings arising from the deprecation of
    EntityPointer in Dune 2.4. This will be made during the next release cycle.
    Moreover, using the multidomain models based on Dune 2.4 is currently only
    possible by patching dune-multidomaingrid. See test/multidomain/README for
    details.
Thomas Fetzer's avatar
Thomas Fetzer committed
970

971
972
973
* DELETED BUILD SYSTEM: The Autotools based build system was removed, use the
  CMake based build system as it is default since Dune 2.4.

Thomas Fetzer's avatar
Thomas Fetzer committed
974
* IMPROVEMENTS and ENHANCEMENTS:
Bernd Flemisch's avatar
Bernd Flemisch committed
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
  - New fully-implicit porous-media models for two fluid phases that may consist
    of an arbitrary number of components have been added. The basic one is
    associated with the property TwoPNC, see test/implicit/2pnc. A more advanced
    one that incorporates solid-fluid phase changes is indicated by TwoPNCMin,
    see test/implicit/2pncmin.

  - The implicit cell-centered models now can use adaptive grid refinement. To
    make a test problem adaptive, just set the property AdaptiveGrid to true and
    choose corresponding indicators via AdaptionInitializationIndicator and
    AdaptionIndicator, see test/implicit/2p/lensproblem.hh for an example. So
    far, indicators are only provided for the TwoPModel. Indicators for other
    models will be provided in the future, as well as parallelization and box
    discretization.

  - With the CpGridCreator, a grid creator has been introduced that reads from a
    Petrel output / Eclipse input file and generates a CpGrid that is offered by
    the OPM module dune-cornerpoint. The fully-implicit cell-centered models are
    now able to deal with cornerpoint grids. See
    test/implicit/2p/test_cc2pcornerpoint for a test of the functionality. A
    realistic corner-point grid will be provided in dumux-lecture soon. The OPM
    modules need to be patched to be compatible with Dune's CMake based build
    system, see patches/README for details.

Thomas Fetzer's avatar
[docu]    
Thomas Fetzer committed
998
  - Zero equation turbulence models (zeroeq) have been added as new models
Bernd Flemisch's avatar
Bernd Flemisch committed
999
1000
    to the freeflow folder. Tests for coupling a turbulent free flow using
    zeroeq turbulence models with flow in a porous medium have been added.